dsh-hyperframes 0.1.1 → 0.3.0

package/skills/faceless-explainer/scripts/transitions.mjs

@@ -0,0 +1,383 @@
+#!/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.]+)"/);
+    const compositionMatch = attrs.match(/\bdata-composition-id="([^"]+)"/);
+    if (compositionMatch?.[1] === compId && !foundRoot) {
+      foundRoot = true;
+      return durationMatch
+        ? tag.replace(/\bdata-duration="[\d.]+"/, `data-duration="${targetDuration}"`)
+        : tag.replace(/(\s*\/?>)$/, ` data-duration="${targetDuration}"$1`);
+    }
+
+    if (!durationMatch) return tag;
+    const duration = Number(durationMatch[1]);
+    if (!Number.isFinite(duration)) return tag;
+
+    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);
+}

package/skills/faceless-explainer/scripts/transitions.test.mjs

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+import test from "node:test";
+
+const script = new URL("./transitions.mjs", import.meta.url).pathname;
+
+function write(filePath, contents) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, contents);
+}
+
+test("inject extends a documented frame root that omits data-duration", (t) => {
+  const project = mkdtempSync(join(tmpdir(), "faceless-transitions-"));
+  t.after(() => rmSync(project, { force: true, recursive: true }));
+
+  write(
+    join(project, "STORYBOARD.md"),
+    `---
+format: 1920x1080
+---
+
+## Frame 1 — First
+
+- duration: 2s
+- transition_in: cut
+- status: animated
+- src: compositions/frames/01-a.html
+
+## Frame 2 — Second
+
+- duration: 2s
+- transition_in: crossfade
+- status: animated
+- src: compositions/frames/02-b.html
+`,
+  );
+  write(
+    join(project, "index.html"),
+    `<!doctype html><html><body>
+<div id="root" data-composition-id="main" data-duration="4"></div>
+<div id="el-01-a" data-start="0" data-duration="2" data-track-index="0"></div>
+<div id="el-02-b" data-start="2" data-duration="2" data-track-index="0"></div>
+<script>window.__timelines={}; window.__timelines["main"] = gsap.timeline({ paused: true });</script>
+</body></html>`,
+  );
+  write(
+    join(project, "compositions/frames/01-a.html"),
+    `<template><div id="root" data-composition-id="01-a"><div class="clip" data-start="0" data-duration="2" data-track-index="0">first</div></div></template>`,
+  );
+  write(
+    join(project, "compositions/frames/02-b.html"),
+    `<template><div id="root" data-composition-id="02-b"><div class="clip" data-start="0" data-duration="2" data-track-index="0">second</div></div></template>`,
+  );
+
+  const result = spawnSync(
+    process.execPath,
+    [script, "inject", "--storyboard", join(project, "STORYBOARD.md"), "--hyperframes", project],
+    { encoding: "utf8" },
+  );
+
+  assert.equal(result.status, 0, result.stderr);
+  const outgoing = readFileSync(join(project, "compositions/frames/01-a.html"), "utf8");
+  assert.match(outgoing, /data-composition-id="01-a" data-duration="2.5"/);
+  assert.match(outgoing, /class="clip"[^>]*data-duration="2.5"/);
+});

package/skills/faceless-explainer/sub-agents/frame-worker.md

@@ -0,0 +1,12 @@
+# Frame worker — faceless-explainer 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 faceless-explainer frame; you run N-up, **one frame each** — your dispatch carries exactly one packet. Tempted to add a generic GSAP / timeline rule here? Wrong home — it belongs in the core contract or `hyperframes-core`.
+
+## Your `focal:` / `roles:` — invented elements
+
+- `focal:` — which **invented** element is the hero.
+- `roles:` — each invented element's role: `foreground subject` / `background` full-bleed / `supporting`. Because the explainer is **faceless, these are elements you design** (a hero word, a diagram node, a chart series, a coined-term card), not captured assets. The **only** real media is a user-supplied image, when present: `public/<basename> — description` (a **`[video]`** tag marks a `.mp4` clip the user provided).
+
+## Designing each element (faceless-explainer constraint)
+
+**Design each element by its `roles`** (the `focal` is the hero): a `foreground subject` is the thing the eye lands on — respect the 83% keep-out, lay text around it, not over it; a `background` is full-bleed and dimmed ~30–50% so foreground content stays legible; `supporting` elements (labels, secondary shapes, ambient layers) stay quiet. These are **invented** — you build them in SVG / CSS / type from `frame.md`'s atoms, never from a fetched file (build the idea the narrative describes; never fall back to generic decorative bokeh or stock filler). **If the user supplied a real image** named in `roles:`/`focal:`, place it: a `[video]` candidate (`.mp4`) renders as a **muted** `<video class="clip">` (`data-start` / `data-duration` / `data-track-index` per the core clip contract), a **direct child of the frame root** — never nested in another timed element, or the renderer freezes it; an untagged image → `<img>`.

package/skills/figma/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: figma
+description: Import Figma content into a HyperFrames composition — rendered assets, brand tokens, components, storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI), connector-assisted motion when available, and shaders from a connector or native export. Use when the user pastes a figma.com link or asks to bring a Figma design, frame, logo, brand, or animation into a video/composition.
+---
+
+> **First, keep this skill fresh — confirm with the user before running:** `npx hyperframes skills update figma`. 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.
+
+# Figma → HyperFrames
+
+Bring the user's Figma work into a composition. **Split by capability** (design spec §2):
+
+| Phase | What                | Transport                 | Surface                       |
+| ----- | ------------------- | ------------------------- | ----------------------------- |
+| 1     | Static assets       | REST                      | `hyperframes figma asset`     |
+| 2     | Brand tokens/styles | REST                      | `hyperframes figma tokens`    |
+| 3     | Components → HTML   | REST                      | `hyperframes figma component` |
+| 4     | Motion → GSAP       | connector when available  | use its motion context        |
+| 5     | Shaders             | connector / manual export | use it or a native export     |
+
+REST is used wherever it can be (usable at volume, headless). A compatible Figma connector is optional for motion and shader data; without one, ask for a native export. Every path freezes assets locally so renders stay deterministic. Storyboard reconstructions compose Phase-1 asset exports (REST) with agent-driven timeline assembly — no connector needed. Existing frozen assets, manifest records, and bindings are unaffected by routing changes — the split only changes which credential the next import uses.
+
+## Auth — two credentials, scoped
+
+**Preflight — before the first CLI call, check a token exists**: shell env (`[ -n "$FIGMA_TOKEN" ]`) **or** the project `.env` (the CLI auto-loads it — a `.env` entry counts as configured). If neither, do NOT run the command to harvest the error — walk the user through the one-time setup first, then stop and wait:
+
+1. figma.com/settings → **Security** → **Personal access tokens** → Generate new token.
+2. Scopes — read-only is all this integration ever needs (it never writes to Figma): **File content: Read-only** + **File metadata: Read-only**. Add **Library content: Read-only** if you'll run `tokens` on a non-Enterprise plan — the published-styles fallback hits `/v1/files/:key/styles`, which 403s without it (a scope the older setup text omitted). Optionally **Variables: Read-only** for brand variables — Enterprise-only; without it `tokens` degrades to published styles automatically (expected, not an error — say so). A 403 now names the exact missing scope; 429s retry automatically (per-minute limit, honors `Retry-After`).
+3. Have the user set `FIGMA_TOKEN` in their shell profile or project `.env`; never ask them to paste the token into the conversation.
+
+While onboarding, also set expectations in one breath: every import lands as a **local frozen file with recorded provenance** — renders never call Figma, re-running a command re-imports only what changed in Figma, and one token works for assets, brand tokens, and components across every file their Figma account can view.
+
+- **Phases 4–5 (motion/shaders):** a compatible Figma connector, with separate authorization from the token. If it is unavailable or unauthenticated, ask the user to connect it or provide a native export, then stop.
+- Say exactly which credential a failing phase needs — never present the split as broken.
+- `BAD_TOKEN` (401) mid-flow → the token is expired/revoked; re-mint. `FORBIDDEN` (403) → the message names the exact missing scope (e.g. `library_content:read` for the styles fallback) — add it, or the file isn't visible to the account. `REQUIRES_ENTERPRISE` (403 on variables) → not a failure: styles fallback already ran. `RATE_LIMITED` (429) → the client already retried with backoff (this applies to EVERY read — assets, tokens, styles, node trees, versions — the retry lives in the shared request path; `Retry-After` is honored, capped at 60s); if it still surfaces, wait a minute or import fewer nodes per call.
+
+**Rate-limit awareness (spec §2.1):** connector quotas vary by Figma plan — batch parent-frame requests, skip verification screenshots unless asked, and cache raw responses so re-derivation never spends a second call. REST is per-minute (10+/min, per-endpoint buckets) — fine at volume, back off on 429.
+
+## Routing
+
+Parse the user's figma link with `parseFigmaRef` (URL, `fileKey:nodeId`, bare `fileKey`). Then by intent:
+
+- "use this layer / logo / image" → **Asset** (CLI)
+- "pull my brand / colors / tokens" → **Tokens** (CLI)
+- "build a scene from this frame" → **Component** (CLI)
+- "import this animation / motion" → **Motion** (connector when available, below)
+- a storyboard section / filmstrip of scene frames → **Storyboard** (below)
+- shader fill/effect → **Shaders** (below)
+
+**Narrate every step for the user** — before each command say what you're about to pull from Figma; after it, say where the artifact landed (the frozen path / sidecar / component dir), what changed in the composition, and the immediate next action (preview, add printed variables, re-import to link bindings). The user should never have to ask "did it work?" or "now what?".
+
+## Assets (Phase 1 — CLI)
+
+```bash
+hyperframes figma asset '<url-or-fileKey:nodeId>' [more refs…] [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]
+```
+
+Renders over REST, sanitizes SVG, freezes under `.media/images/`, appends the manifest with provenance, regenerates `.media/index.md` (the shared media-use inventory), prints an `<img>` snippet. Idempotent per `fileKey:nodeId:format:scale:version`. Prefer SVG for vectors/logos (scalable, animatable), PNG `--scale 2` for raster fidelity. **Always pass `--description "<what it is>"`** (it becomes the index row + `<img alt>`); add `--entity "<name>"` for named brand marks so media-use `resolve --entity` finds them later (entity hits match across image/icon).
+
+**Batch many nodes in ONE request** — pass several refs (space-separated or comma-joined) of the SAME file: `hyperframes figma asset 'KEY:1-2' 'KEY:3-4' 'KEY:5-6'`. All render in a single `/v1/images` call, which is figma's own answer to the per-minute rate limit — prefer it over N separate commands when pulling a whole frame's worth of assets. `--description`/`--entity` apply to every node in the batch, so batch nodes that share a purpose. 429s also auto-retry with backoff regardless.
+
+## Tokens (Phase 2 — CLI)
+
+```bash
+hyperframes figma tokens <fileKey>
+```
+
+Imports variables as composition brand-variable entries + `figma-tokens.json` sidecar + binding-index records (`.media/figma-bindings.jsonl`). Variables are Enterprise-gated upstream: on other plans the command degrades to published-style metadata (values resolve at component-import time). Add the printed entries to the composition's `data-composition-variables`.
+
+**Import tokens before components** when both are wanted — that's what lets component colors link to brand variables instead of baking duplicates.
+
+**Non-Enterprise variables path (field-tested):** REST variables are Enterprise-gated, but a compatible connector may provide variable definitions. When `tokens` reports `REQUIRES_ENTERPRISE` and the connector is available, retrieve the parent scene's variables once, cache the raw response to `.media/figma-cache/`, and use it to build the binding index. The REST node tree's `boundVariables` supplies per-property `VariableID`s; join them by node and property, then write `.media/figma-bindings.jsonl` rows (`{kind:"binding", figmaId, sourceFileKey, compositionVariableId: "figma:<name>", version}`) plus the composition-variable entries. Everything downstream (component `var()` resolution, refresh, runtime CSS variables) is the shipped machinery. Label it for the user: "tokens via the Figma connector — Enterprise plans get this from `hyperframes figma tokens` directly."
+
+The runtime defines every declared composition variable as a CSS custom property (document root + sub-comp hosts), so imported `var(--slug, literal)` fills recolor when the variable default changes — updating one value in `data-composition-variables` re-brands every imported component without re-importing anything. `hyperframes render --variables '<json>'` overrides them at render time.
+
+## Components (Phase 3 — CLI)
+
+```bash
+hyperframes figma component '<url-or-fileKey:nodeId>'
+```
+
+Node tree → editable HTML at exact figma geometry, packaged as a registry item under `compositions/components/<name>/`. Vectors/boolean-ops auto-rasterize via Phase-1 export. Binding pass (spec §7.1, exact-ID only — never value matching):
+
+- **Static fidelity self-check (mandatory for hero content)**: after importing, render the fragment and compare against figma's own pixels — `figma asset <same node> --format png` is the ground truth. Text is the known drift axis: a figma text box shorter than its line-height is vertically-trimmed bounds (the mapper emits `text-box-trim` for these; measured drift without it was ~6px on a 70px font). If the comparison shows drift the mapper doesn't cover, report it — don't hand-tweak the fragment silently.
+- Fill bound to an **imported** token → `var(--slug, #literal)` — brand refresh propagates.
+- Bound to an **unknown** token → literal + `data-figma-unresolved` flag. The command tells you; offer the user: run `tokens` on the source (or library) file, then re-import the component to link them. Ask **once** per unknown library which file it is — never guess, never match by hex.
+
+## Motion (Phase 4 — connector-assisted)
+
+**Usage beacon:** Connector-assisted phases have no CLI touchpoint, so fire the skill beacon at start and finish (anonymous, consent-gated, never fails): `npx hyperframes events --skill=figma-motion` when you begin, `npx hyperframes events --skill=figma-motion --event=skill_completed --outcome=success|error` when done. Same for shaders (`figma-shaders`) and storyboards (`figma-storyboard`).
+
+No REST equivalent exists. When a compatible connector is available, use it and hand its output to the pure helpers in `@hyperframes/core/figma`; otherwise ask for a native export:
+
+1. Retrieve motion context for the parent frame in one recursive request, not one request per element. Save the raw JSON next to the project (`.media/figma-cache/`) so retranslation is free.
+2. Normalize into `MotionDoc`s with `motionContextToDocs(rawResponse, { selectorFor, repeat })` from `@hyperframes/core/figma` — **never transcribe keyframe numbers by hand**. The helper encodes the field-tested decoding rules mechanically: it parses the motion.dev snippets (the reliable encoding — the CSS snippets stretch durations and can disagree; they are ignored), strips loop-wrap tail keyframes (sub-millisecond segments at times ≈0.9999→1 are the loop's instant reset, not authored motion — the wrap is realized by `repeat` restart), and preserves bezier eases verbatim. `selectorFor` must return the ids from the Phase-3 component import — don't derive selectors from node names.
+   2b. **Validate against ground truth before calling it done — mandatory**: export the cohort's root frame through the available connector and run `node skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Y` — it compares motion-energy deltas (static import fidelity cancels out) and fails below 15dB min motion-PSNR (calibrated: faithful ≈ 20+, diverging ≈ 5). Measure `--crop` from the render's actual card edges, don't guess. FAIL means re-check the translation, not the threshold.
+3. `motionToGsap(doc)` → `emitTimelineScript(spec)` → inject as a `<script>` after the GSAP + CustomEase CDN tags. Paused, finite, registered on `window.__timelines` with a literal key.
+4. Untranslatable track (shader-driven, unsupported prop, complex masks) → export through the connector, freeze the MP4, then embed it as `<video class="clip">`. Exception: shader-driven tracks — Figma's export path flattens shaders to the base color (see Shaders below), so a bake there silently loses the shader; ask the user for a native Figma export instead. Always say which path you used and why. Named eases outside the mapped set fall back to linear — the mapping table lives in `motionEase.ts`; flag the fallback to the user when it fires.
+5. Run `npx hyperframes check` before calling it done.
+
+## Shaders (Phase 5 — mostly manual)
+
+Figma's connector render path does not execute shaders (they flatten to the base color), and shader source is only reachable for **library-published** styles (paid Full seat). Default path: ask the user to export the shader frame natively in Figma (PNG or Motion MP4), then import it as a Phase-1 asset / clip. Don't attempt connector pixel capture of a shader — it will silently produce the wrong thing.
+
+## Storyboards (a SECTION of scene frames → animation)
+
+**The cardinal rule: storyboard frames are KEYFRAMES, not slides.** Two frames containing the same element describe that element's state through time — animate the ELEMENT between the states; never play the frames as a sequence of stills. A logo drawn in four consecutive frames at descending y is ONE element rising through four keyframes. Playing storyboard frames back-to-back is the failure mode; reconstructing the element timelines they imply is the job.
+
+Storyboard files follow a grammar you can parse mechanically — don't eyeball, decode:
+
+1. **Scene units**: inside the SECTION, every frame-sized node is a scene — both named FRAMEs _and_ loose full-frame RECTANGLEs (designers paste stills straight into the section). Filter by size (≈ composition aspect, e.g. >1400×900), not by node type or name.
+2. **Order = x-position** (row-major if the strip wraps). Sort scenes by `absoluteBoundingBox.x`.
+3. **Diff adjacent frames into element chains** — this is where the animation lives. Match children across consecutive frames: first by **name** (same name = same element → tween its relative x/y/w/h between states), then by **geometry similarity** (similar size + nearby center = same logical element whose pixels changed → crossfade the two exports in place while tweening geometry; covers typed-text progressions and morph states). Unmatched children enter/exit at their scene's beat. Frame background fills tween as a color track. Export ONE asset per chain (one per state only when pixels genuinely differ) — never one still per frame.
+4. **Stills are the fallback, not the default** — only for frames that don't decompose (flat full-frame screenshots with no shared elements); those get the animatic treatment below.
+5. **Director notes**: TEXT nodes below the strip are motion intent, paired to the scene whose x-range they overlap. They describe _how_ to animate — they are not on-screen copy.
+6. **Batch exports** (elements or stills): `GET /v1/images` accepts comma-separated ids, but big scene frames hit "Render timeout" past ~12 ids — chunk to ~4 per call with a retry. (One call per scene wastes the rate budget; 26 scenes ≈ 52 calls via the single-asset path.)
+7. **Note verbs → transitions** (starter vocabulary, extend as encountered):
+
+| Note says                       | Do                                                                |
+| ------------------------------- | ----------------------------------------------------------------- |
+| EXPLOSION / BURST               | incoming scale ~1.5→1 + fade, `power3.out`                        |
+| SLIDES / SLIDE TO THE… / SCROLL | directional slide in from that edge                               |
+| MORPH / REVEALS                 | crossfade — or Phase-3 import if the motion is inside one scene   |
+| CYCLE THROUGH / EACH ONE        | longer hold — or Phase-3 import if items animate within the scene |
+| (no note)                       | crossfade + slow Ken-Burns drift                                  |
+
+8. **Stills vs. components routing**: a note describing motion _between_ scenes → transition on the still (above). A note describing motion _inside_ a scene ("TEXT LINES REVEAL ONE AFTER THE OTHER", "PILLS ANIMATE IN") → that frame deserves a Phase-3 component import (real elements) animated per the note, not a flat PNG. Do the animatic pass first with stills, then upgrade the scenes the notes single out.
+9. One `main` timeline sequences everything (opacity/x/y per scene at absolute times) — no per-scene sub-compositions needed for an animatic.
+10. **Escalation — frames depict ONE product UI → rebuild the app, not element chains.** When every frame is the same application screen in successive states (a signup flow, a settings panel, a player), element chains undersell it. Rebuild the UI as live DOM — Phase-3 component import for the parts that change state, real exported pixels for static chrome (**code what changes state, freeze what doesn't**) — and treat each frame delta as an **interaction to perform**, not a tween to apply: the cursor enters, clicks the control, the state responds, screens push/slide as real navigation. The result reads as one continuous screen recording of a working app. This is the cardinal rule taken to its conclusion for UI flows; the stills/element-chain treatments are for storyboards that aren't one coherent application.
+
+## Determinism
+
+Never leave a Figma URL in the composition — freeze first. Never emit `repeat: -1`. Timelines paused, finite, literal `window.__timelines` keys. All Figma I/O at import time; render sees local files only.