chore: import upstream snapshot with attribution

skills/hyperframes-creative/frame-presets/cobalt-grid/FRAME.md

@@ -0,0 +1,265 @@
+---
+version: alpha
+name: Cobalt Grid — Frame (video / frame layer)
+description: >
+  Video-first companion to Cobalt Grid's design.md. The unit is the frame (1920×1080). Atoms
+  are identical and sacred — warm cream paper, electric cobalt ink (the only ink), the permanent
+  graph-paper grid, Newsreader serif 400 + Hanken Grotesk + DM Mono, the top/bottom cobalt
+  hairlines, and the pixel-glitch + QR-block signatures. Composition, frame scale, and
+  aspect-ratio behavior are rewritten for the frame. Motion is out of scope.
+unit: the frame — 1920×1080 primary; 9:16 and 1:1 documented
+principle: atoms are sacred · composition is free · numbers come from the script
+
+colors:
+  paper: "#F0EBDE"
+  paper-2: "#E6E0CE"
+  ink: "#1F2BE0"
+  ink-soft: "#5560E5"
+  grid: "rgba(31,43,224,0.10)"
+  ink-faint: "rgba(31,43,224,0.18)"
+
+typography:
+  # — reading ramp —
+  body:        { fontFamily: "Hanken Grotesk", cqw: 0.83, weight: 400, lineHeight: 1.5 }
+  body-lede:   { fontFamily: "Hanken Grotesk", cqw: 0.95, weight: 400, lineHeight: 1.5 }
+  micro:       { fontFamily: "Hanken Grotesk", px: 13, weight: 600, tracking: "0.16em", upper: true }
+  micro-strong:{ fontFamily: "Hanken Grotesk", px: 16, weight: 600, tracking: "0.18em", upper: true }
+  mono-tag:    { fontFamily: "DM Mono", cqw: 0.78, weight: 400, tracking: "0.05em" }
+  mono-chrome: { fontFamily: "DM Mono", px: 13, weight: 400, tracking: "0.06em" }
+  # — display / hero ramp (Newsreader 400, negative tracking) —
+  table-name:  { fontFamily: "Newsreader", cqw: 1.5, weight: 400, lineHeight: 1.15 }
+  row-headline:{ fontFamily: "Newsreader", cqw: 2.1, weight: 400, lineHeight: 1.05 }
+  ed-callout:  { fontFamily: "Newsreader", cqw: 2.6, weight: 400, lineHeight: 1.1, italic: true }
+  headline:    { fontFamily: "Newsreader", cqw: 4.6, weight: 400, lineHeight: 0.95 }
+  headline-index:{ fontFamily: "Newsreader", cqw: 5.0, weight: 400, lineHeight: 0.95 }
+  display-quote:{ fontFamily: "Newsreader", cqw: 5.7, weight: 400, lineHeight: 1.05, tracking: "-0.005em" }
+  display-chapter:{ fontFamily: "Newsreader", cqw: 6.8, weight: 400, lineHeight: 1.0, tracking: "-0.005em" }
+  display-closing:{ fontFamily: "Newsreader", cqw: 9.4, weight: 400, lineHeight: 0.96, tracking: "-0.005em" }
+  display-hero:{ fontFamily: "Newsreader", cqw: 10.4, weight: 400, lineHeight: 0.9, tracking: "-0.008em" }
+  vbig-numeral:{ fontFamily: "Newsreader", cqw: 12.5, weight: 400, lineHeight: 0.9, tracking: "-0.015em" }
+
+spacing:
+  edge: "4cqw"          # standard frame edge inset (~80px@1920)
+  pad-top: "7cqw"
+  pad-bottom: "6cqw"
+  gap-md: "2cqw"
+
+components:
+  graph-grid:
+    backgroundImage: "linear-gradient grid, ~2cqw cells, 10% {colors.ink} ({colors.grid})"
+    placement: "behind EVERY frame on the ground"
+    description: "Permanent graph-paper grid — never disabled; the canvas tone."
+  hairlines:
+    rule: "0.12cqw solid {colors.ink}"
+    placement: "≈3cqw from top + bottom, inset {spacing.edge}"
+    description: "Two persistent cobalt rules framing every composition."
+  page-chrome:
+    typography: "{typography.pagenum}"
+    color: "{colors.ink}"
+    placement: "page number bottom-right, nav/meta hint bottom-left, above the bottom hairline"
+    description: "The only persistent chrome."
+  pixel-glitch:
+    backgroundColor: "{colors.paper}"
+    fill: "repeating-linear-gradient(90deg, {colors.ink} 0 2px, transparent 2px 8px)"
+    size: "14–30cqw wide, full height, stair-stepped"
+    placement: "right on cover/data, left on chapter/colophon; z above grid, below headline"
+    description: "Stair-stepped scanline column. Decorative."
+  qr-block:
+    backgroundColor: "{colors.paper}"
+    cells: "8×8, {colors.ink} on / {colors.grid} off"
+    size: "3–9cqw square"
+    shadow: "0 0 0 0.12cqw {colors.paper} (anti-shadow for readability, not elevation)"
+    description: "QR mosaic patch — corner punctuation."
+  topbar-rule:
+    typography: "{typography.headline-index} + {typography.mono-tag}"
+    borderBottom: "0.12cqw solid {colors.ink}"
+    description: "Section header on index/data/table frames."
+  ledger-row:
+    layout: "grid: mono num · Newsreader name · Hanken desc · mono delta"
+    borderBottom: "0.06cqw solid {colors.ink-faint} (header 0.12cqw solid {colors.ink})"
+    typography: "{typography.mono-tag} + {typography.table-name} + {typography.body}"
+    description: "Dense matrix row with ↑/↓/— delta."
+  pixel-stack-bar:
+    cells: "column-reverse, {colors.grid} off / {colors.ink} on"
+    baseline: "0.12cqw solid {colors.ink} + {typography.mono-tick} ticks"
+    description: "Data as grid-unit cells; echoes the glitch."
+  vstack-label:
+    typography: "{typography.mono-tick}"
+    transform: "writing-mode: vertical-rl"
+    description: "Catalogue chrome along a frame edge."
+---
+
+# Cobalt Grid — Frame (video / frame layer)
+
+## Overview
+
+Cobalt Grid at frame scale is a **two-color risograph trend-report** — warm cream paper, electric
+cobalt ink, and a **permanent graph-paper grid** behind every frame. Cobalt is the _only_ ink:
+headlines, body, rules, the grid, the pixel-glitch decoration, the QR patches. There is no accent
+color and no second surface.
+
+The voice is a three-face conversation: **Newsreader** serif at weight 400 (size, not weight,
+makes hierarchy) carries every display and headline; **Hanken Grotesk** carries body and
+uppercase tracked labels; **DM Mono** carries all chrome — page numbers, tags, ticks, vertical
+stacks. Every frame is framed by top + bottom cobalt hairlines; declarative frames carry the
+**pixel-glitch column** and a **QR-block** patch.
+
+**Key characteristics at frame scale:**
+
+- **Strictly two-color** — cream paper + cobalt ink; no accent, no second surface.
+- **Permanent ~2cqw graph-paper grid** (10% cobalt) behind every frame; cannot be disabled.
+- **Top + bottom 1.5px cobalt hairlines** frame every composition, inset by `edge`.
+- **Newsreader 400** for all display (negative tracking); **Hanken 600** uppercase 0.16em labels; **DM Mono** chrome.
+- **Pixel-glitch column + QR-block** as the signature decorative patches on declarative frames.
+- **Pixel-stack bars** render data as grid-unit cells (cobalt on / 10% off).
+
+## The Frame
+
+### Frame Craft Bar
+
+Three eyeball tests gate every frame before any structural check:
+
+- **Squint** — one Newsreader element dominates at **3–6× its nearest neighbor** (`display-hero`/`vbig-numeral`); hierarchy is size, never weight.
+- **Silence** — declarative frames (cover, chapter, quote, colophon) read **45–60% empty** with the grid showing; the **index ledger and data frame are the one dense exception** (density via quiet repetition, not richness).
+- **Restraint** — **two-color only** (cream + cobalt, never a second hue); one pixel-glitch column and at most one QR-block per declarative frame.
+- **Reference** — aim at a **WIRED Japan / Shift two-color risograph monograph**; failure looks like a **colorful dashboard with a second accent hue**.
+
+- **Primary:** 1920×1080 (16:9). Display authored in **`cqw`** (`px ÷ 1920 × 100 = cqw`).
+- **Vertical:** 1080×1920 (9:16). **Square:** 1080×1080 (1:1).
+- **Safe area:** `edge` (4cqw) inset; hairlines + page chrome live on the safe line.
+
+**The container law (load-bearing).** Every frame ground sets `container-type: size` AND carries
+the graph-paper `background-image`; ALL frame-relative units are `cqw`/`cqh` against it — never
+`vw`. The grid `background-size` is `~2cqw 2cqw` so cell density holds at any render size.
+
+## Colors
+
+Tokens identical to the source. `{colors.paper}` is the ground; `{colors.ink}` cobalt is the only
+ink (type, rules, grid lines, glitch, QR). `{colors.ink-soft}` is a secondary cobalt for editorial
+subtitles only; `{colors.grid}` (10%) is the permanent grid + chart "off" cells; `{colors.ink-faint}`
+(18%) is faint row dividers. **Never a second hue** — emphasis comes from size, from switching
+Hanken→Newsreader, from a mono delta arrow, or from opacity, never from color.
+
+## Typography
+
+Two ramps. The **reading ramp** (Hanken body 0.83cqw, mono chrome in px) carries copy + labels;
+the **display/hero ramp** (Newsreader `headline` 4.6cqw → `vbig-numeral` 12.5cqw) carries every
+statement and figure.
+
+- **Legibility floor:** any load-bearing line ≥ **1.4cqw**; mono chrome (px) is colophon only.
+- **Fit-to-measure:** size the headline to its line length. Cap the block at **≤ 78cqw**; ≤3 words → `display-hero`/`vbig-numeral`; 4–6 → `display-chapter`; 7+ → `headline`.
+- **Newsreader at 400 only**, in cobalt, with negative tracking (hero −0.008em, numeral −0.015em). **Hanken labels uppercase, 0.16–0.18em.** **DM Mono 0.04–0.08em.** No bold serif.
+
+## Depth & Surface
+
+Flat. Depth is structural only:
+
+- **1.5px cobalt rules** — slide hairlines, topbar rule, chart baseline.
+- **1px ink-faint dividers** — dense list / ledger rows.
+- **The graph-paper grid** — measured-plane tone behind everything.
+- **Pixel-glitch + QR** — texture and graphic punctuation, no z-axis.
+
+**Ceiling:** no drop shadow (the QR's 1.5px paper outset is an anti-shadow for readability, not elevation), no gradient, no rounded corner, no second color.
+
+## Shapes
+
+- **0 radius everywhere** — frames, ledger rows, QR cells, glitch blocks, charts. Zero circular elements; this squareness is part of the identity.
+
+## Components
+
+- **graph-grid / hairlines / page-chrome** — the permanent frame furniture, inherited by every composition.
+- **pixel-glitch** (edge column) + **qr-block** (corner patch) — the signature decoration on declarative frames.
+- **topbar-rule** — the index/data/table section header. **ledger-row** — dense matrix row with delta arrows.
+- **pixel-stack-bar** — data as grid-unit cells. **vstack-label** — vertical mono catalogue chrome.
+
+## Frame Treatments
+
+> Recipe: ground · container · composes · focal · chrome · accent · silence · Fixed/Free · density.
+> The grid + hairlines are present on every frame. Choose density by type: declarative = sparse, index/data = dense.
+
+### 1 · Hero Cover (identity · move: serif + glitch · left)
+
+**Ground** paper + grid, hairlines. **Composes** pixel-glitch (right, ~26cqw), qr-block (top-right), display-hero, ed-callout. **Focal** a 1–2 line `display-hero` Newsreader headline in cobalt, left-anchored, with an italic `ed-callout` subtitle in `{colors.ink-soft}`. **Chrome** Hanken kicker; mono meta top + page number. **Accent** none (cobalt is the only ink). **Silence** ~45% paper. **Fixed** Newsreader 400, glitch + QR present, grid + hairlines. **Free** title, glitch step pattern, QR placement. **Density** sparse.
+
+### 2 · Index Ledger (catalog · move: dense matrix · left — the dense frame)
+
+**Ground** paper + grid, hairlines, `pad-top`/`pad-bottom`. **Composes** topbar-rule, ledger-rows. **Focal** a topbar (`headline-index` + mono lab-tag, 1.5px rule) over 4–6 ledger rows (mono num · Newsreader name · Hanken desc), ink-faint dividers. **Chrome** page number. **Accent** mono delta arrows. **Silence** tight — the density exception (the grid wants filling). **Fixed** 1.5px topbar rule, 1px ink-faint dividers, Newsreader names. **Free** rows, lab-tag, deltas. **Density** dense-exception.
+
+### 3 · Chapter Opener (section · move: scale · sparse · left)
+
+**Ground** paper + grid, hairlines. **Composes** pixel-glitch (left, ~14cqw, low opacity), mono index, display-chapter, body-lede. **Focal** a `display-chapter` Newsreader title, with a small mono `CHAPTER NN` index above and an optional Hanken lede ≤42cqw. **Accent** none. **Silence** ~60% — let the grid breathe. **Fixed** Newsreader 400, glitch low-opacity, grid showing. **Free** title, lede, glitch side. **Density** sparse.
+
+### 4 · Data Frame (chart · move: pixel-stack · left)
+
+**Ground** paper + grid, hairlines, `pad-top`. **Composes** topbar-rule, pixel-stack-bar row. **Focal** a row of 6–8 pixel-stack bars (cobalt on / 10% off) over a 1.5px cobalt baseline with mono ticks. **Chrome** topbar headline + mono fig-tag; page number. **Accent** none — data is cobalt cells. **Silence** moderate. **Fixed** grid-unit cells, cobalt baseline, mono ticks. **Free** bar values (from script), tick labels. **Density** standard/dense.
+
+### 5 · Manifesto / Quote (quote · move: centered statement · sparse)
+
+**Ground** paper + grid, hairlines. **Composes** display-quote (or display-manifesto), attribution rule, optional compact glitch. **Focal** a 2–3 line Newsreader pull in cobalt, with a Hanken kicker above and a 1px cobalt attribution rule + mono byline beneath. **Accent** none. **Silence** ~55% — deliberately open. **Fixed** Newsreader 400, attribution rule, grid showing. **Free** quote, byline. **Density** sparse.
+
+### 6 · Colophon (closer · move: right-aligned close · sparse)
+
+**Ground** paper + grid, hairlines. **Composes** pixel-glitch (left edge, mirroring the cover), display-closing, mono credit columns. **Focal** a right-aligned `display-closing` Newsreader title with a Hanken kicker above. **Chrome** 3–4 column mono credit grid at the foot; page number. **Accent** none. **Silence** ~50%. **Fixed** glitch on left, Newsreader 400. **Free** closing line, credits. **Density** sparse.
+
+## Composition Rules
+
+### Do
+
+- Keep the **graph-paper grid + top/bottom hairlines** on every frame — they are the system.
+- Set **Newsreader at 400 in cobalt**; make hierarchy with size, not weight; negative-track display.
+- Track **Hanken labels uppercase 0.16em**; **DM Mono chrome 0.04–0.08em**.
+- Render data as **pixel-stack cells** (cobalt on / 10% off); echo the glitch language.
+- Use the **pixel-glitch column + QR patch** on declarative frames (cover, chapter, quote, colophon).
+- Lean: declarative frames sparse and breathing; index/data dense. Vary anchor (left for index/chapter, centered for quote/closer).
+
+### Don't
+
+- Don't introduce a second ink color — cream + cobalt only.
+- Don't bold Newsreader, round any corner, or add a drop shadow (QR outset is an anti-shadow only).
+- Don't disable the grid or suppress the hairlines.
+- Don't crowd chapter / quote / colophon — those let the grid show.
+- Don't blow a serif headline edge-to-edge — fit to measure.
+
+## Aspect-Ratio Behavior
+
+| Treatment         | 16:9                        | 9:16                                 | 1:1                          |
+| ----------------- | --------------------------- | ------------------------------------ | ---------------------------- |
+| Hero Cover        | headline left, glitch right | headline top, glitch full-width band | headline upper, glitch lower |
+| Index Ledger      | topbar + rows               | topbar + fewer rows                  | 2-col compresses to 1        |
+| Chapter Opener    | title left, glitch left     | title top, glitch side               | centered title               |
+| Data Frame        | 6–8 bars                    | 4–5 bars taller                      | square chart                 |
+| Manifesto / Quote | centered pull               | centered, taller                     | centered                     |
+| Colophon          | right-aligned, glitch left  | stacked, glitch top                  | centered close               |
+
+Grid + hairlines hold on the short edge for every ratio; re-step display so no load-bearing line
+drops below 1.4cqw. Mono chrome stays Latin/digit-only.
+
+## Approved Entities
+
+No real customers, logos, or vendors are defined in the source — render any such mark as a
+placeholder. Trend names, signals, and figures are content; the system supplies the grid and chrome.
+
+## Numerals & Claims (hard rule)
+
+Never invent figures, deltas, dates, or signal counts at frame scale. Render slots as `— figure —`,
+`{metric}`, `↑ —`. Pixel-stack bar heights and ledger deltas especially carry placeholders until the
+script supplies values. Mono catalogue ordinals (001, 002…) are decorative and may be sequential.
+
+## Pre-Render Self-Audit
+
+- **Squint** — one Newsreader element dominates at 3–5× its neighbor.
+- **Silence** — declarative frames 45–60% empty; only index/data run dense.
+- **Two-color** — cream + cobalt only; no second hue anywhere.
+- **Furniture** — grid present, top/bottom hairlines present, page chrome above the hairline.
+- **Type** — Newsreader 400 negative-tracked, fit-to-measure; Hanken labels 0.16em; ≥1.4cqw floor.
+- **Depth** — 0 shadow (QR outset excepted), 0 rounded corner.
+- **Anchor** — left on index/chapter/cover, centered on quote/closer; no 3 consecutive frames share an anchor.
+- **Fabrication** — every numeral/delta traces to the script, else placeholder.
+
+## Known Gaps
+
+- **Motion intentionally out of scope.** frame.md specifies composition only; the 280ms cross-fade in the source is a deck mechanic.
+- **Pixel-glitch is rendered in CSS here** (stacked scanline blocks) rather than the source's inline SVG, to keep the showcase SVG-free; fidelity is preserved.
+- **Three Google Fonts** (Newsreader, Hanken Grotesk, DM Mono); CJK pairing (Noto Serif SC 700/400) carries over from the source.
+- **9:16 / 1:1 are guidance**; verify the legibility floor and grid density per ratio.
+- The QR mosaic and glitch step patterns are hand-authored; there is no generative layer.

skills/hyperframes-creative/frame-presets/cobalt-grid/caption-skin.html

@@ -0,0 +1,238 @@
+<!--
+  Cobalt Grid — caption skin (preset-local source).
+
+  This is the preset's own lower-third karaoke caption look. product-launch-video's
+  Step 2 copies it into the project as caption-skin.html; captions.mjs then fills the
+  three reserved holes, wraps the fragment in a <template>, and writes
+  compositions/captions.html:
+    · the empty GROUPS array            → the engine's scene-aware word groups
+    · the 0 duration + 0 width/height   → real total + canvas size
+    · the empty data-brand-tokens style → :root tokens derived from the project's frame.md
+
+  Token contract — reference ONLY this fixed vocab (captions.mjs injects it from
+  frame.md, so the Step-2 brand overlay flows through; each var has a cobalt literal
+  fallback for standalone preview):
+    --cap-ink · --cap-canvas · --cap-accent · --cap-accent-2 · --font-display ·
+    --font-body · --cap-band-top · --cap-band-height
+  Hooks (do not rename): .caption-group / .caption-word + states .is-active / .is-spoken,
+  root data-composition-id="captions", timeline at window.__timelines["captions"].
+  State changes use gsap.set({className}) (applied on the engine's frame-by-frame seek);
+  never tl.call() callbacks (seek does not fire them → wrong state on render).
+
+  Visual: a cream-paper card carrying the permanent graph-paper grid behind the line,
+  framed by top + bottom 1.5px cobalt hairlines (cobalt's signature frame furniture) —
+  square corners, NO drop shadow (cobalt's depth is structural and flat, never cast).
+  Newsreader serif 400, sentence case, cobalt glyphs. Upcoming words sit in faint
+  cobalt; the current word is a hard COBALT FLAT BLOCK — a risograph knockout: a solid
+  cobalt fill (box-shadow spread = a square block, no blur, no layout shift) with the
+  cream paper reading on top. Spoken words settle to solid cobalt ink, the block cleared.
+  Strictly two-color throughout — cream + cobalt, never a second hue.
+-->
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+
+<!-- captions.mjs injects the project's :root tokens here -->
+<style data-brand-tokens></style>
+
+<style>
+  #captions-root {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+  }
+  .caption-layer {
+    position: absolute;
+    inset: 0;
+    z-index: 20;
+    pointer-events: none;
+  }
+  /* the keep-out band, from captionBand(H) — frame content stays above it */
+  .caption-stage {
+    position: absolute;
+    left: 0;
+    right: 0;
+    top: var(--cap-band-top, 900px);
+    height: var(--cap-band-height, 180px);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+  .caption-group {
+    /* every group is absolutely stacked over the SAME band — exactly one shown at a
+       time via opacity. Must be absolute: in-flow groups would lay out side-by-side. */
+    position: absolute;
+    inset: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    opacity: 0;
+  }
+
+  /* THE cream card — graph-paper grid behind the line + top/bottom 1.5px cobalt
+     hairlines (cobalt's frame furniture), square corners, NO drop shadow */
+  .caption-pill {
+    position: relative;
+    max-width: 78%;
+    padding: 20px 44px 24px;
+    background: var(--cap-canvas, #f0ebde);
+    background-image:
+      linear-gradient(
+        to right,
+        color-mix(in srgb, var(--cap-ink, #1f2be0) 10%, transparent) 1px,
+        transparent 1px
+      ),
+      linear-gradient(
+        to bottom,
+        color-mix(in srgb, var(--cap-ink, #1f2be0) 10%, transparent) 1px,
+        transparent 1px
+      );
+    background-size: 16px 16px;
+    border-top: 1.5px solid var(--cap-ink, #1f2be0);
+    border-bottom: 1.5px solid var(--cap-ink, #1f2be0);
+    border-radius: 0;
+  }
+  .caption-line {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: center;
+    gap: 0.1em 0.34em;
+    font-family: var(--font-display, "Newsreader"), Georgia, serif;
+    font-weight: 400;
+    font-size: clamp(40px, 4.4vw, 58px);
+    line-height: 1.16;
+    letter-spacing: -0.01em;
+  }
+
+  /* upcoming — faint cobalt, no block */
+  .caption-word {
+    display: inline-block;
+    padding: 0 0.06em;
+    color: color-mix(in srgb, var(--cap-ink, #1f2be0) 42%, var(--cap-canvas, #f0ebde));
+  }
+  /* current word — THE cobalt flat block (risograph knockout): a solid cobalt fill
+     via box-shadow spread = a hard square block w/o layout shift, no blur; the cream
+     paper reads on top */
+  .caption-word.is-active {
+    color: var(--cap-canvas, #f0ebde);
+    background: var(--cap-ink, #1f2be0);
+    box-shadow: 0 0 0 0.06em var(--cap-ink, #1f2be0);
+  }
+  /* already spoken — solid cobalt ink, block cleared */
+  .caption-word.is-spoken {
+    color: var(--cap-ink, #1f2be0);
+    background: transparent;
+    box-shadow: none;
+  }
+
+  /* optional per-word accents (dormant until a word-classer tags them) */
+  /* brand / key term — Newsreader italic, cobalt's only display inflection */
+  .caption-word.cap-brand {
+    font-style: italic;
+  }
+  /* numerals / data — the body sans voice, slightly recessed */
+  .caption-word.cap-num {
+    font-family: var(--font-body, "Hanken Grotesk"), ui-monospace, monospace;
+    color: color-mix(in srgb, var(--cap-ink, #1f2be0) 72%, var(--cap-canvas, #f0ebde));
+  }
+  /* emphasis — a cobalt hairline underline (no second hue; emphasis is the ink) */
+  .caption-word.cap-cta {
+    text-decoration: underline;
+    text-decoration-thickness: 2px;
+    text-decoration-color: var(--cap-accent, #5560e5);
+    text-underline-offset: 0.1em;
+  }
+
+  @media (max-aspect-ratio: 9/16) {
+    .caption-pill {
+      max-width: 92%;
+    }
+    .caption-line {
+      font-size: clamp(34px, 5.4vw, 48px);
+    }
+  }
+</style>
+
+<div
+  id="captions-root"
+  data-composition-id="captions"
+  data-timeline-locked
+  data-start="0"
+  data-duration="0"
+  data-fps="30"
+  data-width="0"
+  data-height="0"
+>
+  <div class="caption-layer" aria-hidden="true">
+    <div id="caption-stage" class="caption-stage"></div>
+  </div>
+</div>
+
+<script>
+  // captions.mjs injects the engine's scene-aware groups + real duration here.
+  var GROUPS = [];
+  var DURATION = 0;
+
+  (function () {
+    var stage = document.getElementById("caption-stage");
+
+    // build DOM: one .caption-group per group, .caption-word per word
+    GROUPS.forEach(function (group, g) {
+      var groupEl = document.createElement("div");
+      groupEl.className = "caption-group";
+      groupEl.id = "caption-group-" + g;
+      var pill = document.createElement("div");
+      pill.className = "caption-pill";
+      var line = document.createElement("div");
+      line.className = "caption-line";
+      (group.words || []).forEach(function (w, i) {
+        var span = document.createElement("span");
+        span.className = "caption-word";
+        span.id = "caption-word-" + g + "-" + i;
+        span.textContent = String(w.text);
+        line.appendChild(span);
+      });
+      pill.appendChild(line);
+      groupEl.appendChild(pill);
+      stage.appendChild(groupEl);
+    });
+
+    window.__timelines = window.__timelines || {};
+    var tl = gsap.timeline({ paused: true });
+
+    GROUPS.forEach(function (group, g) {
+      var groupEl = document.getElementById("caption-group-" + g);
+      var words = group.words || [];
+      var next = GROUPS[g + 1];
+      var isLast = g === GROUPS.length - 1;
+      var start = Math.max(0, Number(group.start));
+      var end = isLast ? DURATION : Math.min(Number(next.start), Number(group.end) + 0.3);
+      if (end <= start) end = start + 0.01;
+
+      // group on/off — exactly one group visible at a time
+      tl.set(groupEl, { opacity: 1 }, start);
+      tl.set(groupEl, { opacity: 0 }, end);
+
+      // 3-state karaoke via className SETS — seek-safe (gsap.set applies on the
+      // engine's frame-by-frame seek; .call callbacks would NOT fire).
+      words.forEach(function (w, i) {
+        var el = document.getElementById("caption-word-" + g + "-" + i);
+        var at = Math.max(start, Number(w.start));
+        tl.set(el, { className: "caption-word" }, start); // upcoming (also resets on reverse-seek)
+        tl.set(el, { className: "caption-word is-active" }, at); // current
+        tl.fromTo(el, { scale: 0.985 }, { scale: 1, duration: 0.1, ease: "power3.out" }, at);
+        if (i + 1 < words.length) {
+          var nextAt = Math.max(start, Number(words[i + 1].start));
+          tl.set(el, { className: "caption-word is-spoken" }, nextAt); // demote when next activates
+        }
+      });
+      if (words.length) {
+        var lastEl = document.getElementById("caption-word-" + g + "-" + (words.length - 1));
+        var lastSpoken = Math.min(end, Number(words[words.length - 1].end) + 0.1);
+        tl.set(lastEl, { className: "caption-word is-spoken" }, lastSpoken);
+      }
+    });
+
+    // full-span anchor so the sub-comp timeline spans the whole video
+    tl.to({}, { duration: DURATION }, 0);
+    window.__timelines["captions"] = tl;
+  })();
+</script>