hyperframes 0.8.184 → 0.8.185

package/dist/skills/hyperframes/references/route-briefs.md

@@ -1,11 +0,0 @@
-# Route briefs (moved)
-
-Each route's interview entry — must-haves, conditional questions, deferred asks,
-pitch-eligible fields, and whether the run-shape questions apply — now lives in that
-route's own file, together with its input/output/trigger contract:
-
-`references/routes/<workflow>.md` — e.g. `routes/faceless-explainer.md`,
-`routes/pr-to-video.md` (including the PR-size → length table).
-
-The interview procedure itself (the eight steps) is `references/intent-interview.md`.
-Field semantics and question rules: `hyperframes/references/brief-contract.md` § 2–3.

package/dist/skills/hyperframes/references/routes/embedded-captions.md

@@ -1,11 +0,0 @@
-# Route: embedded-captions
-
-- **Input:** Existing talking-head footage to caption. It is an actual media file, not a URL or creative brief.
-- **Output:** The same footage, untouched, with a caption layer and selected caption identity. The subject may occlude embedded captions. Any length.
-- **Triggers:** "add captions", "add subtitles", "captions behind the subject", "cinematic captions for my clip".
-
-## Interview
-
-- **Must-haves:** which clip (the input file).
-- **Deferred (announce):** the caption **identity** pick — its Step 0 probes the clip first, then shortlists 2–3 identities from the catalog and recommends one. Say that's coming.
-- **Run-shape:** neither — the footage is untouched; there is no storyboard to review.

package/dist/skills/hyperframes/references/routes/faceless-explainer.md

@@ -1,12 +0,0 @@
-# Route: faceless-explainer
-
-- **Input:** A topic, article, notes, or arbitrary text being explained, with no product being marketed and no website to capture.
-- **Output:** A faceless explainer MP4 with invented typography, abstract graphics, diagrams, or data visualization. Sweet spot 30–90s; hard cap about 3 minutes.
-- **Triggers:** "faceless explainer about X", "explain how DNS works as a video", "turn this article into an explainer".
-
-## Interview
-
-- **Must-haves:** **angle** — concept / how-to / listicle / narrative, recommend the one the text's own shape suggests · **length** — inside the 30–90s sweet spot, scaled to how much the text actually teaches · **destination** — YouTube / embed → 16:9 · X / LinkedIn / Instagram feed → 1:1 · Shorts / TikTok → 9:16.
-- **Conditional:** a pasted script adds **`VO_MODE`** — use it verbatim, or restructure per scene?
-- **Pitch round:** `message` + `angle` — five tellings of the same topic are five different videos.
-- **Run-shape:** both.

package/dist/skills/hyperframes/references/routes/general-video.md

@@ -1,12 +0,0 @@
-# Route: general-video
-
-- **Input:** Any custom creation or edit not covered by a specialized route: a static title card, longer brand or sizzle reel, multi-scene montage, static loop/poster, NLE-like footage remix, or freeform composition. It also executes every `flow: companion` brief.
-- **Output:** A HyperFrames composition of any length or format through design → plan → static layout → animation → check → approval → render.
-- **Triggers:** "make a static title card", "longer brand reel", "multi-scene composition", "static loop", "custom video", or any unmatched video request.
-
-## Interview
-
-- **Open-ended requests only:** first derive a one-sentence `message`. Ask `audience` only when it is unclear and would change the story or terminology. Ask `destination` only when it would change aspect or composition. Ask for a priority only when the brief contains a real trade-off. Default to one best version; ask about variations only when the user requests options or comparison.
-- **Specific requests:** a complete ask such as "a static title card with our logo for a website hero" needs no discovery questions.
-- **Pitch round:** `message` — the unformed open-ended request is this round's home case.
-- **Run-shape:** both questions apply. `/general-video` is also the companion host, so `flow: companion` stays on this route with the full toolbox.

package/dist/skills/hyperframes/references/routes/motion-graphics.md

@@ -1,11 +0,0 @@
-# Route: motion-graphics
-
-- **Input:** A short design-led unit, typically under 10s, with no narration, where motion is the message: kinetic type, stat/count-up, chart hit, logo sting, animated title, lower-third, map, tweet/headline/page highlight, or asset-fusion shot.
-- **Output:** A short MP4 or transparent alpha WebM/MOV overlay.
-- **Triggers:** "an 8s logo sting", "animate this stat", "kinetic-type intro", "animate this title", "transparent lower-third overlay".
-
-## Interview
-
-- Autonomous by design: at most **one** clarifying question, owned by its director step, in the flow. No must-haves here beyond confirming the input; route directly.
-- **Run-shape:** neither — the piece is seconds long; a storyboard and a companion session have nothing to add.
-- **Front-door capability offer:** skip it. The director's one-question limit is authoritative.

package/dist/skills/hyperframes/references/routes/music-to-video.md

@@ -1,12 +0,0 @@
-# Route: music-to-video
-
-- **Input:** A music track, a video whose audio becomes the track, or a track generated from a mood brief — with no narration or website capture. User images or videos are optional, so a complete video needs zero supplied assets.
-- **Output:** A beat-synced MP4 driven by a deterministic beat/energy map (`audiomap.json`). It may become a lyric video, slideshow, visualizer, or kinetic promo without changing pipelines.
-- **Triggers:** "make a video for this song", "beat-synced video", "lyric video", "music visualizer", "kinetic promo to this beat".
-
-## Interview
-
-- **Must-haves:** the **music source** — a track file, a video to pull audio from, or generate one from a mood description · **destination → aspect**.
-- **Deferred (announce):** brand (font + palette) and the genre feel are chosen at its Step 3 by design — they emerge from the track's analysis, not from a question up front.
-- **Pitch round:** `message` — the visual concept riding the beat grid (lyric treatment, montage story, kinetic type); brand and genre feel still land at Step 3.
-- **Run-shape:** both.

package/dist/skills/hyperframes/references/routes/pr-to-video.md

@@ -1,28 +0,0 @@
-# Route: pr-to-video
-
-- **Input:** A GitHub PR URL, `owner/repo#N`, or "this PR", read through `gh`; it is not a website capture request.
-- **Output:** A changelog, feature reveal, fix explainer, or refactor walkthrough with diff, before/after, file-tree, and impact scenes. Hard cap about 3 minutes; duration follows change size.
-- **Triggers:** "make a video about this PR", "turn PR #1187 into a changelog video", "release-notes video from this pull request".
-
-## Interview
-
-- **Must-haves:** the **PR reference** (URL, `owner/repo#N`, or "this PR") · **angle** — changelog / feature-reveal / fix-explainer / refactor-walkthrough, recommend the one the PR itself suggests · **audience** — developers (default) · mixed technical · non-technical stakeholders · **length** — from the size table below · **destination** — 16:9 is the default for a code explainer.
-- **Length comes from the PR's change size**, not a fixed guess — peek once, read-only (the workflow's Step 1 still does the full deterministic fetch):
-
-  ```bash
-  gh pr view <PR_REF> --json title,additions,deletions,changedFiles
-  ```
-
-  Pick the tier from `additions + deletions` (nudged up by `changedFiles`) and lead with it (hard cap ~3 min):
-
-  | PR change size                    | Recommended length |
-  | --------------------------------- | ------------------ |
-  | trivial (≲ 50 lines changed)      | ~20–40s            |
-  | focused (~50–200 lines)           | ~40–70s            |
-  | substantial (~200–600 lines)      | ~70–110s           |
-  | large (≳ 600 lines, or 25+ files) | ~110–180s          |
-
-  State the basis in one phrase ("~40s — small change, +44/−13 across 12 files"). The tier is a **ceiling** on how much story the diff can support, never a floor to fill: a one-headline story recommends inside 30–90s regardless of tier (the tier's range may still appear as a non-recommended fuller-walkthrough option).
-
-- **Pitch round:** `angle` and the opening hook — the diff fixes the facts, not the telling.
-- **Run-shape:** both.

package/dist/skills/hyperframes/references/routes/product-launch-video.md

@@ -1,13 +0,0 @@
-# Route: product-launch-video
-
-- **Input:** A website URL; a script or brief that names a site; or a product-launch script with no derivable site or an explicit "do not scrape" instruction. Capture website assets and brand tokens unless the brief selects no-capture mode. Ask whether supplied script copy is verbatim voice-over or may be restructured.
-- **Output:** A product promo, launch video, site tour, or showcase MP4. Sweet spot 30–90s; hard cap about 3 minutes. A show-it-as-is brief features captured screens rather than inventing a separate route.
-- **Triggers:** "launch video for X", "promo for our site", "turn this script into a 60s promo", "text-only launch video", "turn this website into a video", "site tour from this URL".
-
-## Interview
-
-- **First, sell or show?** One question when the request doesn't say: market the product (a promo), or show the site as-is (a tour / showcase)? A show-it answer is **intent, not a different pipeline**: write it into `BRIEF.md` (`## Intent` / `## Customizations` — "feature the site's own captured screens as the video's assets") and the workflow's normal steps carry it — the captured screens become the featured `asset_candidates`.
-- **Must-haves:** **angle** — story shapes from the site's / brief's own positioning, recommend one with its basis · **length** — 30–90s sweet spot, scaled to the material · **destination** — YouTube / embed → 16:9 · X / LinkedIn / Instagram feed → 1:1 · Shorts / TikTok → 9:16.
-- **Conditional:** a show-it-as-is ask adds **what to show** — the whole site, or specific pages/sections (into `BRIEF.md`'s body); a pasted script/brief adds **`VO_MODE`** (verbatim or restructured?); a script that only names a site adds **capture?** — crawl it for brand + assets (default), or text-only / "don't scrape" (no-capture mode, a preset supplies the design system).
-- **Pitch round:** `message` + `angle`, after sell-or-show is settled — the pitches inherit that intent.
-- **Run-shape:** both.

package/dist/skills/hyperframes/references/routes/remotion-to-hyperframes.md

@@ -1,9 +0,0 @@
-# Route: remotion-to-hyperframes
-
-- **Input:** Existing Remotion React source, only when the user explicitly asks to port, convert, or migrate it. A passing Remotion mention is not a trigger.
-- **Output:** A HyperFrames HTML composition translated from the source and compared with the Remotion render through the migration evaluation harness.
-- **Triggers:** "port my Remotion project", "convert this Remotion composition", "migrate from Remotion".
-
-## Interview
-
-- Not served by the intent layer — a migration with no brief. Route directly.

package/dist/skills/hyperframes/references/routes/slideshow.md

@@ -1,11 +0,0 @@
-# Route: slideshow
-
-- **Input:** A brief, outline, or existing page to author as a presentation, pitch deck, or interactive deck. If "slides", "deck", or "convert this page" is ambiguous, confirm that the user wants a HyperFrames slideshow before authoring.
-- **Output:** A runnable HyperFrames composition plus the JSON island used by `SlideshowController`: discrete slides, fragment reveals, branching, hotspots, presenter mode, and speaker notes. The deliverable is a navigable deck, not an MP4.
-- **Triggers:** "make a pitch deck", "interactive presentation", "convert this page into slides", "slideshow with presenter mode".
-
-## Interview
-
-- The one question is the routing confirmation itself — "do you want this as a HyperFrames slideshow?" — asked during triage (it survives every mode: wrong routing is a quality problem). The deck contract owns everything after.
-- **Run-shape:** neither — the deliverable is a navigable deck, not a rendered video.
-- **Front-door capability offer:** skip it. After route confirmation, the deck workflow owns all remaining choices.

package/dist/skills/hyperframes/references/routes/talking-head-recut.md

@@ -1,11 +0,0 @@
-# Route: talking-head-recut
-
-- **Input:** Existing talking-head, interview, or podcast footage to package. The underlying clip plays unchanged.
-- **Output:** The same footage with transcript-synced graphic-overlay cards: kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, or picture-in-picture. Any length.
-- **Triggers:** "package this video", "add graphic overlays to my talk", "add lower-thirds or data callouts to this interview".
-
-## Interview
-
-- **Must-haves:** which clip (the input file).
-- **Deferred (announce):** its render-strategy questions — aspect ratio, layout, style group, card count — stay at its Step 7, where the recommendations come from the probed footage and transcript. Say they're coming.
-- **Run-shape:** neither.

package/dist/skills/hyperframes/references/script-format.md

@@ -1,52 +0,0 @@
-# `SCRIPT.md` — locked narration (optional)
-
-The **locked narration** for a project: the final spoken lines + voice + delivery. It is an _optional_ plan-layer file — a video with no narration (bgm-only, silent overlay) has none. The storyboard's per-frame `voiceover` is the lighter, editable _guide_; `SCRIPT.md` is the _commit_. (Storyboard format → `references/storyboard-format.md`.)
-
-This file defines the SCRIPT.md **shape** only. Synthesizing the spoken lines into audio is a capability owned by `media-use` → `../../media-use/audio/references/tts.md`.
-
-Free-form markdown — there is no strict parser; the TTS step extracts the indented spoken lines.
-
-## Shape
-
-A header block, then one section per spoken line.
-
-| Part                            | Holds                                                                                                                                   |
-| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| Header                          | `**Voice:**` (provider + voice), `**Voice settings:**` (e.g. stability / similarity / style), `**Voice direction:**` (overall delivery) |
-| `## Line N — <label> (Frame N)` | one spoken line, tied to its storyboard frame                                                                                           |
-| `**Time:**`                     | the frame's rough window — a _guide_, not authoritative (real timing comes from TTS word timestamps)                                    |
-| `**Delivery:**`                 | per-line delivery note                                                                                                                  |
-| indented block                  | the **spoken text** — the only part fed to TTS                                                                                          |
-
-## Example
-
-```markdown
-# SCRIPT — acme-launch
-
-**Voice:** Rachel (ElevenLabs)
-**Voice settings:** stability 0.35 · similarity 0.75 · style 0.20
-**Voice direction:** Confident, warm, a little playful.
-
----
-
-## Line 1 — Hook (Frame 1)
-
-**Time:** 0.0 – 3.0s
-**Delivery:** Land the promise on the beat.
-
-    Ship a launch video in an afternoon.
-
-## Line 2 — The problem (Frame 2)
-
-**Time:** 3.0 – 7.0s
-**Delivery:** Wry, a touch tired.
-
-    The old way? Prompt, wait twenty minutes, get something that misses.
-```
-
-## To TTS
-
-Feed each line's spoken text to the provider documented in
-`media-use/audio/references/tts.md`. The `hyperframes tts` command is
-Kokoro-only; use its `--voice` flag, or use the bundled HeyGen helper when word
-timestamps are required. Real per-word timing replaces the `**Time:**` guides.

package/dist/skills/hyperframes/references/subagent-dispatch.md

@@ -1,35 +0,0 @@
-# Subagent dispatch — harness adapter
-
-The video workflows (`product-launch-video` / `faceless-explainer` / `pr-to-video` / `motion-graphics` / `general-video`) describe subagent dispatch in harness-neutral verbs. This file maps those verbs to the primitives of whatever agent harness you are running on. Read it once per run, before the first dispatch; everything else in the workflows (dispatch packets, file artifacts, exit-code gates, Resume tables) is harness-independent and needs no translation.
-
-## The contract (identical on every harness)
-
-- **DISPATCH(role_file, dispatch_context)** — start one child agent whose prompt is the **full contents of the named role file** (a builder-assembled payload like `.hyperframes/frame-packets/_role.md`, or a workflow's `sub-agents/<role>.md`) followed by the `## Dispatch context` block from the workflow, copied **verbatim** (never digested or paraphrased). Every harness below accepts arbitrary task text, so this works everywhere; never rely on the child seeing your conversation, memory, or skills — the prompt and the files on disk are its entire world.
-- **Parallel fan-out** — when a step says "start N workers in parallel", the workers are mutually independent (no ordering, no shared state beyond the filesystem). Run as many concurrently as your harness allows.
-- **WAIT** — a step's completion criterion is always **the expected artifact existing on disk** (e.g. `compositions/<scene-id>.html`), never the harness's completion notification (some harnesses deliver results best-effort). After waiting, verify the artifacts; a missing artifact means that child failed — re-dispatch it once with the same prompt before surfacing an error.
-
-## Concurrency cap → batching rule (cap never changes scope)
-
-A harness concurrency limit **reduces parallelism, not work**: every scene still gets built, with the available slots chewing through the full list. The workflow sets how many scenes each worker gets (`general-video` assigns 2–3).
-
-- When the harness queues excess children internally, submit **all N at once** and let the queue drain.
-- Harness hard-caps active children (e.g. OpenClaw `maxChildrenPerAgent`) → dispatch in **waves of the cap size**: start `cap` workers, wait for their artifacts, start the next wave, until all N scenes exist. Example: 9 scenes on a cap-3 harness = 3 waves of 3 — never drop scenes, never merge scenes into one worker to fit the cap.
-
-## Harness mapping
-
-Use the current harness's native delegation and waiting tools when they are available. The workflow contract stays the same:
-
-- **DISPATCH** sends the complete role file and dispatch context to one worker.
-- **Parallel fan-out** starts independent workers concurrently up to the harness limit.
-- **WAIT** verifies the expected artifacts on disk, not only a completion notification.
-- **Re-dispatch** starts a fresh worker with the same context plus the gate failure.
-
-When native delegation is unavailable, use the existing fallback ladder: launch headless CLI workers that share the project filesystem, then fall back to inline serial execution.
-
-On Codex, native delegation requires the user's explicit permission. Fold a one-line request into the workflow's first existing user pause before dispatch; a standing grant in `AGENTS.md` or the kickoff prompt also counts. Without it, use the fallback ladder rather than silently skipping work.
-
-## Vocabulary mapping
-
-- A request to work "in the background" means dispatch concurrently when the harness supports it.
-- Load a named skill through the harness's skill mechanism, or read `<skills-root>/<skill>/SKILL.md` directly.
-- Map generic read, write, edit, and shell verbs to the current harness's equivalent tools.

package/dist/skills/hyperframes/references/workflow-catalog.md

@@ -1,10 +0,0 @@
-# Workflow catalog (moved)
-
-Each workflow's input/output/trigger contract now lives in its own route file — one
-small read per candidate instead of a whole catalog:
-
-`references/routes/<workflow>.md` — e.g. `routes/product-launch-video.md`,
-`routes/general-video.md`, `routes/remotion-to-hyperframes.md`.
-
-The same file carries that route's interview entry (must-haves, conditionals, deferred
-asks, run-shape), so confirming a route is exactly one read.

package/dist/skills/hyperframes/scripts/lib/frame-packets-core.mjs

@@ -1,176 +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, writeFileSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
-
-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;
-}
-
-export { isMainModule } from "./main-module.mjs";
-
-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);
-  }
-}

package/dist/skills/media-use/audio/scripts/lib/host-audio.mjs

@@ -1,28 +0,0 @@
-// Audio the host app supplied survives every pass that rebuilds audio_meta.json from the storyboard: an entry
-// marked "source": "host" whose file exists. A frame the host scored takes no looked-up cue sound.
-/** The host's own entries in an earlier audio_meta.json, and why any other host-marked entry was dropped; `exists`
- *  resolves a path from the project root. A frame written as "1" is frame 1. */
-export function hostAudio(previous, exists) {
-  const marked = [[previous?.bgm, "path"], ...(previous?.sfx ?? []).map((s) => [s, "file"])].filter(
-    ([entry]) => entry?.source === "host",
-  );
-  const kept = new Set();
-  const dropped = [];
-  for (const [entry, key] of marked) {
-    const path = entry[key];
-    if (typeof path !== "string") dropped.push(`a host entry has no "${key}"`);
-    else if (!exists(path)) dropped.push(`${path} is not on disk`);
-    else kept.add(entry);
-  }
-  const bgm = kept.has(previous?.bgm) ? previous.bgm : null;
-  const sfx = (previous?.sfx ?? [])
-    .filter((s) => kept.has(s))
-    .map((s) => ({ ...s, frame: Number(s.frame) }));
-  return { bgm, sfx, frames: new Set(sfx.map((s) => s.frame)), dropped };
-}
-
-/** `rebuilt` with the host's bed and sounds put back; the host's bed wins over a looked-up one. */
-export function keepHostAudio(rebuilt, host) {
-  const looked = (rebuilt.sfx ?? []).filter((s) => !host.frames.has(s.frame));
-  return { ...rebuilt, bgm: host.bgm ?? rebuilt.bgm, sfx: [...host.sfx, ...looked] };
-}

package/dist/skills/media-use/audio/scripts/lib/host-audio.test.mjs

@@ -1,106 +0,0 @@
-import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
-import test from "node:test";
-import { hostAudio, keepHostAudio } from "./host-audio.mjs";
-
-const onDisk = new Set([
-  "assets/bgm/host.mp3",
-  "assets/sfx/custom-whoosh.mp3",
-  "assets/sfx/whoosh.mp3",
-]);
-const exists = (path) => onDisk.has(path);
-const hostWhoosh = {
-  frame: 1,
-  file: "assets/sfx/custom-whoosh.mp3",
-  offset_s: 0,
-  duration_s: 2,
-  source: "host",
-};
-
-test("a host sound and bed survive a rebuild, and the host's frame takes no looked-up sound", () => {
-  const previous = {
-    bgm: { path: "assets/bgm/host.mp3", source: "host" },
-    sfx: [hostWhoosh, { frame: 2, file: "assets/sfx/whoosh.mp3", offset_s: 0 }],
-  };
-  const rebuilt = {
-    bgm: null,
-    voices: [],
-    sfx: [
-      { frame: 1, file: "assets/sfx/whoosh.mp3", offset_s: 0 },
-      { frame: 2, file: "assets/sfx/whoosh.mp3", offset_s: 0 },
-    ],
-  };
-  const kept = keepHostAudio(rebuilt, hostAudio(previous, exists));
-  assert.deepEqual(kept.bgm, previous.bgm);
-  assert.deepEqual(kept.sfx, [hostWhoosh, rebuilt.sfx[1]]);
-});
-
-test("an unmarked entry or a missing file is not the host's", () => {
-  const previous = {
-    bgm: { path: "assets/bgm/gone.mp3", source: "host" },
-    sfx: [
-      { frame: 1, file: "assets/sfx/whoosh.mp3", offset_s: 0 },
-      { frame: 3, file: "assets/sfx/gone.mp3", source: "host" },
-    ],
-  };
-  const host = hostAudio(previous, exists);
-  assert.equal(host.bgm, null);
-  assert.deepEqual(host.sfx, []);
-  const rebuilt = { bgm: { path: "assets/bgm/looked.mp3" }, voices: [], sfx: [] };
-  assert.deepEqual(keepHostAudio(rebuilt, host), rebuilt);
-});
-
-test("no earlier audio_meta.json keeps the rebuild as it is", () => {
-  const rebuilt = { bgm: null, voices: [], sfx: [{ frame: 1, file: "assets/sfx/whoosh.mp3" }] };
-  assert.deepEqual(keepHostAudio(rebuilt, hostAudio(null, exists)), rebuilt);
-});
-
-// The narrated workflows tell the agent the same host-audio contract and the same meaning of silent.
-const workflowText = (skill, file) =>
-  readFileSync(new URL(`../../../../${skill}/${file}`, import.meta.url), "utf8");
-
-test("each narrated workflow tells a host app's music and sounds the way in, and when a film is silent", () => {
-  for (const skill of ["product-launch-video", "pr-to-video", "faceless-explainer"]) {
-    const steps = workflowText(skill, "SKILL.md");
-    assert.match(
-      steps,
-      /host app's own tools make the music or a sound effect[^\n]+"source": "host"/,
-      skill,
-    );
-    assert.match(steps, /"duration_s": <its length>[^\n]+Every audio pass keeps these/, skill);
-    assert.match(steps, /no `SCRIPT.md`, \*\*and\*\* no `sfx:` cues or host audio/, skill);
-    assert.match(
-      steps,
-      /marked silent \(`music: none`, no `SCRIPT.md`, no `sfx:` cues or host audio\)/,
-      skill,
-    );
-    assert.match(
-      workflowText(skill, "references/story-design.md"),
-      /no `SCRIPT.md` \+ no `sfx:` cues or host audio\*\* — the canonical/,
-      skill,
-    );
-  }
-});
-
-test("a frame written as a string is the same frame, and a gone host file is reported", () => {
-  const previous = {
-    bgm: { path: "assets/bgm/gone.mp3", source: "host" },
-    sfx: [{ ...hostWhoosh, frame: "1" }],
-  };
-  const host = hostAudio(previous, exists);
-  assert.deepEqual(host.sfx, [hostWhoosh]);
-  assert.ok(host.frames.has(1));
-  assert.deepEqual(host.dropped, ["assets/bgm/gone.mp3 is not on disk"]);
-  const rebuilt = { bgm: null, voices: [], sfx: [{ frame: 1, file: "assets/sfx/whoosh.mp3" }] };
-  assert.deepEqual(keepHostAudio(rebuilt, host).sfx, [hostWhoosh]);
-});
-
-test("a host entry with no path is reported, not thrown", () => {
-  const throwsOnNonString = (path) => {
-    if (typeof path !== "string") throw new TypeError("path must be a string");
-    return onDisk.has(path);
-  };
-  const host = hostAudio({ bgm: { src: "x.mp3", source: "host" }, sfx: [] }, throwsOnNonString);
-  assert.equal(host.bgm, null);
-  assert.deepEqual(host.dropped, ['a host entry has no "path"']);
-});