hyperframes 0.8.138 → 0.8.140

package/dist/{sherpa-WEQE23S5.js → sherpa-ZW6PWJS4.js}

@@ -21,42 +21,54 @@ import "./chunk-EOVYQ3IG.js";
 import {
   getPreparedWavDurationSeconds,
   prepareWav
-} from "./chunk-SIMYRD5P.js";
+} from "./chunk-F3SPK6SO.js";
+import {
+  emitWords
+} from "./chunk-6IHWCZ3W.js";
 import {
   stoppedByCancelSignal
-} from "./chunk-DJMXTKKK.js";
+} from "./chunk-LQG6GPVK.js";
 import "./chunk-6BEFEWFB.js";
 import "./chunk-PXSM4HPB.js";
 import "./chunk-WCJGTLPF.js";
 import "./chunk-TVCRUG2S.js";
 import "./chunk-AMKC3AXA.js";
-import "./chunk-7Y5SMPRV.js";
-import "./chunk-RLNB3JCY.js";
+import "./chunk-TPECLKPA.js";
+import "./chunk-6U3MN4HW.js";
+import "./chunk-A4KQZXZI.js";
+import "./chunk-USDEMXXL.js";
+import "./chunk-QP3BRKGF.js";
 import "./chunk-OZUQF4NB.js";
 import "./chunk-DPVXBVLL.js";
-import "./chunk-P5WDMFBB.js";
-import "./chunk-UINDCCO7.js";
+import "./chunk-B3I3XJ47.js";
 import "./chunk-VC76R6W2.js";
+import "./chunk-YA62XGXS.js";
 import "./chunk-OFQWTKPW.js";
+import "./chunk-T76PLPD6.js";
+import "./chunk-FXMKHHPO.js";
+import "./chunk-RQVDTPGD.js";
 import "./chunk-LAOCA3MQ.js";
 import "./chunk-LCSMOLGX.js";
 import "./chunk-TWWSYAKJ.js";
-import "./chunk-STA43FMY.js";
+import "./chunk-WY5OODN5.js";
+import "./chunk-24OWOBQH.js";
+import "./chunk-JFKL3WAE.js";
 import "./chunk-HBBJFK6I.js";
 import "./chunk-PJ3HDUCY.js";
 import "./chunk-TQFG7HTI.js";
 import "./chunk-GK4AIFIH.js";
 import "./chunk-2PSPARWP.js";
+import "./chunk-PMRBLBUP.js";
 import {
   PARAKEET_MODEL_LABEL,
   SHERPA_ERROR_PREFIX,
   SHERPA_RESULT_PREFIX,
+  SHERPA_WINDOW_PREFIX,
   mergeWindowsToWords,
   writeParakeetTranscript
-} from "./chunk-S3S2LSZX.js";
+} from "./chunk-KDPYVTEU.js";
+import "./chunk-UOFAE5RF.js";
 import "./chunk-3GXQPCJC.js";
-import "./chunk-RQVDTPGD.js";
-import "./chunk-PMRBLBUP.js";
 import "./chunk-M2WBOQ2Q.js";
 
 // src/whisper/sherpa.ts
@@ -65,6 +77,7 @@ import { createHash, randomUUID } from "crypto";
 import { createReadStream, mkdirSync, renameSync, rmSync, statSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
+import { createInterface } from "readline";
 import { fileURLToPath } from "url";
 var RUNTIME = "sherpa-onnx-node";
 var RUNTIME_VERSION = PINNED_PACKAGES[RUNTIME];
@@ -315,13 +328,13 @@ function failureReason(err, stderr) {
   if (!why) return how;
   return `${how}: ${bounded(why)}`;
 }
-function decode(wavPath, runtimePath, signal) {
+function decode(wavPath, runtimePath, signal, onWindow) {
   const sourceMode = import.meta.url.endsWith(".ts");
   const worker = new URL(sourceMode ? "./sherpaWorker.ts" : "./sherpaWorker.js", import.meta.url);
   const args = [...sourceMode ? ["--import", "tsx"] : [], fileURLToPath(worker)];
   const input = { wavPath, runtimePath, config: recognizerConfig() };
   return new Promise((resolve, reject) => {
-    execFile(
+    const child = execFile(
       process.execPath,
       args,
       {
@@ -340,6 +353,18 @@ function decode(wavPath, runtimePath, signal) {
         else reject(new Error(`Parakeet decoder ${failureReason(err, stderr)}`));
       }
     );
+    if (onWindow && child.stdout) {
+      createInterface({ input: child.stdout }).on("line", (l) => {
+        if (!l.startsWith(SHERPA_WINDOW_PREFIX)) return;
+        let streamed;
+        try {
+          streamed = JSON.parse(l.slice(SHERPA_WINDOW_PREFIX.length));
+        } catch {
+          return;
+        }
+        onWindow(streamed.window, streamed.through);
+      });
+    }
   });
 }
 function prepareSherpaWav(inputPath, onProgress) {
@@ -358,7 +383,8 @@ async function transcribeWithSherpa(wavPath, dir, options) {
     type: "progress",
     phase: "transcription",
     model: PARAKEET_MODEL_LABEL,
-    status: "started"
+    status: "started",
+    durationSeconds: getPreparedWavDurationSeconds(wavPath)
   });
   if (options.signal.aborted) throw new DecodeCancelled("Transcription cancelled");
   const selected = await selectRuntime(
@@ -372,7 +398,13 @@ async function transcribeWithSherpa(wavPath, dir, options) {
       `Parakeet runtime does not load (${selected.error}). Run hyperframes models install parakeet to repair it, or use --engine whisper.`
     );
   }
-  const windows = await decode(wavPath, selected.path, options.signal);
+  const onEvent = options.onEvent;
+  const windows = await decode(
+    wavPath,
+    selected.path,
+    options.signal,
+    onEvent && ((window, through) => emitWords(onEvent, PARAKEET_MODEL_LABEL, mergeWindowsToWords([window]), through))
+  );
   const result = writeParakeetTranscript(dir, mergeWindowsToWords(windows));
   options.onEvent?.({
     type: "progress",

package/dist/sherpaWorker.js

@@ -7,10 +7,14 @@ var __dirname = __hf_dirname(__filename);
 import {
   SHERPA_ERROR_PREFIX,
   SHERPA_RESULT_PREFIX,
+  SHERPA_WINDOW_PREFIX,
   droppedSpeechGaps,
   silenceCuts,
   spliceGap
-} from "./chunk-S3S2LSZX.js";
+} from "./chunk-KDPYVTEU.js";
+import {
+  readWav
+} from "./chunk-UOFAE5RF.js";
 import "./chunk-M2WBOQ2Q.js";
 
 // src/whisper/sherpaWorker.ts
@@ -32,7 +36,7 @@ function decodeWindow(recognizer, wave, padSeconds = 0) {
 try {
   const sherpa = createRequire(import.meta.url)(runtimePath);
   const recognizer = new sherpa.OfflineRecognizer(config);
-  const wave = sherpa.readWave(wavPath);
+  const wave = readWav(wavPath);
   const cuts = silenceCuts(wave.samples, wave.sampleRate);
   const windows = [];
   for (let k = 0; k + 1 < cuts.length; k++) {
@@ -60,7 +64,11 @@ try {
       const retry = decodeWindow(recognizer, slice, RETRY_PAD_SECONDS);
       if (retry.tokens.length > decoded.tokens.length) decoded = retry;
     }
-    windows.push({ offset: cuts[k] / wave.sampleRate, ...decoded });
+    const window = { offset: cuts[k] / wave.sampleRate, ...decoded };
+    windows.push(window);
+    const through = cuts[k + 1] / wave.sampleRate;
+    process.stdout.write(`${SHERPA_WINDOW_PREFIX}${JSON.stringify({ window, through })}
+`);
   }
   process.stdout.write(`${SHERPA_RESULT_PREFIX}${JSON.stringify(windows)}
 `);

package/dist/skills/hyperframes/references/capability-menu.md

@@ -12,7 +12,7 @@ Each row's last column reads **home → entry → what you get**: the owning ski
 | **Website capture** — headless-Chrome crawl of a real site: screenshots, brand tokens, assets                                                          | "I can capture your site and build from its real look"                                                        | CLI → `npx hyperframes capture <URL> -o ./capture` → `capture/` (screenshots, extracted tokens/text/assets); doctrine: `/product-launch-video`                                                                                                                                                                                                  |
 | **Beat analysis & audio-reactive motion** — a deterministic beat / energy map of a track; cuts land on the grid, elements pulse with the music         | "if there's music, I can cut the video to its beat — and make elements move with it"                          | grid: `/music-to-video` → `scripts/analyze-beatgrid.py` → `audiomap.json` (beats, energy, sections); element reaction: `/hyperframes-creative` → `references/audio-reactive.md` + `scripts/extract-audio-data.py`                                                                                                                               |
 | **Motion blueprints** — proven scene shapes (reveals, counters, charts, dioramas) picked per beat                                                      | "each scene gets a proven motion treatment, not improvised movement"                                          | `/hyperframes-animation` → `blueprints-index.md` + `rules-index.md` → per-beat `blueprint:` ids the build reads                                                                                                                                                                                                                                 |
-| **Voice, music, SFX, images, logos, media treatments** — resolved media plus source-aware color, effects, privacy, reveals, and justified overlays     | "narration, music, sound effects, real assets — and footage polished or stylized to fit the story"            | `/media-use` → deterministic resolve/operate tools plus `references/media-treatments.md`; shader pixels persist through `hyperframes media-treatment`, optional overlays come from Registry, and finite motion uses the host GSAP timeline                                                                                                      |
+| **Voice, music, SFX, images, logos, media treatments** — resolved media plus source-aware color, effects, privacy, reveals, and justified overlays     | "narration, music, sound effects, real assets — and footage polished or stylized to fit the story"            | `/media-use` (a host app's own music and sound-effect tools come first for those) → deterministic resolve/operate tools plus `references/media-treatments.md`; shader pixels persist through `hyperframes media-treatment`, optional overlays come from Registry, and finite motion uses the host GSAP timeline                                 |
 | **Generative video** — an AI presenter delivers the script; a still photo becomes a talking clip; a finished video gets dubbed into another language   | "an AI presenter can read your script on camera; I can animate a photo into a talking clip, or dub the video" | `/media-use` → `references/operations.md` § Generate: video (`heygen video create` / `video-translate`; OAuth free allowance where eligible) → an mp4 clip adopted into `assets/` + manifest record                                                                                                                                             |
 | **Transcription & captions** — word-timed transcripts; styled caption skins on the finished video                                                      | "accurate captions, styled to match"                                                                          | `/media-use` → `scripts/transcribe.mjs` → word-timed transcript; caption machinery `captions.mjs` (home: `/faceless-explainer`) → the caption track                                                                                                                                                                                             |
 | **Cut footage by its transcript** — trim a clip by choosing sentences, not timecodes                                                                   | "I can trim your clip by picking the sentences to keep"                                                       | `/media-use` → `scripts/transcript-cut.mjs` → the trimmed clip + updated transcript                                                                                                                                                                                                                                                             |

package/dist/skills/hyperframes-cli/SKILL.md

@@ -142,6 +142,11 @@ npx hyperframes feedback --rating <0-10> --comment "<specific result or friction
 
 Keep clean-run feedback concise. For any bug or friction, capture a **reproduction packet** before submitting; do not send only a symptom summary. Include the rerunnable command (relative to the project directory — feedback is submitted to a public channel, so do **not** paste absolute paths, home-directory prefixes, or user/machine identifiers), expected versus actual behavior, exact error (also strip absolute paths from stack traces — keep basename + line, drop the leading directory), whether output completed/fell back/failed, workaround, and repro-project status. For a rating ≤ 7 that describes a visual defect (black frame, flicker, corrupt output, wrong frame, blank output, other visual anomaly), also include a `COMPOSITION_STRUCTURE:` block — a privacy-preserving structural anatomy (element census + attribute presence + timeline shape) so maintainers can pattern-match against known bug families without the composition ZIP. Agents auto-fill this via the composition-census helper; the human user does not fill it by hand. If the issue did not reproduce again, say so and still include the last failing command and logs. Use `--file-issue` only with consent: it publishes a minimal reproduction to a public URL. The required packet format and privacy warning live in `references/preview-render.md`.
 
+Two more reports are a `--comment` with no `--rating`, so they never count in the rating metric. Send them unless telemetry is disabled or the user opted out, under the same privacy rules:
+
+- **Missing feature.** Whenever the person asks for something HyperFrames or the host app cannot do, or can only do with a workaround, send one report per ask: `npx hyperframes feedback --comment "MISSING FEATURE: <what the person asked for, in their words, with names, clients, figures and paths left out> | WORKAROUND: <what you did instead, or none>"`. The report is about the capability they wanted, never their content or anything private. A catalog search that found nothing goes to `--search-miss` instead.
+- **Host app.** When `HYPERFRAMES_CLIENT` is set, the CLI is running inside a host app. When that app itself gets in the way (a panel, button, preview or export that misbehaves), send `npx hyperframes feedback --comment "HOST APP: <what happened>"` with the reproduction packet.
+
 ## Read the matching reference before running a command
 
 The following references and owning skills are mandatory command contracts, not optional background reading. Before running a command in the table, read its matching row.

package/dist/skills/hyperframes-cli/references/lint-validate-inspect.md

@@ -50,7 +50,7 @@ One command, one Chrome boot. `check` runs the linter first and skips the browse
 
 Every finding carries a selector, the element's `data-*` identity, the composition source file, a bbox, and the sample time: jump straight from the JSON to the HTML you must edit and re-run.
 
-**Severity is persistence-aware.** A dynamic issue observed at a single grid sample (an entrance/exit transient) demotes to info and never gates. Issues held across samples gate the exit code, a held `content_overlap` is an error, and a held, partially-visible `canvas_overflow` breaching ≥5% of the canvas promotes to warning. Coordinate-frame findings (`escaped_container`, `panel_out_of_canvas`, `connector_detached`) flag geometry computed in one frame but rendered in another — an element far outside its offset parent, a painted panel stuck across the canvas edge, a connector line detached from every node. Text drawn into a `<canvas>` has no DOM box, so `canvas_overflow` cannot see it; `canvas_content_at_edge` warns when a canvas's pixels show sharp content (drawn text, hard shapes) along the frame edge — mark intentional full-bleed art (particles, photos) with `data-layout-allow-overflow`. If a 3s+ composition shows zero geometry change across every sample, `check` fails with `sweep_static`: a frozen timeline makes every green verdict unreliable, so it refuses to pass. The fingerprint includes per-element opacity, so opacity-only reveals (code typing, staggered fades) count as motion — but only while they're still in flight at the sampled times. The classic trap is a reveal that completes early and then holds a static frame for the rest of the duration: every sample lands on the settled state and the run fails. Spread the reveal across the timeline or keep one continuously animated element alive (a blinking caret is idiomatic for code typing) — don't bolt on a slow position drift just to appease the check.
+**Severity is persistence-aware.** A dynamic issue observed at a single grid sample (an entrance/exit transient) demotes to info and never gates. Issues held across samples gate the exit code, a held `content_overlap` is an error, and a held, partially-visible `canvas_overflow` breaching ≥5% of the canvas promotes to warning. Coordinate-frame findings (`escaped_container`, `panel_out_of_canvas`, `connector_detached`) flag geometry computed in one frame but rendered in another — an element far outside its offset parent, a painted panel stuck across the canvas edge, a connector line detached from every node. Text drawn into a `<canvas>` has no DOM box, so `canvas_overflow` cannot see it; `canvas_content_at_edge` warns when a canvas's pixels show sharp content (drawn text, hard shapes) along the frame edge — mark intentional full-bleed art (particles, photos) with `data-layout-allow-overflow`. If a 3s+ composition shows no visible change across every sample, `check` fails with `sweep_static`: a frozen timeline makes every green verdict unreliable, so it refuses to pass. When only audio advanced, it warns instead; a composition meant to be still takes `data-no-timeline` on its root. The fingerprint includes per-element opacity, so opacity-only reveals (code typing, staggered fades) count as motion — but only while they're still in flight at the sampled times. The classic trap is a reveal that completes early and then holds a static frame for the rest of the duration: every sample lands on the settled state and the run fails. Spread the reveal across the timeline or keep one continuously animated element alive (a blinking caret is idiomatic for code typing) — don't bolt on a slow position drift just to appease the check.
 
 **Escape hatches** (mark intent in the HTML, then re-run):
 

package/dist/skills/hyperframes-cli/references/preview-render.md

@@ -157,7 +157,7 @@ npx hyperframes feedback --rating 10                              # clean run, n
 npx hyperframes feedback --rating 6 --comment "bg <video> renders grey in multi-scene; worked around with --format png-sequence"
 ```
 
-`--rating` is an integer from 0-10 (required); `--comment` is free text. Feedback is anonymous and attaches a `doctorSummary` (OS/Node/CPU/mem/ffmpeg) automatically, so don't repeat those fields. A clean run needs only a short result. Before sending any bug, workaround, or confusing behavior, collect this compact reproduction packet:
+`--rating` is an integer from 0-10; `--comment` is free text. A `--comment` with no `--rating` is a ratingless report (`MISSING FEATURE:` and `HOST APP:` in `SKILL.md`) that never counts in the rating metric. Feedback is anonymous and attaches a `doctorSummary` (OS/Node/CPU/mem/ffmpeg) automatically, so don't repeat those fields. A clean run needs only a short result. Before sending any bug, workaround, or confusing behavior, collect this compact reproduction packet:
 
 ```text
 REPRO COMMAND: <HF_*/PRODUCER_* env> npx hyperframes <exact command>   # run from the project directory; do NOT paste absolute paths

package/dist/skills/media-use/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: media-use
-description: Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal.
+description: Agent Media OS for a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal. When the host app provides its own music or sound-effect tools, use those for music and sound effects; `resolve --type bgm|sfx` needs the heygen CLI.
 ---
 
 **Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
@@ -9,7 +9,9 @@ description: Agent Media OS, the single skill for every media need in a HyperFra
 
 The media OS for HyperFrames: resolve · generate · operate · remember — every media type, one skill, zero context noise.
 
-First run: install and sign in to the `heygen` CLI (the free-usage path), then verify with `npx hyperframes media-use resolve --doctor`. Setup and providers: `references/setup-providers.md`.
+First run, when you will use HeyGen media (catalog search, TTS, avatar video): install and sign in to the `heygen` CLI (the free-usage path), then verify with `npx hyperframes media-use resolve --doctor`. Setup and providers: `references/setup-providers.md`.
+
+Music and sound effects inside a host app: when the app you run in gives you its own music or sound-effect tools, use those. `resolve --type bgm` and `--type sfx` search the HeyGen catalog through the `heygen` CLI; without it they fail and say so (`sfx` still answers from its bundled library).
 
 Before generating a voiceover or an avatar video, tell the person: signing in to the heygen CLI with OAuth (`heygen auth login --oauth`) gives a free allowance for TTS voiceover and avatar videos, while an API key bills API credits.
 
@@ -23,8 +25,8 @@ Returns one line: `resolved <id> → <path> (<type>, <metadata>)`. All search no
 
 | Type    | One-line intent                                                                  |
 | ------- | -------------------------------------------------------------------------------- |
-| `bgm`   | background music (HeyGen catalog, 10k+ tracks)                                   |
-| `sfx`   | sound effects (bundled 19-file library + catalog)                                |
+| `bgm`   | background music (HeyGen catalog via the `heygen` CLI, 10k+ tracks)              |
+| `sfx`   | sound effects (bundled 19-file library + catalog via the `heygen` CLI)           |
 | `image` | photos, backgrounds (HeyGen asset search, 75k+ vectors)                          |
 | `icon`  | icons, symbols (transparent)                                                     |
 | `logo`  | official brand marks (theSVG → GitHub avatar → favicon; never redrawn)           |

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

@@ -0,0 +1,28 @@
+// 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

@@ -0,0 +1,106 @@
+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"']);
+});

package/dist/skills/media-use/references/setup-providers.md

@@ -19,7 +19,8 @@ npx hyperframes media-use resolve --doctor
 
 media-use holds no keys; every external tool owns its auth. Generation is
 centered on the HeyGen CLI free-usage path. Install and authenticate `heygen`
-before resolving bgm/sfx/image/icon/voice/avatar-video. Local tools are opt-in
+before resolving bgm/sfx/image/icon/voice/avatar-video; music and sound effects from
+a host app's own tools need none of it. Local tools are opt-in
 alternatives where they exist: mflux for image, Kokoro for voice, Parakeet for
 transcription, and LTX for local video generation. `resolve` spec-checks
 AVAILABLE RAM for those local ladders (`describeModelLadder`); the agent can
@@ -27,7 +28,7 @@ see the ladder and override.
 
 | Type      | Provider / path                                                                                                                                                               |
 | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| bgm/sfx   | heygen catalog free-usage path                                                                                                                                                |
+| bgm/sfx   | heygen catalog free-usage path; a host app's own music and sound tools come first                                                                                             |
 | image     | heygen search free-usage path; optional local mflux; codex `image_gen` upsell                                                                                                 |
 | voice     | heygen tts free-usage path; optional local **Kokoro** (free, on-device)                                                                                                       |
 | icon      | heygen asset search free-usage path                                                                                                                                           |

package/dist/skills/media-use/scripts/lib/heygen-cli.mjs

@@ -68,7 +68,11 @@ function classifyHeygenErrorResult(err) {
   }
 
   const version = firstSemver(text);
-  if (version && versionLessThan(version, HEYGEN_MIN_VERSION)) {
+  // A CLI older than the --headers flag rejects it before printing any version.
+  if (
+    (version && versionLessThan(version, HEYGEN_MIN_VERSION)) ||
+    lower.includes("unknown flag: --headers")
+  ) {
     return { code: "outdated", message: HEYGEN_OUTDATED_MESSAGE };
   }
 
@@ -98,6 +102,22 @@ const pendingFailureTracking = new Set();
 // API, move this state into a per-resolve context before reusing that path.
 let pendingRemediation = null;
 
+const TOOL_WORDS = { bgm: "music", sfx: "sound-effect" };
+
+/** A music or sound-effect resolve miss after the heygen CLI was missing or too old: what is missing, the host
+ * app's own tool, the fix. Other types keep the generic miss. */
+export function heygenMiss(type, { code }) {
+  const tool = TOOL_WORDS[type];
+  if (!tool) return null;
+  const outdated = code === "outdated";
+  const state = outdated ? `older than v${HEYGEN_MIN_VERSION}` : "not installed";
+  return {
+    code: outdated ? "heygen_cli_outdated" : "heygen_cli_missing",
+    fix: outdated ? HEYGEN_UPDATE_COMMAND : HEYGEN_INSTALL_COMMAND,
+    error: `${type} needs the heygen CLI, which is ${state}: use your host app's own ${tool} tool if it has one, or ${outdated ? "update" : "install"} the CLI.`,
+  };
+}
+
 export function consumeHeygenRemediation() {
   const remediation = pendingRemediation;
   pendingRemediation = null;

package/dist/skills/media-use/scripts/lib/heygen-cli.test.mjs

@@ -9,6 +9,7 @@ import {
   HEYGEN_NOT_AUTHENTICATED_MESSAGE,
   HEYGEN_NOT_FOUND_MESSAGE,
   HEYGEN_OUTDATED_MESSAGE,
+  heygenMiss,
   reportHeygenFailure,
 } from "./heygen-cli.mjs";
 
@@ -299,3 +300,16 @@ test("flushHeygenFailureTracking waits for a pending report before resolving", a
 test("flushHeygenFailureTracking resolves immediately when nothing is pending", async () => {
   await flushHeygenFailureTracking();
 });
+
+test("only a music or sound-effect miss names the heygen CLI and the host app's own tool", () => {
+  for (const type of ["image", "icon", "voice", "video"])
+    assert.equal(heygenMiss(type, { code: "not_found" }), null, type);
+  assert.equal(heygenMiss("bgm", { code: "not_found" }).code, "heygen_cli_missing");
+  const sfx = heygenMiss("sfx", { code: "outdated" });
+  assert.equal(sfx.code, "heygen_cli_outdated");
+  assert.match(sfx.error, /host app's own sound-effect tool/);
+});
+
+test("a CLI that rejects --headers without printing a version is outdated", () => {
+  assert.equal(classifyHeygenErrorCode({ stderr: "Error: unknown flag: --headers" }), "outdated");
+});

package/dist/skills/media-use/scripts/resolve.mjs

@@ -49,6 +49,7 @@ import {
   HEYGEN_MIN_VERSION,
   HEYGEN_UPDATE_COMMAND,
   consumeHeygenRemediation,
+  heygenMiss,
   firstSemver,
   flushHeygenFailureTracking,
   versionLessThan,
@@ -530,10 +531,16 @@ async function run() {
     });
     // brand stays local: no frame.md/design.md -> upsell the HyperFrames design
     // flow rather than reporting a generic miss (B5).
-    const msg =
+    const ownFailure =
       providerFailure instanceof BundledSfxAssetsError ||
-      providerFailure instanceof FfBinarySettingError
-        ? providerFailure.message
+      providerFailure instanceof FfBinarySettingError;
+    const heygen = consumeHeygenRemediation();
+    const miss = heygen && !ownFailure ? heygenMiss(type, heygen) : null;
+    const typed = providerFailure instanceof BundledSfxAssetsError ? providerFailure : miss;
+    const msg = ownFailure
+      ? providerFailure.message
+      : miss
+        ? miss.error
         : type === "brand"
           ? "no brand spec found — add a frame.md or design.md (colors/font/logo) to this project. Run the HyperFrames design flow to create one; brand tokens are read locally for deterministic rendering."
           : args.provider
@@ -543,9 +550,7 @@ async function run() {
       console.log(
         JSON.stringify({
           ok: false,
-          ...(providerFailure instanceof BundledSfxAssetsError
-            ? { code: providerFailure.code, fix: providerFailure.fix }
-            : {}),
+          ...(typed ? { code: typed.code, fix: typed.fix } : {}),
           error: msg,
         }),
       );

package/dist/{skills-BVONI6TC.js → skills-VKZAX5AS.js}

@@ -7,21 +7,18 @@ var __dirname = __hf_dirname(__filename);
 import {
   buildNpxCommand
 } from "./chunk-6BEFEWFB.js";
-import {
-  R
-} from "./chunk-WMQNIQDJ.js";
 import {
   trackSkillsInstallSkipped
-} from "./chunk-WH6PRFNX.js";
-import "./chunk-VR5UQWGV.js";
+} from "./chunk-JSGANFFH.js";
+import "./chunk-C2JUHIG5.js";
 import {
   diag
 } from "./chunk-VWG7OQKU.js";
-import {
-  c
-} from "./chunk-ZTZA4UWZ.js";
-import "./chunk-MIOBYUXT.js";
+import "./chunk-GQJZORQP.js";
 import "./chunk-AMKC3AXA.js";
+import {
+  R
+} from "./chunk-WMQNIQDJ.js";
 import {
   defineCommand
 } from "./chunk-S3S4TGEH.js";
@@ -30,21 +27,9 @@ import {
   CliResultSignal,
   setCommandExitCode
 } from "./chunk-PBN6GBJE.js";
-import "./chunk-7Y5SMPRV.js";
-import "./chunk-RLNB3JCY.js";
-import "./chunk-OZUQF4NB.js";
-import "./chunk-DPVXBVLL.js";
-import "./chunk-P5WDMFBB.js";
-import "./chunk-UINDCCO7.js";
-import "./chunk-VC76R6W2.js";
-import "./chunk-OFQWTKPW.js";
-import "./chunk-TWWSYAKJ.js";
-import "./chunk-STA43FMY.js";
-import "./chunk-HBBJFK6I.js";
-import "./chunk-PJ3HDUCY.js";
-import "./chunk-TQFG7HTI.js";
-import "./chunk-GK4AIFIH.js";
-import "./chunk-2PSPARWP.js";
+import "./chunk-USDEMXXL.js";
+import "./chunk-T76PLPD6.js";
+import "./chunk-FXMKHHPO.js";
 import {
   FALLBACK_CORE_SKILLS,
   SKILLS_CLI_LOCK_PATHS_VERIFIED_AT,
@@ -54,19 +39,19 @@ import {
   isCoreSkill,
   presentSkills,
   pruneOrphanedLockEntries
-} from "./chunk-APMG37MX.js";
+} from "./chunk-IFY57LUW.js";
 import {
   withMeta
-} from "./chunk-YNBXJWSD.js";
+} from "./chunk-DDQ4LOML.js";
 import "./chunk-K4WIOZFP.js";
 import "./chunk-XUXGIA7H.js";
 import "./chunk-WERLJGIC.js";
 import "./chunk-ISN5GRYI.js";
-import "./chunk-P75OFLZN.js";
+import "./chunk-MUINFURL.js";
 import "./chunk-KNU5COPB.js";
-import "./chunk-3GXQPCJC.js";
-import "./chunk-RQVDTPGD.js";
-import "./chunk-PMRBLBUP.js";
+import {
+  c
+} from "./chunk-ZTZA4UWZ.js";
 import "./chunk-M2WBOQ2Q.js";
 
 // src/commands/skills.ts

package/dist/{skillsUpdateCheck-KKDPTFM7.js → skillsUpdateCheck-PAY2OPDE.js}

@@ -9,13 +9,13 @@ import {
   printSkillsUpdateNotice,
   refreshSkillsCache,
   skillsCheckDue
-} from "./chunk-APMG37MX.js";
-import "./chunk-YNBXJWSD.js";
+} from "./chunk-IFY57LUW.js";
+import "./chunk-DDQ4LOML.js";
 import "./chunk-K4WIOZFP.js";
 import "./chunk-XUXGIA7H.js";
 import "./chunk-WERLJGIC.js";
 import "./chunk-ISN5GRYI.js";
-import "./chunk-P75OFLZN.js";
+import "./chunk-MUINFURL.js";
 import "./chunk-KNU5COPB.js";
 import "./chunk-M2WBOQ2Q.js";
 export {