@scenar/cli 0.9.1 → 0.11.0

package/src/pack/run-pack.ts

@@ -1,7 +1,14 @@
-import { resolve, join, basename } from "node:path";
+import { resolve, join, basename, dirname } from "node:path";
 import { stat, mkdir, writeFile, rm, readdir, copyFile, access } from "node:fs/promises";
 import { detectRenderExport } from "../render/detect-render-export.js";
 import { resolveProvidersPath } from "../render/resolve-providers.js";
+import type { AuthoredSoundtrack, AuthoredTitleCards } from "../util/load-ts.js";
+import {
+  SFX_DEST_PATHS,
+  resolveMusicAsset,
+  resolveSfxAssetPaths,
+} from "../util/soundtrack-assets.js";
+import { resolveLogoAsset } from "../util/scenario-assets.js";
 import { generateEmbedEntry, generateEmbedHtml } from "./generate-embed-entry.js";
 import { collectPackShots, type CollectedPackShots } from "./collect-pack-shots.js";
 import { runViteBuild } from "./build.js";
@@ -13,7 +20,7 @@ import {
   verifyManifestFilesExist,
   type PackManifest,
 } from "./pack-manifest.js";
-import { DEFAULT_VIEWPORT } from "./viewport.js";
+import { DEFAULT_VIEWPORT, resolvePackViewport } from "./viewport.js";
 
 /**
  * Generator version stamped into scenario.json (kept in sync with the CLI).
@@ -27,9 +34,14 @@ export interface RunPackOptions {
   readonly scenarioDir: string;
   /** Output directory for the bundle (default: ./<scenario-id>-bundle). */
   readonly outDir?: string;
-  /** Canonical viewport width in px (default: {@link DEFAULT_VIEWPORT}.width). */
+  /**
+   * Canonical viewport width in px. Omitted -> the scenario's own authored
+   * viewport (`createScenario({ viewport })` or an exported `viewport`
+   * constant) applies; a scenario that authors none falls back to
+   * {@link DEFAULT_VIEWPORT}. Explicit flags always win over both.
+   */
   readonly width?: number;
-  /** Shell/container height in px (default: {@link DEFAULT_VIEWPORT}.height). */
+  /** Shell/container height in px. Same resolution chain as `width`. */
   readonly shellHeight?: number;
   /**
    * Float the scenario on a backdrop with a window shadow (screen-recording
@@ -50,6 +62,7 @@ export interface PackResult {
   readonly renderFilePath: string;
   readonly providersPath: string | null;
   readonly hasNarration: boolean;
+  readonly hasPresenter: boolean;
   /**
    * The declared shot names recorded in scenario.json (empty = the scenario
    * authoritatively declares none), or undefined when the steps module could
@@ -83,8 +96,6 @@ export async function runPack(options: RunPackOptions): Promise<PackResult> {
 
   const scenarioId = basename(scenarioDir);
   const outDir = options.outDir ? resolve(options.outDir) : resolve(`./${scenarioId}-bundle`);
-  const width = options.width ?? DEFAULT_VIEWPORT.width;
-  const shellHeight = options.shellHeight ?? DEFAULT_VIEWPORT.height;
 
   // The entry must live inside the scenario directory so the bundler's
   // node_modules resolution walks up into the consumer project.
@@ -94,21 +105,41 @@ export async function runPack(options: RunPackOptions): Promise<PackResult> {
     const renderFilePath = await detectRenderExport(scenarioDir);
     const providersPath = await resolveProvidersPath(scenarioDir);
     const hasNarration = await fileExists(join(scenarioDir, "narration", "manifest.json"));
+    const hasPresenter = await fileExists(join(scenarioDir, "presenter", "manifest.json"));
 
     onLog(`Scenario:  ${scenarioId}`);
     onLog(`Render:    ${renderFilePath}`);
     onLog(`Providers: ${providersPath ?? "none"}`);
     onLog(`Narration: ${hasNarration ? "yes (manifest found)" : "none"}`);
+    onLog(`Presenter: ${hasPresenter ? "yes (manifest found)" : "none"}`);
     onLog(`Output:    ${outDir}`);
 
-    // 1. Discover the declared shots by SSR-loading the steps module (same
-    //    Vite resolution as the build below). Before the build on purpose:
-    //    authoring errors — bad shot names, no steps array — fail fast here,
-    //    without paying for a bundle. An import failure is tolerated: the
-    //    shots are then unknown and scenario.json omits the key.
+    // 1. Discover the declared shots — and the authored viewport — by
+    //    SSR-loading the steps module (same Vite resolution as the build
+    //    below). Before the build on purpose: authoring errors — bad shot
+    //    names, no steps array — fail fast here, without paying for a
+    //    bundle. An import failure is tolerated: the shots are then unknown
+    //    and scenario.json omits the key.
     const collectedShots = await collectPackShots(scenarioDir);
     onLog(`Shots:     ${describeCollectedShots(collectedShots)}`);
 
+    // Canonical viewport: explicit options > the scenario's authored
+    // viewport > the packer default. Authored viewports used to be silently
+    // ignored (the authoring docs demonstrated `createScenario({ viewport })`
+    // while pack only ever read its own options); the source is logged so a
+    // surprising size is one log line from its explanation.
+    const resolvedViewport = resolvePackViewport(
+      options,
+      collectedShots.recorded ? collectedShots.authoredViewport : null,
+    );
+    const { width, height: shellHeight } = resolvedViewport;
+    const viewportSourceLabel = {
+      explicit: "explicit",
+      authored: "authored by the scenario",
+      default: "packer default",
+    }[resolvedViewport.source];
+    onLog(`Viewport:  ${width}x${shellHeight} (${viewportSourceLabel})`);
+
     // 2. Generate the browser entry + index.html into the temp dir.
     const stage = options.stage ?? false;
     const entrySource = generateEmbedEntry({
@@ -116,6 +147,7 @@ export async function runPack(options: RunPackOptions): Promise<PackResult> {
       renderFilePath,
       scenarioId,
       hasNarration,
+      hasPresenter,
       providersPath,
       canonicalWidth: width,
       shellHeight,
@@ -135,7 +167,48 @@ export async function runPack(options: RunPackOptions): Promise<PackResult> {
     //    ./narration/manifest.json at runtime and resolves each clip's
     //    relative src against it, so both must ship in the bundle.
     if (hasNarration) {
-      await copyNarration(scenarioDir, outDir);
+      await copyClipTrack(scenarioDir, outDir, "narration", ".mp3");
+    }
+
+    // 4a. Copy the presenter manifest + clips — the same runtime contract
+    //     as narration: the embed fetches ./presenter/manifest.json and
+    //     resolves each clip's relative src against it. CSP is
+    //     `media-src 'self'`, so the clips must ship in the bundle.
+    if (hasPresenter) {
+      await copyClipTrack(scenarioDir, outDir, "presenter", ".mp4");
+    }
+
+    // 4b. Copy the soundtrack's assets: the authored music file (at its
+    //     scenario-relative path, which is what the embed references) and
+    //     the built-in SFX set from @scenar/react. Discovery rides the same
+    //     SSR load as the shots; when the module was not loadable, the
+    //     soundtrack (if any) cannot ship — warn rather than silently
+    //     packing an embed whose audio 404s.
+    if (collectedShots.recorded) {
+      if (collectedShots.authoredSoundtrack) {
+        const copied = await copySoundtrack(
+          scenarioDir,
+          outDir,
+          collectedShots.authoredSoundtrack,
+        );
+        if (copied > 0) onLog(`Soundtrack: ${copied} audio file(s) copied into the bundle`);
+      }
+      // 4c. Copy title-card logos at their scenario-relative paths (the
+      //     card component references them by that same path). Discovery
+      //     rides the same SSR load as the shots and the soundtrack.
+      if (collectedShots.authoredTitleCards) {
+        const copied = await copyTitleCardLogos(
+          scenarioDir,
+          outDir,
+          collectedShots.authoredTitleCards,
+        );
+        if (copied > 0) onLog(`Cards: ${copied} logo file(s) copied into the bundle`);
+      }
+    } else {
+      onLog(
+        "Warning: steps module not loadable under Node — if this scenario authors a " +
+          "soundtrack or title cards, their asset files were NOT copied into the bundle.",
+      );
     }
 
     // 5. Write the required scenario.json descriptor, recording the canonical
@@ -170,6 +243,7 @@ export async function runPack(options: RunPackOptions): Promise<PackResult> {
       renderFilePath,
       providersPath,
       hasNarration,
+      hasPresenter,
       shots: collectedShots.recorded ? collectedShots.shots : undefined,
       manifest,
       totalBytes,
@@ -182,24 +256,95 @@ export async function runPack(options: RunPackOptions): Promise<PackResult> {
 }
 
 /**
- * Copy the narration manifest and every *.mp3 from <scenarioDir>/narration into
- * <outDir>/narration. The manifest is the runtime index the embed fetches; the
- * mp3s are the clips it references by relative src.
+ * Copy one clip track's manifest and media (narration mp3s, presenter
+ * mp4s) from <scenarioDir>/<trackDir> into <outDir>/<trackDir>. The
+ * manifest is the runtime index the embed fetches; the clips are what it
+ * references by relative src. Cache files never ship.
  */
-async function copyNarration(scenarioDir: string, outDir: string): Promise<void> {
-  const srcDir = join(scenarioDir, "narration");
-  const destDir = join(outDir, "narration");
+async function copyClipTrack(
+  scenarioDir: string,
+  outDir: string,
+  trackDir: string,
+  extension: string,
+): Promise<void> {
+  const srcDir = join(scenarioDir, trackDir);
+  const destDir = join(outDir, trackDir);
   await mkdir(destDir, { recursive: true });
   const entries = await readdir(srcDir, { withFileTypes: true });
   for (const entry of entries) {
     if (!entry.isFile()) continue;
     const name = entry.name.toLowerCase();
-    if (name === "manifest.json" || name.endsWith(".mp3")) {
+    if (name === "manifest.json" || name.endsWith(extension)) {
       await copyFile(join(srcDir, entry.name), join(destDir, entry.name));
     }
   }
 }
 
+/**
+ * Copy the soundtrack's audio into the bundle: the authored music file at
+ * its scenario-relative path (the embed references it by that same path),
+ * and the built-in SFX set from @scenar/react at the shared
+ * {@link SFX_DEST_PATHS} locations the generated entry points at. Returns
+ * the number of files copied. Remote music URLs copy nothing.
+ */
+async function copySoundtrack(
+  scenarioDir: string,
+  outDir: string,
+  soundtrack: AuthoredSoundtrack,
+): Promise<number> {
+  let copied = 0;
+
+  if (soundtrack.musicSrc) {
+    const music = await resolveMusicAsset(scenarioDir, soundtrack.musicSrc);
+    if (music) {
+      const dest = join(outDir, music.destRelPath);
+      await mkdir(dirname(dest), { recursive: true });
+      await copyFile(music.sourcePath, dest);
+      copied += 1;
+    }
+  }
+
+  if (soundtrack.sfx) {
+    const sfxPaths = resolveSfxAssetPaths(scenarioDir);
+    for (const sound of ["click", "keystroke"] as const) {
+      const dest = join(outDir, SFX_DEST_PATHS[sound]);
+      await mkdir(dirname(dest), { recursive: true });
+      await copyFile(sfxPaths[sound], dest);
+      copied += 1;
+    }
+  }
+
+  return copied;
+}
+
+/**
+ * Copy title-card logos into the bundle at their scenario-relative paths.
+ * A logo shared by intro and outro copies once; remote URLs copy nothing.
+ * Returns the number of files copied.
+ */
+async function copyTitleCardLogos(
+  scenarioDir: string,
+  outDir: string,
+  titleCards: AuthoredTitleCards,
+): Promise<number> {
+  let copied = 0;
+  const copiedPaths = new Set<string>();
+
+  for (const side of ["intro", "outro"] as const) {
+    const logoSrc = titleCards[side]?.logoSrc;
+    if (!logoSrc) continue;
+    const logo = await resolveLogoAsset(scenarioDir, logoSrc, `titleCards.${side}.logoSrc`);
+    if (!logo || copiedPaths.has(logo.destRelPath)) continue;
+    const dest = join(outDir, logo.destRelPath);
+    await mkdir(dirname(dest), { recursive: true });
+    await copyFile(logo.sourcePath, dest);
+    copiedPaths.add(logo.destRelPath);
+    copied += 1;
+  }
+
+  return copied;
+}
+
 /** One log-friendly line for the shot discovery outcome. */
 function describeCollectedShots(collected: CollectedPackShots): string {
   if (!collected.recorded) {

package/src/pack/viewport.d.ts

@@ -33,4 +33,21 @@ export declare const DEFAULT_VIEWPORT: Viewport;
  * accept a recorded viewport while falling back cleanly for older bundles.
  */
 export declare function parseViewport(value: unknown): Viewport | null;
+/** A resolved pack viewport plus where each number came from (for the log). */
+export interface ResolvedPackViewport extends Viewport {
+    readonly source: "explicit" | "authored" | "default";
+}
+/**
+ * Resolve the canonical viewport a bundle is packed at: explicit options
+ * (CLI flags / MCP params) > the scenario's own authored viewport > the
+ * packer default. Width and height resolve as a pair — an explicit *partial*
+ * override (only `--width`) still counts as explicit, filling the other axis
+ * from the authored viewport when present, else the default — and the
+ * source names the strongest contributor so the pack log can explain a
+ * surprising size in one line.
+ */
+export declare function resolvePackViewport(options: {
+    readonly width?: number;
+    readonly shellHeight?: number;
+}, authored: Viewport | null): ResolvedPackViewport;
 //# sourceMappingURL=viewport.d.ts.map

package/src/pack/viewport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"viewport.d.ts","sourceRoot":"","sources":["../../../src/pack/viewport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,QAAQ;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAsC,CAAC;AAEtE;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAK7D"}
+{"version":3,"file":"viewport.d.ts","sourceRoot":"","sources":["../../../src/pack/viewport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,QAAQ;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAsC,CAAC;AAEtE;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAK7D;AAED,+EAA+E;AAC/E,MAAM,WAAW,oBAAqB,SAAQ,QAAQ;IACpD,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;CACtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EACnE,QAAQ,EAAE,QAAQ,GAAG,IAAI,GACxB,oBAAoB,CAUtB"}

package/src/pack/viewport.js

@@ -19,6 +19,25 @@ export function parseViewport(value) {
         return null;
     return { width, height };
 }
+/**
+ * Resolve the canonical viewport a bundle is packed at: explicit options
+ * (CLI flags / MCP params) > the scenario's own authored viewport > the
+ * packer default. Width and height resolve as a pair — an explicit *partial*
+ * override (only `--width`) still counts as explicit, filling the other axis
+ * from the authored viewport when present, else the default — and the
+ * source names the strongest contributor so the pack log can explain a
+ * surprising size in one line.
+ */
+export function resolvePackViewport(options, authored) {
+    const width = options.width ?? authored?.width ?? DEFAULT_VIEWPORT.width;
+    const height = options.shellHeight ?? authored?.height ?? DEFAULT_VIEWPORT.height;
+    const source = options.width !== undefined || options.shellHeight !== undefined
+        ? "explicit"
+        : authored
+            ? "authored"
+            : "default";
+    return { width, height, source };
+}
 function isPositiveInt(value) {
     return typeof value === "number" && Number.isInteger(value) && value > 0;
 }

package/src/pack/viewport.js.map

@@ -1 +1 @@
-{"version":3,"file":"viewport.js","sourceRoot":"","sources":["../../../src/pack/viewport.ts"],"names":[],"mappings":"AAsBA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAa,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AAEtE;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7D,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,KAAgC,CAAC;IAC3D,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACjE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC3B,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC;AAC3E,CAAC"}
+{"version":3,"file":"viewport.js","sourceRoot":"","sources":["../../../src/pack/viewport.ts"],"names":[],"mappings":"AAsBA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAa,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AAEtE;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7D,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,KAAgC,CAAC;IAC3D,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACjE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC3B,CAAC;AAOD;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAmE,EACnE,QAAyB;IAEzB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,QAAQ,EAAE,KAAK,IAAI,gBAAgB,CAAC,KAAK,CAAC;IACzE,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW,IAAI,QAAQ,EAAE,MAAM,IAAI,gBAAgB,CAAC,MAAM,CAAC;IAClF,MAAM,MAAM,GACV,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS;QAC9D,CAAC,CAAC,UAAU;QACZ,CAAC,CAAC,QAAQ;YACR,CAAC,CAAC,UAAU;YACZ,CAAC,CAAC,SAAS,CAAC;IAClB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AACnC,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC;AAC3E,CAAC"}

package/src/pack/viewport.ts

@@ -41,6 +41,35 @@ export function parseViewport(value: unknown): Viewport | null {
   return { width, height };
 }
 
+/** A resolved pack viewport plus where each number came from (for the log). */
+export interface ResolvedPackViewport extends Viewport {
+  readonly source: "explicit" | "authored" | "default";
+}
+
+/**
+ * Resolve the canonical viewport a bundle is packed at: explicit options
+ * (CLI flags / MCP params) > the scenario's own authored viewport > the
+ * packer default. Width and height resolve as a pair — an explicit *partial*
+ * override (only `--width`) still counts as explicit, filling the other axis
+ * from the authored viewport when present, else the default — and the
+ * source names the strongest contributor so the pack log can explain a
+ * surprising size in one line.
+ */
+export function resolvePackViewport(
+  options: { readonly width?: number; readonly shellHeight?: number },
+  authored: Viewport | null,
+): ResolvedPackViewport {
+  const width = options.width ?? authored?.width ?? DEFAULT_VIEWPORT.width;
+  const height = options.shellHeight ?? authored?.height ?? DEFAULT_VIEWPORT.height;
+  const source =
+    options.width !== undefined || options.shellHeight !== undefined
+      ? "explicit"
+      : authored
+        ? "authored"
+        : "default";
+  return { width, height, source };
+}
+
 function isPositiveInt(value: unknown): value is number {
   return typeof value === "number" && Number.isInteger(value) && value > 0;
 }

package/src/presenter/heygen-client.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Minimal HeyGen API client for `scenar presenter` — deliberately an
+ * internal module of the CLI, not published API. Shaped so a second
+ * avatar provider could slot in behind the same function signatures,
+ * but the interface is not exported until a second provider is a
+ * concrete need (the TTS-provider precedent).
+ *
+ * Endpoints and response fields follow the live Gate 0 transcript:
+ * `POST /v3/assets` (multipart) → `data.asset_id`;
+ * `POST /v3/videos` (`type: "avatar"`, `audio_asset_id`) →
+ * `data.video_id`; `GET /v3/videos/{id}` → `data.status`
+ * (`completed`/`failed`), `data.video_url`, `data.failure_message`.
+ *
+ * BYO key, no Scenar-side proxying — identical to the TTS providers.
+ * Native fetch, no new runtime dependencies.
+ */
+/** Engine flag values → HeyGen's API vocabulary. */
+export declare const HEYGEN_ENGINE_TYPES: {
+    readonly iii: "avatar_iii";
+    readonly iv: "avatar_iv";
+};
+export type HeygenEngineFlag = keyof typeof HEYGEN_ENGINE_TYPES;
+/**
+ * Indicative $/minute of narration audio per engine, from the project
+ * cost analysis. The estimate the cost gate prints is indicative —
+ * HeyGen bills credits, not dollars.
+ */
+export declare const HEYGEN_RATE_PER_MIN: Record<HeygenEngineFlag, number>;
+export interface HeygenRequestContext {
+    readonly apiKey: string;
+    /** Injectable for tests; defaults to a real timer. */
+    readonly sleep?: (ms: number) => Promise<void>;
+    /** Rate-limit feedback sink (stderr line per retry). */
+    readonly onRetry?: (message: string) => void;
+}
+/** Upload one narration MP3 as a HeyGen asset (free). Returns the asset id. */
+export declare function uploadAudioAsset(ctx: HeygenRequestContext, audio: Buffer, filename: string): Promise<string>;
+export interface CreateAvatarVideoInput {
+    readonly avatarId: string;
+    readonly audioAssetId: string;
+    readonly engine: HeygenEngineFlag;
+    readonly resolution: string;
+    /**
+     * Deterministic title (`scenar <scenarioId> step-<N> <hash8>`) so any
+     * duplicate generation is identifiable in the HeyGen dashboard.
+     */
+    readonly title: string;
+}
+/** Create one avatar video lip-synced to the uploaded audio. Returns the video id. */
+export declare function createAvatarVideo(ctx: HeygenRequestContext, input: CreateAvatarVideoInput): Promise<string>;
+export interface PollOutcome {
+    readonly status: "completed" | "failed" | "timeout";
+    readonly videoUrl?: string;
+    readonly failureMessage?: string;
+}
+export interface PollOptions {
+    readonly intervalMs: number;
+    readonly timeoutMs: number;
+    /** Elapsed-time feedback per tick (drives the progress line). */
+    readonly onTick?: (elapsedMs: number) => void;
+}
+/**
+ * Poll a generation to completion. Polling is read-only, so transient
+ * network errors retry on the next tick inside the step timeout.
+ */
+export declare function pollVideo(ctx: HeygenRequestContext, videoId: string, options: PollOptions): Promise<PollOutcome>;
+/** Download a completed clip. Returns the raw bytes. */
+export declare function downloadVideo(url: string): Promise<Buffer>;
+//# sourceMappingURL=heygen-client.d.ts.map

package/src/presenter/heygen-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heygen-client.d.ts","sourceRoot":"","sources":["../../../src/presenter/heygen-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,oDAAoD;AACpD,eAAO,MAAM,mBAAmB;;;CAGtB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,mBAAmB,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAGhE,CAAC;AAKF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,wDAAwD;IACxD,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9C;AA6CD,+EAA+E;AAC/E,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,oBAAoB,EACzB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,sFAAsF;AACtF,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,oBAAoB,EACzB,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,MAAM,CAAC,CAsBjB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/C;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,oBAAoB,EACzB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,WAAW,CAAC,CAqCtB;AAED,wDAAwD;AACxD,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAMhE"}

package/src/presenter/heygen-client.js

@@ -0,0 +1,154 @@
+/**
+ * Minimal HeyGen API client for `scenar presenter` — deliberately an
+ * internal module of the CLI, not published API. Shaped so a second
+ * avatar provider could slot in behind the same function signatures,
+ * but the interface is not exported until a second provider is a
+ * concrete need (the TTS-provider precedent).
+ *
+ * Endpoints and response fields follow the live Gate 0 transcript:
+ * `POST /v3/assets` (multipart) → `data.asset_id`;
+ * `POST /v3/videos` (`type: "avatar"`, `audio_asset_id`) →
+ * `data.video_id`; `GET /v3/videos/{id}` → `data.status`
+ * (`completed`/`failed`), `data.video_url`, `data.failure_message`.
+ *
+ * BYO key, no Scenar-side proxying — identical to the TTS providers.
+ * Native fetch, no new runtime dependencies.
+ */
+const HEYGEN_BASE_URL = "https://api.heygen.com";
+/** Engine flag values → HeyGen's API vocabulary. */
+export const HEYGEN_ENGINE_TYPES = {
+    iii: "avatar_iii",
+    iv: "avatar_iv",
+};
+/**
+ * Indicative $/minute of narration audio per engine, from the project
+ * cost analysis. The estimate the cost gate prints is indicative —
+ * HeyGen bills credits, not dollars.
+ */
+export const HEYGEN_RATE_PER_MIN = {
+    iii: 1.0,
+    iv: 4.0,
+};
+const MAX_ATTEMPTS_ON_429 = 3;
+const DEFAULT_RETRY_AFTER_S = 30;
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Run a HeyGen request, honoring 429 rate limits: wait `Retry-After`
+ * (default 30 s) and retry the same call, up to 3 attempts total.
+ */
+async function heygenFetch(ctx, path, init) {
+    const sleep = ctx.sleep ?? realSleep;
+    let response;
+    for (let attempt = 1;; attempt++) {
+        response = await fetch(`${HEYGEN_BASE_URL}${path}`, {
+            ...init,
+            headers: { "x-api-key": ctx.apiKey, ...(init.headers ?? {}) },
+        });
+        if (response.status !== 429 || attempt >= MAX_ATTEMPTS_ON_429)
+            return response;
+        const retryAfterS = Number(response.headers.get("retry-after")) || DEFAULT_RETRY_AFTER_S;
+        ctx.onRetry?.(`rate-limited, retrying in ${retryAfterS}s (${attempt}/${MAX_ATTEMPTS_ON_429})`);
+        await sleep(retryAfterS * 1000);
+    }
+}
+async function readBody(response) {
+    try {
+        return (await response.json());
+    }
+    catch {
+        return {};
+    }
+}
+function apiError(operation, response, body) {
+    return new Error(`HeyGen ${operation} failed (${response.status}): ${JSON.stringify(body)}`);
+}
+/** Upload one narration MP3 as a HeyGen asset (free). Returns the asset id. */
+export async function uploadAudioAsset(ctx, audio, filename) {
+    const form = new FormData();
+    form.append("file", new Blob([new Uint8Array(audio)], { type: "audio/mpeg" }), filename);
+    const response = await heygenFetch(ctx, "/v3/assets", {
+        method: "POST",
+        body: form,
+    });
+    const body = await readBody(response);
+    if (!response.ok)
+        throw apiError("asset upload", response, body);
+    const assetId = body["data"]?.["asset_id"];
+    if (typeof assetId !== "string" || assetId.length === 0) {
+        throw new Error(`HeyGen asset upload returned no asset_id: ${JSON.stringify(body)}`);
+    }
+    return assetId;
+}
+/** Create one avatar video lip-synced to the uploaded audio. Returns the video id. */
+export async function createAvatarVideo(ctx, input) {
+    const response = await heygenFetch(ctx, "/v3/videos", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            type: "avatar",
+            avatar_id: input.avatarId,
+            audio_asset_id: input.audioAssetId,
+            engine: { type: HEYGEN_ENGINE_TYPES[input.engine] },
+            output_format: "mp4",
+            aspect_ratio: "auto",
+            resolution: input.resolution,
+            title: input.title,
+        }),
+    });
+    const body = await readBody(response);
+    if (!response.ok)
+        throw apiError("video create", response, body);
+    const videoId = body["data"]?.["video_id"];
+    if (typeof videoId !== "string" || videoId.length === 0) {
+        throw new Error(`HeyGen video create returned no video_id: ${JSON.stringify(body)}`);
+    }
+    return videoId;
+}
+/**
+ * Poll a generation to completion. Polling is read-only, so transient
+ * network errors retry on the next tick inside the step timeout.
+ */
+export async function pollVideo(ctx, videoId, options) {
+    const sleep = ctx.sleep ?? realSleep;
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < options.timeoutMs) {
+        await sleep(options.intervalMs);
+        options.onTick?.(Date.now() - startedAt);
+        let body;
+        try {
+            const response = await heygenFetch(ctx, `/v3/videos/${videoId}`, { method: "GET" });
+            body = await readBody(response);
+            if (!response.ok)
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const data = (body["data"] ?? {});
+        const status = data["status"];
+        if (status === "completed") {
+            return {
+                status: "completed",
+                videoUrl: typeof data["video_url"] === "string" ? data["video_url"] : undefined,
+            };
+        }
+        if (status === "failed") {
+            return {
+                status: "failed",
+                failureMessage: typeof data["failure_message"] === "string"
+                    ? data["failure_message"]
+                    : JSON.stringify(data["failure_message"] ?? "unknown failure"),
+            };
+        }
+    }
+    return { status: "timeout" };
+}
+/** Download a completed clip. Returns the raw bytes. */
+export async function downloadVideo(url) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`HeyGen clip download failed (${response.status}) for ${url}`);
+    }
+    return Buffer.from(await response.arrayBuffer());
+}
+//# sourceMappingURL=heygen-client.js.map

package/src/presenter/heygen-client.js.map

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