pr-to-video

# Code vocabulary — the `code-*` animation blocks

PR videos run on two kinds of moving picture: **code** (the lines that changed) and **behavior** (what the change _does_ at runtime). This file is the vocabulary for both — the `code-*` blocks for code beats, and the **mechanism beat** (an invented animated diagram, or a `flowchart` / `data-chart`) for behavior beats. A video that is _all_ code reads flat; **alternate the two** (story-design plans the rhythm; see "Showing behavior" below).

For code beats the registry ships purpose-built **code animation blocks** that render a diff, a typed-on snippet, a morph, a highlight, a scroll, or a 3D/particle/dissolve reveal — far better than hand-built motion. **Reach for one of these first** for any code beat; fall back to hand-authored composition only when none fits.

- **Step 4 (visual design):** for each `diff` / `before_after` / code beat, name the block in the frame's `scene` (e.g. "the `request()` retry block, ~6 lines, `code-diff`"). One judgment call: which block.
- **Step 5 (frame worker):** install the named block and fill it with the real diff/snippet (below). The block is the frame's centerpiece, composited onto code-editorial's navy **Code Surface**.

## Install + use

Every block installs the same way (confirmed `packages/cli/src/commands/add.ts`):

```bash
npx hyperframes add <block-name>     # writes compositions/<block-name>.html
```

It is a self-contained sub-composition (inlined engine; a paused GSAP timeline the engine seeks per frame). Mount it in the frame as a sub-composition clip:

```html
<div
  data-composition-id="code-diff"
  data-composition-src="compositions/code-diff.html"
  data-start="0"
  data-duration="6"
  data-track-index="1"
  data-width="1920"
  data-height="1080"
></div>
```

**Customize by editing two globals** in the installed HTML's inline `<script>`:

- `window.__TOKENS` — the code content, baked as Shiki tokens: `{ <seq>: { lang, theme, bg, fg, states: [ { code, tokens:[ {key, content, color, fontStyle} ] } ] } }`. Replace `code`/`tokens` with the PR's real snippet(s). `fontStyle` is a bitmask (`&1` italic, `&2` bold). The blocks bake `theme: "github-dark"` independently of the `code-snippet-*` themes below.
- `window.__BLOCK` — selects the effect + timing: 2D `{ id, effect, seq, line?, duration }`; WebGL `{ id, effect, seq, duration, seed }`.

The timeline registers synchronously at `window.__timelines[id]`. All blocks are **1920×1080** and **deterministic / seek-safe** (no CSS transitions, no rAF, seeded randomness — never `Math.random` / `Date.now`).

## The animation blocks

| Block                        | What it does                                                                                                      | Inputs of note                                                                                        | PR beat                                                                                                                     |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **`code-diff`**              | Unified diff inside an editor window: removed lines collapse in red, added lines expand in green, staggered. (6s) | `__TOKENS.diff.states` needs **exactly 2 states** (before, after) — the engine LCS-diffs them.        | The diff hunk (before→after); literal add/remove semantics. **The default PR block.**                                       |
| **`code-morph`**             | One snippet transforms into another — shared tokens glide (FLIP), leavers fade out, enterers fade in. (7s)        | `__TOKENS.morph.states` (2+); reuse the same token `key` across states for a token that should glide. | A refactor / rename / signature change where continuity matters (not add/remove framing).                                   |
| **`code-typing`**            | Per-character typewriter reveal with a gliding caret. (5s)                                                        | single state in `__TOKENS.feature.states[0]`.                                                         | A new function / file **written on screen** ("here's what we added").                                                       |
| **`code-highlight`**         | A blue band sweeps one line; the rest dim. (5s)                                                                   | `__BLOCK.line` = target line, **0-based here**. single state.                                         | "This one line is the change" — spotlight a changed/important line. Quick callout.                                          |
| **`code-scroll`**            | "Camera" scrolls a long file to center a target line, dims the rest. (6s)                                         | `__BLOCK.line` = target, **1-based here**. one long state.                                            | Locating the change in a large file. The only block built for long files.                                                   |
| **`code-3d-extrude`**        | Code on a lit, beveled 3D slab that rotates and settles. (8s, WebGL)                                              | single state; `__BLOCK.seed`. `<canvas id="gl">`.                                                     | A hero / title code moment ("the feature"). Style over density — not for reading a diff.                                    |
| **`code-particle-assemble`** | GPU particles scatter, then fly to the exact glyph pixels and resolve to syntax color. (8s, WebGL)                | single state; `__BLOCK.seed`.                                                                         | A dramatic climax reveal of a key snippet. Flashiest; not for line-by-line reading.                                         |
| **`code-shader-dissolve`**   | Code "compiles into existence" out of seeded noise with a moving dissolve front + edge glow. (7s, WebGL)          | single state; `__BLOCK.seed`.                                                                         | A "compiles / builds / works now" beat, or a polished snippet reveal.                                                       |
| **`code-snippet-flight`**    | Discrete snippets fly in from the side and assemble into a stacked program (block-level FLIP). (6s)               | `__TOKENS.flight.states`.                                                                             | "The pieces assemble" — several functions/modules coming together. (An animation block despite the `code-snippet-` prefix.) |

**Gotchas (call out so the worker doesn't trip):**

- **Fit the cadence to the frame's `data-duration`.** Each block carries its own internal timing — `code-typing` types at a fixed per-character speed, so a snippet that's long relative to a short frame **overruns**: the code never finishes typing within `data-duration`, and the chrome beats around it (an underline, a `+N/−M` count-up) never play. Check **char-count × per-char cadence** (plus the block's settle) against `data-duration`, and tune the timing so the **full block lands inside the frame**. This is the one code-motion knob you MUST set to the frame — you're fitting the _timing_, not redesigning the effect (the typewriter / diff / morph stays the block's).
- `code-diff` and `code-morph` need **≥2 baked states**; every other animation block uses a single state.
- **Line indexing differs:** `code-highlight` is **0-based** (`line: 1` = the 2nd line); `code-scroll` is **1-based**. Don't off-by-one.
- **No caption-safe band.** These are full-bleed 1920×1080 code surfaces with no reserved caption area. When captions are enabled, the frame must keep the code panel clear of the bottom caption keep-out band (composite the block in the top ~83%, or scale/inset it) — the worker owns that, not the block.

## The `code-snippet-*` theme family (standalone, not palettes)

These are **NOT palettes you attach to the animation blocks** — each is its own ready-made ~11–12s composition rendering a full developer UI with baked typing and its own timeline. Use one when you want **ambient realistic context** (a real IDE or terminal on screen), not a focused diff. Install the specific one: `npx hyperframes add code-snippet-<name>`.

- **VS Code workbench (12):** full VS Code window (activity bar, file-tree, tabs, editor with per-char typing, integrated terminal running `pytest`, status bar) in each theme. `dark-plus`, `light-plus`, `dark-modern`, `light-modern`, `dark-2026`, `light-2026`, `monokai`, `solarized-light`, `visual-studio-dark`, `visual-studio-light`, `high-contrast`, `high-contrast-light`. (Each pulls a `background.jpeg` into `assets/`.)
- **Apple Terminal (12):** macOS Terminal.app window typing a shell command per profile. `apple-terminal-` + `basic`, `clear-dark`, `clear-light`, `grass`, `homebrew`, `man-page`, `novel`, `ocean`, `pro`, `red-sands`, `silver-aerogel`, `solid-colors`.

The theme is baked into each block (not chosen at runtime); to use a given look, install that block and edit its `codeLines`. For code-editorial's editorial register, prefer the focused animation blocks on the navy Code Surface; reach for a `code-snippet-*` UI only when "show it in a real editor/terminal" is the point.

## Showing behavior — the mechanism beat (not a `code-*` block)

A `code-*` block shows **the code**. It does not show **what the code does**. The single biggest cause of a flat PR video is a body that is all code surfaces — so for any change with a visible runtime behavior, plan a **`mechanism` beat** that _animates the behavior_ (story-design owns the rhythm; this is the vocabulary).

A mechanism beat is **not** a registry `code-*` block. It is one of:

- an **invented animated diagram** — SVG / HTML / GSAP the frame worker builds from code-editorial's atoms (hairline-ink nodes / edges / lanes on cream, one coral marker on the active element), the build playing out the behavior across the shot; **or**
- a **`flowchart` / `flowchart-vertical`** registry block — a process / pipeline / state flow; **or**
- a **`data-chart`** registry block — a perf / metric comparison (two bars or timelines racing).

`flowchart`, `flowchart-vertical`, and `data-chart` install exactly like a code block (`npx hyperframes add <name>`) and mount as a sub-composition — so when a `mechanism` frame names one in its `scene`, Step 5 pre-installs it alongside the `code-*` blocks. An invented SVG/GSAP diagram needs no install (the worker hand-builds it).

**What to animate, by what the change touches** (the menu story-design plans from):

| The change touches…             | Animate (the behavior)                                                  | Use                    |
| ------------------------------- | ----------------------------------------------------------------------- | ---------------------- |
| Retry / backoff / resilience    | request lifecycle: fire → 500 → wait (delay growing) → retry → 200      | invented SVG/GSAP      |
| Caching / memoization           | two lanes racing: cold (hits DB) vs cached (hits cache)                 | invented SVG/GSAP      |
| Concurrency / parallelism       | a serial lane reshaping into parallel lanes                             | invented / `flowchart` |
| Race / ordering bug             | the broken flow (dropped items, colliding writers), then the fixed flow | invented SVG/GSAP      |
| Performance                     | two timelines / bars racing, the new one finishing first                | `data-chart`           |
| Refactor / migration            | a tangled call-graph untangling; same inputs → same outputs             | `flowchart` / invented |
| New endpoint / pipeline / state | data flowing the new path; a state machine lighting up step by step     | `flowchart-vertical`   |

Unlike a `code-*` block (which owns its own animation), the diagram's motion is **yours** — sequence ≥3 effects into entrance (draw the nodes / lanes) → development (run the flow) → settle (the resolved state + one coral emphasis). Never let it enter then freeze.

## PR beat → block cheat-sheet

| PR moment                                                | Block(s)                                                                                                                                                         |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Diff hunk (before → after)                               | `code-diff`                                                                                                                                                      |
| Refactor / rename / signature change (continuity)        | `code-morph`                                                                                                                                                     |
| Failing → passing test (red → green)                     | `code-morph` or `code-diff` + `code-highlight` on the green line; a `code-snippet-*` VS Code/terminal block for a literal test-runner UI                         |
| New function / file typed on                             | `code-typing`                                                                                                                                                    |
| Spotlight one changed line                               | `code-highlight`                                                                                                                                                 |
| Walk / scroll a long changed file                        | `code-scroll`                                                                                                                                                    |
| Pieces / modules assembling into a feature               | `code-snippet-flight`                                                                                                                                            |
| Hero / title code moment ("the feature")                 | `code-3d-extrude`                                                                                                                                                |
| "Compiles / builds / works now" reveal                   | `code-shader-dissolve`                                                                                                                                           |
| Big dramatic snippet reveal / climax                     | `code-particle-assemble`                                                                                                                                         |
| A benchmark / metric / count-up                          | **Not a `code-*` block** — use code-editorial's `number-lockup` (Number/Impact treatment) or the `data-chart` registry block                                     |
| **What the change DOES at runtime** (behavior, not code) | **Not a `code-*` block** — a `mechanism` beat: an invented SVG/GSAP diagram, or `flowchart` / `flowchart-vertical` / `data-chart`. See "Showing behavior" above. |
| Show the change in a realistic IDE / terminal (ambient)  | a `code-snippet-*` VS Code theme (editor) or Apple Terminal profile (CLI run)                                                                                    |

# Cut catalog — within-frame seams (worker-built)

> **A worker build-recipe (Step 5) — the sibling of `../hyperframes-animation/rules/`, not a second motion doc.** These are within-frame cuts the **frame worker builds INSIDE its own composition** (Z-scale + blur + opacity tweens, or per-word x-staggers, all on the frame's own paused GSAP timeline). They are **not** the between-frame transition: story owns that via `transition_in`, which the harness's injector stamps from a **separate registry vocabulary** (`crossfade` / `blur-crossfade` / `push-slide` / `zoom-through` / `squeeze`) — the catalog names here (**cut-the-curve / inverse-zoom / waterfall**) are **not** valid `transition_in` values. Use this catalog when a frame's shot sequence has an internal seam — a within-scene text/element swap, a **Scene-to-Scene** cut (a `Scene` is a time window WITHIN one frame, **not** a frame-to-frame boundary), or a text-to-text line change — and you want it to read as one continuous move instead of a hard slideshow cut. (`zoom-through` lives in both worlds: a whole-frame wrapper transition in the registry, an element-level Z-cut here — same idea, different scope.)

Four techniques that create depth and continuity:

1. **Zoom-Through** — within-scene text swaps, Z-axis, moving TOWARD the viewer
2. **Inverse Zoom-Through** — Z-axis swaps moving AWAY from the viewer
3. **Cut the Curve** — between-scene transitions on x/y
4. **Waterfall Cut** — word-by-word cut-the-curve with staggered exits and entries

All four are the same underlying principle: **cut at peak velocity, match direction and
speed on both sides of the cut.** The differences are axis, scope, and granularity.

**Choosing which at a seam:** for an UNFINISHED phrase (building one larger idea across
several visually distinct scenes that still approach the same point — multi-line text, a
run of consecutive cards) use **cut-the-curve** / **waterfall**. For a STATE CHANGE (turning
to a NEW part of the video — most often hook → context, between two distinct chapters) use
**zoom-through**, and **inverse zoom-through** for an arrival / payoff beat. Chain these so
the frame's internal seams feel like one camera moving through the content.

---

## Blur Logic (applies to all Z-axis variants)

Blur sells the speed at the cut, but it must scale with the SUBJECT SIZE:

| Subject                                                | Peak blur   | Why                                                                                                                                                                                      |
| ------------------------------------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Text-scale (headline, line, word group)                | **10px**    | At 20px text smears into illegibility — the eye loses the word it was tracking and the cut reads as a glitch, not speed. At 20px letterforms go mushy mid-cut; 10px keeps them readable. |
| Full-frame surface (terminal window, card, screenshot) | **18–20px** | Big surfaces have edges and texture that survive heavy blur; lighter blur on a full-frame move reads as a rendering hiccup instead of motion.                                            |

Both sides of a cut use the SAME peak blur — the value must match at the swap frame.
Apply blur to the WRAPPER, never to individual children.

---

## 1. Zoom-Through (forward)

### The Problem

Text enters, holds, exits. Then next text enters, holds, exits. Each text block is
independent — no depth, no continuity. The video feels like a slideshow.

### The Principle

A velocity-matched cut on the Z-axis. You **never see both texts at the same time.** The
outgoing text scales toward the viewer (accelerating), blur and opacity peak at the cut
point hiding a hard swap, and the incoming text continues scaling up from behind
(decelerating into the focal plane). One continuous forward motion, two different texts.

### The Three Phases

**Phase 1: Exit** — text accelerates forward (toward viewer)

- Scale: `1.0 -> 1.2`, Blur: `0px -> 10px` (text-scale; see Blur Logic), Opacity: `1.0 -> 0.15`
- Scale/blur easing: `power3.in` (steep acceleration)
- Opacity easing: `none` (linear — even dimming, separated from scale)
- Duration: 0.2s

**Phase 2: Hard cut** at peak velocity + peak blur

- Outgoing: `opacity: 0` (instant via `tl.set`)
- Incoming: `opacity: 0.15, scale: 0.75, blur: 10px` (instant via `tl.set`)
- All properties match at the cut: blur, opacity, and scale DIRECTION (both scaling up)

**Phase 3: Entry** — text continues forward (growing into focal plane)

- Scale: `0.75 -> 1.0`, Blur: `10px -> 0px`, Opacity: `0.15 -> 1.0`
- Easing: `expo.out` (steep initial burst matching exit velocity, long settle)
- Duration: 0.5s

### Why Opacity Must Be Separate on Exit

Scale uses `power3.in` but that keeps opacity near 1.0 for most of the tween. Splitting
opacity to its own tween with linear ease makes the dimming even. On entry, all properties
can share `expo.out`.

---

## 2. Inverse Zoom-Through (backward)

The mirror: the camera "pulls back" instead of pushing through. The outgoing element
RECEDES away from the viewer; the incoming element arrives OVERSIZED (as if it had been
just behind the camera) and retracts into the focal plane. Both move in the shrinking
direction — same-direction rule preserved, just reversed.

**When to use over the forward variant:** arrival beats. The incoming element lands with
presence because it comes from larger-than-frame — right for a payoff line ("That changes
today."), a giant reply, or a held end-state. Forward zoom-through reads as _progressing
through_ content; inverse reads as _arriving at_ content.

### The Three Phases

**Phase 1: Exit** — element recedes (away from viewer)

- Scale: `1.0 -> 0.8`, Blur: `0px -> 10px` (text-scale)
- Scale/blur easing: `power3.in`; Opacity: `1.0 -> 0.15` on `none` (separate tween)
- Duration: 0.2s

**Phase 2: Hard cut**

- Outgoing: `opacity: 0` via `tl.set`
- Incoming: `opacity: 0.15, scale: 1.25, blur: 10px` via `tl.set`

**Phase 3: Entry** — incoming retracts into place

- Scale: `1.25 -> 1.0`, Blur: `10px -> 0px`, Opacity: `0.15 -> 1.0`
- Easing: `expo.out`, Duration: 0.5s

---

## 3. Cut the Curve (Scene Transitions)

### The Principle

Use cut-the-curve for **all scene-to-scene transitions** on x and y axes. The outgoing
scene's hero element accelerates in one direction, the cut lands mid-motion, and the
incoming scene's hero element continues moving in the **same direction** and decelerates.
Nothing exits fully off-screen and nothing enters from fully off-screen — **speed plus
opacity fading trick the eye**; the partial moves are enough.

### Same Path, Same Direction

If Scene A's hero slides left, Scene B's hero enters from the right and continues sliding
left. Both move leftward. One continuous motion.

| Direction | Scene A exit   | Scene B entry start | Scene B entry end |
| --------- | -------------- | ------------------- | ----------------- |
| Leftward  | `x: 0 -> -230` | `x: +230`           | `x: 0`            |
| Rightward | `x: 0 -> +230` | `x: -230`           | `x: 0`            |
| Upward    | `y: 0 -> -230` | `y: +230`           | `y: 0`            |
| Downward  | `y: 0 -> +230` | `y: -230`           | `y: 0`            |

### Velocity matching via mirrored eases

The cleanest match: exit `power4.in` and entry `power4.out` with the SAME distance and
duration — mathematically the two halves of one `power4.inOut` composite, so the entering
element picks up at exactly the 50% point of the notional path at identical velocity
(e.g. 230px / 0.3s ≈ 3,070 px/s at the cut on both sides).

The fade trick: the exit's opacity completes at ~25–30% of its travel (fade duration
≈ 0.18–0.3s vs motion 0.3–0.34s) — the element vanishes while still visibly accelerating,
and nothing has to reach the frame edge. Entry fades IN fast from ~0.35 under its
deceleration. Time the LAST fading element to die right at the hard cut — gaps where
nothing is moving read as awkward dead air.

### Rules

- Use cut-the-curve for all scene transitions — it's the default, not an accent
- Same direction on both sides; mirrored `.in`/`.out` eases, same distance + duration
- Exit duration short (0.2–0.4s), entry duration >= exit duration
- Partial travel + fade, never full off-screen moves

---

## 4. Waterfall Cut (word-by-word cut-the-curve)

Cut-the-curve at WORD granularity — the strongest version of the leftward cut for
text-to-text seams. Each word of the outgoing line ramps out on its own pronounced curve;
each word of the incoming line cascades in mid-flight. The stagger turns the cut into a
wave the eye rides across the seam.

### Exit (per word)

- Motion: `x: 0 -> -230` over 0.34s on **power4.in** — a much more pronounced ramp than
  the usual power2: the word barely creeps, then RIPS
- Fade: `opacity -> 0` over 0.18s (separate tween, `power1.in`) — completes when the word
  is only ~25–30% into its travel
- Stagger: reading order, ~0.022s per word, timed so the LAST word finishes fading right
  at the hard cut

### Entry (per word)

- `fromTo x: +230 -> 0, opacity: 0.35 -> 1` over 0.3s on **power4.out** — the mirrored
  back half of the composite; every word ignites already moving at matched velocity
- Waterfall stagger with SHRINKING gaps (start 0.05s, multiply by ~0.84 per word) so the
  cascade accelerates across the line — the cascade should speed up word over word, not run
  at a flat per-word delay
- Pre-set all words to `x: +230, opacity: 0` at build time — `immediateRender: false`
  alone leaves un-started words sitting visible at rest during the stagger window

### Whole-line variant

A single-line beat (e.g. a big intro line) exits as one group with the same pronounced
ramp, but stretch its fade to ~0.3s ending ~0.02s before the cut — a lone element that
fades early leaves dead air that a word cascade would have covered.

---

## Choosing a Variant

|                | Zoom-Through                | Inverse Zoom                | Cut the Curve     | Waterfall Cut             |
| -------------- | --------------------------- | --------------------------- | ----------------- | ------------------------- |
| Scope          | Within-scene text swap      | Arrival/payoff beat         | Between scenes    | Text-to-text seam         |
| Axis           | Z, toward viewer            | Z, away from viewer         | X / Y             | X, per-word               |
| Peak blur      | 10px text / 20px full-frame | 10px text / 20px full-frame | none required     | none (fade does the work) |
| Opacity at cut | 0.15                        | 0.15                        | exit faded by cut | last word dies at cut     |
| Feel           | progressing through         | arriving at                 | carried sideways  | a wave across the seam    |

---

## Anti-Patterns

| Don't                                    | Why                                         | Instead                                                |
| ---------------------------------------- | ------------------------------------------- | ------------------------------------------------------ |
| Two texts visible during a zoom-through  | Overlapping text breaks the Z-axis illusion | Hard cut at blur peak, one text at a time              |
| 20px blur on text-scale subjects         | Letterforms smear; reads as a glitch        | 10px for text, 18–20px only full-frame                 |
| Elements on different paths across a cut | Eye tracks one direction, cut goes another  | Same property, same direction                          |
| Mismatched blur/opacity at the swap      | Visible flash or brightness jump            | Identical values at the cut frame                      |
| Gentle easing on entry (`power2.out`)    | Entry velocity feels slower than exit       | Mirror the exit: `power4.out` / `expo.out`             |
| Full off-screen exits / entries          | Wastes time and breaks the speed illusion   | Partial travel + early fade                            |
| Lone element fading long before its cut  | Dead air at the seam                        | Fade ends ~0.02s before the cut, or use a word cascade |
| Zoom-through on body text                | Small text at 0.75 scale is unreadable      | Only headlines and short phrases                       |
| Scene cuts without cut-the-curve         | Static cuts feel like a slideshow           | Cut-the-curve is the default                           |

# Motion language — the move vocabulary + the motion doctrine + the seek-safe core

> The motion layer for **Step 4 (Visual design)**. When you write a frame's **time-coded shot sequence**, you name each scene's move **inline from the vocabulary below** — a named palette of the moves the golden corpus actually uses. Each move carries the **backing rule id** in this skill's local `../hyperframes-animation/rules/`; cite that id so the move resolves to a real recipe when a **frame worker** implements it in Step 5 (the worker reads the rule body in `../hyperframes-animation/rules/<id>.md` — it reproduces the move, it does not guess from the name). You name motion by **role / move name**, never by raw GSAP curve, ms, or stagger formula — the worker maps the curve. Between-frame **transitions are not yours**: story names `transition_in`, the harness injects it; that injected transition **is** the frame's exit. For cuts a worker builds INSIDE a frame (within-scene swaps, scene-to-scene seams), see the catalog in `cut-catalog.md`.

A good code-change explainer feels like one continuous film — one camera, one motion feel, **smooth and timed to the voiceover** — not a pile of slides that animate once and freeze. In a PR explainer the development often _is_ the reveal: the diff hunk typing in, the before→after morph, the impact stat landing. The doctrine in Part 2 is load-bearing: when in doubt, do what it says.

---

# Part 1 — the move vocabulary

Reach into this palette when naming a scene's motion. Pick the move that matches the beat, name it in the shot sequence, and cite the rule id after `→`. The blueprints (`../hyperframes-animation/blueprints/`) name these same moves in their `rule mapping`; you're drawing from one shared palette. Compose 2–4 across a shot's scenes (entrance → sequential reveal → settle), not all at once.

## Kinetic type

- **hard-cut / flash word-swap** — a word or line replaces the previous one on an instant cut (no fade/roll); the swap itself is the beat. → `discrete-text-sequence`
- **in-place token cycle** — a fixed line holds and only its variable slot changes, token → token → token. → `discrete-text-sequence`
- **per-word staggered reveal** — a phrase assembles word-by-word (or chunk-by-chunk), each landing on its own beat. → `dynamic-content-sequencing`
- **kinetic beat-slam** — short phrases slam in on a shared percussive beat array, each with a distinct entrance, resolving on a locked finale; the recipe for "punchy / rhythmic" taglines. → `kinetic-beat-slam`

## Typewriter

- **type-on with caret** — text types in character-by-character behind a blinking caret. → `discrete-text-sequence` (+ `context-sensitive-cursor` for the caret blink / color)
- **backspace-and-retype** — the line types, deletes the last word(s), and retypes a new one (typo-correction, reframe). → `discrete-text-sequence` (+ `context-sensitive-cursor`)

## Count-up / data

- **value-scaled counter** — a number counts up and its font size grows with the value, so the climb itself escalates. → `counting-dynamic-scale`
- **bars / progress / star wipe** — a number paired with a graphic that fills: bar-height stagger, a progress bar / ring filling, a fractional star-rating wipe. → `stat-bars-and-fills`

## Reveal / decode

- **3D char flip-decode** — characters flip in 3D and resolve from scrambled glyphs to the real text (decryption feel). → `hacker-flip-3d`
- **SVG self-draw** — an outline / icon / ring draws itself stroke-by-stroke. → `svg-path-draw`

## Camera

- **push / focus / drift** — a sequential camera move on the frame root (pull-back → focus → push) plus continuous micro-drift; the cinematic baseline. → `multi-phase-camera`
- **zoom-to-target** — zoom into a non-centered element (scale + counter-translate to keep it framed). → `coordinate-target-zoom`
- **pan / focus-lock** — a virtual camera transforming one `.world` wrapper to pan / zoom / lock onto a region. → `viewport-change`
- **camera-cursor-tracking** — the viewport locks to a moving focal point (a typing cursor), static framing then focal-locked tracking. → `camera-cursor-tracking`

## Layout motion

- **cluster→outward expansion** — elements start clustered at center and expand outward to their final positions in lockstep. → `center-outward-expansion`
- **orbit** — elements flip in from 3D space and settle into a continuous elliptical orbit (entry flips in-place at the orbital position). → `orbit-3d-entry`
- **split-tilt cards** — two cards side-by-side with opposing rotationY tilts, entering from their respective sides (comparison / before-after). → `split-tilt-cards`
- **logo/avatar ring + connectors** — avatars or logos on an elliptical ring with SVG connection lines to a center point, staggered entry. → `avatar-cloud-network`

## Surface / UI

- **3D page-scroll reveal** — a full webpage as a tilted 3D card whose internal content scrolls to reveal specific sections. → `3d-page-scroll`
- **cursor click + ripple** — a cursor moves to a target, depresses with it on click, and emits an expanding ripple. → `cursor-click-ripple`
- **button press** — a tactile press: compression then spring recovery, optional release burst / glow. → `press-release-spring` (or `physics-press-reaction` for a click that compresses cursor + target together)
- **keyword glow** — keywords light up with glow + scale + color on an attack-decay-rest envelope, synced to a word rail. → `asr-keyword-glow`

## Morph / handoff

- **scale-swap** — two elements at the same screen center hand off: the outgoing cluster shrinks + fades as the incoming one arrives. → `scale-swap-transition`
- **card morph-anchor** — a container morphs apparent size + corner radius + surface between two shots, then fades to reveal the real target beneath (HyperFrames uses uniform `scale`, not `width`/`height`). → `card-morph-anchor`

## Seam cuts (worker-built, inside a frame)

The velocity-matched cuts a worker authors between a frame's own Scenes. Name the seam in the shot sequence; the recipe is in the catalog, not a single `../hyperframes-animation/rules/` id.

- **zoom-through / inverse zoom-through** — a within-scene swap on the Z-axis; forward reads "progressing through", inverse reads "arriving at" (payoff). → `cut-catalog.md`
- **cut-the-curve** — a scene-to-scene cut where both sides move the same direction at matched velocity. → `cut-catalog.md`
- **waterfall cut** — cut-the-curve at word granularity, a wave across a text-to-text seam. → `cut-catalog.md`

## Emphasis / marker

- **highlight / circle / burst / scribble** — a marker-drawn emphasis on a word or element: yellow highlight sweep, hand-drawn circle, radiating burst, scribble, or rough sketch-outline. → `css-marker-patterns`

## Aliveness during a hold (use sparingly — see Part 2)

- **subtle jitter** — the sanctioned way to keep a settled frame alive: a small, low-amplitude positional/scale jitter on the held element. The motion-graphics trick that reads "alive" without reading "weak." → `sine-wave-loop` (low-amplitude register)
- **live SVG internals** — internal SVG parts move so an icon feels alive (rotating hands, oscillating blades, pulsing dots, dash-flow); fine because it's the subject doing something, not a card breathing. → `svg-icon-enrichment`
- **finite bounded ambient** — a single bounded breathe/drift on ONE held hero, only when genuinely needed; de-emphasized — prefer sequential reveal or jitter first. → `sine-wave-loop`

## The added moves — now backed by local rules

Five moves the golden corpus needs were added to this skill's `../hyperframes-animation/rules/`, rounding out the vocabulary above:

- **depth-of-field / selective-blur** — blur the off-focus subset to spotlight the focal element → `depth-of-field-blur`
- **motion-blur streak** — directional velocity blur on a fast fly-in / camera push-through → `motion-blur-streak`
- **3D depth scatter-assemble** — glyphs/elements scatter into a tumbling 3D cloud, then reassemble → `depth-scatter-assemble`
- **spring-pop entrance** — the canonical entrance pop; default to a smooth long-tail settle, overshoot only when explicitly playful → `spring-pop-entrance`
- **ambient glow / bloom** — un-triggered soft glow blooming behind a static hero → `ambient-glow-bloom`

---

# Part 2 — the motion doctrine (load-bearing)

These four rules are the difference between a clip that reads as a serious code-change explainer and one that reads as an agent-made PowerPoint. Follow them as written.

## 1. Smooth beats bouncy — `power3` is the default

Elements should use **long-tail decel curves that let them settle smoothly. `power3` is enough in most cases.** No bouncy, no overshoot, no `back.out` / `bounce.out` / `elastic.out` as a default.

Bouncy is the **#1 instant turn-off** in user-made Remotion / HyperFrames videos, and the agent almost never gets it right — it thinks bouncy adds emphasis, but it buys that emphasis at the cost of cleanliness. The serious motion-design shops feel the same. **Smooth always wins.** Overshoot is demoted to a **rare, explicitly-playful exception** (a consumer/fun logo slam, a deliberate bell-hit) — never the house style. Name the intent as a long-tail settle; the worker maps `power3` (or `expo.out` on a fast arrival). See `../hyperframes-animation/rules/spring-pop-entrance.md` — it now leads with the smooth settle. (The exact form of that settle is a critically-damped spring; the worker has a baked, seek-safe `springEase` — ζ=1 — in `../hyperframes-animation/adapters/gsap-easing-and-stagger.md` → Spring Eases for when the settle is the hero. Real physics, same doctrine — not a license for bounce.)

## 2. Sequential reveal in the back ~50%, timed to the voiceover

This is the anti-PowerPoint mechanism — sharper than "put development in the middle."

- **Don't dump everything on screen in the first ~25%** of the scene. Rushing all content in up front is exactly what forces the slideshow feel.
- **Reveal each piece — a line, a card, even an h1 — when the voiceover mentions it**, sequencing reveals across the **later ~50%** of the scene. Same amount of agent work, but the cut becomes coherent and gains rhythm.
- **Less is more.** Fewer things on screen, each arriving on its VO beat, beats a full canvas that animated once and froze.

Practically: a frame's shot sequence front-loads almost nothing — the entrance carries only what the VO is saying at t=0, and the rest of the elements wait in the timeline for their spoken cue. A reveal maps onto a development-class move from Part 1 (`per-word staggered reveal`, `cluster→outward expansion`, a `count-up`, an `asr-keyword-glow` synced to the word rail).

## 3. No lazy breathing, no bad pan/push — "no motion over bad motion"

The agent's two reflexive ways to fake "aliveness" both read cheap:

- **No lazy breathing.** Scaling cards/text up and down in a circular loop to look "alive" is the cheap tell. Don't reach for it.
- **No bad slow pan / push in the back half.** A slow pan or push on elements in the later ~50% of a scene **disrupts the viewer's sightline and causes eye discomfort** — it actively makes the frame worse, not better.

The fix for both is the same: **stagger element reveals in time with the script** (rule 2). And the governing principle: **"I'd rather have NO motion than BAD motion."** A held, still frame is better than a frame kept "alive" by breathing or a drifting camera. The **only sanctioned aliveness** during a hold is **subtle jitter** — a small low-amplitude jitter that keeps a frame from feeling dead without looking weak (it's in Code editorial videos now). Everything else holds.

## 4. Internal seams are velocity-matched cuts

When a frame has an internal seam — a within-scene swap, a Scene-to-Scene cut, a text-to-text line change — make it a **velocity-matched cut**, not a hard slideshow cut: cut at peak velocity, match direction and speed on both sides. The catalog (the four techniques, the blur logic, and which to use when) is `cut-catalog.md`; the moves are listed under **Seam cuts** in Part 1.

## One-line summary

Smooth long-tail (`power3`) over bouncy; reveal sequentially in the back ~50% timed to the VO (not dumped in the first 25%); no lazy breathing and no bad slow pan/push — prefer stillness, with subtle jitter as the only aliveness; cut at peak velocity with matched direction/speed (→ `cut-catalog.md`).

---

# Part 3 — the seek-safe core (hard rules)

The frame is a **paused GSAP timeline seeked frame-by-frame**, so some "continuous" intents from a real-time engine can't render — don't name them. These are non-negotiable regardless of doctrine.

- **No infinite / forever motion** — "particles loop endlessly," "logo rotates forever," "marquee on repeat." Any aliveness (the subtle jitter, a live SVG internal, a needed bounded ambient) is a **finite tween over the hold**, never `repeat` / `yoyo`.
- **No randomness or wall-clock** — no `Math.random` particle fields, no `Date.now` drift. Every render must be identical; name deterministic motion only (stagger and any variation derive from the element index).
- **Entrances use `fromTo`** — state the from-state explicitly so a seek to `t=0` lands the element correctly; never rely on a CSS-hidden start (it renders visible before the tween claims it, and flickers under seek).
- **No CSS `transition` / `@keyframes` for motion** — CSS animation runs on the browser clock, independent of the HF seek clock; it desyncs and flickers. Drive all motion inside the paused GSAP timeline.
- **Entrance + sequential reveal only — no mid-video exit.** The frame unmounts via the harness transition; that injected `transition_in` **is** the exit. Exit motion belongs only to the final frame. (Worker-built seam cuts in `cut-catalog.md` are within-frame, not the frame's exit.)

## Forbidden — the failure modes

**Slideshow (the primary failure):** everything dumped on screen in the first ~25%; content enters then freezes; nothing revealed on its VO cue. Fix with rule 2 (sequential reveal timed to the VO).

**Cheap aliveness:** circular breathing as "life"; a slow pan/push in the back half disrupting the eye; many elements floating independently as "motion." Fix with rule 3 (stillness + subtle jitter only).

**Bouncy:** `back.out` / `bounce.out` / `elastic.out` as the default entrance; hand-keyed overshoot. Fix with rule 1 (`power3` long-tail; overshoot only when explicitly playful).

**Always:** no `repeat` / `yoyo`; no `Math.random` / `Date.now`; no all-elements-entering-simultaneously (sequence or stagger).

## Naming motion in a shot — example

> Scene 1 (0.0–1.0s): solid field; hero headline enters via **per-word staggered reveal** (`dynamic-content-sequencing`) on a smooth long-tail settle (`power3`); slow **push** on the root (`multi-phase-camera`) holds steady — no back-half re-push.
> Scene 2 (1.0–3.0s): as the VO names each changed file, five file chips reveal **sequentially** via **cluster→outward expansion** (`center-outward-expansion`), then a **value-scaled counter** (`counting-dynamic-scale`) ticks the +/− line total up beneath them — the back-half reveal, timed to the script, not dumped at t=0.
> Scene 3 (3.0–4.2s): hold on the result; **keyword glow** (`asr-keyword-glow`) lands on the payoff word as the VO says it; settles and holds still — at most **subtle jitter** (`sine-wave-loop`, low amplitude) keeps it alive; no breathing, no drift.

Name the move + its rule id (or `cut-catalog.md` for a seam cut) per scene; let the worker pick curves, ms, and stagger — defaulting to `power3`.

# Story design — PR → narrative

Use this reference in Step 3 to write `STORYBOARD.md` and `SCRIPT.md` for a **PR-to-video** — a code change (the diff, commits, files, +/− stats, and the people behind it) turned into an explainer. There is **no website and no captured assets**; the PR was ingested into `capture/extracted/` in Step 1.

This file defines the story: what the video explains, in what order, and why each frame exists. It does not define layout, effects, animation, or file syntax. For exact storyboard syntax follow `../hyperframes-core/references/storyboard-format.md` and `../hyperframes-core/references/script-format.md`.

## Read first

1. `hyperframes.json` — locked brief: angle (archetype), audience, length, aspect, language.
2. `frame.md` — tone, type, design system (the shipped preset is **code-editorial**: warm editorial, a serif that thinks, scarce coral, a navy code surface).
3. `capture/extracted/visible-text.txt` — the assembled PR brief: title, meta (`base ← head · +N/−M across F files`), people, body, commits, changed files, and a budget-bounded set of **representative diff hunks**. This is your source of **information**.
4. `capture/diff.patch` — the full unified diff, for deeper hunk selection than the brief's excerpt.
5. `capture/extracted/people.json` — contributors (author / committers / reviewers / commenters), bot-filtered, each with an avatar in `assets/<login>.png` (for the credits close).

## Output

- `STORYBOARD.md` — the explanation plan, one frame per beat.
- `SCRIPT.md` — the locked narration, only for spoken frames.

Every frame includes the required storyboard-format fields plus the narrative metadata below.

## Core rule

A diff is a list of edits. A video is a guided act of understanding.

Do **not** narrate the diff file-by-file or read the PR description aloud — that is the single most common failure. **Explain the change** — and where the change has a runtime behavior, **show that behavior in motion** (a `mechanism` beat — see "Show the behavior" below), don't just display the lines that changed. Reorder, merge, omit, compress: surface the one change that matters and drop the incidental churn (lockfile bumps, formatting, generated files) unless it _is_ the story. Scene order comes from narrative design, not from the diff's file order or the commit list.

**Value before evidence** (`../hyperframes-creative/references/story-spine.md`): the viewer-facing payoff — what the change unlocks, fixes, or speeds up — lands by the second beat; the diff and the mechanism are the **evidence** for that claim, never the opening. Implementation is the footnote of the story, not the spine.

Default to a **plain, technical, unhurried developer voice** — accurate, specific, no hype, no marketing gloss. You are explaining a real change to engineers; respect their time and intelligence. `frame.md` (code-editorial) tunes the voice toward considered and literary; it does not change the structure.

## PR archetypes

Choose **one** archetype (or name a compound). Each is a complete path through understanding a change — do not splice phases from different archetypes.

- **Changelog** — "here's what shipped." Hook naming the headline → **2–4 roughly co-equal change items** → ship/wrap. Best for release PRs, multi-change PRs, "what's new in vN." Items are parallel → `cut` / `push-slide` between them. Rule-of-three is strongest when changes compress. An item with a visible behavior can be a `mechanism` mini-demo instead of a bare `diff`.
- **Feature-reveal** — "here's what you can do now." Hook (the outcome the feature unlocks, in user language) → the payoff made concrete (`impact` — what now works) → name it (`change`) → the new code typing on (`diff`) → **animate what it does (`mechanism`)** → close (a callback to the promise). Best for a PR that adds **one notable feature**. The promise leads and the code proves it: `diff` and `mechanism` are the evidence for the opening claim — the viewer should already care before the first line of code appears.
- **Fix-explainer** — "this was broken; here's the fix." Symptom/bug (`problem`) → **animate the broken behavior (`mechanism`)** → the fix as a before→after (`diff`) → **the behavior now working (`mechanism`)** or the result (`impact`). Best for bugfix PRs. Seeing the bug _happen_ and then _not_ happen is the turn — a stronger shape (tension → turn → relief) than the diff alone.
- **Refactor-walkthrough** — "same behavior, better shape." Hook (the smell / the why) → old shape vs new shape (`before_after`) → **the structure untangling, same inputs → same outputs (`mechanism`)** → payoff (`evidence` — lines removed, perf delta, files touched). Best for refactors, perf, cleanups, migrations. A `mechanism` animation _proves_ "same behavior, better shape" far better than asserting it.

**Choosing:** one notable new capability → feature-reveal; a bug fix → fix-explainer; a behavior-preserving cleanup/perf/migration → refactor-walkthrough; many co-equal changes / a release → changelog. Tie-breakers: a feature that also fixes a bug → feature-reveal with the fix as one body beat; a fix that needed a small refactor → fix-explainer (the fix is the headline). **Compound:** write `arc` as `"<outer> with <inner>"`, e.g. `"feature-reveal with changelog"`. Outer = the macro arc the viewer rides; inner = the body rhythm.

## PR-native frame types

Set each frame's `type` to one of these PR-native values. (The storyboard parser keeps `type` verbatim; it is a narrative + pacing label, not a hard enum.) Each maps to a code-editorial frame treatment and a typical visual — so the type, the design, and the visual stay aligned end to end. Note `mechanism` is the **show-the-behavior** beat (an invented animated diagram), distinct from `diff` (show the code).

| `type`         | The frame's job                                                                                                             | code-editorial treatment (frame.md)                                | typical visual (see code-vocabulary.md)                                                 |
| -------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| `hook`         | The high-leverage opening 3–5s                                                                                              | Cover                                                              | — (or `code-3d-extrude` for a hero code moment)                                         |
| `problem`      | The bug / smell / pain / why-care the PR resolves                                                                           | Statement or Pull-quote                                            | `code-highlight` (spotlight the offending line)                                         |
| `change`       | Name the change / the feature / the PR itself                                                                               | Statement or Cover                                                 | —                                                                                       |
| `diff`         | The change body — a before→after, a hunk, new code typed on                                                                 | **Code Surface** (navy)                                            | `code-diff` / `code-morph` / `code-typing`                                              |
| `before_after` | Explicit old-shape vs new-shape comparison (refactor/fix)                                                                   | Code Surface (split / morph)                                       | `code-morph` / `code-diff`                                                              |
| `mechanism`    | **Show what the change DOES at runtime** — the request retrying, the cache filling, serial→parallel, the race resolved      | invented diagram on cream (hairline ink + one coral active marker) | **invented SVG/GSAP**; `flowchart` / `flowchart-vertical` / `data-chart` where they fit |
| `impact`       | The payoff — what now works, what's now possible; opens the video as the promise (feature-reveal) or lands it as the result | Number / Impact                                                    | `number-lockup` (no code block needed)                                                  |
| `evidence`     | Concrete grounding — `+N/−M`, a passing test, a benchmark                                                                   | Number / Impact                                                    | `code-diff` red→green / `number-lockup`                                                 |
| `credits`      | Shipped-by close — the humans behind the change                                                                             | Closing                                                            | — (avatar row from `assets/<login>.png`)                                                |
| `cta`          | The closing ask — pull it, upgrade, read the PR                                                                             | Closing                                                            | — (coral-callout)                                                                       |

The body of a PR video **alternates `diff` (show the code that changed) with `mechanism` (show what it does at runtime)**, landing on `impact` / `evidence` (the result). A body that is all `diff` reads as code show-and-tell — the `mechanism` beat is what makes the change _legible_ and is the usual cure for a video that feels flat. Every PR has a change, so at least one `diff` (or `change`) frame always exists; most PRs also have a behavior worth animating.

## Hook strategy

The hook is the highest-leverage 3–5 seconds. Pick one:

| Strategy               | When                                | Example                                                                |
| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------- |
| Shocking statistic     | The change quantifies the stakes    | "This PR deletes 1,200 lines." / "40% faster cold starts."             |
| Counterintuitive claim | The change contradicts intuition    | "We made the client slower — and that fixed it."                       |
| Pain validation        | The audience already feels the bug  | "Every deploy, the same flaky timeout."                                |
| Concept announcement   | The change has a name worth landing | "Meet retry-with-backoff — flaky networks stop killing your requests." |
| Before/after teaser    | The diff is the whole story         | "One line threw. Now it recovers."                                     |
| Stakes / consequence   | The "why care now" is a real cost   | "This crash hit every user on a flaky network."                        |
| Direct address         | The audience is clearly defined     | "If you've ever waited on a 5-minute CI run…"                          |

Do not open with a generic repo/company description. Whatever the strategy, the hook speaks the **viewer's outcome language** (story-spine rule 1) — never file / function / identifier names; numbers only when they carry stakes ("40% faster"), not inventory ("23 files changed").

## Clarity / rhetoric technique catalog

Each frame's `persuasion` is a **named** technique, not "explain the change." Combine when several are active:

- **Make-concrete** — Worked example (one real request/input) · Analogy (backoff as "knock, wait longer, knock again") · Concretization (abstract change → one tangible code line)
- **Reveal-in-order** — Progressive disclosure (the diff one line at a time) · Build-up (the simple call, then the edge case) · Signposting ("before… after…")
- **Contrast** — Before/after diff · Old shape vs new shape · The bug vs the fix · Two approaches compared
- **Structure** — Rule of three (three changes) · Numbered enumeration · Question→answer · Frame-then-fill (state the shape, then the code)
- **Evidence** — `+N/−M` stat · Passing test / green check · Benchmark / perf delta · Causal chain (request → 5xx → retry → success)
- **Memory & landing** — Callback (return to the hook's bug) · Distillation (the change in one line) · Generalization (this fix → the principle)

## Emotional beats

`beat` is one word or a short compound (e.g. "Recognition and relief"). Avoid generic "positive". A PR video rides a comprehension arc:

- **Negative valley** — _open the gap_ (`hook`/`problem`): curiosity · frustration · recognition · concern · "ugh, that bug"
- **Pivot** — _orient_ (`change`): clarity · orientation · anticipation · focus
- **Build** — _build understanding_ (`diff`/`before_after`/`impact`/`evidence`): comprehension · "aha" · confidence · momentum · conviction · relief (for a fix)
- **Resolution** — _land_ (`credits`/`cta`): satisfaction · resolve · "ship it" · inevitability

Compound beats are often strongest: "Recognition _and_ relief" (a fix), "Curiosity _and_ confidence" (a feature).

## The body is a sequence

A PR video's core is **2–5 body frames**, each advancing one change / one before→after / one item, building cumulatively. **Alternate `diff` (the code) with `mechanism` (the behavior)** — don't stack code surfaces:

- **changelog:** a `diff` (or a `mechanism` mini-demo) per change item; parallel → default `cut` / `push-slide`.
- **feature-reveal:** `impact` (the promise, concrete) → `change` (name it) → `diff` (the code, often typing/morphing on) → `mechanism` (animate it working) → a closing callback to the promise.
- **fix-explainer:** `problem` (symptom) → `mechanism` (the bug happening) → `diff` (cause + fix, before→after) → `impact` (result, or a `mechanism` of it working).
- **refactor-walkthrough:** `before_after` structure → `mechanism` (the structure untangling, behavior preserved) → an `evidence` numbers beat.

## Continuity across frames

This framework builds **one frame per worker** — there is no multi-frame "continue run." A sequence reads as one continuous shot through two storyboard-level levers, both yours:

1. **A consistent stage** — consecutive body frames share one composition idea (the same navy code window filling in, the same before|after split, the same counter advancing), stated in each frame's `scene` so Step 4 and the workers keep the stage stable.
2. **A consistent transition** — pick one seam type for a run (`crossfade` for a soft code reveal, `push-slide` for the next change item) and repeat it.

When a single element genuinely _transforms_ between two ideas (the failing test flips green, the old function becomes the new one), keep it **within one frame** as a development beat (entrance → transform → settle) — the worker owns that motion (a `code-diff` or `code-morph` block). Note the intent in `scene` / narrative; Step 4 wraps it in a time-coded shot sequence around the block (a `code-diff` / `code-morph`).

## Transitions

Use only registry transition names in `transition_in`:

`cut | crossfade | blur-crossfade | push-slide LEFT | push-slide RIGHT | push-slide UP | push-slide DOWN | zoom-through | squeeze`

Pick 2–3 for the whole video and repeat. Frame 1 is `cut` (no previous frame). Match the seam to the narrative: ordered change items → a consistent `push-slide`; a soft reveal / into-the-cause → `crossfade` / `blur-crossfade`; zooming into a code line or pulling back to the file tree → `zoom-through`; a clean new change item → `cut`.

## The diff is the centerpiece

Code beats live on the **navy code surface** (code-editorial's Code Surface treatment) — but the body is **not** all code (pair them with `mechanism` beats, next section). Plan the code beats deliberately:

- **Feature 2–4 real diff hunks**, named in each frame's `scene` — each a small, legible snippet (~4–12 lines), **never a whole file**. Pull them from `capture/diff.patch` / the brief's "Representative diff."
- Name **which code animation block** the frame wants in `scene` (the Step-4 visual phase and the worker read it). See `code-vocabulary.md` for the full map; the short version: before→after = `code-diff`; refactor/rename continuity = `code-morph`; new code written on = `code-typing`; spotlight one line = `code-highlight`; walk a long file = `code-scroll`; a hero reveal = `code-3d-extrude` / `code-particle-assemble`.
- Numbers (`+1,204 / −318`, files touched, perf delta) belong on an `impact` / `evidence` frame as a `number-lockup`, **not** read aloud in narration.

## Show the behavior — the mechanism beat (not just the diff)

A diff shows **what changed in the code**. It does **not** show **what the change does** — and "what it does" is usually the more memorable, more explanatory beat. The single biggest reason a PR video feels flat is that every body frame is a code surface or a number: it _tells_ (here are the lines, here is the stat) but never _shows_ (here is the request actually recovering).

A **`mechanism` frame animates the runtime behavior** the PR changes — built as an **invented animated diagram** (SVG / HTML / GSAP on code-editorial's cream ground: hairline-ink nodes / edges / lanes, one coral marker on the active or changed element), where **the build _is_ the teaching** — each part appears on beat, the flow plays out across the shot. It is **not** a code block and **not** a headline. Reach for the `flowchart` / `flowchart-vertical` / `data-chart` registry blocks where they fit; otherwise invent it (visual-design.md's diagram / abstract-graphics register).

Plan **at least one `mechanism` beat** for any PR with a visible runtime behavior (most feature and fix PRs have one). What to animate, by what the change touches:

| The change touches…             | Animate (the behavior, not the code)                                                               |
| ------------------------------- | -------------------------------------------------------------------------------------------------- |
| Retry / backoff / resilience    | a request lifecycle: fire → 500 → wait (delay growing) → retry → 200                               |
| Caching / memoization           | two lanes racing: cold (slow, hits the DB) vs cached (fast, hits the cache)                        |
| Concurrency / parallelism       | a serial single lane reshaping into parallel lanes                                                 |
| Race / ordering bug             | the broken behavior first (items dropped, two writers colliding), then the fixed flow              |
| Performance                     | two timelines / bars racing, the new one finishing first (a `data-chart` fits)                     |
| Refactor / migration            | a tangled call-graph untangling into a clean one; same inputs → same outputs                       |
| New endpoint / pipeline / state | data flowing through the new path; a state machine lighting up step by step (`flowchart-vertical`) |

Name the mechanism in the frame's `scene` ("animate the request retrying: fire → 500 → backoff → 200, invented SVG flow") so Step 4 and the worker build it. The `diff` frame and the `mechanism` frame are **complementary** — the diff is the proof in code, the mechanism is the proof in motion; alternate them rather than stacking code surfaces.

## The close: a credits / shipped-by scene

A PR is shipped by people, and every PR video closes with a `credits` frame naming them. `capture/extracted/people.json` lists real contributors (bot-filtered), and Step 1 downloaded each avatar to `assets/<login>.png` (the `avatarFetched: true` entries — confirm with `ls assets/`). `reviewDecision` (e.g. `APPROVED`) is honest grounding.

> **The PR `author` only opened the PR — not necessarily who wrote the code.** A teammate often authors most commits. Lead the credits with `committer`s by `commitCount`, not the opener.

The `credits` frame is an avatar row with names + roles + an "approved" check. On that frame only, set `asset_candidates` to 1–6 entries of `assets/<login>.png — <login>, <role>` (commit authors by `commitCount` first, then reviewers; only `avatarFetched: true` logins). The body stays code-only — avatars appear **only** on this close, never decorating a diff frame. The frame sits in the Step 3 proposal like any other, so the user can cut it there; skip it yourself only when no avatar was fetched.

> **Narrate the name, not the handle.** `people.json` carries a `name` field (GitHub display name, e.g. "Miguel Angel Simon Sierra") next to `login` for whichever contributors `gh` already named (author, commit authors, `mergedBy`); it's `null` for reviewers/commenters/assignees, which `gh pr view` only ever gives a bare login. Before writing this frame, resolve any `null` name yourself for the 1-6 people going on the close: `gh api users/<login> --jq .name`. Voiceover always says the **name** (first name is enough — "Shipped by Miguel, reviewed by Wenbo") and **never** reads a raw `@login` aloud (`@miguAng18947550` spoken by TTS is the failure mode this exists to avoid). On-screen text under each avatar can show both, name first, handle small and secondary: `Miguel Angel Simon Sierra` / `@miguel-heygen`. When a name still doesn't resolve (GitHub has no public name for that user either), fall back to the login on-screen and skip that person from the spoken line rather than reading the handle.

Every other frame has **no** `asset_candidates` (the visuals are invented downstream from `scene` + the diff).

### Versions on the end card (cta / changelog)

A `cta` ("upgrade to vN", "npm i pkg@N") or a changelog "what's new in vN" wants a real version — and **a version is the one fact you must never invent.** A PR carries no shipping version, so Step 1 resolves a best-effort one for MERGED PRs and writes it into `capture/extracted/visible-text.txt` as a `Shipped in: <version> (<source>)` meta line (mirrored in `capture/pr.json` as `shipped_version` / `version_source`). Use it:

- **`Shipped in:` present** → use that exact version on the end card. A `version_source` of `unreleased` means the change is on the default branch but not yet in a tagged release — say "shipping in the next release" rather than pinning a tag.
- **No `Shipped in:` line** (open PR, or no version resolvable) → **state the repo / PR URL only** ("read the PR at github.com/…", "pull it") and do **not** name or guess a version number.

## Per-frame length budget — ≤ 9 s, word count is the real measurement

The largest quality bug in PR videos is **scripts that talk too long**. TTS runs at **~2.2 words/second**, so a 45-word "7-second" script is really 20 seconds, and the visual phase has to pad the tail with idle drift (the video reads as "shimmering"). Budget by word count:

| Bound                      | Words (@2.2 wps) | Duration     | When                                                                          |
| -------------------------- | ---------------- | ------------ | ----------------------------------------------------------------------------- |
| **Soft target — default**  | **≤ 19**         | **≤ 9 s**    | Every frame aims here; the cut stays alive.                                   |
| **Exception — ≤ 2 frames** | ≤ 26             | ≤ 12 s       | The main `diff` (the one change you must explain) or a causal-chain `change`. |
| **Hard cap**               | > 26             | > 12 s       | Trim or split.                                                                |
| **Whole-film target**      | ≤ ~400           | up to ~3 min | Sweet spot ~30–90 s (≤ ~155 words); the body carries the load.                |

Estimate while writing: `duration ≈ ceil(word_count / 2.2)`. 29 words → 13s (trim); 17 words → 8s; 12 words → 6s. Trim techniques: cut the lead-in clause ("Until now, the agent shipped…" → "The agent shipped…"); move numbers off-script onto a counter; split only when the halves carry distinct beats (cause then effect). **Silent frames are allowed and common** — a diff typing on, a before→after morph, a counter running. Set `voiceover` empty, omit from `SCRIPT.md`, and make `narrativeRole` carry it. A complex change does not need a long script; it needs a careful one — if you can't headline the change in 19 words, the headline isn't sharp yet.

**Write each line as discrete cues, not one run-on breath.** Step 5 reveals each on-screen piece _when the voiceover names it_ (the anti-PowerPoint mechanism). A line with clear phrase boundaries — "Three retries — then it backs off — then it gives up clean" — hands the shot its reveal cadence for free; a single long clause leaves the frame nothing to pace to.

## Music & silence

The storyboard's top YAML block carries a `music:` field — the BGM mood the audio step retrieves against (e.g. `music: confident minimal tech underscore`). Omitting it falls back to `message:` → `arc:` → a neutral default, so BGM plays unless turned off explicitly.

- **`music: none`** — BGM off (narration, if any, still runs).
- **`music: none` + no `SCRIPT.md`** — the canonical **fully-silent marker**: no narration, no BGM, no SFX. `audio.mjs` generates nothing and the audio step is a clean skip. Use exactly this spelling when the user asks for a silent / music-free video.

## Frame template

```md
## Frame N — Short name

- scene: one clear visual idea — name the hunk/file + the code-\* block ("the request() retry block, ~6 lines, code-diff")
- voiceover: "spoken guide text, or empty"
- duration: ceil(word_count / 2.2) seconds
- transition_in: crossfade
- status: outline
- src: compositions/frames/NN-short-name.html
- type: diff
- persuasion: Before/after contrast
- beat: comprehension
- blueprint: <candidate id from the role→blueprint menu, or omit — a code beat usually omits it (the code-\* block is the shape)>

narrativeRole: What this frame does in the viewer's understanding (its job, not what's on screen).
keyMessage: The one thing the viewer should understand after this frame (one sentence).
```

The `credits` frame additionally carries an `asset_candidates:` line (see the credits section); no other frame does.

## Final checklist

- One archetype is named (compound only when explicit); the sequence is narrative-driven, not diff-order-driven.
- The opening uses a named hook strategy; you do not read the PR description aloud.
- The hook is in viewer-outcome language (no file / function / identifier names), and the video's `message` lands by beat 2 (story-spine).
- Each frame has one job; the body builds cumulatively, **alternating `diff` (the code) with `mechanism` (the behavior)** + `impact` / `evidence` — not a single isolated body frame, and not an unbroken stack of code surfaces.
- Every frame has `type` (PR-native), `persuasion` (a named technique), and `beat` (specific). The emotional arc matches the archetype (fix = frustration → relief; feature = curiosity → confidence).
- Each `voiceover` is phrase-segmented into cues (each a piece Step 5 can reveal on), not one run-on clause; a candidate `blueprint:` is tagged from the role→blueprint menu where a proven shape fits (a code beat usually omits it — the `code-*` block is the shape).
- **2–4 real diff hunks** featured, each a small legible snippet (not a whole file), each naming its `code-*` block in `scene`.
- **At least one `mechanism` beat** animates what the change _does_ at runtime (an invented diagram, or a `flowchart` / `data-chart`), named in its `scene` — unless the PR genuinely has no visible behavior (a pure docs / config bump). The body is not an unbroken run of code surfaces.
- Transitions use only registry names and repeat 2–3 types; frame 1 is `cut`.
- The video closes with a `credits` frame (skipped only when no avatar was fetched); `asset_candidates` is absent on every other frame (1–6 `assets/<login>.png` entries on the close, `avatarFetched: true` only).
- Each `script` fits the budget — ≤ 19 words / ≤ 9 s default, ≤ 2 frames at the ≤ 26 / ≤ 12 s exception; `duration = ceil(word_count / 2.2)`, not a guess.
- `SCRIPT.md` contains only locked spoken narration; silent frames are intentional and omitted from it.

# Visual design — PR-to-video per-frame shot method

> The method behind **Step 4 (Frame visual design)**. You (the orchestrator) read it to **enrich `STORYBOARD.md` frames in place** — story-design wrote the skeleton (each frame's `scene`, `voiceover`, `transition_in`, the narrative fields, and optionally a candidate blueprint id); you add how each frame **looks and moves**. The unit you write per frame is a **time-coded shot sequence** — a shot directed across its whole duration, not a static slide. You write **no HTML** (that's the frame workers). A PR video is **mostly invented** — typography, number-lockups, mechanism diagrams — so you **design** those elements; the two exceptions are **code beats** (a ready-made `code-*` registry block) and the **credits close** (real contributor avatars), both covered below. `frame.md` is your palette/type truth by role. Layout is a compact vocabulary in this file (the **Layout** section below), stated inline per Scene; motion vocabulary + the motion doctrine + the seek-safe core → `motion-language.md`; the proven shapes → `../hyperframes-animation/blueprints-index.md` + `blueprints/<id>.md`; the `code-*` blocks → `code-vocabulary.md`; concrete rules resolve in Step 5 from this skill's local `../hyperframes-animation/rules/`. Adding palette theory or a generic font rule here? Wrong home — `frame.md` + `hyperframes-creative`.

## The unit is a time-coded shot sequence

A frame's visual layer is **a sequence of time windows paced to the voiceover**, not a bag of effect tags. The failure that reads as PowerPoint is **front-loading**: the agent rushes the whole canvas on screen in the first ~25%, and then it just sits. A time-coded shot sequence written **against the VO** makes that impossible: each window states what is on screen and what is moving, and **nothing appears before the voiceover reaches it.** In a PR explainer the development often _is_ the reveal — the diff hunk typing in, the before→after morph, the request-retry diagram running, the impact stat landing. Let the build _be_ the message.

Write each frame as a handful of windows cued by the spoken line:

```
Scene 1 (0.0–Xs):  only what the VO is saying at t=0 enters — never the whole canvas
Scene 2 (Xs–Ys):   the next piece reveals as the VO names it (a file chip / the hunk / a node / a stat)
  …                one window per spoken cue — as many or as few as the line calls for
Scene N (…–end):   content has resolved; hold the read (stillness; subtle jitter at most)
```

- Each `Scene` line names **what's on screen**, **what moves in this window**, and **where it sits** (layout, inline). Times are real seconds across the frame's `duration`.
- **Pace reveals to the voiceover; never front-load.** This is the core anti-PowerPoint mechanism (→ `motion-language.md` Part 2 Rule 2). At t=0 show only what the VO is saying then; reveal each further piece — a line, a file chip, the hunk, a stat — **when the VO names it**, spreading reveals across the shot and especially the **back ~50%**. **The window count = the number of spoken cues the line calls for.** There is **no fixed count and no mandatory "middle" act**; the only sin is dumping everything up front.
- **End on a held read.** Once the content has resolved it holds and reads — **prefer stillness to bad motion**: no forced camera drift, no lazy breathing, no back-half pan/push; at most a subtle jitter keeps it alive (→ `motion-language.md`). Only the final frame has a real exit; every other frame's exit is the harness transition (story's `transition_in`).
- A **deliberately held** frame — content already revealed, now reading still — is legitimate and often right (a climax, a breather). The failure is never "too still"; it is **front-loaded-then-frozen**. Place held beats deliberately for rhythm (allocate them in `## Video direction`).

## Pick the shape — instantiate a blueprint

Don't invent each shot from scratch. The frame's **role** (its `type` / `beat`) points to a proven shape:

1. **Match the role to a blueprint.** Open `../hyperframes-animation/blueprints-index.md`, find the frame's role in the **role→blueprint menu**, and pick the blueprint whose intent fits this beat (story may already have named a candidate id — confirm or override it). Read that `blueprints/<id>.md`: it is a short, domain-agnostic, **time-coded shot template with `[slots]`** and a named **signature move**.

2. **Instantiate its `[slots]` with THIS frame's content** — three postures:
   - **Reproduce** — the blueprint fits the beat and your content maps onto its slots cleanly. Fill every `[slot]` and follow its Scene timing.
   - **Adapt** — the _structure_ fits but the content / surface doesn't. State **what you keep / what you change** in one line, then write the adapted Scene lines. You may never drop the **signature move**, and you keep the reveals **paced to the VO**.
   - **Compose** — no blueprint fits the beat. Build the shot from the **motion vocabulary** in `motion-language.md`: still pace reveals to the VO. Mark it `blueprint: compose`.

3. **Keep the signature move.** Whichever posture, the blueprint's signature move is the spine of the shot — carry it through.

> A **code beat** is the one place you don't pick a blueprint for the centerpiece — the `code-*` block _is_ the shape (see **PR code beats** below). You still write the Scene sequence for the surrounding surface.

## What you add to each frame

Story-design's `## Frame N` block already carries the narrative. You append the shot. Story's `scene` / `voiceover` / `transition_in` / role fields stay untouched.

```
## Frame 4 — The retry fix
- scene: the request() retry hunk lands on the navy code surface   ← refine only if it could read sharper
- voiceover: "…"            ← story's; leave it
- transition_in: crossfade  ← story's; leave it
- type: diff                ← story's (PR-native)
- persuasion: Show-the-change
- beat: clarity
- blueprint: compose        ← code beats compose the surround; the block owns the code motion
- focal: code-diff — the request() retry block, ~6 lines   ← you add: the code-* block IS the focal
- roles: code surface = foreground subject · file header = supporting · dim grid = background
- sfx: keyclack-soft, soft-confirm

Scene 1 (0.0–1.0s): the navy Code Surface window seats in (scale-in + soft shadow), file header "client/request.ts" types on — Centered, ~60% of frame. Slow push-in underneath.
Scene 2 (1.0–3.2s): the camera settles onto the hunk; the `code-diff` block runs its own before→after on its cadence (the worker fits it to the duration) — you do not re-specify the code motion.
Scene 3 (3.2–4.5s): a coral underline draws on the changed line as the VO names it; a `+6/−2` count-up ticks beside the header; settles and holds STILL.
```

The lightweight tags:

- **`blueprint:`** — the id you instantiated (with `(Reproduce)` / `(Adapt)`), or `compose`. One id per frame.
- **`focal:`** — for a concept/mechanism beat, the **invented** hero (a hero word, a diagram, a number-lockup); for a **code beat**, the **`code-*` block** (name the block + the hunk); for the **credits** close, the avatar row.
- **`roles:`** — each element's role: `foreground subject` · `background` (full-bleed, dim 30–50%) · `supporting`. Invented elements you **design**; the only real assets are the credits `assets/<login>.png` avatars (named in story's `asset_candidates`).
- **`sfx:`** — name the sound the beat wants; the audio script's `fetch-sfx` retrieves it and the assembler mounts it at root — you only **name** it, never embed `<audio>`.

**Layout + motion are stated INLINE in each Scene line** — name the template / density / depth as part of "where it sits", and name the move from `motion-language.md`'s vocabulary; let it settle on a long-tail curve (`power3` default). Never write px / scale / ease curves / ms (the worker writes those).

## PR code beats — name a `code-*` block

For a `diff` / `before_after` / code beat, the frame's centerpiece is a **ready-made `code-*` registry block**, not an invented HTML visual — the one exception to "invent every visual."

- **Name the block in `scene` + `focal`.** Pick the one that fits the beat (before→after = `code-diff`; refactor/rename = `code-morph`; new code written on = `code-typing`; spotlight a line = `code-highlight`; walk a long file = `code-scroll`; a hero reveal = `code-3d-extrude` / `code-particle-assemble`). Full map → `code-vocabulary.md`. Name the hunk too ("the `request()` retry block, ~6 lines"). The block is the `focal`; the Step-5 worker installs + fills it with the real diff.
- **The block owns the code animation; your Scenes choreograph the surrounding Code Surface.** The block _is_ the development beat (the diff/typewriter/morph plays on its own cadence — the worker only fits it to the frame's `data-duration` so a long snippet doesn't overrun). Your Scene windows move the code-editorial **Code Surface** around it: the navy window seating in, the file header typing on, the camera settling onto the hunk, a `+N/−M` `count-up`, a coral underline drawing on the landed line. Name those moves inline; **do not re-specify the code animation itself.** A code beat is usually `blueprint: compose` (the block is the shape).

## PR mechanism beats — invent an animated diagram of the behavior

A **`mechanism`** frame is the **show-the-behavior** beat — the antidote to a video that only shows code + text. Its `focal` is an **invented animated diagram** that plays out what the change _does_ at runtime (the request retrying, the cache filling, serial→parallel, the race resolved) — **not** a `code-*` block and **not** a headline.

- **Name the behavior + the diagram in `scene` + `focal`.** e.g. `scene: "animate the request lifecycle — fire → 500 → backoff → retry → 200, invented SVG flow"`; `focal: the request-lifecycle flow`. Reach for the `flowchart` / `flowchart-vertical` / `data-chart` registry blocks where they fit (name them in `scene` so Step 5 pre-installs them); otherwise the worker builds it in SVG / HTML / GSAP from code-editorial's atoms.
- **The build IS the shot sequence.** Unlike a code block (which owns its own animation), the diagram is yours to choreograph across the Scene windows — the lanes / nodes draw on (Scene 1), the flow runs / the lane splits / the front advances as the VO names each step (middle Scenes), the resolved state + one coral emphasis lands (final Scene). Never let it enter then freeze.
- **Stay on code-editorial's cream ground, hairline-ink.** Nodes / edges / lanes in hairline ink on cream; **one coral marker** on the active or changed element; mono labels. Not the navy code surface (that's for code), not heavy shapes / bokeh. Plan it into the top ~83% (caption keep-out).

A `mechanism` frame carries **no** `asset_candidates` (it's invented, like every non-credits frame).

## Impact & credits

- **Impact / evidence** — numbers (`+1,204 / −318`, files touched, perf delta) go on an `impact` frame as a **`number-lockup`** (code-editorial's Number/Impact treatment): name it the `focal`, reveal it with a `count-up` paced to the VO.
- **Credits close** — the optional `credits` frame uses the real `assets/<login>.png` avatars (named in story's `asset_candidates`) as the `focal`: an avatar row that staggers in. This is the one frame with non-empty `asset_candidates` and real assets.

## Inventing the visual (non-code beats)

Every non-code, non-credits beat (`hook` / `change` / `cta` / concept) is **designed**, not captured. Three first-class treatments:

- **Typographic / kinetic type** — a hero word, the PR's headline claim, a stat. Treat type as the subject: full-bleed scale, weight contrast, one emphasized term. Strongest for hooks and the cta.
- **Abstract graphics** — shapes / paths / geometry that _embody_ the idea the script names; don't decorate with generic bokeh.
- **Diagram / data-viz** — the mechanism diagrams above, a `data-chart` for a perf delta, a number-lockup. The build (each part on beat) is the teaching — design it to assemble across the Scenes.

Make the invented hero **fill 40–60% of the frame** — big enough to read; don't shrink the one designed element into decoration around empty space.

## Layout — named inline per Scene

State each Scene's layout as part of "where it sits." **If the blueprint (or the code-\* block) already implies a composition, that wins** — describe it directly; the vocabulary below is for composing freely. Never write px / scale / shadow (the worker does). One frame's layout can EVOLVE across its Scenes. Use **≥3 different framings per video**; never the same framing twice in a row.

- **Framing vocabulary** — centered (hero / climax / a single code surface) · rule-of-thirds · split-screen (before/after, two surfaces) · layered-depth (immersive) · asymmetric 60/40 or 70/30 (a code surface + a caption rail) · triptych (three changes at once) · full-width strip (a file list / timeline). Let the beat decide, not a quota.
- **Density** — primary visual ≥ 40% of canvas; ≥ 3 depth layers; never a lone small cluster floating in empty space. Openings/closings are prone to emptiness — add environmental layers (a dim grid, low-opacity scanlines, brand-color ambient). Squint test: after blur you can still pick out the #1 element.
- **Hierarchy** — combine ≥ 2 of size (3:1) / weight (800 vs 400) / contrast / position (upper-third is golden) / motion, so one element clearly dominates.
- **Depth** — layer 2–3 of: size, blur, opacity gradient, overlap, shadow-stack, counter-scale on a push.
- **Don't show**: nav bars, footers, scrollbars, real cursors / browser chrome, generic decorative shapes, floating bokeh / purple-blue "AI" gradients (banned). The navy code surface is for code beats only; mechanism diagrams stay on cream.

## Portrait & square (non-16:9 canvases)

The zones, density, hierarchy, and depth principles all still apply; the **aspect ratio** changes, and a wide layout doesn't transplant into a tall one — design for the storyboard's `format` from the start.

- **Stack vertically, not side-by-side** — split-screen / triptych / 60-40 become top/bottom stacks. A code surface runs nearly full-width in portrait with fewer visible lines.
- **Vertical center moves with the canvas** — anchor a centered hero around **y ≈ 0.42 × height** (portrait ≈806, square ≈454), not a fixed 540.
- **Type runs larger, fewer words per line.** **Travels well to portrait:** Centered, Layered Depth, Full-Width Strip; **avoid** wide Split Screen / Triptych — use stacked equivalents.

## `## Video direction` — write the invariants ONCE

The whole video shares one look and one motion grammar. Write a **`## Video direction`** block ONCE at the top of `STORYBOARD.md` so every frame inherits it and per-frame Scene lines carry only the **delta**. This block is load-bearing — **keep it.**

- **palette system** — from `frame.md` (code-editorial): which roles map to which hues. Never invent.
- **motion grammar + reveal model** — long-tail eases (`power3` default, smooth over bouncy) + the **VO-paced reveal** model + what may stay alive during a hold (subtle jitter at most) (→ `motion-language.md`).
- **rhythm / held-frame allocation** — name the **held / breather frames** so the video varies its energy.
- **negative list** — off-brand textures, **plus both motion failure modes** — slideshow (front-load then freeze) and screensaver (everything floating independently) (→ `motion-language.md`).

Do **not** repeat these per frame.

## Palette & type — from `frame.md`, never invented

- **Palette** — `frame.md` (code-editorial) is the color truth; apply its roles per frame. Generic basics → `hyperframes-creative/references/house-style.md`.
- **Type** — fonts resolve via `frame.md`'s type tokens; reference them **by role** (display / body / mono / the pack's ramp), never by raw family or px. Code surfaces and mechanism labels use the **mono** role. Typography craft → `hyperframes-creative/references/typography.md`.

## Caption-band keep-out (plan side)

The bottom ~17% of the canvas is reserved for the caption pill. Plan every frame's content into the **top ~83%** (the worker enforces the pixel cutoff). When captions are enabled, primary content caps at the band top, and a centered hero anchors at **y ≈ 0.42 × height** (landscape ≈454, portrait ≈806); background / ambient layers are exempt and may stay full-bleed. Holds even when captions are disabled — bottom-edge consistency.

## Where the detail lives

| For…                                                                            | Read                                                                           |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| the proven shapes + role→blueprint menu + how to pick                           | `../hyperframes-animation/blueprints-index.md` → `blueprints/<id>.md`          |
| the `code-*` blocks (pick + fill for a code beat)                               | `code-vocabulary.md` (local)                                                   |
| motion — shot model, vocabulary, holds, idle budget, stillness, seek-safe       | `motion-language.md` (local)                                                   |
| layout — framing, density, depth, hierarchy, inventing the visual, caption band | the **Layout** + **Inventing the visual** sections in this file                |
| concrete eases / ms / stagger + rule recipe bodies (Step 5)                     | local `../hyperframes-animation/rules/` (the frame worker reads it; you don't) |
| palette + type tokens                                                           | the project's `frame.md` (code-editorial); basics → `hyperframes-creative`     |
| within-frame cuts / seams (zoom-through · cut-the-curve · waterfall)            | `cut-catalog.md` (the worker builds them inside the composition)               |
| transitions                                                                     | story-design owns `transition_in`; you don't touch it                          |

## Before you finish — checklist

- **`## Video direction`** written once at the top (palette · motion grammar + shot model + idle budget · stillness allocation · negative list incl. both failure modes); per-frame entries are deltas.
- Every frame is a **time-coded shot sequence** with real second windows across its `duration` — not a tag bag.
- **No frame front-loads** — at t=0 only what the VO is saying enters; each further piece reveals on its spoken cue, across the back ~50%. Window count follows the VO.
- Every frame names a **`blueprint:`** id (Reproduce / Adapt) or `compose`; an Adapt keeps the signature move; nothing collapses to a single front-loaded dump.
- **Code beats** name a `code-*` block as the `focal`, let the block own the code animation, and choreograph only the surrounding Code Surface in the Scenes.
- **Mechanism beats** name an **invented animated diagram of the behavior** (or a `flowchart` / `data-chart`), choreographed across the Scenes on code-editorial's cream ground with one coral marker — not a code block, not typography; the body is not an unbroken run of code surfaces.
- **Impact** uses a `number-lockup` with a `count-up`; the **credits** close uses the real avatars as the `focal`.
- Each non-code, non-credits frame names its **invented** `focal` + per-element `roles`, kept few and load-bearing.
- Layout + motion named **inline** per Scene (no px / ease curves / ms / JS).
- Content planned into the top ~83% (caption band clear); palette / type pulled from `frame.md` by role.
- You wrote no HTML.

#!/usr/bin/env node
// assemble-index.mjs — deterministic top-level index.html assembly for a
// HyperFrames project. No subagent, no judgment: turns STORYBOARD.md + the
// built frame files (+ optional audio_meta.json) into the standalone index.html
// the renderer consumes, and stages the frame-named capture assets into assets/.
//
// index.html is a *standalone* composition (root <div id="root"> directly in
// <body>, no <template> wrapper — template is for sub-comps). Structure is
// modeled on the canonical fixture packages/studio/fixtures/storyboard-sample/
// index.html and the authoritative head/audio template in
// packages/core/docs/quickstart-template.html. Frame mount order = STORYBOARD
// document order. Transitions are NOT written here — the transitions injector
// mutates this file afterward (data-start/duration/track-index + GSAP).
//
// Track lanes. Same-track time-overlap is this workflow's own assembly convention,
// not a framework rule: the render never reads data-track-index, and no lint rule
// checks overlap (timeline_track_too_dense counts elements per lane for readability).
// The convention exists because the frame injector below ping-pongs 0/1 for overlaps:
//   1      frame sub-comp clips (sequential; the injector 0/1-ping-pongs for overlaps)
//   2      captions sub-comp clip (full-duration overlay, on top of frames)
//   10     per-frame voice <audio>
//   11     BGM <audio>
//   20+i   SFX <audio> (one lane each)
//
// audio_meta.json contract (produced by audio.mjs; OPTIONAL — absent ⇒ silent
// video, frames only). Durations come from STORYBOARD (audio sync-durations
// writes them), NOT from here; this file carries only media PATHS, keyed by
// frame number:
//   { "bgm":   { "path": "assets/bgm/x.mp3", "volume": 0.12 } | null,
//     "voices":[ { "frame": 3, "path": "assets/voice/03.wav" } ],
//     "sfx":   [ { "frame": 3, "file": "assets/sfx/x.mp3", "offset_s": 0,
//                  "duration_s": 1.0, "volume": 0.35 } ] }
//
// Reads:  --storyboard STORYBOARD.md, --hyperframes <project root>,
//         [--audio-meta audio_meta.json]. On disk: each built frame's src html,
//         capture/{assets,assets/videos,screenshots}/<basename> for staging, compositions/captions.html.
// Writes: <project>/index.html  +  stages assets/<basename>  +  (guard ① below)
//         repairs a frame file in place when its root is missing data-width/height.
//
// Pre-assembly frame guards (run in the same pass that reads each frame, so common
// `lint` failures surface HERE instead of after assembly + a wasted render):
//   ① AUTO-REPAIR — a sub-comp root missing data-width/data-height: inject the canvas
//      dims (the renderer needs them on the cloned root; else lint root_missing_dimensions).
//   ② HARD FAIL  — a timed element (data-start+duration+track-index) that is not the root
//      and lacks class="clip" (shows the whole frame), or two same-track clips that overlap.
//   (Media inside a sub-comp is NOT a violation: the runtime seeks + decodes nested
//    <video>/<audio> at any depth — see packages/core/src/runtime/{media,startResolver}.ts.)
//
// Exit 0 = index.html written + summary. Exit 1 = fatal contract break (no
// frames, a built/animated frame missing its src/file, a frame with no
// duration, an inner data-composition-id mismatch, or a guard ② violation).
// No backstop: fix upstream.

import { existsSync, readFileSync, writeFileSync } from "node:fs";
import { spawnSync } from "node:child_process";
import { basename, join, resolve } from "node:path";
import { parseStoryboard } from "./lib/storyboard.mjs";
import { parseFormat } from "./lib/dimensions.mjs";
import { stageAssets } from "./lib/assets.mjs";
import { parseColors, semanticColors } from "./lib/tokens.mjs";
import { validateFrameHtml } from "./lib/frame-contract.mjs";
import { bgmDefaultVolume } from "../../media-use/audio/scripts/lib/bgm.mjs";

// ---------- argv ----------
const argv = process.argv.slice(2);
const flag = (name, def) => {
  const i = argv.indexOf(`--${name}`);
  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
};
// Deliberate escape from the bgm_pending refusal below — for previewing while a detached
// generate is still running. Off by default so a silent film can't ship by accident.
const allowPendingBgm = argv.includes("--allow-pending-bgm");
function die(msg) {
  console.error(`✗ assemble-index.mjs: ${msg}`);
  process.exit(1);
}

// Ensure the BGM track is at least `total` seconds long. HeyGen (and most music
// libraries) return a short loopable clip (~15–30s); mounting it at data-duration=total
// would leave the video's TAIL SILENT. If the file is short, loop-extend it to `total`
// (with a 0.4s fade-in + 1.5s fade-out) into a sibling *.loop.mp3 and return that path.
// Needs ffprobe+ffmpeg (present in the render env); degrades to the original + a warning
// when they're absent, so assembly never hard-fails on audio tooling.
function ensureBgmCovers(relPath, hyperframesDir, total) {
  const abs = join(hyperframesDir, relPath);
  const probe = spawnSync(
    "ffprobe",
    ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", "--", abs],
    { encoding: "utf8" },
  );
  if (probe.status !== 0) return { looped: false, short: false, reason: "ffprobe unavailable" };
  const dur = parseFloat(String(probe.stdout || "").trim());
  if (!Number.isFinite(dur) || dur <= 0)
    return { looped: false, short: false, reason: "unreadable duration" };
  if (dur >= total - 0.1) return { looped: false, short: false, dur }; // already covers
  const relOut = relPath.replace(/\.([^./]+)$/, ".loop.$1");
  const absOut = join(hyperframesDir, relOut);
  const fadeOut = Math.max(0, total - 1.5);
  const ff = spawnSync(
    "ffmpeg",
    [
      "-y",
      "-stream_loop",
      "-1",
      "-i",
      abs,
      "-t",
      String(total),
      "-af",
      `afade=t=in:st=0:d=0.4,afade=t=out:st=${fadeOut}:d=1.5`,
      "-c:a",
      "libmp3lame",
      "-q:a",
      "2",
      absOut,
    ],
    { encoding: "utf8" },
  );
  if (ff.status !== 0 || !existsSync(absOut))
    return { looped: false, short: true, dur, reason: "ffmpeg unavailable" };
  return { looped: true, rel: relOut, from: dur };
}

const hyperframesDir = resolve(flag("hyperframes", "."));
const storyboardPath = resolve(flag("storyboard", join(hyperframesDir, "STORYBOARD.md")));
const audioMetaPath = resolve(flag("audio-meta", join(hyperframesDir, "audio_meta.json")));
const outPath = resolve(flag("out", join(hyperframesDir, "index.html")));

const r3 = (x) => Math.round(x * 1000) / 1000;
const anomalies = [];
const frameErrors = []; // fatal per-frame composition violations (guard ②) — reported together
const repairs = []; // auto-repairs applied to frame files in place (guard ①)

// ---------- parse storyboard ----------
if (!existsSync(storyboardPath)) die(`STORYBOARD.md not found at ${storyboardPath}`);
const manifest = parseStoryboard(readFileSync(storyboardPath, "utf8"));
const { width: WIDTH, height: HEIGHT } = parseFormat(manifest.globals.format);

// ---------- per-frame composition guards (see header ①②) ----------
// String-level checks on each frame's HTML — no DOM parse, deterministic, run in
// the same pass that already reads the file. OPEN_TAG matches one opening tag while
// tolerating quoted attribute values that contain ">" (e.g. inline styles).
const OPEN_TAG = "<([a-zA-Z][a-zA-Z0-9-]*)((?:[^>\"']|\"[^\"]*\"|'[^']*')*)>";
const attrPresent = (attrs, name) => new RegExp(`(?:^|\\s)${name}(?:[\\s=]|$)`).test(attrs);
const attrValue = (attrs, name) => {
  const m = attrs.match(new RegExp(`(?:^|\\s)${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`));
  return m ? (m[1] ?? m[2]) : null;
};
// The root (or a nested-comp mount) legitimately carries timing without class="clip".
const isRootish = (attrs) =>
  /(?:^|\s)id\s*=\s*["']root["']/.test(attrs) ||
  attrPresent(attrs, "data-composition-id") ||
  attrPresent(attrs, "data-composition-src");

// Locate the composition root opening tag: prefer id="root", else the first element
// carrying data-composition-id. Returns { start, end, full, attrs } or null.
function findRootTag(html) {
  const re = new RegExp(OPEN_TAG, "g");
  let m;
  let firstCompId = null;
  while ((m = re.exec(html))) {
    const attrs = m[2];
    if (/(?:^|\s)id\s*=\s*["']root["']/.test(attrs))
      return { start: m.index, end: m.index + m[0].length, full: m[0], attrs };
    if (attrPresent(attrs, "data-composition-id") && !firstCompId)
      firstCompId = { start: m.index, end: m.index + m[0].length, full: m[0], attrs };
  }
  return firstCompId;
}

// Returns { errors: string[], repairedHtml: string|null, repairNote: string|null }.
function guardFrame(html, label) {
  const errors = [];
  // Scan a copy with comments + <script>/<style> bodies blanked, so a tag-like string
  // in a comment (e.g. "<!-- match the host <video> coords -->") or in GSAP code can't
  // trip ②. ① still splices into the ORIGINAL html, so its offsets stay correct.
  const scan = html
    .replace(/<!--[\s\S]*?-->/g, " ")
    .replace(/<script\b[\s\S]*?<\/script[^>]*>/gi, " ")
    .replace(/<style\b[\s\S]*?<\/style[^>]*>/gi, " ");

  // ② timed-element checks: missing class="clip", and same-track window overlap.
  // (Media inside a sub-comp is fine: the runtime's global media sweep seeks + decodes
  // <video>/<audio> at any nesting depth, re-basing each clip's local data-start by its
  // host composition's absolute start — no root-child requirement. See
  // packages/core/src/runtime/{media,startResolver}.ts.)
  const re = new RegExp(OPEN_TAG, "g");
  const clips = [];
  let m;
  while ((m = re.exec(scan))) {
    const attrs = m[2];
    if (
      !attrPresent(attrs, "data-start") ||
      !attrPresent(attrs, "data-duration") ||
      !attrPresent(attrs, "data-track-index")
    )
      continue;
    if (isRootish(attrs)) continue;
    if (!/(?:^|\s)class\s*=\s*["'][^"']*\bclip\b[^"']*["']/.test(attrs)) {
      errors.push(
        `${label}: a timed <${m[1]}> (data-start/duration/track-index) has no class="clip" — it renders for the whole frame instead of only its window. Add class="clip", or remove the timing attrs if it is a GSAP-animated element meant to be present throughout.`,
      );
    }
    const track = attrValue(attrs, "data-track-index");
    const start = parseFloat(attrValue(attrs, "data-start"));
    const dur = parseFloat(attrValue(attrs, "data-duration"));
    if (track != null && Number.isFinite(start) && Number.isFinite(dur))
      clips.push({ track, start, end: start + dur });
  }
  const EPS = 1e-3; // adjacent clips that merely touch are legal
  const byTrack = new Map();
  for (const c of clips) {
    const arr = byTrack.get(c.track);
    if (arr) arr.push(c);
    else byTrack.set(c.track, [c]);
  }
  for (const [track, list] of byTrack) {
    list.sort((a, b) => a.start - b.start);
    for (let i = 1; i < list.length; i++) {
      if (list[i].start < list[i - 1].end - EPS) {
        errors.push(
          `${label}: clips on track ${track} overlap (one ends at ${r3(list[i - 1].end)}s, the next starts at ${r3(list[i].start)}s). This workflow's injector assumes one clip per lane at a time. The render itself tolerates the overlap; put them on distinct data-track-index lanes or fix their windows.`,
        );
        break; // one report per track is enough
      }
    }
  }

  // ① auto-repair: ensure the root carries data-width / data-height.
  let repairedHtml = null;
  let repairNote = null;
  const root = findRootTag(html);
  if (root) {
    const needW = !attrPresent(root.attrs, "data-width");
    const needH = !attrPresent(root.attrs, "data-height");
    if (needW || needH) {
      const inject =
        (needW ? ` data-width="${WIDTH}"` : "") + (needH ? ` data-height="${HEIGHT}"` : "");
      const newTag = root.full.replace(/(\/?>)$/, `${inject}$1`);
      repairedHtml = html.slice(0, root.start) + newTag + html.slice(root.end);
      repairNote = `${label}: injected${needW ? " data-width" : ""}${needH ? " data-height" : ""} (${WIDTH}×${HEIGHT}) on the root — was missing (would lint root_missing_dimensions)`;
    }
  }

  return { errors, repairedHtml, repairNote };
}

// ---------- resolve mountable frames in document order ----------
// A frame mounts when its src html exists on disk. A built/animated frame
// missing its src/file is a contract break (die). An outline frame with no
// file is skipped (still a placeholder) with an anomaly note.
const mounted = [];
for (const f of manifest.frames) {
  const label = `frame ${f.number ?? f.index}${f.title ? ` (${f.title})` : ""}`;
  const built = f.status === "built" || f.status === "animated";
  if (!f.src) {
    if (built) die(`${label} is ${f.status} but has no \`src\` — the orchestrator must write it`);
    anomalies.push(`${label}: status ${f.status}, no src — skipped`);
    continue;
  }
  const compAbs = join(hyperframesDir, f.src);
  // Read directly and handle ENOENT here rather than an existsSync precheck — the
  // check→read/write pair is a TOCTOU race CodeQL flags (js/file-system-race).
  let html;
  try {
    html = readFileSync(compAbs, "utf8");
  } catch {
    if (built)
      die(`${label} is ${f.status} but its src ${f.src} is not on disk — re-dispatch the worker`);
    anomalies.push(`${label}: src ${f.src} not on disk (status ${f.status}) — skipped`);
    continue;
  }
  if (!Number.isFinite(f.durationSeconds) || f.durationSeconds <= 0) {
    die(
      `${label}: no positive duration (got ${JSON.stringify(f.duration)}) — run audio sync-durations`,
    );
  }
  // Host data-composition-id MUST equal the inner file's, or the runtime never
  // finds the timeline. frame_id = src basename (frame-worker contract); verify
  // the inner html actually declares it.
  const compId = basename(f.src).replace(/\.html?$/i, "");
  // Guard against blank/partial scene files: a worker that errors or is
  // interrupted mid-write leaves an empty (or markup-less) file that exists but
  // fails at render with "Composition HTML is empty or could not be parsed".
  // Catch it here — before emitting data-composition-src — and re-dispatch.
  if (!html.trim() || !/<\w/.test(html)) {
    die(
      `${label}: ${f.src} is empty or has no HTML — the worker wrote a blank/partial file. Re-dispatch that worker before assembling.`,
    );
  }
  try {
    validateFrameHtml(html, { expectedId: compId, expectedDuration: f.durationSeconds });
  } catch (error) {
    die(`${label}: ${error.message}`);
  }
  // pre-assembly guards: ① repair missing root dims in place, ② collects fatal violations.
  const guard = guardFrame(html, label);
  if (guard.repairedHtml) {
    writeFileSync(compAbs, guard.repairedHtml);
    html = guard.repairedHtml;
    repairs.push(guard.repairNote);
  }
  for (const e of guard.errors) frameErrors.push(e);
  if (
    !html.includes(`data-composition-id="${compId}"`) &&
    !html.includes(`data-composition-id='${compId}'`)
  ) {
    die(`${label}: ${f.src} has no data-composition-id="${compId}" (host/inner id must match)`);
  }
  mounted.push({ frame: f, compId, durationSeconds: r3(f.durationSeconds) });
}
if (frameErrors.length) {
  die(
    `${frameErrors.length} frame composition violation(s) — fix the worker output and re-assemble:\n` +
      frameErrors.map((e) => `  • ${e}`).join("\n"),
  );
}
if (mounted.length === 0) die("no mountable frames (none built with an on-disk src)");

// cumulative starts — emitted data-start[i] + data-duration[i] == start[i+1] by
// construction (renderer computes end the same way), so adjacent clips touch
// exactly with no float-overlap.
let acc = 0;
for (const m of mounted) {
  m.start = acc;
  acc += m.durationSeconds;
}
const TOTAL = r3(acc);

// ---------- duration expectation (advisory) ----------
// Frontmatter `duration:` carries the brief's rough length expectation
// (storyboard-format.md § Frontmatter). Never blocks the build: report where
// the cut lands, and flag a large gap so the agent judges whether the drift
// serves the piece.
let durationNote = "";
const rawTarget = manifest.globals.extra?.duration;
if (rawTarget != null && String(rawTarget).trim() !== "") {
  const targetMatch = String(rawTarget).match(/(\d+(?:\.\d+)?)/);
  const target = targetMatch ? parseFloat(targetMatch[1]) : NaN;
  if (!Number.isFinite(target) || target <= 0) {
    anomalies.push(
      `frontmatter duration "${rawTarget}" is not parseable (e.g. "22s") — skipped the expectation check`,
    );
  } else {
    const diff = r3(TOTAL - target);
    durationNote = ` (expected ~${target}s, ${diff >= 0 ? "+" : ""}${diff}s)`;
    const pct = Math.abs((diff / target) * 100);
    if (pct > 10) {
      anomalies.push(
        `total ${TOTAL}s lands ${Math.round(pct)}% ${diff > 0 ? "over" : "under"} the brief's ~${target}s expectation — ` +
          `judge whether the drift serves the piece (pacing, narration fit); re-pace, or update \`duration:\` if the new length is intended`,
      );
    }
  }
}
const startOfFrameNumber = new Map();
for (const m of mounted) if (m.frame.number != null) startOfFrameNumber.set(m.frame.number, m);

// ---------- audio_meta (optional) ----------
let audio = { bgm: null, voices: [], sfx: [] };
if (existsSync(audioMetaPath)) {
  try {
    const parsed = JSON.parse(readFileSync(audioMetaPath, "utf8"));
    // bgm_pending rides along: without it this step cannot tell a detached generate that has
    // not landed yet from a film that is silent by design, and it would build the silent one.
    audio = {
      bgm: parsed.bgm ?? null,
      bgm_pending: !!parsed.bgm_pending,
      voices: parsed.voices ?? [],
      sfx: parsed.sfx ?? [],
    };
  } catch (e) {
    die(`audio_meta.json parse: ${e.message}`);
  }
}
const voiceByFrame = new Map();
for (const v of audio.voices) if (v.frame != null) voiceByFrame.set(v.frame, v);

// ---------- build <body> in track order ----------
const body = [];
let voiceCount = 0;

for (const m of mounted) {
  // (track 1) frame sub-comp clip — no class="clip" semantics needed; .scene CSS sizes it.
  body.push(
    `      <div`,
    `        id="el-${m.compId}"`,
    `        class="scene"`,
    `        data-composition-id="${m.compId}"`,
    `        data-composition-src="${m.frame.src}"`,
    `        data-start="${m.start}"`,
    `        data-duration="${m.durationSeconds}"`,
    `        data-track-index="1"`,
    `      ></div>`,
  );
  // (track 10) voice — only when the file is actually on disk.
  const v = m.frame.number != null ? voiceByFrame.get(m.frame.number) : undefined;
  if (v?.path) {
    if (existsSync(join(hyperframesDir, v.path))) {
      body.push(
        `      <audio`,
        `        id="el-${m.compId}-voice"`,
        `        src="${v.path}"`,
        `        data-start="${m.start}"`,
        `        data-duration="${m.durationSeconds}"`,
        `        data-track-index="10"`,
        `        data-volume="1"`,
        `      ></audio>`,
      );
      voiceCount++;
    } else {
      anomalies.push(`${m.compId}: voice ${v.path} not on disk — skipped`);
    }
  }
  body.push("");
}

// (track 11) BGM — duck under narration when any voice is present. Loop-extend a short
// track to the full video length so the tail isn't silent (libraries return ~15–30s clips).
let bgmEmitted = false;
let bgmNote = "";
if (audio.bgm?.path) {
  if (existsSync(join(hyperframesDir, audio.bgm.path))) {
    let bgmSrc = audio.bgm.path;
    const cov = ensureBgmCovers(audio.bgm.path, hyperframesDir, TOTAL);
    if (cov.looped) {
      bgmSrc = cov.rel;
      bgmNote = ` (looped ${cov.from.toFixed(1)}s→${TOTAL}s)`;
    } else if (cov.short) {
      anomalies.push(
        `bgm is ${cov.dur?.toFixed?.(1) ?? "?"}s (< ${TOTAL}s) and could not be extended (${cov.reason}) — the tail will be silent; install ffmpeg`,
      );
    }
    // An explicit volume from audio_meta always wins; otherwise the shared
    // media-use default (bed ~ -18 dB under narration, forward for a silent film).
    const vol = audio.bgm.volume != null ? audio.bgm.volume : bgmDefaultVolume(voiceCount > 0);
    body.push(
      `      <!-- BGM -->`,
      `      <audio`,
      `        id="el-bgm"`,
      `        src="${bgmSrc}"`,
      `        data-start="0"`,
      `        data-duration="${TOTAL}"`,
      `        data-track-index="11"`,
      `        data-volume="${vol}"`,
      `      ></audio>`,
      "",
    );
    bgmEmitted = true;
  } else {
    anomalies.push(`bgm ${audio.bgm.path} not on disk — skipped`);
  }
} else if (audio.bgm_pending) {
  // The distinction the flag exists to make. A warning is not enough: assemble is re-run on
  // rework long after the audio step's own warning scrolled past, and it would happily build a
  // silent film from a snapshot whose JSON says the bed is still generating.
  if (!allowPendingBgm) {
    die(
      "audio_meta.json says bgm_pending — the music bed is still generating and is NOT in this " +
        "assembly. Wait for the track, re-run the audio step, then assemble again. To assemble a " +
        "deliberately silent preview anyway, pass --allow-pending-bgm.",
    );
  }
  anomalies.push(
    "bgm still generating (bgm_pending) — assembled without a bed per --allow-pending-bgm",
  );
}

// (track 2) captions — captions.mjs writes this or legally skips; key off existence.
let captionsEmitted = false;
if (existsSync(join(hyperframesDir, "compositions/captions.html"))) {
  body.push(
    `      <!-- captions -->`,
    `      <div`,
    `        id="el-captions"`,
    `        class="scene"`,
    `        data-composition-id="captions"`,
    `        data-composition-src="compositions/captions.html"`,
    `        data-start="0"`,
    `        data-duration="${TOTAL}"`,
    `        data-track-index="2"`,
    `      ></div>`,
    "",
  );
  captionsEmitted = true;
}

// (track 20+i) SFX — placed at its frame's start + offset.
let sfxEmitted = 0;
audio.sfx.forEach((cue, i) => {
  const host = cue.frame != null ? startOfFrameNumber.get(cue.frame) : undefined;
  if (!host) {
    anomalies.push(`sfx ${cue.file}: frame ${cue.frame} not mounted — skipped`);
    return;
  }
  const rel = cue.file;
  if (!existsSync(join(hyperframesDir, rel))) {
    anomalies.push(`sfx ${rel} not on disk — skipped`);
    return;
  }
  const t = r3(host.start + (cue.offset_s ?? 0));
  const dur = r3(cue.duration_s ?? 1);
  const vol = cue.volume != null ? cue.volume : 0.35;
  if (sfxEmitted === 0) body.push(`      <!-- SFX -->`);
  body.push(
    `      <audio`,
    `        id="el-sfx-${i}"`,
    `        src="${rel}"`,
    `        data-start="${t}"`,
    `        data-duration="${dur}"`,
    `        data-track-index="${20 + i}"`,
    `        data-volume="${vol}"`,
    `      ></audio>`,
  );
  sfxEmitted++;
});

// ---------- stage frame-named assets: capture/ → assets/ (idempotent backstop) ----------
// Frame workers + the live preview reference assets/<basename>; stage-assets.mjs
// already ran this at Step 4 close. Re-run as a backstop so a late-named asset
// still lands. Shared logic: lib/assets.mjs (first-wins, safe to call twice).
const {
  staged,
  wanted,
  anomalies: assetAnomalies,
} = stageAssets({
  hyperframesDir,
  frames: manifest.frames,
});
for (const a of assetAnomalies) anomalies.push(a);

// ---------- <head> ----------
// ---------- ground color ----------
// Per-frame roots carry data-start/data-duration and get clip-gated against the
// global timeline in render (only the first frame's [0,dur] window overlaps global
// 0), so a frame's own full-bleed background can't be relied on as the video ground —
// every frame after the first would render on the bare body color (black). Paint the
// ground on the always-present root composition instead, using the project's frame.md
// canvas color (the same ground role the caption skin maps to --cap-canvas). Falls
// back to the body letterbox color when frame.md is absent or has no resolvable ground.
const framePath = join(hyperframesDir, "frame.md");
let groundColor = null;
if (existsSync(framePath)) {
  try {
    const roles = semanticColors(parseColors(readFileSync(framePath, "utf8")));
    if (roles && roles.canvas) groundColor = roles.canvas;
  } catch {
    /* leave groundColor null — #root stays transparent over the body letterbox */
  }
}

const headStyle = [
  "      * {",
  "        margin: 0;",
  "        padding: 0;",
  "        box-sizing: border-box;",
  "      }",
  "      html,",
  "      body {",
  `        width: ${WIDTH}px;`,
  `        height: ${HEIGHT}px;`,
  "        overflow: hidden;",
  "        background: #000;",
  "      }",
  "      #root {",
  "        position: relative;",
  `        width: ${WIDTH}px;`,
  `        height: ${HEIGHT}px;`,
  "        overflow: hidden;",
  ...(groundColor ? [`        background: ${groundColor};`] : []),
  "      }",
  "      .scene {",
  "        position: absolute;",
  "        inset: 0;",
  "        width: 100%;",
  "        height: 100%;",
  "      }",
].join("\n");

const html = `<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=${WIDTH}, height=${HEIGHT}" />
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js" integrity="sha384-sG0Hv1tP1lZCk9KQmrIbY/XNwi+OY84GQqhMscbnsoBFqAz8KNCil1kvfL3Hbbk2" crossorigin="anonymous"></script>
    <style>
${headStyle}
    </style>
  </head>
  <body>
    <div
      id="root"
      data-composition-id="main"
      data-start="0"
      data-duration="${TOTAL}"
      data-width="${WIDTH}"
      data-height="${HEIGHT}"
    >
${body.join("\n")}
    </div>

    <script>
      window.__timelines = window.__timelines || {};
      window.__timelines["main"] = gsap.timeline({ paused: true });
    </script>
  </body>
</html>
`;

writeFileSync(outPath, html);

// ---------- summary ----------
console.log(`✓ wrote ${outPath}`);
console.log(`  canvas:            ${WIDTH}×${HEIGHT}`);
console.log(`  frames (track 1):  ${mounted.length}`);
console.log(`  voice  (track 10): ${voiceCount}`);
console.log(`  bgm    (track 11): ${bgmEmitted ? "yes" + bgmNote : "no"}`);
console.log(`  captions (track 2): ${captionsEmitted ? "yes" : "no"}`);
console.log(`  sfx    (track 20+): ${sfxEmitted}`);
console.log(`  assets staged:     ${staged}/${wanted.size}`);
console.log(`  total duration:    ${TOTAL}s${durationNote}`);
if (repairs.length) {
  console.log(`\nrepaired (frame files updated in place):`);
  for (const rp of repairs) console.log(`  - ${rp}`);
}
if (anomalies.length) {
  console.log(`\nanomalies (non-fatal):`);
  for (const a of anomalies) console.log(`  - ${a}`);
}

import assert from "node:assert/strict";
import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { spawnSync } from "node:child_process";
import test from "node:test";

const assembleScript = new URL("./assemble-index.mjs", import.meta.url).pathname;

// ── bgm_pending at the assembly boundary ─────────────────────────────────────
// Regression: the flag survived into audio_meta.json but assemble rebuilt its audio object
// from three named keys and dropped it, so the step that actually builds the film could not
// tell "not ready yet" from "silent by design" and would ship the silent one.

function assembleWith({ audioMeta, extraArgs = [] }) {
  const dir = mkdtempSync(join(tmpdir(), "product-launch-assemble-"));
  writeFileSync(
    join(dir, "STORYBOARD.md"),
    "---\nformat: 1920x1080\nmessage: T\n---\n\n## Frame 1 — A\n- duration: 3s\n- src: compositions/frames/01-a.html\n",
  );
  mkdirSync(join(dir, "compositions", "frames"), { recursive: true });
  writeFileSync(
    join(dir, "compositions", "frames", "01-a.html"),
    // pr-to-video's frame contract wants one bare <template> whose inner root carries the
    // composition id and duration (lib/frame-contract.mjs).
    '<template><div data-composition-id="01-a" data-width="1920" data-height="1080" ' +
      'data-duration="3"><section class="clip" data-start="0" data-duration="3"></section>' +
      "</div></template>",
  );
  if (audioMeta) writeFileSync(join(dir, "audio_meta.json"), JSON.stringify(audioMeta));
  const r = spawnSync(
    process.execPath,
    [
      assembleScript,
      "--storyboard",
      join(dir, "STORYBOARD.md"),
      "--hyperframes",
      dir,
      ...extraArgs,
    ],
    { encoding: "utf8" },
  );
  return { dir, r };
}

test("assemble REFUSES while bgm_pending and no bed on disk", () => {
  const { dir, r } = assembleWith({
    audioMeta: { bgm: null, bgm_pending: true, voices: [], sfx: [] },
  });

  assert.notEqual(r.status, 0, "should not assemble a silent film over a pending bed");
  assert.match(r.stderr, /bgm_pending/);
  // Refusing means producing nothing, not a half-built index.
  assert.equal(existsSync(join(dir, "index.html")), false);
});

test("--allow-pending-bgm assembles anyway, and says so", () => {
  const { dir, r } = assembleWith({
    audioMeta: { bgm: null, bgm_pending: true, voices: [], sfx: [] },
    extraArgs: ["--allow-pending-bgm"],
  });

  assert.equal(r.status, 0, r.stderr);
  assert.equal(existsSync(join(dir, "index.html")), true);
  assert.match(r.stdout + r.stderr, /pending/i);
});

test("a film that is silent BY DESIGN still assembles untouched", () => {
  // The whole point of carrying the flag: this case must stay distinguishable from the above.
  const { dir, r } = assembleWith({ audioMeta: { bgm: null, voices: [], sfx: [] } });

  assert.equal(r.status, 0, r.stderr);
  assert.equal(existsSync(join(dir, "index.html")), true);
  assert.doesNotMatch(r.stderr, /bgm_pending/);
});

#!/usr/bin/env node
// audio.mjs — audio ADAPTER (reuses the product-launch SCRIPT.md / STORYBOARD.md
// model; this file is intentionally identical across the reusing skills). The
// TTS / BGM / SFX implementation
// no longer lives here: it is the shared engine at
// ../../media-use/audio/scripts/audio.mjs. This file only (a) maps the
// product-launch model (SCRIPT.md frames + STORYBOARD.md music/sfx) into the
// engine's neutral audio_request.json, (b) converts the engine's id-keyed
// audio_meta back into the frame-keyed shape captions.mjs / assemble-index.mjs
// already consume, and (c) keeps the local `sync-durations` pass (it rewrites
// STORYBOARD.md, which is product-launch-specific).
//
// Three modes (unchanged CLI surface):
//   (default) generate — engine --only tts,bgm. BGM mode is "retrieve" (strict:
//        no HeyGen credential ⇒ skip, never a detached generate, since this
//        workflow has no wait-bgm step). Runs in the background during Step 4.
//   sync-durations — write real voice durations into STORYBOARD.md (local).
//   fetch-sfx      — engine --only sfx, merged into the existing meta (Step 5,
//        after the frames' `sfx:` cues exist).
//
//   node audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json
//   node audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md
//   node audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .

import { spawnSync } from "node:child_process";
import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { parseStoryboard } from "./lib/storyboard.mjs";

const HERE = dirname(fileURLToPath(import.meta.url));
const DEFAULT_ENGINE = join(HERE, "..", "..", "media-use", "audio", "scripts", "audio.mjs");

const flag = (argv, name, def) => {
  const i = argv.indexOf(`--${name}`);
  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
};
const pad2 = (n) => String(n).padStart(2, "0");

// SCRIPT.md → [{ frame, text }]. `## … (Frame N)` opens a line; `**key:**` rows
// are metadata; the indented block is the spoken text (the only TTS input).
function parseScript(md) {
  const out = [];
  let cur = null;
  const flush = () => {
    if (cur && cur.text.trim()) out.push({ frame: cur.frame, text: cur.text.trim() });
    cur = null;
  };
  for (const line of md.split(/\r?\n/)) {
    const h = line.match(/^#{2,3}\s+.*?\(frame\s+(\d+)\)/i);
    if (h) {
      flush();
      cur = { frame: Number(h[1]), text: "" };
      continue;
    }
    if (!cur) continue;
    if (/^\s*\*\*/.test(line)) continue;
    const m = line.match(/^(?: {4,}|\t)(.+)$/);
    if (m) cur.text += (cur.text ? " " : "") + m[1].trim();
  }
  flush();
  return out;
}

// Path of the engine's neutral meta — a stable sidecar so `--only` merges
// (generate then fetch-sfx) accumulate, while audio_meta.json holds the PL shape.
const neutralPath = (plOutPath) => join(dirname(plOutPath), "audio_engine_meta.json");

// Run the shared engine. Returns nothing; dies on a non-zero exit.
function runEngine({ request, hyperframesDir, neutral, only, extra = [] }, die) {
  const reqPath = join(hyperframesDir, "audio_request.json");
  writeFileSync(reqPath, JSON.stringify(request, null, 2));
  const engine = process.env.HF_MEDIA_ENGINE || DEFAULT_ENGINE;
  if (!existsSync(engine)) die(`media audio engine not found at ${engine} (set $HF_MEDIA_ENGINE)`);
  const args = [
    engine,
    "--request",
    reqPath,
    "--hyperframes",
    hyperframesDir,
    "--out",
    neutral,
    "--only",
    only,
    ...extra,
  ];
  const r = spawnSync("node", args, { stdio: "inherit" });
  if (r.status !== 0) die(`media audio engine exited ${r.status}`);
}

// Engine neutral meta (id-keyed) → product-launch meta (frame-keyed) consumed by
// captions.mjs / assemble-index.mjs. id is the zero-padded frame number.
function toProductLaunchMeta(neutral) {
  const voices = (neutral.voices ?? []).map((v) => ({
    frame: Number(v.id),
    path: v.path,
    duration_s: v.duration_s,
    words: (v.words ?? []).map((w) => ({ id: w.id, text: w.text, start: w.start, end: w.end })),
  }));
  const bgm = neutral.bgm
    ? {
        path: neutral.bgm.path,
        volume: neutral.bgm.volume,
        query: neutral.bgm.query ?? null,
        duration_s: neutral.bgm.duration_s ?? null,
      }
    : null;
  // bgm_pending must survive the neutral → skill translation. A detached generate
  // (Lyria/MusicGen) leaves `bgm: null, bgm_pending: true` until the track lands; dropping the
  // flag makes "not ready yet" indistinguishable from "silent by design", so a later
  // `fetch-sfx` snapshot turns a still-generating bed into no music at all with no signal.
  const bgmPending = !!neutral.bgm_pending;
  const sfx = (neutral.sfx ?? []).map((s) => ({
    frame: Number(s.id),
    file: s.file,
    offset_s: s.offset_s ?? 0,
    duration_s: s.duration_s ?? 1,
    volume: s.volume ?? 0.35,
  }));
  return { bgm, bgm_pending: bgmPending, voices, sfx };
}

// ── generate (TTS + BGM) ────────────────────────────────────────────────────
function runGenerate(argv) {
  const die = (m) => {
    console.error(`✗ audio generate: ${m}`);
    process.exit(1);
  };
  const hyperframesDir = resolve(flag(argv, "hyperframes", "."));
  const storyboardPath = resolve(flag(argv, "storyboard", join(hyperframesDir, "STORYBOARD.md")));
  const scriptPath = resolve(flag(argv, "script", join(hyperframesDir, "SCRIPT.md")));
  const outPath = resolve(flag(argv, "out", join(hyperframesDir, "audio_meta.json")));
  const userVoice = flag(argv, "voice", null);
  const speed = Number(flag(argv, "speed", "1.0")) || 1.0;

  if (!existsSync(storyboardPath)) die(`STORYBOARD.md not found at ${storyboardPath}`);
  const manifest = parseStoryboard(readFileSync(storyboardPath, "utf8"));
  const g = manifest.globals;

  const lines = existsSync(scriptPath)
    ? parseScript(readFileSync(scriptPath, "utf8")).map((l) => ({
        id: pad2(l.frame),
        text: l.text,
      }))
    : [];
  // The canonical fully-silent marker (SKILL.md Step 3.1): `music: none` in
  // the storyboard's top YAML block turns BGM off; combined with no SCRIPT.md
  // the project is fully silent — generate nothing and remove any stale meta
  // from a previous run (assemble treats an absent audio_meta.json as silent).
  const bgmOff =
    String(g.extra?.music ?? "")
      .trim()
      .toLowerCase() === "none";
  if (bgmOff && !lines.length) {
    rmSync(outPath, { force: true });
    rmSync(neutralPath(outPath), { force: true });
    console.log(
      "✓ audio generate: project marked silent (music: none, no SCRIPT.md) — nothing to generate",
    );
    return;
  }
  if (!lines.length) console.error("· no SCRIPT.md — silent film (BGM only)");

  // BGM mood: storyboard `music:` → message → arc → default. `mode: retrieve` is
  // strict here (no wait-bgm step downstream).
  const query = (g.extra && g.extra.music) || g.message || g.arc || "calm cinematic underscore";
  const request = {
    provider: "auto",
    speed,
    lines,
    bgm: bgmOff
      ? { mode: "none" }
      : { mode: "retrieve", query, blob: g.message || "", arc: g.arc || "" },
  };
  if (userVoice) request.voice = userVoice;

  const neutral = neutralPath(outPath);
  runEngine({ request, hyperframesDir, neutral, only: "tts,bgm" }, die);

  const meta = toProductLaunchMeta(JSON.parse(readFileSync(neutral, "utf8")));
  writeFileSync(outPath, JSON.stringify(meta, null, 2));
  console.log(
    `✓ audio generate: ${meta.voices.length} voice + ${meta.bgm ? "1 bgm" : "no bgm"} → ${outPath}`,
  );
}

// ── fetch-sfx ────────────────────────────────────────────────────────────────
function runFetchSfx(argv) {
  const die = (m) => {
    console.error(`✗ audio fetch-sfx: ${m}`);
    process.exit(1);
  };
  const hyperframesDir = resolve(flag(argv, "hyperframes", "."));
  const storyboardPath = resolve(flag(argv, "storyboard", join(hyperframesDir, "STORYBOARD.md")));
  const outPath = resolve(flag(argv, "audio-meta", join(hyperframesDir, "audio_meta.json")));

  if (!existsSync(storyboardPath)) die(`STORYBOARD.md not found at ${storyboardPath}`);
  const manifest = parseStoryboard(readFileSync(storyboardPath, "utf8"));

  // Per-frame `sfx:` cues (comma-separated) → engine lines carrying only sfx.
  // `filter(Boolean)` alone is not enough: a storyboard that spells "no SFX here" as
  // `sfx: none` reaches the engine as a cue literally NAMED "none", which then fails to
  // resolve. The absence sentinels are part of the storyboard vocabulary, so drop them.
  const SFX_NONE = new Set(["none", "no", "n/a", "na", "skip", "-", "—", "–"]);
  const lines = [];
  for (const f of manifest.frames) {
    const names = (f.extra?.sfx ?? "")
      .split(",")
      .map((s) => s.trim())
      .filter((s) => s && !SFX_NONE.has(s.toLowerCase()));
    if (names.length && f.number != null) lines.push({ id: pad2(f.number), sfx: names });
  }

  const neutral = neutralPath(outPath);
  const request = { lines, bgm: { mode: "none" } };
  // --only sfx is a MERGE, not an overwrite: the engine reads the existing neutral
  // sidecar (audio_engine_meta.json) and recomputes only the sfx section, so the
  // voices/bgm written by the earlier generate (--only tts,bgm) pass are preserved.
  runEngine({ request, hyperframesDir, neutral, only: "sfx" }, die);

  const meta = toProductLaunchMeta(JSON.parse(readFileSync(neutral, "utf8")));
  writeFileSync(outPath, JSON.stringify(meta, null, 2));
  console.log(`✓ audio fetch-sfx: ${meta.sfx.length} SFX cue(s) → ${outPath}`);
  // This pass rewrites audio_meta.json from the neutral sidecar. If a detached BGM generate is
  // still running, the bed it eventually writes is NOT folded back in — the snapshot we just
  // took has no music. Say so instead of leaving a silent film behind.
  if (meta.bgm_pending && !meta.bgm) {
    console.warn(
      "⚠ audio fetch-sfx: a detached BGM generate is still pending, so this snapshot has no bed. " +
        "Re-run `fetch-sfx` (or re-point audio_meta.json at the track) once it lands, before assembling.",
    );
  }
}

// ── sync-durations (local; rewrites STORYBOARD.md) ────────────────────────────
function runSyncDurations(argv) {
  const die = (m) => {
    console.error(`✗ audio sync-durations: ${m}`);
    process.exit(1);
  };
  const hyperframesDir = resolve(flag(argv, "hyperframes", "."));
  const audioMetaPath = resolve(flag(argv, "audio-meta", join(hyperframesDir, "audio_meta.json")));
  const storyboardPath = resolve(flag(argv, "storyboard", join(hyperframesDir, "STORYBOARD.md")));
  if (!existsSync(audioMetaPath)) die(`audio_meta.json not found at ${audioMetaPath}`);

  const meta = JSON.parse(readFileSync(audioMetaPath, "utf8"));
  const durByFrame = new Map();
  for (const v of meta.voices ?? []) {
    if (v.frame != null && v.duration_s) durByFrame.set(v.frame, v.duration_s);
  }

  // Read directly and handle ENOENT here, rather than an existsSync precheck —
  // the check→write pair (write-back below) is a TOCTOU race CodeQL flags.
  let storyboardRaw = "";
  try {
    storyboardRaw = readFileSync(storyboardPath, "utf8");
  } catch {
    die(`STORYBOARD.md not found at ${storyboardPath}`);
  }
  const lines = storyboardRaw.split(/\r?\n/);
  const FRAME_RE = /^#{2,3}\s+(?:frame|beat|scene)\b.*?(\d+)/i;
  let curFrame = null;
  let updated = 0;
  for (let i = 0; i < lines.length; i++) {
    const h = lines[i].match(FRAME_RE);
    if (h) {
      curFrame = Number(h[1]);
      continue;
    }
    if (curFrame != null && durByFrame.has(curFrame)) {
      const m = lines[i].match(/^(\s*[-*]\s+duration\s*:\s*).*/i);
      if (m) {
        lines[i] = `${m[1]}${durByFrame.get(curFrame)}s`;
        durByFrame.delete(curFrame);
        updated++;
      }
    }
  }
  writeFileSync(storyboardPath, lines.join("\n"));
  const missing = [...durByFrame.keys()];
  console.log(
    `✓ audio sync-durations: ${updated} frame duration(s) updated` +
      (missing.length ? ` · no \`- duration:\` line for frame(s) ${missing.join(", ")}` : ""),
  );
}

// ── dispatch ──────────────────────────────────────────────────────────────────
const sub = process.argv[2];
if (sub === "sync-durations") runSyncDurations(process.argv.slice(3));
else if (sub === "fetch-sfx") runFetchSfx(process.argv.slice(3));
else runGenerate(process.argv.slice(2)); // default: generate

#!/usr/bin/env node
// build-frame.mjs — Step 2 design system in ONE command. The LLM only chooses a
// preset; this does the deterministic rest: copy the preset's FRAME.md → frame.md,
// remix its colors/typography onto the project's brand tokens, copy the preset's
// caption-skin.html, and self-validate. "Strict on brand" is deterministic, so it's
// a script, not LLM hand-editing (which mis-copies hex / breaks keys).
//
//   node build-frame.mjs --preset capsule --hyperframes .
//     [--tokens capture/extracted/tokens.json]  [--preset-dir <abs path to frame-presets>]
//
// Remix rule — ONLY `colors:` values and `typography:` fontFamily change; keys,
// structure, geometry, and components are untouched:
//   colors — map brand tokens onto the preset's keys BY ROLE: the ink-role key takes
//            the brand ink (darkest/ink-named), the canvas-role key takes the brand
//            canvas (lightest), and every other color is repainted with the nearest
//            brand accent's hue+saturation while KEEPING its own lightness, so tint
//            families (sun / sun-soft / haze) stay a family. Empty brand colors → the
//            preset palette is kept (it is already a complete, good design).
//   fonts  — the preset's display family → the brand display font, its body family →
//            the brand body font, wherever they appear. Empty brand fonts → kept.

import {
  copyFileSync,
  existsSync,
  mkdirSync,
  readdirSync,
  readFileSync,
  writeFileSync,
} from "node:fs";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import {
  brandRolesFromStats,
  chroma,
  lum,
  parseColors,
  parseFonts,
  pickAccent,
  semanticColors,
  STATUS_ROLE_KEY,
  UA_DEFAULT_COLORS,
} from "./lib/tokens.mjs";

const __dirname = dirname(fileURLToPath(import.meta.url));
const argv = process.argv.slice(2);
const flag = (name, def) => {
  const i = argv.indexOf(`--${name}`);
  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
};
const die = (m) => {
  console.error(`✗ build-frame: ${m}`);
  process.exit(1);
};

const presetName = flag("preset", null);
const hyperframesDir = resolve(flag("hyperframes", "."));
const presetDir = resolve(
  flag("preset-dir", join(__dirname, "../../hyperframes-creative/frame-presets")),
);
const tokensPath = resolve(flag("tokens", join(hyperframesDir, "capture/extracted/tokens.json")));

if (!presetName) die("--preset <name> is required");
const presetFrame = join(presetDir, presetName, "FRAME.md");
if (!existsSync(presetFrame)) {
  const avail = existsSync(presetDir)
    ? readdirSync(presetDir, { withFileTypes: true })
        .filter((d) => d.isDirectory())
        .map((d) => d.name)
    : [];
  die(
    `no FRAME.md for preset "${presetName}" under ${presetDir}\n  available: ${avail.join(", ")}`,
  );
}

// ── HSL helpers (recolor = brand hue+sat, original lightness) ──────────────────
function hexToHsl(hex) {
  const m = /^#?([0-9a-fA-F]{6})$/.exec(String(hex).trim());
  if (!m) return null;
  const n = parseInt(m[1], 16);
  const r = ((n >> 16) & 255) / 255,
    g = ((n >> 8) & 255) / 255,
    b = (n & 255) / 255;
  const max = Math.max(r, g, b),
    min = Math.min(r, g, b),
    d = max - min;
  let h = 0;
  const l = (max + min) / 2;
  const s = d === 0 ? 0 : l > 0.5 ? d / (2 - max - min) : d / (max + min);
  if (d !== 0) {
    h = max === r ? (g - b) / d + (g < b ? 6 : 0) : max === g ? (b - r) / d + 2 : (r - g) / d + 4;
    h *= 60;
  }
  return { h, s, l };
}
function hslToHex(h, s, l) {
  h = (((h % 360) + 360) % 360) / 360;
  const hue = (p, q, t) => {
    t = (t + 1) % 1;
    if (t < 1 / 6) return p + (q - p) * 6 * t;
    if (t < 1 / 2) return q;
    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
    return p;
  };
  let r, g, b;
  if (s === 0) {
    r = g = b = l;
  } else {
    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
    const p = 2 * l - q;
    r = hue(p, q, h + 1 / 3);
    g = hue(p, q, h);
    b = hue(p, q, h - 1 / 3);
  }
  const to = (x) =>
    Math.round(x * 255)
      .toString(16)
      .padStart(2, "0")
      .toUpperCase();
  return `#${to(r)}${to(g)}${to(b)}`;
}
const hueDist = (a, b) => {
  const d = Math.abs(a - b) % 360;
  return d > 180 ? 360 - d : d;
};
function hexToRgb(hex) {
  const m = /^#?([0-9a-fA-F]{6})$/.exec(String(hex).trim());
  if (!m) return null;
  const n = parseInt(m[1], 16);
  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
}
const rgbToHsl = (r, g, b) =>
  hexToHsl("#" + [r, g, b].map((x) => Math.round(x).toString(16).padStart(2, "0")).join(""));
// Repaint a chromatic rgba()/rgb() tint with the brand accent's RGB, keeping its alpha.
// A near-neutral rgb (shadow / scrim overlay) is left untouched; a non-rgba string → null.
function remapRgbaToAccent(val, brAccent, brAccent2, prAccentHsl, prAccent2Hsl) {
  const m = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)\s*(?:[,/]\s*([\d.]+%?))?\s*\)$/i.exec(
    String(val).trim(),
  );
  if (!m) return null;
  const r = +m[1],
    g = +m[2],
    b = +m[3],
    a = m[4];
  if (Math.max(r, g, b) - Math.min(r, g, b) < 16) return null; // neutral overlay — keep as-is
  const src = rgbToHsl(r, g, b);
  const useSecond =
    brAccent2 &&
    prAccentHsl &&
    prAccent2Hsl &&
    src &&
    hueDist(src.h, prAccent2Hsl.h) < hueDist(src.h, prAccentHsl.h);
  const t = hexToRgb(useSecond ? brAccent2 : brAccent);
  if (!t) return null;
  return a !== undefined
    ? `rgba(${t[0]}, ${t[1]}, ${t[2]}, ${a})`
    : `rgb(${t[0]}, ${t[1]}, ${t[2]})`;
}

// ── brand tokens ──────────────────────────────────────────────────────────────
let brandColors = [];
let brandFonts = [];
let brandFontWeights = []; // weights the brand text font actually ships (tokens fonts[].weights)
let brandColorStats = []; // rich per-color usage stats (areaBg / interactiveBg / textCount …)
// Icon/glyph fonts capture surfaces as "fonts" — they are never the brand text face
// (webflow-icons, Font Awesome, icomoon …) and must not become display/body or contribute weights.
const ICON_FONT_PATTERN =
  /(?:^|[\s_-])icons?(?:[\s_-]|$)|icomoon|font\s*-?awesome|glyphicons?|material\s*icons|feather\s*icons|(?:icon|glyph).*font|font.*(?:icon|glyph)|^vidaxlfont$/i;
const isIconFont = (name) => ICON_FONT_PATTERN.test(String(name));
if (existsSync(tokensPath)) {
  try {
    const t = JSON.parse(readFileSync(tokensPath, "utf8"));
    brandColors = (t.colors ?? [])
      .map((c) => (typeof c === "string" ? c : (c?.hex ?? c?.value ?? "")))
      .map((c) => String(c).trim())
      .filter((c) => /^#?[0-9a-fA-F]{6}$/.test(c))
      .map((c) => (c.startsWith("#") ? c : `#${c}`));
    brandFonts = (t.fonts ?? [])
      .map((f) => (typeof f === "string" ? f : (f?.family ?? f?.name ?? "")))
      .map((f) => String(f).split(",")[0].replace(/['"]/g, "").trim())
      .filter(Boolean)
      .filter((f) => !isIconFont(f));
    // Union of the (non-icon) brand fonts' available weights — used to clamp the preset's
    // type ramp so a font shipping only 400/500 never faux-bolds a 600/700 heading.
    brandFontWeights = [
      ...new Set(
        (t.fonts ?? [])
          .filter((f) => f && typeof f === "object" && !isIconFont(f.family ?? f.name ?? ""))
          .flatMap((f) => (Array.isArray(f.weights) ? f.weights : []))
          .map((w) => parseInt(w, 10))
          .filter((w) => Number.isFinite(w)),
      ),
    ].sort((a, b) => a - b);
    brandColorStats = Array.isArray(t.colorStats) ? t.colorStats : [];
  } catch (e) {
    die(`tokens.json parse: ${e.message}`);
  }
}

let md = readFileSync(presetFrame, "utf8");
const presetColors = parseColors(md);
const summary = [];

// ── color remix ───────────────────────────────────────────────────────────────
if (brandColors.length && presetColors.length) {
  const pr = semanticColors(presetColors);
  // Brand roles: prefer the function-based reading of capture colorStats (canvas =
  // largest background, accent = top interactive bg, ink = dominant contrasting text).
  // Fall back to the legacy luminance/chroma heuristic only when stats are absent —
  // but pick the accent via pickAccent either way so a UA-default link color never wins.
  const br =
    brandRolesFromStats(brandColorStats, brandColors) ??
    (() => {
      // strip UA-default link colors so a stray <a> color can't become ink/canvas/accent
      const clean = brandColors.filter((h) => !UA_DEFAULT_COLORS.has(h.toUpperCase()));
      const s = semanticColors(clean.map((h, i) => [`c${i}`, h]));
      return {
        ink: s.ink,
        canvas: s.canvas,
        accent: pickAccent(brandColorStats, clean, [s.ink, s.canvas]) ?? s.accent,
        accent2: s.accent2,
      };
    })();
  if (!br.accent) die("accent 选取失败：品牌色里没有可用的强调色");
  if (chroma(br.accent) <= 40) {
    console.warn(
      `  ⚠ accent ${br.accent} 彩度很低 (${chroma(br.accent)}) — 确认这是品牌色而非中性/默认色`,
    );
  }
  // Map by LUMINANCE POLARITY. The preset's darker value takes the brand's darker value and
  // the lighter takes the lighter — UNLESS the brand's GROUND polarity differs from the
  // preset's. Every shipped preset is light-ground; a dark-mode brand (Linear, Vercel,
  // Raycast…) has its canvas darker than its ink (colorStats already resolved the real
  // ground as the largest-area background). On a polarity MISMATCH we INVERT the mapping so a
  // light preset becomes the dark brand (canvas↔ink swap) instead of forcing the brand onto
  // an off-brand light video; neutral/tint lightness is then mirrored (L→1−L) so the whole
  // palette flips to the brand's ground. Same-polarity (the common case) is unchanged.
  const darker = (a, b) => ((lum(a) ?? 0) <= (lum(b) ?? 0) ? a : b);
  const prDark = darker(pr.ink, pr.canvas);
  const prLight = prDark === pr.ink ? pr.canvas : pr.ink;
  const brDark = darker(br.ink, br.canvas);
  const brLight = brDark === br.ink ? br.canvas : br.ink;
  const presetGroundDark = (lum(pr.canvas) ?? 255) < (lum(pr.ink) ?? 0);
  const brandGroundDark = (lum(br.canvas) ?? 255) < (lum(br.ink) ?? 0);
  const invert = presetGroundDark !== brandGroundDark;
  const mapDark = invert ? brLight : brDark; // preset's dark value → this brand value
  const mapLight = invert ? brDark : brLight; // preset's light value → this brand value
  const flipL = (l) => (invert ? 1 - l : l); // mirror tint/neutral lightness when flipping
  const prAccentHsl = hexToHsl(pr.accent);
  const prAccent2Hsl = hexToHsl(pr.accent2);
  const newByKey = new Map();
  for (const [key, val] of presetColors) {
    const ph = hexToHsl(val);
    let next;
    if (val === prDark) next = mapDark;
    else if (val === prLight) next = mapLight;
    else if (STATUS_ROLE_KEY.test(key))
      // semantic status colors (green/red …) — the HUE carries the meaning; never repaint.
      // MUST precede the accent checks: a preset's red "negative" is often its 2nd-most-chromatic
      // color and would otherwise be claimed as accent2 and recolored to the brand hue.
      next = val;
    else if (val === pr.accent)
      next = br.accent; // primary accent → the EXACT brand color
    else if (pr.accent2 !== pr.accent && val === pr.accent2)
      next = br.accent2; // exact 2nd accent
    else if (!ph) {
      // rgba()/rgb() tint → repaint its rgb with the brand accent, keep alpha (a neutral
      // overlay is kept). A non-color non-hex value (var(), named) falls through unchanged.
      next = remapRgbaToAccent(val, br.accent, br.accent2, prAccentHsl, prAccent2Hsl) ?? val;
    } else if (chroma(val) < 16) {
      // NEUTRAL source (grey text-ladder, hairline borders) → keep it NEUTRAL. Apply at most a
      // whisper of the brand hue (sat ≤ 0.06); never the accent's full saturation — that is what
      // turned the grey ladder into saturated blue.
      const bh = hexToHsl(br.accent);
      next = bh ? hslToHex(bh.h, Math.min(ph.s, 0.06), flipL(ph.l)) : val;
    } else {
      // chromatic tint → repaint with the nearest brand accent's hue+sat, keep THIS color's
      // lightness so tint families stay families.
      const useSecond =
        pr.accent !== pr.accent2 &&
        prAccentHsl &&
        prAccent2Hsl &&
        hueDist(ph.h, prAccent2Hsl.h) < hueDist(ph.h, prAccentHsl.h);
      const bh = hexToHsl(useSecond ? br.accent2 : br.accent);
      next = bh ? hslToHex(bh.h, bh.s, flipL(ph.l)) : val;
    }
    if (next !== val) newByKey.set(key, next);
  }
  // rewrite only the value of each colors: line; everything else byte-identical.
  let inBlock = false;
  md = md
    .split(/\r?\n/)
    .map((line) => {
      if (/^colors:\s*$/.test(line)) {
        inBlock = true;
        return line;
      }
      if (inBlock && /^\S/.test(line)) inBlock = false;
      if (!inBlock) return line;
      const m = line.match(
        /^(\s+)([\w-]+):\s*(?:"[^"]*"|'[^']*'|#[0-9a-fA-F]{3,8}|rgba?\([^)]*\)|[^#\n]*?)(\s+#.*)?$/,
      );
      if (m && newByKey.has(m[2])) return `${m[1]}${m[2]}: "${newByKey.get(m[2])}"${m[3] ?? ""}`;
      return line;
    })
    .join("\n");
  summary.push(
    `colors: ${invert ? "INVERTED (dark-mode brand on light preset) · " : ""}dark ${prDark}→${mapDark}, light ${prLight}→${mapLight}, accent ${pr.accent}→${br.accent}` +
      ` (${newByKey.size}/${presetColors.length} keys repainted${brandColorStats.length ? ", via colorStats" : ""})`,
  );
} else {
  summary.push(
    brandColors.length
      ? "colors: preset has no parseable colors — kept"
      : "colors: no brand colors — preset palette kept",
  );
}

// ── font remix ────────────────────────────────────────────────────────────────
if (brandFonts.length) {
  const pf = parseFonts(md);
  const strip = (q) => (q ? q.replace(/^"|"$/g, "") : null);
  const pDisplay = strip(pf.display);
  const pBody = strip(pf.body);
  const pMono = strip(pf.mono);
  // A monospace brand face is for code / labels / chrome — never the reading display or body.
  // Split the brand fonts: the primary NON-mono family carries display AND body (the common
  // single-sans case, e.g. Inter for everything), and a captured mono (Berkeley Mono,
  // JetBrains Mono…) is routed onto the preset's mono role instead of turning the body
  // monospace. (Distinct display/body brands still resolve to a clean sans; hand-tune the
  // display in frame.md if a separate display face is wanted.)
  const isMonoFont = (n) =>
    /(?:^|[\s_-])mono(?:[\s_-]|$)|monospace|consol|courier|menlo|monaco|jetbrains|berkeley|space\s*mono|ibm\s*plex\s*mono|sf\s*mono|roboto\s*mono|source\s*code|fira\s*code|geist\s*mono|dm\s*mono/i.test(
      String(n),
    );
  const nonMono = brandFonts.filter((f) => !isMonoFont(f));
  const monoFonts = brandFonts.filter(isMonoFont);
  const bDisplay = nonMono[0] ?? brandFonts[0];
  const bBody = nonMono[0] ?? brandFonts[0];
  const bMono = monoFonts[0] ?? null;
  const escRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
  // Replace the preset family as a WHOLE WORD/PHRASE everywhere — frontmatter values,
  // component strings like "Space Grotesk 600", AND prose — case-sensitive with word
  // boundaries so a single-word family ("Inter") can never corrupt a substring
  // ("interactive"). Quote-exact replace alone missed names baked into longer strings + prose.
  const swapFamily = (from, to) => {
    if (from && to && from !== to) md = md.replace(new RegExp(`\\b${escRe(from)}\\b`, "g"), to);
  };
  swapFamily(pDisplay, bDisplay);
  if (pBody !== pDisplay) swapFamily(pBody, bBody);
  // route the brand mono onto the preset's mono role (only if the preset has a DISTINCT mono
  // family — never collapse body/display into mono)
  if (bMono && pMono && pMono !== pBody && pMono !== pDisplay) swapFamily(pMono, bMono);
  summary.push(
    `fonts: display ${pDisplay}→${bDisplay}, body ${pBody}→${bBody}` +
      (bMono && pMono && pMono !== pBody && pMono !== pDisplay ? `, mono ${pMono}→${bMono}` : ""),
  );
} else {
  summary.push("fonts: no brand fonts — preset fonts kept");
}

// ── stage preset-owned offline font faces ────────────────────────────────────
// PR ingestion has no captured brand fonts. Presets that own a type system must
// therefore carry their own licensed files instead of depending on a first-run
// Google Fonts fetch or a renderer-only embedding path that Studio workers cannot see.
const presetFontsDir = join(presetDir, presetName, "fonts");
if (existsSync(presetFontsDir)) {
  const fontSpecs = [
    ["EB Garamond", "EBGaramond", 400],
    ["EB Garamond", "EBGaramond", 700],
    ["Inter", "Inter", 400],
    ["Inter", "Inter", 700],
    ["JetBrains Mono", "JetBrainsMono", 400],
    ["JetBrains Mono", "JetBrainsMono", 700],
  ];
  const outDir = join(hyperframesDir, "assets/fonts");
  const faces = [];
  for (const [family, stem, weight] of fontSpecs) {
    const file = `${stem}-${weight}.woff2`;
    const source = join(presetFontsDir, file);
    if (!existsSync(source)) die(`preset font is missing: ${source}`);
    mkdirSync(outDir, { recursive: true });
    copyFileSync(source, join(outDir, file));
    faces.push(
      `@font-face{font-family:"${family}";font-weight:${weight};font-style:normal;font-display:block;src:url("assets/fonts/${file}") format("woff2");}`,
    );
  }
  md +=
    `\n\n## Font loading (preset-owned, offline)\n\n` +
    `These licensed faces are staged in \`assets/fonts/\`. Paste this block inside every frame template; do not link Google Fonts:\n\n` +
    "```html\n<style>\n" +
    faces.join("\n") +
    "\n</style>\n```\n";
  summary.push(`fonts: staged ${fontSpecs.length} preset face(s) for offline preview/render`);
}

// ── cap type weights to the brand font's available faces ──────────────────────
// The remix swaps the font FAMILY but keeps the preset's weights; a brand font that ships
// only e.g. 400/500 would faux-bold every 600/700 heading. Clamp each `typography:` weight
// to the NEAREST weight the brand font actually provides (tokens.json fonts[].weights).
if (brandFonts.length && brandFontWeights.length) {
  const avail = brandFontWeights;
  const nearest = (n) =>
    avail.reduce((best, w) => {
      const dw = Math.abs(w - n),
        db = Math.abs(best - n);
      return dw < db || (dw === db && w > best) ? w : best;
    }, avail[0]);
  let capped = 0;
  const cap = (num) => {
    const n = parseInt(num, 10);
    if (avail.includes(n)) return String(n);
    const c = nearest(n);
    if (c !== n) capped++;
    return String(c);
  };
  let inType = false;
  md = md
    .split(/\r?\n/)
    .map((line) => {
      if (/^typography:\s*$/.test(line)) {
        inType = true;
        return line;
      }
      if (inType && /^\S/.test(line)) inType = false;
      let out = line;
      // (a) structured `weight: NNN` in the typography ramp
      if (inType) out = out.replace(/(\bweight:\s*)(\d{3})\b/g, (m, pfx, num) => pfx + cap(num));
      // (b) a weight baked into a quoted `typography:` component value, e.g.
      //     cta-button → typography: "Basier Square 600"  (NNN not followed by a unit like px)
      out = out.replace(
        /(typography:\s*"[^"]*?\b)(\d{3})\b(?![a-z%])/gi,
        (m, pfx, num) => pfx + cap(num),
      );
      return out;
    })
    .join("\n");
  if (capped)
    summary.push(`fonts: capped ${capped} type weight(s) to brand faces {${avail.join(", ")}}`);
}

// ── brand-adaptation note ─────────────────────────────────────────────────────
// The remix fixes the NORMATIVE frontmatter, but the preset's PROSE still carries its
// original weight ranges / color-names. Prepend a short "frontmatter is truth" header so a
// reader (or frame worker) interprets any lingering preset prose THROUGH the brand values —
// instead of fragile per-sentence prose surgery.
if (brandFonts.length || (brandColors.length && presetColors.length)) {
  const bD = brandFonts[0];
  const bB = brandFonts[1] ?? brandFonts[0];
  const note =
    `## Brand adaptation (READ FIRST — the frontmatter is the source of truth)\n\n` +
    `This is the **${presetName}** preset remixed onto the captured brand. The YAML frontmatter above ` +
    `(colors · typography · components) is **normative and already correct — use it verbatim.** The prose ` +
    `below is the ORIGINAL preset's intent; read it THROUGH the frontmatter:\n\n` +
    (brandFonts.length
      ? `- **Fonts** — already set to **${bD}** (display) / **${bB}** (body); ignore any preset font name lingering in prose.\n`
      : "") +
    (brandFontWeights.length
      ? `- **Weights** — the brand font ships \`{${brandFontWeights.join(", ")}}\` only; every weight is clamped to these — ignore higher preset weights (e.g. 600/700) in prose.\n`
      : "") +
    `- **Colors** — use the frontmatter hex; preset color NAMES in prose (e.g. "cobalt", "cream") mean the remapped brand values.\n`;
  if (/^# .*$/m.test(md)) md = md.replace(/^# .*$/m, (m) => `${m}\n\n${note}`);
  else md = `${note}\n${md}`;
  summary.push("brand-adaptation note prepended");
}

// ── stage brand font files + emit @font-face ──────────────────────────────────
// A brand font is rarely a Google font, so renaming the family in frame.md is not enough:
// nothing loads the actual face. If the capture downloaded font files, copy them to
// assets/fonts/ under CLEAN, face-named names (so captions.mjs' family-prefix matcher
// finds them too) and append a ready-to-paste, ROOT-RELATIVE @font-face block to frame.md.
//
// The staged NAME is a contract, not cosmetics: captions.mjs derives each face's weight and
// style back out of it. So the name has to carry every axis that distinguishes one face from
// another, and the dedup key has to be the whole face. Naming on weight alone made Google's
// two-file Newsreader download (upright + italic, both scoring "Regular") collide on one
// slot: the italic sorts first, took the name, the upright was never staged, and the block
// below then asserted font-style:normal over italic bytes.
if (brandFonts.length) {
  const norm = (s) =>
    String(s)
      .toLowerCase()
      .replace(/[^a-z0-9]/g, "");
  const extOf = (f) => (f.match(/\.(woff2|woff|ttf|otf)$/i)?.[1] ?? "").toLowerCase();
  const FMT = { woff2: "woff2", woff: "woff", ttf: "truetype", otf: "opentype" };
  const weightInfo = (name) => {
    const s = name.toLowerCase();
    // A numeric axis is the font's own answer, so it beats the word heuristic. Fontsource
    // names every face that way and carries no weight WORD at all, so word-only parsing
    // scored a whole family "Regular" and staged exactly one of its faces.
    //
    // A weight token must not be buried inside a longer run: this reads capture files,
    // which are commonly hash-named, and "Newsreader-a1b200c3.woff2" is not a 200-weight
    // face. Hence a non-digit before (which also stops "2100" reading as 100) and no
    // alphanumeric after. "Roboto900.ttf" still parses.
    const numeric = /(?:^|[^0-9])([1-9]00)(?![0-9a-z])/.exec(s);
    if (numeric) return { n: Number(numeric[1]), w: numeric[1] };
    if (/black|heavy|ultra|extrabold/.test(s)) return { n: 800, w: "ExtraBold" };
    if (/semibold|demibold/.test(s)) return { n: 600, w: "SemiBold" };
    if (/bold/.test(s)) return { n: 700, w: "Bold" };
    if (/medium/.test(s)) return { n: 500, w: "Medium" };
    if (/light|thin/.test(s)) return { n: 300, w: "Light" };
    return { n: 400, w: "Regular" };
  };
  const styleOf = (name) => (/italic|oblique/i.test(name) ? "italic" : "normal");
  const fams = [...new Set(brandFonts)];
  const srcDirs = [
    join(hyperframesDir, "capture/assets/fonts"),
    join(hyperframesDir, "assets/fonts"),
  ].filter((d) => existsSync(d));
  const files = [];
  for (const d of srcDirs)
    for (const f of readdirSync(d).sort()) if (extOf(f)) files.push({ d, f });
  // Single family → all font files belong to it (the common captured case, hash-named files
  // included). Multiple families → assign each file to the longest family key its name contains.
  const ranked = [...fams].sort((a, b) => norm(b).length - norm(a).length);
  const famOf = (f) =>
    fams.length === 1 ? fams[0] : ranked.find((x) => norm(f).includes(norm(x)));
  const outDir = join(hyperframesDir, "assets/fonts");
  const faces = [];
  const stagedNames = new Set();
  for (const { d, f } of files) {
    const fam = famOf(f);
    if (!fam) continue;
    const { n, w } = weightInfo(f);
    const style = styleOf(f);
    const clean = `${fam.replace(/[^A-Za-z0-9]/g, "")}-${w}${style === "italic" ? "-Italic" : ""}.${extOf(f)}`;
    if (stagedNames.has(clean)) continue;
    mkdirSync(outDir, { recursive: true });
    if (!existsSync(join(outDir, clean))) copyFileSync(join(d, f), join(outDir, clean));
    stagedNames.add(clean);
    faces.push(
      `@font-face{font-family:"${fam}";font-weight:${n};font-style:${style};font-display:block;src:url("assets/fonts/${clean}") format("${FMT[extOf(f)]}");}`,
    );
  }
  if (faces.length) {
    md +=
      `\n\n## Font loading (auto-generated)\n\n` +
      `The brand font ships as local files in \`assets/fonts/\` — do NOT link Google Fonts for it. ` +
      `Paste this \`<style>\` into every frame's \`<head>\`/\`<template>\` (captions use the same files) ` +
      `so \`font-family\` resolves in preview, snapshot, and render alike:\n\n` +
      "```html\n<style>\n" +
      faces.join("\n") +
      "\n</style>\n```\n";
    summary.push(
      `fonts: staged ${stagedNames.size} face(s) → assets/fonts/ + @font-face in frame.md`,
    );
  }
}

// ── write frame.md ────────────────────────────────────────────────────────────
const framePath = join(hyperframesDir, "frame.md");
writeFileSync(framePath, md);

// ── copy caption-skin.html ────────────────────────────────────────────────────
const presetSkin = join(presetDir, presetName, "caption-skin.html");
let skinCopied = false;
if (existsSync(presetSkin)) {
  const skinDir = join(hyperframesDir, ".hyperframes");
  mkdirSync(skinDir, { recursive: true });
  copyFileSync(presetSkin, join(skinDir, "caption-skin.html"));
  skinCopied = true;
}

// ── self-validate ─────────────────────────────────────────────────────────────
const outColors = parseColors(md);
if (outColors.length !== presetColors.length) {
  die(`color keys changed (${presetColors.length}→${outColors.length}) — keys must be preserved`);
}
const outRoles = semanticColors(outColors);
const li = lum(outRoles.ink),
  lc = lum(outRoles.canvas);
// ink (type) and canvas (ground) must differ enough to READ — in EITHER direction. A
// light-mode spec has ink darker than canvas; a dark-mode spec (the polarity flip above)
// the reverse. Assert luminance SEPARATION, not a fixed polarity.
if (li != null && lc != null && Math.abs(li - lc) < 40) {
  die(
    `ink (${outRoles.ink}, lum ${li.toFixed(0)}) and canvas (${outRoles.canvas}, lum ${lc.toFixed(0)}) lack contrast — bad brand mapping`,
  );
}

console.log(`✓ build-frame: ${presetName} → ${framePath}`);
for (const s of summary) console.log(`  ${s}`);
console.log(
  `  .hyperframes/caption-skin.html: ${skinCopied ? "copied" : "preset ships none — captions will use the default pill"}`,
);
console.log(`  self-check: keys preserved, ink/canvas contrast ok ✓`);

#!/usr/bin/env node
// captions.mjs — build the captions sub-composition from STORYBOARD + audio_meta.
//
// One mode: `build`. Reads STORYBOARD.md (frame order + durations → cumulative
// frame starts) + audio_meta.json (voices[].words, frame-relative) → absolute-
// timed caption groups → writes:
//   compositions/captions.html  — a self-contained sub-composition the index
//        assembler mounts on its captions track (data-composition-id="captions").
//   caption_groups.json         — the computed groups (debug / inspection / --out).
//   caption-overrides.json      — an empty `[]` shim (silences the captions runtime's
//        validate-time fetch; only written when captions.html is).
// No narration / no words → legal skip: nothing written, assemble-index then omits
// the captions track (it keys off compositions/captions.html existence).
//
//   node captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json
//
// CAPTION LOOK — two sources, picked automatically:
//   1. PRESET SKIN (preferred). If a project-local `.hyperframes/caption-skin.html`
//      exists (Step 2 copies the chosen frame-preset's skin into the project), it is
//      the caption look.
//      It is a brand-token-strict skin with three reserved holes; this script fills them
//      and wraps the result in a <template> for the engine:
//        - `var GROUPS = [];`            → the computed caption groups
//        - `var DURATION = 0;` + data-duration="0" (and data-width/height="0") → real values
//        - `<style data-brand-tokens></style>` → :root tokens derived from the project's
//          frame.md (colors + fonts), mapped to a fixed semantic vocab every skin shares:
//          --cap-ink / --cap-canvas / --cap-accent / --cap-accent-2 / --font-display /
//          --font-body, plus --cap-band-top / --cap-band-height (the keep-out band).
//      So the brand-token overlay from Step 2 flows into the captions automatically.
//   2. DEFAULT (fallback). No skin file → the built-in Roboto/black pill (buildCaptionsHtml).
//
// Grouping mirrors the proven heuristics (frame boundary · sentence-end punct ·
// silence gap · density-aware word cap); word timings come inline from audio_meta.

import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { parseStoryboard } from "./lib/storyboard.mjs";
import { captionBand, parseFormat } from "./lib/dimensions.mjs";
import { parseColors, parseFonts, semanticColors } from "./lib/tokens.mjs";

const flag = (argv, name, def) => {
  const i = argv.indexOf(`--${name}`);
  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
};
const r3 = (x) => Number(x.toFixed(3));

// ── grouping params ───────────────────────────────────────────────────────────
const SILENCE_GAP = 0.18; // s of silence between words → split
const TAIL_PAD = 0.12; // s the group lingers after its last word
const SENT_END = /[.?!,;:—]$/;
const DENSITY_WINDOW = 1.0; // s window for words/sec density
function wordCap(density) {
  return density > 3.5 ? 2 : density > 2.5 ? 3 : 4;
}

function runBuild(argv) {
  const skip = (reason) => {
    console.log(`captions: skipped (${reason})`);
    process.exit(0);
  };
  const die = (m) => {
    console.error(`✗ captions build: ${m}`);
    process.exit(1);
  };

  const hyperframesDir = resolve(flag(argv, "hyperframes", "."));
  const storyboardPath = resolve(flag(argv, "storyboard", join(hyperframesDir, "STORYBOARD.md")));
  const audioMetaPath = resolve(flag(argv, "audio-meta", join(hyperframesDir, "audio_meta.json")));
  const outPath = resolve(flag(argv, "out", join(hyperframesDir, "caption_groups.json")));
  const htmlPath = join(hyperframesDir, "compositions/captions.html");
  const overridesPath = join(hyperframesDir, "caption-overrides.json");
  const skinArg = flag(argv, "skin", null);
  const hiddenSkinPath = join(hyperframesDir, ".hyperframes", "caption-skin.html");
  const legacySkinPath = join(hyperframesDir, "caption-skin.html");
  const skinPath = resolve(
    skinArg ?? (existsSync(hiddenSkinPath) ? hiddenSkinPath : legacySkinPath),
  );
  const framePath = resolve(flag(argv, "frame", join(hyperframesDir, "frame.md")));

  if (!existsSync(storyboardPath)) die(`STORYBOARD.md not found at ${storyboardPath}`);
  const manifest = parseStoryboard(readFileSync(storyboardPath, "utf8"));
  const { width: W, height: H } = parseFormat(manifest.globals.format);

  if (!existsSync(audioMetaPath)) skip("no audio_meta.json (silent film)");
  const meta = JSON.parse(readFileSync(audioMetaPath, "utf8"));
  if (!Array.isArray(meta.voices) || meta.voices.length === 0) skip("no narration");

  // cumulative frame starts (by frame number) + total duration, from STORYBOARD.
  const startByFrame = new Map();
  let acc = 0;
  for (const f of manifest.frames) {
    if (f.number != null) startByFrame.set(f.number, acc);
    acc += Number.isFinite(f.durationSeconds) ? f.durationSeconds : 0;
  }
  const total = r3(acc);

  // absolute word stream: frame start + frame-relative word timing.
  const words = [];
  for (const v of meta.voices) {
    const base = startByFrame.get(v.frame);
    if (base == null || !Array.isArray(v.words)) continue;
    for (const w of v.words) {
      const text = String(w.text ?? "").trim();
      if (!text || /^[.?!,;:—–-]+$/.test(text)) continue; // drop empties + bare punctuation
      if (!isFinite(w.start) || !isFinite(w.end)) continue;
      words.push({ text, start: r3(base + w.start), end: r3(base + w.end), frame: v.frame });
    }
  }
  words.sort((a, b) => a.start - b.start);
  if (words.length === 0) skip("no usable words");

  // density at i = words whose start falls within [w.start, w.start + WINDOW).
  const densityAt = (i) => {
    const t0 = words[i].start;
    let n = 0;
    for (let j = i; j < words.length && words[j].start < t0 + DENSITY_WINDOW; j++) n++;
    return n / DENSITY_WINDOW;
  };

  // group: split on frame change / silence gap / word cap; always flush after a
  // sentence-ending word.
  const groups = [];
  let cur = null;
  for (let i = 0; i < words.length; i++) {
    const w = words[i];
    const prev = cur && cur.words[cur.words.length - 1];
    const crossFrame = cur && w.frame !== cur.frame;
    const gap = prev && w.start - prev.end > SILENCE_GAP;
    const full = cur && cur.words.length >= cur.cap;
    if (!cur || crossFrame || gap || full) {
      if (cur) groups.push(cur);
      cur = { frame: w.frame, cap: wordCap(densityAt(i)), words: [] };
    }
    cur.words.push(w);
    if (SENT_END.test(w.text)) {
      groups.push(cur);
      cur = null;
    }
  }
  if (cur) groups.push(cur);

  // finalize: ids, start/end (tail-padded, clamped < next group's start), text.
  const finalized = groups.map((g, gi) => {
    const first = g.words[0];
    const last = g.words[g.words.length - 1];
    const next = groups[gi + 1];
    let end = r3(last.end + TAIL_PAD);
    if (next && next.words[0].start < end) end = r3(next.words[0].start);
    return {
      id: `caption-group-${gi}`,
      frame: g.frame,
      start: r3(first.start),
      end,
      text: g.words.map((w) => w.text).join(" "),
      words: g.words.map((w, wi) => ({
        id: `caption-word-${gi}-${wi}`,
        text: w.text,
        start: r3(w.start),
        end: r3(w.end),
      })),
    };
  });

  // ── write caption_groups.json ──
  mkdirSync(dirname(outPath), { recursive: true });
  writeFileSync(
    outPath,
    JSON.stringify({ total_duration_s: total, width: W, height: H, groups: finalized }, null, 2),
  );

  // ── write compositions/captions.html (preset skin if present, else default) ──
  mkdirSync(dirname(htmlPath), { recursive: true });
  let source;
  if (existsSync(skinPath)) {
    const tokens = frameTokensCss(framePath, H);
    const faces = brandFontFaces(framePath, hyperframesDir);
    const fonts = existsSync(framePath) ? parseFonts(readFileSync(framePath, "utf8")) : {};
    writeFileSync(
      htmlPath,
      buildFromSkin(
        readFileSync(skinPath, "utf8"),
        finalized,
        total,
        W,
        H,
        tokens,
        die,
        faces,
        fonts,
      ),
    );
    source = `preset skin (${skinPath.replace(hyperframesDir + "/", "")})`;
  } else {
    writeFileSync(htmlPath, buildCaptionsHtml(finalized, total, W, H));
    source = "default (built-in pill)";
  }

  // ── write caption-overrides.json shim ──
  // Atomic create-if-absent: `wx` throws if the file already exists (which we
  // ignore) — no existsSync→writeFileSync TOCTOU gap.
  try {
    writeFileSync(overridesPath, "[]\n", { flag: "wx" });
  } catch {
    /* overrides shim already present */
  }

  console.log(
    `✓ captions build: ${finalized.length} group(s) from ${words.length} words → compositions/captions.html (total ${total}s) · skin: ${source}`,
  );
}

// ── preset-skin path ────────────────────────────────────────────────────────
// Fill the skin's three reserved holes + the root's 0-placeholders, then wrap the
// fragment in a <template> (the engine clones template contents only). One generic
// fill works for every preset's skin — no per-skin transform.
//
// Every preset's skin is authored against ITS OWN fonts/metrics (broadside→Barlow @
// line-height 1.02, capsule→Bodoni, …). When the project's brand font differs (it
// almost always does), three things must be reconciled so ANY skin renders correctly
// for ANY brand — done here generically, not per-project:
//   · @font-face for the brand fonts (else the renderer can't supply them → fallback)
//   · the skin's preset-font FALLBACK literals (var(--font-x, "Barlow")) repointed to
//     the brand family, so no undeclared font name trips font_family_without_font_face
//   · a metric safety net: a heavier brand font overflows a tight preset line-height,
//     so the active-word highlight clips — a line-height floor + word padding fixes it
//   · data-composition-id + dimensions on the <template> root (skins lead with
//     <script>/<style>, so the root element must carry the id, not the first child)
function buildFromSkin(skin, groups, total, W, H, tokens, die, faces = "", fonts = {}) {
  const fillOnce = (src, re, repl, label) => {
    const n = (src.match(re) || []).length;
    if (n !== 1) die(`caption-skin.html: expected exactly one ${label}, found ${n}`);
    return src.replace(re, () => repl);
  };
  let out = skin;
  // Strip HTML doc-comments first. A skin's authoring comment can contain tag-like text
  // (broadside's literally says "<template>"), which the linter's tag scanner then picks
  // up as the root element → false root_missing_composition_id / root_missing_dimensions.
  // The comments are preview/authoring docs, not needed in the generated composition.
  // Strip in a fixpoint loop, not a single global pass: removing one comment can
  // re-form a marker from a nested/partial pair (e.g. <!--<!---->-->), which one
  // pass misses — CodeQL flags the single replace as incomplete sanitization.
  for (let prev = ""; prev !== out; ) {
    prev = out;
    out = out.replace(/<!--[\s\S]*?-->/g, "");
  }
  // brand :root tokens + @font-face for the brand fonts, both into the reserved hole
  out = fillOnce(
    out,
    /<style data-brand-tokens>\s*<\/style>/,
    `<style data-brand-tokens>\n${faces ? faces + "\n" : ""}${tokens}\n    </style>`,
    "<style data-brand-tokens></style> hole",
  );
  // Resolve the skin's font-family var()s to the brand family LITERAL. Two reasons:
  //  (1) the linter's used-font scanner naively comma-splits, so var(--x, "Brand") yields
  //      junk tokens ('var(--x', 'brand")') that never match the @font-face → a false
  //      font_family_without_font_face; a plain "Brand" literal matches the @font-face.
  //  (2) it drops the preset's own fallback name (Barlow / IBM Plex Mono / …), which has
  //      no @font-face in this project. The :root token stays for any other consumer.
  if (fonts.display)
    out = out.replace(/var\(\s*--font-display\s*(?:,\s*"[^"]*"\s*)?\)/g, fonts.display);
  if (fonts.body) out = out.replace(/var\(\s*--font-body\s*(?:,\s*"[^"]*"\s*)?\)/g, fonts.body);
  out = fillOnce(
    out,
    /var GROUPS = \[\];/,
    `var GROUPS = ${JSON.stringify(groups)};`,
    "`var GROUPS = [];` hole",
  );
  out = fillOnce(out, /var DURATION = 0;/, `var DURATION = ${total};`, "`var DURATION = 0;` hole");
  out = fillOnce(out, /data-duration="0"/, `data-duration="${total}"`, '`data-duration="0"` hole');
  out = fillOnce(out, /data-width="0"/, `data-width="${W}"`, '`data-width="0"` hole');
  out = fillOnce(out, /data-height="0"/, `data-height="${H}"`, '`data-height="0"` hole');
  // font-robust safety net — appended last so it wins the cascade over the skin's own
  // (preset-font-tuned) line-height. Kept SNUG (1.1) so the plate hugs the text. NO extra
  // word/pill padding: inspect's `text_box_overflow` on the highlight words is a cosmetic
  // false-positive here (heavy-glyph ink slightly exceeds the line box, but there's no
  // overflow:hidden — nothing is clipped); zeroing it would need an airy line-height that
  // balloons the pill, which is worse. Override only if a brand font genuinely clips.
  out += "\n<style>\n  .caption-line { line-height: 1.1 !important; }\n</style>";
  return `<template id="captions-template" data-composition-id="captions" data-width="${W}" data-height="${H}">\n${out.trim()}\n</template>\n`;
}

export { buildFromSkin };

// @font-face for the brand display/body fonts, matched from the project's font dirs
// (staged assets/fonts first, else capture/assets/fonts) by family-name prefix, with
// weight parsed from the filename. Paths are relative to compositions/captions.html.
// Returns "" when frame.md or font files are absent (then the skin's fallback applies).
function brandFontFaces(framePath, hyperframesDir) {
  if (!existsSync(framePath)) return "";
  const { display, body } = parseFonts(readFileSync(framePath, "utf8"));
  const families = [
    ...new Set([display, body].filter(Boolean).map((f) => f.replace(/^"|"$/g, ""))),
  ];
  if (!families.length) return "";
  const dirs = [
    // ROOT-RELATIVE — compositions are served with the project root as their base URL, so a
    // "../" prefix escapes the root (lint: invalid_parent_traversal_in_asset_path) and 404s in
    // Studio/preview. Mirror what the frame workers use for images.
    { abs: join(hyperframesDir, "assets/fonts"), rel: "assets/fonts" },
    { abs: join(hyperframesDir, "capture/assets/fonts"), rel: "capture/assets/fonts" },
  ].filter((d) => existsSync(d.abs));
  const weightOf = (n) => {
    const s = n.toLowerCase();
    // A numeric axis is the font's own answer, so it beats the word heuristic. Fontsource
    // names every face this way ("inter-latin-500-normal.woff2") and carries no weight
    // WORD at all, so word-only parsing collapsed a whole family onto 400 and shipped
    // exactly one of its faces.
    //
    // A weight token must not be buried inside a longer run: capture/assets/fonts holds
    // hash-named files, and "Newsreader-a1b200c3.woff2" is not a 200-weight face. Hence a
    // non-digit before (which also stops "2100" reading as 100) and no alphanumeric after.
    // "Roboto900.ttf" still parses — requiring separators on both sides would have lost it.
    const numeric = /(?:^|[^0-9])([1-9]00)(?![0-9a-z])/.exec(s);
    if (numeric) return Number(numeric[1]);
    if (/black|heavy|ultra|extrabold/.test(s)) return 800;
    if (/semibold|demibold/.test(s)) return 600; // before /bold/ — "demibold" contains "bold"
    if (/bold/.test(s)) return 700;
    if (/medium/.test(s)) return 500;
    if (/light|thin/.test(s)) return 300;
    return 400; // book / regular / roman
  };
  // Weight is not the only axis in a filename. Google Fonts ships Newsreader as
  // "Newsreader-Italic-VariableFont_opsz,wght.ttf" + "Newsreader-VariableFont_opsz,wght.ttf",
  // and the italic sorts first — so without a style axis the italic file claimed the
  // family's ONLY 400 slot, the upright file was dropped as a duplicate, and the face
  // was declared with no `font-style`. @font-face is deliberately global (the composition
  // CSS scoper exempts it, and it has to be), so the whole document then rendered that
  // family in italics — captions italicizing every sibling composition.
  const styleOf = (n) => (/italic|oblique/i.test(n) ? "italic" : "normal");
  const fmtOf = (f) =>
    /\.woff2$/i.test(f)
      ? "woff2"
      : /\.woff$/i.test(f)
        ? "woff"
        : /\.ttf$/i.test(f)
          ? "truetype"
          : "opentype";
  // Normalize away ALL non-alphanumerics (spaces, underscores, hyphens) on BOTH the
  // family name and the filename. Real font files use "_" / "-" as word separators
  // ("TT_Norms_Pro_Bold.woff2"), so stripping only whitespace never matched them — the
  // family key "ttnormspro" failed `startsWith` against "tt_norms_pro_bold", and the
  // function silently returned "" → captions shipped with NO @font-face for any
  // underscore/hyphen-named brand font (e.g. TT Norms Pro), which is exactly the
  // font_family_without_font_face bug.
  const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
  const faces = [];
  const seen = new Set();
  const claimed = new Set(); // each file is claimed by the MOST SPECIFIC family only
  // Match the longest family key first so "TT Norms Pro" can't swallow the files that
  // belong to "TT Norms Pro Mono" (its key is a prefix of the longer one's).
  const ranked = [...families].sort((a, b) => norm(b).length - norm(a).length);
  for (const fam of ranked) {
    const key = norm(fam);
    for (const d of dirs) {
      let files = [];
      try {
        files = readdirSync(d.abs);
      } catch {
        continue;
      }
      for (const f of files.sort()) {
        if (!/\.(woff2|woff|ttf|otf)$/i.test(f)) continue;
        if (claimed.has(f)) continue; // a more specific family already took this file
        if (!norm(f.replace(/\.(woff2|woff|ttf|otf)$/i, "")).startsWith(key)) continue;
        const w = weightOf(f);
        const style = styleOf(f);
        const dedup = `${fam}-${w}-${style}`;
        if (seen.has(dedup)) continue; // one src per face; assets/fonts wins over capture
        seen.add(dedup);
        claimed.add(f);
        faces.push(
          `      @font-face { font-family: '${fam}'; src: url('${d.rel}/${f}') format('${fmtOf(f)}'); font-weight: ${w}; font-style: ${style}; font-display: block; }`,
        );
      }
    }
  }
  // Loud signal instead of a silent "". If frame.md named a brand font but no file
  // matched, the caption text WILL fall back to a generic font in the render — surface
  // the cause here (at build time) rather than letting it surface 2 steps later as a
  // font_family_without_font_face lint error disconnected from its root cause.
  if (!faces.length) {
    const where = dirs.length
      ? dirs.map((d) => d.rel).join(" / ")
      : "assets/fonts or capture/assets/fonts (neither exists)";
    console.warn(
      `  ⚠ captions: frame.md names font ${families.map((f) => `"${f}"`).join(", ")} ` +
        `but no matching .woff2/.woff/.ttf/.otf was found in ${where} — captions will fall back ` +
        `(text may render in the wrong font). Stage a font file whose name starts with the family ` +
        `(e.g. "TT Norms Pro" → TT_Norms_Pro_Bold.woff2) so it ships with the project.`,
    );
  }
  return faces.join("\n");
}

export { brandFontFaces }; // exported as a seam for unit testing

// frame.md colors:/typography: → a :root token block, mapped to the fixed semantic
// vocab every preset skin references. Robust to per-preset key names: colors are
// matched by name, then by luminance. Brand-token overlay (Step 2) flows through
// because the values come from the project's frame.md. No frame.md → band vars only.
function frameTokensCss(framePath, H) {
  const band = captionBand(H);
  const out = [];
  if (existsSync(framePath)) {
    const md = readFileSync(framePath, "utf8");
    const colors = parseColors(md);
    for (const [k, v] of colors) out.push(`      --${k}: ${v};`); // raw, for completeness
    const sem = semanticColors(colors);
    if (sem.ink) out.push(`      --cap-ink: ${sem.ink};`);
    if (sem.canvas) out.push(`      --cap-canvas: ${sem.canvas};`);
    if (sem.accent) out.push(`      --cap-accent: ${sem.accent};`);
    if (sem.accent2) out.push(`      --cap-accent-2: ${sem.accent2};`);
    const { display, body } = parseFonts(md);
    if (display) out.push(`      --font-display: ${display}, system-ui, serif;`);
    if (body) out.push(`      --font-body: ${body}, system-ui, sans-serif;`);
  }
  out.push(`      --cap-band-top: ${band.bandTopY}px;`);
  out.push(`      --cap-band-height: ${band.bandHeight}px;`);
  return `      :root {\n${out.join("\n")}\n      }`;
}

// ── default path (no preset skin) ─────────────────────────────────────────────
// Self-contained captions sub-composition. The <template> holds the band container
// + style AND the <script> (the HyperFrames loader only executes scripts INSIDE the
// cloned template — a sibling <script> after </template> never runs, so the timeline
// never registers and captions render blank). The script builds per-word spans and a
// paused, seek-safe GSAP timeline (opacity for group show/hide, a quick color tween
// per word for the karaoke highlight — no className flips, no JS state) and ends each
// group with a hard tl.set kill so an exit can't get stuck. gsap is loaded via CDN
// inside the template (matching the frame compositions). Band = captionBand(H).
function buildCaptionsHtml(groups, total, W, H) {
  const band = captionBand(H);
  const fs = Math.round(H * 0.038);
  const pad = Math.round(fs * 0.4);
  return `<template id="captions-template">
  <div
    data-composition-id="captions"
    data-width="${W}"
    data-height="${H}"
    data-duration="${total}"
    id="captions-root"
  >
    <div id="cap"></div>
  </div>
  <style>
    #captions-root {
      position: absolute;
      inset: 0;
      pointer-events: none;
    }
#cap {
      position: absolute;
      left: 0;
      right: 0;
      top: ${band.bandTopY}px;
      height: ${band.bandHeight}px;
      display: flex;
      align-items: center;
      justify-content: center;
    }
.caption-group {
      position: absolute;
      max-width: 80%;
      padding: ${pad}px ${Math.round(pad * 1.8)}px;
      background: rgba(0, 0, 0, 0.72);
      border-radius: ${Math.round(fs * 0.3)}px;
      font-family: Roboto, sans-serif;
      font-weight: 700;
      font-size: ${fs}px;
      line-height: 1.25;
      text-align: center;
      color: #fff;
      opacity: 0;
    }
.caption-word {
      color: rgba(255, 255, 255, 0.55);
    }
  </style>
  <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js" integrity="sha384-sG0Hv1tP1lZCk9KQmrIbY/XNwi+OY84GQqhMscbnsoBFqAz8KNCil1kvfL3Hbbk2" crossorigin="anonymous"></script>
  <script>
    (function () {
      var GROUPS = ${JSON.stringify(groups)};
      var cap = document.getElementById("cap");
      var tl = gsap.timeline({ paused: true });
      GROUPS.forEach(function (g) {
        var el = document.createElement("div");
        el.className = "caption-group";
        g.words.forEach(function (w) {
          var s = document.createElement("span");
          s.className = "caption-word";
          s.textContent = w.text + " ";
          el.appendChild(s);
        });
        cap.appendChild(el);
        tl.fromTo(el, { opacity: 0 }, { opacity: 1, duration: 0.18, overwrite: "auto" }, g.start);
        tl.to(el, { opacity: 0, duration: 0.12, overwrite: "auto" }, g.end);
        tl.set(el, { opacity: 0, visibility: "hidden" }, g.end + 0.12); // deterministic hard kill
        g.words.forEach(function (w, i) {
          tl.to(el.children[i], { color: "#ffffff", duration: 0.06 }, w.start);
        });
      });
      tl.to({}, { duration: ${total} }, 0); // full-span anchor
      window.__timelines = window.__timelines || {};
      window.__timelines["captions"] = tl;
    })();
  </script>
</template>
`;
}

if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
  const sub = process.argv[2];
  if (sub === "build" || sub === undefined) runBuild(process.argv.slice(sub === "build" ? 3 : 2));
  else {
    console.error(
      "usage: node captions.mjs build [--storyboard …] [--audio-meta …] [--hyperframes .]",
    );
    process.exit(2);
  }
}

import assert from "node:assert/strict";
import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import test from "node:test";
import { fileURLToPath } from "node:url";
import { brandFontFaces, buildFromSkin } from "./captions.mjs";

const presetsDir = fileURLToPath(
  new URL("../../hyperframes-creative/frame-presets/", import.meta.url),
);
const skins = readdirSync(presetsDir, { withFileTypes: true })
  .filter((entry) => entry.isDirectory())
  .map((entry) => ({
    name: entry.name,
    source: readFileSync(
      new URL(
        `../../hyperframes-creative/frame-presets/${entry.name}/caption-skin.html`,
        import.meta.url,
      ),
      "utf8",
    ),
  }))
  .filter(({ source }) => source.includes(".caption-word.is-active"));

for (const canvas of ["#f7f3e8", "#111827"]) {
  for (const skin of skins) {
    test(`${skin.name} preserves word-state rules on ${canvas}`, () => {
      const active = skin.source.match(/\.caption-word\.is-active\s*\{[^}]*\}/s)?.[0];
      const spoken = skin.source.match(/\.caption-word\.is-spoken\s*\{[^}]*\}/s)?.[0];
      assert.ok(active, "skin must define an active-word rule");
      assert.ok(spoken, "skin must define a spoken-word rule");

      const output = buildFromSkin(
        skin.source,
        [],
        1,
        1920,
        1080,
        `:root { --cap-canvas: ${canvas}; --cap-ink: #111111; --cap-accent: #ffcc00; }`,
        (message) => {
          throw new Error(message);
        },
      );

      assert.ok(output.includes(active));
      assert.ok(output.includes(spoken));
      assert.equal(output.match(/\.caption-word\.is-active\s*\{/g)?.length, 1);
      assert.equal(output.match(/\.caption-word\.is-spoken\s*\{/g)?.length, 1);
    });
  }
}

// @font-face is document-global on purpose — the composition CSS scoper exempts it, and it
// has to, since a face declaration cannot be scoped. That makes brandFontFaces the one part
// of the captions sub-composition whose output reaches every sibling composition, so it has
// to describe each face exactly: get an axis wrong and the whole document renders the brand
// family wrong.
function withFontProject(files, run) {
  const dir = mkdtempSync(join(tmpdir(), "hf-captions-fonts-"));
  try {
    mkdirSync(join(dir, "assets/fonts"), { recursive: true });
    for (const name of files) writeFileSync(join(dir, "assets/fonts", name), "");
    writeFileSync(
      join(dir, "frame.md"),
      'typography:\n  display: { fontFamily: "Newsreader", weight: 400 }\n  body: { fontFamily: "Inter", weight: 400 }\n',
    );
    return run(join(dir, "frame.md"), dir);
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
}

test("an italic file is declared italic, and never squats the family's upright slot", () => {
  // Google Fonts' own Newsreader download. The italic sorts first, so before the style axis
  // existed it claimed the family's only 400 slot, the upright was dropped as a duplicate,
  // and the face shipped with no font-style — italicizing every sibling composition that
  // used Newsreader.
  const faces = withFontProject(
    ["Newsreader-Italic-VariableFont_opsz,wght.ttf", "Newsreader-VariableFont_opsz,wght.ttf"],
    brandFontFaces,
  );
  const lines = faces.split("\n").filter((line) => line.includes("Newsreader"));
  assert.equal(lines.length, 2, "both the upright and the italic file must be declared");

  const upright = lines.find((line) => line.includes("Newsreader-VariableFont"));
  const italic = lines.find((line) => line.includes("Newsreader-Italic-VariableFont"));
  assert.ok(upright, "the upright file must survive");
  assert.match(upright, /font-style: normal/);
  assert.ok(italic, "the italic file must survive");
  assert.match(italic, /font-style: italic/);
});

test("a numeric weight in the filename is read as the weight", () => {
  // Fontsource names every face numerically and carries no weight WORD, so word-only
  // parsing scored the whole family 400 and shipped exactly one of its four faces.
  const faces = withFontProject(
    [
      "inter-latin-400-normal.woff2",
      "inter-latin-500-normal.woff2",
      "inter-latin-600-italic.woff2",
      "inter-latin-700-normal.woff2",
    ],
    brandFontFaces,
  );
  const lines = faces.split("\n").filter((line) => line.includes("Inter"));
  assert.equal(lines.length, 4, "each face is a distinct weight/style pair");
  for (const [file, weight, style] of [
    ["inter-latin-400-normal", 400, "normal"],
    ["inter-latin-500-normal", 500, "normal"],
    ["inter-latin-600-italic", 600, "italic"],
    ["inter-latin-700-normal", 700, "normal"],
  ]) {
    const line = lines.find((candidate) => candidate.includes(file));
    assert.ok(line, `${file} must be declared`);
    assert.match(line, new RegExp(`font-weight: ${weight};`));
    assert.match(line, new RegExp(`font-style: ${style};`));
  }
});

test("word-named weights still parse when the filename carries no numeric axis", () => {
  const faces = withFontProject(
    ["Newsreader_Bold.woff2", "Newsreader_Regular.woff2"],
    brandFontFaces,
  );
  const lines = faces.split("\n").filter((line) => line.includes("Newsreader"));
  assert.equal(lines.length, 2);
  assert.match(
    lines.find((line) => line.includes("Bold")),
    /font-weight: 700; font-style: normal/,
  );
  assert.match(
    lines.find((line) => line.includes("Regular")),
    /font-weight: 400; font-style: normal/,
  );
});

// build-frame.mjs stages captured brand fonts under a REWRITTEN name, and brandFontFaces
// derives the face's axes back out of that name. The two are a contract, and it is easy to
// break silently from either side: build-frame used to drop the style token while renaming,
// so an italic file arrived as "Newsreader-Regular.ttf" and was declared upright — leaving
// the document-global normal slot pointing at italic bytes even once brandFontFaces learned
// about styles. These two tests pin both ends of that contract.
test("the names build-frame.mjs stages round-trip back to the right face", () => {
  const faces = withFontProject(
    [
      "Newsreader-Regular.ttf",
      "Newsreader-Regular-Italic.ttf",
      "Inter-400.woff2",
      "Inter-600-Italic.woff2",
    ],
    brandFontFaces,
  );
  for (const [file, weight, style] of [
    ["Newsreader-Regular.ttf", 400, "normal"],
    ["Newsreader-Regular-Italic.ttf", 400, "italic"],
    ["Inter-400.woff2", 400, "normal"],
    ["Inter-600-Italic.woff2", 600, "italic"],
  ]) {
    const line = faces.split("\n").find((candidate) => candidate.includes(`/${file}'`));
    assert.ok(line, `${file} must be declared`);
    assert.match(line, new RegExp(`font-weight: ${weight};`));
    assert.match(line, new RegExp(`font-style: ${style};`));
  }
});

test("a weight token buried in a longer run is not read as a weight", () => {
  // capture/assets/fonts commonly holds hash-named files, and a hash is not a weight.
  const faces = withFontProject(
    ["Newsreader-a1b200c3.woff2", "Inter-2100.woff2", "Inter900.woff2"],
    brandFontFaces,
  );
  const weightOf = (file) =>
    Number(/font-weight: (\d+);/.exec(faces.split("\n").find((l) => l.includes(file)))?.[1]);

  // "200" sits mid-run (…b200c3), so the word path decides: Regular.
  assert.equal(weightOf("Newsreader-a1b200c3.woff2"), 400);
  // 4-digit guard: "2100" must not read as 100.
  assert.equal(weightOf("Inter-2100.woff2"), 400);
  // ...but a trailing weight with no separator is still a weight.
  assert.equal(weightOf("Inter900.woff2"), 900);
});

// captions.mjs ships once per creation workflow because each skill installs standalone,
// and the three copies are meant to be byte-identical. This PR alone had to land the same
// two-axis fix in all three; a future one that lands in only one drifts silently.
test("captions.mjs is byte-identical across the three workflows that ship it", () => {
  const [first, ...rest] = ["product-launch-video", "faceless-explainer", "pr-to-video"].map(
    (skill) => ({
      skill,
      source: readFileSync(new URL(`../../${skill}/scripts/captions.mjs`, import.meta.url), "utf8"),
    }),
  );
  for (const other of rest) {
    assert.equal(other.source, first.source, `${other.skill} drifted from ${first.skill}`);
  }
});

test("every build-frame.mjs copy stages the style axis it promises", () => {
  for (const skill of ["product-launch-video", "faceless-explainer", "pr-to-video"]) {
    const source = readFileSync(
      new URL(`../../${skill}/scripts/build-frame.mjs`, import.meta.url),
      "utf8",
    );
    // The staged filename must carry the style, or the italic and upright faces of one
    // weight collide on a single name and only whichever sorts first survives.
    assert.match(
      source,
      /const clean = `\$\{fam\.replace\(\/\[\^A-Za-z0-9\]\/g, ""\)\}-\$\{w\}\$\{style === "italic" \? "-Italic" : ""\}\./,
      `${skill}/build-frame.mjs must keep the style token in the staged name`,
    );
    // ...and the emitted descriptor must report the real style, not a hardcoded normal.
    assert.doesNotMatch(
      source,
      /font-weight:\$\{n\};font-style:normal/,
      `${skill}/build-frame.mjs must not assert font-style:normal over captured bytes`,
    );
  }
});

#!/usr/bin/env node
// Step 1 — contributor avatar fetch (NETWORK; orchestrator-invoked).
//
// The counterpart to ingest.mjs: ingest is a pure offline transform, THIS is the
// one network step on the people front. It reads the people list ingest produced
// and downloads each contributor's GitHub avatar into assets/<login>.png,
// then rewrites people.json with `avatarFetched` flags so downstream (story-design)
// knows which avatars actually exist.
//
// Avatars + a credits/shipped-by scene are the ONE place the faceless default is
// relaxed. They are an OPTIONAL enhancement, so this script is best-effort:
//   - a missing/deleted user, a network blip, an offline run → log + skip
//   - it ALWAYS exits 0 (a failed avatar must never block the build)
//
// Network is constrained on purpose: only https GitHub avatar hosts are fetched
// (SSRF guard), and bytes are only ever written under the project dir (no path
// traversal), so a tampered people.json can't redirect the fetch or the write.
//
// Reads:
//   --people <path>      capture/extracted/people.json (from ingest.mjs)
// Writes:
//   assets/<login>.png    one per contributor whose avatar resolved
//   (rewrites people.json in place with avatarFetched: true/false)
//
// Flags: --project-dir .  --timeout 8000 (ms per request)
//   Avatars are written to <project-dir>/<person.avatarFile>, where avatarFile is
//   the project-root-relative "assets/<login>.png" — the SAME assets/ dir the frame
//   workers reference and assemble-index stages (lib/assets.mjs). Anchor on the
//   project root so the path stays under the project's assets/.
//
// Usage (orchestrator already cd'd into PROJECT_DIR, so --project-dir defaults to "."):
//   node fetch-people-avatars.mjs --people ./capture/extracted/people.json

import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync } from "node:fs";
import { resolve, join, dirname, sep } from "node:path";

const argv = process.argv.slice(2);
const flag = (name, def) => {
  const i = argv.indexOf(`--${name}`);
  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
};

const peoplePath = resolve(flag("people", "./capture/extracted/people.json"));
const projectDir = resolve(flag("project-dir", "."));
const TIMEOUT = parseInt(flag("timeout", "8000"), 10);

// SSRF guard: avatars only ever come from GitHub's avatar hosts, so refuse any
// other URL rather than fetching whatever string people.json happens to carry.
// `github.com/<login>.png` 302s to avatars.githubusercontent.com (redirect stays
// on-host, controlled by GitHub).
const AVATAR_HOSTS = new Set(["avatars.githubusercontent.com", "github.com", "www.github.com"]);
function isAllowedAvatarUrl(u) {
  let parsed;
  try {
    parsed = new URL(u);
  } catch {
    return false;
  }
  if (parsed.protocol !== "https:") return false;
  const host = parsed.hostname.toLowerCase();
  return AVATAR_HOSTS.has(host) || host.endsWith(".githubusercontent.com");
}

// Path guard: the written file must stay inside the project dir, so a crafted
// avatarFile ("../../etc/…") can't escape via join().
function isUnderProject(p) {
  const r = resolve(p);
  return r === projectDir || r.startsWith(projectDir + sep);
}

// Soft-exit helper — avatars are optional, so every early-out is exit 0.
function softExit(msg) {
  console.log(`• fetch-avatars: ${msg}`);
  process.exit(0);
}

if (!existsSync(peoplePath)) softExit(`no people.json at ${peoplePath} — skipping (no avatars)`);

let doc;
try {
  doc = JSON.parse(readFileSync(peoplePath, "utf8"));
} catch (e) {
  softExit(`people.json unreadable (${e.message}) — skipping`);
}

const people = Array.isArray(doc.people) ? doc.people : [];
if (!people.length) softExit("no contributors in people.json — skipping");

async function fetchOne(person) {
  const { login, avatarUrl } = person;
  if (!login || !avatarUrl) return "skip";
  if (!isAllowedAvatarUrl(avatarUrl)) {
    person.avatarFetched = false;
    console.log(`  (skip avatar @${login}: not a GitHub avatar URL)`);
    return "fail";
  }
  // avatarFile is project-root-relative ("assets/<login>.png"); anchor on the
  // project root so it stays under the project's assets/ dir.
  const dest = join(projectDir, person.avatarFile || `assets/${login}.png`);
  if (!isUnderProject(dest)) {
    person.avatarFetched = false;
    console.log(`  (skip avatar @${login}: avatar path escapes the project dir)`);
    return "fail";
  }
  mkdirSync(dirname(dest), { recursive: true });
  // Idempotent: a non-empty file from a prior run is reused (re-runs are free).
  if (existsSync(dest) && statSync(dest).size > 0) {
    person.avatarFetched = true;
    return "cached";
  }
  const ctrl = new AbortController();
  const timer = setTimeout(() => ctrl.abort(), TIMEOUT);
  try {
    const res = await fetch(avatarUrl, {
      signal: ctrl.signal,
      redirect: "follow", // github.com/<login>.png redirects to avatars.githubusercontent.com
      headers: { "User-Agent": "hyperframes-pr-to-video" },
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const buf = Buffer.from(await res.arrayBuffer());
    if (!buf.length) throw new Error("empty body");
    writeFileSync(dest, buf);
    person.avatarFetched = true;
    return "ok";
  } catch (e) {
    person.avatarFetched = false;
    console.log(`  (skip avatar @${login}: ${e.message})`);
    return "fail";
  } finally {
    clearTimeout(timer);
  }
}

let ok = 0;
let cached = 0;
let fail = 0;
// Sequential keeps it simple and gentle on github.com; the list is tiny (a PR's
// contributors), so latency is not a concern.
for (const person of people) {
  const r = await fetchOne(person);
  if (r === "ok") ok++;
  else if (r === "cached") cached++;
  else if (r === "fail") fail++;
}

// Persist avatarFetched flags so story-design can reference only real avatars.
try {
  writeFileSync(peoplePath, JSON.stringify(doc, null, 2) + "\n");
} catch (e) {
  console.log(`  (warn: could not rewrite people.json flags: ${e.message})`);
}

console.log(
  `✓ fetch-avatars: ${ok + cached}/${people.length} avatar(s) in assets/` +
    ` (${ok} new, ${cached} cached, ${fail} failed)`,
);
process.exit(0);

#!/usr/bin/env node
// Step 1 — PR fetch (deterministic; runs gh; large-PR-safe; NO scratch dir).
//
// Replaces a bare `gh pr view … > capture/pr.json` in the orchestrator. It folds
// the PR into the two artifacts ingest.mjs consumes:
//   capture/pr.json    the gh pr view core (title, body, author, refs, commits,
//                      reviews, comments, assignees, +/− stats, …) with its `files`
//                      list COMPLETED via a paginated `gh api .../pulls/N/files`
//                      call — `gh pr view --json files` truncates at ~100 files, so a
//                      big PR would otherwise lose the tail. Commits keep gh pr view's
//                      rich `authors[]` (co-authors) — only `files` needs the override.
//                      For MERGED PRs it also stamps a best-effort `shipped_version`
//                      (+ `version_source`) so the end card / cta doesn't invent one.
//   capture/diff.patch the full unified diff (`gh pr diff`).
//
// gh runs HERE so auth / not-found / private-repo errors surface with gh's own stderr
// and exit 1 (the orchestrator then stops). Intermediates are held in memory — this
// writes ONLY the two files above, so there is no `_ingest_tmp/` scratch to clean up
// (the previous "let the agent fetch in pieces" approach polluted videos/ and was
// non-deterministic). ingest.mjs stays a pure offline transform downstream.
//
// Usage:
//   node fetch-pr.mjs --pr "<url | owner/repo#N | N>" [--out-dir ./capture]
//
// Exit 0 = capture/pr.json + capture/diff.patch written + summary on stdout.
// Exit 1 = gh not authenticated / PR not found / pr view failed.

import { execFileSync } from "node:child_process";
import { mkdirSync, writeFileSync } from "node:fs";
import { join, resolve } from "node:path";

const argv = process.argv.slice(2);
const flag = (name, def) => {
  const i = argv.indexOf(`--${name}`);
  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
};
function die(msg) {
  console.error(`✗ fetch-pr.mjs: ${msg}`);
  process.exit(1);
}

const prRef = flag("pr", null);
if (!prRef) die('--pr "<url | owner/repo#N | N>" is required');
const outDir = resolve(flag("out-dir", "./capture"));

// Run gh, capture stdout. Returns { ok, stdout, stderr } — never throws (callers
// decide whether a failure is fatal). 64 MB buffer covers large diffs / file lists.
function ghTry(args) {
  try {
    const stdout = execFileSync("gh", args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
    return { ok: true, stdout, stderr: "" };
  } catch (e) {
    return {
      ok: false,
      stdout: (e.stdout || "").toString(),
      stderr: (e.stderr || e.message || "").toString().trim(),
    };
  }
}

// ── 0. auth — fail fast with gh's own hint ───────────────────────────────────
if (!ghTry(["auth", "status"]).ok) {
  die("gh is not authenticated — run: gh auth login");
}

// ── 1. core PR object (gh pr view) ───────────────────────────────────────────
const FIELDS = [
  "number",
  "title",
  "body",
  "author",
  "url",
  "baseRefName",
  "headRefName",
  "commits",
  "files",
  "additions",
  "deletions",
  "changedFiles",
  "labels",
  "reviews",
  "latestReviews",
  "comments",
  "assignees",
  "reviewDecision",
  "mergedBy",
  "state",
  "mergedAt",
].join(",");

const view = ghTry(["pr", "view", prRef, "--json", FIELDS]);
if (!view.ok) die(`gh pr view "${prRef}" failed (auth / not found / private?):\n${view.stderr}`);

let pr;
try {
  pr = JSON.parse(view.stdout);
} catch (e) {
  die(`gh pr view returned unparseable JSON (${e.message})`);
}

// ── 2. complete the files list via paginated gh api (the truncation fix) ──────
// gh pr view --json files caps at ~100 files; the REST endpoint paginates with no
// cap. --jq runs per page, so the output is NDJSON (one file object per line).
const number = pr.number;
const m = /github\.com\/([^/]+)\/([^/]+)\/pull\/\d+/.exec(pr.url || "");
const owner = m?.[1];
const repo = m?.[2];
let filesNote = `${Array.isArray(pr.files) ? pr.files.length : 0} (from pr view)`;
if (owner && repo && number != null) {
  const apiFiles = ghTry([
    "api",
    "--paginate",
    `repos/${owner}/${repo}/pulls/${number}/files`,
    "--jq",
    ".[] | {path: .filename, additions, deletions, status}",
  ]);
  if (apiFiles.ok) {
    const files = apiFiles.stdout
      .split("\n")
      .filter(Boolean)
      .map((l) => {
        try {
          return JSON.parse(l);
        } catch {
          return null;
        }
      })
      .filter(Boolean);
    if (files.length) {
      pr.files = files;
      if (pr.changedFiles == null || files.length > pr.changedFiles) pr.changedFiles = files.length;
      filesNote = `${files.length} (completed via gh api)`;
    }
  } else {
    console.error(
      `  (warn: gh api files failed — keeping pr view's files: ${apiFiles.stderr.split("\n")[0]})`,
    );
  }
} else {
  console.error("  (warn: could not parse owner/repo from PR url — keeping pr view's files)");
}

// ── 2.5 best-effort shipping version (MERGED PRs only) ───────────────────────
// The end card / cta ("upgrade to vN", "what's new in vN") wants a real version;
// a PR carries none, so the agent would otherwise guess. We resolve one here and
// stamp it onto pr.json as `shipped_version` (+ a `version_source` note that keeps
// it honest). `git tag --contains` isn't available on a remote-only fetch, so we
// use gh api proxies: the first release published at/after the merge is the first
// tag that can contain the merge commit; failing that, the default branch's
// package manifest version (unreleased); else null. Always best-effort — a lookup
// failure just leaves the fields null (the skill then falls back to the repo URL).
pr.shipped_version = null;
pr.version_source = null;
if (pr.state === "MERGED") {
  const mergedAt = pr.mergedAt ? Date.parse(pr.mergedAt) : NaN;

  // (a) earliest non-draft release published on/after the merge.
  if (owner && repo && !Number.isNaN(mergedAt)) {
    const rel = ghTry([
      "api",
      "--paginate",
      `repos/${owner}/${repo}/releases`,
      "--jq",
      ".[] | select(.draft == false) | {tag: .tag_name, published: .published_at}",
    ]);
    if (rel.ok) {
      let best = null;
      for (const line of rel.stdout.split("\n").filter(Boolean)) {
        let r;
        try {
          r = JSON.parse(line);
        } catch {
          continue;
        }
        if (!r?.tag || !r?.published) continue;
        const t = Date.parse(r.published);
        if (Number.isNaN(t) || t < mergedAt) continue;
        if (!best || t < best.t) best = { tag: r.tag, t };
      }
      if (best) {
        pr.shipped_version = best.tag;
        pr.version_source = "first release published at/after merge";
      }
    } else {
      console.error(`  (warn: gh api releases failed: ${rel.stderr.split("\n")[0]})`);
    }
  }

  // (b) fallback — default branch's package manifest version (change merged but not
  //     yet in a tagged release). Marked as unreleased so the skill doesn't present
  //     it as a shipped tag.
  if (pr.shipped_version == null && owner && repo) {
    const pkg = ghTry(["api", `repos/${owner}/${repo}/contents/package.json`, "--jq", ".content"]);
    if (pkg.ok && pkg.stdout.trim()) {
      try {
        const manifest = JSON.parse(Buffer.from(pkg.stdout.trim(), "base64").toString("utf8"));
        if (manifest?.version) {
          pr.shipped_version = String(manifest.version);
          pr.version_source = "default-branch package.json (unreleased)";
        }
      } catch {
        /* not JSON / no version — leave null */
      }
    }
  }
}

// ── 3. write capture/pr.json + capture/diff.patch ────────────────────────────
mkdirSync(outDir, { recursive: true });
const prJsonPath = join(outDir, "pr.json");
writeFileSync(prJsonPath, JSON.stringify(pr, null, 2) + "\n");

const diff = ghTry(["pr", "diff", prRef]);
const diffPath = join(outDir, "diff.patch");
if (diff.ok) {
  writeFileSync(diffPath, diff.stdout);
} else {
  // The brief still builds without the diff (ingest treats it as optional), so this
  // is a warning, not fatal — but surface it.
  console.error(
    `  (warn: gh pr diff failed — brief builds without it: ${diff.stderr.split("\n")[0]})`,
  );
}

// ── 4. summary ───────────────────────────────────────────────────────────────
const repoLabel = owner && repo ? `${owner}/${repo}` : "(repo?)";
console.log(
  [
    `✓ fetch-pr: ${repoLabel} PR #${number ?? "?"} — "${(pr.title || "").slice(0, 72)}"`,
    `  files: ${filesNote}; diff: ${diff.ok ? `${diff.stdout.length} chars` : "MISSING"}`,
    `  shipped_version: ${pr.shipped_version ?? "null"}${pr.version_source ? ` (${pr.version_source})` : ""}`,
    `  wrote ${prJsonPath}${diff.ok ? ` + ${diffPath}` : ""}`,
  ].join("\n"),
);

import assert from "node:assert/strict";
import { execFileSync } from "node:child_process";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import test from "node:test";

import { validateFrameHtml } from "./lib/frame-contract.mjs";

const scriptDir = dirname(new URL(import.meta.url).pathname);
const buildFrameScript = join(scriptDir, "build-frame.mjs");
const assembleScript = join(scriptDir, "assemble-index.mjs");
const transitionsScript = join(scriptDir, "transitions.mjs");

function write(path, contents) {
  mkdirSync(dirname(path), { recursive: true });
  writeFileSync(path, contents);
}

function validFrame(id = "01-valid", duration = 3) {
  return `<template id="${id}-template">
  <div data-composition-id="${id}" data-width="1920" data-height="1080" data-duration="${duration}">
    <div class="clip" data-start="0" data-duration="${duration}" data-track-index="0"></div>
    <style>#root { color: black; }</style>
    <script>window.__timelines = window.__timelines || {}; window.__timelines["${id}"] = gsap.timeline({ paused: true });</script>
  </div>
</template>`;
}

test("valid bare template fragment passes the shared frame contract", () => {
  assert.doesNotThrow(() =>
    validateFrameHtml(validFrame(), { expectedId: "01-valid", expectedDuration: 3 }),
  );
});

test("HTML5 unquoted root attributes are accepted", () => {
  assert.deepEqual(
    validateFrameHtml(
      `<template><div data-composition-id=01-valid data-duration=3></div></template>`,
      { expectedId: "01-valid", expectedDuration: 3 },
    ),
    { compositionId: "01-valid", duration: 3 },
  );
});

test("duration accepts decimal seconds but rejects alternate numeric syntaxes", () => {
  assert.doesNotThrow(() =>
    validateFrameHtml(
      `<template><div data-composition-id="01-valid" data-duration="3.25"></div></template>`,
    ),
  );
  for (const duration of ["0x10", "3e2", "Infinity"]) {
    assert.throws(
      () =>
        validateFrameHtml(
          `<template><div data-composition-id="01-valid" data-duration="${duration}"></div></template>`,
        ),
      /positive.*duration/i,
    );
  }
});

test("full HTML is rejected even when it contains a valid inner template", () => {
  const html = `<!doctype html><html><head></head><body>${validFrame()}</body></html>`;
  assert.throws(
    () => validateFrameHtml(html, { expectedId: "01-valid", expectedDuration: 3 }),
    /bare <template>|full HTML document/i,
  );
});

test("missing or mismatched composition id and duration fail explicitly", () => {
  assert.throws(
    () =>
      validateFrameHtml(`<template><div data-duration="3"></div></template>`, {
        expectedId: "01-valid",
        expectedDuration: 3,
      }),
    /composition id/i,
  );
  assert.throws(
    () =>
      validateFrameHtml(
        `<template><div data-composition-id="wrong" data-duration="3"></div></template>`,
        { expectedId: "01-valid", expectedDuration: 3 },
      ),
    /expected.*01-valid/i,
  );
  assert.throws(
    () =>
      validateFrameHtml(
        `<template><div data-composition-id="01-valid" data-duration="0"></div></template>`,
        { expectedId: "01-valid", expectedDuration: 3 },
      ),
    /positive.*duration/i,
  );
});

test("assembler rejects malformed worker output before writing index.html", () => {
  const project = mkdtempSync(join(tmpdir(), "p2v-frame-contract-"));
  write(
    join(project, "STORYBOARD.md"),
    `---\nformat: 1920x1080\n---\n\n## Frame 1 — Broken\n\n- duration: 3s\n- status: animated\n- src: compositions/frames/01-broken.html\n`,
  );
  write(
    join(project, "compositions", "frames", "01-broken.html"),
    `<!doctype html><html><body><div data-composition-id="01-broken" data-duration="3"></div></body></html>`,
  );

  assert.throws(
    () =>
      execFileSync(
        process.execPath,
        [assembleScript, "--storyboard", join(project, "STORYBOARD.md"), "--hyperframes", project],
        { encoding: "utf8", stdio: "pipe" },
      ),
    /bare <template>|full HTML document/i,
  );
  assert.equal(existsSync(join(project, "index.html")), false);
});

test("validated bare frames survive assembly and transition injection", () => {
  const project = mkdtempSync(join(tmpdir(), "p2v-frame-transition-"));
  write(
    join(project, "STORYBOARD.md"),
    `---\nformat: 1920x1080\n---\n\n## Frame 1 — First\n\n- duration: 3s\n- transition_in: cut\n- status: animated\n- src: compositions/frames/01-first.html\n\n## Frame 2 — Second\n\n- duration: 3s\n- transition_in: crossfade 0.4s\n- status: animated\n- src: compositions/frames/02-second.html\n`,
  );
  write(join(project, "compositions", "frames", "01-first.html"), validFrame("01-first", 3));
  write(join(project, "compositions", "frames", "02-second.html"), validFrame("02-second", 3));

  execFileSync(
    process.execPath,
    [assembleScript, "--storyboard", join(project, "STORYBOARD.md"), "--hyperframes", project],
    { encoding: "utf8" },
  );
  execFileSync(
    process.execPath,
    [
      transitionsScript,
      "inject",
      "--storyboard",
      join(project, "STORYBOARD.md"),
      "--hyperframes",
      project,
    ],
    { encoding: "utf8" },
  );
  const verified = execFileSync(
    process.execPath,
    [
      transitionsScript,
      "verify",
      "--storyboard",
      join(project, "STORYBOARD.md"),
      "--index",
      join(project, "index.html"),
    ],
    { encoding: "utf8" },
  );
  assert.match(verified, /1 transition\(s\) verified/);
  assert.doesNotThrow(() =>
    execFileSync(
      process.execPath,
      [assembleScript, "--storyboard", join(project, "STORYBOARD.md"), "--hyperframes", project],
      { encoding: "utf8" },
    ),
  );
});

test("Code editorial preset stages renderer-parity fonts for an empty PR token set", () => {
  const project = mkdtempSync(join(tmpdir(), "p2v-code-editorial-fonts-"));
  write(join(project, "capture", "extracted", "tokens.json"), '{"colors":[],"fonts":[]}');

  execFileSync(
    process.execPath,
    [buildFrameScript, "--preset", "code-editorial", "--hyperframes", project],
    { encoding: "utf8" },
  );

  const expected = [
    "EBGaramond-400.woff2",
    "EBGaramond-700.woff2",
    "Inter-400.woff2",
    "Inter-700.woff2",
    "JetBrainsMono-400.woff2",
    "JetBrainsMono-700.woff2",
  ];
  for (const name of expected) {
    const path = join(project, "assets", "fonts", name);
    assert.equal(existsSync(path), true, `${name} should be staged`);
    const magic = readFileSync(path).subarray(0, 4).toString("ascii");
    assert.equal(magic, "wOF2", `${name} should be a WOFF2 file`);
  }

  const frameMd = readFileSync(join(project, "frame.md"), "utf8");
  assert.match(frameMd, /@font-face\{font-family:"EB Garamond";font-weight:400/);
  assert.match(frameMd, /@font-face\{font-family:"Inter";font-weight:700/);
  assert.match(frameMd, /@font-face\{font-family:"JetBrains Mono";font-weight:400/);
  assert.doesNotMatch(frameMd, /fonts\.googleapis\.com/);
});

test("bundled Code editorial font licenses are shipped beside the assets", () => {
  const fontDir = resolve(
    scriptDir,
    "../../hyperframes-creative/frame-presets/code-editorial/fonts",
  );
  for (const family of ["eb-garamond", "inter", "jetbrains-mono"]) {
    assert.equal(existsSync(join(fontDir, `OFL-${family}.txt`)), true);
  }
});

#!/usr/bin/env node

// Thin wrapper over the shared packet builder in hyperframes-core — this file pins
// this workflow's paths plus its two behavioral differences: a code frame must carry
// an upstream-selected `### Source excerpt`, and code frames get a code-vocabulary
// excerpt appended to their packet. Everything else has one owner:
// ../../hyperframes-core/scripts/lib/frame-packets-core.mjs

import { existsSync, readFileSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import * as core from "../../hyperframes-core/scripts/lib/frame-packets-core.mjs";

const SKILL_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");

function sourceExcerpt(block) {
  const match = block.match(/^### Source excerpt\s*\n+(```[^\n]*\n[\s\S]*?\n```)/im);
  return match?.[1] ?? null;
}

function validateFrame(frame) {
  const codeFrame = /\bcode-[a-z0-9-]+\b/i.test(core.field(frame.block, "focal") ?? "");
  if (codeFrame && !sourceExcerpt(frame.block)) {
    throw new Error(`${frame.heading}: code frame requires an upstream-selected Source excerpt`);
  }
}

function codeVocabularySection(block) {
  const focal = core.field(block, "focal") ?? "";
  const codeId = focal.match(/\b(code-[a-z0-9-]+)\b/i)?.[1];
  if (!codeId) return "";
  const vocabPath = join(SKILL_DIR, "references", "code-vocabulary.md");
  if (!existsSync(vocabPath)) {
    return `\n## Code block\n\nUse registry block \`${codeId}\`.\n`;
  }
  const vocab = readFileSync(vocabPath, "utf8");
  const lines = vocab.split("\n");
  const exactToken = `\`${codeId.toLowerCase()}\``;
  const matchingLines = lines.filter((line) => line.toLowerCase().includes(exactToken));
  if (matchingLines.length === 0) {
    return `\n## Code block\n\nUse registry block \`${codeId}\`.\n`;
  }
  return `\n## Code block excerpt (${codeId})\n\n${matchingLines.join("\n").trim()}\n`;
}

const CONFIG = {
  animationDir: resolve(SKILL_DIR, "../hyperframes-animation"),
  corePath: resolve(SKILL_DIR, "../hyperframes-core/references/frame-worker-core.md"),
  deltaPath: resolve(SKILL_DIR, "sub-agents/frame-worker.md"),
  validateFrame,
  extraSections: codeVocabularySection,
};

export function buildRolePayload({ outDir }) {
  return core.buildRolePayload({ ...CONFIG, outDir });
}

export function buildFramePackets(options) {
  return core.buildFramePackets({ ...CONFIG, ...options });
}

if (core.isMainModule(import.meta.url)) core.runCli({ buildFramePackets, buildRolePayload });

#!/usr/bin/env node
// Step 1 — PR ingest (deterministic; no subagent; NO network).
//
// Pure transform. The orchestrator (SKILL.md Step 1) runs `gh` itself so auth /
// not-found / private-repo errors surface with gh's own stderr; THIS script never
// touches the network. It only folds the two gh artifacts into the synthetic
// capture package the shared Gen-B backend (build-frame / captions / assemble-index)
// expects — the same shape faceless-explainer's Step 1 writes by hand, so the
// whole downstream runs unchanged. `capture/extracted/` is kept (no website was
// captured — the PR is ingested into the same folder the engine reads by default).
//
// Reads:
//   --pr-json <path>   gh pr view --json number,title,body,author,url,baseRefName,
//                      headRefName,commits,files,additions,deletions,changedFiles,labels,
//                      reviews,latestReviews,comments,assignees,reviewDecision,mergedBy
//                      + fetch-pr.mjs's best-effort shipped_version / version_source
//   --diff <path>      gh pr diff (raw unified diff)  [optional — brief still builds without it]
// Writes (under --out-dir, default ./capture/extracted):
//   tokens.json        synthetic design tokens (colors:[] → code-editorial native palette)
//   visible-text.txt   the narrative SOURCE: a readable plain-text brief assembled
//                      from title + meta + people + body + commits + changed files + a
//                      budget-bounded selection of representative diff hunks.
//   people.json        the contributors (PR author / commit authors / reviewers /
//                      commenters / assignees — the PR `author` is only the opener, so
//                      commit authors from commits[].authors[] are tracked separately),
//                      bot-filtered + deduped, each with a GitHub avatar URL + intended
//                      assets/<login>.png path. The avatars themselves are
//                      downloaded by the orchestrator (fetch-people-avatars.mjs) — THIS
//                      script stays offline. people.json + the avatars are the ONE place
//                      the faceless default is relaxed: an optional credits/shipped-by close.
//
// The story-design subagent reads visible-text.txt for the narrative AND gets the
// full diff.patch separately for deep hunk selection — so this brief is curated,
// not exhaustive: noisy files (lockfiles / dist / maps) are deprioritised so real
// source hunks win the char budget.
//
// Usage:
//   node ingest.mjs --pr-json ./capture/pr.json --diff ./capture/diff.patch \
//                   --out-dir ./capture/extracted
//
// Exit 0 = tokens.json + visible-text.txt written + summary on stdout.
// Exit 1 = pr.json missing / unparseable (orchestrator should stop).

import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { resolve, join } from "node:path";

// ---------- argv ----------
const argv = process.argv.slice(2);
const flag = (name, def) => {
  const i = argv.indexOf(`--${name}`);
  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
};
function die(msg) {
  console.error(`✗ ingest.mjs: ${msg}`);
  process.exit(1);
}

const prJsonPath = resolve(flag("pr-json", "./capture/pr.json"));
const diffPath = flag("diff") ? resolve(flag("diff")) : resolve("./capture/diff.patch");
const outDir = resolve(flag("out-dir", "./capture/extracted"));

// Budgets — keep visible-text.txt readable and bounded for the story-design agent.
const MAX_BODY_CHARS = parseInt(flag("max-body-chars", "2600"), 10);
const MAX_DIFF_CHARS = parseInt(flag("max-diff-chars", "4800"), 10);
const MAX_HUNK_LINES = parseInt(flag("max-hunk-lines", "22"), 10); // per hunk, post-context-trim
const MAX_COMMITS = parseInt(flag("max-commits", "12"), 10);
const MAX_FILES_LISTED = parseInt(flag("max-files-listed", "40"), 10);

// Noisy paths whose diff bodies rarely teach anything — deprioritised in hunk
// selection (still listed in "Files changed" with their stats).
const NOISE_RX =
  /(^|\/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|npm-shrinkwrap\.json|go\.sum|Cargo\.lock|composer\.lock|Gemfile\.lock|poetry\.lock)$|\.(min\.js|min\.css|map|snap)$|(^|\/)(dist|build|out|vendor|node_modules|\.next|coverage)\//;

// ---------- read pr.json ----------
if (!existsSync(prJsonPath)) die(`pr.json not found at ${prJsonPath} (run gh pr view first)`);
let pr;
try {
  pr = JSON.parse(readFileSync(prJsonPath, "utf8"));
} catch (e) {
  die(`pr.json is not valid JSON (${e.message}) — check the gh pr view output`);
}

// ---------- read diff (optional) ----------
let diffRaw = "";
if (existsSync(diffPath)) {
  try {
    diffRaw = readFileSync(diffPath, "utf8");
  } catch {
    diffRaw = "";
  }
}

// ---------- derive scalars ----------
const number = pr.number ?? "?";
const title = (pr.title || `Pull request #${number}`).trim();
const url = pr.url || "";
const repo = (() => {
  const m = /github\.com\/([^/]+\/[^/]+)\/pull\//.exec(url);
  if (m) return m[1];
  if (pr.headRepository?.nameWithOwner) return pr.headRepository.nameWithOwner;
  return "";
})();
const author = pr.author?.login || pr.author?.name || "unknown";
const baseRef = pr.baseRefName || "base";
const headRef = pr.headRefName || "head";
const additions = pr.additions ?? 0;
const deletions = pr.deletions ?? 0;
const changedFiles = pr.changedFiles ?? (Array.isArray(pr.files) ? pr.files.length : 0);
const labels = Array.isArray(pr.labels)
  ? pr.labels.map((l) => (typeof l === "string" ? l : l?.name)).filter(Boolean)
  : [];

// ---------- people (author / reviewers / commenters / assignees) ----------
// Offline bot heuristic — gh gives reviewer/commenter authors as a bare `login`
// (no `is_bot`), so we filter by the GitHub `[bot]` suffix + a denylist of the
// review/CI bots that dominate org PRs. Best-effort: a bot that slips through
// just gets an avatar downloaded and can still be excluded by story-design.
const BOT_DENYLIST = new Set(
  [
    "claude",
    "graphite-app",
    "dependabot",
    "github-actions",
    "codecov",
    "codecov-commenter",
    "coderabbitai",
    "sonarcloud",
    "sonarqubecloud",
    "vercel",
    "netlify",
    "renovate",
    "snyk-bot",
    "greenkeeper",
    "mergify",
    "allcontributors",
    "imgbot",
    "pre-commit-ci",
    "deepsource-autofix",
    "sentry-io",
    "semgrep-app",
    "cubic-dev-ai",
    "gemini-code-assist",
    "copilot-pull-request-reviewer",
    "github-advanced-security",
    "restyled-io",
    "changeset-bot",
    "bundlemon",
  ].map((s) => s.toLowerCase()),
);
const isBot = (login) => {
  if (!login) return true;
  const l = login.toLowerCase();
  return l.endsWith("[bot]") || l.endsWith("-bot") || l.endsWith("[robot]") || BOT_DENYLIST.has(l);
};

// "author" = the PR opener; "committer" = wrote/co-authored commits in this PR
// (often differs from the opener — a teammate force-pushes the branch, or commits
// are co-authored). Commit authors are first-class contributors for a credits close.
const ROLE_ORDER = ["author", "committer", "reviewer", "commenter", "assignee"];
const peopleMap = new Map(); // login -> { login, name, roles:Set, reviewState, association, commitCount }
const botsFiltered = new Set();
// Returns the person record for a real (non-bot) login, creating it on first
// touch; records and drops bots. null means "skip this login". `name` is the
// GitHub display name (e.g. "Miguel Angel Simon Sierra") — gh only hands this
// over for author/commits/mergedBy, not reviewers/commenters/assignees, so it's
// filled in opportunistically and the first non-empty value wins.
function consider(login, name) {
  if (!login) return null;
  if (isBot(login)) {
    botsFiltered.add(login);
    return null;
  }
  if (!peopleMap.has(login))
    peopleMap.set(login, {
      login,
      name: null,
      roles: new Set(),
      reviewState: null,
      association: null,
      commitCount: 0,
    });
  const p = peopleMap.get(login);
  if (!p.name && name) p.name = name;
  return p;
}

const authorLogin = pr.author?.login || null;
{
  const p = consider(authorLogin, pr.author?.name);
  if (p) p.roles.add("author");
}

// Commit authors — the people who actually wrote the code. pr.commits[].authors[]
// carries login/name/email; co-authored commits list several. Counts drive ordering
// and the brief ("Name (@login, N commits)"). Authors with no GitHub login
// (email-only) can't be avatar'd, so they're skipped here.
for (const c of Array.isArray(pr.commits) ? pr.commits : []) {
  for (const a of Array.isArray(c?.authors) ? c.authors : []) {
    const p = consider(a?.login, a?.name);
    if (!p) continue;
    p.roles.add("committer");
    p.commitCount += 1;
  }
}

// Reviewers — prefer latestReviews (one row per reviewer, final state); fall back
// to reviews[] (all events → keep the last state per reviewer).
let reviewSource = Array.isArray(pr.latestReviews) ? pr.latestReviews : [];
if (!reviewSource.length && Array.isArray(pr.reviews)) {
  const lastByAuthor = new Map();
  for (const r of pr.reviews) {
    const lg = r?.author?.login;
    if (lg) lastByAuthor.set(lg, r); // later events overwrite earlier
  }
  reviewSource = [...lastByAuthor.values()];
}
for (const r of reviewSource) {
  const p = consider(r?.author?.login, r?.author?.name);
  if (!p) continue;
  p.roles.add("reviewer");
  if (r.state) p.reviewState = r.state;
  if (r.authorAssociation) p.association = r.authorAssociation;
}

for (const c of Array.isArray(pr.comments) ? pr.comments : []) {
  const p = consider(c?.author?.login, c?.author?.name);
  if (p) p.roles.add("commenter");
}
for (const a of Array.isArray(pr.assignees) ? pr.assignees : []) {
  const p = consider(a?.login, a?.name);
  if (p) p.roles.add("assignee");
}

const REVIEW_STATE_LABEL = {
  APPROVED: "approved",
  CHANGES_REQUESTED: "changes requested",
  COMMENTED: "commented",
  DISMISSED: "dismissed",
  PENDING: "pending",
};
const primaryRoleRank = (roles) => {
  for (let i = 0; i < ROLE_ORDER.length; i++) if (roles.includes(ROLE_ORDER[i])) return i;
  return ROLE_ORDER.length;
};
const people = [...peopleMap.values()]
  .map((p) => ({
    login: p.login,
    // Display name for narration/on-screen credits — GitHub logins read aloud
    // badly ("@miguAng18947550"). null when GitHub has no public name for this
    // user and fetch-people-avatars.mjs couldn't resolve one either; the credits
    // frame falls back to the login in that case.
    name: p.name || null,
    roles: ROLE_ORDER.filter((r) => p.roles.has(r)),
    commitCount: p.commitCount || 0,
    reviewState: p.reviewState || null,
    association: p.association || null,
    // Unauthenticated avatar endpoint — redirects to the user's avatar; the
    // orchestrator's fetch-people-avatars.mjs downloads it here.
    avatarUrl: `https://github.com/${encodeURIComponent(p.login)}.png?size=200`,
    avatarFile: `assets/${p.login}.png`,
    avatarFetched: false, // set true by fetch-people-avatars.mjs once downloaded
  }))
  .sort((a, b) => primaryRoleRank(a.roles) - primaryRoleRank(b.roles));

const reviewDecision = pr.reviewDecision || null;
const mergedByLogin = pr.mergedBy?.login || null;

// Best-effort shipping version stamped by fetch-pr.mjs (MERGED PRs only). Surfaced
// in the brief so the end card / cta cites a real version instead of inventing one;
// null means "no version known — the close names the repo URL only" (see story-design.md).
const shippedVersion = typeof pr.shipped_version === "string" ? pr.shipped_version : null;
const versionSource = typeof pr.version_source === "string" ? pr.version_source : null;

// ---------- clean body ----------
function cleanBody(raw) {
  if (!raw || typeof raw !== "string") return "";
  // Strip HTML comments (PR templates) to a fixpoint, so fragments left by one
  // pass can't reassemble into a new comment (CodeQL
  // js/incomplete-multi-character-sanitization).
  let t = raw;
  for (let prev = null; prev !== t; ) {
    prev = t;
    t = t.replace(/<!--[\s\S]*?-->/g, "");
  }
  t = t
    .replace(/\r\n/g, "\n")
    .replace(/\n{3,}/g, "\n\n")
    .trim();
  if (t.length > MAX_BODY_CHARS) {
    t = t.slice(0, MAX_BODY_CHARS).replace(/\s+\S*$/, "") + "\n…(description truncated)";
  }
  return t;
}
const body = cleanBody(pr.body);

// ---------- commits ----------
const commits = Array.isArray(pr.commits) ? pr.commits : [];
const commitLines = commits
  .map(
    (c) =>
      c?.messageHeadline || (c?.messageBody || "").split("\n")[0] || (c?.oid || "").slice(0, 7),
  )
  .filter(Boolean);

// ---------- files (from pr.json) ----------
const files = (Array.isArray(pr.files) ? pr.files : []).map((f) => ({
  path: f.path || f.filename || "",
  additions: f.additions ?? 0,
  deletions: f.deletions ?? 0,
}));

// ---------- parse the unified diff into per-file hunks ----------
function parseDiff(raw) {
  if (!raw) return new Map();
  const lines = raw.split("\n");
  const byPath = new Map(); // path -> { hunks: string[][] }
  let curPath = null;
  let curHunk = null;
  const ensure = (p) => {
    if (!byPath.has(p)) byPath.set(p, { hunks: [] });
    return byPath.get(p);
  };
  for (const line of lines) {
    if (line.startsWith("diff --git ")) {
      // new file block; provisional path from "b/<path>" (refined by +++ below)
      const m = /^diff --git a\/(.+?) b\/(.+)$/.exec(line);
      curPath = m ? m[2] : null;
      curHunk = null;
      if (curPath) ensure(curPath);
      continue;
    }
    if (line.startsWith("+++ ")) {
      // authoritative new path ("+++ b/path" or "+++ /dev/null" for deletions)
      const p = line.slice(4).replace(/^b\//, "").trim();
      if (p && p !== "/dev/null") {
        curPath = p;
        ensure(curPath);
      }
      continue;
    }
    if (line.startsWith("--- ")) continue;
    if (line.startsWith("@@")) {
      if (!curPath) continue;
      curHunk = [line];
      ensure(curPath).hunks.push(curHunk);
      continue;
    }
    if (curHunk && curPath) {
      // body line of the current hunk (context / + / -); ignore the trailing
      // "\ No newline at end of file" sentinel
      if (line.startsWith("\\")) continue;
      curHunk.push(line);
    }
  }
  return byPath;
}
const diffByPath = parseDiff(diffRaw);

// Render a single hunk, trimmed: keep the @@ header + all +/- lines, but cap
// surrounding context to keep signal high and stay inside the line budget.
function renderHunk(hunk) {
  const header = hunk[0];
  const bodyLines = hunk.slice(1);
  const kept = [];
  for (const l of bodyLines) {
    if (l.startsWith("+") || l.startsWith("-")) kept.push(l);
    else if (kept.length && kept[kept.length - 1] !== "  ⋯") {
      // collapse runs of context into a single marker (only between changes)
      if (kept.some((k) => k.startsWith("+") || k.startsWith("-"))) kept.push("  ⋯");
    }
  }
  // drop a trailing context marker
  while (kept.length && kept[kept.length - 1] === "  ⋯") kept.pop();
  let out = [header.replace(/\s*$/, "")];
  out = out.concat(kept.slice(0, MAX_HUNK_LINES));
  if (kept.length > MAX_HUNK_LINES)
    out.push(`  …(+${kept.length - MAX_HUNK_LINES} more changed lines)`);
  return out.join("\n");
}

// ---------- rank files for the representative-diff section ----------
// real source first (non-noise, by total churn desc), noisy files last.
const ranked = [...files]
  .filter((f) => f.path && diffByPath.has(f.path))
  .sort((a, b) => {
    const an = NOISE_RX.test(a.path) ? 1 : 0;
    const bn = NOISE_RX.test(b.path) ? 1 : 0;
    if (an !== bn) return an - bn;
    return b.additions + b.deletions - (a.additions + a.deletions);
  });
// include any diffed paths missing from files[] (rare; e.g. renames) at the tail
for (const p of diffByPath.keys()) {
  if (!ranked.find((f) => f.path === p)) ranked.push({ path: p, additions: 0, deletions: 0 });
}

// ---------- build the representative-diff section under the char budget ----------
const diffSections = [];
let diffChars = 0;
let filesShown = 0;
let filesOmitted = 0;
for (const f of ranked) {
  const entry = diffByPath.get(f.path);
  if (!entry || !entry.hunks.length) continue;
  const head = `### ${f.path}  (+${f.additions} / -${f.deletions})`;
  const rendered = entry.hunks.map(renderHunk).join("\n");
  const block = `${head}\n${rendered}`;
  if (diffChars + block.length > MAX_DIFF_CHARS && filesShown > 0) {
    filesOmitted++;
    continue;
  }
  diffSections.push(block);
  diffChars += block.length;
  filesShown++;
}

// ---------- assemble visible-text.txt ----------
const lines = [];
lines.push(`# ${title}`);
lines.push("");
const metaBits = [repo, `PR #${number}`, `by ${author}`].filter(Boolean);
lines.push(metaBits.join(" · "));
lines.push(
  `${baseRef} ← ${headRef} · +${additions} / -${deletions} across ${changedFiles} file(s)`,
);
if (labels.length) lines.push(`Labels: ${labels.join(", ")}`);
if (url) lines.push(`URL: ${url}`);
if (shippedVersion)
  lines.push(`Shipped in: ${shippedVersion}${versionSource ? ` (${versionSource})` : ""}`);
lines.push("");

// People & reviews — human context for an optional credits / shipped-by close.
// Avatars land in assets/<login>.png (downloaded by the orchestrator). Each
// person is labeled "Name (@login)" — the credits close speaks the name, the
// handle is display-only (never read aloud; see story-design.md).
const label = (p) => (p.name ? `${p.name} (@${p.login})` : `@${p.login}`);
if (people.length) {
  lines.push("## People & reviews");
  const authorPerson = people.find((p) => p.roles.includes("author"));
  if (authorPerson) lines.push(`Author (opened PR): ${label(authorPerson)}`);
  const committers = people.filter((p) => p.roles.includes("committer"));
  if (committers.length) {
    const parts = committers
      .slice()
      .sort((a, b) => b.commitCount - a.commitCount)
      .map(
        (p) =>
          `${label(p)}${p.commitCount ? ` (${p.commitCount} commit${p.commitCount === 1 ? "" : "s"})` : ""}`,
      );
    lines.push(`Commit authors: ${parts.join(", ")}`);
  }
  const reviewers = people.filter((p) => p.roles.includes("reviewer"));
  if (reviewers.length) {
    const parts = reviewers.map(
      (p) =>
        `${label(p)}${p.reviewState ? ` (${REVIEW_STATE_LABEL[p.reviewState] || p.reviewState.toLowerCase()})` : ""}`,
    );
    lines.push(`Reviewers: ${parts.join(", ")}`);
  }
  const commentersOnly = people.filter(
    (p) =>
      p.roles.includes("commenter") && !p.roles.includes("author") && !p.roles.includes("reviewer"),
  );
  if (commentersOnly.length) lines.push(`Commenters: ${commentersOnly.map(label).join(", ")}`);
  if (reviewDecision) lines.push(`Review decision: ${reviewDecision}`);
  if (mergedByLogin) lines.push(`Merged by: @${mergedByLogin}`);
  lines.push(`Avatars: assets/<login>.png (${people.length} contributor(s) — see people.json)`);
  if (botsFiltered.size) lines.push(`(bots filtered out: ${[...botsFiltered].join(", ")})`);
  lines.push("");
}

lines.push("## What the PR says");
lines.push(body || "(no description provided)");
lines.push("");

if (commitLines.length) {
  lines.push(`## Commits (${commitLines.length})`);
  for (const c of commitLines.slice(0, MAX_COMMITS)) lines.push(`- ${c}`);
  if (commitLines.length > MAX_COMMITS)
    lines.push(`- …(+${commitLines.length - MAX_COMMITS} more)`);
  lines.push("");
}

if (files.length) {
  lines.push(`## Files changed (${files.length})`);
  const sortedFiles = [...files].sort(
    (a, b) => b.additions + b.deletions - (a.additions + a.deletions),
  );
  for (const f of sortedFiles.slice(0, MAX_FILES_LISTED)) {
    lines.push(`- ${f.path}  (+${f.additions} / -${f.deletions})`);
  }
  if (files.length > MAX_FILES_LISTED)
    lines.push(`- …(+${files.length - MAX_FILES_LISTED} more files)`);
  lines.push("");
}

if (diffSections.length) {
  lines.push("## Representative diff");
  lines.push("");
  lines.push(diffSections.join("\n\n"));
  if (filesOmitted > 0) {
    lines.push("");
    lines.push(
      `…(diff truncated to fit; ${filesOmitted} more changed file(s) omitted — see capture/diff.patch for the full change)`,
    );
  }
  lines.push("");
} else if (diffRaw) {
  lines.push("## Representative diff");
  lines.push("(diff present but no parseable hunks — see capture/diff.patch)");
  lines.push("");
}

const visibleText =
  lines
    .join("\n")
    .replace(/\n{3,}/g, "\n\n")
    .trim() + "\n";

// ---------- assemble tokens.json (FE scaffold shape; colors:[] → preset native palette) ----------
const oneLiner = (() => {
  const firstPara = body.split("\n").find((l) => l.trim().length > 0) || title;
  const s = `PR #${number}${repo ? ` in ${repo}` : ""}: ${firstPara}`.replace(/\s+/g, " ").trim();
  return s.length > 150 ? s.slice(0, 147).replace(/\s+\S*$/, "") + "…" : s;
})();
const tokens = {
  title,
  description: oneLiner,
  colors: [],
  fonts: [],
};

// ---------- assemble people.json ----------
const peopleDoc = {
  authorLogin,
  reviewDecision,
  mergedBy: mergedByLogin,
  botsFiltered: [...botsFiltered],
  people, // deduped, bot-filtered; each has roles[] + avatarUrl + avatarFile + avatarFetched
};

// ---------- write ----------
mkdirSync(outDir, { recursive: true });
const tokensOut = join(outDir, "tokens.json");
const textOut = join(outDir, "visible-text.txt");
const peopleOut = join(outDir, "people.json");
writeFileSync(tokensOut, JSON.stringify(tokens, null, 2) + "\n");
writeFileSync(textOut, visibleText);
writeFileSync(peopleOut, JSON.stringify(peopleDoc, null, 2) + "\n");

// ---------- summary ----------
const reviewerCount = people.filter((p) => p.roles.includes("reviewer")).length;
const committerCount = people.filter((p) => p.roles.includes("committer")).length;
console.log(
  [
    `✓ ingest: ${repo || "(repo?)"} PR #${number} — "${title}"`,
    `  +${additions} / -${deletions} across ${changedFiles} file(s); ${commitLines.length} commit(s)`,
    `  diff: ${filesShown} file(s) shown, ${filesOmitted} omitted (budget ${MAX_DIFF_CHARS} chars)`,
    `  people: ${people.length} contributor(s) (${committerCount} commit author(s), ${reviewerCount} reviewer(s)${reviewDecision ? `, decision ${reviewDecision}` : ""}${botsFiltered.size ? `; ${botsFiltered.size} bot(s) filtered` : ""})`,
    `  wrote ${textOut} (${visibleText.length} chars) + ${tokensOut} + ${peopleOut}`,
  ].join("\n"),
);

// assets.mjs — stage frame-named capture assets into assets/.
// Shared by stage-assets.mjs (Step 4 close, BEFORE the frame workers run) and
// assemble-index.mjs (Step 5, idempotent backstop). Only assets a frame names
// in `asset_candidates` are staged; unnamed assets never reach the project.
// asset_candidates value form: "assets/<basename> — desc; assets/… — …".

import { copyFileSync, existsSync, mkdirSync } from "node:fs";
import { basename, join } from "node:path";

export function basenamesFromCandidates(value) {
  if (typeof value !== "string") return [];
  return value
    .split(";")
    .map((seg) => seg.split(/\s+[—–-]\s+/)[0].trim()) // strip the " — description"
    .filter(Boolean)
    .map((p) => basename(p.replace(/^assets\//, "")));
}

// Copy each frame's asset_candidates from capture/{assets,assets/videos,
// assets/svgs, screenshots} into assets/. Already-staged files are left as is
// (first-wins), so calling this twice is safe. Returns { staged, wanted, anomalies }.
export function stageAssets({ hyperframesDir, frames }) {
  const wanted = new Set();
  for (const f of frames) {
    for (const b of basenamesFromCandidates(f.extra?.asset_candidates)) wanted.add(b);
  }
  const captureDirs = [
    join(hyperframesDir, "capture/assets"),
    join(hyperframesDir, "capture/assets/videos"), // videos download into a subdir
    join(hyperframesDir, "capture/assets/svgs"), // inline SVGs extract into a subdir
    join(hyperframesDir, "capture/screenshots"),
  ];
  const assetsDir = join(hyperframesDir, "assets");
  const anomalies = [];
  let staged = 0;
  if (wanted.size > 0) {
    mkdirSync(assetsDir, { recursive: true });
    for (const b of wanted) {
      const dest = join(assetsDir, b);
      if (existsSync(dest)) {
        staged++;
        continue;
      } // first-wins / already staged
      const src = captureDirs.map((d) => join(d, b)).find((p) => existsSync(p));
      if (src) {
        copyFileSync(src, dest);
        staged++;
      } else {
        anomalies.push(
          `asset "${b}" named by a frame but not found under capture/ — frame will 404 it`,
        );
      }
    }
  }
  return { staged, wanted, anomalies };
}

// dimensions.mjs — canvas size + caption-band geometry for the video
// pipeline. Single source of truth = the STORYBOARD frontmatter `format` global
// ("1920x1080" / "1080x1920" / "1080x1080", or a named orientation). Every
// script and the index assembler reads the size from here; none hardcodes it.

// Named orientation presets. Square/portrait are 1080-based so they share the
// long-edge pixel budget with landscape (same render-cost ballpark).
export const ORIENTATION_PRESETS = {
  landscape: { width: 1920, height: 1080 }, // 16:9 — default
  portrait: { width: 1080, height: 1920 }, // 9:16 — reels / shorts / TikTok
  square: { width: 1080, height: 1080 }, // 1:1 — feed
};

export const DEFAULT_DIMENSIONS = ORIENTATION_PRESETS.landscape;

function sane(w, h) {
  return Number.isFinite(w) && Number.isFinite(h) && w >= 240 && h >= 240 && w <= 8192 && h <= 8192;
}

// Parse a STORYBOARD `format` global into { width, height, source }. Accepts
// "WxH" (e.g. "1920x1080"; `x` or `×`, any inner spacing) or a named orientation;
// falls back to landscape so a storyboard with a missing/garbled format still
// renders (no behavior change vs the old landscape lock).
export function parseFormat(format) {
  const s = typeof format === "string" ? format.trim().toLowerCase() : "";
  if (ORIENTATION_PRESETS[s]) return { ...ORIENTATION_PRESETS[s], source: `orientation=${s}` };
  const m = s.match(/^(\d+)\s*[x×]\s*(\d+)$/);
  if (m) {
    const w = parseInt(m[1] ?? "", 10);
    const h = parseInt(m[2] ?? "", 10);
    if (sane(w, h)) return { width: w, height: h, source: "format" };
  }
  return { ...DEFAULT_DIMENSIONS, source: "default(landscape)" };
}

// Caption band geometry, derived from canvas height: the bottom ~16.67% (180px
// at h=1080). Frame content must end `safetyPx` above the band top. Holds even
// when captions are disabled (bottom-edge consistency).
export const CAPTION_BAND_FRACTION = 0.1667;
export function captionBand(height, safetyPx = 20) {
  const h = Number.isFinite(height) ? height : DEFAULT_DIMENSIONS.height;
  const bandHeight = Math.round(h * CAPTION_BAND_FRACTION);
  const bandTopY = h - bandHeight; // foreground must end at/above this y
  return { bandHeight, bandTopY, foregroundMaxY: bandTopY - safetyPx };
}

function fail(message) {
  throw new Error(`frame contract: ${message}`);
}

function attrValue(attrs, name) {
  const match = attrs.match(
    new RegExp(`(?:^|\\s)${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'=<>\`]+))`, "i"),
  );
  return match ? (match[1] ?? match[2] ?? match[3]) : null;
}

export function validateFrameHtml(html, { expectedId, expectedDuration } = {}) {
  const source = String(html ?? "");
  const trimmed = source.trim();
  if (/<!doctype|<\/?(?:html|head|body)\b/i.test(trimmed)) {
    fail("worker output must be one bare <template> fragment, not a full HTML document");
  }
  const opens = trimmed.match(/<template\b/gi) ?? [];
  const closes = trimmed.match(/<\/template\s*>/gi) ?? [];
  if (opens.length !== 1 || closes.length !== 1 || !/^<template\b/i.test(trimmed)) {
    fail("worker output must contain exactly one bare <template> fragment");
  }
  if (!/<\/template\s*>$/i.test(trimmed)) {
    fail("markup outside the closing </template> is not allowed");
  }

  const templateOpen = trimmed.match(/^<template\b[^>]*>/i)?.[0];
  if (!templateOpen) fail("template opening tag is malformed");
  const inner = trimmed.slice(
    templateOpen.length,
    trimmed.toLowerCase().lastIndexOf("</template>"),
  );
  const root = inner.match(/^\s*<([A-Za-z][\w:-]*)\b((?:[^>"']|"[^"]*"|'[^']*')*)>/);
  if (!root) fail("template must begin with one composition root element");
  const attrs = root[2];
  const compositionId = attrValue(attrs, "data-composition-id");
  if (!compositionId) fail("composition id is missing on the template root");
  if (expectedId && compositionId !== expectedId) {
    fail(`composition id ${JSON.stringify(compositionId)} does not match expected ${expectedId}`);
  }

  const durationRaw = attrValue(attrs, "data-duration");
  const decimalDuration = /^(?:\d+(?:\.\d+)?|\.\d+)$/.test(durationRaw ?? "");
  const duration = Number(durationRaw);
  if (!decimalDuration || !Number.isFinite(duration) || duration <= 0) {
    fail("root must declare a positive data-duration");
  }
  // Transition injection may extend an outgoing frame beyond its storyboard duration.
  // A shorter root is always invalid; a longer root remains safe to reassemble.
  if (Number.isFinite(expectedDuration) && duration < Number(expectedDuration) - 0.001) {
    fail(`root duration ${duration}s is shorter than expected ${expectedDuration}s`);
  }
  return { compositionId, duration };
}

// pad-frame-duration.mjs — keeps a frame's own #root/clip data-duration in
// sync with the padded index.html wrapper duration transitions.mjs computes.
//
// The frame's OWN internal file declares its #root/clip data-duration to the
// STORYBOARD's content-only length (frame-worker.md: duration is "fixed
// upstream"). When an outgoing transition pads the index.html WRAPPER's
// data-duration to cover the transition tail, the frame's own internal
// duration is left short — the render engine clip-gates the sub-composition's
// visible content at that shorter value, so content vanishes abruptly at
// content-end instead of fading gracefully through the wrapper's extended
// fade-out tween. Pad the frame's own file to match so both durations agree.

import { readFileSync, writeFileSync } from "node:fs";
import { resolve } from "node:path";

export function padFrameInternalDuration(hyperframesDir, frameSrc, frameId, newDuration) {
  const framePath = resolve(hyperframesDir, frameSrc);
  let html;
  try {
    html = readFileSync(framePath, "utf8");
  } catch (err) {
    if (err?.code === "ENOENT") return;
    throw err;
  }
  const tagRe = /<[a-z][\w:-]*\s[^<>]*?>/gi;
  let m;
  while ((m = tagRe.exec(html)) !== null) {
    const tag = m[0];
    if (!tag.includes(`data-composition-id="${frameId}"`)) continue;
    if (!/data-duration="[\d.]+"/.test(tag)) continue;
    const newTag = tag.replace(/data-duration="[\d.]+"/, `data-duration="${newDuration}"`);
    if (newTag === tag) return;
    writeFileSync(framePath, html.slice(0, m.index) + newTag + html.slice(m.index + tag.length));
    return;
  }
}

// storyboard.mjs — vendored lenient parser for STORYBOARD.md.
//
// Faithful plain-JS port of @hyperframes/core/storyboard
// (packages/core/src/storyboard/parseStoryboard.ts). Vendored because skills
// ship standalone: installed via `npx skills add`, a skill's scripts can't reach
// the monorepo's core package, and the core export points at .ts source that
// `node` (which runs these scripts) can't load. CANONICAL contract = the core
// parser + skills/hyperframes-core/references/storyboard-format.md; keep this in
// lockstep. Behavior: never throws, accepts freeform narrative, recognizes
// Frame/Beat/Scene headings at H2/H3, preserves unknown keys verbatim under
// `extra` (keys lowercased). Pure node — no deps.

export const FRAME_STATUSES = ["outline", "built", "animated"];
export const DEFAULT_FRAME_STATUS = "outline";

// Detection-only frame heading (ends at the keyword); ReDoS-hardened — keep as-is.
const FRAME_HEADING_RE = /^(#{2,3})[ \t]+(?:frame|beat|scene)\b/i;
const FRAME_TITLE_SEP_RE = /^[\s.:—-]+/;
const HEADING_LEVEL_RE = /^(#{1,6})\s+/;
const META_RE = /^\s*[-*]\s+([A-Za-z_][\w-]*)\s*:\s*(.+?)\s*$/;
const LEADING_INT_RE = /^(\d+)/;
const DURATION_NUM_RE = /(\d+(?:\.\d+)?)/;
const TRANSITION_KEYS = new Set(["transition_in", "transitionin", "transition"]);
const SCENE_KEYS = new Set(["scene", "description", "summary", "caption"]);
export const VOICEOVER_ALIASES = ["voiceover", "vo", "voice_over", "narration"];
const VOICEOVER_KEYS = new Set(VOICEOVER_ALIASES);

export function parseStoryboard(source) {
  const warnings = [];
  const { globals, bodyStartLine, body } = parseFrontmatter(source, warnings);
  const frames = parseFrames(body, bodyStartLine, warnings);
  return { globals, frames, warnings };
}

function emptyGlobals() {
  return { extra: {} };
}

function isFrameStatus(value) {
  return FRAME_STATUSES.includes(value);
}

// ── Frontmatter ─────────────────────────────────────────────────────────────
function findFrontmatterRange(lines, warnings) {
  let start = 0;
  while (start < lines.length && (lines[start] ?? "").trim() === "") start++;
  if ((lines[start] ?? "").trim() !== "---") return null;
  for (let i = start + 1; i < lines.length; i++) {
    if ((lines[i] ?? "").trim() === "---") return { start, end: i };
  }
  warnings.push({
    message: "Frontmatter opening '---' has no closing '---'; treating whole file as body.",
    line: start + 1,
  });
  return null;
}

function parseFrontmatterEntries(lines, start, end, warnings) {
  const globals = emptyGlobals();
  for (let i = start + 1; i < end; i++) {
    const raw = lines[i] ?? "";
    if (raw.trim() === "") continue;
    const colon = raw.indexOf(":");
    if (colon === -1) {
      warnings.push({
        message: `Ignored non key:value frontmatter line: "${raw.trim()}"`,
        line: i + 1,
      });
      continue;
    }
    const key = raw.slice(0, colon).trim().toLowerCase();
    assignGlobal(globals, key, stripQuotes(raw.slice(colon + 1).trim()));
  }
  return globals;
}

function parseFrontmatter(source, warnings) {
  const lines = source.split(/\r?\n/);
  const range = findFrontmatterRange(lines, warnings);
  if (!range) return { globals: emptyGlobals(), bodyStartLine: 1, body: source };
  const globals = parseFrontmatterEntries(lines, range.start, range.end, warnings);
  const body = lines.slice(range.end + 1).join("\n");
  return { globals, bodyStartLine: range.end + 2, body };
}

function assignGlobal(globals, key, value) {
  switch (key) {
    case "format":
      globals.format = value;
      break;
    case "message":
      globals.message = value;
      break;
    case "arc":
      globals.arc = value;
      break;
    case "audience":
      globals.audience = value;
      break;
    default:
      globals.extra[key] = value;
  }
}

// ── Frames ──────────────────────────────────────────────────────────────────
function openFrameSection(line, headingLine) {
  const match = FRAME_HEADING_RE.exec(line);
  if (!match) return null;
  const headingText = line.slice(match[0].length).replace(FRAME_TITLE_SEP_RE, "").trim();
  return { headingText, headingLine, level: (match[1] ?? "##").length, lines: [] };
}

function endsFrameSection(line, current) {
  if (!current) return false;
  const heading = HEADING_LEVEL_RE.exec(line);
  return heading !== null && (heading[1] ?? "").length <= current.level;
}

function parseFrames(body, bodyStartLine, warnings) {
  const lines = body.split(/\r?\n/);
  const sections = [];
  let current = null;
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i] ?? "";
    const opened = openFrameSection(line, bodyStartLine + i);
    if (opened) {
      sections.push(opened);
      current = opened;
    } else if (endsFrameSection(line, current)) {
      current = null;
    } else if (current) {
      current.lines.push(line);
    }
  }
  return sections.map((section, idx) => buildFrame(section, idx + 1, warnings));
}

function buildFrame(section, index, warnings) {
  const frame = { index, status: DEFAULT_FRAME_STATUS, narrative: "", extra: {} };
  const { number, title } = parseHeading(section.headingText);
  if (number !== undefined) frame.number = number;
  if (title) frame.title = title;

  const narrativeLines = [];
  for (const line of section.lines) {
    const meta = META_RE.exec(line);
    if (meta) {
      applyMeta(
        frame,
        (meta[1] ?? "").toLowerCase(),
        (meta[2] ?? "").trim(),
        section.headingLine,
        warnings,
      );
    } else {
      narrativeLines.push(line);
    }
  }
  frame.narrative = narrativeLines.join("\n").trim();
  return frame;
}

function parseHeading(text) {
  if (!text) return {};
  const intMatch = LEADING_INT_RE.exec(text);
  if (!intMatch) return { title: text };
  const number = Number.parseInt(intMatch[1] ?? "", 10);
  const rest = text
    .slice((intMatch[0] ?? "").length)
    .replace(/^[\s.:—-]+/, "")
    .trim();
  return { number, title: rest || undefined };
}

// Dispatch a recognized metadata key to its field, else stash under `extra`.
// Mirrors core's META_SETTERS map exactly (direct keys + alias sets).
function applyMeta(frame, key, value, headingLine, warnings) {
  switch (key) {
    case "duration":
      applyDuration(frame, value, headingLine, warnings);
      return;
    case "status":
      applyStatus(frame, value, headingLine, warnings);
      return;
    case "poster":
      applyPoster(frame, value);
      return;
    case "src":
      frame.src = value;
      return;
  }
  if (TRANSITION_KEYS.has(key)) {
    frame.transitionIn = value;
    return;
  }
  if (SCENE_KEYS.has(key)) {
    frame.scene = value;
    return;
  }
  if (VOICEOVER_KEYS.has(key)) {
    frame.voiceover = stripQuotes(value);
    return;
  }
  frame.extra[key] = value;
}

function applyPoster(frame, value) {
  const num = DURATION_NUM_RE.exec(value);
  if (num) frame.poster = Number.parseFloat(num[1] ?? "");
}

function applyDuration(frame, value, headingLine, warnings) {
  frame.duration = value;
  const num = DURATION_NUM_RE.exec(value);
  if (num) {
    frame.durationSeconds = Number.parseFloat(num[1] ?? "");
    return;
  }
  warnings.push({
    message: `Frame ${frame.index}: could not parse duration "${value}".`,
    line: headingLine,
    frameIndex: frame.index,
  });
}

function applyStatus(frame, value, headingLine, warnings) {
  const normalized = value.toLowerCase();
  if (isFrameStatus(normalized)) {
    frame.status = normalized;
    return;
  }
  frame.extra.status = value;
  warnings.push({
    message: `Frame ${frame.index}: unknown status "${value}"; defaulting to "${DEFAULT_FRAME_STATUS}".`,
    line: headingLine,
    frameIndex: frame.index,
  });
}

function stripQuotes(value) {
  if (value.length >= 2) {
    const first = value[0];
    const last = value[value.length - 1];
    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
      return value.slice(1, -1);
    }
  }
  return value;
}

// tokens.mjs — shared brand-token parsing + semantic role mapping for frame.md /
// FRAME.md. Used by build-frame.mjs (remix a preset onto brand tokens) and
// captions.mjs (derive caption colors from frame.md). One mapping → frames and
// captions stay consistent. Pure node.

// Collect `key: value` pairs under the top-level `colors:` block (until dedent).
export function parseColors(md) {
  const out = [];
  let inBlock = false;
  for (const line of md.split(/\r?\n/)) {
    if (/^colors:\s*$/.test(line)) {
      inBlock = true;
      continue;
    }
    if (!inBlock) continue;
    if (/^\S/.test(line)) break; // dedent to a top-level key → end of block
    const m = line.match(
      /^\s+([\w-]+):\s*(?:"([^"]+)"|'([^']+)'|(#[0-9a-fA-F]{3,8}|rgba?\([^)]*\)|[^#\s][^#\n]*?))\s*(?:#.*)?$/,
    );
    if (m) out.push([m[1], (m[2] ?? m[3] ?? m[4]).trim()]);
  }
  return out;
}

// relative luminance of a #rrggbb (null for non-hex like rgba()).
export function lum(v) {
  const m = /^#?([0-9a-fA-F]{6})$/.exec(String(v).trim());
  if (!m) return null;
  const n = parseInt(m[1], 16);
  return 0.2126 * ((n >> 16) & 255) + 0.7152 * ((n >> 8) & 255) + 0.0722 * (n & 255);
}

// chroma (max−min channel) of a #rrggbb — a cheap "how colorful" proxy; −1 for non-hex.
export function chroma(v) {
  const m = /^#?([0-9a-fA-F]{6})$/.exec(String(v).trim());
  if (!m) return -1;
  const n = parseInt(m[1], 16);
  const r = (n >> 16) & 255,
    g = (n >> 8) & 255,
    b = n & 255;
  return Math.max(r, g, b) - Math.min(r, g, b);
}

// Browser user-agent default colors for links / visited links. These leak into a
// capture from any UNSTYLED <a> and are NOT brand colors — but being pure & saturated
// they beat a real accent on chroma alone. Never let one become the accent.
export const UA_DEFAULT_COLORS = new Set(
  ["#0000EE", "#0000FF", "#0000CC", "#1A0DAB", "#551A8B", "#EE0000"].map((c) => c.toUpperCase()),
);

// Semantic STATUS roles (green "positive", red "negative"/"error", amber "warning" …). Their HUE
// carries the meaning, so they are never a brand ACCENT — a status red is frequently the most
// chromatic color in a palette (e.g. #dc2626 chroma 182 beats a deep-blue accent #1E40AF chroma
// 145) and would otherwise win a pure chroma ranking, painting captions/highlights the error red.
// build-frame.mjs uses this same key set to protect status colors during the preset→brand remix.
export const STATUS_ROLE_KEY =
  /(?:^|[-_])(?:positive|negative|success|error|warning|danger|good|bad|up|down|info|neutral|alert|caution|critical)(?:[-_]|$)/i;

// Pick the brand ACCENT — never by raw chroma alone, never a UA-default link color.
// Priority:
//   1) with capture colorStats → the colorful color that RECURS across the UI. The brand
//      accent shows up in MANY roles (link text + icon + button + badge), whereas a one-off
//      CTA fill appears in just one. So rank chromatic (chroma>40) candidates by role
//      diversity first, then total prevalence, then interactive use, then chroma. This keeps
//      a pervasive brand color (e.g. an indigo used everywhere) ahead of a single bright
//      button fill (e.g. a lime used once) — the old "top interactiveBg" rule picked the
//      latter. Requiring interactiveBg>0 is dropped so a text/icon-only accent can still win.
//   2) no stats → most chromatic color AFTER removing UA defaults + `exclude`.
// A stray default link color (e.g. #0000EE) can win under neither path.
export function pickAccent(stats, colors, exclude = []) {
  const ban = new Set([...exclude, ...UA_DEFAULT_COLORS].map((c) => String(c).toUpperCase()));
  const ok = (h) => /^#[0-9a-fA-F]{6}$/.test(String(h)) && !ban.has(String(h).toUpperCase());
  // Prominence rank from the (frequency-ordered) `colors` palette: index 0 = most used.
  // A saturated color sitting at the TAIL is almost always a one-off (a single CTA fill),
  // not the brand accent — capture colorStats counts are too sparse to tell these apart
  // (e.g. Linear's indigo and a lime CTA both register count≈1), but palette ORDER does.
  const rank = new Map((colors ?? []).map((h, i) => [String(h).toUpperCase(), i]));
  const prom = (h) => (rank.has(String(h).toUpperCase()) ? rank.get(String(h).toUpperCase()) : 1e9);
  if (Array.isArray(stats) && stats.length) {
    const roles = (s) =>
      ((s.interactiveBg || 0) > 0 ? 1 : 0) +
      ((s.textCount || 0) > 0 ? 1 : 0) +
      ((s.bgCount || 0) > 0 ? 1 : 0);
    const a = stats
      .filter((s) => ok(s?.hex) && chroma(s.hex) > 40)
      .sort(
        (x, y) =>
          roles(y) - roles(x) || // used in MORE roles (link+icon+button) = the brand accent
          prom(x.hex) - prom(y.hex) || // earlier in the palette = more prominent
          (y.count || 0) - (x.count || 0) ||
          (y.interactiveBg || 0) - (x.interactiveBg || 0) ||
          chroma(y.hex) - chroma(x.hex),
      );
    if (a.length) return a[0].hex;
  }
  const c = (colors ?? [])
    .map(String)
    .filter(ok)
    .sort((x, y) => chroma(y) - chroma(x));
  return c[0];
}

// Derive brand roles from rich capture colorStats (areaBg / interactiveBg / textCount /
// maxArea) — by semantic FUNCTION, not luminance/chroma proxies. Returns null when stats
// are unusable, so the caller can fall back. canvas = the color painting the most real
// background area (the page ground, dark or light); ink = the dominant text color that
// actually contrasts with the canvas; accent via pickAccent.
export function brandRolesFromStats(stats, colorsInOrder) {
  if (!Array.isArray(stats) || !stats.length) return null;
  const v = stats.filter((s) => /^#[0-9a-fA-F]{6}$/.test(s?.hex || ""));
  if (!v.length) return null;
  const canvas = [...v].sort(
    (a, b) =>
      (b.areaBg || 0) - (a.areaBg || 0) ||
      (b.maxArea || 0) - (a.maxArea || 0) ||
      (b.bgCount || 0) - (a.bgCount || 0),
  )[0]?.hex;
  // pass the frequency-ordered palette (tokens.colors) so pickAccent can use palette
  // PROMINENCE — colorStats counts alone are too sparse to rank rare accents.
  const accent = pickAccent(v, colorsInOrder ?? v.map((s) => s.hex), [canvas]);
  if (!canvas || !accent) return null;
  const cl = lum(canvas) ?? 0;
  const ink =
    [...v]
      .filter((s) => s.hex !== canvas && s.hex !== accent)
      .sort((a, b) => (b.textCount || 0) - (a.textCount || 0))
      .find((s) => Math.abs((lum(s.hex) ?? 0) - cl) > 64)?.hex ??
    (cl > 128 ? "#000000" : "#FFFFFF");
  const accent2 =
    pickAccent(v, colorsInOrder ?? v.map((s) => s.hex), [canvas, ink, accent]) ?? accent;
  return { ink, canvas, accent, accent2 };
}

// Map a list of [key, value] colors to semantic roles. ink = a dark/ink-named
// color (else darkest); canvas = a paper/cream/white-named color (else lightest);
// accents = whatever's left, ranked by chroma (the loudest color is almost always
// the brand accent) — UA-default link colors AND semantic status colors (positive/
// negative/error…) excluded so neither a stray <a> color nor a status red ever wins.
// For an unkeyed brand list, pass synthetic keys — name matching simply no-ops and it
// falls back to luminance/chroma, which is what we want. NOTE: when capture colorStats
// exist, prefer brandRolesFromStats() — it picks by function, not these proxies.
export function semanticColors(colors) {
  if (!colors.length) return {};
  const named = (re) => colors.find(([k]) => re.test(k));
  const hexes = colors.filter(([, v]) => lum(v) != null);
  const byLum = [...hexes].sort((a, b) => (lum(a[1]) ?? 1e9) - (lum(b[1]) ?? 1e9));
  const pick = (m, fallback) => (m ? m[1] : fallback ? fallback[1] : undefined);
  // "ink" must be a whole word-segment so "soft-pink"/"pink" don't match it.
  const ink = pick(
    named(/(?:^|[-_])ink(?:[-_]|$)|black|charcoal|^text(?:-dark)?$|outline|noir/i),
    byLum[0] ?? colors[0],
  );
  const canvas = pick(
    named(/cream|paper|canvas|white|bg|ground|surface|base|sand|parchment|off-?white|bone/i),
    byLum[byLum.length - 1] ?? colors[colors.length - 1],
  );
  const accents = colors
    .filter(
      ([k, v]) =>
        v !== ink &&
        v !== canvas &&
        !UA_DEFAULT_COLORS.has(String(v).toUpperCase()) &&
        !STATUS_ROLE_KEY.test(k), // a status red/green carries meaning by hue — never an accent
    )
    .sort((a, b) => chroma(b[1]) - chroma(a[1]))
    .map(([, v]) => v);
  return { ink, canvas, accent: accents[0] ?? ink, accent2: accents[1] ?? accents[0] ?? ink };
}

// Collect role→fontFamily under the top-level `typography:` block; pick a display
// + body family from the usual role names. Returns quoted families (or null).
export function parseFonts(md) {
  const roles = {};
  let inBlock = false;
  for (const line of md.split(/\r?\n/)) {
    if (/^typography:\s*$/.test(line)) {
      inBlock = true;
      continue;
    }
    if (!inBlock) continue;
    if (/^\S/.test(line)) break;
    const m = line.match(/^\s+([\w-]+):\s*\{[^}]*fontFamily:\s*"([^"]+)"/);
    if (m) roles[m[1]] = m[2];
  }
  const q = (s) => (s ? `"${s}"` : null);
  const body = roles.body ?? roles.subtitle ?? Object.values(roles)[0];
  const display =
    roles.display ??
    roles.headline ??
    roles["card-headline"] ??
    roles["section-headline"] ??
    roles["quote-display"] ??
    roles.h1 ??
    roles.h2 ??
    roles.title ??
    roles.hero ??
    body;
  // the monospace / chrome family (code, tags, ticks, page numbers) — so the remix can
  // route a captured brand mono (Berkeley Mono, JetBrains Mono…) onto this role instead
  // of the reading body. null when the preset has no distinct mono role.
  const mono =
    roles.mono ??
    roles["mono-tag"] ??
    roles["mono-chrome"] ??
    roles["mono-tick"] ??
    roles.code ??
    roles.data ??
    roles.pagenum ??
    null;
  return { display: q(display), body: q(body), mono: q(mono) };
}

// transition-registry.mjs — loader for this skill's vendored transition registry
// (./transitions.json). The registry is the curated Tier-B subset (transform /
// opacity / filter on the two frame clip wrappers `#el-<id>`, no overlay DOM) +
// each type's GSAP template. Vendored into the skill so it ships standalone; the
// recipes originate from the shared catalog skills/hyperframes-animation/
// transitions/ (css-*.md) — keep them in step if those shared recipes change.

import { readFileSync } from "node:fs";
import { resolve, dirname } from "node:path";
import { fileURLToPath } from "node:url";

const here = dirname(fileURLToPath(import.meta.url));
export const DEFAULT_REGISTRY_PATH = resolve(here, "./transitions.json");

let _cache = null;

export function loadTransitionRegistry(registryPath = DEFAULT_REGISTRY_PATH) {
  if (_cache && _cache.path === registryPath) return _cache.data;
  let data;
  try {
    data = JSON.parse(readFileSync(registryPath, "utf8"));
  } catch (e) {
    throw new Error(`transition registry not loadable at ${registryPath}: ${e.message}`);
  }
  if (!Array.isArray(data.transitions) || data.transitions.length === 0) {
    throw new Error(`transition registry ${registryPath} has no transitions[]`);
  }
  _cache = { path: registryPath, data };
  return data;
}

// Convenience: a Map name -> transition record.
export function transitionsByName(registryPath = DEFAULT_REGISTRY_PATH) {
  const data = loadTransitionRegistry(registryPath);
  const map = new Map();
  for (const t of data.transitions) map.set(t.name, t);
  return map;
}

{
  "_comment": "Vendored transition registry for the product-launch workflow — the curated Tier-B subset (transform/opacity/filter on the two frame clip wrappers #el-<id>, no overlay DOM, no per-frame cooperation). Each type carries its GSAP template; the transitions.mjs injector stamps it onto window.__timelines[\"main\"]. Recipes originate from the shared catalog skills/hyperframes-animation/transitions/ (css-*.md) — keep in step if those change. Token placeholders the injector substitutes: __OLD__ (#el-<from>), __NEW__ (#el-<to>), __T__ (overlap-start s), __DUR__ (this boundary's duration), __DX__/__DXIN__ (horizontal travel + incoming offset), __DY__/__DYIN__ (vertical).",
  "transitions": [
    {
      "name": "crossfade",
      "energy": "any",
      "default_duration_s": 0.5,
      "directions": [],
      "source": "css-dissolve.md",
      "gsap_template": [
        "tl.to(__OLD__, { opacity: 0, duration: __DUR__, ease: \"power2.inOut\" }, __T__);",
        "tl.fromTo(__NEW__, { opacity: 0 }, { opacity: 1, duration: __DUR__, ease: \"power2.inOut\" }, __T__);"
      ]
    },
    {
      "name": "blur-crossfade",
      "energy": "calm",
      "default_duration_s": 0.6,
      "directions": [],
      "source": "css-dissolve.md",
      "note": "Default when the two frames' #root backgrounds differ a lot — the blur masks the background-color clash a plain crossfade would expose.",
      "gsap_template": [
        "tl.to(__OLD__, { filter: \"blur(10px)\", scale: 1.03, opacity: 0, duration: __DUR__, ease: \"power2.inOut\" }, __T__);",
        "tl.fromTo(__NEW__, { filter: \"blur(10px)\", scale: 0.97, opacity: 0 }, { filter: \"blur(0px)\", scale: 1, opacity: 1, duration: __DUR__, ease: \"power2.inOut\" }, __T__);"
      ]
    },
    {
      "name": "push-slide",
      "energy": "medium",
      "default_duration_s": 0.5,
      "directions": ["LEFT", "RIGHT", "UP", "DOWN"],
      "default_direction": "LEFT",
      "source": "css-push.md",
      "note": "Directional. The injector picks __DX__/__DY__ from the direction and emits the horizontal OR vertical pair (not both).",
      "gsap_template_horizontal": [
        "tl.to(__OLD__, { x: __DX__, duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
        "tl.fromTo(__NEW__, { x: __DXIN__, opacity: 1 }, { x: 0, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
      ],
      "gsap_template_vertical": [
        "tl.to(__OLD__, { y: __DY__, duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
        "tl.fromTo(__NEW__, { y: __DYIN__, opacity: 1 }, { y: 0, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
      ]
    },
    {
      "name": "zoom-through",
      "energy": "high",
      "default_duration_s": 0.4,
      "directions": [],
      "source": "css-scale.md",
      "gsap_template": [
        "tl.to(__OLD__, { scale: 2.5, opacity: 0, filter: \"blur(8px)\", duration: __DUR__, ease: \"power3.in\" }, __T__);",
        "tl.fromTo(__NEW__, { scale: 0.5, opacity: 0, filter: \"blur(8px)\" }, { scale: 1, opacity: 1, filter: \"blur(0px)\", duration: __DUR__, ease: \"power3.out\" }, __T__);"
      ]
    },
    {
      "name": "squeeze",
      "energy": "medium",
      "default_duration_s": 0.4,
      "directions": [],
      "source": "css-push.md",
      "note": "Old compresses to a vertical line on the left edge; new expands from the right edge. Incoming starts off (scaleX 0) so its higher-track stacking is harmless.",
      "gsap_template": [
        "tl.to(__OLD__, { scaleX: 0, transformOrigin: \"left center\", duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
        "tl.fromTo(__NEW__, { scaleX: 0, transformOrigin: \"right center\", opacity: 1 }, { scaleX: 1, transformOrigin: \"right center\", duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
      ]
    }
  ],
  "default_high_energy": "zoom-through",
  "default_calm": "blur-crossfade",
  "max_duration_s": 2.0
}

#!/usr/bin/env node

import { spawnSync } from "node:child_process";
import { realpathSync } from "node:fs";
import { pathToFileURL } from "node:url";

export function hasCliCommand(helpText, command) {
  const escaped = command.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
  return new RegExp(`^\\s+${escaped}(?:\\s+|$)`, "m").test(String(helpText));
}

export function runCliPreflight({ command = "check", spawn = spawnSync } = {}) {
  const result = spawn("npx", ["hyperframes", "--help"], {
    encoding: "utf8",
    shell: process.platform === "win32",
  });
  const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
  if (result.status !== 0) {
    throw new Error(`unable to inspect HyperFrames CLI capabilities\n${output.trim()}`);
  }
  if (!hasCliCommand(output, command)) {
    throw new Error(
      `the installed HyperFrames CLI does not provide \`${command}\`, but the current pr-to-video skill requires it. Upgrade the CLI before starting frame work.`,
    );
  }
  return true;
}

function main() {
  try {
    runCliPreflight();
    console.log("✓ pr-to-video preflight: required CLI capabilities are available");
  } catch (error) {
    console.error(`✗ pr-to-video preflight: ${error.message}`);
    process.exit(1);
  }
}

// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
// a raw compare silently skips main() when invoked through any symlinked path.
function isMainModule() {
  if (!process.argv[1]) return false;
  try {
    return pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url;
  } catch {
    return false;
  }
}

if (isMainModule()) main();

#!/usr/bin/env node

import { homedir } from "node:os";
import { join, resolve } from "node:path";
import { realpathSync } from "node:fs";
import { pathToFileURL } from "node:url";

function safeSegment(value) {
  const normalized = value
    .normalize("NFKD")
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, "-")
    .replace(/^-+|-+$/g, "");
  if (!normalized || normalized === "." || normalized === "..") {
    throw new Error("Invalid GitHub PR reference: owner/repository is empty after sanitization");
  }
  return normalized;
}

export function parsePrReference(raw) {
  const input = String(raw ?? "").trim();
  let match = input.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)(?:[/?#].*)?$/i);
  if (!match) match = input.match(/^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)#(\d+)$/);
  if (!match) {
    throw new Error(`Invalid GitHub PR reference: ${JSON.stringify(input)}`);
  }
  const number = Number(match[3]);
  if (!Number.isSafeInteger(number) || number <= 0) {
    throw new Error(`Invalid GitHub PR reference: ${JSON.stringify(input)}`);
  }
  return { owner: safeSegment(match[1]), repo: safeSegment(match[2]), number };
}

export function resolvePrToVideoProjectDir({
  pr,
  explicitDir,
  cwd = process.cwd(),
  env = process.env,
}) {
  if (explicitDir?.trim()) return resolve(cwd, explicitDir.trim());
  const ref = parsePrReference(pr);
  const cacheRoot = env.XDG_CACHE_HOME?.trim()
    ? resolve(env.XDG_CACHE_HOME)
    : join(env.HOME?.trim() ? resolve(env.HOME) : homedir(), ".cache");
  return join(
    cacheRoot,
    "hyperframes",
    "pr-to-video",
    ref.owner,
    ref.repo,
    `${ref.repo}-pr-${ref.number}`,
  );
}

function flag(argv, name) {
  const index = argv.indexOf(`--${name}`);
  return index >= 0 ? argv[index + 1] : undefined;
}

function main() {
  const argv = process.argv.slice(2);
  const pr = flag(argv, "pr");
  if (!pr) {
    console.error('usage: node project-dir.mjs --pr "<github PR>" [--project-dir <path>]');
    process.exit(2);
  }
  try {
    console.log(
      resolvePrToVideoProjectDir({
        pr,
        explicitDir: flag(argv, "project-dir") ?? process.env.PR_TO_VIDEO_PROJECT_DIR,
      }),
    );
  } catch (error) {
    console.error(`✗ project-dir: ${error.message}`);
    process.exit(1);
  }
}

// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
// a raw compare silently skips main() when invoked through any symlinked path.
function isMainModule() {
  if (!process.argv[1]) return false;
  try {
    return pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url;
  } catch {
    return false;
  }
}

if (isMainModule()) main();

#!/usr/bin/env node
// transitions.mjs — inter-frame transition injector + verifier for the video workflow.
//
//   inject  — read STORYBOARD frame order + each frame's transition_in, overlap
//             the frame clip wrappers in index.html, and stamp the GSAP template.
//   verify  — deterministic gate over the injector's output.
//
// transition_in (written by story-design on the INCOMING frame) names a registry
// type directly: crossfade | blur-crossfade | push-slide | zoom-through | squeeze,
// optionally "<type> <DIR>" / "<type> <N>s" (e.g. "push-slide LEFT", "crossfade
// 0.4s"). `cut` / `none` / empty ⇒ hard cut (no overlap, no stamp).
//
// Mechanics — EXTEND-OUTGOING-ONLY (keeps voice/SFX/captions synced; their timing
// is keyed to the original frame start). At boundary i→i+1 (type = the incoming
// frame's transition_in): extend ONLY the outgoing wrapper's data-duration by
// `dur` so it holds its final frame across the window; do NOT move any data-start;
// the incoming — already present from the cut on a higher track — fades/pushes in
// over it. Then 0/1-ping-pong ALL frame clips' data-track-index (adjacent
// overlapping wrappers never share a track — lint timeline_track_too_dense) and
// stamp the token-substituted GSAP template into __timelines["main"] at T =
// incoming start. captions(2)/voice(10)/bgm(11)/sfx(20+) are never touched.
//
//   node transitions.mjs inject --storyboard ./STORYBOARD.md --hyperframes .
//   node transitions.mjs verify --storyboard ./STORYBOARD.md --index ./index.html

import { existsSync, readFileSync, writeFileSync } from "node:fs";
import { join, resolve } from "node:path";
import { parseStoryboard } from "./lib/storyboard.mjs";
import { parseFormat } from "./lib/dimensions.mjs";
import { loadTransitionRegistry, transitionsByName } from "./lib/transition-registry.mjs";
import { padFrameInternalDuration } from "./lib/pad-frame-duration.mjs";

const flag = (argv, name, def) => {
  const i = argv.indexOf(`--${name}`);
  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
};
const NO_TRANSITION = new Set(["cut", "none", ""]);
const r3 = (x) => Number(x.toFixed(3));

// transition_in → { type, direction?, dur? } | null (hard cut).
function parseTransitionIn(raw) {
  const s = (raw ?? "").trim();
  if (NO_TRANSITION.has(s.toLowerCase())) return null;
  const parts = s.split(/\s+/);
  const spec = { type: parts[0].toLowerCase() };
  for (const p of parts.slice(1)) {
    const m = p.match(/^(\d+(?:\.\d+)?)s?$/);
    if (m) spec.dur = Number(m[1]);
    else spec.direction = p.toUpperCase();
  }
  return spec;
}

// Mounted STORYBOARD frames present in index.html, in document order: { id, frame }.
function mountedFramesInOrder(manifest, html) {
  const out = [];
  for (const f of manifest.frames) {
    if (!f.src) continue;
    const id = f.src
      .split("/")
      .pop()
      .replace(/\.html?$/i, "");
    if (html.includes(`id="el-${id}"`)) out.push({ id, frame: f });
  }
  return out;
}

// Frame clip wrappers parsed out of index.html (ids carry hyphens; excludes
// el-captions and audio by keying off the known frame-id set). The id is matched
// from anywhere in the tag's attribute list — never assume it is the first attribute
// (the index assembler emits data-hf-id before id, so an id-first regex finds nothing
// and inject crashes on the empty clip map).
function parseFrameClips(html, frameIds) {
  const clipRe = /<div\b([^>]*)><\/div>/g;
  const clips = new Map();
  let m;
  while ((m = clipRe.exec(html)) !== null) {
    const attrs = m[1];
    const idm = attrs.match(/\bid="el-([A-Za-z0-9_-]+)"/);
    if (!idm || !frameIds.has(idm[1])) continue;
    const num = (re) => {
      const x = attrs.match(re);
      return x ? Number(x[1]) : null;
    };
    clips.set(idm[1], {
      id: idm[1],
      block: m[0],
      start: num(/data-start="([\d.]+)"/),
      duration: num(/data-duration="([\d.]+)"/),
      track: num(/data-track-index="(\d+)"/) ?? 0,
    });
  }
  return clips;
}

// The host wrapper is extended across an outgoing transition, so the mounted
// frame must remain visually populated for the same local-time window. Extend
// the frame root and every non-audio timed element that reached the original
// storyboard boundary. This also repairs worker files whose root was already
// inflated while their ground/content clips still ended at the synced duration.
function extendFrameTail(hyperframesDir, frame, baseDuration, targetDuration, die) {
  if (!frame?.src || targetDuration <= baseDuration) return;
  const framePath = join(hyperframesDir, frame.src);
  let html;
  try {
    html = readFileSync(framePath, "utf8");
  } catch {
    die(`outgoing frame file not found at ${framePath}`);
  }

  const compId = frame.src
    .split("/")
    .pop()
    .replace(/\.html?$/i, "");
  const EPS = 0.011;
  let foundRoot = false;
  let extended = 0;
  const rewritten = html.replace(/<([A-Za-z][\w:-]*)\b([^>]*)>/g, (tag, name, attrs) => {
    const durationMatch = attrs.match(/\bdata-duration="([\d.]+)"/);
    if (!durationMatch) return tag;
    const duration = Number(durationMatch[1]);
    if (!Number.isFinite(duration)) return tag;

    const compositionMatch = attrs.match(/\bdata-composition-id="([^"]+)"/);
    if (compositionMatch?.[1] === compId && !foundRoot) {
      foundRoot = true;
      return tag.replace(/\bdata-duration="[\d.]+"/, `data-duration="${targetDuration}"`);
    }

    if (name.toLowerCase() === "audio") return tag;
    const startMatch = attrs.match(/\bdata-start="([\d.]+)"/);
    if (!startMatch) return tag;
    const start = Number(startMatch[1]);
    const end = start + duration;
    if (end < baseDuration - EPS || end >= targetDuration - EPS) return tag;
    extended++;
    return tag.replace(/\bdata-duration="[\d.]+"/, `data-duration="${r3(targetDuration - start)}"`);
  });

  if (!foundRoot) die(`${frame.src} has no data-composition-id="${compId}" root`);
  writeFileSync(framePath, rewritten);
  console.log(
    `  ${compId}: extended root + ${extended} tail clip(s) ${baseDuration}s→${targetDuration}s`,
  );
}

// Resolve a transition_in spec to a registry record (calm default on unknown).
function resolveRecord(spec, byName, reg, warn) {
  let rec = byName.get(spec.type);
  if (!rec) {
    rec = byName.get(reg.default_calm);
    warn(`transition_in "${spec.type}" not in registry — using ${reg.default_calm}`);
  }
  return rec;
}
function resolveDur(spec, rec, reg) {
  let dur = spec.dur ?? rec.default_duration_s ?? 0.5;
  return Math.min(dur, reg.max_duration_s ?? 2.0);
}

// GSAP lines for one transition record (token substitution).
function buildGsap(rec, fromId, toId, dur, T, direction, canvasW, canvasH, die) {
  const subs = {
    __OLD__: `"#el-${fromId}"`,
    __NEW__: `"#el-${toId}"`,
    __T__: String(T),
    __DUR__: String(dur),
  };
  let template;
  if (rec.directions && rec.directions.length > 0) {
    const dir = (direction || rec.default_direction || rec.directions[0]).toUpperCase();
    const vertical = dir === "UP" || dir === "DOWN";
    template = vertical ? rec.gsap_template_vertical : rec.gsap_template_horizontal;
    if (!template)
      die(`transition ${rec.name}: missing ${vertical ? "vertical" : "horizontal"} template`);
    if (vertical) {
      const dy = dir === "UP" ? -canvasH : canvasH;
      subs.__DY__ = String(dy);
      subs.__DYIN__ = String(-dy);
    } else {
      const dx = dir === "LEFT" ? -canvasW : canvasW;
      subs.__DX__ = String(dx);
      subs.__DXIN__ = String(-dx);
    }
  } else {
    template = rec.gsap_template;
    if (!template) die(`transition ${rec.name}: missing gsap_template`);
  }
  return template.map((line) => {
    let out = line;
    for (const [k, v] of Object.entries(subs)) out = out.split(k).join(v);
    return out;
  });
}

function runInject(argv) {
  const hyperframesDir = resolve(flag(argv, "hyperframes", "."));
  const storyboardPath = resolve(flag(argv, "storyboard", join(hyperframesDir, "STORYBOARD.md")));
  const indexPath = join(hyperframesDir, "index.html");
  const die = (msg) => {
    console.error(`✗ transitions inject: ${msg}`);
    process.exit(1);
  };

  if (!existsSync(storyboardPath)) die(`STORYBOARD.md not found at ${storyboardPath}`);

  const manifest = parseStoryboard(readFileSync(storyboardPath, "utf8"));
  const { width: CW, height: CH } = parseFormat(manifest.globals.format);
  const reg = loadTransitionRegistry();
  const byName = transitionsByName();

  // Read directly and handle ENOENT here, rather than an existsSync precheck —
  // the check→write pair (write-back below) is a TOCTOU race CodeQL flags.
  let html = "";
  try {
    html = readFileSync(indexPath, "utf8");
  } catch {
    die(`index.html not found at ${indexPath} — run assemble-index.mjs first`);
  }
  const order = mountedFramesInOrder(manifest, html);
  if (order.length === 0) die("no frame clips found in index.html");
  const frameIds = new Set(order.map((x) => x.id));
  const clips = parseFrameClips(html, frameIds);

  const gsapLines = [];
  const applied = [];
  for (let i = 1; i < order.length; i++) {
    const spec = parseTransitionIn(order[i].frame.transitionIn);
    if (!spec) continue; // hard cut
    const incoming = clips.get(order[i].id);
    const outgoing = clips.get(order[i - 1].id);
    const rec = resolveRecord(spec, byName, reg, (m) =>
      console.error(`  ! frame ${order[i].id}: ${m}`),
    );
    const dur = resolveDur(spec, rec, reg);
    const T = r3(incoming.start); // cut = incoming start (frames tile)
    const baseDuration = outgoing.duration;
    outgoing.duration = r3(baseDuration + dur); // extend outgoing only
    extendFrameTail(hyperframesDir, order[i - 1].frame, baseDuration, outgoing.duration, die);
    padFrameInternalDuration(
      hyperframesDir,
      order[i - 1].frame.src,
      outgoing.id,
      outgoing.duration,
    );
    gsapLines.push(
      ...buildGsap(rec, outgoing.id, incoming.id, dur, T, spec.direction, CW, CH, die),
    );
    applied.push({ from: outgoing.id, to: incoming.id, type: rec.name, dur, T });
  }

  if (applied.length === 0) {
    console.log(`✓ transitions inject: 0 transitions (all cuts) — index.html unchanged`);
    return;
  }

  // 0/1 ping-pong all frame clips in play order.
  const ordered = [...clips.values()].sort((a, b) => a.start - b.start || a.id.localeCompare(b.id));
  ordered.forEach((c, i) => {
    c.track = i % 2;
  });

  // rewrite each clip block: start unchanged; duration possibly extended; track ping-ponged.
  for (const c of clips.values()) {
    const nb = c.block
      .replace(/data-duration="[\d.]+"/, `data-duration="${c.duration}"`)
      .replace(/data-track-index="\d+"/, `data-track-index="${c.track}"`);
    html = html.replace(c.block, nb);
  }

  // stamp the GSAP after the master timeline anchor.
  const anchor = 'window.__timelines["main"] = gsap.timeline({ paused: true });';
  if (!html.includes(anchor)) die("master timeline anchor not found in index.html");
  // The transition tweens alone leave window.__timelines["main"] spanning only the
  // last transition (e.g. 24.7s), shorter than the real composition. The Studio
  // reads main.duration() as its master duration and parses clips against it, so a
  // short master collapses its timeline (clips dropped, duration wrong, blank stage)
  // — the render engine is unaffected (it trusts the root data-duration attr). Stamp
  // a full-span anchor so main.duration() == composition total. Mirrors the
  // `tl.to({}, { duration })` anchor captions.html already uses.
  const rootDurMatch = html.match(/data-composition-id="main"[^>]*?data-duration="([\d.]+)"/);
  const totalDur = rootDurMatch ? Number(rootDurMatch[1]) : null;
  const block = [
    anchor,
    "      // ── frame transitions (injected by transitions.mjs) ──",
    '      (function () { var tl = window.__timelines["main"];',
    ...gsapLines.map((l) => "        " + l),
    ...(totalDur
      ? [
          `        tl.to({}, { duration: ${totalDur} }, 0); // full-span anchor — main.duration() == composition total (Studio master duration)`,
        ]
      : []),
    "      })();",
  ].join("\n");
  html = html.replace(anchor, block);

  writeFileSync(indexPath, html);
  console.log(`✓ transitions inject: ${applied.length} transition(s) stamped into index.html`);
  for (const a of applied) console.log(`  ${a.from}→${a.to}: ${a.type} ${a.dur}s @ T=${a.T}s`);
  const tracks = ordered
    .map((c) => `${c.id}[t${c.track} ${c.start}→${r3(c.start + c.duration)}]`)
    .join(" ");
  console.log(`  tracks: ${tracks}`);
}

function runVerify(argv) {
  const hyperframesDir = resolve(flag(argv, "hyperframes", "."));
  const storyboardPath = resolve(flag(argv, "storyboard", join(hyperframesDir, "STORYBOARD.md")));
  const indexPath = resolve(flag(argv, "index", join(hyperframesDir, "index.html")));
  const bail = (msg) => {
    console.error(`✗ transitions verify: ${msg}`);
    process.exit(1);
  };

  if (!existsSync(storyboardPath)) bail("STORYBOARD.md not found");
  if (!existsSync(indexPath)) bail("index.html not found");

  const manifest = parseStoryboard(readFileSync(storyboardPath, "utf8"));
  const html = readFileSync(indexPath, "utf8");
  const order = mountedFramesInOrder(manifest, html);
  const frameIds = new Set(order.map((x) => x.id));
  const clips = parseFrameClips(html, frameIds);

  const EPS = 0.011;
  const overlaps = (a, b) =>
    a.start < b.start + b.duration - EPS && b.start < a.start + a.duration - EPS;
  const fail = [];

  // (4) global no same-track overlap. This is this workflow's own lane convention,
  //     not a lint rule: nothing in the framework rejects same-track overlap.
  const all = [...clips.values()];
  for (let i = 0; i < all.length; i++)
    for (let j = i + 1; j < all.length; j++) {
      const a = all[i];
      const b = all[j];
      if (a.track === b.track && overlaps(a, b))
        fail.push(`same-track overlap: ${a.id}[t${a.track}] & ${b.id}[t${b.track}]`);
    }

  const bm = html.match(/frame transitions \(injected[\s\S]*?\}\)\(\);/);
  const txBlock = bm ? bm[0] : "";

  let expected = 0;
  for (let i = 1; i < order.length; i++) {
    const spec = parseTransitionIn(order[i].frame.transitionIn);
    if (!spec) continue;
    expected++;
    const to = clips.get(order[i].id);
    const from = clips.get(order[i - 1].id);
    if (!to || !from) {
      fail.push(`boundary ${order[i - 1].id}→${order[i].id}: wrapper missing`);
      continue;
    }
    if (!txBlock.includes(`"#el-${from.id}"`) || !txBlock.includes(`"#el-${to.id}"`))
      fail.push(`boundary ${from.id}→${to.id}: injected block does not reference both ids`);
    const overlapAmt = r3(from.start + from.duration - to.start);
    if (overlapAmt <= 0) fail.push(`boundary ${from.id}→${to.id}: no overlap (${overlapAmt}s)`);
    if (from.track === to.track)
      fail.push(`boundary ${from.id}→${to.id}: both on track ${from.track}`);
  }
  if (expected > 0 && !txBlock)
    fail.push(`${expected} transition(s) expected but no injected block found`);

  if (fail.length) {
    console.error(`✗ transitions verify: ${fail.length} failure(s):`);
    for (const f of fail) console.error(`  - ${f}`);
    process.exit(1);
  }
  console.log(
    `✓ transitions verify: ${expected} transition(s) verified (cross-track, overlap>0, both ids referenced, no same-track overlap)`,
  );
}

const sub = process.argv[2];
const rest = process.argv.slice(3);
if (sub === "inject") runInject(rest);
else if (sub === "verify") runVerify(rest);
else {
  console.error("usage: node transitions.mjs <inject|verify> [args...]");
  process.exit(2);
}

import assert from "node:assert/strict";
import { existsSync, mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { homedir, tmpdir } from "node:os";
import { dirname, isAbsolute, join, relative, resolve } from "node:path";
import test from "node:test";

import { parsePrReference, resolvePrToVideoProjectDir } from "./project-dir.mjs";
import { buildFramePackets } from "./frame-packets.mjs";
import { hasCliCommand } from "./preflight.mjs";

function write(path, contents) {
  mkdirSync(dirname(path), { recursive: true });
  writeFileSync(path, contents);
}

test("default project directory is durable and outside the caller repository", () => {
  const caller = mkdtempSync(join(tmpdir(), "p2v-caller-"));
  const cache = mkdtempSync(join(tmpdir(), "p2v-cache-"));
  const result = resolvePrToVideoProjectDir({
    pr: "https://github.com/EveryInc/compound-engineering-plugin/pull/1092",
    cwd: caller,
    env: { XDG_CACHE_HOME: cache, HOME: homedir() },
  });

  assert.equal(
    result,
    join(
      cache,
      "hyperframes",
      "pr-to-video",
      "everyinc",
      "compound-engineering-plugin",
      "compound-engineering-plugin-pr-1092",
    ),
  );
  assert.ok(isAbsolute(result));
  assert.ok(relative(caller, result).startsWith(".."));
});

test("explicit project directory is preserved exactly after absolute resolution", () => {
  const caller = mkdtempSync(join(tmpdir(), "p2v-explicit-caller-"));
  assert.equal(
    resolvePrToVideoProjectDir({
      pr: "EveryInc/compound-engineering-plugin#1092",
      cwd: caller,
      explicitDir: "../my-video",
      env: {},
    }),
    resolve(caller, "../my-video"),
  );
});

test("distinct owner and repository segments cannot collide in the durable cache", () => {
  const cache = mkdtempSync(join(tmpdir(), "p2v-cache-collision-"));
  const first = resolvePrToVideoProjectDir({
    pr: "foo-bar/baz#1",
    env: { XDG_CACHE_HOME: cache },
  });
  const second = resolvePrToVideoProjectDir({
    pr: "foo/bar-baz#1",
    env: { XDG_CACHE_HOME: cache },
  });

  assert.notEqual(first, second);
});

test("PR parsing sanitizes owner and repository path traversal", () => {
  assert.deepEqual(
    parsePrReference("https://github.com/EveryInc/compound-engineering-plugin/pull/1092"),
    {
      owner: "everyinc",
      repo: "compound-engineering-plugin",
      number: 1092,
    },
  );
  assert.throws(() => parsePrReference("../../outside#1092"), /valid GitHub PR reference/i);
});

test("#1092 packets contain selected excerpts but never the full diff", () => {
  const project = mkdtempSync(join(tmpdir(), "p2v-packets-"));
  const largeDiff = `diff --git a/noise b/noise\n${"+unselected noise\n".repeat(10_000)}`;
  write(join(project, "capture", "diff.patch"), largeDiff);
  write(join(project, "frame.md"), "# compact frame tokens\n");
  write(
    join(project, "STORYBOARD.md"),
    `---\nformat: 1920x1080\n---\n\n## Frame 1 — Diff\n\n- duration: 4s\n- src: compositions/frames/01-diff.html\n- focal: code-diff\n- blueprint: compose\n- rules: text-reveal\n\n### Source excerpt\n\n\`\`\`diff\n-oldCall()\n+newCall({ attested: true })\n\`\`\`\n\n## Frame 2 — Impact\n\n- duration: 3s\n- src: compositions/frames/02-impact.html\n- blueprint: dataviz-countup\n- rules: counting-dynamic-scale\n`,
  );

  const result = buildFramePackets({
    projectDir: project,
    storyboardPath: join(project, "STORYBOARD.md"),
    outDir: join(project, ".hyperframes", "frame-packets"),
    maxPacketBytes: 32_000,
  });

  assert.equal(result.length, 2);
  const codePacket = readFileSync(result[0].path, "utf8");
  assert.match(codePacket, /newCall\(\{ attested: true \}\)/);
  assert.doesNotMatch(codePacket, /unselected noise/);
  assert.doesNotMatch(codePacket, /code-scroll/);
  assert.ok(Buffer.byteLength(codePacket) < 32_000);
  assert.ok(result.every((packet) => packet.path.endsWith(".md")));

  const role = readFileSync(join(project, ".hyperframes", "frame-packets", "_role.md"), "utf8");
  assert.match(role, /# Frame worker — core contract/);
  assert.match(role, /# Frame worker — PR-to-video delta/);
});

test("packet validation is atomic and leaves no partial output on overflow", () => {
  const project = mkdtempSync(join(tmpdir(), "p2v-packets-atomic-"));
  const outDir = join(project, ".hyperframes", "frame-packets");
  write(join(project, "frame.md"), "# frame\n");
  write(
    join(project, "STORYBOARD.md"),
    `---\nformat: 1920x1080\n---\n\n## Frame 1 — Intro\n\n- duration: 2s\n- src: compositions/frames/01-intro.html\n\n## Frame 2 — Diff\n\n- duration: 4s\n- src: compositions/frames/02-diff.html\n- focal: code-diff\n\n### Source excerpt\n\n\`\`\`diff\n${"+oversized line\n".repeat(300)}\`\`\`\n`,
  );

  assert.throws(
    () => buildFramePackets({ projectDir: project, outDir, maxPacketBytes: 2_000 }),
    /limit 2000/,
  );
  assert.equal(existsSync(outDir), false);
});

test("code frames without an upstream-selected excerpt fail before dispatch", () => {
  const project = mkdtempSync(join(tmpdir(), "p2v-packets-missing-"));
  write(join(project, "frame.md"), "# frame\n");
  write(
    join(project, "STORYBOARD.md"),
    `---\nformat: 1920x1080\n---\n\n## Frame 1 — Diff\n\n- duration: 4s\n- src: compositions/frames/01-diff.html\n- focal: code-diff\n`,
  );

  assert.throws(
    () =>
      buildFramePackets({
        projectDir: project,
        storyboardPath: join(project, "STORYBOARD.md"),
        outDir: join(project, ".hyperframes", "frame-packets"),
      }),
    /Source excerpt/i,
  );
});

// The other half of this skill's frame-packets delta. The excerpt guard above is
// pinned; the code-vocabulary injection was not — deleting `codeVocabularySection`
// outright left all 455 skills tests green, so the section a code worker reads to
// pick its registry block could have been dropped silently.
test("a code frame carries the vocabulary excerpt for the block it names", () => {
  const project = mkdtempSync(join(tmpdir(), "p2v-packets-vocab-"));
  write(join(project, "frame.md"), "# frame\n");
  write(
    join(project, "STORYBOARD.md"),
    `---\nformat: 1920x1080\n---\n\n## Frame 1 — Diff\n\n- duration: 4s\n- src: compositions/frames/01-diff.html\n- focal: code-diff\n\n### Source excerpt\n\n\`\`\`diff\n-oldCall()\n+newCall()\n\`\`\`\n`,
  );

  const [packet] = buildFramePackets({ projectDir: project });
  const contents = readFileSync(packet.path, "utf8");

  assert.match(contents, /## Code block excerpt \(code-diff\)/);
  assert.match(contents, /`code-diff`/);
});

test("a code block the vocabulary does not describe still names itself for install", () => {
  const project = mkdtempSync(join(tmpdir(), "p2v-packets-vocab-miss-"));
  write(join(project, "frame.md"), "# frame\n");
  write(
    join(project, "STORYBOARD.md"),
    `---\nformat: 1920x1080\n---\n\n## Frame 1 — Diff\n\n- duration: 4s\n- src: compositions/frames/01-diff.html\n- focal: code-not-in-the-vocabulary\n\n### Source excerpt\n\n\`\`\`diff\n-oldCall()\n+newCall()\n\`\`\`\n`,
  );

  const [packet] = buildFramePackets({ projectDir: project });

  assert.match(
    readFileSync(packet.path, "utf8"),
    /## Code block\n\nUse registry block `code-not-in-the-vocabulary`\./,
  );
});

test("a mechanism frame gets no code-block section at all", () => {
  const project = mkdtempSync(join(tmpdir(), "p2v-packets-mechanism-"));
  write(join(project, "frame.md"), "# frame\n");
  write(
    join(project, "STORYBOARD.md"),
    `---\nformat: 1920x1080\n---\n\n## Frame 1 — Mechanism\n\n- duration: 4s\n- src: compositions/frames/01-mechanism.html\n- focal: the request-lifecycle flow\n`,
  );

  const [packet] = buildFramePackets({ projectDir: project });

  assert.doesNotMatch(readFileSync(packet.path, "utf8"), /## Code block/);
});

test("CLI capability detection rejects skills newer than the available command surface", () => {
  const stableHelp = `Project:\n  lint  Validate a composition\n  snapshot  Capture frames\n\nUnknown command check`;
  const currentHelp = `Project:\n  lint  Validate a composition\n  check Run the full project validation gate\n  snapshot  Capture frames`;

  assert.equal(hasCliCommand(stableHelp, "check"), false);
  assert.equal(hasCliCommand(currentHelp, "check"), true);
});

---
name: pr-to-video
description: "Turn a GitHub pull request (a PR URL, owner/repo#N, or 'this PR' in a checked-out repo) into a code-change explainer video — changelog, feature reveal, fix, or refactor walkthrough built from the diff, commits, and files: the input is a code change, not a website. Not a product promo (/product-launch-video) or a no-PR topic explainer (/faceless-explainer). Unclear → /hyperframes."
---

> **First, keep this skill fresh — confirm with the user before running:** `npx hyperframes skills update pr-to-video`. A fast no-op when everything is current; otherwise it refreshes this skill plus the core domain skills it depends on before you rely on them.

> **media-use**: Before sourcing audio/images/logos, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog and brand logos from their official sources. Run `--adopt` first to register existing assets. See `/media-use` skill.

# PR to HyperFrames

Use this skill to ingest a GitHub pull request, understand the change, plan a code-change explainer, and build it frame by frame in HyperFrames. The input is a **code change** (read via `gh`), not a website — there is **no capture step and no real assets** beyond the contributors' avatars.

> **The front door is `/hyperframes`.** You are the orchestrator. Run each step, verify its gate, and only then continue. This skill is for a **GitHub pull request** (a code change). Any other intent, a bare "make a video", or any uncertainty → read `/hyperframes` first — the intent layer owns every route decision, and a fresh creation arriving here without `BRIEF.md` goes through it anyway (Setup's opening rule).

You are the orchestrator. Work in the resolved external `PROJECT_DIR`, never in the caller repository by default. Run steps in order and pass each gate before continuing. User-gated steps are Step 0, Step 3, and Step 6. Read `../hyperframes-core/references/brief-contract.md` before Step 0 — it defines the gate types and how `BRIEF.md`'s `flow`/`storyboard` derive the mode that governs the Step 3/4/6 gates. Do every step yourself except Step 5, where you dispatch a bounded pool of frame workers. Do not put design or motion rules here; those live in the frame-worker sub-agent, this skill's local `../hyperframes-animation/rules/` + `../hyperframes-animation/blueprints/`, and `hyperframes-creative`.

Workflow: Step 0 setup → `hyperframes.json`; Step 1 ingest → `capture/extracted/` + `assets/<login>.png`; Step 2 design system → `frame.md`; Step 3 storyboard/script → `STORYBOARD.md` and `SCRIPT.md`; Step 3.1 audio → `audio_meta.json`; Step 4 visual design → enriched `STORYBOARD.md`; Step 5 frames → `compositions/frames/NN-*.html` and `index.html`; Step 6 final render → `renders/video.mp4`.

---

## Step 0: Setup

Goal: Enter with a confirmed brief — including the **PR reference** (a full URL, an `<owner>/<repo>#<N>` ref, or "this PR" in a checked-out repo) — create the HyperFrames project, and make the brief durable. The style is always **code-editorial** (fixed at Step 2, never asked).

**The brief is confirmed by the intent layer, not by questions asked here.** Opening rule, in order: **(1)** `BRIEF.md` exists → read it and ask nothing — the brief is settled, and its `flow`/`storyboard` derive the mode (brief contract § 1). **(2)** No `BRIEF.md` but the project exists (`hyperframes.json` / `STORYBOARD.md` on disk) → resume from the storyboard's frontmatter and the recorded preferences; never re-interrogate a half-built project. **(3)** Neither — a fresh creation request that arrived here directly → read `/hyperframes` and run its intent layer (`references/intent-interview.md`): it checks recipes and remembered defaults, and conducts this route's questions — including the PR-size → length doctrine, which lives whole in `../hyperframes/references/routes/pr-to-video.md` — then hands back the locked brief. Edit requests skip all of this — go do the edit.

Resolve the project directory before doing any other work. Preserve a user-supplied project directory; otherwise use the durable external cache location printed by the resolver. Never create `videos/` in the caller repository:

```bash
PR="<url | owner/repo#N>"
if [ -n "${EXPLICIT_PROJECT_DIR:-}" ]; then
  PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR" --project-dir "$EXPLICIT_PROJECT_DIR")"
else
  PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR")"
fi
echo "PR-to-video project: $PROJECT_DIR"
node <SKILL_DIR>/scripts/preflight.mjs
```

The capability preflight runs before fetch, story work, audio, or frame dispatch. If the installed CLI cannot run the validation command required by this skill, stop with its upgrade instruction rather than spending the run's context first.

Initialize only if `$PROJECT_DIR/hyperframes.json` is missing. Its basename comes from the PR, such as `acme-sdk-pr-1842`; never use the workspace name or a timestamp.

`npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank --skill=pr-to-video` — `init` checks the installed skills against the latest on GitHub and updates the global set if any are out of date.

Every relative-path command below runs with `$PROJECT_DIR` as its working directory. Examples without an explicit subshell mean `(cd "$PROJECT_DIR" && …)`; never change the caller repository's working tree.

**Write `BRIEF.md` immediately after init** (never before — `init` refuses a non-empty directory): the intent layer's locked brief, shape per `../hyperframes-core/references/brief-format.md`. Resolve `<MEDIA_DIR>` as the installed `/media-use` skill directory. Then record each preference-backed answer with `node <MEDIA_DIR>/scripts/prefs.mjs record --hyperframes .` (`brief-format.md` names the subset). If the intent layer adopted a recipe, run `node <MEDIA_DIR>/scripts/recipe.mjs use --hyperframes . --name <name>`; it copies its `frame.md` into the project (Step 2 is then skipped) and returns the skeletons Step 3 drafts from. A recipe fills answers, not approvals; the review gates still run.

**Show sign-in status before proceeding past Setup** — run `npx hyperframes auth status` and relay its output verbatim. It reports whether voice/BGM will use HeyGen or local engines and, when signed out, how to sign in. Apply one branch:

- **Collaborative:** wait for the user to sign in or explicitly choose `offline` / `go`.
- **Autonomous:** state the status and continue through the available local engines.

Do not silently omit a required capability when no offline provider exists; surface the blocker. Do not fold this decision into another question or write keys into a per-repo `.env`. Auth ownership and offline fallbacks: `/media-use` `references/setup-providers.md` § Providers.

**Gate:** `hyperframes.json` and `BRIEF.md` exist; the PR ref is captured in the brief; the preference-backed answers were recorded (brief contract § 2); sign-in status was shown (signed in, or continuing offline).

---

## Step 1: Ingest the PR (no capture)

Goal: Fetch the PR's facts and fold them into the project as the source of information. There is **no website capture**. `fetch-pr.mjs` runs `gh` deterministically — completing the files list via paginated `gh api` so a large PR doesn't truncate at ~100 files, and writing only `capture/pr.json` + `capture/diff.patch` (no scratch dir). For MERGED PRs it also resolves a best-effort `shipped_version` (+ `version_source`) into `pr.json`, so the end card can cite a real version instead of inventing one. Then `ingest.mjs` folds that into the synthetic capture package offline.

```bash
PR="<url | owner/repo#N | N>"

# Fetch the PR deterministically: runs gh, completes the files list via paginated
# gh api (so a big PR doesn't truncate at ~100 files), writes only capture/pr.json +
# capture/diff.patch — no scratch dir. gh auth / not-found / private errors exit 1 here.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)

# Offline transform → capture/extracted/{tokens.json (colors:[] → code-editorial palette),
# visible-text.txt (the brief), people.json (contributors, bot-filtered, name+login,
# avatarFile=assets/<login>.png)}.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/ingest.mjs \
  --pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)

# The people front's one network step — download each contributor's GitHub avatar to
# assets/<login>.png for the credits close. Best-effort; always exits 0.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
  --people ./capture/extracted/people.json)
```

If `fetch-pr.mjs` exits 1 (gh auth / not found / private), report its stderr and stop — **do not fabricate PR contents**. If `ingest.mjs` exits 1, read its stderr (usually a malformed `pr.json`), fix, and rerun (deterministic). `fetch-people-avatars.mjs` always exits 0; missing avatars just mean no credits close to author.

`people.json` carries a `name` for whichever contributors `gh` already named (the PR author, commit authors, `mergedBy`) — `null` for the rest (reviewers/commenters/assignees, which `gh pr view` only ever gives a bare `login`). Before writing the credits close in Step 3, resolve any `null` name yourself for the 1-6 people who'll actually appear on that frame: `gh api users/<login> --jq .name` (you already have `gh` — no need to script this). If GitHub has no public name for that user either, fall back to the login on-screen and drop that person from the spoken line (see story-design.md's credits section — the voiceover must still say names, never raw handles).

**Gate:** `capture/pr.json`, `capture/diff.patch`, `capture/extracted/tokens.json`, `capture/extracted/visible-text.txt`, and `capture/extracted/people.json` exist; you can state the PR's change in one clear sentence. `assets/<login>.png` is best-effort — its absence is not a failure.

---

## Step 2: Design System

Goal: Adopt the code-editorial frame preset; a script turns it into this video's `frame.md` + caption skin.

The style is fixed — **code-editorial** (warm editorial; a navy code surface built for diffs). Run:

```bash
node <SKILL_DIR>/scripts/build-frame.mjs --preset code-editorial --hyperframes .
```

The script copies the code-editorial preset's `FRAME.md` → `frame.md`, remixes it onto any brand tokens in `capture/extracted/tokens.json` (a PR has none → `colors:[]`/`fonts:[]` keeps code-editorial's own palette, a complete design), copies the preset's caption skin to `.hyperframes/caption-skin.html`, and self-validates (exits 1 on a broken mapping). Proceed as soon as it exits 0 — no hand-editing.

**Gate:** `build-frame.mjs` exited 0 — `frame.md` exists from the code-editorial preset, and `.hyperframes/caption-skin.html` exists as the caption skin source.

---

## Step 3: Storyboard and Script

Goal: Turn the PR into an approved frame-by-frame explanation plan.

Read `../hyperframes-creative/references/story-spine.md` (hook language, value-before-evidence, storyboard-as-proposal, source-traceable visuals), `references/story-design.md`, `../hyperframes-animation/blueprints-index.md`, `../hyperframes-core/references/storyboard-format.md`, and `../hyperframes-core/references/script-format.md`. Use them to write `STORYBOARD.md` and, when narration is needed, `SCRIPT.md`. Set the frontmatter `duration:` from the brief's `length` — a rough expectation; assembly reports where the cut lands against it.

Use `story-design.md` for the PR archetype (changelog / feature-reveal / fix-explainer / refactor-walkthrough), the PR-native frame types, hook, persuasion, beats, the per-frame word budget, and the credits close. The sequence comes from **narrative design, not the diff's file order** — explain the change, don't read the diff aloud. As a **soft guide**, consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`: for each beat, write the voiceover in the shape its candidate blueprint implies and tag that candidate `blueprint:` id when one fits (story truth still decides which beats exist — never force a beat to fit a shape). Feature 2–4 real diff hunks (from `capture/diff.patch`), each a small legible snippet; name the `code-*` block each wants in the frame's `scene`. Frames carry no `asset_candidates` except the `credits` close (1–6 `assets/<login>.png` avatars). Use the exact required fields from the storyboard and script references.

After drafting, run the review loop's plan pass — `../hyperframes-core/references/review-loop.md` § 1: open the board (don't ask whether to — run the preview from `PROJECT_DIR` in the background), present the plan as a proposal, and ask the two questions — approve or change, and **sketches first** (recommended) or skip. Feedback loops through chat or the board's comments file until approved. This is a **checkpoint gate** (brief contract § 1): in autonomous mode there is no board and nothing to ask — post the same summary as a heads-up and proceed; sketches collapse into the build, and the one preview question comes at Step 6.

**Gate:** `STORYBOARD.md` exists, every frame has the required narrative fields, `SCRIPT.md` exists when narration is needed, and the user approved the plan (autonomous: the summary was posted as a heads-up).

---

## Step 3.1: Audio

Goal: Generate narration, word timings, music, and audio metadata from the approved script.

Start audio after Step 3 approval. Run it in the background, then continue to Step 4.

**Choose the narration voice from the user's ask before invoking.** If the request named a voice, gender, or tone, pick a matching voice id and pass it with `--voice <id>`. The pipeline default is otherwise **Marcia (female)** on HeyGen / `am_michael` on Kokoro — so a request like "a male voice" is silently ignored unless you pass the flag. Voice ids are provider-specific; resolve against whichever provider Step 0's sign-in status selected: **HeyGen** (signed in) via `node <MEDIA_DIR>/audio/scripts/heygen-tts.mjs --list` (or `GET /v3/voices?engine=starfish`); **Kokoro** (offline) via the voice table in `<MEDIA_DIR>/audio/references/tts.md` (prefixes `am_`/`bm_` male, `af_`/`bf_` female). When the user expressed no preference, fall back to the remembered voice (brief contract § 2) before the pipeline default, and say which one you used; omit `--voice` only when neither names one. When the user explicitly picked a voice this run, record it (`prefs.mjs record --key voice`).

`node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json --voice <voice-id> &`

The audio script handles narration, word timings, BGM lookup from HeyGen's music library, and timing metadata. BGM mood comes from the storyboard's `music:` field. This uses the HeyGen Audio API for retrieval, not generation, and the same `~/.heygen` credential as TTS. For provider details, read `../media-use/audio/references/tts.md`.

If there is no narration and no `SCRIPT.md`, skip voice generation. BGM may still run if the storyboard has a music mood.

**The canonical fully-silent marker** (shared across the workflows that reuse this audio model): `music: none` in the STORYBOARD.md top YAML block **and** no `SCRIPT.md`. That combination marks the project silent — no narration, no BGM, no SFX. `audio.mjs` recognizes it and generates nothing (it removes any stale `audio_meta.json`; an absent `audio_meta.json` is what assemble treats as silent), so this step is a clean skip. `music: none` with narration keeps TTS and turns only BGM off. Use exactly this spelling — don't improvise other markers.

**Gate:** audio job has started, or the project is marked silent (`music: none` + no `SCRIPT.md`).

---

## Step 4: Frame Visual Design

Goal: Add the visual direction, layout intent, and motion choices to each storyboard frame.

**Sketch the board first (collaborative only).** The moment the plan is approved, run the sketch pass — `../hyperframes-core/references/review-loop.md` § 2 (don't wait on Step 3.1; sketches don't use timings): wireframe every frame yourself, mark each `built`, pause for the one layout question when the board is full, and revise only the sketches named until the board is confirmed. Stand-ins: for a **code beat**, a plain code panel with the filename and a few real diff lines as text — the `code-*` block wiring belongs to the workers. Only then write the visual design below onto the confirmed layouts. In autonomous mode, or when the user chose to skip sketches at Step 3, skip this pass — frames go straight from `outline` to `animated` at Step 5.

Edit `STORYBOARD.md` in place. Do not create another storyboard. Use `frame.md` as source of truth for color, type, layout feel, and style.

Read `references/visual-design.md`, `../hyperframes-animation/blueprints-index.md`, `references/motion-language.md`, `references/code-vocabulary.md`, and `../hyperframes-animation/rules-index.md`. Use `visual-design.md` for the method (the time-coded shot sequence, the inline Layout vocabulary, and the code-beat treatment), plus the required `## Video direction` block. Use `../hyperframes-animation/blueprints-index.md` to pick each frame's shot shape. Use `code-vocabulary.md` to pick the right `code-*` block per code beat (diff = `code-diff`, refactor = `code-morph`, new code = `code-typing`, …). Use `motion-language.md` (the motion vocabulary + the motion doctrine) and `../hyperframes-animation/rules-index.md` (valid rule names) for motion — do not invent motion or block/blueprint names.

For every frame, write a **time-coded shot sequence** into `STORYBOARD.md` per `visual-design.md`'s method: pick the frame's blueprint (or compose), instantiate it with THIS frame's content, and pace each Scene's reveal to the voiceover so the frame develops across its full duration instead of front-loading then freezing. **For a code beat, the `code-*` block is the frame's `focal`** and the Scenes choreograph the surrounding code-editorial Code Surface (the entry of the file/header, the camera onto the hunk, the landing line) — **not** the code animation itself, which the block owns. Immediately after each code frame's fields, add a `### Source excerpt` fenced `diff` block containing only the exact real hunk the worker must render (12 lines maximum). Select it here from `capture/diff.patch`; workers are forbidden from reopening that full diff. State layout and motion **inline** per Scene (vocabularies in `visual-design.md` and `motion-language.md`). Add one video-wide `## Video direction` block.

Do not change story, script, `transition_in`, `asset_candidates`, or the PR source. Do not write HTML in this step. There is **no asset-staging step** — the only real assets are the credits avatars, already in `assets/`.

**Gate:** every frame has a time-coded shot sequence whose reveals are paced to the voiceover (no front-loading); code frames name a `code-*` block as the `focal`; `## Video direction` exists. Collaborative: the sketch board was confirmed.

---

## Step 5: Build Frames

Goal: Build every storyboard frame as an HTML composition and assemble the playable video.

Wait for Step 3.1 audio to finish if audio was started. Then sync durations and fetch SFX; skip both if silent.

`node <SKILL_DIR>/scripts/audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md`

`node <SKILL_DIR>/scripts/audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .`

Duration sync is mechanical: real voice duration wins; silent frames keep estimates; never hand-edit synced durations.

**Pre-install the registry blocks** named across `STORYBOARD.md` once, before dispatch, so parallel workers don't race on the registry:

`for b in <each registry block named in the storyboard>; do npx hyperframes add "$b"; done`

Before dispatch, read `../hyperframes-core/references/subagent-dispatch.md`. Build bounded packets and the worker role payload:

```bash
node <SKILL_DIR>/scripts/frame-packets.mjs --project "$PROJECT_DIR" --storyboard "$PROJECT_DIR/STORYBOARD.md"
```

The packet builder hard-fails a code frame without the upstream-selected `### Source excerpt`, and hard-caps packet bytes. It also writes `_role.md` (`../hyperframes-core/references/frame-worker-core.md` + this skill's `sub-agents/frame-worker.md`, concatenated verbatim — the complete worker role). Dispatch **at most three workers total**, balanced across the packet paths; each worker's prompt carries `_role.md` and its assigned packet paths — paste the role in full or hand its path (equivalent; the worker starts from exactly those documents) — and each worker may build multiple assigned frames sequentially, reading the role once. Workers read only their packet(s) and `frame.md`. They never open the full `STORYBOARD.md`, `capture/diff.patch`, or `capture/extracted/visible-text.txt`. Each worker writes only its assigned `compositions/frames/NN-*.html`; workers never edit `STORYBOARD.md`. When a frame has a **confirmed sketch** on disk (collaborative runs — review loop § 3), say so in that worker's dispatch context: the sketch is the existing `compositions/frames/NN-*.html`, and the worker dresses that layout rather than redrawing it (frame-worker core § When a confirmed sketch exists).

On a failed frame, re-dispatch **that frame only**, with its existing packet plus the exact validator/lint finding. One retry maximum. Do not replay a whole batch and do not retry without a concrete finding.

**Full-bleed backgrounds ride on a `class="clip"` layer, never the `#root`.** A frame's ground (color field / gradient / grid) is its own full-duration background clip — a `background` set on the `#root` / `data-composition-id` element is clip-gated to the frame's window and is not a dependable ground, so dark content can land on the black host `body` and render invisible. The video's base ground is painted by the assembler from `frame.md`'s `canvas` color onto the index `#root`. (Full rule + self-check: `../hyperframes-core/references/frame-worker-core.md`.)

As each worker returns, mark that frame `animated` in `STORYBOARD.md`.

After audio timings exist, build captions in the background and assemble the index:

`node <SKILL_DIR>/scripts/captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json &`

`node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard ./STORYBOARD.md --hyperframes .`

`captions.mjs` uses the project's `.hyperframes/caption-skin.html` (code-editorial's, copied in Step 2), injecting brand tokens from `frame.md`; `captions: skipped (<reason>)` is valid. `assemble-index.mjs` stages the credits avatars from `assets/` as an idempotent backstop.

**Gate:** every frame is marked `animated` (collaborative: the sketch board was confirmed at Step 4), `index.html` exists, and captions are built or explicitly skipped.

---

## Step 6: Finalize

Goal: Verify the assembled video, get user approval, and render the final MP4.

Inject transitions, run checks, pause for review, then render.

`node <SKILL_DIR>/scripts/transitions.mjs inject --storyboard ./STORYBOARD.md --hyperframes .`

`node <SKILL_DIR>/scripts/transitions.mjs verify --storyboard ./STORYBOARD.md --index ./index.html`

`npx hyperframes lint`

`npx hyperframes check`

`npx hyperframes snapshot --at <frame-midpoints>`

`snapshot` stitches the captured frames into one contact sheet (`snapshots/contact-sheet.jpg`). Glance at it; if nothing is obviously broken, move on — don't linger here.

If a command fails, surface stderr and stop — don't pile on recovery commands. Fix it yourself: the cheapest safe edit to `compositions/frames/NN-*.html`, then rerun the failed check.

**Known false-positive — do not chase it.** `check` may report a handful of `text_box_overflow` errors of ~1–4px on the **caption** highlight words (selector `#caption-word-*` / `.caption-line`). The caption pill uses a deliberately snug `line-height` (set once in `scripts/captions.mjs`) and has **no `overflow:hidden`**, so a heavy display glyph's ink spills a few px into the pill's own padding — nothing is actually clipped. Treat these as expected and proceed. Do **not** inflate the caption `line-height` (it balloons the pill, which is worse). Only act on a `text_box_overflow` when it names a **frame** element (`#el-NN-*`), not a caption word.

After checks pass, pause for user review — the review loop's final look (`../hyperframes-core/references/review-loop.md` § 4): one question, on the Studio that has been open since Step 3 — render now, or what changes? (Autonomous: the one kept question, preview first or render — open the preview with the command below on a yes.) Then deliver the MP4 with the contact sheet and the frame ids so revisions can target a single frame.

Preview: `npx hyperframes preview "$PROJECT_DIR" --background`

Render only after user approval (autonomous mode: after the preview-or-render question):

`npx hyperframes render --skill=pr-to-video --quality high --output renders/video.mp4`

Do not rerun `lint`, `check`, or `snapshot` after rendering unless the user asks.

After the user is done reviewing (or after render when no more live edits are expected), stop only this project's background server: `npx hyperframes preview "$PROJECT_DIR" --stop`. Never tear it down while waiting for review.

**Gate:** `lint` and `check` passed and the snapshots were inspected before render; user approved at the review pause (autonomous: checks passed and the delivery includes the contact sheet); `renders/video.mp4` exists. Final reply states the MP4 path and final duration.

---

## Quick Reference

**Formats:** landscape `1920x1080`; portrait `1080x1920`; square `1080x1080` — derived from the destination (brief contract § 2). Set the format once in the storyboard frontmatter.

**PR deltas vs a captured-asset workflow:** no Step 1 capture (the `gh` CLI ingests the PR into a synthetic `capture/extracted/` package — `tokens.json` + `visible-text.txt` + `people.json`); the only real assets are the contributors' `assets/<login>.png` avatars (the credits close); no `asset-descriptions.md`, no asset-staging step. Code beats are rendered by the `code-*` registry blocks on code-editorial's navy Code Surface; the style is always **code-editorial**.

**Background scripts:** the workflow ships these under `scripts/`: `fetch-pr` (PR → `capture/pr.json` + `diff.patch` via `gh`; large-PR-safe, no scratch), `ingest` (→ synthetic capture package; offline), and `fetch-people-avatars` (contributor avatars → `assets/`); plus the shared engine — `build-frame` (adopt + brand-remix a preset into `frame.md` + caption skin), `audio` (TTS, BGM, SFX, duration sync), `captions`, `transitions` (inject + verify), and `assemble-index`. Everything else is the `hyperframes` CLI. Code blocks install via `npx hyperframes add <name>`.

The reusable, domain-agnostic shot shapes live in `../hyperframes-animation/blueprints/` (indexed by `../hyperframes-animation/blueprints-index.md`); the `code-*` registry blocks are the code-beat vocabulary (`references/code-vocabulary.md`).

| Read                                                                                                                                                        | When                                                                                                     |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `[../hyperframes-core/references/brief-contract.md](../hyperframes-core/references/brief-contract.md)`                                                      | Gate types, mode derivation from `BRIEF.md`, field semantics.                                            |
| `[../hyperframes-creative/references/story-spine.md](../hyperframes-creative/references/story-spine.md)`                                                    | Step 3: story doctrine — hook language, value-before-evidence, proposal shape, source-traceable visuals. |
| `[references/story-design.md](references/story-design.md)`                                                                                                  | Step 3: plan the PR explanation.                                                                         |
| `[../hyperframes-animation/blueprints-index.md](../hyperframes-animation/blueprints-index.md)`                                                              | Step 3: role→blueprint menu. Step 4: pick the shot shape.                                                |
| `[../hyperframes-core/references/storyboard-format.md](../hyperframes-core/references/storyboard-format.md)`                                                | Step 3: write `STORYBOARD.md`.                                                                           |
| `[../hyperframes-core/references/script-format.md](../hyperframes-core/references/script-format.md)`                                                        | Step 3: write `SCRIPT.md`.                                                                               |
| `[../media-use/audio/references/tts.md](../media-use/audio/references/tts.md)`                                                                              | Step 3.1: choose or understand TTS providers.                                                            |
| `[references/visual-design.md](references/visual-design.md)`                                                                                                | Step 4: write the frame's shot sequence (+ Layout vocabulary).                                           |
| `[references/code-vocabulary.md](references/code-vocabulary.md)`                                                                                            | Step 4 + 5: pick + fill the `code-*` block for a code beat.                                              |
| `[references/motion-language.md](references/motion-language.md)`                                                                                            | Step 4: the motion vocabulary + the motion doctrine.                                                     |
| `[references/cut-catalog.md](references/cut-catalog.md)`                                                                                                    | Step 4-5: the cut catalog (worker builds within-frame seams).                                            |
| `[../hyperframes-animation/rules-index.md](../hyperframes-animation/rules-index.md)` + `[../hyperframes-animation/rules/](../hyperframes-animation/rules/)` | Step 5: local rule recipe bodies for the cited motions.                                                  |
| `[../hyperframes-core/references/frame-worker-core.md](../hyperframes-core/references/frame-worker-core.md)`                                                | Step 5: the shared worker contract (packet builder prepends it to the delta).                            |
| `[sub-agents/frame-worker.md](sub-agents/frame-worker.md)`                                                                                                  | Step 5: the workflow's frame-worker delta.                                                               |
| `[../hyperframes-core/references/subagent-dispatch.md](../hyperframes-core/references/subagent-dispatch.md)`                                                | Step 5: dispatch sub-agents safely.                                                                      |
| `[../hyperframes-creative/frame-presets/code-editorial/FRAME.md](../hyperframes-creative/frame-presets/code-editorial/FRAME.md)`                            | Step 2: the code-editorial preset (fixed style).                                                         |

# Frame worker — PR-to-video delta

> The shared law is the core contract above (the packet builder prepends `../hyperframes-core/references/frame-worker-core.md` to this file as `_role.md`) — read the two as one role. This file carries only what's specific to a PR-to-video frame.

## Batch dispatch — you build a small packet batch

At most three workers run; your dispatch assigns **one or more** bounded packet paths under `.hyperframes/frame-packets/`. Read this role and shared `frame.md` **once**, then process the packets in order — for each, use its exact frame block, inlined blueprint / rule excerpts, and (for a code beat) the selected code-block / source excerpts. Never open the full `STORYBOARD.md`, `capture/diff.patch`, or `capture/extracted/visible-text.txt`; the orchestrator already selected the exact source excerpt and put it in each code frame's packet. After the last assigned file passes the self-check, stop.

Extra inputs beyond the core contract:

- `code-vocabulary.md` — absolute path provided in your dispatch. For a **code beat**, read it for the named `code-*` block's exact inputs (`window.__TOKENS`, `window.__BLOCK`, line indexing); your packet carries the matching excerpt.
- `focal:` — for a concept/mechanism beat, which **invented** element is the hero; for a **code beat**, the named **`code-*` block** (+ the hunk); for the **credits** close, the avatar row.
- `roles:` — each element's role: `foreground subject` / `background` full-bleed / `supporting`. Most are invented elements you design; the only real assets are the credits `assets/<login>.png` avatars.

## Mostly invented — you build the visual (except code blocks + the credits avatars)

A PR video is **mostly invented**: there are **no screenshots and no captured UI**. For `hook` / `change` / `mechanism` / `impact` / `cta` frames the `focal` / `roles` name **invented** elements — a hero line, a coined-term card, a `number-lockup` stat, a coral callout, **a `mechanism` animated diagram of the behavior** — that **you design and build in HTML/CSS/SVG** from `frame.md`. Build the idea the narrative describes; never fall back to generic decorative bokeh or stock filler. Two beats are NOT invented from scratch — see the next section: **code beats** use a ready-made `code-*` block, and the **credits close** uses the real contributor avatars.

## PR code beats, mechanism beats + the credits close

- **Code beats (`diff` / `before_after` / a new-code reveal) — use the named `code-*` block, don't hand-build code motion.** Your `## Frame N` `scene` / `focal` names which block (e.g. `code-diff`, `code-morph`, `code-typing`); the orchestrator has already installed it (pre-install step). Read the `code-vocabulary.md` excerpt in your packet for that block's exact inputs, then:
  - Use only the packet's `### Source excerpt`. It is the real before/after hunk selected upstream. Never reopen the full diff or brief.
  - Fill the block's `window.__TOKENS` with that real code (the baked Shiki tokens) and set `window.__BLOCK` (effect, `line`, `duration`) **so the full block completes within the frame's `data-duration`** — a long snippet at the block's default per-character cadence overruns a short frame (the code never finishes typing). `code-diff` / `code-morph` need **2 states** (before, after); the others take one. **Line indexing differs — `code-highlight` is 0-based, `code-scroll` 1-based** — don't off-by-one.
  - Integrate the filled block as **this frame's composition** per the core sub-composition contract: its `data-composition-id` and its `window.__timelines[...]` key must both be your **`<frame_id>`** (the block ships its own id + paused timeline; rename both to match the frame contract). The block already renders an editor window (titlebar / filename) reading as code-editorial's navy **Code Surface** — set the filename + any `+N/−M` chrome from the `scene`.
  - **The block owns the code animation; your Scene windows choreograph the surrounding Code Surface** — the navy window seating in, the file header typing on, the camera settling onto the hunk, a coral underline on the landed line. **Do not re-specify the code motion** (the block is the development beat). A code beat is usually `blueprint: compose`.
  - **The block has no caption-safe band.** When `Captions: enabled`, inset/scale the code panel into the top ~83% so it clears the keep-out band; never let code run under the caption pill.
- **Mechanism beats (`mechanism`) — build an invented animated diagram of the behavior; the build _is_ the shot.** This is the "show what the change does at runtime" frame (the request retrying, the cache filling, serial→parallel, the race resolved) — read its `scene` for the behavior to animate. Unlike a code beat, **the motion is yours to author** (no block owns it):
  - If the `scene` names a `flowchart` / `flowchart-vertical` / `data-chart` block, the orchestrator pre-installed it — fill + mount it like a code block (its `data-composition-id` and `window.__timelines[...]` key both become your `<frame_id>`). Otherwise **hand-build the diagram in SVG / HTML / GSAP** from `frame.md`'s atoms.
  - **Code editorial register:** hairline-ink nodes / edges / lanes on the cream ground, **one coral marker** on the active / changed element, mono labels — **not** the navy code surface (that's for code), no heavy shapes / bokeh.
  - **Choreograph the Scene windows:** the nodes / lanes draw on (Scene 1); **the flow runs** as the VO names each step (middle Scenes — the request hops, the lane splits, the front advances, the bars race) — this _is_ the teaching, so it must play across the shot, never enter-then-freeze; the resolved state + the one coral emphasis lands (final Scene). Keep it in the top ~83% (caption keep-out).
- **The `credits` close — the one frame with real assets.** Its `asset_candidates` names 2–6 `assets/<login>.png` avatars (downloaded upstream). Render them as `<img>` in hairline-ringed chips — an avatar row with each contributor's name + role in mono (an "approved" mark if the close calls for it), staggered in across the Scene windows. Avatars appear **only** here, never decorating a code frame.

## PR-specific self-check additions

- The composition root also carries a **positive `data-duration` matching the packet**.
- **Code-block cadence fits `data-duration`** — for a code beat, the `code-*` block's internal cadence is set so the full block completes within the frame's `data-duration` (a long snippet at the default per-character speed overruns — the code never finishes and the chrome beats never play; see `code-vocabulary.md`).
- Fonts: copy the auto-generated `@font-face` block from `frame.md`; the Code editorial preset's EB Garamond, Inter, and JetBrains Mono faces live in `assets/fonts/`. Never link Google Fonts.
- Visible-text exception: real code inside a `code-*` block is the content, not narration.