dsh-hyperframes 0.2.0 → 0.3.1

package/skills/motion-graphics/categories/news/module.md

@@ -0,0 +1,56 @@
+# news — category module (search-driven)
+
+Search a real news article → animate it as an **article-highlight** — a faithful HF port of the centered-emphasis technique. Signature motion: the article text is laid out at a **readable size (NOT zoomed)**, slides + fades up, then the **keyword is highlighted in place** — a marker band grows left→right behind it. No blow-up zoom. ~5–7s.
+
+Two layouts share that one highlight core — pick by aspect + whether there's a logo / person to feature:
+
+| Layout                    | Aspect     | Use when                                                        | Has                                                                        |
+| ------------------------- | ---------- | --------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| **A · centered-emphasis** | 9:16 / 1:1 | text-only, social vertical                                      | kicker + one centered sentence + keyword highlight                         |
+| **B · full article**      | 16:9       | there's a real **outlet logo** and/or a **person** in the story | logo + date + multi-line headline highlight + dek + outlet + person cutout |
+
+## Source (Step 2)
+
+RWA / web search (or `hyperframes capture`) → a real article. The Director extracts the **keyword** (1–2 words / a number / a name — the hook) and, for Layout B, also a **brand logo**, a **date**, and a **person photo**. `asset_needs: { kind: news|web|image, query }` — request the logo (Wikimedia / simple-icons) and the person photo (Wikimedia) as separate asset queries. Run the person photo through `hyperframes remove-background <in> -o <out>.png` to get a transparent cutout.
+
+## The highlight core (shared by both layouts) — the marker-band technique
+
+The keyword highlight is a marker band grown L→R via `background-size` (NOT a `transform:scaleX` bar):
+
+```css
+.hl {
+  --hlw: 0%;
+  background-image: linear-gradient(var(--hl), var(--hl)); /* --hl: rgba(250,222,99,.6) */
+  background-repeat: no-repeat;
+  background-position: 0 72%;
+  background-size: var(--hlw) 64%;
+  box-decoration-break: clone;
+  -webkit-box-decoration-break: clone;
+}
+```
+
+`box-decoration-break:clone` makes the band **wrap across line breaks** seamlessly — a multi-word keyword spanning 2–3 lines still highlights continuously (the old `scaleX` bar could not). GSAP tweens the CSS var `--hlw` 0%→100%, **swept on AFTER the text settles — never pre-applied**. Optionally scale the duration with keyword length ~0.5–1.5s.
+
+## Layout A — centered-emphasis (9:16, text-only) — Builder
+
+1. **Lay out the key SENTENCE at a readable size — do NOT zoom.** Paper-light stage; an outlet `#kicker` (e.g. "BBC NEWS · TECHNOLOGY", brand accent) at top; the key sentence centered, serif, **~70–76px / 700 / line-height ~1.4**, `max-width ≈ 900`. The whole sentence stays legible; the keyword is emphasized _within_ it.
+2. Wrap the keyword inline: `… raised <span class="hl" id="kw">$750M</span> at …`.
+3. **Timeline** (seek-safe, paused): kicker fades+slides in → **sentence slides+fades up** (`set{autoAlpha:0,y:52}`→`to{autoAlpha:1,y:0,duration:0.8,ease:"power3.out"}`, no zoom) → **keyword highlight grows** (`--hlw 0→100%`, after the sentence settles) → gentle hold (`scale 1.012`).
+
+**Reference:** `samples/news/_ref-centered-emphasis.html` (+ `news/v2-*`).
+
+## Layout B — full article (16:9, logo + person) — Builder
+
+The editorial article-card layout (logo top-left + date + big serif headline with a multi-line keyword highlight + dek + outlet bottom-left + a background-removed **person cutout** bottom-right). 1920×1080, paper-light gradient stage, Georgia serif.
+
+1. **Logo** top-left (`#logo`, ~64px) — inline the outlet/brand SVG, `fill:currentColor`, set `color` to the mark's own hue (or near-black for a monochrome mark). **Date** below it (`#date`, ~30px, muted).
+2. **Headline** (`#headline`, Georgia **96px / 700**, `width≈1080`, `line-height 1.16`) with the keyword wrapped in `<span class="hl" id="kw">` — the highlight band sweeps across **all wrapped lines** of the phrase.
+3. **Dek** (`#dek`, Helvetica ~38px gray) under the headline; **outlet** (`#outlet`, Georgia bold ~50px) bottom-left.
+4. **Person cutout** (`#subject`, the bg-removed PNG, `height≈860`, `right:40; bottom:0`, `drop-shadow`) — **slides up from bottom-right** as the hero beat.
+5. **Timeline** (seek-safe, paused): logo `back.out` @0.15 → date @0.4 → **subject slides up** (`set{autoAlpha:0,x:90,y:60}`→`to{autoAlpha:1,x:0,y:0,duration:0.85,ease:"power3.out"}`) @0.45 → headline @0.7 → dek @1.5 → outlet @1.9 → **keyword highlight** (`--hlw 0→100%`, `duration:0.8`) @2.2. duration ~6.5s.
+
+**Reference:** `samples/news/_ref-article-layout.html` (a real article rendered with a real outlet logo + a background-removed person + a real story).
+
+## Critical
+
+Highlight is **grown in place, swept on AFTER the text — never pre-applied**. The text **stays readable — do NOT zoom the keyword to fill the frame** (team feedback 2026-06-09: zoom loses context and reads wrong; the technique never zooms — it presents the text and highlights the word). For Layout B, the person MUST be a `remove-background` cutout (no rectangular photo box). Deterministic; honor `references/builder-contract.md`.

package/skills/motion-graphics/categories/stat/module.md

@@ -0,0 +1,21 @@
+# stat — category module
+
+A single **hero number** reveal. Asset-free (the "input" is the number). ~4–6s.
+
+## Plan (Director)
+
+`content`: `{ value, prefix ($), suffix (% / x / K-M-B), label, ring: bool }`. Envelope: bold display font, restrained palette + one accent.
+
+## Vocabulary / leans on
+
+- Block: **`apple-money-count`** (finance-flavoured: $ counter + green flash + money burst + SFX) when it fits; otherwise hand-author.
+- Rules: `hyperframes-animation/rules/{counting-dynamic-scale, stat-bars-and-fills}`.
+- Primitives: `count_up` (odometer) · `scale_pop` · `ring_fill` (arc) · `label_stagger` (after value) · `hold`.
+
+## Build (reuse-first)
+
+Reuse `apple-money-count` + set target / prefix / suffix / label / palette; **or** hand-author per the proven prototype `v0-stat-motion-demo`:
+
+- **count-up is timeline-driven** — tween a proxy `{v:0}→target` with `onUpdate` writing the formatted number (seek-safe; never setInterval/wall-clock).
+- `font-variant-numeric: tabular-nums`; decelerating ease; ~1.2–1.6s then **hold** the final value.
+- ring/arc via `stroke-dashoffset`, finishing in sync with the count-up; label fades in **after** the number lands (value → meaning).

package/skills/motion-graphics/categories/tweet/module.md

@@ -0,0 +1,16 @@
+# tweet — category module (search-driven)
+
+**Search a tweet → animate the tweet card.** Grounded in a real post (RWA). ~4–8s.
+
+## Source (Step 2)
+
+RWA `search_tweets` (specific query, or a given tweet URL/id) → tweet: author, handle, avatar, text, timestamp, metrics (likes/reposts). `asset_needs`: `{ kind: tweet, query|source, treatment: none }`. Freeze the avatar + any embedded media.
+
+## Vocabulary / leans on
+
+- Block: registry **`x-post`** (animated X/Twitter post card overlay with engagement metrics) — reuse it directly.
+- Primitives: card slide/scale-in · text type-on / line reveal · avatar pop · metrics **count-up** · optional emphasis on a keyword.
+
+## Build (reuse-first)
+
+`npx hyperframes add x-post` → fill author / handle / avatar / text / metrics from the resolved tweet; animate the card in, type-on the text (or line-by-line reveal), count-up the metrics. Frozen project-local avatar/media (never a remote URL). `export: alpha-overlay` if it's meant to sit over other footage.

package/skills/motion-graphics/categories/webpage/module.md

@@ -0,0 +1,30 @@
+# webpage — category module (search-driven)
+
+**Animate a webpage / link** (the "website animation" use case). Search-driven: the user gives or names a URL → fetch/capture it → animate it (scroll-through, UI reveal, cursor demo, region callouts). Distinct from captioning an existing _video file_ (that's `/embedded-captions`) and from a narrated video _of_ a site (that's a `/product-launch-video` site-tour ask); here the source is a _web page_ and the output is a short, unnarrated highlight shot.
+
+## Source (Step 2)
+
+Fetch the page via `hyperframes capture --json` (DOM + screenshots) or a provided screenshot → frozen project-local image(s)/DOM. `asset_needs`: `{ kind: web, source: <url>, treatment: none }`.
+
+Inspect the capture result before building. If `BLOCKED.md` exists, JSON reports `ok: false`, or the
+command exits non-zero, stop the URL-capture path and report the reason. Continue with a provided
+screenshot only when it was an explicit source from the user (or the user explicitly chooses it
+after the failure). Do not animate a blocked partial capture, invent missing DOM, or eyeball element
+coordinates from protection/challenge pages.
+
+This web need cannot use the generic asset-free fallback: it requires a usable captured screenshot
+or DOM, or a provided screenshot explicitly selected by the user. If none is available, stop.
+
+## Vocabulary / leans on
+
+- Rules: `hyperframes-animation/rules/{3d-page-scroll, demo-page-scroll-spotlight, cursor-click-ripple, coordinate-target-zoom, viewport-change}`.
+- Primitives: scroll pan · spotlight/dim · cursor move + click-ripple · zoom-to-region · callout pin + label.
+
+## Build (reuse-first)
+
+Place the captured page as the base layer; animate a **scroll-through** (translateY over the page height), **spotlight** key regions (dim + highlight), a **cursor** that moves and clicks (ripple), **zoom** to a coordinate, and **callout** pins/labels anchored to page regions. Honor `builder-contract.md`.
+
+**Two rules that match the news article-highlight (see `../news/module.md`):**
+
+- **Highlights are swept/animated ON, never pre-applied** — a spotlight box wipes in (`scaleX 0→1`), a marker sweeps a region, a callout pops _after_ the zoom lands; the page never starts pre-annotated.
+- **Anchor to REAL element positions** — `hyperframes capture` gives the page HTML/DOM, so measure the target element (`getBoundingClientRect` → stage-local) and zoom/highlight it exactly, step-by-step (the "highlight a real element" technique). Don't eyeball coords.

package/skills/motion-graphics/grounding/PROTOCOL.md

@@ -0,0 +1,64 @@
+# locate — find "X" in an image (no detector API assumed)
+
+The single contract every consumer (asset-fusion ring, webpage highlight, future
+explainer/recut overlays) uses:
+
+```
+locate(image, target-description) → { box: [x0,y0,x1,y1], center: [cx,cy] }   # normalized 0..1
+```
+
+## Why this exists
+
+Author models are unreliable at **regressing pixel coordinates** on a cluttered
+full image (measured: weak vision models ~16–24% center error → rings land off-target)
+but reliable at **picking a numbered strip** (~3–4% with the loop below). So:
+never eyeball coordinates; localize by discrete choice. (RSVP, ACL 2025.)
+
+## Routing — pick the cheapest path that's actually available
+
+1. **A strong detector is available** (e.g. `GEMINI_API_KEY` in env) →
+   `node grounding/locate.mjs auto <img> "<target>"` — one call, done.
+   **Never assume the key exists.** No key → path 2.
+2. **No detector (the normal case)** → YOU are the localizer; run the grid loop.
+
+## The grid loop (you read images between steps)
+
+```
+node grounding/locate.mjs overlay <img> --out /tmp/g
+  → READ /tmp/g/gv.png (vertical strips 1-9) and gh.png (horizontal 1-9);
+    decide which strip numbers the target spans (list EVERY strip it touches).
+node grounding/locate.mjs region <img> --vids 4,5 --hids 6,7 --out /tmp/g
+  → READ /tmp/g/gc.png (the region cropped + upscaled, finer 6×6 grid);
+    pick the finer strips. (Pick strips again — do NOT switch to estimating
+    coordinates; discrete choice is the whole point, at BOTH stages.)
+node grounding/locate.mjs final <img> --region <from step 2> --vids 3,4 --hids 3,4
+  → the final {box, center}.
+node grounding/locate.mjs mark <img> --box <final box> --out /tmp/g/check.png
+  → VERIFY: READ check.png. Red box ON the target → done. Off → redo
+    region/final with corrected strips (you now know which direction). Never
+    skip this step; it converts silent misses into one cheap retry.
+```
+
+## Ambiguity — resolve BEFORE localizing
+
+If the target description can match several instances ("a drum" when the scene
+has five), no geometry will save you. First make the reference unique
+("the right-most drum", "the drum on the front boat"), asking the user if
+needed — then run the loop.
+
+## Degradation path (if locate.mjs itself is unavailable)
+
+The idea is 5 lines — reproduce it with any image tool:
+draw a numbered 9×9 grid → pick the strips the target spans → crop that region
+(+pad ~0.4 strip) and upscale → draw a finer 6×6 grid → pick again → map back
+(`global = region_origin + local × region_size`) → draw the box and LOOK at it.
+
+## Notes
+
+- Geometry is frozen in `locate.mjs` (node + ffmpeg, zero npm deps — both
+  already required by hyperframes). Don't re-implement it ad hoc; the measured
+  accuracy holds for THIS implementation.
+- Consumers: `samples/asset-fusion/_ref-circle-highlight.html` takes `CFG.box`
+  directly from `final`/`auto` output.
+- Measured end-to-end (same agent, same template, only the localization step
+  differs): eyeballing 6.5% avg center error → this protocol 2.3%, no case worse.

package/skills/motion-graphics/grounding/locate.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+/* locate.mjs — find "X" in an image WITHOUT any detector API or key.
+ *
+ * You (the author model) are weak at regressing pixel coordinates but strong at
+ * "which numbered strip is the target in?" — so localization = RSVP grid-index
+ * (ACL 2025 long.715): pick strips on a numbered grid, reconstruct the box
+ * geometrically. Zero npm deps — node + ffmpeg (both already required by
+ * hyperframes). Full protocol: grounding/PROTOCOL.md.
+ *
+ * THE LOOP (you read images between steps):
+ *   1) node locate.mjs overlay <img> --out DIR
+ *        → DIR/gv.png (vertical strips 1..9) + DIR/gh.png (horizontal 1..9).
+ *        READ both, pick the strip numbers the target spans.
+ *   2) node locate.mjs region <img> --vids 4,5 --hids 6,7 --out DIR
+ *        → prints coarse region + writes DIR/gc.png (region cropped+upscaled,
+ *        finer 6×6 grid). READ it, pick the finer strips.
+ *   3) node locate.mjs final <img> --region x0,y0,x1,y1 --vids 3,4 --hids 3,4
+ *        → {box, center} normalized to the FULL image.
+ *   4) node locate.mjs mark <img> --box x0,y0,x1,y1 --out DIR/check.png
+ *        → VERIFY: read check.png — is the red box on the target? If off,
+ *        redo step 2/3 with corrected strips. Never skip this.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, copyFileSync } from "node:fs";
+
+const N1 = 9,
+  PAD1 = 0.4; // stage 1: strips per axis, padding in STRIP units
+const N2 = 6,
+  PAD2 = 0.25; // stage 2 (crop)
+const GREEN = "0x3CDC5A",
+  BLUE = "0x3C82FF",
+  RED = "0xFF3232";
+
+const ff = (args) =>
+  execFileSync("ffmpeg", ["-v", "error", "-y", ...args], {
+    stdio: ["ignore", "ignore", "inherit"],
+  });
+function probe(img) {
+  const out = execFileSync("ffprobe", [
+    "-v",
+    "error",
+    "-select_streams",
+    "v:0",
+    "-show_entries",
+    "stream=width,height",
+    "-of",
+    "csv=p=0",
+    "--",
+    img,
+  ])
+    .toString()
+    .trim();
+  const [w, h] = out.split(",").map(Number);
+  return { w, h };
+}
+function font() {
+  const dst = "/tmp/locate-font.ttf";
+  if (!existsSync(dst)) {
+    for (const c of [
+      "/System/Library/Fonts/Supplemental/Arial Bold.ttf",
+      "/System/Library/Fonts/Supplemental/Arial.ttf",
+      "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
+    ]) {
+      if (existsSync(c)) {
+        copyFileSync(c, dst);
+        break;
+      }
+    }
+  }
+  return dst;
+}
+function gridFilters(w, h, n, axis, fz) {
+  const F = font(),
+    fs = [];
+  if (axis === "v" || axis === "both") {
+    for (let i = 1; i < n; i++)
+      fs.push(`drawbox=x=${Math.round((i * w) / n)}:y=0:w=2:h=${h}:color=${GREEN}@0.8:t=fill`);
+    for (let i = 0; i < n; i++)
+      fs.push(
+        `drawtext=fontfile=${F}:text='${i + 1}':x=${Math.round(((i + 0.5) * w) / n - fz * 0.3)}:y=6:fontsize=${fz}:fontcolor=black:box=1:boxcolor=white@0.95:boxborderw=5`,
+      );
+  }
+  if (axis === "h" || axis === "both") {
+    for (let j = 1; j < n; j++)
+      fs.push(`drawbox=x=0:y=${Math.round((j * h) / n)}:w=${w}:h=2:color=${BLUE}@0.8:t=fill`);
+    for (let j = 0; j < n; j++)
+      fs.push(
+        `drawtext=fontfile=${F}:text='${j + 1}':x=6:y=${Math.round(((j + 0.5) * h) / n - fz * 0.5)}:fontsize=${fz}:fontcolor=black:box=1:boxcolor=white@0.95:boxborderw=5`,
+      );
+  }
+  return fs;
+}
+const ids = (s) => String(s).split(",").filter(Boolean).map(Number);
+const regionOf = (v, h, n, pad) => [
+  Math.max(Math.min(...v) - 1 - pad, 0) / n,
+  Math.max(Math.min(...h) - 1 - pad, 0) / n,
+  Math.min(Math.max(...v) + pad, n) / n,
+  Math.min(Math.max(...h) + pad, n) / n,
+];
+const r4 = (x) => Math.round(x * 1e4) / 1e4;
+const out = (o) => console.log(JSON.stringify(o));
+
+// --- tiny arg parsing: locate.mjs <cmd> <img?> --k v ---
+const [cmd, ...rest] = process.argv.slice(2);
+const pos = rest.filter((a) => !a.startsWith("--"));
+const opt = {};
+for (let i = 0; i < rest.length; i++)
+  if (rest[i].startsWith("--")) opt[rest[i].slice(2)] = rest[i + 1];
+const img = pos[0];
+
+if (cmd === "overlay") {
+  const dir = opt.out || ".";
+  mkdirSync(dir, { recursive: true });
+  const n = Number(opt.n || N1);
+  const { w, h } = probe(img);
+  const fz = Math.max(16, Math.round(Math.min(w, h) / 22));
+  ff(["-i", img, "-vf", gridFilters(w, h, n, "v", fz).join(","), `${dir}/gv.png`]);
+  ff(["-i", img, "-vf", gridFilters(w, h, n, "h", fz).join(","), `${dir}/gh.png`]);
+  out({
+    w,
+    h,
+    n,
+    vertical: `${dir}/gv.png`,
+    horizontal: `${dir}/gh.png`,
+    next: "READ gv.png + gh.png, then: locate.mjs region <img> --vids .. --hids .. --out " + dir,
+  });
+} else if (cmd === "region") {
+  const dir = opt.out || ".";
+  mkdirSync(dir, { recursive: true });
+  const n = Number(opt.n || N1),
+    nf = Number(opt.nf || N2);
+  const reg = regionOf(ids(opt.vids), ids(opt.hids), n, PAD1);
+  const { w, h } = probe(img);
+  const cx = Math.floor(reg[0] * w),
+    cy = Math.floor(reg[1] * h);
+  const cw = Math.max(2, Math.floor((reg[2] - reg[0]) * w)),
+    ch = Math.max(2, Math.floor((reg[3] - reg[1]) * h));
+  const uw = Math.max(cw, 640),
+    uh = Math.round((ch * uw) / cw);
+  const fz = Math.max(15, Math.round(Math.min(uw, uh) / 16));
+  ff([
+    "-i",
+    img,
+    "-vf",
+    [
+      `crop=${cw}:${ch}:${cx}:${cy}`,
+      `scale=${uw}:${uh}`,
+      ...gridFilters(uw, uh, nf, "both", fz),
+    ].join(","),
+    `${dir}/gc.png`,
+  ]);
+  out({
+    region: reg.map(r4),
+    crop_grid: `${dir}/gc.png`,
+    nf,
+    next: `READ gc.png, then: locate.mjs final <img> --region ${reg.map(r4).join(",")} --vids .. --hids ..`,
+  });
+} else if (cmd === "final") {
+  const nf = Number(opt.nf || N2);
+  const reg = opt.region.split(",").map(Number);
+  const rl = regionOf(ids(opt.vids), ids(opt.hids), nf, PAD2);
+  const [x0, y0, x1, y1] = reg;
+  const box = [
+    x0 + rl[0] * (x1 - x0),
+    y0 + rl[1] * (y1 - y0),
+    x0 + rl[2] * (x1 - x0),
+    y0 + rl[3] * (y1 - y0),
+  ].map(r4);
+  out({
+    box,
+    center: [r4((box[0] + box[2]) / 2), r4((box[1] + box[3]) / 2)],
+    next:
+      "VERIFY: locate.mjs mark <img> --box " +
+      box.join(",") +
+      " --out <dir>/check.png — then READ it",
+  });
+} else if (cmd === "mark") {
+  const box = opt.box.split(",").map(Number);
+  const { w, h } = probe(img);
+  const bx = Math.round(box[0] * w),
+    by = Math.round(box[1] * h);
+  const bw = Math.max(2, Math.round((box[2] - box[0]) * w)),
+    bh = Math.max(2, Math.round((box[3] - box[1]) * h));
+  const dst = opt.out || "./check.png";
+  ff(["-i", img, "-vf", `drawbox=x=${bx}:y=${by}:w=${bw}:h=${bh}:color=${RED}@1:t=6`, dst]);
+  out({
+    marked: dst,
+    next: "READ it — red box on the target? If off, redo region/final with corrected strips.",
+  });
+} else if (cmd === "auto") {
+  // OPTIONAL fast path — only if a strong detector key happens to exist. Never assume it.
+  const key = process.env.GEMINI_API_KEY;
+  if (!key) {
+    console.error(
+      "auto needs GEMINI_API_KEY; use the grid loop instead (overlay→region→final→mark)",
+    );
+    process.exit(1);
+  }
+  const target = pos[1];
+  const b64 = execFileSync("base64", ["-i", img]).toString().replace(/\n/g, "");
+  const mime = img.match(/\.png$/i) ? "image/png" : "image/jpeg";
+  const body = {
+    contents: [
+      {
+        parts: [
+          { inline_data: { mime_type: mime, data: b64 } },
+          {
+            text: `Detect "${target}". Return ONLY {"box_2d":[ymin,xmin,ymax,xmax]} integers 0-1000.`,
+          },
+        ],
+      },
+    ],
+    generationConfig: { temperature: 0, response_mime_type: "application/json" },
+  };
+  const res = await fetch(
+    `https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent?key=${key}`,
+    { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) },
+  );
+  const t = (await res.json()).candidates[0].content.parts[0].text;
+  let bb = JSON.parse(t.match(/\{[\s\S]*\}/)[0]).box_2d;
+  if (Array.isArray(bb[0])) bb = bb[0];
+  const s = Math.max(...bb) > 1.5 ? 1000 : 1;
+  const box = [bb[1] / s, bb[0] / s, bb[3] / s, bb[2] / s].map(r4);
+  out({ box, center: [r4((box[0] + box[2]) / 2), r4((box[1] + box[3]) / 2)] });
+} else {
+  console.error("usage: locate.mjs overlay|region|final|mark|auto … (see header comment)");
+  process.exit(1);
+}

package/skills/motion-graphics/phases/source/guide.md

@@ -0,0 +1,21 @@
+# source phase — asset sourcing (asset-first)
+
+Runs **only when `shot-plan.json.asset_needs` is non-empty** (the form categories never reach here). Sources each needed asset → a **frozen project-local path** + a ledger (`assets/index.md`). Uses `/media-use` (capture / asset prep) plus, **when an external asset-search skill such as media-use is installed**, its `resolve` step. If no such search capability is available, it **degrades to asset-free** (see below).
+
+## Per asset_need
+
+- `image / icon / logo / svg` → media-use `resolve`: **search** (asset_scout: Google Images / SerpAPI + Noun Project), **generate** (image model), or **user-supplied** (logo). Optional `treatment`: cutout (remove-bg) / recolor / vectorize.
+- `news / web / tweet` → **RWA-style search** (media-use's documented lineage — `media-use/references/search-strategy.md` traces `resolve` to the RWA subagent). Two-pole queries: **atomic** (1–3 words, composable) or **specific** (5–15 words: a news event / tweet); never the middle. A failed specific query is dropped, not broadened.
+
+## Steps
+
+1. Read `asset_needs` from `shot-plan.json`.
+2. For each: **analyze → search → review (use/maybe/reject — selection is the hard part; do NOT take the first/generated result) → freeze** the kept asset into `assets/` (rehost remote URLs).
+3. Write `assets/index.md` — agent-readable ledger: `role → frozen path + provenance`.
+4. For `asset-fusion`: also capture the asset's measurable geometry (so Director Part 2 can set `element_positions`) + an eyedropper palette.
+
+## Degrade gracefully
+
+If a provider / search is unavailable, mark the need unmet in `context.log`; the category falls back to asset-free where possible (e.g. `news` → typographic headline without the sourced image).
+
+> Illustrative: `(cd "$PROJECT_DIR" && node <SKILL_DIR>/phases/source/resolve.mjs --plan ./shot-plan.json --out ./assets)` — or drive media-use's `resolve` procedure directly.

package/skills/motion-graphics/references/builder-contract.md

@@ -0,0 +1,38 @@
+# Builder contract — composition rules (detail behind agents/builder.md)
+
+## Root must be sized
+
+Root `#stage` (`data-composition-id`) needs `position: relative; width: <W>px; height: <H>px`. Without a resolved height, flex children collapse to ~0 and content piles into the top-left. Automated gates may miss it, so inspect proof snapshots.
+
+## Layout before animation
+
+1. Identify the **hero frame** (the moment most elements are visible) → build THAT in static CSS first, no GSAP.
+2. `.scene-content` fills the scene with padding, not offsets:
+   ```css
+   display: flex;
+   flex-direction: column;
+   justify-content: center;
+   width: 100%;
+   height: 100%;
+   padding: 120px 160px;
+   gap: 24px;
+   box-sizing: border-box;
+   ```
+   Never `position:absolute; top:Npx` on a content container (it overflows). Reserve absolute for decoratives. Keep ≥80px padding (title-safe margin).
+3. **Entrances**: use `gsap.from()` only for a non-clip element active from `t=0`. Inside `.clip`, in sub-compositions, and for later entrances, use explicit `fromTo()`. The CSS position is ground truth; the tween is the journey to it.
+4. **Exits**: only the final scene animates elements out; between scenes the transition IS the exit.
+
+## Timeline / clip contract
+
+- ONE `gsap.timeline({paused:true})` on `window.__timelines["<id>"]`; `tl.seek(0)`; never `tl.play()`.
+- Timed elements: `class="clip"` + `data-start`/`data-duration`/`data-track-index` + a stable `id`. Timeline-driven groups inside one full-duration clip don't each need timing attrs.
+- Deterministic only — no `Date.now()` / `Math.random()` / network. Count-ups tween a proxy object via `onUpdate` (seek-safe), never a wall-clock counter.
+
+## Correctness
+
+- **Seek-safe reveal of delayed elements**: on a non-clip element or wrapper inside a clip, use one registered timeline `fromTo()` with an explicit `{ autoAlpha: 0 }` start and `{ autoAlpha: 1, ... }` end. Do not page-load `gsap.set()` a later `.clip`, and never target `.clip` visibility; the framework owns its lifecycle. _(Eval finding.)_
+- **Count-ups** tween a proxy via `onUpdate`; they only render when the host advances the timeline **with events enabled** (`tl.time()` / non-suppressed seek). A bare `seek(t, true)` freezes them at 0 — the HF render host must seek with events on. _(Eval finding.)_
+- Clamp at tween bounds; don't let a spring overshoot past a held value.
+- Allowed eases: `power1–4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine` (`.in/.out/.inOut`).
+- One motif per scene. Run `hyperframes check`; mark intentional overflow `data-layout-allow-overflow="true"`.
+- **Palette discipline**: define all colors in one `palette` object / CSS custom properties — no inline hex scattered through the markup (for `asset-fusion`, eyedropper the palette from the asset).

package/skills/motion-graphics/references/motion-vocabulary.md

@@ -0,0 +1,43 @@
+# text module · motion vocabulary (primitive → GSAP)
+
+Named primitives the Director references in `motion` strings and the Builder implements. `code_hint`s are framework-neutral physics; the GSAP recipe is the HF implementation. Prefer an HF **registry component** (bottom) when one fits — don't reinvent.
+
+## Entry
+
+| primitive                     | GSAP recipe (into CSS end-state)                               | suits                     |
+| ----------------------------- | -------------------------------------------------------------- | ------------------------- |
+| `slide_bottom/top/left/right` | `from({ y:±150 / x:±200, opacity:0, ease:"power4.out" })`      | calm, build, professional |
+| `scale_grow`                  | `from({ scale:0, opacity:0, duration:.6, ease:"power2.out" })` | calm, gentle              |
+| `scale_punch`                 | `from({ scale:.6, opacity:0, ease:"back.out(2.2)" })`          | impact, energetic         |
+| `fade_in`                     | `from({ opacity:0, duration:.4 })`                             | subtle                    |
+| `fade_blur`                   | `from({ opacity:0, filter:"blur(14px)" })`                     | cinematic, dreamy         |
+| `typewriter`                  | reveal via clip/`SplitText` width step                         | technical, narrative      |
+| `word_reveal`                 | per-word `from({opacity:0,y:..}, stagger:.1)`                  | storytelling              |
+| `wave`                        | per-letter `from({y:..}, stagger:{each:.04})`                  | flowing, musical          |
+| `bounce_in`                   | `from({y:-120}, ease:"bounce.out")`                            | playful                   |
+| `slam`                        | `from({ y:-300, ease:"power4.out" })` + shake on land          | impact, heavy             |
+
+## Emphasis (in place, often on a beat)
+
+| primitive     | GSAP recipe                                                          | suits              |
+| ------------- | -------------------------------------------------------------------- | ------------------ |
+| `scale_pulse` | `to({ scale:1.12, yoyo:true, repeat:1, ease:"sine.inOut" })` at beat | rhythmic, peak     |
+| `shake`       | `to({ keyframes:[{x:-9},{x:9},{x:0}], ease:"none" })`                | urgent, intense    |
+| `glow`        | `to({ textShadow:"0 0 46px <ink/accent>", yoyo:true, repeat:1 })`    | important, magical |
+| `color_shift` | `to({ color:"<accent>" })` (or accent on the word in CSS)            | dynamic            |
+
+## Exit
+
+| primitive   | GSAP recipe                                        | suits      |
+| ----------- | -------------------------------------------------- | ---------- |
+| `fade_out`  | `to({ opacity:0, duration:.4, ease:"power2.in" })` | ending     |
+| `slide_out` | `to({ y/x: off, opacity:0, ease:"power2.in" })`    | transition |
+| `scale_out` | `to({ scale:1.06, opacity:0, ease:"power2.in" })`  | transition |
+
+## Accent graphics (not text)
+
+`underline_sweep` `fromTo({scaleX:0},{scaleX:1}, transformOrigin:"left center")` · `bar_wipe` · `hold_breath` `to({scale:1.015, ease:"sine.inOut"})`.
+
+## Prefer HF registry components when they fit
+
+`caption-kinetic-slam` · `caption-editorial-emphasis` · `caption-neon-glow` · `caption-glitch-rgb` · `caption-particle-burst` · `caption-weight-shift` · `caption-matrix-decode` · `caption-pill-karaoke` · `shimmer-sweep`. These are pre-built, in-ecosystem, and already render-tested — the Builder should reach for them before hand-rolling an equivalent.

package/skills/motion-graphics/references/shot-plan-ir.md

@@ -0,0 +1,54 @@
+# shot-plan IR
+
+The single contract between Director and Builder. One file: `PROJECT_DIR/shot-plan.json`.
+
+```jsonc
+{
+  // ── envelope (every category) ──
+  "category": "kinetic-type | stat | charts | logo-reveal | lower-thirds | webpage | news | tweet | asset-fusion",
+  "duration_s": 6,
+  "fps": 30,
+  "canvas": { "w": 1080, "h": 1920, "aspect": "9:16" },
+  "style": "free-form visual direction (mood / energy / reference)",
+  "palette": ["#…"], // or "derive-from-asset"
+  "font": "<HF embed-list font>",
+  "beats": [12, 37], // optional accent frames/seconds
+  "export": "mp4", // or "alpha-overlay" (transparent webm/mov)
+
+  // ── sourcing seam (Director Part 1) — [] means skip the source phase ──
+  "asset_needs": [
+    {
+      "role": "hero",
+      "kind": "image|icon|logo|svg|news|web|tweet",
+      "query": "…",
+      "source": "…",
+      "treatment": "cutout|recolor|vectorize|none",
+    },
+  ],
+
+  // ── build directive (Director Part 2, reuse-first) ──
+  "block": "<catalog block id, e.g. data-chart | caption-kinetic-slam>", // optional
+  "customize": {
+    /* what to change on the block: data, text, palette, positions */
+  },
+
+  // ── category-specific content ──
+  "content": {
+    /* shape varies by category, below */
+  },
+}
+```
+
+**Per-category `content` shapes:**
+
+- `kinetic-type` → `scenes[]` `{ id, start, end, text, emphasis_words[], emotion, motion, beats[] }`
+- `stat` → `{ value, prefix, suffix, label, ring: bool }`
+- `charts` → `{ type: bar|line|pie|race|pct, data[], labels[], headline, axes: bool }`
+- `logo-reveal` → `{ logo: <asset path>, tagline, url }`
+- `lower-thirds` → `{ name, role, position, brand_colors[] }`
+- `webpage` → `{ url, capture, highlights: [ { selector|region, label } ] }` (step-highlight a real captured page)
+- `news` → `{ outlet, headline, body, keyword, layout: A|B, logo?, date?, subject? }` (article-highlight: lay text out readable — **no zoom** — then sweep a marker band over the keyword in place. Layout **A** = centered-emphasis 9:16 text-only; **B** = full article 16:9 with `logo` + `date` + `subject` (a person photo → `remove-background` cutout))
+- `tweet` → `{ author, handle, avatar, text, metrics }`
+- `asset-fusion` → `{ data_type, asset: <path>, affordance, element_positions: {center, extent, safe[], avoid[]}, derived_palette[], connectors[] }`
+
+**Invariants:** `scenes` (if present) partition `[0, duration_s]` with no gaps/overlaps · empty `asset_needs` ⇒ Step 2 (source) is skipped · a named `block` ⇒ the Builder reuses + customizes it rather than hand-authoring.