@scenar/cli 0.10.0 → 0.11.0

package/src/util/load-ts.ts

@@ -97,6 +97,145 @@ export function findAuthoredViewport(exports: Record<string, unknown>): Authored
   return null;
 }
 
+/**
+ * A scenario-authored soundtrack, mirroring the proto `SoundtrackConfig`
+ * in camelCase (the same shape as `@scenar/core`'s `Soundtrack`).
+ */
+export interface AuthoredSoundtrack {
+  musicSrc?: string;
+  musicVolume?: number;
+  duckingVolume?: number;
+  sfx?: boolean;
+}
+
+/** The soundtrack's known field names — used to pick a clean copy. */
+const SOUNDTRACK_FIELDS = ["musicSrc", "musicVolume", "duckingVolume", "sfx"] as const;
+
+function pickSoundtrack(value: unknown): AuthoredSoundtrack | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  const soundtrack: Record<string, unknown> = {};
+  for (const field of SOUNDTRACK_FIELDS) {
+    if (record[field] !== undefined) soundtrack[field] = record[field];
+  }
+  return soundtrack as AuthoredSoundtrack;
+}
+
+/**
+ * Find the scenario's authored soundtrack in a loaded module's exports,
+ * or null when the module authors none.
+ *
+ * Mirrors {@link findAuthoredViewport}'s two authored forms and
+ * precedence exactly:
+ *
+ * 1. A scenario-shaped export — an object carrying both a `soundtrack`
+ *    and a delayMs-bearing `steps` array (what `createScenario()`
+ *    returns when the author passes a soundtrack).
+ * 2. An export *named* `soundtrack` — the directory-form counterpart,
+ *    for authors of a raw steps array.
+ *
+ * Field validity (volume ranges, non-empty musicSrc) is the validator's
+ * concern, not discovery's — this only locates the authored object.
+ */
+export function findAuthoredSoundtrack(
+  exports: Record<string, unknown>,
+): AuthoredSoundtrack | null {
+  for (const value of Object.values(exports)) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) continue;
+    const record = value as Record<string, unknown>;
+    if (record["soundtrack"] !== undefined && isStepsShape(record["steps"])) {
+      return pickSoundtrack(record["soundtrack"]);
+    }
+  }
+  if (exports["soundtrack"] !== undefined) {
+    return pickSoundtrack(exports["soundtrack"]);
+  }
+  return null;
+}
+
+/**
+ * A scenario-authored title card, mirroring the proto `TitleCard`
+ * in camelCase (the same shape as `@scenar/core`'s `TitleCard`).
+ */
+export interface AuthoredTitleCard {
+  title?: string;
+  subtitle?: string;
+  logoSrc?: string;
+  ctaText?: string;
+  durationMs?: number;
+}
+
+/**
+ * A scenario-authored title-cards config, mirroring the proto
+ * `TitleCardsConfig` in camelCase.
+ */
+export interface AuthoredTitleCards {
+  intro?: AuthoredTitleCard;
+  outro?: AuthoredTitleCard;
+}
+
+/** The card's known field names — used to pick a clean copy. */
+const TITLE_CARD_FIELDS = [
+  "title",
+  "subtitle",
+  "logoSrc",
+  "ctaText",
+  "durationMs",
+] as const;
+
+function pickTitleCard(value: unknown): AuthoredTitleCard | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  const card: Record<string, unknown> = {};
+  for (const field of TITLE_CARD_FIELDS) {
+    if (record[field] !== undefined) card[field] = record[field];
+  }
+  return card as AuthoredTitleCard;
+}
+
+function pickTitleCards(value: unknown): AuthoredTitleCards | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  const cards: AuthoredTitleCards = {};
+  const intro = pickTitleCard(record["intro"]);
+  const outro = pickTitleCard(record["outro"]);
+  if (intro) cards.intro = intro;
+  if (outro) cards.outro = outro;
+  return cards;
+}
+
+/**
+ * Find the scenario's authored title cards in a loaded module's exports,
+ * or null when the module authors none.
+ *
+ * Mirrors {@link findAuthoredSoundtrack}'s two authored forms and
+ * precedence exactly:
+ *
+ * 1. A scenario-shaped export — an object carrying both a `titleCards`
+ *    and a delayMs-bearing `steps` array (what `createScenario()`
+ *    returns when the author passes title cards).
+ * 2. An export *named* `titleCards` — the directory-form counterpart,
+ *    for authors of a raw steps array.
+ *
+ * Field validity (non-empty title, positive duration) is the validator's
+ * concern, not discovery's — this only locates the authored object.
+ */
+export function findAuthoredTitleCards(
+  exports: Record<string, unknown>,
+): AuthoredTitleCards | null {
+  for (const value of Object.values(exports)) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) continue;
+    const record = value as Record<string, unknown>;
+    if (record["titleCards"] !== undefined && isStepsShape(record["steps"])) {
+      return pickTitleCards(record["titleCards"]);
+    }
+  }
+  if (exports["titleCards"] !== undefined) {
+    return pickTitleCards(exports["titleCards"]);
+  }
+  return null;
+}
+
 /**
  * Dynamically import a TypeScript steps file and extract the
  * steps array by duck-typing ({@link findStepsArray}).
@@ -113,3 +252,29 @@ export async function loadStepsFromTs(filePath: string): Promise<ImportedStep[]>
   }
   return steps;
 }
+
+/**
+ * Dynamically import a TypeScript steps file and extract the authored
+ * soundtrack ({@link findAuthoredSoundtrack}), or null when the module
+ * authors none. Node caches the module, so calling this alongside
+ * {@link loadStepsFromTs} costs one import.
+ */
+export async function loadSoundtrackFromTs(
+  filePath: string,
+): Promise<AuthoredSoundtrack | null> {
+  const mod = await import(pathToFileURL(filePath).href);
+  return findAuthoredSoundtrack(mod.default ?? mod);
+}
+
+/**
+ * Dynamically import a TypeScript steps file and extract the authored
+ * title cards ({@link findAuthoredTitleCards}), or null when the module
+ * authors none. Node caches the module, so calling this alongside
+ * {@link loadStepsFromTs} costs one import.
+ */
+export async function loadTitleCardsFromTs(
+  filePath: string,
+): Promise<AuthoredTitleCards | null> {
+  const mod = await import(pathToFileURL(filePath).href);
+  return findAuthoredTitleCards(mod.default ?? mod);
+}

package/src/util/narration-cache.d.ts

@@ -3,20 +3,28 @@ interface CacheEntry {
     durationMs: number;
 }
 interface CacheFile {
+    /**
+     * The generating provider's cache identity (see `TtsProvider.fingerprint`).
+     * Audio from one provider/model/default-voice configuration must never be
+     * served as a cache hit for another. Legacy cache files predate this field;
+     * they never match and regenerate once.
+     */
+    fingerprint: string;
     voice: string;
     steps: (CacheEntry | null)[];
 }
-export declare function computeHash(narration: string, voice: string): string;
+export declare function computeHash(narration: string, voice: string, fingerprint: string): string;
 export declare function loadCache(outputDir: string): Promise<CacheFile | null>;
 export declare function saveCache(outputDir: string, cache: CacheFile): Promise<void>;
 export declare function fileExists(filePath: string): Promise<boolean>;
 /**
- * Check whether a step's narration is already cached (matching hash
- * and the MP3 file still exists on disk).
+ * Check whether a step's narration is already cached: the cache file was
+ * written by the same provider configuration (fingerprint) and voice, the
+ * step's hash matches, and the MP3 file still exists on disk.
  */
-export declare function isCached(cache: CacheFile | null, stepIndex: number, hash: string, voice: string): boolean;
+export declare function isCached(cache: CacheFile | null, stepIndex: number, hash: string, voice: string, fingerprint: string): boolean;
 export declare function getCachedDuration(cache: CacheFile, stepIndex: number): number;
-export declare function buildCacheFile(voice: string, totalSteps: number, entries: Map<number, {
+export declare function buildCacheFile(fingerprint: string, voice: string, totalSteps: number, entries: Map<number, {
     hash: string;
     durationMs: number;
 }>): CacheFile;

package/src/util/narration-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"narration-cache.d.ts","sourceRoot":"","sources":["../../../src/util/narration-cache.ts"],"names":[],"mappings":"AAIA,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,SAAS;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,CAAC,UAAU,GAAG,IAAI,CAAC,EAAE,CAAC;CAC9B;AAID,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIpE;AAED,wBAAsB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAO5E;AAED,wBAAsB,SAAS,CAC7B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,SAAS,GAAG,IAAI,EACvB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAIT;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,EAChB,SAAS,EAAE,MAAM,GAChB,MAAM,CAER;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GACzD,SAAS,CASX"}
+{"version":3,"file":"narration-cache.d.ts","sourceRoot":"","sources":["../../../src/util/narration-cache.ts"],"names":[],"mappings":"AAIA,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,SAAS;IACjB;;;;;OAKG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,CAAC,UAAU,GAAG,IAAI,CAAC,EAAE,CAAC;CAC9B;AAID,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,MAAM,CAIR;AAED,wBAAsB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAO5E;AAED,wBAAsB,SAAS,CAC7B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,SAAS,GAAG,IAAI,EACvB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,OAAO,CAMT;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,EAChB,SAAS,EAAE,MAAM,GAChB,MAAM,CAER;AAED,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GACzD,SAAS,CASX"}

package/src/util/narration-cache.js

@@ -2,9 +2,9 @@ import { createHash } from "node:crypto";
 import { readFile, writeFile, access } from "node:fs/promises";
 import { join } from "node:path";
 const CACHE_FILENAME = ".narration-cache.json";
-export function computeHash(narration, voice) {
+export function computeHash(narration, voice, fingerprint) {
     return createHash("sha256")
-        .update(`${voice}\0${narration}`)
+        .update(`${fingerprint}\0${voice}\0${narration}`)
         .digest("hex");
 }
 export async function loadCache(outputDir) {
@@ -29,23 +29,25 @@ export async function fileExists(filePath) {
     }
 }
 /**
- * Check whether a step's narration is already cached (matching hash
- * and the MP3 file still exists on disk).
+ * Check whether a step's narration is already cached: the cache file was
+ * written by the same provider configuration (fingerprint) and voice, the
+ * step's hash matches, and the MP3 file still exists on disk.
  */
-export function isCached(cache, stepIndex, hash, voice) {
-    if (!cache || cache.voice !== voice)
+export function isCached(cache, stepIndex, hash, voice, fingerprint) {
+    if (!cache || cache.fingerprint !== fingerprint || cache.voice !== voice) {
         return false;
+    }
     const entry = cache.steps[stepIndex];
     return entry !== null && entry !== undefined && entry.hash === hash;
 }
 export function getCachedDuration(cache, stepIndex) {
     return cache.steps[stepIndex].durationMs;
 }
-export function buildCacheFile(voice, totalSteps, entries) {
+export function buildCacheFile(fingerprint, voice, totalSteps, entries) {
     const steps = Array.from({ length: totalSteps }, () => null);
     for (const [idx, entry] of entries) {
         steps[idx] = entry;
     }
-    return { voice, steps };
+    return { fingerprint, voice, steps };
 }
 //# sourceMappingURL=narration-cache.js.map

package/src/util/narration-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"narration-cache.js","sourceRoot":"","sources":["../../../src/util/narration-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAYjC,MAAM,cAAc,GAAG,uBAAuB,CAAC;AAE/C,MAAM,UAAU,WAAW,CAAC,SAAiB,EAAE,KAAa;IAC1D,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,GAAG,KAAK,KAAK,SAAS,EAAE,CAAC;SAChC,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,SAAiB;IAC/C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CAAC;QACrE,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAc,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,SAAiB,EACjB,KAAgB;IAEhB,MAAM,SAAS,CACb,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,EAC/B,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CACtC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAgB;IAC/C,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAuB,EACvB,SAAiB,EACjB,IAAY,EACZ,KAAa;IAEb,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAClD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACrC,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;AACtE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,KAAgB,EAChB,SAAiB;IAEjB,OAAO,KAAK,CAAC,KAAK,CAAC,SAAS,CAAE,CAAC,UAAU,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,KAAa,EACb,UAAkB,EAClB,OAA0D;IAE1D,MAAM,KAAK,GAA0B,KAAK,CAAC,IAAI,CAC7C,EAAE,MAAM,EAAE,UAAU,EAAE,EACtB,GAAG,EAAE,CAAC,IAAI,CACX,CAAC;IACF,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;QACnC,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACrB,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC1B,CAAC"}
+{"version":3,"file":"narration-cache.js","sourceRoot":"","sources":["../../../src/util/narration-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAmBjC,MAAM,cAAc,GAAG,uBAAuB,CAAC;AAE/C,MAAM,UAAU,WAAW,CACzB,SAAiB,EACjB,KAAa,EACb,WAAmB;IAEnB,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,GAAG,WAAW,KAAK,KAAK,KAAK,SAAS,EAAE,CAAC;SAChD,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,SAAiB;IAC/C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CAAC;QACrE,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAc,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,SAAiB,EACjB,KAAgB;IAEhB,MAAM,SAAS,CACb,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,EAC/B,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CACtC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAgB;IAC/C,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAuB,EACvB,SAAiB,EACjB,IAAY,EACZ,KAAa,EACb,WAAmB;IAEnB,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,WAAW,KAAK,WAAW,IAAI,KAAK,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC;QACzE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACrC,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;AACtE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,KAAgB,EAChB,SAAiB;IAEjB,OAAO,KAAK,CAAC,KAAK,CAAC,SAAS,CAAE,CAAC,UAAU,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,WAAmB,EACnB,KAAa,EACb,UAAkB,EAClB,OAA0D;IAE1D,MAAM,KAAK,GAA0B,KAAK,CAAC,IAAI,CAC7C,EAAE,MAAM,EAAE,UAAU,EAAE,EACtB,GAAG,EAAE,CAAC,IAAI,CACX,CAAC;IACF,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;QACnC,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACrB,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AACvC,CAAC"}

package/src/util/narration-cache.ts

@@ -8,15 +8,26 @@ interface CacheEntry {
 }
 
 interface CacheFile {
+  /**
+   * The generating provider's cache identity (see `TtsProvider.fingerprint`).
+   * Audio from one provider/model/default-voice configuration must never be
+   * served as a cache hit for another. Legacy cache files predate this field;
+   * they never match and regenerate once.
+   */
+  fingerprint: string;
   voice: string;
   steps: (CacheEntry | null)[];
 }
 
 const CACHE_FILENAME = ".narration-cache.json";
 
-export function computeHash(narration: string, voice: string): string {
+export function computeHash(
+  narration: string,
+  voice: string,
+  fingerprint: string,
+): string {
   return createHash("sha256")
-    .update(`${voice}\0${narration}`)
+    .update(`${fingerprint}\0${voice}\0${narration}`)
     .digest("hex");
 }
 
@@ -49,16 +60,20 @@ export async function fileExists(filePath: string): Promise<boolean> {
 }
 
 /**
- * Check whether a step's narration is already cached (matching hash
- * and the MP3 file still exists on disk).
+ * Check whether a step's narration is already cached: the cache file was
+ * written by the same provider configuration (fingerprint) and voice, the
+ * step's hash matches, and the MP3 file still exists on disk.
  */
 export function isCached(
   cache: CacheFile | null,
   stepIndex: number,
   hash: string,
   voice: string,
+  fingerprint: string,
 ): boolean {
-  if (!cache || cache.voice !== voice) return false;
+  if (!cache || cache.fingerprint !== fingerprint || cache.voice !== voice) {
+    return false;
+  }
   const entry = cache.steps[stepIndex];
   return entry !== null && entry !== undefined && entry.hash === hash;
 }
@@ -71,6 +86,7 @@ export function getCachedDuration(
 }
 
 export function buildCacheFile(
+  fingerprint: string,
   voice: string,
   totalSteps: number,
   entries: Map<number, { hash: string; durationMs: number }>,
@@ -82,5 +98,5 @@ export function buildCacheFile(
   for (const [idx, entry] of entries) {
     steps[idx] = entry;
   }
-  return { voice, steps };
+  return { fingerprint, voice, steps };
 }

package/src/util/presenter-cache.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Presenter clip cache — the `.narration-cache.json` pattern applied to
+ * `scenar presenter`, where a cache hit saves real money (a HeyGen
+ * generation costs dollars, not milliseconds).
+ *
+ * The per-step hash keys on the narration MP3 **bytes**: the audio is
+ * the entire upstream state of a clip, so re-narrating a step (new
+ * voice, new text, new provider) invalidates its presenter clip
+ * automatically — no coordination needed between the two commands.
+ */
+interface PresenterCacheEntry {
+    hash: string;
+    durationMs: number;
+}
+export interface PresenterCacheFile {
+    /**
+     * The generation configuration this cache was written under:
+     * `heygen/<engine>/<resolution>/<container>/<avatarId>`. Any change
+     * regenerates everything — a clip from one avatar or quality tier
+     * must never be served as a hit for another. The container is
+     * recorded even though v1 is mp4-only, so a future webm option
+     * invalidates correctly.
+     */
+    fingerprint: string;
+    steps: (PresenterCacheEntry | null)[];
+}
+/** Compose the cache fingerprint for one generation configuration. */
+export declare function presenterFingerprint(engine: string, resolution: string, container: string, avatarId: string): string;
+/** Hash a step's narration audio bytes — the clip's entire upstream state. */
+export declare function computePresenterHash(audioBytes: Buffer): string;
+export declare function loadPresenterCache(outputDir: string): Promise<PresenterCacheFile | null>;
+export declare function savePresenterCache(outputDir: string, cache: PresenterCacheFile): Promise<void>;
+/**
+ * Whether a step's clip is already cached under this fingerprint. The
+ * caller still verifies the clip file exists on disk — a cache entry
+ * for a deleted file regenerates.
+ */
+export declare function isPresenterCached(cache: PresenterCacheFile | null, stepIndex: number, hash: string, fingerprint: string): boolean;
+export declare function buildPresenterCacheFile(fingerprint: string, totalSteps: number, entries: Map<number, {
+    hash: string;
+    durationMs: number;
+}>): PresenterCacheFile;
+export {};
+//# sourceMappingURL=presenter-cache.d.ts.map

package/src/util/presenter-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presenter-cache.d.ts","sourceRoot":"","sources":["../../../src/util/presenter-cache.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,UAAU,mBAAmB;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,CAAC,mBAAmB,GAAG,IAAI,CAAC,EAAE,CAAC;CACvC;AAID,sEAAsE;AACtE,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,MAAM,CAER;AAED,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAOpC;AAED,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,IAAI,CAAC,CAKf;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,kBAAkB,GAAG,IAAI,EAChC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAIT;AAED,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GACzD,kBAAkB,CASpB"}

package/src/util/presenter-cache.js

@@ -0,0 +1,43 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+const CACHE_FILENAME = ".presenter-cache.json";
+/** Compose the cache fingerprint for one generation configuration. */
+export function presenterFingerprint(engine, resolution, container, avatarId) {
+    return `heygen/${engine}/${resolution}/${container}/${avatarId}`;
+}
+/** Hash a step's narration audio bytes — the clip's entire upstream state. */
+export function computePresenterHash(audioBytes) {
+    return createHash("sha256").update(audioBytes).digest("hex");
+}
+export async function loadPresenterCache(outputDir) {
+    try {
+        const raw = await readFile(join(outputDir, CACHE_FILENAME), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function savePresenterCache(outputDir, cache) {
+    await writeFile(join(outputDir, CACHE_FILENAME), JSON.stringify(cache, null, 2) + "\n");
+}
+/**
+ * Whether a step's clip is already cached under this fingerprint. The
+ * caller still verifies the clip file exists on disk — a cache entry
+ * for a deleted file regenerates.
+ */
+export function isPresenterCached(cache, stepIndex, hash, fingerprint) {
+    if (!cache || cache.fingerprint !== fingerprint)
+        return false;
+    const entry = cache.steps[stepIndex];
+    return entry !== null && entry !== undefined && entry.hash === hash;
+}
+export function buildPresenterCacheFile(fingerprint, totalSteps, entries) {
+    const steps = Array.from({ length: totalSteps }, () => null);
+    for (const [idx, entry] of entries) {
+        steps[idx] = entry;
+    }
+    return { fingerprint, steps };
+}
+//# sourceMappingURL=presenter-cache.js.map

package/src/util/presenter-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presenter-cache.js","sourceRoot":"","sources":["../../../src/util/presenter-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA+BjC,MAAM,cAAc,GAAG,uBAAuB,CAAC;AAE/C,sEAAsE;AACtE,MAAM,UAAU,oBAAoB,CAClC,MAAc,EACd,UAAkB,EAClB,SAAiB,EACjB,QAAgB;IAEhB,OAAO,UAAU,MAAM,IAAI,UAAU,IAAI,SAAS,IAAI,QAAQ,EAAE,CAAC;AACnE,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,oBAAoB,CAAC,UAAkB;IACrD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,SAAiB;IAEjB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CAAC;QACrE,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAuB,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,SAAiB,EACjB,KAAyB;IAEzB,MAAM,SAAS,CACb,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,EAC/B,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CACtC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAgC,EAChC,SAAiB,EACjB,IAAY,EACZ,WAAmB;IAEnB,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,WAAW,KAAK,WAAW;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACrC,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;AACtE,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,WAAmB,EACnB,UAAkB,EAClB,OAA0D;IAE1D,MAAM,KAAK,GAAmC,KAAK,CAAC,IAAI,CACtD,EAAE,MAAM,EAAE,UAAU,EAAE,EACtB,GAAG,EAAE,CAAC,IAAI,CACX,CAAC;IACF,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;QACnC,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACrB,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;AAChC,CAAC"}

package/src/util/presenter-cache.ts

@@ -0,0 +1,101 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/**
+ * Presenter clip cache — the `.narration-cache.json` pattern applied to
+ * `scenar presenter`, where a cache hit saves real money (a HeyGen
+ * generation costs dollars, not milliseconds).
+ *
+ * The per-step hash keys on the narration MP3 **bytes**: the audio is
+ * the entire upstream state of a clip, so re-narrating a step (new
+ * voice, new text, new provider) invalidates its presenter clip
+ * automatically — no coordination needed between the two commands.
+ */
+
+interface PresenterCacheEntry {
+  hash: string;
+  durationMs: number;
+}
+
+export interface PresenterCacheFile {
+  /**
+   * The generation configuration this cache was written under:
+   * `heygen/<engine>/<resolution>/<container>/<avatarId>`. Any change
+   * regenerates everything — a clip from one avatar or quality tier
+   * must never be served as a hit for another. The container is
+   * recorded even though v1 is mp4-only, so a future webm option
+   * invalidates correctly.
+   */
+  fingerprint: string;
+  steps: (PresenterCacheEntry | null)[];
+}
+
+const CACHE_FILENAME = ".presenter-cache.json";
+
+/** Compose the cache fingerprint for one generation configuration. */
+export function presenterFingerprint(
+  engine: string,
+  resolution: string,
+  container: string,
+  avatarId: string,
+): string {
+  return `heygen/${engine}/${resolution}/${container}/${avatarId}`;
+}
+
+/** Hash a step's narration audio bytes — the clip's entire upstream state. */
+export function computePresenterHash(audioBytes: Buffer): string {
+  return createHash("sha256").update(audioBytes).digest("hex");
+}
+
+export async function loadPresenterCache(
+  outputDir: string,
+): Promise<PresenterCacheFile | null> {
+  try {
+    const raw = await readFile(join(outputDir, CACHE_FILENAME), "utf-8");
+    return JSON.parse(raw) as PresenterCacheFile;
+  } catch {
+    return null;
+  }
+}
+
+export async function savePresenterCache(
+  outputDir: string,
+  cache: PresenterCacheFile,
+): Promise<void> {
+  await writeFile(
+    join(outputDir, CACHE_FILENAME),
+    JSON.stringify(cache, null, 2) + "\n",
+  );
+}
+
+/**
+ * Whether a step's clip is already cached under this fingerprint. The
+ * caller still verifies the clip file exists on disk — a cache entry
+ * for a deleted file regenerates.
+ */
+export function isPresenterCached(
+  cache: PresenterCacheFile | null,
+  stepIndex: number,
+  hash: string,
+  fingerprint: string,
+): boolean {
+  if (!cache || cache.fingerprint !== fingerprint) return false;
+  const entry = cache.steps[stepIndex];
+  return entry !== null && entry !== undefined && entry.hash === hash;
+}
+
+export function buildPresenterCacheFile(
+  fingerprint: string,
+  totalSteps: number,
+  entries: Map<number, { hash: string; durationMs: number }>,
+): PresenterCacheFile {
+  const steps: (PresenterCacheEntry | null)[] = Array.from(
+    { length: totalSteps },
+    () => null,
+  );
+  for (const [idx, entry] of entries) {
+    steps[idx] = entry;
+  }
+  return { fingerprint, steps };
+}

package/src/util/scenario-assets.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A scenario-local asset reference resolved for shipping: where the
+ * authored file is, and where it lands in a staged public dir or packed
+ * bundle (the authored path with its leading `./` removed, so the
+ * runtime reference resolves onto the shipped file in both outputs).
+ */
+export interface ScenarioAsset {
+    /** Absolute path of the authored file. */
+    readonly sourcePath: string;
+    /** Destination path relative to the public dir / bundle root. */
+    readonly destRelPath: string;
+}
+/**
+ * True when an asset src is a remote URL (has a scheme) rather than a
+ * scenario-relative path. Remote assets are referenced, never copied.
+ */
+export declare function isRemoteUrl(src: string): boolean;
+/**
+ * Resolve a scenario-relative asset reference against its scenario
+ * directory — the shared containment-and-existence contract behind
+ * every shipped asset (soundtrack music, title-card logos).
+ *
+ * Returns `null` for remote URLs (used from where they live). Throws
+ * with an actionable message when the path escapes the scenario
+ * directory or the file does not exist — both would otherwise surface
+ * as a broken reference in the packed embed or the rendered video.
+ *
+ * @param configPath - The authored field, for error messages
+ *   (e.g. "soundtrack.musicSrc").
+ * @param expectation - What a valid reference looks like, appended to
+ *   the error (e.g. 'an MP3 inside the scenario directory').
+ */
+export declare function resolveScenarioAsset(scenarioDir: string, src: string, configPath: string, expectation: string): Promise<ScenarioAsset | null>;
+/**
+ * The image extensions the packed-embed deploy contract serves —
+ * derived from the canonical extension table so this can never drift
+ * from the server's allowlist. Notably NO svg (active content).
+ */
+export declare const IMAGE_EXTENSIONS: readonly string[];
+/**
+ * Resolve a title card's `logo_src` against its scenario directory,
+ * additionally enforcing the deploy contract's image formats — an
+ * unservable extension must fail at build time, not as a 404 (or a
+ * rejected deploy) later.
+ */
+export declare function resolveLogoAsset(scenarioDir: string, logoSrc: string, configPath: string): Promise<ScenarioAsset | null>;
+//# sourceMappingURL=scenario-assets.d.ts.map

package/src/util/scenario-assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario-assets.d.ts","sourceRoot":"","sources":["../../../src/util/scenario-assets.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAuB/B;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAIZ,CAAC;AAEnC;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAmB/B"}

package/src/util/scenario-assets.js

@@ -0,0 +1,71 @@
+import { access } from "node:fs/promises";
+import { isAbsolute, join, normalize } from "node:path";
+import { CONTENT_TYPE_BY_EXTENSION, finalExtension } from "../pack/bundle-contract.js";
+/**
+ * True when an asset src is a remote URL (has a scheme) rather than a
+ * scenario-relative path. Remote assets are referenced, never copied.
+ */
+export function isRemoteUrl(src) {
+    return /^[a-z][a-z0-9+.-]*:\/\//i.test(src);
+}
+/**
+ * Resolve a scenario-relative asset reference against its scenario
+ * directory — the shared containment-and-existence contract behind
+ * every shipped asset (soundtrack music, title-card logos).
+ *
+ * Returns `null` for remote URLs (used from where they live). Throws
+ * with an actionable message when the path escapes the scenario
+ * directory or the file does not exist — both would otherwise surface
+ * as a broken reference in the packed embed or the rendered video.
+ *
+ * @param configPath - The authored field, for error messages
+ *   (e.g. "soundtrack.musicSrc").
+ * @param expectation - What a valid reference looks like, appended to
+ *   the error (e.g. 'an MP3 inside the scenario directory').
+ */
+export async function resolveScenarioAsset(scenarioDir, src, configPath, expectation) {
+    if (isRemoteUrl(src))
+        return null;
+    const destRelPath = normalize(src).replace(/^\.\//, "");
+    if (isAbsolute(destRelPath) || destRelPath === ".." || destRelPath.startsWith("../")) {
+        throw new Error(`${configPath} "${src}" points outside the scenario directory.\n` +
+            `The reference must be ${expectation} so it can ship with the bundle,\n` +
+            "or an absolute URL.");
+    }
+    const sourcePath = join(scenarioDir, destRelPath);
+    try {
+        await access(sourcePath);
+    }
+    catch {
+        throw new Error(`${configPath} "${src}" not found at ${sourcePath}.\n` +
+            `Add the file (${expectation}), or fix the path in the config.`);
+    }
+    return { sourcePath, destRelPath };
+}
+/**
+ * The image extensions the packed-embed deploy contract serves —
+ * derived from the canonical extension table so this can never drift
+ * from the server's allowlist. Notably NO svg (active content).
+ */
+export const IMAGE_EXTENSIONS = Object.entries(CONTENT_TYPE_BY_EXTENSION)
+    .filter(([, contentType]) => contentType.startsWith("image/"))
+    .map(([extension]) => extension);
+/**
+ * Resolve a title card's `logo_src` against its scenario directory,
+ * additionally enforcing the deploy contract's image formats — an
+ * unservable extension must fail at build time, not as a 404 (or a
+ * rejected deploy) later.
+ */
+export async function resolveLogoAsset(scenarioDir, logoSrc, configPath) {
+    const asset = await resolveScenarioAsset(scenarioDir, logoSrc, configPath, "an image inside the scenario directory (e.g. ./logo.png)");
+    if (asset === null)
+        return null;
+    const extension = finalExtension(asset.destRelPath);
+    if (!IMAGE_EXTENSIONS.includes(extension)) {
+        throw new Error(`${configPath} "${logoSrc}" is not a supported image format.\n` +
+            `The deploy contract serves: ${IMAGE_EXTENSIONS.join(", ")}. ` +
+            "SVG is deliberately excluded (active content) — inline it in a view instead.");
+    }
+    return asset;
+}
+//# sourceMappingURL=scenario-assets.js.map