hyperframes 0.8.142 → 0.8.143

package/dist/{render-X3NFNVEQ.js → render-TSE75QUL.js}

@@ -6,21 +6,21 @@ var __filename = __hf_fileURLToPath(import.meta.url);
 var __dirname = __hf_dirname(__filename);
 import {
   maybePromptRenderFeedback
-} from "./chunk-JU6Y5TTZ.js";
+} from "./chunk-3NE7ZYU2.js";
 import {
   reportVariableIssues,
   resolveVariablesArg,
   validateVariablesAgainstProject
-} from "./chunk-6UYZB4TY.js";
+} from "./chunk-LW6HO6U3.js";
 import {
   loadProducer
-} from "./chunk-XTLBLWOV.js";
+} from "./chunk-QVYVUCWD.js";
 import {
   formatLintStartupMessage
 } from "./chunk-6CSYCFQV.js";
 import {
   resolveProject
-} from "./chunk-LJAU4TPS.js";
+} from "./chunk-VIVBA6E6.js";
 import {
   renderJobObservabilityTelemetryPayload
 } from "./chunk-VXVRPIJA.js";
@@ -32,8 +32,8 @@ import {
   resolveCompositionEntryArg,
   resolveDefaultFpsArg,
   windowsChromeCrashRemediation
-} from "./chunk-TY6XOHEM.js";
-import "./chunk-YEIFI443.js";
+} from "./chunk-P7THMINS.js";
+import "./chunk-WPNE5NEP.js";
 import {
   desktopHint
 } from "./chunk-EDUBJPGL.js";
@@ -44,29 +44,29 @@ import {
   formatRenderSummaryDetail,
   formatScreenshotFallbackHint,
   resolvePrintedCaptureMode
-} from "./chunk-IHFUKJOR.js";
+} from "./chunk-K2FLNJVB.js";
 import "./chunk-DCAI5DBR.js";
 import "./chunk-EOVYQ3IG.js";
 import {
   runEnvironmentChecks
 } from "./chunk-KOEWEFHK.js";
-import "./chunk-PFCFR3KZ.js";
+import "./chunk-442JNXRM.js";
 import {
   createRenderCancellationScope
-} from "./chunk-FWRNQOLT.js";
+} from "./chunk-UICWP23D.js";
 import {
   loadProjectConfig,
   readProjectConfigWithStatus,
   seedProjectAuthoringSkill
-} from "./chunk-EFDXGAAD.js";
+} from "./chunk-2LBBHMKT.js";
 import "./chunk-XT7X6QCP.js";
 import "./chunk-4YYJOFKS.js";
 import {
   normalizeSkillSlug
 } from "./chunk-HVW7ABXD.js";
-import "./chunk-JOTLPC6S.js";
-import "./chunk-75JJVANE.js";
-import "./chunk-QXPCARFE.js";
+import "./chunk-HW4AKJ5F.js";
+import "./chunk-CLOH4LIB.js";
+import "./chunk-TAMQYQGJ.js";
 import "./chunk-AWDFDFI3.js";
 import "./chunk-P6LJ4Y32.js";
 import {
@@ -82,8 +82,8 @@ import {
   trackRenderError,
   trackRenderObservation,
   trackRenderPreflightRejected
-} from "./chunk-XGMNQQTJ.js";
-import "./chunk-LBKDQKWV.js";
+} from "./chunk-QFN7NVWM.js";
+import "./chunk-OSSHSIMD.js";
 import "./chunk-VWG7OQKU.js";
 import {
   bytesToMb
@@ -110,27 +110,27 @@ import {
   MAX_VP9_CPU_USED,
   MIN_VP9_CPU_USED,
   isVideoFrameFormat
-} from "./chunk-IDX52YJN.js";
-import "./chunk-DPHJKWP5.js";
-import "./chunk-A4KQZXZI.js";
+} from "./chunk-33RZPZ4K.js";
+import "./chunk-F26LCYRY.js";
+import "./chunk-NE55C6S5.js";
 import "./chunk-USDEMXXL.js";
 import {
   formatRenderOutputTimestamp,
   fpsToFfmpegArg,
   fpsToNumber,
   parseFps
-} from "./chunk-YFT3BL7N.js";
+} from "./chunk-4M4EC7JX.js";
+import "./chunk-6TPZSTCL.js";
+import "./chunk-VC76R6W2.js";
+import "./chunk-YA62XGXS.js";
 import {
   checkOutputResolutionCompatibility,
   isAspectAgnosticResolutionAlias,
   normalizeResolutionFlag,
   suggestMatchingPreset
-} from "./chunk-OZUQF4NB.js";
-import "./chunk-DPVXBVLL.js";
-import "./chunk-J4UX3RS3.js";
-import "./chunk-VC76R6W2.js";
-import "./chunk-YA62XGXS.js";
+} from "./chunk-MQZVBHEY.js";
 import "./chunk-OFQWTKPW.js";
+import "./chunk-DPVXBVLL.js";
 import "./chunk-T76PLPD6.js";
 import "./chunk-FXMKHHPO.js";
 import "./chunk-RQVDTPGD.js";
@@ -148,16 +148,17 @@ import "./chunk-TWWSYAKJ.js";
 import {
   lintProject,
   shouldBlockRender
-} from "./chunk-IW2CKH6A.js";
+} from "./chunk-XONFUK3M.js";
 import {
   collectSubCompositionSrcs
-} from "./chunk-JFKL3WAE.js";
-import "./chunk-HBBJFK6I.js";
+} from "./chunk-IWFLMU2N.js";
+import "./chunk-APDLWWFG.js";
 import "./chunk-PJ3HDUCY.js";
-import "./chunk-TQFG7HTI.js";
-import "./chunk-GK4AIFIH.js";
+import "./chunk-3RM2ETQT.js";
+import "./chunk-ZLW2V65P.js";
+import "./chunk-SDYDNHEE.js";
 import "./chunk-2PSPARWP.js";
-import "./chunk-PMRBLBUP.js";
+import "./chunk-T42U2W2R.js";
 import "./chunk-K4WIOZFP.js";
 import {
   readConfigFresh,
@@ -171,7 +172,7 @@ import {
 } from "./chunk-ISN5GRYI.js";
 import {
   VERSION
-} from "./chunk-DZEVA7DI.js";
+} from "./chunk-W35EKBS6.js";
 import {
   normalizeErrorMessage
 } from "./chunk-KNU5COPB.js";
@@ -645,7 +646,7 @@ function formatGpuModes(plan) {
 }
 async function warnForSlideshow(plan) {
   try {
-    const { slideshowIslandRegex } = await import("./slideshow-EJ4IMY6P.js");
+    const { slideshowIslandRegex } = await import("./slideshow-4OJEPWNZ.js");
     if (!slideshowIslandRegex("i").test(readFileSync2(plan.renderTarget, "utf8"))) return;
     console.log(
       c.warn("\u26A0") + "  This composition carries a slideshow island \u2014 `render` captures only the first scene, so the MP4 will be truncated to slide 1. Use " + c.accent("hyperframes present") + " for the deck; a linear main-line MP4 export is not yet available."
@@ -670,7 +671,7 @@ async function executeRenderPlan(plan, dependencies, cancellation) {
   let batchModule;
   let preparedBatch;
   if (plan.batchPath) {
-    batchModule = await import("./batchRender-4YUHQI6X.js");
+    batchModule = await import("./batchRender-4U73BYTU.js");
     try {
       preparedBatch = batchModule.prepareBatchRender({
         batchPath: plan.batchPath,
@@ -1460,7 +1461,7 @@ var render_default = defineCommand({
 });
 async function readCompositionDimensions(compositionHtml) {
   try {
-    const { ensureDOMParser } = await import("./dom-IROKGVJI.js");
+    const { ensureDOMParser } = await import("./dom-37K6YOH4.js");
     ensureDOMParser();
     const doc = new DOMParser().parseFromString(compositionHtml, "text/html");
     const rootEl = doc.querySelector("[data-composition-id]");

package/dist/{render-batch-M55YZLZ5.js → render-batch-GGUOK3DS.js}

@@ -6,7 +6,7 @@ var __filename = __hf_fileURLToPath(import.meta.url);
 var __dirname = __hf_dirname(__filename);
 import {
   warnOnDimensionMismatch
-} from "./chunk-THXFSPLV.js";
+} from "./chunk-ZIRIDSDB.js";
 import {
   requireStack
 } from "./chunk-H4YZZ2VQ.js";
@@ -14,30 +14,31 @@ import {
   loadProjectVariableSchema,
   reportVariableIssues,
   validateVariablesAgainstSchema
-} from "./chunk-6UYZB4TY.js";
-import "./chunk-5Z63TBTX.js";
+} from "./chunk-LW6HO6U3.js";
+import "./chunk-FH7WODJH.js";
 import {
   errorBox
-} from "./chunk-IHFUKJOR.js";
-import "./chunk-PFCFR3KZ.js";
+} from "./chunk-K2FLNJVB.js";
+import "./chunk-442JNXRM.js";
 import {
   failCommand,
   setCommandExitCode
 } from "./chunk-PBN6GBJE.js";
-import "./chunk-YFT3BL7N.js";
-import "./chunk-OZUQF4NB.js";
-import "./chunk-DPVXBVLL.js";
-import "./chunk-J4UX3RS3.js";
+import "./chunk-4M4EC7JX.js";
+import "./chunk-6TPZSTCL.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-YA62XGXS.js";
+import "./chunk-MQZVBHEY.js";
 import "./chunk-OFQWTKPW.js";
+import "./chunk-DPVXBVLL.js";
 import "./chunk-T76PLPD6.js";
 import "./chunk-FXMKHHPO.js";
 import "./chunk-RQVDTPGD.js";
-import "./chunk-TQFG7HTI.js";
-import "./chunk-GK4AIFIH.js";
+import "./chunk-3RM2ETQT.js";
+import "./chunk-ZLW2V65P.js";
+import "./chunk-SDYDNHEE.js";
 import "./chunk-2PSPARWP.js";
-import "./chunk-PMRBLBUP.js";
+import "./chunk-T42U2W2R.js";
 import {
   normalizeErrorMessage
 } from "./chunk-KNU5COPB.js";

package/dist/{renderCancellation-X5BEHAZU.js → renderCancellation-PZRWB53I.js}

@@ -7,32 +7,33 @@ var __dirname = __hf_dirname(__filename);
 import {
   createRenderCancellationScope,
   stoppedByCancelSignal
-} from "./chunk-FWRNQOLT.js";
-import "./chunk-IDX52YJN.js";
-import "./chunk-DPHJKWP5.js";
-import "./chunk-A4KQZXZI.js";
+} from "./chunk-UICWP23D.js";
+import "./chunk-33RZPZ4K.js";
+import "./chunk-F26LCYRY.js";
+import "./chunk-NE55C6S5.js";
 import "./chunk-USDEMXXL.js";
-import "./chunk-YFT3BL7N.js";
-import "./chunk-OZUQF4NB.js";
-import "./chunk-DPVXBVLL.js";
-import "./chunk-J4UX3RS3.js";
+import "./chunk-4M4EC7JX.js";
+import "./chunk-6TPZSTCL.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-YA62XGXS.js";
+import "./chunk-MQZVBHEY.js";
 import "./chunk-OFQWTKPW.js";
+import "./chunk-DPVXBVLL.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-IW2CKH6A.js";
-import "./chunk-JFKL3WAE.js";
-import "./chunk-HBBJFK6I.js";
+import "./chunk-XONFUK3M.js";
+import "./chunk-IWFLMU2N.js";
+import "./chunk-APDLWWFG.js";
 import "./chunk-PJ3HDUCY.js";
-import "./chunk-TQFG7HTI.js";
-import "./chunk-GK4AIFIH.js";
+import "./chunk-3RM2ETQT.js";
+import "./chunk-ZLW2V65P.js";
+import "./chunk-SDYDNHEE.js";
 import "./chunk-2PSPARWP.js";
-import "./chunk-PMRBLBUP.js";
+import "./chunk-T42U2W2R.js";
 import "./chunk-3GXQPCJC.js";
 import "./chunk-M2WBOQ2Q.js";
 export {

package/dist/renderSetupWorker.js

@@ -16,14 +16,15 @@ import "./chunk-LCSMOLGX.js";
 import "./chunk-TWWSYAKJ.js";
 import {
   lintProject
-} from "./chunk-IW2CKH6A.js";
-import "./chunk-JFKL3WAE.js";
-import "./chunk-HBBJFK6I.js";
+} from "./chunk-XONFUK3M.js";
+import "./chunk-IWFLMU2N.js";
+import "./chunk-APDLWWFG.js";
 import "./chunk-PJ3HDUCY.js";
-import "./chunk-TQFG7HTI.js";
-import "./chunk-GK4AIFIH.js";
+import "./chunk-3RM2ETQT.js";
+import "./chunk-ZLW2V65P.js";
+import "./chunk-SDYDNHEE.js";
 import "./chunk-2PSPARWP.js";
-import "./chunk-PMRBLBUP.js";
+import "./chunk-T42U2W2R.js";
 import "./chunk-KNU5COPB.js";
 import "./chunk-M2WBOQ2Q.js";
 

package/dist/{resolver-GAMXRA42.js → resolver-S5VK6UCB.js}

@@ -11,25 +11,26 @@ import {
   resolveItemWithDependencies,
   resolveItemsByTag,
   unreachableRegistryMessage
-} from "./chunk-JOTLPC6S.js";
-import "./chunk-QXPCARFE.js";
+} from "./chunk-HW4AKJ5F.js";
+import "./chunk-TAMQYQGJ.js";
 import "./chunk-AWDFDFI3.js";
 import "./chunk-P6LJ4Y32.js";
 import "./chunk-GMECXFAN.js";
-import "./chunk-YFT3BL7N.js";
-import "./chunk-OZUQF4NB.js";
-import "./chunk-DPVXBVLL.js";
-import "./chunk-J4UX3RS3.js";
+import "./chunk-4M4EC7JX.js";
+import "./chunk-6TPZSTCL.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-YA62XGXS.js";
+import "./chunk-MQZVBHEY.js";
 import "./chunk-OFQWTKPW.js";
+import "./chunk-DPVXBVLL.js";
 import "./chunk-T76PLPD6.js";
 import "./chunk-FXMKHHPO.js";
 import "./chunk-RQVDTPGD.js";
-import "./chunk-TQFG7HTI.js";
-import "./chunk-GK4AIFIH.js";
+import "./chunk-3RM2ETQT.js";
+import "./chunk-ZLW2V65P.js";
+import "./chunk-SDYDNHEE.js";
 import "./chunk-2PSPARWP.js";
-import "./chunk-PMRBLBUP.js";
+import "./chunk-T42U2W2R.js";
 import "./chunk-M2WBOQ2Q.js";
 export {
   listRegistryItems,

package/dist/{sherpa-ZYTNFHD5.js → sherpa-LVIUEAGF.js}

@@ -21,43 +21,44 @@ import "./chunk-EOVYQ3IG.js";
 import {
   getPreparedWavDurationSeconds,
   prepareWav
-} from "./chunk-7FCDA4RH.js";
+} from "./chunk-N3DQEVSI.js";
 import {
   emitWords
 } from "./chunk-6IHWCZ3W.js";
 import {
   stoppedByCancelSignal
-} from "./chunk-FWRNQOLT.js";
+} from "./chunk-UICWP23D.js";
 import "./chunk-6BEFEWFB.js";
-import "./chunk-PXSM4HPB.js";
-import "./chunk-WCJGTLPF.js";
+import "./chunk-U3X3TPBW.js";
+import "./chunk-BHVFTYSI.js";
 import "./chunk-TVCRUG2S.js";
 import "./chunk-AMKC3AXA.js";
-import "./chunk-IDX52YJN.js";
-import "./chunk-DPHJKWP5.js";
-import "./chunk-A4KQZXZI.js";
+import "./chunk-33RZPZ4K.js";
+import "./chunk-F26LCYRY.js";
+import "./chunk-NE55C6S5.js";
 import "./chunk-USDEMXXL.js";
-import "./chunk-YFT3BL7N.js";
-import "./chunk-OZUQF4NB.js";
-import "./chunk-DPVXBVLL.js";
-import "./chunk-J4UX3RS3.js";
+import "./chunk-4M4EC7JX.js";
+import "./chunk-6TPZSTCL.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-YA62XGXS.js";
+import "./chunk-MQZVBHEY.js";
 import "./chunk-OFQWTKPW.js";
+import "./chunk-DPVXBVLL.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-IW2CKH6A.js";
-import "./chunk-JFKL3WAE.js";
-import "./chunk-HBBJFK6I.js";
+import "./chunk-XONFUK3M.js";
+import "./chunk-IWFLMU2N.js";
+import "./chunk-APDLWWFG.js";
 import "./chunk-PJ3HDUCY.js";
-import "./chunk-TQFG7HTI.js";
-import "./chunk-GK4AIFIH.js";
+import "./chunk-3RM2ETQT.js";
+import "./chunk-ZLW2V65P.js";
+import "./chunk-SDYDNHEE.js";
 import "./chunk-2PSPARWP.js";
-import "./chunk-PMRBLBUP.js";
+import "./chunk-T42U2W2R.js";
 import {
   PARAKEET_MODEL_LABEL,
   SHERPA_ERROR_PREFIX,

package/dist/skills/hyperframes-cli/references/doctor-browser.md

@@ -28,7 +28,7 @@ Run `doctor` first when:
 
 Common issues:
 
-- **Missing FFmpeg** — install via `brew install ffmpeg` (macOS) or your package manager.
+- **Missing FFmpeg** — install via `brew install ffmpeg` (macOS) or your package manager, or [configure existing binaries](#configure-ffmpeg-without-a-package-manager).
 - **Missing bundled Chrome** — run `npx hyperframes browser ensure`.
 - **Low memory** — close other Chromes, reduce `--workers`, or use `--quality draft`.
 - **Chrome exits instantly inside an agent sandbox (macOS)** — seatbelt-style sandboxes
@@ -44,6 +44,29 @@ Common issues:
   blocker is identified, BEFORE any optional fallback work: a later session failure must
   not erase the report of work already done.
 
+### Configure FFmpeg without a package manager
+
+Get FFmpeg and FFprobe binaries for your operating system and architecture from the [FFmpeg download page](https://ffmpeg.org/download.html). Both must be executable. You can use them without Homebrew or a system-wide installation:
+
+```bash
+export HYPERFRAMES_FFMPEG_PATH="/absolute/path/to/ffmpeg"
+export HYPERFRAMES_FFPROBE_PATH="/absolute/path/to/ffprobe"
+npx hyperframes doctor --json
+```
+
+Set both variables in the environment that launches HyperFrames. On Windows, point them at `ffmpeg.exe` and `ffprobe.exe` using your shell's environment-variable syntax. A configured path takes precedence over automatic discovery; a missing configured file is reported as missing.
+
+Alternatively, put the binaries in `.hyperframes/bin/ffmpeg` and `.hyperframes/bin/ffprobe` (`.exe` on Windows), then run HyperFrames from that project's directory. Discovery checks `PATH` before this project-local directory, so use the environment variables when you need a particular build.
+
+Verify the **FFmpeg** and **FFprobe** entries in `doctor --json` report `ok: true` and the expected paths. To gate only these encoding dependencies with `jq`:
+
+```bash
+npx hyperframes doctor --json | jq -e \
+  '[.checks[] | select(.name == "FFmpeg" or .name == "FFprobe")] | length == 2 and all(.ok)'
+```
+
+The report's top-level `ok` also includes optional tools such as Docker and local voice providers; those failures do not require installing them for a local video render. Check Chrome separately with the browser commands below.
+
 ## browser
 
 ```bash

package/dist/skills/media-use/scripts/lib/cache.mjs

@@ -1,4 +1,11 @@
-import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync } from "node:fs";
+import {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+  copyFileSync,
+  statSync,
+} from "node:fs";
 import { join, basename } from "node:path";
 import { createHash } from "node:crypto";
 import { readManifest, appendRecord, normalizePrompt } from "./manifest.mjs";
@@ -45,9 +52,10 @@ export function findGlobalBySha(shaPrefix) {
     .toLowerCase()
     .trim();
   if (!p) return null;
-  const matches = readGlobalManifest().filter(
+  const matchingRecords = readGlobalManifest().filter(
     (r) => r.reusable && typeof r.sha === "string" && r.sha.startsWith(p),
   );
+  const matches = Array.from(new Map(matchingRecords.map((r) => [r.sha, r])).values());
   if (matches.length === 0) return null;
   if (matches.length > 1) {
     const exact = matches.find((r) => r.sha === p);
@@ -58,27 +66,36 @@ export function findGlobalBySha(shaPrefix) {
 }
 
 function validateCacheHit(match) {
-  if (!match?.sha) return null;
-  return isComplete(cacheEntryDir(globalMediaDir(), match.sha)) ? match : null;
+  if (!match?.sha || !match.cached_path) return null;
+  if (!isComplete(cacheEntryDir(globalMediaDir(), match.sha))) return null;
+  try {
+    const file = statSync(match.cached_path);
+    return file.isFile() && file.size > 0 ? match : null;
+  } catch {
+    return null;
+  }
 }
 
 export function cacheGet(prompt, type) {
   const key = normalizePrompt(prompt);
   if (!key) return null;
-  return validateCacheHit(
+  return (
     readGlobalManifest().find(
       (r) =>
         r.reusable &&
         normalizePrompt(r.provenance?.prompt) === key &&
-        (type == null || r.type === type),
-    ),
+        (type == null || r.type === type) &&
+        validateCacheHit(r),
+    ) ?? null
   );
 }
 
 export function cacheGetByEntity(entity) {
   const lower = entity.toLowerCase();
-  return validateCacheHit(
-    readGlobalManifest().find((r) => r.reusable && r.entity && r.entity.toLowerCase() === lower),
+  return (
+    readGlobalManifest().find(
+      (r) => r.reusable && r.entity && r.entity.toLowerCase() === lower && validateCacheHit(r),
+    ) ?? null
   );
 }
 
@@ -86,7 +103,7 @@ export function cachePut(filePath, record) {
   const sha = contentHash(filePath);
   // Idempotent: same content already promoted -> don't duplicate the global
   // record. ponytail: skips usage_count bump; add it when the metric is needed.
-  const existing = readGlobalManifest().find((r) => r.sha === sha);
+  const existing = readGlobalManifest().findLast((r) => r.sha === sha && validateCacheHit(r));
   if (existing) return { sha, cached_path: existing.cached_path, deduped: true };
 
   const dir = globalMediaDir();
@@ -108,12 +125,9 @@ export function cachePut(filePath, record) {
 }
 
 export function importFromCache(cacheRecord, projectDir, localId, localPath) {
+  if (!validateCacheHit(cacheRecord)) return null;
   const sha = cacheRecord.sha;
-  const entryDir = cacheEntryDir(globalMediaDir(), sha);
-  if (!isComplete(entryDir)) return null;
-
   const cachedFile = cacheRecord.cached_path;
-  if (!cachedFile || !existsSync(cachedFile)) return null;
 
   mkdirSync(join(projectDir, ".media"), { recursive: true });
   const fullDest = join(projectDir, localPath);

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

@@ -0,0 +1,110 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { test } from "node:test";
+import { appendRecord } from "./manifest.mjs";
+import {
+  cacheGet,
+  cacheGetByEntity,
+  cachePut,
+  findGlobalBySha,
+  importFromCache,
+  readGlobalManifest,
+} from "./cache.mjs";
+
+function sandbox(t) {
+  const root = mkdtempSync(join(tmpdir(), "mu-cache-recovery-"));
+  const previous = process.env.HYPERFRAMES_MEDIA_HOME;
+  process.env.HYPERFRAMES_MEDIA_HOME = join(root, "library");
+  t.after(() => {
+    if (previous === undefined) delete process.env.HYPERFRAMES_MEDIA_HOME;
+    else process.env.HYPERFRAMES_MEDIA_HOME = previous;
+    rmSync(root, { recursive: true, force: true });
+  });
+  const source = join(root, "original.wav");
+  const bytes = "cache recovery fixture";
+  writeFileSync(source, bytes);
+  const record = {
+    id: "bgm_001",
+    type: "bgm",
+    entity: "Recovery",
+    provenance: { prompt: "cache recovery" },
+  };
+  return { root, source, bytes, record };
+}
+
+for (const invalid of [
+  "missing file",
+  "missing marker",
+  "missing directory",
+  "empty file",
+  "directory",
+]) {
+  test(`cachePut repairs a ${invalid} before deduplicating`, (t) => {
+    const { root, source, bytes, record } = sandbox(t);
+    const first = cachePut(source, record);
+    const entry = dirname(first.cached_path);
+    if (invalid === "missing marker") rmSync(join(entry, ".hf-complete"));
+    else if (invalid === "missing directory") rmSync(entry, { recursive: true });
+    else if (invalid === "empty file") writeFileSync(first.cached_path, "");
+    else {
+      rmSync(first.cached_path);
+      if (invalid === "directory") mkdirSync(first.cached_path);
+    }
+
+    const replacement = join(root, "replacement.wav");
+    writeFileSync(replacement, bytes);
+    const repaired = cachePut(replacement, record);
+
+    assert.equal(repaired.deduped, undefined);
+    assert.equal(repaired.sha, first.sha);
+    assert.equal(readFileSync(repaired.cached_path, "utf8"), bytes);
+    const cached = cacheGet("  Cache  Recovery ", "bgm");
+    assert.equal(cached?.sha, repaired.sha);
+    assert.equal(readFileSync(cached.cached_path, "utf8"), bytes);
+    assert.equal(cacheGetByEntity("recovery")?.sha, repaired.sha);
+    const imported = importFromCache(cached, join(root, "project"), "bgm_002", "restored.wav");
+    assert.equal(imported?.provenance.imported_from, first.sha);
+    assert.equal(readFileSync(join(root, "project", "restored.wav"), "utf8"), bytes);
+  });
+}
+
+test("an intact cache stays deduplicated without adding a manifest record", (t) => {
+  const { source, record } = sandbox(t);
+  const first = cachePut(source, record);
+  const second = cachePut(source, record);
+
+  assert.deepEqual(second, { ...first, deduped: true });
+  assert.equal(readGlobalManifest().length, 1);
+});
+
+test("prompt and entity lookups skip a stale entry for another complete match", (t) => {
+  const { root, source, record } = sandbox(t);
+  const first = cachePut(source, record);
+  rmSync(first.cached_path);
+  const secondSource = join(root, "second.wav");
+  writeFileSync(secondSource, "different reusable bytes");
+  const second = cachePut(secondSource, record);
+
+  assert.equal(cacheGet("cache recovery", "bgm")?.sha, second.sha);
+  assert.equal(cacheGetByEntity("RECOVERY")?.sha, second.sha);
+  assert.equal(cacheGet("cache recovery", "sfx"), null);
+});
+
+test("sha reuse counts distinct content and selects the repaired record", (t) => {
+  const { root, source, bytes, record } = sandbox(t);
+  const first = cachePut(source, record);
+  rmSync(first.cached_path);
+  const replacement = join(dirname(first.cached_path), "replacement.wav");
+  writeFileSync(replacement, bytes);
+  appendRecord(join(root, "library"), {
+    ...record,
+    sha: first.sha,
+    reusable: true,
+    cached_path: replacement,
+  });
+
+  assert.equal(findGlobalBySha(first.sha)?.cached_path, replacement);
+  assert.equal(findGlobalBySha(first.sha.slice(0, 16))?.cached_path, replacement);
+});

package/dist/skills/media-use/scripts/lib/duck.mjs

@@ -5,7 +5,7 @@ export function speechSpans(meta, { mergeGap = 0.6, offsets, sequential = false,
   const merge = Number(mergeGap);
   const lists = wordListsFromMediaMeta(meta);
   const voices = Array.isArray(meta?.voices) ? meta.voices : [];
-  if (lists.length > 1 && !offsets && !sequential) {
+  if (lists.filter((words) => words.length > 0).length > 1 && !offsets && !sequential) {
     throw new Error(
       "audio_meta has multiple voice lines with file-relative times; pass --sequential or --offsets so spans land at composition time",
     );
@@ -16,6 +16,7 @@ export function speechSpans(meta, { mergeGap = 0.6, offsets, sequential = false,
     const voice = voices[i];
     let offset = 0;
     if (offsets) {
+      if (lists[i].length === 0) continue;
       const id = voice?.id ?? String(i);
       if (!(id in offsets)) throw new Error(`--offsets is missing voice "${id}"`);
       offset = Number(offsets[id]) || 0;