Improve TPS cue visuals and screenshots

Author: KSemenenko

AGENTS.md

@@ -87,12 +87,16 @@ Rule format:
 - TPS authoring completeness must be checked against the upstream `managedcode/TPS` README, not only the currently shipped editor menus, so new editor support stays aligned with the full spec for emotions, delivery, pauses, speed, pronunciation, and related cues.
 - Editor TPS command surfaces must expose the full currently supported TPS authoring set consistently across top toolbar menus, floating-toolbar menus, and Monaco assistance; do not ship partial or differently grouped command taxonomies between those surfaces.
 - TPS cue semantics must be visually represented across both the editor and live reader surfaces: emotions, delivery, voice, pace, energy, pauses or breath marks, pronunciation, phonetics, stress, staccato, legato, emphasis, highlight, aside, rhetorical, building, sarcasm, loud, soft, whisper, and related cues need visible affordances that help the user read intent without inspecting raw TPS tags.
+- TPS word and emotion treatments should use tasteful word-level CSS effects such as gradients, shadows, underline textures, and constrained animation when they make the cue more legible and interesting; do not limit cue rendering to flat color changes, but never let effects reduce readability or cause word overlap.
+- TPS emotion cue colors must be meaningfully distinguishable from each other and should be grounded in color/emotion theory where possible; do not ship a set of near-identical pastel tints that users cannot tell apart while reading.
 - TPS cue rendering work must start from an explicit design note that maps each supported TPS style to its reader/editor visual treatment, animation, and test expectation before implementation, so the product does not grow one-off cue styling.
 - TPS visual cue work must include end-to-end browser coverage and public README screenshots or screenshot-backed examples so users can see that the editor and prompter render the supported cue taxonomy, not only parse it internally.
-- README TPS cue documentation must show a separate visual example for every supported cue family and tag treatment. Each example must be an isolated plain-text reader card with one normal sentence and exactly one central word carrying the TPS cue, so screenshots make one visual effect obvious at a time instead of grouping many tags together.
-- README TPS cue screenshots must capture the full teleprompter reader test block or card, not only a cropped word or raw text line; the card should contain one normal sentence where only the central cue word carries the visual style.
+- README TPS cue documentation must show a separate visual example for every supported cue family and tag treatment. Each example must be an isolated plain-text reader card with one normal sentence and exactly one cue scope, either one central word or a short central phrase when the TPS tag supports phrase spans, so screenshots make one visual effect obvious at a time instead of grouping unrelated tags together.
+- README TPS cue screenshots must capture the full teleprompter reader test block or card, not only a cropped word or raw text line; the card should contain one normal sentence where only the central cue word or cue phrase carries the visual style.
 - 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 per block; do not group multiple TPS tags in the same example card.
+- 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: use a long enough central target word, assert slow and xslow expand its visible width, assert fast and xfast tighten it, and preserve non-overlapping word gaps so readability stays intact.
+- 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.
 - 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

@@ -88,7 +88,7 @@ In the teleprompter, the clean reading line keeps those cues visible through sub
 
 ![TPS cue styling in the teleprompter](docs/screenshots/readme/tps-teleprompter-cues.png)
 
-The screenshot matrix below is generated from `test-tps-cue-matrix.tps`. Each row uses one plain reader card, one normal sentence, and one central cue word so the visual treatment is isolated.
+The screenshot matrix below is generated from `test-tps-cue-matrix.tps`. Each row uses one plain reader card, one normal sentence, and one isolated cue scope: usually one central cue word, plus phrase-span examples where TPS tags can intentionally wrap multiple words.
 
 | TPS cue | Reader meaning | Visible reader treatment | Reader screenshot |
 | --- | --- | --- | --- |
@@ -98,12 +98,12 @@ 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 | Carries a slow timing contract and airy treatment on the central word | <img src="docs/screenshots/readme/tps-cues/07-speed-xslow.png" alt="Xslow cue reader screenshot" width="360"> |
-| `[slow]` | Slow pace | Carries a slow timing contract without overlapping surrounding words | <img src="docs/screenshots/readme/tps-cues/08-speed-slow.png" alt="Slow 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"> |
 | `[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 | Speeds timing while preserving normal readable word spacing | <img src="docs/screenshots/readme/tps-cues/10-speed-fast.png" alt="Fast cue reader screenshot" width="360"> |
-| `[xfast]` | Extra-fast pace | Speeds timing further without visually squeezing the central word into 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 fast timing contract | <img src="docs/screenshots/readme/tps-cues/12-speed-180wpm.png" alt="180 WPM 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"> |
@@ -131,14 +131,19 @@ The screenshot matrix below is generated from `test-tps-cue-matrix.tps`. Each ro
 | `[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 | Keeps the central reader word clean while preserving pronunciation metadata | <img src="docs/screenshots/readme/tps-cues/40-guide-pronunciation.png" alt="Pronunciation guide reader screenshot" width="360"> |
-| `[phonetic:IPA]` | Phonetic note | Keeps the central reader word clean while preserving phonetic metadata | <img src="docs/screenshots/readme/tps-cues/41-guide-phonetic.png" alt="Phonetic guide reader screenshot" width="360"> |
+| `[pronunciation:guide]` | Pronunciation note | Shows the 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 the 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"> |
 | `[edit_point:high]` | High production cut point | Stays out of the spoken line and records the strongest editor marker | <img src="docs/screenshots/readme/tps-cues/45-edit-point-high.png" alt="High edit point reader screenshot" width="360"> |
 | `Speaker:Narrator` | Speaker metadata | Keeps persona metadata in validation, graph, and optional chrome without raw reader text | <img src="docs/screenshots/readme/tps-cues/46-metadata-speaker.png" alt="Speaker metadata reader screenshot" width="360"> |
 | `Archetype:Coach` | Archetype metadata | Keeps delivery persona metadata in validation, graph, and optional chrome without raw reader text | <img src="docs/screenshots/readme/tps-cues/47-metadata-archetype.png" alt="Archetype metadata reader screenshot" width="360"> |
+| `[slow]steady 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]steady 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]steady 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]steady 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]steady 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"> |
 
 The full implemented rendering contract, animation constraints, and verification evidence are recorded in [TPS Cue Rendering Specification](TPS_CUE_RENDERING_PLAN.md).