@scenar/cli 0.9.1 → 0.11.0

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

package/src/util/scenario-assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario-assets.js","sourceRoot":"","sources":["../../../src/util/scenario-assets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,EAAE,yBAAyB,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAevF;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,OAAO,0BAA0B,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,WAAmB,EACnB,GAAW,EACX,UAAkB,EAClB,WAAmB;IAEnB,IAAI,WAAW,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAElC,MAAM,WAAW,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACxD,IAAI,UAAU,CAAC,WAAW,CAAC,IAAI,WAAW,KAAK,IAAI,IAAI,WAAW,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACrF,MAAM,IAAI,KAAK,CACb,GAAG,UAAU,KAAK,GAAG,4CAA4C;YAC/D,yBAAyB,WAAW,oCAAoC;YACxE,qBAAqB,CACxB,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IAClD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,GAAG,UAAU,KAAK,GAAG,kBAAkB,UAAU,KAAK;YACpD,iBAAiB,WAAW,mCAAmC,CAClE,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAsB,MAAM,CAAC,OAAO,CAC/D,yBAAyB,CAC1B;KACE,MAAM,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;KAC7D,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,WAAmB,EACnB,OAAe,EACf,UAAkB;IAElB,MAAM,KAAK,GAAG,MAAM,oBAAoB,CACtC,WAAW,EACX,OAAO,EACP,UAAU,EACV,0DAA0D,CAC3D,CAAC;IACF,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAEhC,MAAM,SAAS,GAAG,cAAc,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACpD,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,GAAG,UAAU,KAAK,OAAO,sCAAsC;YAC7D,+BAA+B,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YAC9D,8EAA8E,CACjF,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/src/util/scenario-assets.ts

@@ -0,0 +1,111 @@
+import { access } from "node:fs/promises";
+import { isAbsolute, join, normalize } from "node:path";
+import { CONTENT_TYPE_BY_EXTENSION, finalExtension } from "../pack/bundle-contract.js";
+
+/**
+ * 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 function isRemoteUrl(src: string): boolean {
+  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: string,
+  src: string,
+  configPath: string,
+  expectation: string,
+): Promise<ScenarioAsset | null> {
+  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: readonly string[] = 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: string,
+  logoSrc: string,
+  configPath: string,
+): Promise<ScenarioAsset | null> {
+  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;
+}

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

@@ -0,0 +1,34 @@
+import { type ScenarioAsset } from "./scenario-assets.js";
+export { isRemoteUrl } from "./scenario-assets.js";
+/** Absolute filesystem locations of the built-in SFX asset files. */
+export interface SfxAssetPaths {
+    readonly click: string;
+    readonly keystroke: string;
+}
+/**
+ * Where the built-in SFX set lives inside a staged render public dir and
+ * inside a packed bundle — one convention, shared with the composition's
+ * `sfxSrcs` default and the embed entry's `soundtrackSources`, so every
+ * consumer looks in the same place.
+ */
+export declare const SFX_DEST_PATHS: SfxAssetPaths;
+/**
+ * Resolve the built-in SFX asset files from `@scenar/react`, using the
+ * given directory as the resolution context — the scenario directory, so
+ * the assets come from the same installed `@scenar/react` the generated
+ * entry imports.
+ */
+export declare function resolveSfxAssetPaths(fromDir: string): SfxAssetPaths;
+/** A scenario-local music asset: where it is, and where it ships. */
+export type MusicAsset = ScenarioAsset;
+/**
+ * Resolve a soundtrack's `music_src` against its scenario directory —
+ * the shared {@link resolveScenarioAsset} contract with music wording.
+ *
+ * Returns `null` for remote URLs (played from where they live). Throws
+ * with an actionable message when the referenced file does not exist or
+ * the path escapes the scenario directory — both would otherwise surface
+ * as a silently music-less video or a 404 in the packed embed.
+ */
+export declare function resolveMusicAsset(scenarioDir: string, musicSrc: string): Promise<MusicAsset | null>;
+//# sourceMappingURL=soundtrack-assets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"soundtrack-assets.d.ts","sourceRoot":"","sources":["../../../src/util/soundtrack-assets.ts"],"names":[],"mappings":"AAEA,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,aAG5B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAenE;AAED,qEAAqE;AACrE,MAAM,MAAM,UAAU,GAAG,aAAa,CAAC;AAEvC;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAO5B"}

package/src/util/soundtrack-assets.js

@@ -0,0 +1,48 @@
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { resolveScenarioAsset } from "./scenario-assets.js";
+export { isRemoteUrl } from "./scenario-assets.js";
+/**
+ * Where the built-in SFX set lives inside a staged render public dir and
+ * inside a packed bundle — one convention, shared with the composition's
+ * `sfxSrcs` default and the embed entry's `soundtrackSources`, so every
+ * consumer looks in the same place.
+ */
+export const SFX_DEST_PATHS = {
+    click: "soundtrack/sfx/click.mp3",
+    keystroke: "soundtrack/sfx/keystroke.mp3",
+};
+/**
+ * Resolve the built-in SFX asset files from `@scenar/react`, using the
+ * given directory as the resolution context — the scenario directory, so
+ * the assets come from the same installed `@scenar/react` the generated
+ * entry imports.
+ */
+export function resolveSfxAssetPaths(fromDir) {
+    const require = createRequire(join(fromDir, "__scenar_resolver__.js"));
+    try {
+        return {
+            click: require.resolve("@scenar/react/assets/sfx/click.mp3"),
+            keystroke: require.resolve("@scenar/react/assets/sfx/keystroke.mp3"),
+        };
+    }
+    catch {
+        throw new Error("soundtrack.sfx is enabled, but @scenar/react's sound-effect assets could not be\n" +
+            `resolved from ${fromDir}.\n\n` +
+            "The default SFX set ships inside @scenar/react (assets/sfx/). Install or update\n" +
+            "it in this project: pnpm add @scenar/react");
+    }
+}
+/**
+ * Resolve a soundtrack's `music_src` against its scenario directory —
+ * the shared {@link resolveScenarioAsset} contract with music wording.
+ *
+ * Returns `null` for remote URLs (played from where they live). Throws
+ * with an actionable message when the referenced file does not exist or
+ * the path escapes the scenario directory — both would otherwise surface
+ * as a silently music-less video or a 404 in the packed embed.
+ */
+export async function resolveMusicAsset(scenarioDir, musicSrc) {
+    return resolveScenarioAsset(scenarioDir, musicSrc, "soundtrack.musicSrc", "an MP3 inside the scenario directory (e.g. ./soundtrack/music.mp3)");
+}
+//# sourceMappingURL=soundtrack-assets.js.map

package/src/util/soundtrack-assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"soundtrack-assets.js","sourceRoot":"","sources":["../../../src/util/soundtrack-assets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,oBAAoB,EAAsB,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAQnD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAkB;IAC3C,KAAK,EAAE,0BAA0B;IACjC,SAAS,EAAE,8BAA8B;CAC1C,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,wBAAwB,CAAC,CAAC,CAAC;IACvE,IAAI,CAAC;QACH,OAAO;YACL,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,oCAAoC,CAAC;YAC5D,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,wCAAwC,CAAC;SACrE,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,mFAAmF;YACjF,iBAAiB,OAAO,OAAO;YAC/B,mFAAmF;YACnF,4CAA4C,CAC/C,CAAC;IACJ,CAAC;AACH,CAAC;AAKD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,WAAmB,EACnB,QAAgB;IAEhB,OAAO,oBAAoB,CACzB,WAAW,EACX,QAAQ,EACR,qBAAqB,EACrB,oEAAoE,CACrE,CAAC;AACJ,CAAC"}

package/src/util/soundtrack-assets.ts

@@ -0,0 +1,69 @@
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { resolveScenarioAsset, type ScenarioAsset } from "./scenario-assets.js";
+
+export { isRemoteUrl } from "./scenario-assets.js";
+
+/** Absolute filesystem locations of the built-in SFX asset files. */
+export interface SfxAssetPaths {
+  readonly click: string;
+  readonly keystroke: string;
+}
+
+/**
+ * Where the built-in SFX set lives inside a staged render public dir and
+ * inside a packed bundle — one convention, shared with the composition's
+ * `sfxSrcs` default and the embed entry's `soundtrackSources`, so every
+ * consumer looks in the same place.
+ */
+export const SFX_DEST_PATHS: SfxAssetPaths = {
+  click: "soundtrack/sfx/click.mp3",
+  keystroke: "soundtrack/sfx/keystroke.mp3",
+};
+
+/**
+ * Resolve the built-in SFX asset files from `@scenar/react`, using the
+ * given directory as the resolution context — the scenario directory, so
+ * the assets come from the same installed `@scenar/react` the generated
+ * entry imports.
+ */
+export function resolveSfxAssetPaths(fromDir: string): SfxAssetPaths {
+  const require = createRequire(join(fromDir, "__scenar_resolver__.js"));
+  try {
+    return {
+      click: require.resolve("@scenar/react/assets/sfx/click.mp3"),
+      keystroke: require.resolve("@scenar/react/assets/sfx/keystroke.mp3"),
+    };
+  } catch {
+    throw new Error(
+      "soundtrack.sfx is enabled, but @scenar/react's sound-effect assets could not be\n" +
+        `resolved from ${fromDir}.\n\n` +
+        "The default SFX set ships inside @scenar/react (assets/sfx/). Install or update\n" +
+        "it in this project: pnpm add @scenar/react",
+    );
+  }
+}
+
+/** A scenario-local music asset: where it is, and where it ships. */
+export type MusicAsset = ScenarioAsset;
+
+/**
+ * Resolve a soundtrack's `music_src` against its scenario directory —
+ * the shared {@link resolveScenarioAsset} contract with music wording.
+ *
+ * Returns `null` for remote URLs (played from where they live). Throws
+ * with an actionable message when the referenced file does not exist or
+ * the path escapes the scenario directory — both would otherwise surface
+ * as a silently music-less video or a 404 in the packed embed.
+ */
+export async function resolveMusicAsset(
+  scenarioDir: string,
+  musicSrc: string,
+): Promise<MusicAsset | null> {
+  return resolveScenarioAsset(
+    scenarioDir,
+    musicSrc,
+    "soundtrack.musicSrc",
+    "an MP3 inside the scenario directory (e.g. ./soundtrack/music.mp3)",
+  );
+}

package/src/validate/scenario-validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scenario-validator.d.ts","sourceRoot":"","sources":["../../../src/validate/scenario-validator.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;CAC7C;AAgBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,GAAG,gBAAgB,CAcpE"}
+{"version":3,"file":"scenario-validator.d.ts","sourceRoot":"","sources":["../../../src/validate/scenario-validator.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;CAC7C;AAgBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,GAAG,gBAAgB,CAgBpE"}

package/src/validate/scenario-validator.js

@@ -25,6 +25,8 @@ export function validateScenario(scenario) {
     const obj = scenario;
     validateViewport(obj["viewport"], errors);
     validateSteps(obj["steps"], errors);
+    validateSoundtrack(obj["soundtrack"], errors);
+    validateTitleCards(obj["titleCards"], errors);
     return { valid: errors.length === 0, errors };
 }
 function validateViewport(viewport, errors) {
@@ -42,6 +44,71 @@ function validateViewport(viewport, errors) {
         errors.push({ path: "viewport.height", reason: "height must be a positive integer." });
     }
 }
+function validateSoundtrack(soundtrack, errors) {
+    if (soundtrack === undefined || soundtrack === null)
+        return;
+    if (typeof soundtrack !== "object" || Array.isArray(soundtrack)) {
+        errors.push({ path: "soundtrack", reason: "soundtrack must be an object." });
+        return;
+    }
+    const st = soundtrack;
+    if (st["musicSrc"] !== undefined) {
+        if (typeof st["musicSrc"] !== "string" || st["musicSrc"].length === 0) {
+            errors.push({
+                path: "soundtrack.musicSrc",
+                reason: "musicSrc must be a non-empty asset reference (e.g. \"./soundtrack/music.mp3\").",
+            });
+        }
+    }
+    validateVolume(st["musicVolume"], "soundtrack.musicVolume", errors);
+    validateVolume(st["duckingVolume"], "soundtrack.duckingVolume", errors);
+    if (st["sfx"] !== undefined && typeof st["sfx"] !== "boolean") {
+        errors.push({ path: "soundtrack.sfx", reason: "sfx must be a boolean." });
+    }
+}
+function validateVolume(value, path, errors) {
+    if (value === undefined)
+        return;
+    if (typeof value !== "number" || value < 0 || value > 1) {
+        errors.push({ path, reason: "must be a number between 0.0 and 1.0." });
+    }
+}
+function validateTitleCards(titleCards, errors) {
+    if (titleCards === undefined || titleCards === null)
+        return;
+    if (typeof titleCards !== "object" || Array.isArray(titleCards)) {
+        errors.push({ path: "titleCards", reason: "titleCards must be an object." });
+        return;
+    }
+    const cards = titleCards;
+    for (const side of ["intro", "outro"]) {
+        if (cards[side] !== undefined) {
+            validateTitleCard(cards[side], `titleCards.${side}`, errors);
+        }
+    }
+}
+function validateTitleCard(card, path, errors) {
+    if (card === null || typeof card !== "object" || Array.isArray(card)) {
+        errors.push({ path, reason: "card must be an object." });
+        return;
+    }
+    const c = card;
+    if (typeof c["title"] !== "string" || c["title"].length === 0) {
+        errors.push({ path: `${path}.title`, reason: "title is required and must be a non-empty string." });
+    }
+    for (const field of ["subtitle", "logoSrc", "ctaText"]) {
+        if (c[field] !== undefined) {
+            if (typeof c[field] !== "string" || c[field].length === 0) {
+                errors.push({ path: `${path}.${field}`, reason: `${field} must be a non-empty string when present.` });
+            }
+        }
+    }
+    if (c["durationMs"] !== undefined) {
+        if (typeof c["durationMs"] !== "number" || c["durationMs"] <= 0) {
+            errors.push({ path: `${path}.durationMs`, reason: "durationMs must be a positive integer." });
+        }
+    }
+}
 function validateSteps(steps, errors) {
     if (!Array.isArray(steps)) {
         errors.push({ path: "steps", reason: "steps must be an array." });
@@ -69,6 +136,21 @@ function validateStep(step, path, errors) {
             errors.push({ path: `${path}.delayMs`, reason: "delayMs must be a non-negative integer." });
         }
     }
+    if (s["presenter"] !== undefined) {
+        if (typeof s["presenter"] !== "boolean") {
+            errors.push({ path: `${path}.presenter`, reason: "presenter must be a boolean." });
+        }
+        else if (s["presenter"] === true &&
+            (typeof s["narrationText"] !== "string" || s["narrationText"].length === 0)) {
+            // Cross-field rule (see the Step.presenter proto doc comment):
+            // caught here so `scenar validate` flags the contradiction before
+            // the paid `scenar presenter` command runs.
+            errors.push({
+                path: `${path}.presenter`,
+                reason: "presenter requires narration_text — a presenter clip is derived from the step's narration audio.",
+            });
+        }
+    }
     if (s["interactions"] !== undefined) {
         if (!Array.isArray(s["interactions"])) {
             errors.push({ path: `${path}.interactions`, reason: "interactions must be an array." });

package/src/validate/scenario-validator.js.map

@@ -1 +1 @@
-{"version":3,"file":"scenario-validator.js","sourceRoot":"","sources":["../../../src/validate/scenario-validator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scenario-validator.js","sourceRoot":"","sources":["../../../src/validate/scenario-validator.ts"],"names":[],"mappings":"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"}

package/src/validate/scenario-validator.ts

@@ -44,6 +44,8 @@ export function validateScenario(scenario: unknown): ValidationResult {
 
   validateViewport(obj["viewport"], errors);
   validateSteps(obj["steps"], errors);
+  validateSoundtrack(obj["soundtrack"], errors);
+  validateTitleCards(obj["titleCards"], errors);
 
   return { valid: errors.length === 0, errors };
 }
@@ -69,6 +71,97 @@ function validateViewport(
   }
 }
 
+function validateSoundtrack(
+  soundtrack: unknown,
+  errors: ValidationError[],
+): void {
+  if (soundtrack === undefined || soundtrack === null) return;
+
+  if (typeof soundtrack !== "object" || Array.isArray(soundtrack)) {
+    errors.push({ path: "soundtrack", reason: "soundtrack must be an object." });
+    return;
+  }
+
+  const st = soundtrack as Record<string, unknown>;
+
+  if (st["musicSrc"] !== undefined) {
+    if (typeof st["musicSrc"] !== "string" || st["musicSrc"].length === 0) {
+      errors.push({
+        path: "soundtrack.musicSrc",
+        reason: "musicSrc must be a non-empty asset reference (e.g. \"./soundtrack/music.mp3\").",
+      });
+    }
+  }
+
+  validateVolume(st["musicVolume"], "soundtrack.musicVolume", errors);
+  validateVolume(st["duckingVolume"], "soundtrack.duckingVolume", errors);
+
+  if (st["sfx"] !== undefined && typeof st["sfx"] !== "boolean") {
+    errors.push({ path: "soundtrack.sfx", reason: "sfx must be a boolean." });
+  }
+}
+
+function validateVolume(
+  value: unknown,
+  path: string,
+  errors: ValidationError[],
+): void {
+  if (value === undefined) return;
+  if (typeof value !== "number" || value < 0 || value > 1) {
+    errors.push({ path, reason: "must be a number between 0.0 and 1.0." });
+  }
+}
+
+function validateTitleCards(
+  titleCards: unknown,
+  errors: ValidationError[],
+): void {
+  if (titleCards === undefined || titleCards === null) return;
+
+  if (typeof titleCards !== "object" || Array.isArray(titleCards)) {
+    errors.push({ path: "titleCards", reason: "titleCards must be an object." });
+    return;
+  }
+
+  const cards = titleCards as Record<string, unknown>;
+  for (const side of ["intro", "outro"] as const) {
+    if (cards[side] !== undefined) {
+      validateTitleCard(cards[side], `titleCards.${side}`, errors);
+    }
+  }
+}
+
+function validateTitleCard(
+  card: unknown,
+  path: string,
+  errors: ValidationError[],
+): void {
+  if (card === null || typeof card !== "object" || Array.isArray(card)) {
+    errors.push({ path, reason: "card must be an object." });
+    return;
+  }
+
+  const c = card as Record<string, unknown>;
+
+  if (typeof c["title"] !== "string" || c["title"].length === 0) {
+    errors.push({ path: `${path}.title`, reason: "title is required and must be a non-empty string." });
+  }
+
+  for (const field of ["subtitle", "logoSrc", "ctaText"] as const) {
+    if (c[field] !== undefined) {
+      if (typeof c[field] !== "string" || (c[field] as string).length === 0) {
+        errors.push({ path: `${path}.${field}`, reason: `${field} must be a non-empty string when present.` });
+      }
+    }
+  }
+
+  if (c["durationMs"] !== undefined) {
+    if (typeof c["durationMs"] !== "number" || c["durationMs"] <= 0) {
+      errors.push({ path: `${path}.durationMs`, reason: "durationMs must be a positive integer." });
+    }
+  }
+}
+
 function validateSteps(
   steps: unknown,
   errors: ValidationError[],
@@ -110,6 +203,23 @@ function validateStep(
     }
   }
 
+  if (s["presenter"] !== undefined) {
+    if (typeof s["presenter"] !== "boolean") {
+      errors.push({ path: `${path}.presenter`, reason: "presenter must be a boolean." });
+    } else if (
+      s["presenter"] === true &&
+      (typeof s["narrationText"] !== "string" || s["narrationText"].length === 0)
+    ) {
+      // Cross-field rule (see the Step.presenter proto doc comment):
+      // caught here so `scenar validate` flags the contradiction before
+      // the paid `scenar presenter` command runs.
+      errors.push({
+        path: `${path}.presenter`,
+        reason: "presenter requires narration_text — a presenter clip is derived from the step's narration audio.",
+      });
+    }
+  }
+
   if (s["interactions"] !== undefined) {
     if (!Array.isArray(s["interactions"])) {
       errors.push({ path: `${path}.interactions`, reason: "interactions must be an array." });