|
| 1 | +# Multi-Scene Build Pipeline |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +Single-pass is reserved for true one-scene compositions: title cards, standalone overlays, single-clip animations. |
| 6 | + |
| 7 | +## Who runs this pipeline |
| 8 | + |
| 9 | +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. |
| 10 | + |
| 11 | +- **If you're the top-level agent:** run the full pipeline. Fan out scene subagents and evaluator subagents in parallel. |
| 12 | +- **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. |
| 13 | + |
| 14 | +The assembler, scaffold markers, fragment spec, and gates are the same either way; only the dispatch shape changes. |
| 15 | + |
| 16 | +## Scene Fragment Spec |
| 17 | + |
| 18 | +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. |
| 19 | + |
| 20 | +### Structure |
| 21 | + |
| 22 | +Exactly three sections, in this order, each appearing exactly once: |
| 23 | + |
| 24 | +``` |
| 25 | +<!-- HTML --> |
| 26 | +<div class="s3-heading">...</div> |
| 27 | +... |
| 28 | +
|
| 29 | +<!-- CSS --> |
| 30 | +.s3-heading { color: var(--fg); ... } |
| 31 | +... |
| 32 | +
|
| 33 | +<!-- GSAP --> |
| 34 | +var S3 = 14.3; |
| 35 | +tl.set('#s3-heading', { opacity: 0, y: 30 }, 0); |
| 36 | +tl.to('#s3-heading', { opacity: 1, y: 0, duration: 0.4 }, S3 + 0.5); |
| 37 | +... |
| 38 | +``` |
| 39 | + |
| 40 | +### Required |
| 41 | + |
| 42 | +- **Three markers, one each:** `<!-- HTML -->`, `<!-- CSS -->`, `<!-- GSAP -->` — no duplicates |
| 43 | +- **ID prefix:** All IDs and classes use `s{N}-` prefix (e.g., `#s3-heading`, `.s7-chart`) |
| 44 | +- **GSAP pattern:** `tl.set()` at time 0 for initial state, `tl.to()` at scene time for animation |
| 45 | +- **Scene start var:** Define `var SN = {start_time};` at top of GSAP section, reference it for all tweens |
| 46 | +- **Finite repeats:** All `repeat` values must be explicit numbers, never `-1` or `Infinity` |
| 47 | + |
| 48 | +### Prohibited |
| 49 | + |
| 50 | +- `<!DOCTYPE`, `<html`, `<head`, `<body` — this is a fragment, not a document |
| 51 | +- `<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. |
| 52 | +- `<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. |
| 53 | +- `<script src=` — no external script loading |
| 54 | +- `gsap.timeline(` — the scaffold creates the timeline |
| 55 | +- `window.__timelines` — the scaffold registers it |
| 56 | +- `tl.from(` or `tl.fromTo(` — causes flash-of-default-state (use `tl.set` + `tl.to`) |
| 57 | +- `body {` in CSS — the scaffold owns body styles |
| 58 | +- `.scene {` in CSS — the scaffold owns scene base styles |
| 59 | +- `position`, `top`, `left`, `width`, `height`, `opacity`, or `z-index` on `#sceneN` — the scaffold owns the scene container; only style elements INSIDE the scene |
| 60 | +- Bare class names without `s{N}-` prefix (`.heading`, `.card`, `.tendril`, `.crack`) — causes cross-scene collisions when two scenes use the same name |
| 61 | +- 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. |
| 62 | + |
| 63 | +### Contrast |
| 64 | + |
| 65 | +All text elements must achieve **4.5:1 contrast ratio** (WCAG AA) against their scene background. Check especially: |
| 66 | + |
| 67 | +- HUD labels, stats, and values against dark backgrounds |
| 68 | +- Light-colored text on tinted/colored backgrounds |
| 69 | +- Small text (under 24px) has no large-text exemption |
| 70 | + |
| 71 | +Use the design.md foreground color for text. If an element needs a different color for visual effect, verify contrast manually. |
| 72 | + |
| 73 | +### Assembly contract |
| 74 | + |
| 75 | +If a scene file follows this spec, the assembler can: |
| 76 | + |
| 77 | +1. Split on `<!-- HTML -->`, `<!-- CSS -->`, `<!-- GSAP -->` markers |
| 78 | +2. Inject HTML between the scaffold's `<div id="sceneN" class="scene">` and `</div>` |
| 79 | +3. Append CSS to the scaffold's `<style>` block |
| 80 | +4. Append GSAP into the scaffold's `<script>` after transitions, before `window.__timelines` registration |
| 81 | + |
| 82 | +No parsing, no stripping, no guessing. |
| 83 | + |
| 84 | +## Phase 1: Scaffold + Scene subagents (parallel) |
| 85 | + |
| 86 | +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. |
| 87 | + |
| 88 | +**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. |
| 89 | + |
| 90 | +### Scaffold |
| 91 | + |
| 92 | +Build the HTML skeleton yourself (or in a subagent): |
| 93 | + |
| 94 | +- All scene `<div>` elements with `data-start`, `data-duration`, `data-track-index` |
| 95 | +- The root composition container with `data-composition-id`, `data-width`, `data-height` |
| 96 | +- The GSAP timeline backbone: `gsap.timeline({ paused: true })`, `window.__timelines` registration |
| 97 | +- All transition code between scenes (read [transitions.md](transitions.md)) |
| 98 | +- Global CSS: body reset, scene positioning, font declarations, the `design.md` palette as CSS |
| 99 | +- Leave each scene's inner content empty: `<div id="scene1" class="scene"><!-- SCENE 1 CONTENT --></div>` |
| 100 | +- **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. |
| 101 | +- **Assembly markers** — the scaffold must include these exact comments so the assembler knows where to inject: |
| 102 | + - `/* SCENE STYLES */` inside the `<style>` block — scene CSS goes here |
| 103 | + - `// SCENE TWEENS` inside the `<script>` block, after transitions, before `window.__timelines` registration — scene GSAP goes here |
| 104 | + - `<!-- SCENE N CONTENT -->` inside each empty scene div — scene HTML goes here |
| 105 | + |
| 106 | +### Scene subagents |
| 107 | + |
| 108 | +Dispatch one subagent per scene, running in parallel (concurrently with the scaffold). Each subagent receives: |
| 109 | + |
| 110 | +- The **Scene Fragment Spec** (above) — the subagent must follow this exactly |
| 111 | +- The `design.md` (or its values summarized) |
| 112 | +- The global animation rules from the prompt |
| 113 | +- That scene's specific prompt section only |
| 114 | +- The scene number `N` and start time — used for the `s{N}-` prefix and `var SN = {start_time};` |
| 115 | +- **The persistent-subject choreography block for this scene**, if any — see below |
| 116 | + |
| 117 | +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. |
| 118 | + |
| 119 | +### Persistent-subject choreography contract |
| 120 | + |
| 121 | +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). |
| 122 | + |
| 123 | +When dispatching scene subagents, **the orchestrator must pass each subagent its scene's choreography block** along with these instructions: |
| 124 | + |
| 125 | +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. |
| 126 | +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. |
| 127 | +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. |
| 128 | +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. |
| 129 | +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. |
| 130 | + |
| 131 | +The scaffold's responsibility: |
| 132 | + |
| 133 | +1. Create the subject's DOM in the shared overlay layer outside `.scene` containers. |
| 134 | +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. |
| 135 | +3. Use `xPercent: -50, yPercent: -50` on the subject so position coords are center coords. |
| 136 | +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). |
| 137 | + |
| 138 | +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. |
| 139 | + |
| 140 | +## Phase 2b: Streaming evaluation |
| 141 | + |
| 142 | +As each scene file appears in `.hyperframes/scenes/`, dispatch an evaluator subagent immediately — don't wait for all scenes to finish. The evaluator receives: |
| 143 | + |
| 144 | +- The scene file |
| 145 | +- The **Scene Fragment Spec** (above) |
| 146 | +- That scene's section from the original prompt |
| 147 | +- The `design.md` |
| 148 | + |
| 149 | +### Evaluation order: format first, then content |
| 150 | + |
| 151 | +**Step 1 — Format validation (instant FAIL if any check fails):** |
| 152 | + |
| 153 | +- Exactly 3 markers (`<!-- HTML -->`, `<!-- CSS -->`, `<!-- GSAP -->`), each appearing once |
| 154 | +- 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) |
| 155 | +- All IDs and classes use `s{N}-` prefix |
| 156 | +- No position/top/left/width/height/opacity/z-index on `#sceneN` in CSS |
| 157 | +- All `repeat` values are finite numbers |
| 158 | + |
| 159 | +**Step 2 — Content validation (only if format passes):** |
| 160 | + |
| 161 | +- **Prompt adherence**: Does the scene include the elements the prompt described? List what's present and what's missing. |
| 162 | +- **Design compliance**: Are the design.md colors, fonts, corners, and spacing used? Any invented values? |
| 163 | +- **Contrast**: All text elements meet 4.5:1 against the scene background color. Check HUD labels, stats, and small text especially. |
| 164 | +- **Density**: 15+ animated elements? 3 parallax layers? |
| 165 | + |
| 166 | +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. |
| 167 | + |
| 168 | +Run evaluators concurrently with scene builds — a scene that finishes first gets evaluated first. The pipeline streams, not batches. |
| 169 | + |
| 170 | +## Phase 3: Assembly |
| 171 | + |
| 172 | +Once all scenes have PASS evaluations, run the deterministic assembler — do NOT hand-stitch scenes manually: |
| 173 | + |
| 174 | +```ts |
| 175 | +const { assembleScenes } = await import("@hyperframes/core/assemble"); |
| 176 | +const result = assembleScenes("./project-dir"); |
| 177 | +if (!result.ok) { |
| 178 | + // result.errors has file + message for each issue |
| 179 | +} |
| 180 | +``` |
| 181 | + |
| 182 | +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. |
| 183 | + |
| 184 | +After assembly succeeds: |
| 185 | + |
| 186 | +1. Run `npx hyperframes lint` and fix any structural issues |
| 187 | +2. Run `npx hyperframes validate` if available |
| 188 | +3. **Review the output** — read through the assembled file checking that scene HTML, CSS, and GSAP look correct before serving |
| 189 | + |
| 190 | +## Persistent Elements Across Scenes |
| 191 | + |
| 192 | +When an element persists across scenes (a photograph, logo, product shot), the scaffold owns its DOM and timeline — scene subagents must not animate it. Pre-plan where the element sits in each scene so subagents know what region to avoid. Without this, scene subagents place content in regions the persistent element will later occupy during transitions. |
0 commit comments