dsh-hyperframes 0.2.0 → 0.3.1

package/skills/embedded-captions/references/aesthetic-principles.md

@@ -0,0 +1,168 @@
+# Aesthetic Principles for Cinematic Captions
+
+The 18 rules that separate "designed" caption work from "preset-generated" caption work. This is the single most important reference in the skill — every plan.json and every Standard-mode HTML should be checked against these before committing.
+
+The whole competitive thesis: every AI caption tool in 2026 (Veed, Submagic, Opus Clip, Captions.ai, CapCut) is a **preset picker**. They hand the user a box of crayons. This skill is a **director** — it exercises judgment. Beat them on taste, not feature count.
+
+---
+
+## The 18 rules
+
+### 1. The subject always wins
+
+Captions exist to serve the face, not compete with it. If the caption draws the eye before the speaker, the caption has failed. **Before shipping any plan.json, ask: "does the caption or the subject read first?"** If caption wins, shrink, dim, or move it.
+
+### 2. Occlude, don't hover
+
+World-class caption design puts text _into_ the scene. Letters that pass behind a shoulder, mic, or head feel diegetic. Letters that float uniformly above the lower-third feel like PowerPoint. Use the matte pipeline — that's the moat over every competitor.
+
+### 3. Contrast is a hierarchy problem, not a brightness problem
+
+A white box behind text is a failure of taste. Priority order:
+
+1. `mix-blend-mode: overlay` or `screen` picking up scene luminance
+2. 2–3px dark stroke + soft drop shadow
+3. Narrow semi-opaque gradient bar (NOT a solid box)
+4. Dim the background plate by 10–15% locally
+5. (LAST RESORT) A hard white pill box — banned on cinematic directions
+
+### 4. Kill the constant lower-third
+
+Fixed-bottom captions are monotone. Caption zone shifts with shot:
+
+- Tight close-up → upper sidebar or crown
+- Mid-shot → embedded on back wall / foam / whiteboard
+- Wide → classic lower-third offset to non-subject side
+
+### 5. One family, two weights maximum
+
+Hierarchy lives in **weight** (e.g., 500 → 800), not in **font**. Mixing Montserrat + script + serif in one clip is the #1 amateur tell. Ship Inter, SF Pro, Söhne, GT America, Aktiv Grotesk, or Neue Haas Grotesk with ≥5 weights and compose with weight + size.
+
+### 6. Tracking tightens as size grows
+
+Display-size (>40pt) wants negative tracking (-10 to -30 units, or `-0.015em` to `-0.035em`). Body-size (14–20pt equivalent) wants positive tracking (+5 to +15, or `+0.005em` to `+0.015em`). Apple SF Pro's optical-size model is the reference. Submagic defaults do the opposite — they look cheap because of it.
+
+### 7. Cap height ≈ 3.5–5% of frame height for body captions
+
+- 1080p vertical (1920 tall): body 65–95px, emph/hook 130–170px
+- 1080p landscape (1080 tall): body 40–55px, emph 70–100px
+- Hormozi-size (~7–9% of frame) is **hook** size, not body size. Reserve for punchlines.
+
+### 8. Never italicize for emphasis in video text
+
+Italics are a **print** convention for flow inside a paragraph. On 24fps motion they read as "tilted" not "stressed". Emphasize with weight (extrabold), color (single accent), or size (1.3–1.6×). Italics allowed only for:
+
+- Literal quotation of written material
+- Foreign word
+- Thought vs spoken dichotomy
+
+### 9. Color discipline: one hue + neutrals
+
+Pick **one** saturated accent per video for keyword highlights. Hormozi's yellow+green+red works for him because his content is already loud. Cinematic = single accent + white/bone/charcoal. Default palette:
+
+- Warm white `#F5EFE6` on dark
+- Graphite `#1A1A1A` on light
+- Accent chosen from scene sampling
+
+### 10. Animate transform only, never the letter itself
+
+`letter-spacing`, `filter:blur`, `font-weight` animations cause inline-block reflow → line-jumps. Animate `translateY`, `scale`, `opacity`, `clip-path`. This is locked from the embedded-captions debugging.
+
+### 11. Minimum 0.4s per word visible
+
+BBC reading speed is 160–180 wpm (0.33–0.38s/word). Cinematic feel wants more breathing room — 200–220ms stagger per word, hold full phrase 0.4–0.6s before exit. Entries under 150ms read as frantic.
+
+### 12. Stagger is the primary expressive axis
+
+Same phrase, different stagger, totally different feel:
+
+| Stagger | Feel                             |
+| ------- | -------------------------------- |
+| 40ms    | machine-gun, urgent, TikTok-hook |
+| 80ms    | conversational, default          |
+| 150ms   | deliberate, documentary          |
+| 250ms+  | poetic, ceremonial               |
+
+Pick from content tone, not default to one value.
+
+### 13. Emphasis escalates _within_ a phrase, not _between_ phrases
+
+Every word bolded = no emphasis. Structure:
+
+- 70% plain body
+- 20% slight lift (color OR weight, not both)
+- 8% full emphasis (bigger, brighter, held longer)
+- 2% climax (biggest, held 1.5s, breath before + after)
+
+### 14. Break rhythm once per 30s
+
+Every-word-same-way = eye adapts, stops registering motion. Plant a rhythm-break every ~30s:
+
+- Phrase enters from opposite direction
+- A single word at 2× size
+- A beat of pure silence with no caption
+- A color shift
+
+This is what separates Submagic-preset work from something designed.
+
+### 15. Caption what adds, cut what restates
+
+Transcribe everything. **Display** 70–85%. Remove:
+
+- Filler ("um", "like", "you know", "I mean")
+- Self-corrections ("I think... I mean actually...")
+- Obvious visual echoes ("as you can see here" while pointing)
+
+Editorial judgment — no existing AI caption tool does this. It's pure upside.
+
+### 16. Segment on breath, not on duration
+
+Chunk at natural pauses ≥ 250ms. A caption spanning a breath-break feels wrong. Whisper word-level timestamps make this trivial.
+
+### 17. Safe zones per platform, always
+
+- 9:16 TikTok/IG/Shorts: caption zone `y ∈ [12%, 78%]` (bottom 22% is UI)
+- 16:9 broadcast: title-safe = center 80%
+- TV export: 5% margin on all sides
+
+Bake into the layout solver. Never eyeball.
+
+### 18. Letterbox/pillarbox is caption real estate
+
+Black bars on 9:16 from 16:9 source? Those bars are the caption home. 2.35:1 cinematic frame on 16:9 export? Serif quotation in the letterbox reads as documentary.
+
+---
+
+## Rhetorical judgment rules (editorial)
+
+These are the "what to caption" decisions. No existing tool exercises them.
+
+- **Filler suppression** — off/light/strong. Default: light for documentary, strong for vlog.
+- **Self-correction folding** — display only the final version.
+- **Breath-group segmentation** — split on silences >250ms, never mid-phrase.
+- **Semantic emphasis** — LLM-pass per phrase: "which 1–2 words carry the meaning?" Highlight those. Don't default to stressed syllables or loudest words.
+- **Silence honor** — if speaker pauses 1.5s+ for rhetorical effect, don't back-fill with lingering prior caption. Let silence breathe.
+- **Quote-sensing** — "he said, quote…" or air quotes → italic (one of the allowed italic exceptions).
+- **No `[laughs]` / `[sighs]`** — those are accessibility captions. For aesthetic captions, they pollute the frame.
+
+---
+
+## Self-critique checklist (run before rendering)
+
+The agent's own pre-render pass. Flag violations:
+
+- [ ] Does the caption or subject read first? (Rule #1)
+- [ ] Any hard white pill boxes? (Rule #3 — banned on cinematic)
+- [ ] Still lower-third for a close-up? (Rule #4)
+- [ ] More than 2 weights or more than 1 font family? (Rule #5)
+- [ ] Italic used for emphasis? (Rule #8 — banned)
+- [ ] More than 1 saturated accent color? (Rule #9)
+- [ ] Letter-spacing or filter:blur animating? (Rule #10 — banned)
+- [ ] Stagger same for documentary and vlog? (Rule #12)
+- [ ] Every group emphasized? (Rule #13)
+- [ ] 30s+ with no rhythm-break? (Rule #14)
+- [ ] Displaying every filler word? (Rule #15)
+- [ ] Caption crossing breath-break? (Rule #16)
+- [ ] Caption in platform UI zone? (Rule #17)
+
+Any "yes" to a violation question → regenerate the affected segment.

package/skills/embedded-captions/references/anti-patterns.md

@@ -0,0 +1,188 @@
+# Anti-Patterns
+
+You default to these. Stop.
+
+Each entry: the bad habit, what it produces, what to do instead. Written in the voice of someone who has watched an agent do this 10 times — because we have.
+
+---
+
+## Layout
+
+### You default to center-aligned crown.
+
+`.crown-plane { left: 0; right: 0; text-align: center }` is the template default, and you'll leave it on every video because it worked once. On a subject that sits right-of-center (Jobs in a 16:9 frame), the body eats the middle 60% of the word and "THE BEATLES" becomes "THE \_\_\_ S".
+
+**Before using the default crown**, run the three conditions in [layout-heuristics.md § Crown placement](layout-heuristics.md):
+
+1. Subject centered within 10% of frame center
+2. Clean zones ≥ 15% on each side
+3. Crown width > subject width + 400px
+
+If any one fails, **move the crown to the larger clean zone** with a narrower container and smaller font. Don't keep centering a word that's about to be 60% occluded.
+
+### You compute text leftmost as `plane_left + padding`.
+
+That's correct for left-aligned. Wrong for the templates you're using, which are **right-aligned** on the main column and **center-aligned** on crowns. The real leftmost depends on the word width.
+
+| Alignment | leftmost_x                                         |
+| --------- | -------------------------------------------------- |
+| Left      | `plane_left + padding_left`                        |
+| Right     | `plane_right − padding_right − longest_line_width` |
+| Center    | `plane_center − longest_line_width / 2`            |
+
+Compute it against the **longest wrapped line**, not the whole phrase. "four very talented guys" wraps to 3 lines — the widest is "talented" (~8 chars), not 23.
+
+### You treat `plane_left` as the text's leftmost edge.
+
+It isn't. With `left: 180px` and a right-aligned 468px word, the text starts 104px **before** `plane_left` relative to the plane, but actually lands somewhere inside the plane box. The plane box just sets the coordinate space — the text positions inside it based on alignment. Check the compiled output, not the plane attribute.
+
+### You center text on the frame when the subject is off-center.
+
+Look at the subject's body center, not the frame center. Jobs sits at x=1100 in a 1920 frame. The **scene's** center of gravity is 1100, not 960. Center-aligning text to 960 is center-aligning to the empty left third, not to anything meaningful.
+
+### You copy-paste position values from memory-wall to a new video.
+
+`top: 40, right: 30, width: 720, rotateY: -13` worked for a 1280×720 frame with an acoustic foam wall on the right. It will not work on a 1920×1080 frame with a bookshelf backdrop. Run the 6-item checklist in [scene-types.md](scene-types.md) for the new video before reusing any numbers.
+
+---
+
+## Typography
+
+### You use template default font sizes regardless of column width.
+
+Template defaults (66/78/92/140) are tuned for a ~560px column. When you bump the plane to 700px+ and don't touch the fonts, the captions feel underweight — small text swimming in negative space.
+
+Use the [Font-size × column-width matrix](typography-presets.md). For a 700px column, that's 78/108/128/220 — a 30-40% bump across the board. Re-check pillarbox safety after bumping (bigger right-aligned text extends further left).
+
+### You pick `intro` style for every first caption.
+
+Intro = italic, smaller, contemplative. Fine for filler discourse markers ("You know,", "So,", "Well,"). **Not** for the first line when it's actually the thesis ("I've had this kind of upbringing"). Read the words semantically, not positionally.
+
+### You skip emphasis entirely because "every caption looks clean."
+
+A story without an emph or crown is typographically flat — viewers can't feel the crescendo. Reserve at least ONE emph per video for the line that lands. Skip it only for truly monotone content (policy statements, warnings).
+
+### You give every group its own style.
+
+Style is supposed to signal _hierarchy_. Using `intro`/`phrase`/`emph`/`dream`/`crown` all in one 15-second video means none of them signal anything. Pick 2-3 styles max for a short clip.
+
+### You only use the 5 preset class names.
+
+`intro / phrase / emph / dream / crown` are scaffolding, not a closed set. The canonical `memory-wall.html` uses `cap-1 / cap-2 / cap-3 / cap-4` — **position-indexed** with bespoke typography per position. That's how it achieves the 3-line right-aligned cascade on the climax. You can't express "this cap has a hanging indent at position 2" with `"style": "dream"`.
+
+The `"style"` field in plan.json accepts **any string** — it becomes `class="cap-<string>"`. Define the class in `custom_css`:
+
+```json
+"custom_css": ".cap-1 { font-size: 78px; ... } .cap-2 { padding-right: 44px; }",
+"groups": [{"id": "cg-0", "style": "1", ...}]
+```
+
+When the scene needs per-position bespoke typography, do this. Don't force-fit into `intro / phrase / emph`.
+
+### You regenerate from plan.json when a canonical example already has the answer.
+
+When scene framing matches `references/example-renders/memory-wall.html` or `champion.html`, clone that HTML into `<project>/index.html` and only swap the GROUPS array. Don't re-derive the design from presets — you'll lose the specific per-position typography that took many iterations to validate. See [bespoke-vs-presets.md § The clone-and-tweak workflow](bespoke-vs-presets.md).
+
+---
+
+## Blending
+
+### You default to `mix-blend-mode: overlay`.
+
+Overlay works on **mid-tone** backgrounds. On dark bookshelves (<60 luminance), overlay makes white text render as black. On sunny backgrounds (>180 luminance), overlay blows out. Check the actual luminance of the caption region in a sampled frame. Pick:
+
+- mid-tone surface (60-180) → `overlay`
+- dark surface (<60) → `screen`
+- bright surface (>180) → `normal` with opaque text
+
+### You animate `letter-spacing` on the word entry.
+
+You saw a "typewriter breath" effect somewhere and added `letterSpacing: "0.04em"` to the `fromTo` "from" state. Result: inline-block reflow every frame → the whole `.cap` line box recomputes → captions visibly jump between rows. See the "Some → line 2" bug from memory-wall.
+
+**Animate only opacity + transform.** If you want a breath effect, use `scale` or `y`, not letter-spacing.
+
+---
+
+## Animation
+
+### You fade both the group container AND each word.
+
+Default feels safer: fade the container in, then fade each word in. But container.opacity × word.opacity produces a non-linear curve — at progress 40% the combined opacity is 16%, not 40%. Visible result: captions seem to "pop" into view around halfway.
+
+Set container opacity to 1 at entrance via `tl.set`, then fade only the words. Single-layer opacity = linear perceived fade.
+
+### You stack captions in a flex column.
+
+Flex-direction: column with multiple `.cap` children looks tidy in source. At runtime, hidden captions (`visibility: hidden`) still reserve flex space. The newly-entering caption shows up at the _bottom_ of the column instead of the designed position — landing in the gesture zone, getting clipped.
+
+Use `position: absolute` for each `.cap` inside the plane so hidden ones don't occupy layout. Both shipped templates do this.
+
+### You start the timeline at t=0.
+
+Caption at exactly t=0 feels like it was there before the video started. Offset 0.1-0.3s (hyperframes motion-principles.md agrees). Same for the very last caption — let it exit before the video fades.
+
+---
+
+## Scene admission
+
+### You trust that "looks like one speaker" = "is one speaker throughout."
+
+TV archive clips cut to B-roll mid-sentence. Interview clips insert cutaways to the interviewer. You didn't check frames beyond the first one, so you rendered captions across a shot transition. Result: captions designed for Subject A are placed relative to Subject B's position (or empty frame) for half the render.
+
+Sample frames at 20%, 50%, 80% BEFORE planning. If the scene changes, trim to the largest single-subject segment.
+
+### You ignore baked-in captions / pillarbox / watermarks.
+
+You saw black bars on the sides and didn't computing the safe-zone. Your captions cross the pillarbox. Or: the source already has burned-in subtitles and you added more — two caption systems fighting for attention.
+
+Run the **letterbox probe** first. If the source has existing captions, refuse with: "source already captioned, adding more would conflict."
+
+### You ship Whisper's transcript without checking timings against the beat.
+
+Transcription is Whisper (via `transcribe.cjs`, no API key) — good word timings, but not infallible: a word can land with a near-zero duration or a timestamp a beat off. This skill is verbatim + on-beat, so `check-timing.cjs --strict` (80ms tolerance) is the gate, not a suggestion — fix drift in `plan.json` before rendering, and never pack two transcript words into one timed entry (the second inherits the first's timestamp and fires early).
+
+---
+
+## Matting
+
+### You enable CoreML for the matting ONNX.
+
+It's the Apple way, obviously faster. No. CoreML partitions the ONNX graph across providers. The mixed-precision boundary produced (observed with the previous RVM engine) alpha=30 inside the subject's face while background correctly reads 0. Captions shine through face. Pin the CPU execution provider only (`onnxruntime-node`). Our `matte.cjs` already does this; don't "optimize" it by re-adding CoreML.
+
+### You pick a matte model by "general vs human."
+
+DECISION FLIPPED 2026-06-12 after a 5-model × 6-scene A/B with caption renders: the matte's job here is CAPTION LAYERING, not prop fidelity. `u2net_human_seg` (via hyperframes `remove-background`) usually excludes thin offset furniture (mic boom arms) from the matte — words stop being sliced by booms, which beat PP-MattingV2's prop-preserving behavior on real caption videos. It is NOT surgical: large salient objects near the subject (telescope rigs) can still leak in — always sample frames_fg/. Known cost: HELD products can drop out intermittently (captions pass in front) — route product-demo climaxes away from held objects. `isnet-general-use` lost outright (backlit-hair collapse). birefnet-portrait (MIT) beat everything semantically (keeps held items AND drops furniture) but is 928 MB / ~7 s-per-frame CPU — a future quality tier, not the default.
+
+---
+
+## Grouping
+
+### You caption every word.
+
+Transcripts are verbose — "you know, um, I, I mean, you know" is 5 words from a single beat. Captioning all of them clutters the screen and breaks reading rhythm.
+
+Editorially drop filler. Use the rules in [caption-grouping.md](caption-grouping.md): merge short fragments, cut repeated discourse markers, keep the meaning, trim the noise. You are writing typography to support speech, not a court transcript.
+
+### You group by fixed word-count.
+
+"3 words per caption, always" makes every caption look the same and fights the natural cadence of speech. Break on sentence boundaries, 250ms+ pauses, and semantic units instead. Caption sizes will naturally vary from 2 words to 5 — that's correct.
+
+---
+
+## The meta anti-pattern
+
+### You read one reference doc and skip the rest.
+
+You'll read this file alone and feel covered. These anti-patterns reference concepts defined in `layout-heuristics.md`, `typography-presets.md`, `scene-types.md`. If you haven't read those, the fix advice here won't make sense.
+
+**Order of reading for a new video**:
+
+1. SKILL.md (decision gate + pipeline + pre-flight probes)
+2. bespoke-vs-presets.md (**first check if a canonical example fits — clone if so**)
+3. scene-types.md (template selection — all 4 wall conditions)
+4. layout-heuristics.md (positions, sides, crown, font scale, pillarbox formula)
+5. typography-presets.md (font-size × column-width table, starting points)
+6. caption-grouping.md (word → group)
+7. **This file last** (to catch yourself before committing to plan.json)
+
+If you're pressed for time, still read this one — it flags the failures you're about to make.

package/skills/embedded-captions/references/bespoke-vs-presets.md

@@ -0,0 +1,178 @@
+# Bespoke design vs. presets — when to override, when to clone
+
+The 5 preset styles (`intro / phrase / emph / dream / crown`) and the 3 templates (`wall-embed`, `corner-column-crown`, `portrait-header`) are **scaffolds**, not rules. The best renders we've shipped all override presets for specific groups because **typography is a per-scene decision**, not a general rule.
+
+If you only use presets, your render will look generic. If you only copy existing renders, your skill won't adapt. The right workflow is:
+
+1. **Decide the shape first** (template choice, plane position, blend mode).
+2. **Check if a canonical example is close enough** → clone and tweak words + timings.
+3. **Otherwise start from presets** → override per-group via `custom_css`.
+
+---
+
+## Canonical example renders
+
+Full HTML for two validated renders is in `references/example-renders/`:
+
+| File               | Scene                                                   | What makes it work                                                                                                                                                                                         |
+| ------------------ | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `memory-wall.html` | Introspective monologue, right-side foam wall, mid-tone | Right-aligned cascade, per-group bespoke sizes (`cap-1` 78 italic / `cap-2` 66 italic + right hanging-indent / `cap-3` 72 upright / `cap-4` 90 uppercase). `mix-blend-mode: screen` for the dark-ish foam. |
+| `champion.html`    | Podcast interview, cluttered bookshelf, 1920×1080       | Upper-left column + center-stage crown. Tuned preset class sizes (`cap-intro` 52 / `cap-phrase` 60 / `cap-emph` 70 / `cap-crown` 140). `screen` blend reads the shelves through text.                      |
+
+**When a new scene matches one of these closely** (similar framing, similar subject-center, similar backdrop type): clone the HTML and only replace the GROUPS array + word timings. Don't re-derive the design from presets — you'll lose the specific choices that took many iterations to validate.
+
+---
+
+## When presets are wrong
+
+You'll reach for presets like `"style": "emph"` when what the scene really needs is:
+
+### "This cap is at position N and deserves its own treatment"
+
+`memory-wall.html` uses `cap-1 / cap-2 / cap-3 / cap-4` — **position-indexed**, not role-indexed. Each one is a bespoke design for a specific phrase at a specific point in the arc:
+
+- cap-1 (soft opener, 4 words): 78px italic 600 — feels like a whisper
+- cap-2 (dreamy modifier, 3 words): 66px italic 500 + `padding-right: 44px` — hanging indent creates ragged right-edge stagger
+- cap-3 (turn, 2 words): 72px upright 700 — the syntactic pivot, no italic
+- cap-4 (climax, 4 words): 90px uppercase 900 — three lines cascade right-aligned
+
+`phrase/emph/intro` can't express "this cap has a hanging indent" or "this cap is the syntactic pivot". When that matters, invent your own class names:
+
+```json
+{
+  "template": "wall-embed",
+  "custom_css": "
+    .cap-1 { font-size: 78px; font-weight: 600; font-style: italic;
+             letter-spacing: -0.01em; }
+    .cap-2 { font-size: 66px; font-weight: 500; font-style: italic;
+             padding-right: 44px; }
+    .cap-3 { font-size: 72px; font-weight: 700; letter-spacing: -0.015em; }
+    .cap-4 { font-size: 90px; font-weight: 900; letter-spacing: -0.03em;
+             text-transform: uppercase; line-height: 1.0; }
+  ",
+  "groups": [
+    { "id": "cg-0", "style": "1", "words": [...] },
+    { "id": "cg-1", "style": "2", "words": [...] },
+    ...
+  ]
+}
+```
+
+The `"style": "1"` field becomes `class="cap-1"` on the element — any string works, no validation.
+
+### "The template's blend doesn't suit this backdrop" → pick a different template, do NOT override
+
+**Cinematic mode does not override colour or blend.** A template's `mix-blend-mode` + fill are **locked DNA** — `make-composition.cjs` ignores `plan.cap_color` / `blend_mode` / `text_shadow` / `text_filter`. Selecting a template commits to its look; the only agent-authored things are layout (planes/positions) and per-group typography.
+
+So use the caption-region luminance to **choose** a template that already fits — never to recolour one:
+
+| Region luminance                  | What fits                                                                                     | Why                                                                        |
+| --------------------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| < 60 (dark / low-key)             | a cream + `screen` template (`cinematic-cream`, `memory-wall`, `champion`, `portrait-header`) | light text glows, picks up the scene                                       |
+| 60–180 (mid-tone)                 | a cream + `screen` template still reads (add a scrim via Standard if marginal)                | text picks up texture                                                      |
+| > 180 (bright: window, pale wall) | **none of the cream/`screen` Cinematic templates — they wash out**                            | → use **Standard mode** (opaque rail, set per the chosen template) instead |
+
+If the scene is bright and the cream/`screen` look washes out, that's the signal to switch to **Standard mode** (which sets opaque colour in the HTML), not to recolour a Cinematic template into something it isn't.
+
+### "Hanging indent / outdent / letter-width tweak"
+
+These are per-group affordances you'll occasionally need. Express via `custom_css`:
+
+```css
+#cg-2 {
+  padding-right: 44px;
+} /* right-aligned: shrinks right edge, creating left outdent */
+#cg-2 {
+  padding-left: 44px;
+} /* left-aligned: offset right start */
+.cap-emph .w:first-child {
+  font-size: 110%;
+} /* oversize first word only */
+```
+
+The `#cg-N` selector always works because `make-composition.cjs` writes `<div id="cg-N" ...>` for every group.
+
+### "Caps should accumulate (flex stack) instead of swap"
+
+All three templates default to `position: absolute` on `.cap` inside their plane — caps stack at one spot and only the active one shows (single-caption swap). This is correct for `portrait-header` and `corner-column-crown`, where each caption replaces the last.
+
+`memory-wall` uses **flex column accumulation** — captions pile up like a poem. The template doesn't default to this, so override via custom_css:
+
+```css
+.wall-plane {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: flex-end; /* or flex-start for left-aligned */
+  text-align: right;
+  gap: 14px;
+}
+.wall-plane .cap {
+  position: static; /* un-do template's absolute */
+  top: auto;
+  right: auto;
+  max-width: 100%;
+}
+```
+
+With this + staggered `in` / `out` times, cap-0 fades in at t=0.2, cap-1 at t=2.55 (below cap-0 in flex order), cap-2 at t=4.90 (replaces both as they fade out together at t=4.85) — this is how the memory-wall poem pages work.
+
+### "Font size doesn't match the scene"
+
+Template preset sizes are tuned for a specific column width + frame size. Don't fight them — override:
+
+```json
+"custom_css": ".cap-intro { font-size: 52px; } .cap-phrase { font-size: 60px; }"
+```
+
+Then check [typography-presets.md § Font-size scales with column width](typography-presets.md) for what to aim at given your plane's actual dimensions.
+
+---
+
+## The clone-and-tweak workflow
+
+For a new video that's clearly similar to an existing canonical example:
+
+```bash
+# 1. Scaffold the project
+hyperframes init <project> --non-interactive --video <video.mp4> --skill=embedded-captions
+
+# 2. Matte + transcribe
+node scripts/matte.cjs <project>
+node scripts/transcribe.cjs <project>
+
+# 3. Copy the canonical HTML instead of writing plan.json
+cp references/example-renders/memory-wall.html <project>/index.html
+
+# 4. Replace GROUPS array with the new transcript's grouping (hand-edit index.html)
+
+# 5. Render directly (skip make-composition.cjs since we're not using plan.json)
+bash scripts/render-and-composite.sh <project>
+```
+
+This skips the preset-based plan.json entirely. Use when:
+
+- Subject framing, shot composition, and backdrop type are similar to the example
+- You just need to swap the words and timings
+- The bespoke typography from the example is what you want
+
+**Don't clone when**:
+
+- Subject position differs significantly (e.g. centered vs off-center)
+- Scene luminance / blend-mode needs are different
+- You want to experiment with new typography
+
+In those cases, start with plan.json + custom_css and iterate.
+
+---
+
+## Rendering history
+
+`render-and-composite.sh` now snapshots `index.html` + `plan.json` into `<project>/history/` with a timestamp before every render. If the user says "the previous one was better", diff against the latest snapshot:
+
+```bash
+ls <project>/history/
+diff <project>/history/index-20260422-203947.html <project>/index.html
+```
+
+This lets you recover a design you iterated away from, without re-reading the agent transcript.

package/skills/embedded-captions/references/caption-grouping.md

@@ -0,0 +1,130 @@
+# Caption Grouping
+
+How to turn the Whisper word-level transcript into the `groups[]` array of plan.json.
+
+## Goal
+
+**Each group is one visual phrase**: enters, reveals word-by-word, exits. Rule of thumb: 1 group ≈ 1 comma-to-comma clause or 1 breath of speech.
+
+## Input
+
+`transcript.json` from `transcribe.cjs`:
+
+```json
+{
+  "words": [
+    { "text": "Some", "start": 0.24, "end": 0.44, "type": "word" },
+    { "text": " ", "start": 0.44, "end": 0.48, "type": "spacing" },
+    { "text": "memories", "start": 0.48, "end": 0.82, "type": "word" }
+  ]
+}
+```
+
+Drop `type: "spacing"` entries; you only need words.
+
+## Break boundaries
+
+Cut a new group at ANY of:
+
+1. **Pause ≥ 500ms** (gap between word.end[i] and word.start[i+1]) — speaker took a breath.
+2. **Sentence terminator** — word ends with `.`, `?`, `!`, or an em-dash-like pause.
+3. **Strong comma** — `,` followed by pause ≥ 250ms.
+4. **Discourse reset** — words like "but", "so", "and then", "you know" starting a clause often merit their own or new group.
+5. **Group reaches 6 words OR 2.5 seconds** — whichever first. Long groups feel like subtitles, not embedded typography.
+
+Hard constraints:
+
+- Minimum 2 words per group (1-word exceptions: interjections like "Wait." or the crown line).
+- Minimum 0.5s on screen. If a group is less, merge into neighbor.
+- No overlapping groups — at most one visible at a time.
+
+## Timing the group
+
+For a group with words `w[0]..w[n-1]`:
+
+- `in` = `w[0].start - 0.08` (enter slightly before first word)
+- `out` = `min(next_group.in - 0.05, w[n-1].end + 0.6)` (linger ~0.6s after last word, but don't collide with next)
+
+The last group extends to the video end if needed.
+
+## Style & tone (cross-reference)
+
+See `typography-presets.md` for how to pick `style` and `tone` per group. Work left-to-right through the groups and:
+
+1. First group: default `intro` + `soft`.
+2. Watch for emphasis signals (ALL CAPS in transcript is rare but possible; more often it's semantic — superlatives, proper nouns).
+3. Escalate tone into `present` once the monologue shifts from setup to statement.
+4. Reserve `crown` for at most ONE group, typically the final line.
+
+## Editorial surgery is allowed
+
+You do NOT have to caption every word. It's fine to:
+
+- **Drop filler** like extra "you know"s, "um"s, "I mean"s if they bloat the visual pace.
+- **Condense** a 6-word run into 4 by cutting function words, as long as the meaning and timing remain truthful.
+- **Skip the whole thing** during obvious silence or non-speech (laugh, music interlude).
+
+Editorial rule: you are writing typography to support the speech, not a court transcript. Keep meaning, trim noise.
+
+## Example (champion)
+
+Transcript: "You know, for me I've had this kind of upbringing, had the great foundation and, you know, I've achieved incredible things. I was dreaming of becoming number one in the world and becoming a Wimbledon champion"
+
+Groups after editorial pass:
+
+```json
+[
+  {
+    "id": "cg-0",
+    "style": "intro",
+    "tone": "soft",
+    "words": ["You", "know", "for", "me"],
+    "in": 0.1,
+    "out": 1.45
+  },
+  {
+    "id": "cg-1",
+    "style": "phrase",
+    "tone": "soft",
+    "words": ["I've", "had", "this", "kind", "of", "upbringing"],
+    "in": 1.4,
+    "out": 3.35
+  },
+  {
+    "id": "cg-2",
+    "style": "phrase",
+    "tone": "soft",
+    "words": ["the", "great", "foundation"],
+    "in": 3.5,
+    "out": 5.35
+  },
+  {
+    "id": "cg-3",
+    "style": "emph",
+    "tone": "present",
+    "words": ["I've", "achieved", "incredible", "things"],
+    "in": 6.05,
+    "out": 8.3
+  },
+  {
+    "id": "cg-4",
+    "style": "dream",
+    "tone": "present",
+    "words": ["dreaming", "of", "becoming", "number", "one"],
+    "in": 8.5,
+    "out": 10.4
+  }
+]
+```
+
+Plus the crown:
+
+```json
+{ "id": "cg-crown", "style": "crown", "words": ["Wimbledon", "Champion"], "in": 10.8, "out": 12.08 }
+```
+
+Notice "had" was dropped from cg-2 ("had the great foundation" → "the great foundation"), "I was" was dropped from cg-4, and "a" was dropped from crown — all for visual cadence.
+
+## word.start/end inside groups
+
+Pass through the original timestamps from the transcript. Don't retime individual words — only the group `in`/`out`. The word-level karaoke reveal inside each group uses the original w.start.