Implement TPS visual cue rendering across editor and teleprompter

Author: KSemenenko

AGENTS.md

@@ -310,6 +310,7 @@ Repo-specific design rules:
 - Prefer deleting JS files entirely when they only hold product UI behavior or duplicated constants; JS modules may exist only as thin bridges to browser APIs or external JS SDKs, with the owning workflow and state kept in C#/Blazor.
 - TPS front matter pasted or imported into the editor source MUST be parsed into the metadata rail automatically and removed from the visible body text instead of staying inline in the source editor.
 - TPS support MUST fully implement the current `design/TPS.md` contract end to end; legacy or partially compatible TPS syntax is not a supported mode, and any old incompatible behavior should be removed instead of kept behind compatibility shims.
+- TPS visual semantics MUST track the current TPS spec end to end: editor and reader surfaces should communicate delivery cues such as volume, emphasis, stress, speed, and delivery mode through typography, spacing, weight, and motion where appropriate, not through color alone.
 - For standalone cloud-storage integrations, persist provider keys, tokens, and connection metadata in browser `localStorage`; do not introduce server-side secret storage for runtime auth in this app shape.
 - Third-party runtime JavaScript SDKs MUST be sourced only from explicitly pinned GitHub Release tags and assets, copied into the repo, bundled locally with their runtime dependencies, and never loaded from CDNs, package registries, `latest` endpoints, or ad-hoc remote downloads at app runtime.
 - Repo-owned manifests, scripts, workflows, and project files that track third-party runtime JavaScript SDKs MUST point to concrete GitHub release versions and asset URLs, never floating references.

src/PrompterOne.Shared/Contracts/TpsVisualCueContracts.cs

@@ -0,0 +1,21 @@
+namespace PrompterOne.Shared.Contracts;
+
+public static class TpsVisualCueContracts
+{
+    public const string CueOpacityVariableName = "--tps-cue-opacity";
+    public const string CueScaleVariableName = "--tps-cue-scale";
+    public const string CueWeightVariableName = "--tps-cue-weight";
+    public const string DeliveryAttributeName = "data-tps-delivery";
+    public const string DeliveryModeBuilding = "building";
+    public const string SpeedAttributeName = "data-tps-speed";
+    public const string SpeedCueFast = "fast";
+    public const string SpeedCueSlow = "slow";
+    public const string SpeedCueXfast = "xfast";
+    public const string SpeedCueXslow = "xslow";
+    public const string StressAttributeName = "data-tps-stress";
+    public const string StressAttributeValue = "true";
+    public const string VolumeAttributeName = "data-tps-volume";
+    public const string VolumeLoud = "loud";
+    public const string VolumeSoft = "soft";
+    public const string VolumeWhisper = "whisper";
+}

src/PrompterOne.Shared/Editor/Components/EditorSourcePanel.razor.cs

@@ -4,6 +4,7 @@
 using Microsoft.Extensions.Logging.Abstractions;
 using Microsoft.JSInterop;
 using PrompterOne.Core.Models.Editor;
+using PrompterOne.Shared.Contracts;
 
 namespace PrompterOne.Shared.Components.Editor;
 
@@ -30,6 +31,14 @@ public partial class EditorSourcePanel
     private bool _syncScrollAfterRender = true;
     private bool _visibleCanRedo;
     private bool _visibleCanUndo;
+    private static readonly object SourceCueContracts = new
+    {
+        volumeAttributeName = TpsVisualCueContracts.VolumeAttributeName,
+        deliveryAttributeName = TpsVisualCueContracts.DeliveryAttributeName,
+        speedAttributeName = TpsVisualCueContracts.SpeedAttributeName,
+        stressAttributeName = TpsVisualCueContracts.StressAttributeName,
+        stressAttributeValue = TpsVisualCueContracts.StressAttributeValue
+    };
 
     [Parameter] public bool CanRedo { get; set; }
 
@@ -237,7 +246,7 @@ private async Task EnsureSurfaceInteropReadyAsync()
         }
 
         _surfaceInteropReady = await RunInitializationInteropAsync(
-            () => Interop.InitializeAsync(_textareaRef, _overlayRef),
+            () => Interop.InitializeAsync(_textareaRef, _overlayRef, SourceCueContracts),
             InitializeSurfaceFailureMessage);
     }
 
@@ -251,7 +260,7 @@ private async Task SafeSyncScrollAsync()
     private async Task SafeRenderOverlayAsync()
     {
         _ = await RunInteropAsync(
-            () => Interop.RenderOverlayAsync(_overlayRef, Text),
+            () => Interop.RenderOverlayAsync(_overlayRef, Text, SourceCueContracts),
             InitializeSurfaceFailureMessage);
     }
 

src/PrompterOne.Shared/Editor/Components/EditorSourcePanel.razor.css

@@ -197,18 +197,30 @@ body.theme-light .efb-menu-item[data-tip]::after {
 .ed-main ::deep .mk-emo-calm{color:#5EECC2;}
 .ed-main ::deep .mk-emo-energetic{color:#FFA050;}
 .ed-main ::deep .mk-emo-professional{color:#80B8FF;}
-.ed-main ::deep .mk-vol-loud{color:#FFB86A;font-weight:800;}
-.ed-main ::deep .mk-vol-soft{color:#C9DFFF;}
-.ed-main ::deep .mk-vol-whisper{color:#D7D1E2;font-style:italic;}
-.ed-main ::deep .mk-del-aside{color:#E2C89A;font-style:italic;}
-.ed-main ::deep .mk-del-rhetorical{color:#D7B8FF;}
-.ed-main ::deep .mk-del-sarcasm{color:#FFAACD;}
-.ed-main ::deep .mk-del-building{color:#FFD98A;font-weight:700;}
-.ed-main ::deep .mk-stress{text-decoration:underline;text-decoration-color:#FFD060;text-underline-offset:4px;text-decoration-thickness:2px;}
-.ed-main ::deep .mk-xslow{color:#FF8A8A;text-shadow:0 0 8px rgba(255,138,138,.16);}
-.ed-main ::deep .mk-slow{color:#FFB86A;text-shadow:0 0 8px rgba(255,184,106,.14);}
-.ed-main ::deep .mk-fast{color:#8ECFFF;text-shadow:0 0 8px rgba(142,207,255,.12);}
-.ed-main ::deep .mk-xfast{color:#8ECFFF;opacity:.84;}
+.ed-main ::deep [data-tps-volume],
+.ed-main ::deep [data-tps-delivery],
+.ed-main ::deep [data-tps-speed],
+.ed-main ::deep [data-tps-stress="true"]{
+    --tps-cue-opacity:1;
+    --tps-cue-scale:1;
+    display:inline-block;
+    font-weight:var(--tps-cue-weight, inherit);
+    opacity:var(--tps-cue-opacity);
+    transform:translateY(calc((1 - var(--tps-cue-scale)) * .04em)) scale(var(--tps-cue-scale));
+    transform-origin:left 72%;
+}
+.ed-main ::deep .mk-vol-loud{color:#FFB86A;font-weight:var(--tps-cue-weight, 800);--tps-cue-scale:1.06;}
+.ed-main ::deep .mk-vol-soft{color:#C9DFFF;--tps-cue-opacity:.92;--tps-cue-scale:.96;}
+.ed-main ::deep .mk-vol-whisper{color:#D7D1E2;font-style:italic;letter-spacing:.025em;--tps-cue-opacity:.84;--tps-cue-scale:.93;}
+.ed-main ::deep .mk-del-aside{color:#E2C89A;font-style:italic;--tps-cue-opacity:.88;--tps-cue-scale:.96;}
+.ed-main ::deep .mk-del-rhetorical{color:#D7B8FF;--tps-cue-scale:1.02;}
+.ed-main ::deep .mk-del-sarcasm{color:#FFAACD;--tps-cue-opacity:.92;--tps-cue-scale:1.01;}
+.ed-main ::deep .mk-del-building{color:#FFD98A;font-weight:var(--tps-cue-weight, 700);--tps-cue-scale:1.05;--tps-cue-weight:760;}
+.ed-main ::deep .mk-stress{text-decoration:underline;text-decoration-color:#FFD060;text-underline-offset:4px;text-decoration-thickness:2px;--tps-cue-scale:1.07;--tps-cue-weight:820;}
+.ed-main ::deep .mk-xslow{color:#FF8A8A;letter-spacing:.018em;text-shadow:0 0 8px rgba(255,138,138,.16);}
+.ed-main ::deep .mk-slow{color:#FFB86A;letter-spacing:.012em;text-shadow:0 0 8px rgba(255,184,106,.14);}
+.ed-main ::deep .mk-fast{color:#8ECFFF;letter-spacing:-.01em;text-shadow:0 0 8px rgba(142,207,255,.12);}
+.ed-main ::deep .mk-xfast{color:#8ECFFF;letter-spacing:-.018em;opacity:.84;}
 .ed-main ::deep .mk-phonetic{color:#D88AFF;background-image:linear-gradient(180deg, transparent 62%, rgba(216,138,255,.12) 62%);box-shadow:inset 0 -1px 0 rgba(216,138,255,.28);}
 .ed-main ::deep .mk-phonetic-word{border-bottom:2px dashed rgba(216,138,255,.4);}
 .ed-main ::deep .mk-special{color:#E0C070;background-image:linear-gradient(180deg, transparent 60%, rgba(224,192,112,.12) 60%);box-shadow:inset 0 -1px 0 rgba(224,192,112,.22);}

src/PrompterOne.Shared/Editor/Rendering/EditorMarkupRenderer.cs

@@ -2,6 +2,7 @@
 using System.Text;
 using System.Text.RegularExpressions;
 using Microsoft.AspNetCore.Components;
+using PrompterOne.Shared.Contracts;
 
 namespace PrompterOne.Shared.Rendering;
 
@@ -140,18 +141,13 @@ private void AppendStyledText(string text)
             var encoded = WebUtility.HtmlEncode(text)
                 .Replace("\n", "<br>", StringComparison.Ordinal);
 
-            var classes = CurrentState.BuildCssClass();
-            if (string.IsNullOrWhiteSpace(classes))
+            if (!CurrentState.RequiresSpan())
             {
                 _builder.Append(encoded);
                 return;
             }
 
-            _builder.Append("<span class=\"")
-                .Append(classes)
-                .Append("\">")
-                .Append(encoded)
-                .Append("</span>");
+            AppendStyledSpan(encoded, CurrentState);
         }
 
         private void HandleTag(string rawTag)
@@ -235,21 +231,42 @@ private void HandleTag(string rawTag)
             if (SpeedClasses.TryGetValue(name, out var speedClass))
             {
                 AppendTag(rawTag);
-                PushScope(name, ScopeKind.Style, CurrentState with { SpeedClass = speedClass });
+                PushScope(
+                    name,
+                    ScopeKind.Style,
+                    CurrentState with
+                    {
+                        SpeedClass = speedClass,
+                        SpeedValue = speedClass is null ? null : name.ToLowerInvariant()
+                    });
                 return;
             }
 
             if (VolumeClasses.TryGetValue(name, out var volumeClass))
             {
                 AppendTag(rawTag);
-                PushScope(name, ScopeKind.Style, CurrentState with { VolumeClass = volumeClass });
+                PushScope(
+                    name,
+                    ScopeKind.Style,
+                    CurrentState with
+                    {
+                        VolumeClass = volumeClass,
+                        VolumeValue = name.ToLowerInvariant()
+                    });
                 return;
             }
 
             if (DeliveryClasses.TryGetValue(name, out var deliveryClass))
             {
                 AppendTag(rawTag);
-                PushScope(name, ScopeKind.Style, CurrentState with { DeliveryClass = deliveryClass });
+                PushScope(
+                    name,
+                    ScopeKind.Style,
+                    CurrentState with
+                    {
+                        DeliveryClass = deliveryClass,
+                        DeliveryValue = name.ToLowerInvariant()
+                    });
                 return;
             }
 
@@ -324,11 +341,21 @@ private void AppendPronunciationPayload(ScopeFrame scope, RenderState parentStat
                 .Append(guide)
                 .Append("</span> ");
 
-            var cssClass = parentState.BuildCssClass("mk-phonetic-word");
-            _builder.Append("<span class=\"")
-                .Append(cssClass)
-                .Append("\">")
-                .Append(spoken)
+            AppendStyledSpan(spoken, parentState, "mk-phonetic-word");
+        }
+
+        private void AppendStyledSpan(string encodedText, RenderState state, params string[] extraClasses)
+        {
+            if (!state.RequiresSpan(extraClasses))
+            {
+                _builder.Append(encodedText);
+                return;
+            }
+
+            _builder.Append("<span");
+            state.AppendHtmlAttributes(_builder, extraClasses);
+            _builder.Append('>')
+                .Append(encodedText)
                 .Append("</span>");
         }
 
@@ -395,14 +422,27 @@ private sealed class ScopeFrame(string name, EditorMarkupRenderer.ScopeKind kind
 
     private sealed record RenderState(
         string? EmotionClass,
+        string? VolumeValue,
         string? VolumeClass,
+        string? DeliveryValue,
         string? DeliveryClass,
+        string? SpeedValue,
         string? SpeedClass,
         bool IsEmphasis,
         bool IsHighlighted,
         bool IsStress)
     {
-        public static readonly RenderState Default = new(null, null, null, null, false, false, false);
+        public static readonly RenderState Default = new(null, null, null, null, null, null, null, false, false, false);
+
+        public bool RequiresSpan(params string[] extraClasses) =>
+            !string.IsNullOrWhiteSpace(EmotionClass) ||
+            !string.IsNullOrWhiteSpace(VolumeClass) ||
+            !string.IsNullOrWhiteSpace(DeliveryClass) ||
+            !string.IsNullOrWhiteSpace(SpeedClass) ||
+            IsEmphasis ||
+            IsHighlighted ||
+            IsStress ||
+            extraClasses.Any(static value => !string.IsNullOrWhiteSpace(value));
 
         public string BuildCssClass(params string[] extraClasses)
         {
@@ -446,6 +486,44 @@ public string BuildCssClass(params string[] extraClasses)
             classes.AddRange(extraClasses.Where(static value => !string.IsNullOrWhiteSpace(value)));
             return string.Join(" ", classes);
         }
+
+        public void AppendHtmlAttributes(StringBuilder builder, params string[] extraClasses)
+        {
+            var classes = BuildCssClass(extraClasses);
+            if (!string.IsNullOrWhiteSpace(classes))
+            {
+                AppendAttribute(builder, "class", classes);
+            }
+
+            if (!string.IsNullOrWhiteSpace(VolumeValue))
+            {
+                AppendAttribute(builder, TpsVisualCueContracts.VolumeAttributeName, VolumeValue);
+            }
+
+            if (!string.IsNullOrWhiteSpace(DeliveryValue))
+            {
+                AppendAttribute(builder, TpsVisualCueContracts.DeliveryAttributeName, DeliveryValue);
+            }
+
+            if (!string.IsNullOrWhiteSpace(SpeedValue))
+            {
+                AppendAttribute(builder, TpsVisualCueContracts.SpeedAttributeName, SpeedValue);
+            }
+
+            if (IsStress)
+            {
+                AppendAttribute(builder, TpsVisualCueContracts.StressAttributeName, TpsVisualCueContracts.StressAttributeValue);
+            }
+        }
+
+        private static void AppendAttribute(StringBuilder builder, string name, string value)
+        {
+            builder.Append(' ')
+                .Append(name)
+                .Append("=\"")
+                .Append(WebUtility.HtmlEncode(value))
+                .Append('"');
+        }
     }
 
     private enum ScopeKind

src/PrompterOne.Shared/Editor/Services/EditorInterop.cs

@@ -9,11 +9,11 @@ public sealed class EditorInterop(IJSRuntime jsRuntime)
 {
     private readonly IJSRuntime _jsRuntime = jsRuntime;
 
-    public ValueTask<bool> InitializeAsync(ElementReference textarea, ElementReference overlay) =>
-        _jsRuntime.InvokeAsync<bool>(EditorSurfaceInteropMethodNames.Initialize, textarea, overlay);
+    public ValueTask<bool> InitializeAsync(ElementReference textarea, ElementReference overlay, object cueContracts) =>
+        _jsRuntime.InvokeAsync<bool>(EditorSurfaceInteropMethodNames.Initialize, textarea, overlay, cueContracts);
 
-    public ValueTask RenderOverlayAsync(ElementReference overlay, string text) =>
-        _jsRuntime.InvokeVoidAsync(EditorSurfaceInteropMethodNames.RenderOverlay, overlay, text ?? string.Empty);
+    public ValueTask RenderOverlayAsync(ElementReference overlay, string text, object cueContracts) =>
+        _jsRuntime.InvokeVoidAsync(EditorSurfaceInteropMethodNames.RenderOverlay, overlay, text ?? string.Empty, cueContracts);
 
     public ValueTask SyncScrollAsync(ElementReference textarea, ElementReference overlay) =>
         _jsRuntime.InvokeVoidAsync(EditorSurfaceInteropMethodNames.SyncScroll, textarea, overlay);