Refine TPS music cue visuals

Author: KSemenenko

AGENTS.md

@@ -97,9 +97,13 @@ Rule format:
 - README TPS cue screenshots may use a static reader state; do not start playback just to document a visual cue treatment when selecting the target block and active word already shows the style clearly.
 - The TPS cue matrix fixture must keep the same one-cue isolation contract as the README screenshots: `test-tps-cue-matrix.tps` needs one block per visual treatment, one normal sentence per block, and one central cue-bearing word or short phrase per block; do not group unrelated TPS tags in the same example card.
 - TPS speed cue screenshots must make the pace treatment obvious on the cue-bearing word: when the matrix uses cue-named focus words such as `xslow`, `slow`, `fast`, and `xfast`, assert the computed letter-spacing order and preserve non-overlapping word gaps; use a separate same-word control only when validating absolute width comparisons.
+- TPS slow and loud cue visuals must be obvious in the reader: slow/xslow should visibly broaden the cue word through tracking and word-shape treatment, while loud should carry a larger, weightier typographic presence without creating overlap or baseline jumps.
 - TPS pronunciation and phonetic cue screenshots must show the readable guide in the reader UI, not only store it in hidden attributes or tooltips, so users can see how the word should be pronounced while reading the matrix.
 - TPS pronunciation and phonetic reader guides must be large enough to read as rehearsal text above the cue word; do not render them as tiny tooltip pills that require zooming.
+- TPS pronunciation and phonetic cue examples must use realistic pronunciation notation with IPA-style symbols and stress marks, not placeholder labels such as `GUIDE` or `IPA`.
 - TPS cue matrix focus words must name the cue being demonstrated when possible, for example `[sad]sad[/sad]` instead of styling a generic word such as `calibration`, so each screenshot is understandable on its own.
+- TPS articulation visuals must follow music-reading metaphors: `legato` should read like a curved slur/ligature mark, not a wavy spelling-style underline, and a legato phrase should use one slur across the grouped phrase when possible; `staccato` should read as dots.
+- TPS editorial cues must remain visually distinct: `[emphasis]`, Markdown `**bold**`, Markdown `*italic*`, and `[highlight]` need separate reader treatments instead of collapsing into the same underline or generic emphasis style.
 - User-facing file transfer actions in the shell should use `Import` and `Export` wording instead of `Open Script` and `Save File`, because the app also has its own internal script/workspace structure.
 - File workflows must stay local-first inside PrompterOne: scripts need in-app autosave and an internal change-history path in the browser environment, not only external disk import/export actions.
 - Hotkey work must target PrompterOne’s own browser surfaces and settings inventory only; do not design around OBS commands or claim OBS integration paths that the product does not have.

README.md

@@ -84,7 +84,7 @@ In the editor, TPS authoring stays readable while Monaco colors cue tags, underl
 
 ![TPS cue styling in the editor](docs/screenshots/readme/tps-editor-cues.png)
 
-In the teleprompter, the clean reading line keeps those cues visible through subtle contour: pace changes affect timing, slower cues may widen word spacing, faster cues keep normal non-overlapping spacing, voice and delivery affect emphasis, breath marks appear as reading rests, legato and staccato use music-like line texture, and energy or melody adds a stronger visual rhythm without exposing raw TPS tags.
+In the teleprompter, the clean reading line keeps those cues visible through music-inspired reading marks: pace changes affect timing and word shape, slower cues widen the word, faster cues keep bounded non-overlapping tracking, loud cues get larger and weightier, building delivery adds a crescendo-style hairpin, breath and pause cues read like rests, legato uses a music-like slur, staccato uses dots, and energy or melody adds stronger visual rhythm without exposing raw TPS tags. The notation model follows common score-reading conventions for slurs, staccato, and crescendo hairpins from music notation references such as [List of musical symbols](https://en.wikipedia.org/wiki/List_of_musical_symbols) and [Music Theory Academy's dynamics guide](https://www.musictheoryacademy.com/how-to-read-sheet-music/dynamics/).
 
 ![TPS cue styling in the teleprompter](docs/screenshots/readme/tps-teleprompter-cues.png)
 
@@ -98,15 +98,15 @@ The screenshot matrix below is generated from `test-tps-cue-matrix.tps`. Each ro
 | `[pause:500ms]` | Explicit half-second rest | Renders a pause cue before the central word and preserves phrase spacing | <img src="docs/screenshots/readme/tps-cues/04-pause-500ms.png" alt="500 millisecond pause reader screenshot" width="360"> |
 | `[pause:1s]` | Explicit one-second rest | Renders a pause cue before the central word and keeps the next word readable | <img src="docs/screenshots/readme/tps-cues/05-pause-1s.png" alt="One second pause reader screenshot" width="360"> |
 | `[breath]` | Breath cue | Renders a breath rest before the central word without turning the cue into spoken text | <img src="docs/screenshots/readme/tps-cues/06-breath.png" alt="Breath cue reader screenshot" width="360"> |
-| `[xslow]` | Extra-slow pace | Widens the central word with visibly airy tracking and slower timing | <img src="docs/screenshots/readme/tps-cues/07-speed-xslow.png" alt="Xslow cue reader screenshot" width="360"> |
-| `[slow]` | Slow pace | Opens the central word with positive tracking while preserving readable gaps | <img src="docs/screenshots/readme/tps-cues/08-speed-slow.png" alt="Slow cue reader screenshot" width="360"> |
+| `[xslow]` | Extra-slow pace | Broadens the central word with visibly airy tracking, wider word shape, and slower timing | <img src="docs/screenshots/readme/tps-cues/07-speed-xslow.png" alt="Xslow cue reader screenshot" width="360"> |
+| `[slow]` | Slow pace | Opens and broadens the central word while preserving readable gaps | <img src="docs/screenshots/readme/tps-cues/08-speed-slow.png" alt="Slow cue reader screenshot" width="360"> |
 | `[normal]` | Reset to normal pace | Returns the central word to the base pace treatment | <img src="docs/screenshots/readme/tps-cues/09-speed-normal.png" alt="Normal pace cue reader screenshot" width="360"> |
 | `[fast]` | Fast pace | Tightens the central word with compact tracking and faster timing | <img src="docs/screenshots/readme/tps-cues/10-speed-fast.png" alt="Fast cue reader screenshot" width="360"> |
 | `[xfast]` | Extra-fast pace | Makes the central word visibly narrower without colliding with neighbors | <img src="docs/screenshots/readme/tps-cues/11-speed-xfast.png" alt="Xfast cue reader screenshot" width="360"> |
 | `[180WPM]` | Explicit WPM pace | Maps the central word to a measured fast timing and compact spacing contract | <img src="docs/screenshots/readme/tps-cues/12-speed-180wpm.png" alt="180 WPM cue reader screenshot" width="360"> |
-| `[loud]` | Strong vocal intensity | Adds stronger weight and tone to the central word | <img src="docs/screenshots/readme/tps-cues/13-volume-loud.png" alt="Loud cue reader screenshot" width="360"> |
-| `[soft]` | Softer delivery | Lowers intensity while keeping the central word legible | <img src="docs/screenshots/readme/tps-cues/14-volume-soft.png" alt="Soft cue reader screenshot" width="360"> |
-| `[whisper]` | Whispered delivery | Uses subdued opacity and tone for the central word | <img src="docs/screenshots/readme/tps-cues/15-volume-whisper.png" alt="Whisper cue reader screenshot" width="360"> |
+| `[loud]` | Strong vocal intensity | Makes the central word visibly larger and weightier with a warmer projected tone | <img src="docs/screenshots/readme/tps-cues/13-volume-loud.png" alt="Loud cue reader screenshot" width="360"> |
+| `[soft]` | Softer delivery | Uses a smaller, lighter, cooler treatment while keeping the central word legible | <img src="docs/screenshots/readme/tps-cues/14-volume-soft.png" alt="Soft cue reader screenshot" width="360"> |
+| `[whisper]` | Whispered delivery | Uses a smaller, airy italic treatment with subdued opacity and dotted texture | <img src="docs/screenshots/readme/tps-cues/15-volume-whisper.png" alt="Whisper cue reader screenshot" width="360"> |
 | `[warm]` | Warm emotional tone | Tints the central word with an amber/orange warm treatment | <img src="docs/screenshots/readme/tps-cues/16-emotion-warm.png" alt="Warm emotion cue reader screenshot" width="360"> |
 | `[urgent]` | Urgent emotional tone | Gives the central word a red/crimson urgent treatment | <img src="docs/screenshots/readme/tps-cues/17-emotion-urgent.png" alt="Urgent emotion cue reader screenshot" width="360"> |
 | `[excited]` | Excited emotional tone | Gives the central word a magenta/violet excited treatment | <img src="docs/screenshots/readme/tps-cues/18-emotion-excited.png" alt="Excited emotion cue reader screenshot" width="360"> |
@@ -121,18 +121,18 @@ The screenshot matrix below is generated from `test-tps-cue-matrix.tps`. Each ro
 | `[neutral]` | Neutral tone reset | Returns the central word to neutral delivery even inside a warmer block context | <img src="docs/screenshots/readme/tps-cues/27-emotion-neutral.png" alt="Neutral emotion cue reader screenshot" width="360"> |
 | `[aside]` | Aside delivery shape | Gives the central word a delivery-specific aside cue | <img src="docs/screenshots/readme/tps-cues/28-delivery-aside.png" alt="Aside delivery cue reader screenshot" width="360"> |
 | `[rhetorical]` | Rhetorical delivery shape | Marks the central word with a rhetorical treatment | <img src="docs/screenshots/readme/tps-cues/29-delivery-rhetorical.png" alt="Rhetorical delivery cue reader screenshot" width="360"> |
-| `[building]` | Building delivery shape | Adds a build cue so delivery can rise through the phrase | <img src="docs/screenshots/readme/tps-cues/30-delivery-building.png" alt="Building delivery cue reader screenshot" width="360"> |
+| `[building]` | Building delivery shape | Adds a crescendo-style hairpin and progressive weight so delivery can rise through the phrase | <img src="docs/screenshots/readme/tps-cues/30-delivery-building.png" alt="Building delivery cue reader screenshot" width="360"> |
 | `[sarcasm]` | Sarcastic delivery shape | Marks the central word with a sarcastic delivery cue | <img src="docs/screenshots/readme/tps-cues/31-delivery-sarcasm.png" alt="Sarcasm delivery cue reader screenshot" width="360"> |
-| `[legato]` | Smooth articulation | Adds a music-like connected underline texture below the central word | <img src="docs/screenshots/readme/tps-cues/32-articulation-legato.png" alt="Legato articulation cue reader screenshot" width="360"> |
-| `[staccato]` | Clipped articulation | Adds a dotted, clipped underline texture below the central word | <img src="docs/screenshots/readme/tps-cues/33-articulation-staccato.png" alt="Staccato articulation cue reader screenshot" width="360"> |
+| `[legato]` | Smooth articulation | Adds a music-like curved slur below the central word | <img src="docs/screenshots/readme/tps-cues/32-articulation-legato.png" alt="Legato articulation cue reader screenshot" width="360"> |
+| `[staccato]` | Clipped articulation | Adds clipped music-like dots below the central word | <img src="docs/screenshots/readme/tps-cues/33-articulation-staccato.png" alt="Staccato articulation cue reader screenshot" width="360"> |
 | `[energy:8]` | High intensity contour | Adds stronger energy weight and rhythm to the central word | <img src="docs/screenshots/readme/tps-cues/34-contour-energy.png" alt="Energy contour cue reader screenshot" width="360"> |
 | `[melody:3]` | Melodic movement | Adds a subtle melodic contour to the central word | <img src="docs/screenshots/readme/tps-cues/35-contour-melody.png" alt="Melody contour cue reader screenshot" width="360"> |
-| `[highlight]` | Editorial highlight | Preserves highlight as a visible phrase cue on the central word | <img src="docs/screenshots/readme/tps-cues/36-editorial-highlight.png" alt="Highlight cue reader screenshot" width="360"> |
-| `[emphasis]` | Editorial emphasis | Preserves emphasis as continuous reader styling | <img src="docs/screenshots/readme/tps-cues/37-editorial-emphasis.png" alt="Emphasis cue reader screenshot" width="360"> |
-| Markdown bold | Strong editorial emphasis | Shows bold emphasis on the central word without raw markdown markers | <img src="docs/screenshots/readme/tps-cues/38-markdown-bold.png" alt="Markdown bold reader screenshot" width="360"> |
-| Markdown italic | Light editorial emphasis | Shows italic emphasis on the central word without raw markdown markers | <img src="docs/screenshots/readme/tps-cues/39-markdown-italic.png" alt="Markdown italic reader screenshot" width="360"> |
-| `[pronunciation:guide]` | Pronunciation note | Shows a large readable pronunciation guide above the central word while keeping the spoken word clean | <img src="docs/screenshots/readme/tps-cues/40-guide-pronunciation.png" alt="Pronunciation guide reader screenshot" width="360"> |
-| `[phonetic:IPA]` | Phonetic note | Shows a large readable phonetic guide above the central word while keeping the spoken word clean | <img src="docs/screenshots/readme/tps-cues/41-guide-phonetic.png" alt="Phonetic guide reader screenshot" width="360"> |
+| `[highlight]` | Editorial highlight | Uses a translucent marker-pen background behind the central word | <img src="docs/screenshots/readme/tps-cues/36-editorial-highlight.png" alt="Highlight cue reader screenshot" width="360"> |
+| `[emphasis]` | Editorial emphasis | Uses a strong underline and weight treatment that stays distinct from markdown bold and italic | <img src="docs/screenshots/readme/tps-cues/37-editorial-emphasis.png" alt="Emphasis cue reader screenshot" width="360"> |
+| Markdown bold | Strong editorial emphasis | Shows a heavier bold word shape without raw markdown markers | <img src="docs/screenshots/readme/tps-cues/38-markdown-bold.png" alt="Markdown bold reader screenshot" width="360"> |
+| Markdown italic | Light editorial emphasis | Shows a visibly slanted italic word shape without raw markdown markers | <img src="docs/screenshots/readme/tps-cues/39-markdown-italic.png" alt="Markdown italic reader screenshot" width="360"> |
+| `[pronunciation:prəˌnʌnsiˈeɪʃən]` | Pronunciation note | Shows a large readable pronunciation guide above the central word while keeping the spoken word clean | <img src="docs/screenshots/readme/tps-cues/40-guide-pronunciation.png" alt="Pronunciation guide reader screenshot" width="360"> |
+| `[phonetic:/fəˈnɛtɪk/]` | Phonetic note | Shows a large readable phonetic guide above the central word while keeping the spoken word clean | <img src="docs/screenshots/readme/tps-cues/41-guide-phonetic.png" alt="Phonetic guide reader screenshot" width="360"> |
 | `[stress:rising]` | Stress guide | Adds stress treatment to the central word for rehearsal | <img src="docs/screenshots/readme/tps-cues/42-guide-stress.png" alt="Stress guide reader screenshot" width="360"> |
 | `[edit_point]` | Production cut point | Stays out of the spoken word while leaving operator/editor context | <img src="docs/screenshots/readme/tps-cues/43-edit-point.png" alt="Edit point reader screenshot" width="360"> |
 | `[edit_point:medium]` | Medium production cut point | Stays out of the spoken line and records a stronger editor marker | <img src="docs/screenshots/readme/tps-cues/44-edit-point-medium.png" alt="Medium edit point reader screenshot" width="360"> |
@@ -142,8 +142,8 @@ The screenshot matrix below is generated from `test-tps-cue-matrix.tps`. Each ro
 | `[slow]slow cadence[/slow]` | Phrase pace span | Applies the same slow timing and open tracking across a two-word cue phrase | <img src="docs/screenshots/readme/tps-cues/48-phrase-speed-slow.png" alt="Slow phrase reader screenshot" width="360"> |
 | `[urgent]urgent cadence[/urgent]` | Phrase emotion span | Applies the urgent color treatment across a two-word cue phrase | <img src="docs/screenshots/readme/tps-cues/49-phrase-emotion-urgent.png" alt="Urgent phrase reader screenshot" width="360"> |
 | `[loud]loud cadence[/loud]` | Phrase volume span | Applies stronger vocal weight and tone across a two-word cue phrase | <img src="docs/screenshots/readme/tps-cues/50-phrase-volume-loud.png" alt="Loud phrase reader screenshot" width="360"> |
-| `[building]building cadence[/building]` | Phrase delivery span | Applies the building delivery treatment across a two-word cue phrase | <img src="docs/screenshots/readme/tps-cues/51-phrase-delivery-building.png" alt="Building phrase reader screenshot" width="360"> |
-| `[legato]legato cadence[/legato]` | Phrase articulation span | Applies the smooth legato underline texture across a two-word cue phrase | <img src="docs/screenshots/readme/tps-cues/52-phrase-articulation-legato.png" alt="Legato phrase reader screenshot" width="360"> |
+| `[building]building cadence[/building]` | Phrase delivery span | Applies one crescendo-style hairpin and progressive build treatment across the two-word cue phrase | <img src="docs/screenshots/readme/tps-cues/51-phrase-delivery-building.png" alt="Building phrase reader screenshot" width="360"> |
+| `[legato]legato cadence[/legato]` | Phrase articulation span | Applies one smooth legato slur across the two-word cue phrase | <img src="docs/screenshots/readme/tps-cues/52-phrase-articulation-legato.png" alt="Legato phrase reader screenshot" width="360"> |
 
 The full implemented rendering contract, animation constraints, and verification evidence are recorded in [TPS Cue Rendering Specification](TPS_CUE_RENDERING_PLAN.md).