@mevdragon/vidfarm-devcli 0.14.0 → 0.15.0

package/.agents/skills/hyperframes-creative/frame-presets/daisy-days/FRAME.md

@@ -0,0 +1,274 @@
+---
+version: alpha
+name: Daisy Days — Frame (video / frame layer)
+description: >
+  Video-first companion to Daisy Days' design.md. The unit is the frame (1920×1080). Atoms are
+  identical and sacred — the sunny-garden pastel palette (cream + turquoise/pink/butter/mint/
+  lavender/peach/sky + coral accent), charcoal 3px outlines, hard offset shadows (6/4px, no blur),
+  the Fredoka + Quicksand pairing, generous radii, headline text-shadow on color, dot bullets, and
+  the hand-drawn SVG ornament layer. Composition + frame scale rewritten. Motion 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:
+  cream: "#F5F0E6"
+  turquoise: "#7ECDC0"
+  soft-pink: "#F7C8D4"
+  butter: "#FDE68A"
+  mint: "#A8E6CF"
+  lavender: "#D4A5E8"
+  peach: "#FFCBA4"
+  sky: "#A8D8F0"
+  coral: "#F8635F"
+  text-dark: "#2D2D2D"
+  text-muted: "#6B6B6B"
+  white: "#FFFFFF"
+
+borders: { primary: "3px solid text-dark", thin: "2px solid text-dark" }
+shadows: { default: "6px 6px 0 text-dark", small: "4px 4px 0 text-dark", text-headline: "3px 3px 0 text-dark", text-headline-soft: "3px 3px 0 rgba(0,0,0,0.2)" }
+
+typography:
+  # — reading ramp (Quicksand) —
+  body:    { fontFamily: "Quicksand", cqw: 0.95, weight: 500, lineHeight: 1.6 }
+  body-strong:{ fontFamily: "Quicksand", cqw: 0.95, weight: 600, lineHeight: 1.5 }
+  meta:    { fontFamily: "Quicksand", cqw: 0.78, weight: 600, lineHeight: 1.45 }
+  # — display ramp (Fredoka One / Fredoka 600 — single weight, never italic) —
+  badge:   { fontFamily: "Fredoka One", cqw: 0.9, tracking: "0.02em" }
+  label-display:{ fontFamily: "Fredoka One", cqw: 1.3, lineHeight: 1.3, tracking: "0.02em" }
+  subtitle:{ fontFamily: "Fredoka One", cqw: 1.8, lineHeight: 1.2, tracking: "0.02em" }
+  quote:   { fontFamily: "Fredoka One", cqw: 2.6, lineHeight: 1.35 }
+  title:   { fontFamily: "Fredoka One", cqw: 3.0, lineHeight: 1.15, tracking: "0.02em" }
+  headline:{ fontFamily: "Fredoka One", cqw: 4.5, lineHeight: 1.1, tracking: "0.02em" }
+  display: { fontFamily: "Fredoka One", cqw: 6.5, lineHeight: 1.1, tracking: "0.02em" }
+
+spacing:
+  pad-slide: "3cqw"
+  radius: "20px"
+  radius-lg: "28px"
+  radius-pill: "50px"
+  radius-round: "50%"
+
+components:
+  card:
+    backgroundColor: "{colors.white}"
+    border: "3px solid {colors.text-dark}"
+    rounded: "{spacing.radius} (28px featured)"
+    shadow: "6px 6px 0 {colors.text-dark}"
+    description: "The universal container; white-on-pastel is standard."
+  framed-header:
+    backgroundColor: "pastel cap + {colors.white} body"
+    border: "3px solid {colors.text-dark} (one continuous)"
+    rounded: "{spacing.radius-lg}"
+    shadow: "6px 6px 0 {colors.text-dark}"
+    description: "Pastel header strip flush above a white body — one unit, one shadow."
+  badge-pill:
+    backgroundColor: "{colors.butter}"
+    border: "3px solid {colors.text-dark}"
+    rounded: "{spacing.radius-pill}"
+    typography: "{typography.badge}"
+    shadow: "4px 4px 0 {colors.text-dark}"
+    description: "Section tag. white-space:nowrap."
+  circle-marker:
+    backgroundColor: "any pastel"
+    textColor: "{colors.white} (dark on butter)"
+    border: "3px solid {colors.text-dark}"
+    rounded: "50%"
+    size: "bullet 20 / icon 44 / dot 48 / step 90"
+    typography: "Fredoka numeral"
+    description: "Steps carry a small shadow."
+  bullet-dot:
+    backgroundColor: "{colors.butter}"
+    border: "2px solid {colors.text-dark}"
+    rounded: "50%"
+    size: "20px (::before, 4px from line top)"
+    description: "Lists never use glyph bullets."
+  ornament:
+    type: "hand-drawn SVG (daisy, star, sun, cloud, rainbow)"
+    stroke: "2.1px {colors.text-dark}"
+    placement: "z-index:1 behind content (z-index:2), cropping past the frame edge"
+    description: "3–7 per frame, clustered at corners/edges."
+  quote-mark:
+    typography: "oversized Fredoka quote glyph"
+    color: "{colors.soft-pink} (charcoal stroke)"
+    description: "Above a quote body."
+  text-headline-shadow:
+    shadow: "3px 3px 0 {colors.text-dark} (soft 20% variant on pink/mint)"
+    appliesTo: "Fredoka headlines on saturated surfaces (cream headlines sit flat)"
+    description: "Makes the headline read 'outlined' like the shapes."
+---
+
+# Daisy Days — Frame (video / frame layer)
+
+## Overview
+
+Daisy Days at frame scale is a **cheerful, childlike system** — picture-book illustration meets
+sticker-sheet kawaii. Every shape carries a **3px charcoal outline**, every elevated element a
+**solid hard offset shadow** (no blur), every surface a sunny-garden pastel. The voice is one
+pairing: **Fredoka One** (chunky rounded, single weight) for every headline, **Quicksand** for
+every body and meta line. The signature is the **hand-drawn SVG ornament layer** — daisies, stars,
+suns, clouds, rainbows clustering at corners and cropping past the edge.
+
+The palette is **multi-pastel with one warm pop**: cream canvas, seven pastel surfaces, and
+`{colors.coral}` reserved for small high-attention markers only. Headlines on a saturated surface
+get a 3px charcoal text-shadow (so they read "outlined" like the shapes) and switch to white;
+headlines on cream sit flat in charcoal. Depth is 2D and graphic — thick outline + hard offset =
+sticker-on-paper.
+
+**Key characteristics at frame scale:**
+
+- **Cream default + rotating pastel surfaces**; `{colors.coral}` is a marker accent, never a surface.
+- **Fredoka One** headlines + **Quicksand 500/600** body — strict by role, never crossed.
+- **3px charcoal outline + hard offset shadow** (6/4px, zero blur) on every elevated shape.
+- **Generous radii** — 20px cards, 28px featured, pill badges, full-circle markers; no square corners.
+- **Headline text-shadow on saturated surfaces** (white text); flat charcoal on cream.
+- **Dot bullets** (outlined butter discs, never glyphs) + a **3–7 ornament wreath** per frame.
+
+## The Frame
+
+### Frame Craft Bar
+
+Three eyeball tests gate every frame before any structural check:
+
+- **Squint** — one Fredoka headline or content card dominates at 3–6× its neighbor.
+- **Silence** — **one content container per frame** surrounded by an ornament wreath; the **info-card grid is the one dense exception**. Empty corners read as broken.
+- **Restraint** — cream or **one** pastel surface; coral is a small-marker accent (never a surface); charcoal borders + hard offset shadows only; no ninth color.
+- **Reference** — aim at a **children's picture-book / sticker-sheet kawaii zine**; failure looks like a **flat, square-cornered, blurred-shadow corporate slide**.
+
+- **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:** `pad-slide` ~3cqw; ornaments deliberately bleed past the edge.
+
+**The container law (load-bearing).** Every frame ground sets `container-type: size`; ALL
+frame-relative units are `cqw`/`cqh` against it — never `vw`. Borders stay 3px/2px; radii stay
+20/28/50px; shadow offsets scale in `cqw` so the sticker offset holds proportionally.
+
+## Colors
+
+Tokens identical to the source. Default ground `{colors.cream}`; rotate saturated pastels
+(turquoise / soft-pink / butter / mint / lavender / peach / sky) for tonal mood. **Cards are white**
+on any surface. **Borders + shadows are always `{colors.text-dark}` charcoal** — never colored,
+never blurred, never `rgba` (save the soft text-shadow variant). `{colors.coral}` is the lone
+high-saturation accent — small markers (step circles, dots, headers) **only**, never a surface.
+Body is charcoal/muted; pastels carry **no semantic meaning**. No ninth color.
+
+## Typography
+
+Two ramps. The **reading ramp** (Quicksand 500 body 0.95cqw, 600 emphasis, meta) carries copy; the
+**display ramp** (Fredoka One `label-display` 1.3cqw → `display` 6.5cqw, single weight) carries
+every headline, title, quote, and marker numeral.
+
+- **Legibility floor:** any load-bearing line ≥ **1.4cqw**; meta is chrome only.
+- **Fit-to-measure:** size the headline to its length. Cap the block at **≤ 78cqw**; ≤3 words → `display`; 4–6 → `headline`; 7+ → `title`.
+- **Fredoka One for all display, Quicksand for all body — never crossed.** Fredoka is single-weight (no italic, no underline, no alt weights); Quicksand stays 500/600/700. Fredoka tracking 0.02em; Quicksand body never uppercase.
+
+## Depth & Surface
+
+2D graphic depth — hard offset shadow, solid charcoal, zero blur, bottom-right:
+
+- **`shadows.default` 6px** cards, frames, badges, chart containers.
+- **`shadows.small` 4px** small cards, step circles, avatars.
+- **Text-headline shadow** — 3px charcoal on Fredoka headlines over saturated surfaces (20% soft variant on pink/mint); cream headlines flat.
+- **Outline + offset** together are the sticker-on-paper signature.
+
+**Ceiling:** no blurred shadow, no `rgba` (except the soft text-shadow), no gradient, no glow; an element either casts a hard charcoal offset or none.
+
+## Shapes
+
+- **20px** cards, **28px** featured, **50px** pill (badges, counter), **50%** all circles, **4px** legend swatch. Zero square corners — every region is rounded.
+
+## Components
+
+- **card / framed-header** — the white-fill bordered containers (one shadow). **badge-pill** — butter section tag.
+- **circle-marker** family (bullet 20 / icon 44 / dot 48 / step 90) + **bullet-dot** — outlined pastel discs, Fredoka numerals.
+- **ornament** — the hand-drawn SVG sticker layer (3–7 per frame). **quote-mark** — soft-pink Fredoka anchor. **text-headline-shadow** — the on-color headline treatment.
+
+## Frame Treatments
+
+> Recipe: ground · container · composes · focal · chrome · accent · silence · Fixed/Free · density.
+> One content container per frame + a 3–7 ornament wreath; empty corners read as broken.
+
+### 1 · Cover (identity · move: ornament wreath · saturated · centered)
+
+**Ground** a saturated pastel (e.g. `{colors.turquoise}`). **Composes** badge-pill, display, body sub, 3–7 ornaments, counter. **Focal** a 1–2 line Fredoka `display` in **white with the 3px charcoal text-shadow**, centered, under a butter badge-pill. **Chrome** counter pill. **Accent** the ornament wreath (daisies + stars at corners, cropping past edges). **Silence** content centered; ornaments fill the edges. **Fixed** text-shadow on color, 3px outlines, charcoal shadows. **Free** surface color, ornament mix/positions, copy. **Density** full-but-not-crowded.
+
+### 2 · Info Cards (catalog · move: 3-up white cards · cream · the dense frame)
+
+**Ground** `{colors.cream}`, `pad-slide`. **Composes** headline (flat charcoal), 3× card (circle-icon + Fredoka title + Quicksand body), a couple ornaments. **Focal** three white 3px-bordered cards with 6px shadows. **Chrome** flat headline. **Accent** the pastel circle-icons (rotate turquoise/coral/lavender). **Silence** tight — the density exception (fewer ornaments here). **Fixed** white cards, 3px + 6px, 20px radius. **Free** card content, icon hues. **Density** dense-exception.
+
+### 3 · Process Steps (sequence · move: rotating circle markers · peach · centered)
+
+**Ground** `{colors.peach}` (or another pastel). **Composes** headline (white + text-shadow), 3–4 step circles + `→` arrows, ornaments. **Focal** a row of 90px outlined step circles, fills **rotating coral → mint → sky → lavender**, Fredoka white numerals, linked by Fredoka arrows. **Chrome** white headline with text-shadow. **Accent** the rotating circle fills. **Silence** moderate. **Fixed** 3px circles + small shadow, rotating fills, arrow glyphs. **Free** step count, labels. **Density** standard.
+
+### 4 · Quote (quote · move: quote-mark anchor · soft-pink · centered)
+
+**Ground** `{colors.soft-pink}`. **Composes** a white quote card (28px radius, 6px shadow), quote-mark, Fredoka quote, Quicksand attribution, ornaments. **Focal** a Fredoka `quote` in charcoal inside the white card, under an oversized soft-pink quote-mark. **Chrome** Quicksand 700 attribution. **Accent** the quote-mark + a star or two. **Silence** card centered, ornaments at corners. **Fixed** quote-mark anchor, white card. **Free** quote, attribution. **Density** moderate.
+
+### 5 · Framed Section (feature · move: cap+body card · cream)
+
+**Ground** `{colors.cream}`. **Composes** framed-header (pastel cap + white body), bullet-dot list, ornaments. **Focal** a framed-header — a pastel cap strip (Fredoka title, optional text-shadow) above a white body with a butter-dot bullet list. **Accent** the cap color + bullet dots. **Silence** moderate. **Fixed** one continuous 3px border + one shadow, butter dot bullets. **Free** cap color, list. **Density** standard.
+
+### 6 · Closing (closer · move: ornament wreath · saturated · centered)
+
+**Ground** a saturated pastel (e.g. `{colors.lavender}`). **Composes** badge-pill, display (white + text-shadow), 3–7 ornaments. **Focal** a Fredoka `display` sign-off in white with the charcoal text-shadow, centered. **Accent** the ornament wreath. **Silence** content centered. **Fixed** text-shadow on color, ornaments fill corners. **Free** sign-off, surface, ornaments. **Density** full.
+
+## Composition Rules
+
+### Do
+
+- Pair **Fredoka One headlines + Quicksand body** strictly by role.
+- Outline every shape **3px charcoal + a hard offset shadow** (6/4px, no blur); white card fills on any surface.
+- Give Fredoka headlines on **saturated surfaces a 3px charcoal text-shadow + white text**; flat charcoal on cream.
+- Use **outlined butter-disc bullets** (never glyphs); cluster **3–7 hand-drawn ornaments** per frame (corners, cropping past edges).
+- Keep **one content container per frame**; rotate marker colors (coral → mint → sky → lavender → butter); reserve coral for small markers.
+- Center most frames; lean cream for content-dense frames, saturated for cover/closer/quote.
+
+### Don't
+
+- No square corners; no blurred or `rgba` shadows (save the soft text-shadow).
+- No colored borders (charcoal only); no coral surface; no ninth color.
+- No third font; no Quicksand headline or Fredoka body; no italic/underline Fredoka; no uppercase Quicksand body.
+- No glyph bullets; no empty corners (ornaments fill them); no two competing content panels.
+- Don't blow a headline edge-to-edge — fit to measure.
+
+## Aspect-Ratio Behavior
+
+| Treatment      | 16:9                       | 9:16                             | 1:1        |
+| -------------- | -------------------------- | -------------------------------- | ---------- |
+| Cover          | centered, corner ornaments | centered, taller, more ornaments | centered   |
+| Info Cards     | 3 across                   | stacked                          | 2+1        |
+| Process Steps  | horizontal + arrows        | vertical, arrows rotate down     | 2×2        |
+| Quote          | centered card              | centered, taller                 | centered   |
+| Framed Section | cap + body                 | cap + body taller                | cap + body |
+| Closing        | centered, wreath           | centered, wreath                 | centered   |
+
+`pad-slide` holds on the short edge; re-step display above the 1.4cqw floor. On tighter ratios keep
+the ornament count toward the upper end (5–7) so corners never read empty.
+
+## Approved Real Entities
+
+No real customers, logos, or vendors are defined in the source — render any such mark as a
+placeholder. Ornaments and pastels are content-agnostic; counters/badges carry per-deck text.
+
+## Numerals & Claims (hard rule)
+
+Never invent figures, dates, or counts at frame scale. Render slots as `— figure —`, `{metric}`,
+`N`. Step numbers and any chart values carry placeholders until the script supplies them; the slide
+counter is decorative chrome.
+
+## Pre-Render Self-Audit
+
+- **Squint** — one Fredoka headline or content card dominates per frame.
+- **Silence** — one container per frame surrounded by an ornament wreath; only the info-card grid runs dense.
+- **Color** — cream or one pastel surface; coral markers only; charcoal borders/shadows; no ninth hue.
+- **Type** — Fredoka headlines (text-shadow + white on saturated, flat charcoal on cream), Quicksand body; ≥1.4cqw floor.
+- **Depth** — 3px outline + hard offset (no blur, no rgba save soft text-shadow); rounded corners only.
+- **Ornaments** — 3–7 per frame, cropping past edges; no empty corners. **Bullets** — outlined discs, never glyphs.
+- **Fabrication** — every numeral traces to the script, else placeholder.
+
+## Known Gaps
+
+- **Motion intentionally out of scope.** frame.md specifies composition only; the source uses scroll-snap nav, no transition spec.
+- **Fonts:** the source names _Fredoka One_; Google now serves the **Fredoka** variable family — request `Fredoka:wght@500;600;700` and set display weight 600 (visually equal to Fredoka One), with `Fredoka One` kept first in the stack for environments that still serve it. Quicksand loads normally. CJK: ZCOOL XiaoWei (display) / Yozai (body).
+- **9:16 / 1:1 are guidance**; keep ornament count high so corners stay filled per ratio.
+- Ornaments (daisy/star/sun/cloud/rainbow), markers, and framed headers are CSS/SVG-only; recoloring SVG ornaments requires editing their stroke values.
+- **Contrast:** keep `{colors.text-muted}` off pastel surfaces (cream/white cards only); small text on saturated grounds should be charcoal or white.

package/.agents/skills/hyperframes-creative/frame-presets/daisy-days/caption-skin.html

@@ -0,0 +1,230 @@
+<!--
+  Daisy Days — 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 daisy-days 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 cheerful picture-book card — a cream surface inside a 3px charcoal outline
+  with a hard 6px charcoal offset shadow (no blur) and a generous 24px radius, the
+  sticker-on-paper signature. Fredoka One glyphs, sentence case, charcoal ink. Upcoming
+  words sit in muted charcoal; the current word pops into a rounded sunny-pastel candy
+  block (coral fill, 3px charcoal outline, hard 3px offset shadow, 12px radius) with a
+  bouncy scale pop; spoken words settle to solid charcoal, the candy block cleared.
+-->
+<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 picture-book card — cream surface, 3px charcoal outline, generous 24px radius,
+     a hard 6px charcoal offset shadow (no blur): the sticker-on-paper signature */
+  .caption-pill {
+    max-width: 80%;
+    padding: 18px 40px 22px;
+    background: var(--cap-canvas, #f5f0e6);
+    border: 3px solid var(--cap-ink, #2d2d2d);
+    border-radius: 24px;
+    box-shadow: 6px 6px 0 var(--cap-ink, #2d2d2d);
+  }
+  .caption-line {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: center;
+    gap: 0.18em 0.32em;
+    font-family: var(--font-display, "Fredoka One"), "Baloo 2", sans-serif;
+    font-weight: 600;
+    font-size: clamp(38px, 4.2vw, 56px);
+    line-height: 1.22;
+    letter-spacing: 0.02em;
+  }
+
+  /* upcoming — muted charcoal, no candy block */
+  .caption-word {
+    display: inline-block;
+    padding: 0.02em 0.16em;
+    border-radius: 12px;
+    color: color-mix(in srgb, var(--cap-ink, #2d2d2d) 52%, var(--cap-canvas, #f5f0e6));
+  }
+  /* current word — THE sunny-pastel candy block: a rounded coral chip with a 3px
+     charcoal outline + a hard 3px charcoal offset shadow (no blur), charcoal on top */
+  .caption-word.is-active {
+    color: var(--cap-ink, #2d2d2d);
+    background: var(--cap-accent, #f8635f);
+    border-radius: 12px;
+    box-shadow:
+      0 0 0 3px var(--cap-ink, #2d2d2d),
+      3px 5px 0 0 var(--cap-ink, #2d2d2d);
+  }
+  /* already spoken — solid charcoal, candy block cleared */
+  .caption-word.is-spoken {
+    color: var(--cap-ink, #2d2d2d);
+    background: transparent;
+    box-shadow: none;
+  }
+
+  /* optional per-word accents (dormant until a word-classer tags them) */
+  /* brand / key term — a butter candy chip, the cheerful second pastel */
+  .caption-word.cap-brand {
+    color: var(--cap-ink, #2d2d2d);
+    background: var(--cap-accent-2, #fde68a);
+    border-radius: 12px;
+    box-shadow: 0 0 0 3px var(--cap-ink, #2d2d2d);
+  }
+  /* numerals / data — Quicksand, slightly recessed */
+  .caption-word.cap-num {
+    font-family: var(--font-body, "Quicksand"), system-ui, sans-serif;
+    font-weight: 700;
+    color: color-mix(in srgb, var(--cap-ink, #2d2d2d) 78%, var(--cap-canvas, #f5f0e6));
+  }
+  /* emphasis — a butter underline rule (the second sunny pastel) */
+  .caption-word.cap-cta {
+    text-decoration: underline;
+    text-decoration-thickness: 3px;
+    text-decoration-color: var(--cap-accent-2, #fde68a);
+    text-underline-offset: 0.12em;
+  }
+
+  @media (max-aspect-ratio: 9/16) {
+    .caption-pill {
+      max-width: 92%;
+    }
+    .caption-line {
+      font-size: clamp(32px, 5.2vw, 46px);
+    }
+  }
+</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.82 }, { scale: 1, duration: 0.2, ease: "back.out(2.6)" }, 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>