From 9348d354013b68b5ccc6cbe15650b6ab2210a22e Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Thu, 16 Apr 2026 23:31:05 -0700
Subject: [PATCH] feat(skills): pre-plan persistent-subject choreography
 (Addition C)

User feedback from eval 5 exposed a real R4 failure mode:

- p2 Thread: Maya's card persisted across scenes (good) but often
  landed in positions that didn't fit the scene's content
  hierarchy (bad). Semantic-mismatch.
- p3 Vermeer: painting zoomed to 2.1x in scene 2, blocking the
  right-column metadata the scene subagent had authored. Size-
  collision.

Root cause: expansion identifies the subject, scene subagents
author their scenes INDEPENDENTLY (picking their own layouts),
and the scaffold tweens the subject's position/scale across
transitions as an afterthought. Scene subagents don't know how
big the subject will be in THEIR scene, so they place their
chrome wherever, and then the scaffold's tween scales the subject
up or moves it into regions already filled.

Fix: expansion pre-plans the choreography BEFORE the per-scene
detailed breakdown. Per-scene block specifies:
- position (center x, y)
- scale
- size_envelope (actual on-screen footprint in this scene)
- role (focal / background anchor / data-point / glyph-slot / ...)
- reserved_region (rectangle scene subagent must leave empty)
- scene_must_avoid (short instruction)

Orchestrator (multi-scene.md) passes each scene subagent its
scene's choreography block plus the contract:
- The scaffold owns the subject's DOM + timeline.
- Your scene layout MUST respect the reserved region.
- Design your scene chrome around the element's role in this scene.
- Do NOT animate the persistent subject in your timeline.

Invariants:
- Size envelope reflects the SETTLED state (if the subject scales
  up during the scene, reserve for the larger size).
- Scene-to-scene positions trace a visually-coherent path, not
  leapfrogs.
- Role changes drive reserved-region size.

Branch worktree only. Not synced to installed main skill path.
---
 skills/hyperframes/references/multi-scene.md  | 188 ++++++++++++++++++
 .../references/prompt-expansion.md            |  58 ++++++
 2 files changed, 246 insertions(+)
 create mode 100644 skills/hyperframes/references/multi-scene.md

diff --git a/skills/hyperframes/references/multi-scene.md b/skills/hyperframes/references/multi-scene.md
new file mode 100644
index 000000000..7de628db1
--- /dev/null
+++ b/skills/hyperframes/references/multi-scene.md
@@ -0,0 +1,188 @@
+# Multi-Scene Build Pipeline
+
+For compositions with 2 or more scenes, build in phases instead of one pass. A single pass produces shallow results — detail drops as context fills with boilerplate, and the authoring agent tends to under-decorate later scenes. Giving each scene its own subagent keeps per-scene density and decoration consistent.
+
+Single-pass is reserved for true one-scene compositions: title cards, standalone overlays, single-clip animations.
+
+## Who runs this pipeline
+
+The parallel dispatch in Phase 1 and Phase 2b requires the `Agent`/`Task` tool. In Claude Code, only the **top-level conversation agent** (the one that received the user's `/hyperframes` invocation) has this tool. Dispatched subagents typically do not.
+
+- **If you're the top-level agent:** run the full pipeline. Fan out scene subagents and evaluator subagents in parallel.
+- **If you're a nested subagent** (you were dispatched with a `/hyperframes` task): you cannot fan out further. Author all scene fragments sequentially yourself, strictly following the Scene Fragment Spec below, then run the assembler and lint gates. Do not silently skip the pipeline — note in your final report that parallel dispatch was unavailable and you built serially.
+
+The assembler, scaffold markers, fragment spec, and gates are the same either way; only the dispatch shape changes.
+
+## Scene Fragment Spec
+
+Every scene file (`.hyperframes/scenes/sceneN.html`) must be a **fragment**, not a standalone document. The assembler splits on markers and injects verbatim — non-compliant files break assembly.
+
+### Structure
+
+Exactly three sections, in this order, each appearing exactly once:
+
+```
+<!-- HTML -->
+<div class="s3-heading">...</div>
+...
+
+<!-- CSS -->
+.s3-heading { color: var(--fg); ... }
+...
+
+<!-- GSAP -->
+var S3 = 14.3;
+tl.set('#s3-heading', { opacity: 0, y: 30 }, 0);
+tl.to('#s3-heading', { opacity: 1, y: 0, duration: 0.4 }, S3 + 0.5);
+...
+```
+
+### Required
+
+- **Three markers, one each:** `<!-- HTML -->`, `<!-- CSS -->`, `<!-- GSAP -->` — no duplicates
+- **ID prefix:** All IDs and classes use `s{N}-` prefix (e.g., `#s3-heading`, `.s7-chart`)
+- **GSAP pattern:** `tl.set()` at time 0 for initial state, `tl.to()` at scene time for animation
+- **Scene start var:** Define `var SN = {start_time};` at top of GSAP section, reference it for all tweens
+- **Finite repeats:** All `repeat` values must be explicit numbers, never `-1` or `Infinity`
+
+### Prohibited
+
+- `<!DOCTYPE`, `<html`, `<head`, `<body` — this is a fragment, not a document
+- `<style>` or `</style>` tags — the CSS section is raw CSS, not wrapped in style tags. The scaffold's `<style>` block receives the content directly. Nested style tags break rendering.
+- `<script>` or `</script>` tags — the GSAP section is raw JS, not wrapped in script tags. The scaffold's single `<script>` block receives the content directly. Nested script tags cause `Unexpected token '<'` parse errors.
+- `<script src=` — no external script loading
+- `gsap.timeline(` — the scaffold creates the timeline
+- `window.__timelines` — the scaffold registers it
+- `tl.from(` or `tl.fromTo(` — causes flash-of-default-state (use `tl.set` + `tl.to`)
+- `body {` in CSS — the scaffold owns body styles
+- `.scene {` in CSS — the scaffold owns scene base styles
+- `position`, `top`, `left`, `width`, `height`, `opacity`, or `z-index` on `#sceneN` — the scaffold owns the scene container; only style elements INSIDE the scene
+- Bare class names without `s{N}-` prefix (`.heading`, `.card`, `.tendril`, `.crack`) — causes cross-scene collisions when two scenes use the same name
+- CSS `transform` for centering (`translate(-50%, -50%)`) on elements that GSAP animates — GSAP overwrites the entire `transform` property, destroying the CSS centering. Use GSAP `xPercent: -50, yPercent: -50` in the `tl.set()` at time 0 instead.
+
+### Contrast
+
+All text elements must achieve **4.5:1 contrast ratio** (WCAG AA) against their scene background. Check especially:
+
+- HUD labels, stats, and values against dark backgrounds
+- Light-colored text on tinted/colored backgrounds
+- Small text (under 24px) has no large-text exemption
+
+Use the design.md foreground color for text. If an element needs a different color for visual effect, verify contrast manually.
+
+### Assembly contract
+
+If a scene file follows this spec, the assembler can:
+
+1. Split on `<!-- HTML -->`, `<!-- CSS -->`, `<!-- GSAP -->` markers
+2. Inject HTML between the scaffold's `<div id="sceneN" class="scene">` and `</div>`
+3. Append CSS to the scaffold's `<style>` block
+4. Append GSAP into the scaffold's `<script>` after transitions, before `window.__timelines` registration
+
+No parsing, no stripping, no guessing.
+
+## Phase 1: Scaffold + Scene subagents (parallel)
+
+The scaffold and scene subagents have no dependency on each other — dispatch them all at the same time. Scene subagents don't read the scaffold; they only need the fragment spec, design.md, and their scene prompt section. Assembly waits for both to finish.
+
+**Nested-subagent fallback:** If you don't have the dispatch tool (see "Who runs this pipeline" above), write the scaffold first, then write each scene fragment yourself one after another. Skip Phase 2b streaming evaluation — the assembler's format validation (Phase 3) is your gate instead. Note the constraint in your final report.
+
+### Scaffold
+
+Build the HTML skeleton yourself (or in a subagent):
+
+- All scene `<div>` elements with `data-start`, `data-duration`, `data-track-index`
+- The root composition container with `data-composition-id`, `data-width`, `data-height`
+- The GSAP timeline backbone: `gsap.timeline({ paused: true })`, `window.__timelines` registration
+- All transition code between scenes (read [transitions.md](transitions.md))
+- Global CSS: body reset, scene positioning, font declarations, the `design.md` palette as CSS
+- Leave each scene's inner content empty: `<div id="scene1" class="scene"><!-- SCENE 1 CONTENT --></div>`
+- **Visibility kills for every scene** including the last — after each scene's exit transition, add `tl.set("#sceneN", { visibility: "hidden" }, exitEndTime)`. The final scene needs this too (after its fade-out), or it remains partially visible when scrubbing.
+- **Assembly markers** — the scaffold must include these exact comments so the assembler knows where to inject:
+  - `/* SCENE STYLES */` inside the `<style>` block — scene CSS goes here
+  - `// SCENE TWEENS` inside the `<script>` block, after transitions, before `window.__timelines` registration — scene GSAP goes here
+  - `<!-- SCENE N CONTENT -->` inside each empty scene div — scene HTML goes here
+
+### Scene subagents
+
+Dispatch one subagent per scene, running in parallel (concurrently with the scaffold). Each subagent receives:
+
+- The **Scene Fragment Spec** (above) — the subagent must follow this exactly
+- The `design.md` (or its values summarized)
+- The global animation rules from the prompt
+- That scene's specific prompt section only
+- The scene number `N` and start time — used for the `s{N}-` prefix and `var SN = {start_time};`
+- **The persistent-subject choreography block for this scene**, if any — see below
+
+Each subagent focuses its entire context on making ONE scene visually rich: parallax layers, micro-animations, kinetic typography, ambient motion, background decoratives. No boilerplate, no other scenes. **Each subagent must write to a file** — text returned in conversation is not accessible to the assembly agent.
+
+### Persistent-subject choreography contract
+
+If the expansion identified a persistent subject (R4 applies), the expansion will have produced a choreography plan with one block per scene. See [`prompt-expansion.md` → Pre-plan the persistent-subject choreography](./prompt-expansion.md).
+
+When dispatching scene subagents, **the orchestrator must pass each subagent its scene's choreography block** along with these instructions:
+
+1. **The persistent subject lives in a shared overlay layer outside your scene container.** Do NOT author the subject inside your scene fragment. The scaffold owns the subject's DOM + timeline.
+2. **Your scene's layout must respect the reserved region.** No typography, no decoratives, no scene chrome may be placed inside the reserved region specified for your scene. The subject will occupy it.
+3. **Design your scene's content around the element's role in this scene.** If the role is _focal subject_, your scene chrome is thin margins and light labels around it. If _background anchor_, your chrome fills the frame and the subject is a small corner anchor. If _data-point in a row_, your scene includes the row structure and reserves a slot for the subject.
+4. **Do NOT animate the persistent subject in your GSAP timeline.** The scaffold authors the subject's tweens across scene boundaries on the `tl` timeline. Your scene tweens animate the scene's own content only.
+5. **Your scene may reference the subject's position as a fixed anchor** — e.g., "the label line points at the subject's center at {x, y}." Treat it like a pre-placed element the scaffold will render for you.
+
+The scaffold's responsibility:
+
+1. Create the subject's DOM in the shared overlay layer outside `.scene` containers.
+2. Author tweens on the subject that move it between choreography positions across scene boundaries — the transitions' timing determines when the subject starts its move.
+3. Use `xPercent: -50, yPercent: -50` on the subject so position coords are center coords.
+4. Coordinate scene crossfades with subject moves so the subject's motion spans the crossfade midpoint (so the viewer tracks one element through the cut).
+
+Without this contract: scene subagents place their content where they think looks good, then the scaffold animates the subject into a region that was already filled — producing the size-collision and semantic-mismatch failures observed in prior evals.
+
+## Phase 2b: Streaming evaluation
+
+As each scene file appears in `.hyperframes/scenes/`, dispatch an evaluator subagent immediately — don't wait for all scenes to finish. The evaluator receives:
+
+- The scene file
+- The **Scene Fragment Spec** (above)
+- That scene's section from the original prompt
+- The `design.md`
+
+### Evaluation order: format first, then content
+
+**Step 1 — Format validation (instant FAIL if any check fails):**
+
+- Exactly 3 markers (`<!-- HTML -->`, `<!-- CSS -->`, `<!-- GSAP -->`), each appearing once
+- No prohibited patterns (DOCTYPE, html/head/body tags, `<script>`/`</script>` tags, script src, gsap.timeline, window.\_\_timelines, tl.from, body/scene CSS rules, CSS `transform` on GSAP-animated elements)
+- All IDs and classes use `s{N}-` prefix
+- No position/top/left/width/height/opacity/z-index on `#sceneN` in CSS
+- All `repeat` values are finite numbers
+
+**Step 2 — Content validation (only if format passes):**
+
+- **Prompt adherence**: Does the scene include the elements the prompt described? List what's present and what's missing.
+- **Design compliance**: Are the design.md colors, fonts, corners, and spacing used? Any invented values?
+- **Contrast**: All text elements meet 4.5:1 against the scene background color. Check HUD labels, stats, and small text especially.
+- **Density**: 15+ animated elements? 3 parallax layers?
+
+The evaluator writes a verdict to `.hyperframes/scenes/sceneN.eval.md`: PASS or FAIL with specific issues. If FAIL, re-dispatch the scene subagent with the evaluator's feedback appended to the original instructions. Maximum 2 retries per scene — if a scene fails 3 times, escalate to the user with the evaluator's feedback and ask how to proceed. If PASS, the scene is ready for assembly.
+
+Run evaluators concurrently with scene builds — a scene that finishes first gets evaluated first. The pipeline streams, not batches.
+
+## Phase 3: Assembly
+
+Once all scenes have PASS evaluations, run the deterministic assembler — do NOT hand-stitch scenes manually:
+
+```ts
+const { assembleScenes } = await import("@hyperframes/core/assemble");
+const result = assembleScenes("./project-dir");
+if (!result.ok) {
+  // result.errors has file + message for each issue
+}
+```
+
+The assembler validates every fragment against the spec, splits on markers, injects into the scaffold's marked slots, and verifies div balance. If any fragment fails validation, it aborts with specific errors — fix the fragment and re-run.
+
+After assembly succeeds:
+
+1. Run `npx hyperframes lint` and fix any structural issues
+2. Run `npx hyperframes validate` if available
+3. **Review the output** — read through the assembled file checking that scene HTML, CSS, and GSAP look correct before serving
diff --git a/skills/hyperframes/references/prompt-expansion.md b/skills/hyperframes/references/prompt-expansion.md
index cf4235bd7..d142e5273 100644
--- a/skills/hyperframes/references/prompt-expansion.md
+++ b/skills/hyperframes/references/prompt-expansion.md
@@ -77,6 +77,64 @@ If the composition is about a specific, named, real-world artifact — a photogr
 
 These are the exceptions. The default is: use what's real.
 
+## Pre-plan the persistent-subject choreography
+
+When R4 applies (a subject persists across scenes via shared overlay), the subject's position, size, and role across scenes **must be pre-planned by the expansion**, not left for scene subagents to improvise. Without a pre-plan, two failures happen:
+
+1. **Semantic-mismatch positions** — scene 2's layout puts the subject somewhere that fits scene 2 alone, but the path from scene 1's position to scene 2's position doesn't read as a coherent camera/lens move.
+2. **Size collisions** — scene 2 is authored with its own typography and metadata in regions that the subject will later occupy (because the scaffold scales it up mid-transition). The result: the scaled-up subject blocks the scene's content.
+
+The root cause of both: scene subagents currently author their scenes without knowing how big the subject will be in THEIR scene, or what region they must leave empty for it.
+
+### What the expansion must produce
+
+Before the per-scene breakdown, emit a **choreography plan** for each persistent subject. Per scene, specify:
+
+- **position** — center coordinates `{ x, y }` in the 1920×1080 frame.
+- **scale** — the subject's on-screen scale when the scene is at its hold.
+- **size_envelope** — actual bounding box `{ w, h }` reflecting the SETTLED size in this scene (if the subject scales up or down during the scene, use the largest size it reaches).
+- **role** — the subject's semantic role in this scene: _focal subject_, _background anchor_, _data-point in a row_, _glyph-slot_, _map pin_, _frame margin ornament_, etc.
+- **reserved_region** — rectangular region `{ x: [min,max], y: [min,max] }` the scene subagent must leave empty. If the element fills the frame at this scale, the region fills the frame and typography must live in narrow margins or overlay-over-subject.
+- **scene_must_avoid** — a short instruction for the scene subagent, e.g. "do not place other content in the reserved region" or "typography goes to top-left + bottom-left margins only; no right-column meta at this scale."
+
+Example for a Vermeer painting scene 2 where the painting zooms to 2.1×:
+
+```yaml
+persistent_subject:
+  id: "#painting"
+  form: "<img src='girl-with-pearl-earring.jpg' />"
+
+choreography:
+  scene1:
+    position: { x: 1380, y: 540 }
+    scale: 1.0
+    size_envelope: { w: 540, h: 680 }
+    role: focal subject, held still on the right third
+    reserved_region: { x: [1100, 1920], y: [180, 900] }
+    scene_must_avoid: title/byline typography lives in the left column only
+  scene2:
+    position: { x: 960, y: 540 }
+    scale: 2.1
+    size_envelope: { w: 1134, h: 1428 }
+    role: zoom focus on the pearl/jaw; the painting IS the frame
+    reserved_region: { x: [240, 1680], y: [-250, 1250] }
+    scene_must_avoid: typography goes to top-left + bottom-left margins only; NO right-column meta at this scale
+  scene3:
+    position: { x: 620, y: 540 }
+    scale: 0.85
+    size_envelope: { w: 460, h: 580 }
+    role: closing subject, held left-of-center
+    reserved_region: { x: [380, 860], y: [250, 830] }
+    scene_must_avoid: closing stanza goes to right column
+```
+
+### Invariants
+
+- **Size envelope reflects the settled state.** If the subject enters scene 2 at scale 1 and tweens up to scale 2.1, the envelope for scene 2 is at scale 2.1. Scenes reserve for the FINAL state, not the entry state.
+- **The choreography plan traces a visually-coherent path.** Scene-to-scene positions should read like a deliberate camera/lens move (push-in, pull-back, pan, reposition), not a leapfrog.
+- **Role changes drive reserved-region size.** When the subject is _focal_, the reserved region is large (the subject dominates). When _background anchor_, the region is small or corner-pinned.
+- **Scene subagents receive their scene's choreography block.** See `multi-scene.md` for the dispatch contract.
+
 ## What to generate
 
 Expand into a full production prompt with these sections: