dsh-hyperframes 0.9.1 → 0.9.2

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

@@ -1,219 +0,0 @@
-import assert from "node:assert/strict";
-import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import test from "node:test";
-import { fileURLToPath } from "node:url";
-import { brandFontFaces, buildFromSkin } from "./captions.mjs";
-
-const presetsDir = fileURLToPath(
-  new URL("../../hyperframes-creative/frame-presets/", import.meta.url),
-);
-const skins = readdirSync(presetsDir, { withFileTypes: true })
-  .filter((entry) => entry.isDirectory())
-  .map((entry) => ({
-    name: entry.name,
-    source: readFileSync(
-      new URL(
-        `../../hyperframes-creative/frame-presets/${entry.name}/caption-skin.html`,
-        import.meta.url,
-      ),
-      "utf8",
-    ),
-  }))
-  .filter(({ source }) => source.includes(".caption-word.is-active"));
-
-for (const canvas of ["#f7f3e8", "#111827"]) {
-  for (const skin of skins) {
-    test(`${skin.name} preserves word-state rules on ${canvas}`, () => {
-      const active = skin.source.match(/\.caption-word\.is-active\s*\{[^}]*\}/s)?.[0];
-      const spoken = skin.source.match(/\.caption-word\.is-spoken\s*\{[^}]*\}/s)?.[0];
-      assert.ok(active, "skin must define an active-word rule");
-      assert.ok(spoken, "skin must define a spoken-word rule");
-
-      const output = buildFromSkin(
-        skin.source,
-        [],
-        1,
-        1920,
-        1080,
-        `:root { --cap-canvas: ${canvas}; --cap-ink: #111111; --cap-accent: #ffcc00; }`,
-        (message) => {
-          throw new Error(message);
-        },
-      );
-
-      assert.ok(output.includes(active));
-      assert.ok(output.includes(spoken));
-      assert.equal(output.match(/\.caption-word\.is-active\s*\{/g)?.length, 1);
-      assert.equal(output.match(/\.caption-word\.is-spoken\s*\{/g)?.length, 1);
-    });
-  }
-}
-
-// @font-face is document-global on purpose — the composition CSS scoper exempts it, and it
-// has to, since a face declaration cannot be scoped. That makes brandFontFaces the one part
-// of the captions sub-composition whose output reaches every sibling composition, so it has
-// to describe each face exactly: get an axis wrong and the whole document renders the brand
-// family wrong.
-function withFontProject(files, run) {
-  const dir = mkdtempSync(join(tmpdir(), "hf-captions-fonts-"));
-  try {
-    mkdirSync(join(dir, "assets/fonts"), { recursive: true });
-    for (const name of files) writeFileSync(join(dir, "assets/fonts", name), "");
-    writeFileSync(
-      join(dir, "frame.md"),
-      'typography:\n  display: { fontFamily: "Newsreader", weight: 400 }\n  body: { fontFamily: "Inter", weight: 400 }\n',
-    );
-    return run(join(dir, "frame.md"), dir);
-  } finally {
-    rmSync(dir, { recursive: true, force: true });
-  }
-}
-
-test("an italic file is declared italic, and never squats the family's upright slot", () => {
-  // Google Fonts' own Newsreader download. The italic sorts first, so before the style axis
-  // existed it claimed the family's only 400 slot, the upright was dropped as a duplicate,
-  // and the face shipped with no font-style — italicizing every sibling composition that
-  // used Newsreader.
-  const faces = withFontProject(
-    ["Newsreader-Italic-VariableFont_opsz,wght.ttf", "Newsreader-VariableFont_opsz,wght.ttf"],
-    brandFontFaces,
-  );
-  const lines = faces.split("\n").filter((line) => line.includes("Newsreader"));
-  assert.equal(lines.length, 2, "both the upright and the italic file must be declared");
-
-  const upright = lines.find((line) => line.includes("Newsreader-VariableFont"));
-  const italic = lines.find((line) => line.includes("Newsreader-Italic-VariableFont"));
-  assert.ok(upright, "the upright file must survive");
-  assert.match(upright, /font-style: normal/);
-  assert.ok(italic, "the italic file must survive");
-  assert.match(italic, /font-style: italic/);
-});
-
-test("a numeric weight in the filename is read as the weight", () => {
-  // Fontsource names every face numerically and carries no weight WORD, so word-only
-  // parsing scored the whole family 400 and shipped exactly one of its four faces.
-  const faces = withFontProject(
-    [
-      "inter-latin-400-normal.woff2",
-      "inter-latin-500-normal.woff2",
-      "inter-latin-600-italic.woff2",
-      "inter-latin-700-normal.woff2",
-    ],
-    brandFontFaces,
-  );
-  const lines = faces.split("\n").filter((line) => line.includes("Inter"));
-  assert.equal(lines.length, 4, "each face is a distinct weight/style pair");
-  for (const [file, weight, style] of [
-    ["inter-latin-400-normal", 400, "normal"],
-    ["inter-latin-500-normal", 500, "normal"],
-    ["inter-latin-600-italic", 600, "italic"],
-    ["inter-latin-700-normal", 700, "normal"],
-  ]) {
-    const line = lines.find((candidate) => candidate.includes(file));
-    assert.ok(line, `${file} must be declared`);
-    assert.match(line, new RegExp(`font-weight: ${weight};`));
-    assert.match(line, new RegExp(`font-style: ${style};`));
-  }
-});
-
-test("word-named weights still parse when the filename carries no numeric axis", () => {
-  const faces = withFontProject(
-    ["Newsreader_Bold.woff2", "Newsreader_Regular.woff2"],
-    brandFontFaces,
-  );
-  const lines = faces.split("\n").filter((line) => line.includes("Newsreader"));
-  assert.equal(lines.length, 2);
-  assert.match(
-    lines.find((line) => line.includes("Bold")),
-    /font-weight: 700; font-style: normal/,
-  );
-  assert.match(
-    lines.find((line) => line.includes("Regular")),
-    /font-weight: 400; font-style: normal/,
-  );
-});
-
-// build-frame.mjs stages captured brand fonts under a REWRITTEN name, and brandFontFaces
-// derives the face's axes back out of that name. The two are a contract, and it is easy to
-// break silently from either side: build-frame used to drop the style token while renaming,
-// so an italic file arrived as "Newsreader-Regular.ttf" and was declared upright — leaving
-// the document-global normal slot pointing at italic bytes even once brandFontFaces learned
-// about styles. These two tests pin both ends of that contract.
-test("the names build-frame.mjs stages round-trip back to the right face", () => {
-  const faces = withFontProject(
-    [
-      "Newsreader-Regular.ttf",
-      "Newsreader-Regular-Italic.ttf",
-      "Inter-400.woff2",
-      "Inter-600-Italic.woff2",
-    ],
-    brandFontFaces,
-  );
-  for (const [file, weight, style] of [
-    ["Newsreader-Regular.ttf", 400, "normal"],
-    ["Newsreader-Regular-Italic.ttf", 400, "italic"],
-    ["Inter-400.woff2", 400, "normal"],
-    ["Inter-600-Italic.woff2", 600, "italic"],
-  ]) {
-    const line = faces.split("\n").find((candidate) => candidate.includes(`/${file}'`));
-    assert.ok(line, `${file} must be declared`);
-    assert.match(line, new RegExp(`font-weight: ${weight};`));
-    assert.match(line, new RegExp(`font-style: ${style};`));
-  }
-});
-
-test("a weight token buried in a longer run is not read as a weight", () => {
-  // capture/assets/fonts commonly holds hash-named files, and a hash is not a weight.
-  const faces = withFontProject(
-    ["Newsreader-a1b200c3.woff2", "Inter-2100.woff2", "Inter900.woff2"],
-    brandFontFaces,
-  );
-  const weightOf = (file) =>
-    Number(/font-weight: (\d+);/.exec(faces.split("\n").find((l) => l.includes(file)))?.[1]);
-
-  // "200" sits mid-run (…b200c3), so the word path decides: Regular.
-  assert.equal(weightOf("Newsreader-a1b200c3.woff2"), 400);
-  // 4-digit guard: "2100" must not read as 100.
-  assert.equal(weightOf("Inter-2100.woff2"), 400);
-  // ...but a trailing weight with no separator is still a weight.
-  assert.equal(weightOf("Inter900.woff2"), 900);
-});
-
-// captions.mjs ships once per creation workflow because each skill installs standalone,
-// and the three copies are meant to be byte-identical. This PR alone had to land the same
-// two-axis fix in all three; a future one that lands in only one drifts silently.
-test("captions.mjs is byte-identical across the three workflows that ship it", () => {
-  const [first, ...rest] = ["product-launch-video", "faceless-explainer", "pr-to-video"].map(
-    (skill) => ({
-      skill,
-      source: readFileSync(new URL(`../../${skill}/scripts/captions.mjs`, import.meta.url), "utf8"),
-    }),
-  );
-  for (const other of rest) {
-    assert.equal(other.source, first.source, `${other.skill} drifted from ${first.skill}`);
-  }
-});
-
-test("every build-frame.mjs copy stages the style axis it promises", () => {
-  for (const skill of ["product-launch-video", "faceless-explainer", "pr-to-video"]) {
-    const source = readFileSync(
-      new URL(`../../${skill}/scripts/build-frame.mjs`, import.meta.url),
-      "utf8",
-    );
-    // The staged filename must carry the style, or the italic and upright faces of one
-    // weight collide on a single name and only whichever sorts first survives.
-    assert.match(
-      source,
-      /const clean = `\$\{fam\.replace\(\/\[\^A-Za-z0-9\]\/g, ""\)\}-\$\{w\}\$\{style === "italic" \? "-Italic" : ""\}\./,
-      `${skill}/build-frame.mjs must keep the style token in the staged name`,
-    );
-    // ...and the emitted descriptor must report the real style, not a hardcoded normal.
-    assert.doesNotMatch(
-      source,
-      /font-weight:\$\{n\};font-style:normal/,
-      `${skill}/build-frame.mjs must not assert font-style:normal over captured bytes`,
-    );
-  }
-});

package/skills/faceless-explainer/scripts/frame-packets.mjs

@@ -1,27 +0,0 @@
-#!/usr/bin/env node
-
-// Thin wrapper over the shared packet builder in hyperframes — this file only
-// pins the paths that are specific to this workflow skill. The logic (frame
-// splitting, rule citation, packet bounds, `_role.md` assembly) has one owner:
-// ../../hyperframes/scripts/lib/frame-packets-core.mjs
-
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import * as core from "./lib/frame-packets-core.mjs";
-
-const SKILL_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const CONFIG = {
-  animationDir: resolve(SKILL_DIR, "../hyperframes-animation"),
-  corePath: resolve(SKILL_DIR, "../hyperframes/references/frame-worker-core.md"),
-  deltaPath: resolve(SKILL_DIR, "sub-agents/frame-worker.md"),
-};
-
-export function buildRolePayload({ outDir }) {
-  return core.buildRolePayload({ ...CONFIG, outDir });
-}
-
-export function buildFramePackets(options) {
-  return core.buildFramePackets({ ...CONFIG, ...options });
-}
-
-if (core.isMainModule(import.meta.url)) core.runCli({ buildFramePackets, buildRolePayload });

package/skills/faceless-explainer/scripts/frame-packets.test.mjs

@@ -1,66 +0,0 @@
-import assert from "node:assert/strict";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-import test from "node:test";
-
-import { buildFramePackets } from "./frame-packets.mjs";
-
-function write(path, contents) {
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, contents);
-}
-
-test("packets inline the blueprint body and the Scene-cited rule recipes", () => {
-  const project = mkdtempSync(join(tmpdir(), "fev-packets-"));
-  write(join(project, "frame.md"), "# tokens\n");
-  write(
-    join(project, "STORYBOARD.md"),
-    `---\nformat: 1920x1080\n---\n\n## Frame 1 — Hook\n\n- duration: 3s\n- src: compositions/frames/01-hook.html\n- blueprint: dataviz-countup\n- scene: hero stat punches in\n\nScene 1 (0.0–1.5s): the stat enters via spring-pop-entrance, then counting-dynamic-scale runs the tally.\n\n## Frame 2 — Freeform\n\n- duration: 4s\n- src: compositions/frames/02-freeform.html\n- blueprint: compose\n\nScene 1 (0.0–4.0s): a quiet hold, no named motion.\n`,
-  );
-
-  const result = buildFramePackets({ projectDir: project });
-  assert.equal(result.length, 2);
-
-  const hook = readFileSync(result[0].path, "utf8");
-  assert.match(hook, /## Selected blueprint: dataviz-countup/);
-  assert.match(hook, /## Selected motion rule: spring-pop-entrance/);
-  assert.match(hook, /## Selected motion rule: counting-dynamic-scale/);
-  assert.match(hook, /RULES_DIR: /);
-
-  const freeform = readFileSync(result[1].path, "utf8");
-  assert.doesNotMatch(freeform, /## Selected blueprint/);
-  assert.doesNotMatch(freeform, /## Selected motion rule/);
-});
-
-test("_role.md is the core contract + this workflow's delta, verbatim", () => {
-  const project = mkdtempSync(join(tmpdir(), "fev-role-"));
-  write(join(project, "frame.md"), "# tokens\n");
-  write(
-    join(project, "STORYBOARD.md"),
-    `---\nformat: 1920x1080\n---\n\n## Frame 1 — Hook\n\n- duration: 3s\n- src: compositions/frames/01-hook.html\n`,
-  );
-
-  buildFramePackets({ projectDir: project });
-  const rolePath = join(project, ".hyperframes", "frame-packets", "_role.md");
-  assert.ok(existsSync(rolePath));
-  const role = readFileSync(rolePath, "utf8");
-  assert.match(role, /# Frame worker — core contract/);
-  assert.match(role, /# Frame worker — faceless-explainer delta/);
-});
-
-test("packet validation is atomic and leaves no partial output on overflow", () => {
-  const project = mkdtempSync(join(tmpdir(), "fev-atomic-"));
-  const outDir = join(project, ".hyperframes", "frame-packets");
-  write(join(project, "frame.md"), "# tokens\n");
-  write(
-    join(project, "STORYBOARD.md"),
-    `---\nformat: 1920x1080\n---\n\n## Frame 1 — Big\n\n- duration: 3s\n- src: compositions/frames/01-big.html\n\n${"padding line\n".repeat(300)}`,
-  );
-
-  assert.throws(
-    () => buildFramePackets({ projectDir: project, outDir, maxPacketBytes: 2_000 }),
-    /limit 2000/,
-  );
-  assert.equal(existsSync(outDir), false);
-});

package/skills/faceless-explainer/scripts/lib/assets.mjs

@@ -1,56 +0,0 @@
-// assets.mjs — stage frame-named capture assets into assets/.
-// Shared by stage-assets.mjs (Step 4 close, BEFORE the frame workers run) and
-// assemble-index.mjs (Step 5, idempotent backstop). Only assets a frame names
-// in `asset_candidates` are staged; unnamed assets never reach the project.
-// asset_candidates value form: "assets/<basename> — desc; assets/… — …".
-
-import { copyFileSync, existsSync, mkdirSync } from "node:fs";
-import { basename, join } from "node:path";
-
-export function basenamesFromCandidates(value) {
-  if (typeof value !== "string") return [];
-  return value
-    .split(";")
-    .map((seg) => seg.split(/\s+[—–-]\s+/)[0].trim()) // strip the " — description"
-    .filter(Boolean)
-    .map((p) => basename(p.replace(/^assets\//, "")));
-}
-
-// Copy each frame's asset_candidates from capture/{assets,assets/videos,
-// assets/svgs, screenshots} into assets/. Already-staged files are left as is
-// (first-wins), so calling this twice is safe. Returns { staged, wanted, anomalies }.
-export function stageAssets({ hyperframesDir, frames }) {
-  const wanted = new Set();
-  for (const f of frames) {
-    for (const b of basenamesFromCandidates(f.extra?.asset_candidates)) wanted.add(b);
-  }
-  const captureDirs = [
-    join(hyperframesDir, "capture/assets"),
-    join(hyperframesDir, "capture/assets/videos"), // videos download into a subdir
-    join(hyperframesDir, "capture/assets/svgs"), // inline SVGs extract into a subdir
-    join(hyperframesDir, "capture/screenshots"),
-  ];
-  const assetsDir = join(hyperframesDir, "assets");
-  const anomalies = [];
-  let staged = 0;
-  if (wanted.size > 0) {
-    mkdirSync(assetsDir, { recursive: true });
-    for (const b of wanted) {
-      const dest = join(assetsDir, b);
-      if (existsSync(dest)) {
-        staged++;
-        continue;
-      } // first-wins / already staged
-      const src = captureDirs.map((d) => join(d, b)).find((p) => existsSync(p));
-      if (src) {
-        copyFileSync(src, dest);
-        staged++;
-      } else {
-        anomalies.push(
-          `asset "${b}" named by a frame but not found under capture/ — frame will 404 it`,
-        );
-      }
-    }
-  }
-  return { staged, wanted, anomalies };
-}

package/skills/faceless-explainer/scripts/lib/bgm-volume.mjs

@@ -1,4 +0,0 @@
-// Music sits under narration; a silent film brings music forward.
-export const BGM_BED_VOLUME = 0.12;
-export const BGM_SILENT_VOLUME = 0.9;
-export const bgmDefaultVolume = (hasVoice) => (hasVoice ? BGM_BED_VOLUME : BGM_SILENT_VOLUME);

package/skills/faceless-explainer/scripts/lib/captured-fonts.mjs

@@ -1,58 +0,0 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-
-// Capture preserves subset and variable-axis descriptors in extracted/page.html.
-// Filenames alone cannot identify a face's character coverage.
-export function stageCapturedFonts(projectDir, families) {
-  const page = join(projectDir, "capture/extracted/page.html");
-  const result = { faces: [], families: new Set(), files: new Set() };
-  if (!existsSync(page)) return result;
-  const wanted = new Set(families.map((family) => family.toLowerCase()));
-  const html = readFileSync(page, "utf8");
-  const copied = new Set();
-  for (const style of html.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi)) {
-    const css = style[1].replace(/\/\*[\s\S]*?\*\//g, "");
-    for (const match of css.matchAll(/@font-face\s*\{([^}]+)\}/gi)) {
-      const body = match[1];
-      const familyValue = /(?:^|;)\s*font-family\s*:\s*([^;]+)/i.exec(body)?.[1]?.trim();
-      if (!familyValue) continue;
-      const family = familyValue.replace(/^(['"])(.*)\1$/, "$2");
-      if (!wanted.has(family.toLowerCase())) continue;
-      result.families.add(family.toLowerCase());
-      const source = /(?:^|;)\s*src\s*:\s*([^;]+)/i.exec(body);
-      if (!source) continue;
-      const sources = localFontSources(source[1], projectDir);
-      if (!sources.length) {
-        console.warn("Captured font has no downloaded source: " + family);
-        continue;
-      }
-      for (const file of sources) {
-        if (copied.has(file.name)) continue;
-        if (!copied.size) mkdirSync(join(projectDir, "assets/fonts"), { recursive: true });
-        copyFileSync(file.source, join(projectDir, file.target));
-        copied.add(file.name);
-        result.files.add(file.target);
-      }
-      const src = sources.map((file) => file.css).join(", ");
-      const rule = "@font-face{" + body.replace(source[1], src) + "}";
-      if (!result.faces.includes(rule)) result.faces.push(rule);
-    }
-  }
-  return result;
-}
-
-function localFontSources(source, projectDir) {
-  const files = [];
-  for (const match of source.matchAll(
-    /url\(\s*(?:"([^"]+)"|'([^']+)'|([^\s)]+))\s*\)(\s*format\([^)]*\))?/gi,
-  )) {
-    const url = match[1] ?? match[2] ?? match[3];
-    const name = /^assets\/fonts\/([a-z0-9_.-]+\.(?:woff2?|ttf|otf))$/i.exec(url)?.[1];
-    if (!name) continue;
-    const path = join(projectDir, "capture/assets/fonts", name);
-    if (!existsSync(path)) continue;
-    const target = "assets/fonts/captured-" + name;
-    files.push({ name, source: path, target, css: 'url("' + target + '")' + (match[4] ?? "") });
-  }
-  return files;
-}

package/skills/faceless-explainer/scripts/lib/dimensions.mjs

@@ -1,45 +0,0 @@
-// dimensions.mjs — canvas size + caption-band geometry for the video
-// pipeline. Single source of truth = the STORYBOARD frontmatter `format` global
-// ("1920x1080" / "1080x1920" / "1080x1080", or a named orientation). Every
-// script and the index assembler reads the size from here; none hardcodes it.
-
-// Named orientation presets. Square/portrait are 1080-based so they share the
-// long-edge pixel budget with landscape (same render-cost ballpark).
-export const ORIENTATION_PRESETS = {
-  landscape: { width: 1920, height: 1080 }, // 16:9 — default
-  portrait: { width: 1080, height: 1920 }, // 9:16 — reels / shorts / TikTok
-  square: { width: 1080, height: 1080 }, // 1:1 — feed
-};
-
-export const DEFAULT_DIMENSIONS = ORIENTATION_PRESETS.landscape;
-
-function sane(w, h) {
-  return Number.isFinite(w) && Number.isFinite(h) && w >= 240 && h >= 240 && w <= 8192 && h <= 8192;
-}
-
-// Parse a STORYBOARD `format` global into { width, height, source }. Accepts
-// "WxH" (e.g. "1920x1080"; `x` or `×`, any inner spacing) or a named orientation;
-// falls back to landscape so a storyboard with a missing/garbled format still
-// renders (no behavior change vs the old landscape lock).
-export function parseFormat(format) {
-  const s = typeof format === "string" ? format.trim().toLowerCase() : "";
-  if (ORIENTATION_PRESETS[s]) return { ...ORIENTATION_PRESETS[s], source: `orientation=${s}` };
-  const m = s.match(/^(\d+)\s*[x×]\s*(\d+)$/);
-  if (m) {
-    const w = parseInt(m[1] ?? "", 10);
-    const h = parseInt(m[2] ?? "", 10);
-    if (sane(w, h)) return { width: w, height: h, source: "format" };
-  }
-  return { ...DEFAULT_DIMENSIONS, source: "default(landscape)" };
-}
-
-// Caption band geometry, derived from canvas height: the bottom ~16.67% (180px
-// at h=1080). Frame content must end `safetyPx` above the band top. Holds even
-// when captions are disabled (bottom-edge consistency).
-export const CAPTION_BAND_FRACTION = 0.1667;
-export function captionBand(height, safetyPx = 20) {
-  const h = Number.isFinite(height) ? height : DEFAULT_DIMENSIONS.height;
-  const bandHeight = Math.round(h * CAPTION_BAND_FRACTION);
-  const bandTopY = h - bandHeight; // foreground must end at/above this y
-  return { bandHeight, bandTopY, foregroundMaxY: bandTopY - safetyPx };
-}

package/skills/faceless-explainer/scripts/lib/frame-packets-core.mjs

@@ -1,194 +0,0 @@
-// Frame packets inline the storyboard frame, blueprint and cited recipes.
-// Workflow wrappers supply resource paths and workflow-specific sections.
-// The role combines the shared worker contract with the workflow delta.
-
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  realpathSync,
-  writeFileSync,
-} from "node:fs";
-import { basename, join, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
-
-export function field(block, name) {
-  const match = block.match(new RegExp(`^-\\s+${name}:\\s*(.+)$`, "im"));
-  return match?.[1]?.trim() ?? null;
-}
-
-export function splitFrames(storyboard) {
-  const matches = [...storyboard.matchAll(/^## Frame\s+([^\n]+)$/gm)];
-  return matches.map((match, index) => {
-    const start = match.index;
-    const end = matches[index + 1]?.index ?? storyboard.length;
-    return {
-      heading: match[1].trim(),
-      block: storyboard.slice(start, end).trim(),
-    };
-  });
-}
-
-export function frameId(frame) {
-  const src = field(frame.block, "src");
-  if (!src) throw new Error(`${frame.heading}: missing src`);
-  return basename(src).replace(/\.html?$/i, "");
-}
-
-export function selectedFile(path, heading) {
-  if (!path || !existsSync(path)) return "";
-  return `\n## ${heading}\n\n${readFileSync(path, "utf8").trim()}\n`;
-}
-
-function escapeRegExp(id) {
-  return id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-export function knownRuleIds(animationDir) {
-  const rulesDir = join(animationDir, "rules");
-  if (!existsSync(rulesDir)) {
-    console.warn(
-      `frame-packets: no rules dir at ${rulesDir} — packets will inline no motion recipes`,
-    );
-    return [];
-  }
-  return readdirSync(rulesDir)
-    .filter((name) => name.endsWith(".md"))
-    .map((name) => name.replace(/\.md$/, ""));
-}
-
-export function citedRules(block, ruleIds) {
-  const explicit = (field(block, "rules") ?? "")
-    .split(/[,\s]+/)
-    .map((rule) => rule.trim())
-    .filter(Boolean);
-  const mentioned = ruleIds.filter((id) =>
-    new RegExp(`(?<![\\w-])${escapeRegExp(id)}(?![\\w-])`, "i").test(block),
-  );
-  return [...new Set([...explicit, ...mentioned])].filter((id) => ruleIds.includes(id));
-}
-
-// visual-design.md tells the author to write the blueprint as `<id> (Reproduce)`
-// or `<id> (Adapt)` — the qualifier is direction for the frame worker, not part of
-// the filename. Parse the field into the id it names (or null for `compose`), so
-// no caller ever resolves a raw field value against the blueprints directory.
-export function blueprintId(block) {
-  const raw = field(block, "blueprint");
-  if (!raw) return null;
-  const id = raw.replace(/\s*\([^)]*\)\s*$/, "").trim();
-  return id && id.toLowerCase() !== "compose" ? id : null;
-}
-
-export function resourceSections(block, { animationDir, ruleIds, frameId }) {
-  let sections = "";
-  const blueprint = blueprintId(block);
-  if (blueprint) {
-    const blueprintsDir = join(animationDir, "blueprints");
-    const path = join(blueprintsDir, `${blueprint}.md`);
-    // An installed library must contain the named blueprint.
-    // An absent on-demand library warns, like missing motion rules.
-    if (!existsSync(blueprintsDir)) {
-      console.warn(
-        `frame-packets: no blueprints dir at ${blueprintsDir} — packets will inline no blueprint`,
-      );
-    } else if (!existsSync(path)) {
-      throw new Error(`${frameId ?? "frame"}: blueprint "${blueprint}" has no file at ${path}`);
-    } else {
-      sections += selectedFile(path, `Selected blueprint: ${blueprint}`);
-    }
-  }
-  for (const rule of citedRules(block, ruleIds)) {
-    sections += selectedFile(
-      join(animationDir, "rules", `${rule}.md`),
-      `Selected motion rule: ${rule}`,
-    );
-  }
-  return sections;
-}
-
-export function buildRolePayload({ corePath, deltaPath, outDir }) {
-  const core = readFileSync(corePath, "utf8").trim();
-  const delta = readFileSync(deltaPath, "utf8").trim();
-  const role = `${core}\n\n---\n\n${delta}\n`;
-  mkdirSync(outDir, { recursive: true });
-  const path = join(outDir, "_role.md");
-  writeFileSync(path, role);
-  return { path, bytes: Buffer.byteLength(role) };
-}
-
-export function buildFramePackets({
-  projectDir,
-  storyboardPath = join(projectDir, "STORYBOARD.md"),
-  outDir = join(projectDir, ".hyperframes", "frame-packets"),
-  maxPacketBytes = 48_000,
-  animationDir,
-  corePath,
-  deltaPath,
-  // Per-workflow hooks (all optional):
-  // designTruthLine(projectDir) -> the packet's design-truth input line
-  // validateFrame(frame, id)   -> throw to reject a frame before packing
-  // extraSections(block)       -> extra packet sections appended after the rule recipes
-  designTruthLine = (dir) => `- Design tokens: ${join(resolve(dir), "frame.md")}`,
-  validateFrame,
-  extraSections,
-}) {
-  const storyboard = readFileSync(storyboardPath, "utf8");
-  const frames = splitFrames(storyboard);
-  if (frames.length === 0) throw new Error("STORYBOARD.md has no frame blocks");
-  const ruleIds = knownRuleIds(animationDir);
-
-  const packets = frames.map((frame) => {
-    const id = frameId(frame);
-    if (validateFrame) validateFrame(frame, id);
-    const packet = `# Frame packet: ${id}\n\n## Project inputs\n\n- Project: ${resolve(projectDir)}\n${designTruthLine(projectDir)}\n- RULES_DIR: ${join(animationDir, "rules")}\n\n## Assigned storyboard block\n\n${frame.block}\n${resourceSections(frame.block, { animationDir, ruleIds, frameId: id })}${extraSections ? extraSections(frame.block) : ""}`;
-    const bytes = Buffer.byteLength(packet);
-    if (bytes > maxPacketBytes) {
-      throw new Error(`${id}: frame packet is ${bytes} bytes (limit ${maxPacketBytes})`);
-    }
-    return { frameId: id, path: join(outDir, `${id}.md`), bytes, packet };
-  });
-
-  mkdirSync(outDir, { recursive: true });
-  for (const { path, packet } of packets) writeFileSync(path, packet);
-  buildRolePayload({ corePath, deltaPath, outDir });
-  return packets.map(({ packet: _packet, ...result }) => result);
-}
-
-export function flag(argv, name, fallback) {
-  const index = argv.indexOf(`--${name}`);
-  return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
-}
-
-// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
-// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
-// a raw compare silently skips main() when invoked through any symlinked path.
-export function isMainModule(importMetaUrl) {
-  if (!process.argv[1]) return false;
-  try {
-    return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
-  } catch {
-    return false;
-  }
-}
-
-export function runCli({ buildFramePackets: build, buildRolePayload: buildRole }) {
-  const argv = process.argv.slice(2);
-  const projectDir = resolve(flag(argv, "project", "."));
-  const outDir = resolve(flag(argv, "out-dir", join(projectDir, ".hyperframes", "frame-packets")));
-  try {
-    const packets = build({
-      projectDir,
-      storyboardPath: resolve(flag(argv, "storyboard", join(projectDir, "STORYBOARD.md"))),
-      outDir,
-    });
-    const role = buildRole({ outDir });
-    console.log(`✓ frame packets: ${packets.length} bounded packet(s)`);
-    for (const packet of packets)
-      console.log(`  ${packet.frameId}: ${packet.bytes} bytes → ${packet.path}`);
-    console.log(`  worker role: ${role.bytes} bytes → ${role.path}`);
-  } catch (error) {
-    console.error(`✗ frame packets: ${error.message}`);
-    process.exit(1);
-  }
-}