dsh-hyperframes 0.9.1 → 0.9.3

package/skills/pr-to-video/scripts/transitions.mjs

@@ -1,383 +0,0 @@
-#!/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/pr-to-video/scripts/workflow-guardrails.test.mjs

@@ -1,198 +0,0 @@
-import assert from "node:assert/strict";
-import { existsSync, mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir, tmpdir } from "node:os";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import test from "node:test";
-
-import { parsePrReference, resolvePrToVideoProjectDir } from "./project-dir.mjs";
-import { buildFramePackets } from "./frame-packets.mjs";
-import { hasCliCommand } from "./preflight.mjs";
-
-function write(path, contents) {
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, contents);
-}
-
-test("default project directory is durable and outside the caller repository", () => {
-  const caller = mkdtempSync(join(tmpdir(), "p2v-caller-"));
-  const cache = mkdtempSync(join(tmpdir(), "p2v-cache-"));
-  const result = resolvePrToVideoProjectDir({
-    pr: "https://github.com/EveryInc/compound-engineering-plugin/pull/1092",
-    cwd: caller,
-    env: { XDG_CACHE_HOME: cache, HOME: homedir() },
-  });
-
-  assert.equal(
-    result,
-    join(
-      cache,
-      "hyperframes",
-      "pr-to-video",
-      "everyinc",
-      "compound-engineering-plugin",
-      "compound-engineering-plugin-pr-1092",
-    ),
-  );
-  assert.ok(isAbsolute(result));
-  assert.ok(relative(caller, result).startsWith(".."));
-});
-
-test("explicit project directory is preserved exactly after absolute resolution", () => {
-  const caller = mkdtempSync(join(tmpdir(), "p2v-explicit-caller-"));
-  assert.equal(
-    resolvePrToVideoProjectDir({
-      pr: "EveryInc/compound-engineering-plugin#1092",
-      cwd: caller,
-      explicitDir: "../my-video",
-      env: {},
-    }),
-    resolve(caller, "../my-video"),
-  );
-});
-
-test("distinct owner and repository segments cannot collide in the durable cache", () => {
-  const cache = mkdtempSync(join(tmpdir(), "p2v-cache-collision-"));
-  const first = resolvePrToVideoProjectDir({
-    pr: "foo-bar/baz#1",
-    env: { XDG_CACHE_HOME: cache },
-  });
-  const second = resolvePrToVideoProjectDir({
-    pr: "foo/bar-baz#1",
-    env: { XDG_CACHE_HOME: cache },
-  });
-
-  assert.notEqual(first, second);
-});
-
-test("PR parsing sanitizes owner and repository path traversal", () => {
-  assert.deepEqual(
-    parsePrReference("https://github.com/EveryInc/compound-engineering-plugin/pull/1092"),
-    {
-      owner: "everyinc",
-      repo: "compound-engineering-plugin",
-      number: 1092,
-    },
-  );
-  assert.throws(() => parsePrReference("../../outside#1092"), /valid GitHub PR reference/i);
-});
-
-test("#1092 packets contain selected excerpts but never the full diff", () => {
-  const project = mkdtempSync(join(tmpdir(), "p2v-packets-"));
-  const largeDiff = `diff --git a/noise b/noise\n${"+unselected noise\n".repeat(10_000)}`;
-  write(join(project, "capture", "diff.patch"), largeDiff);
-  write(join(project, "frame.md"), "# compact frame tokens\n");
-  write(
-    join(project, "STORYBOARD.md"),
-    `---\nformat: 1920x1080\n---\n\n## Frame 1 — Diff\n\n- duration: 4s\n- src: compositions/frames/01-diff.html\n- focal: code-diff\n- blueprint: compose\n- rules: text-reveal\n\n### Source excerpt\n\n\`\`\`diff\n-oldCall()\n+newCall({ attested: true })\n\`\`\`\n\n## Frame 2 — Impact\n\n- duration: 3s\n- src: compositions/frames/02-impact.html\n- blueprint: dataviz-countup\n- rules: counting-dynamic-scale\n`,
-  );
-
-  const result = buildFramePackets({
-    projectDir: project,
-    storyboardPath: join(project, "STORYBOARD.md"),
-    outDir: join(project, ".hyperframes", "frame-packets"),
-    maxPacketBytes: 32_000,
-  });
-
-  assert.equal(result.length, 2);
-  const codePacket = readFileSync(result[0].path, "utf8");
-  assert.match(codePacket, /newCall\(\{ attested: true \}\)/);
-  assert.doesNotMatch(codePacket, /unselected noise/);
-  assert.doesNotMatch(codePacket, /code-scroll/);
-  assert.ok(Buffer.byteLength(codePacket) < 32_000);
-  assert.ok(result.every((packet) => packet.path.endsWith(".md")));
-
-  const role = readFileSync(join(project, ".hyperframes", "frame-packets", "_role.md"), "utf8");
-  assert.match(role, /# Frame worker — core contract/);
-  assert.match(role, /# Frame worker — PR-to-video delta/);
-});
-
-test("packet validation is atomic and leaves no partial output on overflow", () => {
-  const project = mkdtempSync(join(tmpdir(), "p2v-packets-atomic-"));
-  const outDir = join(project, ".hyperframes", "frame-packets");
-  write(join(project, "frame.md"), "# frame\n");
-  write(
-    join(project, "STORYBOARD.md"),
-    `---\nformat: 1920x1080\n---\n\n## Frame 1 — Intro\n\n- duration: 2s\n- src: compositions/frames/01-intro.html\n\n## Frame 2 — Diff\n\n- duration: 4s\n- src: compositions/frames/02-diff.html\n- focal: code-diff\n\n### Source excerpt\n\n\`\`\`diff\n${"+oversized line\n".repeat(300)}\`\`\`\n`,
-  );
-
-  assert.throws(
-    () => buildFramePackets({ projectDir: project, outDir, maxPacketBytes: 2_000 }),
-    /limit 2000/,
-  );
-  assert.equal(existsSync(outDir), false);
-});
-
-test("code frames without an upstream-selected excerpt fail before dispatch", () => {
-  const project = mkdtempSync(join(tmpdir(), "p2v-packets-missing-"));
-  write(join(project, "frame.md"), "# frame\n");
-  write(
-    join(project, "STORYBOARD.md"),
-    `---\nformat: 1920x1080\n---\n\n## Frame 1 — Diff\n\n- duration: 4s\n- src: compositions/frames/01-diff.html\n- focal: code-diff\n`,
-  );
-
-  assert.throws(
-    () =>
-      buildFramePackets({
-        projectDir: project,
-        storyboardPath: join(project, "STORYBOARD.md"),
-        outDir: join(project, ".hyperframes", "frame-packets"),
-      }),
-    /Source excerpt/i,
-  );
-});
-
-// The other half of this skill's frame-packets delta. The excerpt guard above is
-// pinned; the code-vocabulary injection was not — deleting `codeVocabularySection`
-// outright left all 455 skills tests green, so the section a code worker reads to
-// pick its registry block could have been dropped silently.
-test("a code frame carries the vocabulary excerpt for the block it names", () => {
-  const project = mkdtempSync(join(tmpdir(), "p2v-packets-vocab-"));
-  write(join(project, "frame.md"), "# frame\n");
-  write(
-    join(project, "STORYBOARD.md"),
-    `---\nformat: 1920x1080\n---\n\n## Frame 1 — Diff\n\n- duration: 4s\n- src: compositions/frames/01-diff.html\n- focal: code-diff\n\n### Source excerpt\n\n\`\`\`diff\n-oldCall()\n+newCall()\n\`\`\`\n`,
-  );
-
-  const [packet] = buildFramePackets({ projectDir: project });
-  const contents = readFileSync(packet.path, "utf8");
-
-  assert.match(contents, /## Code block excerpt \(code-diff\)/);
-  assert.match(contents, /`code-diff`/);
-});
-
-test("a code block the vocabulary does not describe still names itself for install", () => {
-  const project = mkdtempSync(join(tmpdir(), "p2v-packets-vocab-miss-"));
-  write(join(project, "frame.md"), "# frame\n");
-  write(
-    join(project, "STORYBOARD.md"),
-    `---\nformat: 1920x1080\n---\n\n## Frame 1 — Diff\n\n- duration: 4s\n- src: compositions/frames/01-diff.html\n- focal: code-not-in-the-vocabulary\n\n### Source excerpt\n\n\`\`\`diff\n-oldCall()\n+newCall()\n\`\`\`\n`,
-  );
-
-  const [packet] = buildFramePackets({ projectDir: project });
-
-  assert.match(
-    readFileSync(packet.path, "utf8"),
-    /## Code block\n\nUse registry block `code-not-in-the-vocabulary`\./,
-  );
-});
-
-test("a mechanism frame gets no code-block section at all", () => {
-  const project = mkdtempSync(join(tmpdir(), "p2v-packets-mechanism-"));
-  write(join(project, "frame.md"), "# frame\n");
-  write(
-    join(project, "STORYBOARD.md"),
-    `---\nformat: 1920x1080\n---\n\n## Frame 1 — Mechanism\n\n- duration: 4s\n- src: compositions/frames/01-mechanism.html\n- focal: the request-lifecycle flow\n`,
-  );
-
-  const [packet] = buildFramePackets({ projectDir: project });
-
-  assert.doesNotMatch(readFileSync(packet.path, "utf8"), /## Code block/);
-});
-
-test("CLI capability detection rejects skills newer than the available command surface", () => {
-  const stableHelp = `Project:\n  lint  Validate a composition\n  snapshot  Capture frames\n\nUnknown command check`;
-  const currentHelp = `Project:\n  lint  Validate a composition\n  check Run the full project validation gate\n  snapshot  Capture frames`;
-
-  assert.equal(hasCliCommand(stableHelp, "check"), false);
-  assert.equal(hasCliCommand(currentHelp, "check"), true);
-});

package/skills/pr-to-video/sub-agents/frame-worker.md

@@ -1,38 +0,0 @@
-# Frame worker — PR-to-video delta
-
-> The shared law is the core contract above (the packet builder prepends `../hyperframes/references/frame-worker-core.md` to this file as `_role.md`) — read the two as one role. This file carries only what's specific to a PR-to-video frame.
-
-## Batch dispatch — you build a small packet batch
-
-At most three workers run; your dispatch assigns **one or more** bounded packet paths under `.hyperframes/frame-packets/`. Read this role and shared `frame.md` **once**, then process the packets in order — for each, use its exact frame block, inlined blueprint / rule excerpts, and (for a code beat) the selected code-block / source excerpts. Never open the full `STORYBOARD.md`, `capture/diff.patch`, or `capture/extracted/visible-text.txt`; the orchestrator already selected the exact source excerpt and put it in each code frame's packet. After the last assigned file passes the self-check, stop.
-
-Extra inputs beyond the core contract:
-
-- `code-vocabulary.md` — absolute path provided in your dispatch. For a **code beat**, read it for the named `code-*` block's exact inputs (`window.__TOKENS`, `window.__BLOCK`, line indexing); your packet carries the matching excerpt.
-- `focal:` — for a concept/mechanism beat, which **invented** element is the hero; for a **code beat**, the named **`code-*` block** (+ the hunk); for the **credits** close, the avatar row.
-- `roles:` — each element's role: `foreground subject` / `background` full-bleed / `supporting`. Most are invented elements you design; the only real assets are the credits `assets/<login>.png` avatars.
-
-## Mostly invented — you build the visual (except code blocks + the credits avatars)
-
-A PR video is **mostly invented**: there are **no screenshots and no captured UI**. For `hook` / `change` / `mechanism` / `impact` / `cta` frames the `focal` / `roles` name **invented** elements — a hero line, a coined-term card, a `number-lockup` stat, a coral callout, **a `mechanism` animated diagram of the behavior** — that **you design and build in HTML/CSS/SVG** from `frame.md`. Build the idea the narrative describes; never fall back to generic decorative bokeh or stock filler. Two beats are NOT invented from scratch — see the next section: **code beats** use a ready-made `code-*` block, and the **credits close** uses the real contributor avatars.
-
-## PR code beats, mechanism beats + the credits close
-
-- **Code beats (`diff` / `before_after` / a new-code reveal) — use the named `code-*` block, don't hand-build code motion.** Your `## Frame N` `scene` / `focal` names which block (e.g. `code-diff`, `code-morph`, `code-typing`); the orchestrator has already installed it (pre-install step). Read the `code-vocabulary.md` excerpt in your packet for that block's exact inputs, then:
-  - Use only the packet's `### Source excerpt`. It is the real before/after hunk selected upstream. Never reopen the full diff or brief.
-  - Fill the block's `window.__TOKENS` with that real code (the baked Shiki tokens) and set `window.__BLOCK` (effect, `line`, `duration`) **so the full block completes within the frame's `data-duration`** — a long snippet at the block's default per-character cadence overruns a short frame (the code never finishes typing). `code-diff` / `code-morph` need **2 states** (before, after); the others take one. **Line indexing differs — `code-highlight` is 0-based, `code-scroll` 1-based** — don't off-by-one.
-  - Integrate the filled block as **this frame's composition** per the core sub-composition contract: its `data-composition-id` and its `window.__timelines[...]` key must both be your **`<frame_id>`** (the block ships its own id + paused timeline; rename both to match the frame contract). The block already renders an editor window (titlebar / filename) reading as code-editorial's navy **Code Surface** — set the filename + any `+N/−M` chrome from the `scene`.
-  - **The block owns the code animation; your Scene windows choreograph the surrounding Code Surface** — the navy window seating in, the file header typing on, the camera settling onto the hunk, a coral underline on the landed line. **Do not re-specify the code motion** (the block is the development beat). A code beat is usually `blueprint: compose`.
-  - **The block has no caption-safe band.** When `Captions: enabled`, inset/scale the code panel into the top ~83% so it clears the keep-out band; never let code run under the caption pill.
-- **Mechanism beats (`mechanism`) — build an invented animated diagram of the behavior; the build _is_ the shot.** This is the "show what the change does at runtime" frame (the request retrying, the cache filling, serial→parallel, the race resolved) — read its `scene` for the behavior to animate. Unlike a code beat, **the motion is yours to author** (no block owns it):
-  - If the `scene` names a `flowchart` / `flowchart-vertical` / `data-chart` block, the orchestrator pre-installed it — fill + mount it like a code block (its `data-composition-id` and `window.__timelines[...]` key both become your `<frame_id>`). Otherwise **hand-build the diagram in SVG / HTML / GSAP** from `frame.md`'s atoms.
-  - **Code editorial register:** hairline-ink nodes / edges / lanes on the cream ground, **one coral marker** on the active / changed element, mono labels — **not** the navy code surface (that's for code), no heavy shapes / bokeh.
-  - **Choreograph the Scene windows:** the nodes / lanes draw on (Scene 1); **the flow runs** as the VO names each step (middle Scenes — the request hops, the lane splits, the front advances, the bars race) — this _is_ the teaching, so it must play across the shot, never enter-then-freeze; the resolved state + the one coral emphasis lands (final Scene). Keep it in the top ~83% (caption keep-out).
-- **The `credits` close — the one frame with real assets.** Its `asset_candidates` names 2–6 `assets/<login>.png` avatars (downloaded upstream). Render them as `<img>` in hairline-ringed chips — an avatar row with each contributor's name + role in mono (an "approved" mark if the close calls for it), staggered in across the Scene windows. Avatars appear **only** here, never decorating a code frame.
-
-## PR-specific self-check additions
-
-- The composition root also carries a **positive `data-duration` matching the packet**.
-- **Code-block cadence fits `data-duration`** — for a code beat, the `code-*` block's internal cadence is set so the full block completes within the frame's `data-duration` (a long snippet at the default per-character speed overruns — the code never finishes and the chrome beats never play; see `code-vocabulary.md`).
-- Fonts: copy the auto-generated `@font-face` block from `frame.md`; the Code editorial preset's EB Garamond, Inter, and JetBrains Mono faces live in `assets/fonts/`. Never link Google Fonts.
-- Visible-text exception: real code inside a `code-*` block is the content, not narration.