@scenar/cli 0.1.20 → 0.2.1

package/src/narrate/run-narrate.ts

@@ -0,0 +1,298 @@
+import { mkdir, writeFile, stat } from "node:fs/promises";
+import { join, resolve, extname, basename, dirname } from "node:path";
+import { loadScenarioYaml } from "../util/load-yaml.js";
+import { loadStepsFromTs } from "../util/load-ts.js";
+import { discoverScenarios } from "../util/discover-scenarios.js";
+import {
+  computeHash,
+  loadCache,
+  saveCache,
+  fileExists,
+  isCached,
+  getCachedDuration,
+  buildCacheFile,
+} from "../util/narration-cache.js";
+import { validateScenario } from "../validate/scenario-validator.js";
+import { resolveProvider } from "../tts/resolve-provider.js";
+import type { TtsProvider } from "../tts/types.js";
+
+/** Options for {@link runNarrate}. Paths may be relative; resolved here. */
+export interface RunNarrateOptions {
+  /** A scenario YAML file, a .ts steps file, or a directory of scenarios. */
+  readonly target: string;
+  /** TTS provider name: echogarden, edge-tts, or openai (default echogarden). */
+  readonly tts?: string;
+  /** Output directory for audio (default: alongside the scenario). */
+  readonly out?: string;
+  /** Voice name (provider-specific). */
+  readonly voice?: string;
+  /** URL path prefix for the `src` fields written into the manifest. */
+  readonly baseUrl?: string;
+  /** Progress sink for per-step/per-scenario messages. */
+  readonly onLog?: (message: string) => void;
+}
+
+/** Per-scenario narration outcome. */
+export interface NarratedScenario {
+  readonly id: string;
+  readonly generated: number;
+  readonly cached: number;
+  /** True when the scenario had no narration text (nothing to synthesize). */
+  readonly skipped: boolean;
+}
+
+/** Aggregate result of a narrate run. */
+export interface NarrateResult {
+  readonly mode: "file" | "directory";
+  readonly scenarios: NarratedScenario[];
+  readonly totalGenerated: number;
+  readonly totalCached: number;
+  readonly totalSkipped: number;
+  readonly errors: Array<{ id: string; message: string }>;
+}
+
+interface StepWithNarration {
+  index: number;
+  text: string;
+}
+
+function extractNarratedSteps(
+  steps: Array<{ narration?: string; narrationText?: string }>,
+): StepWithNarration[] {
+  const result: StepWithNarration[] = [];
+  for (let i = 0; i < steps.length; i++) {
+    const text = steps[i]!.narration ?? steps[i]!.narrationText;
+    if (typeof text === "string" && text.length > 0) {
+      result.push({ index: i, text });
+    }
+  }
+  return result;
+}
+
+interface RuntimeManifestEntry {
+  src: string;
+  durationMs: number;
+}
+
+interface RuntimeManifest {
+  steps: (RuntimeManifestEntry | null)[];
+}
+
+function buildRuntimeManifest(
+  totalSteps: number,
+  entries: Map<number, { src: string; durationMs: number }>,
+): RuntimeManifest {
+  const steps: (RuntimeManifestEntry | null)[] = Array.from({ length: totalSteps }, () => null);
+  for (const [idx, entry] of entries) {
+    steps[idx] = entry;
+  }
+  return { steps };
+}
+
+async function loadStepsFromFile(
+  filePath: string,
+): Promise<{ steps: Array<{ narration?: string; narrationText?: string }>; totalSteps: number }> {
+  const ext = extname(filePath).toLowerCase();
+
+  if (ext === ".ts" || ext === ".tsx") {
+    const steps = await loadStepsFromTs(filePath);
+    return { steps, totalSteps: steps.length };
+  }
+
+  const scenario = await loadScenarioYaml(filePath);
+  const validation = validateScenario(scenario);
+  if (!validation.valid) {
+    throw new Error(
+      `Scenario has ${validation.errors.length} error(s). Run 'scenar validate ${filePath}' for details.`,
+    );
+  }
+
+  const steps = (scenario as Record<string, unknown>)["steps"] as
+    | Array<Record<string, unknown>>
+    | undefined;
+  if (!steps) {
+    throw new Error("No steps found in scenario.");
+  }
+  return { steps: steps as Array<{ narrationText?: string }>, totalSteps: steps.length };
+}
+
+interface GenerateOptions {
+  scenarioId: string;
+  narratedSteps: StepWithNarration[];
+  totalSteps: number;
+  outDir: string;
+  voice: string;
+  baseUrl?: string;
+  provider: TtsProvider;
+  onLog: (message: string) => void;
+}
+
+interface GenerateStats {
+  generated: number;
+  cached: number;
+}
+
+async function generateNarration(opts: GenerateOptions): Promise<GenerateStats> {
+  const { scenarioId, narratedSteps, totalSteps, outDir, voice, baseUrl, provider, onLog } = opts;
+
+  await mkdir(outDir, { recursive: true });
+
+  const existingCache = await loadCache(outDir);
+  const stats: GenerateStats = { generated: 0, cached: 0 };
+  const manifestEntries = new Map<number, { src: string; durationMs: number }>();
+  const cacheEntries = new Map<number, { hash: string; durationMs: number }>();
+
+  for (const step of narratedSteps) {
+    const hash = computeHash(step.text, voice);
+    const fileName = `step-${step.index}.mp3`;
+    const mp3Path = join(outDir, fileName);
+
+    const srcPrefix = baseUrl ? `${baseUrl.replace(/\/$/, "")}/${scenarioId}` : `.`;
+    const src = `${srcPrefix}/${fileName}`;
+
+    if (isCached(existingCache, step.index, hash, voice) && (await fileExists(mp3Path))) {
+      const durationMs = getCachedDuration(existingCache!, step.index);
+      manifestEntries.set(step.index, { src, durationMs });
+      cacheEntries.set(step.index, { hash, durationMs });
+      stats.cached++;
+      onLog(`    step ${step.index}: cached`);
+      continue;
+    }
+
+    onLog(`    step ${step.index}: generating...`);
+    const result = await provider.synthesize(step.text, { voice: voice || undefined });
+
+    await writeFile(mp3Path, result.audio);
+    manifestEntries.set(step.index, { src, durationMs: result.durationMs });
+    cacheEntries.set(step.index, { hash, durationMs: result.durationMs });
+    stats.generated++;
+    onLog(`    step ${step.index}: ${result.durationMs}ms (${result.audio.length} bytes)`);
+  }
+
+  const manifest = buildRuntimeManifest(totalSteps, manifestEntries);
+  await writeFile(join(outDir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+
+  const cache = buildCacheFile(voice, totalSteps, cacheEntries);
+  await saveCache(outDir, cache);
+
+  onLog(`\x1b[32m+\x1b[0m ${scenarioId}: ${stats.generated} generated, ${stats.cached} cached`);
+  return stats;
+}
+
+/**
+ * Generate narration audio for a scenario file or a directory of scenarios —
+ * the pure orchestration behind `scenar narrate`. Resolves the TTS provider,
+ * synthesizes per-step audio (incremental via a content-hash cache), writes each
+ * scenario's manifest, and returns aggregate stats. No process/exit coupling.
+ */
+export async function runNarrate(options: RunNarrateOptions): Promise<NarrateResult> {
+  const onLog = options.onLog ?? (() => {});
+  const provider = await resolveProvider(options.tts ?? "echogarden");
+  const resolved = resolve(options.target);
+  const info = await stat(resolved);
+
+  return info.isDirectory()
+    ? narrateDirectory(resolved, options, provider, onLog)
+    : narrateSingleFile(resolved, options, provider, onLog);
+}
+
+async function narrateSingleFile(
+  filePath: string,
+  options: RunNarrateOptions,
+  provider: TtsProvider,
+  onLog: (message: string) => void,
+): Promise<NarrateResult> {
+  const { steps, totalSteps } = await loadStepsFromFile(filePath);
+  const narratedSteps = extractNarratedSteps(steps);
+  const id = basename(dirname(filePath));
+
+  if (narratedSteps.length === 0) {
+    return {
+      mode: "file",
+      scenarios: [{ id, generated: 0, cached: 0, skipped: true }],
+      totalGenerated: 0,
+      totalCached: 0,
+      totalSkipped: 1,
+      errors: [],
+    };
+  }
+
+  const outDir = options.out ?? join(dirname(filePath), "narration");
+  const stats = await generateNarration({
+    scenarioId: id,
+    narratedSteps,
+    totalSteps,
+    outDir,
+    voice: options.voice ?? "",
+    baseUrl: options.baseUrl,
+    provider,
+    onLog,
+  });
+
+  return {
+    mode: "file",
+    scenarios: [{ id, generated: stats.generated, cached: stats.cached, skipped: false }],
+    totalGenerated: stats.generated,
+    totalCached: stats.cached,
+    totalSkipped: 0,
+    errors: [],
+  };
+}
+
+async function narrateDirectory(
+  dirPath: string,
+  options: RunNarrateOptions,
+  provider: TtsProvider,
+  onLog: (message: string) => void,
+): Promise<NarrateResult> {
+  const scenarios = await discoverScenarios(dirPath);
+  const result: NarratedScenario[] = [];
+  const errors: Array<{ id: string; message: string }> = [];
+  let totalGenerated = 0;
+  let totalCached = 0;
+  let totalSkipped = 0;
+
+  if (scenarios.length > 0) {
+    onLog(`Discovered ${scenarios.length} scenario(s)`);
+  }
+
+  for (const scenario of scenarios) {
+    onLog(`  ${scenario.id}`);
+    try {
+      const steps = await loadStepsFromTs(scenario.stepsPath);
+      const narratedSteps = extractNarratedSteps(steps);
+
+      if (narratedSteps.length === 0) {
+        onLog("    (no narration)");
+        totalSkipped++;
+        result.push({ id: scenario.id, generated: 0, cached: 0, skipped: true });
+        continue;
+      }
+
+      const outDir = options.out
+        ? join(options.out, scenario.id)
+        : join(dirPath, scenario.id, "narration");
+
+      const stats = await generateNarration({
+        scenarioId: scenario.id,
+        narratedSteps,
+        totalSteps: steps.length,
+        outDir,
+        voice: options.voice ?? "",
+        baseUrl: options.baseUrl,
+        provider,
+        onLog,
+      });
+
+      totalGenerated += stats.generated;
+      totalCached += stats.cached;
+      result.push({ id: scenario.id, generated: stats.generated, cached: stats.cached, skipped: false });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      onLog(`    \x1b[31mfailed\x1b[0m: ${message}`);
+      errors.push({ id: scenario.id, message });
+    }
+  }
+
+  return { mode: "directory", scenarios: result, totalGenerated, totalCached, totalSkipped, errors };
+}

package/src/pack/generate-embed-entry.d.ts

@@ -30,6 +30,17 @@ export interface EmbedEntryInput {
  * @scenar/react theme + styles so the bundle is self-contained, and scopes the
  * tree with `SCENAR_CLASS` + `DemoViewport` exactly as the authoring surfaces do.
  *
+ * Interactions: the entry wires the full host-side interaction system —
+ * `useStepInteractions` + `<Cursor>` + `<ViewportTransformLayer>` — so packed
+ * embeds run the same narration-synced cursor moves, clicks, typing, hovers,
+ * drags, scrolls, and viewport transitions as the in-app player. (`ScenarioPlayer`
+ * itself owns none of this; the host must wire it, per DemoViewport's contract.)
+ *
+ * Theme: the embed reads `?theme` from its own URL and applies the `dark` class
+ * alongside `SCENAR_CLASS` when `theme=dark` (matching the `.scenar.dark` token
+ * selector). The default is light, so existing embeds are unaffected; a host can
+ * theme-sync simply by framing `…/?theme=dark`.
+ *
  * Pure function, no side effects — the caller writes the result to disk.
  */
 export declare function generateEmbedEntry(input: EmbedEntryInput): string;

package/src/pack/generate-embed-entry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-embed-entry.d.ts","sourceRoot":"","sources":["../../../src/pack/generate-embed-entry.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,cAAc,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,YAAY,EAAE,OAAO,CAAC;IACtB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAqFjE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAgBnF"}
+{"version":3,"file":"generate-embed-entry.d.ts","sourceRoot":"","sources":["../../../src/pack/generate-embed-entry.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,cAAc,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,YAAY,EAAE,OAAO,CAAC;IACtB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAiJjE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAgBnF"}

package/src/pack/generate-embed-entry.js

@@ -9,6 +9,17 @@ import { posix } from "node:path";
  * @scenar/react theme + styles so the bundle is self-contained, and scopes the
  * tree with `SCENAR_CLASS` + `DemoViewport` exactly as the authoring surfaces do.
  *
+ * Interactions: the entry wires the full host-side interaction system —
+ * `useStepInteractions` + `<Cursor>` + `<ViewportTransformLayer>` — so packed
+ * embeds run the same narration-synced cursor moves, clicks, typing, hovers,
+ * drags, scrolls, and viewport transitions as the in-app player. (`ScenarioPlayer`
+ * itself owns none of this; the host must wire it, per DemoViewport's contract.)
+ *
+ * Theme: the embed reads `?theme` from its own URL and applies the `dark` class
+ * alongside `SCENAR_CLASS` when `theme=dark` (matching the `.scenar.dark` token
+ * selector). The default is light, so existing embeds are unaffected; a host can
+ * theme-sync simply by framing `…/?theme=dark`.
+ *
  * Pure function, no side effects — the caller writes the result to disk.
  */
 export function generateEmbedEntry(input) {
@@ -17,11 +28,24 @@ export function generateEmbedEntry(input) {
     const renderImport = toPosix(input.renderFilePath).replace(/\.[^.]+$/, "");
     const lines = [];
     // --- Imports ---
+    // React hooks drive the host-side interaction system (the same one the
+    // in-app player wires): step tracking, cursor target, ripple/drag flags, and
+    // the viewport transform. Without these, the embed would render content but
+    // silently drop every cursor move and mid-step interaction.
+    lines.push(`import { useCallback, useRef, useState } from "react";`);
     lines.push(`import { createRoot } from "react-dom/client";`);
-    const reactImports = input.hasNarration
-        ? `ScenarioPlayer, DemoViewport, SCENAR_CLASS, useNarrationManifest`
-        : `ScenarioPlayer, DemoViewport, SCENAR_CLASS`;
-    lines.push(`import { ${reactImports} } from "@scenar/react";`);
+    const reactImports = [
+        "ScenarioPlayer",
+        "DemoViewport",
+        "SCENAR_CLASS",
+        "Cursor",
+        "useStepInteractions",
+        "ViewportTransformLayer",
+        "VIEWPORT_TRANSFORM_IDENTITY",
+    ];
+    if (input.hasNarration)
+        reactImports.push("useNarrationManifest");
+    lines.push(`import { ${reactImports.join(", ")} } from "@scenar/react";`);
     lines.push(`import "@scenar/react/theme.css";`);
     lines.push(`import "@scenar/react/styles.css";`);
     lines.push(`import { renderStep } from ${JSON.stringify(renderImport)};`);
@@ -54,26 +78,73 @@ export function generateEmbedEntry(input) {
         lines.push(``);
         lines.push(`const _resolveManifestUrl = () => "./narration/manifest.json";`);
     }
+    // --- Theme: opt-in dark via ?theme=dark (default light; backward-compatible) ---
+    // Read once at module load from the embed's own URL. `theme=dark` adds the
+    // `dark` class next to SCENAR_CLASS so the `.scenar.dark` tokens apply; any
+    // other value (including absent) renders light, preserving prior behavior.
+    lines.push(``);
+    lines.push(`const _theme = (() => {`);
+    lines.push(`  try { return new URLSearchParams(window.location.search).get("theme"); }`);
+    lines.push(`  catch { return null; }`);
+    lines.push(`})();`);
+    lines.push(`const _rootClass = _theme === "dark" ? SCENAR_CLASS + " dark" : SCENAR_CLASS;`);
     // --- App tree ---
+    // The structure mirrors the in-app demo wiring exactly (see DemoViewport's
+    // contract and ViewportTransformLayer's "Cursor must be a sibling" invariant):
+    //   DemoViewport(containerRef)
+    //     └ ViewportTransformLayer(transform)
+    //         └ ScenarioPlayer(embed, onStepChange)
+    //     └ Cursor(target, containerRef)   ← sibling, not a child
+    // `useStepInteractions` reads the current step's `interactions` and drives the
+    // cursor / ripple / drag / viewport state, synced to narration duration.
+    const manifestExpr = input.hasNarration ? "_manifest" : "undefined";
     lines.push(``);
     lines.push(`function _App() {`);
     if (input.hasNarration) {
         lines.push(`  const _manifest = useNarrationManifest(${JSON.stringify(input.scenarioId)}, _resolveManifestUrl);`);
     }
+    lines.push(`  const _containerRef = useRef<HTMLDivElement>(null);`);
+    lines.push(`  const [_stepIndex, _setStepIndex] = useState(0);`);
+    lines.push(`  const [_cursorTarget, _setCursorTarget] = useState<string | undefined>(undefined);`);
+    lines.push(`  const [_showRipple, _setShowRipple] = useState(true);`);
+    lines.push(`  const [_dragging, _setDragging] = useState(false);`);
+    lines.push(`  const [_viewport, _setViewport] = useState(VIEWPORT_TRANSFORM_IDENTITY);`);
+    lines.push(``);
+    // Reset the cursor when the step changes so a prior step's target never
+    // lingers; the new step's interactions re-set it at their scheduled time.
+    lines.push(`  const _handleStepChange = useCallback((_data: any, index: number) => {`);
+    lines.push(`    _setStepIndex(index);`);
+    lines.push(`    _setCursorTarget(undefined);`);
+    lines.push(`  }, []);`);
+    lines.push(``);
+    lines.push(`  useStepInteractions({`);
+    lines.push(`    stepIndex: _stepIndex,`);
+    lines.push(`    narrationManifest: ${manifestExpr},`);
+    lines.push(`    containerRef: _containerRef,`);
+    lines.push(`    setCursorTarget: _setCursorTarget,`);
+    lines.push(`    setShowRipple: _setShowRipple,`);
+    lines.push(`    setDragging: _setDragging,`);
+    lines.push(`    setViewportTransform: _setViewport,`);
+    lines.push(`    steps: _steps,`);
+    lines.push(`  });`);
+    lines.push(``);
     lines.push(`  const _bundle = {`);
     lines.push(`    id: ${JSON.stringify(input.scenarioId)},`);
     lines.push(`    steps: _steps,`);
-    lines.push(`    narrationManifest: ${input.hasNarration ? "_manifest" : "undefined"},`);
+    lines.push(`    narrationManifest: ${manifestExpr},`);
     lines.push(`  };`);
     const open = input.providersPath ? `<_Providers>` : ``;
     const close = input.providersPath ? `</_Providers>` : ``;
     lines.push(`  return (`);
-    lines.push(`    <div className={SCENAR_CLASS}>`);
+    lines.push(`    <div className={_rootClass}>`);
     lines.push(`      ${open}`);
-    lines.push(`      <DemoViewport canonicalWidth={${input.canonicalWidth}} shellHeight={${input.shellHeight}}>`);
-    lines.push(`        <ScenarioPlayer bundle={_bundle} embed>`);
-    lines.push(`          {(data: any, stepIndex: number) => renderStep(data, stepIndex)}`);
-    lines.push(`        </ScenarioPlayer>`);
+    lines.push(`      <DemoViewport containerRef={_containerRef} canonicalWidth={${input.canonicalWidth}} shellHeight={${input.shellHeight}}>`);
+    lines.push(`        <ViewportTransformLayer transform={_viewport}>`);
+    lines.push(`          <ScenarioPlayer bundle={_bundle} embed onStepChange={_handleStepChange}>`);
+    lines.push(`            {(data: any, stepIndex: number) => renderStep(data, stepIndex)}`);
+    lines.push(`          </ScenarioPlayer>`);
+    lines.push(`        </ViewportTransformLayer>`);
+    lines.push(`        <Cursor target={_cursorTarget} containerRef={_containerRef} showRipple={_showRipple} isDragging={_dragging} />`);
     lines.push(`      </DemoViewport>`);
     lines.push(`      ${close}`);
     lines.push(`    </div>`);

package/src/pack/generate-embed-entry.js.map

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

package/src/pack/generate-embed-entry.ts

@@ -33,6 +33,17 @@ export interface EmbedEntryInput {
  * @scenar/react theme + styles so the bundle is self-contained, and scopes the
  * tree with `SCENAR_CLASS` + `DemoViewport` exactly as the authoring surfaces do.
  *
+ * Interactions: the entry wires the full host-side interaction system —
+ * `useStepInteractions` + `<Cursor>` + `<ViewportTransformLayer>` — so packed
+ * embeds run the same narration-synced cursor moves, clicks, typing, hovers,
+ * drags, scrolls, and viewport transitions as the in-app player. (`ScenarioPlayer`
+ * itself owns none of this; the host must wire it, per DemoViewport's contract.)
+ *
+ * Theme: the embed reads `?theme` from its own URL and applies the `dark` class
+ * alongside `SCENAR_CLASS` when `theme=dark` (matching the `.scenar.dark` token
+ * selector). The default is light, so existing embeds are unaffected; a host can
+ * theme-sync simply by framing `…/?theme=dark`.
+ *
  * Pure function, no side effects — the caller writes the result to disk.
  */
 export function generateEmbedEntry(input: EmbedEntryInput): string {
@@ -43,11 +54,23 @@ export function generateEmbedEntry(input: EmbedEntryInput): string {
   const lines: string[] = [];
 
   // --- Imports ---
+  // React hooks drive the host-side interaction system (the same one the
+  // in-app player wires): step tracking, cursor target, ripple/drag flags, and
+  // the viewport transform. Without these, the embed would render content but
+  // silently drop every cursor move and mid-step interaction.
+  lines.push(`import { useCallback, useRef, useState } from "react";`);
   lines.push(`import { createRoot } from "react-dom/client";`);
-  const reactImports = input.hasNarration
-    ? `ScenarioPlayer, DemoViewport, SCENAR_CLASS, useNarrationManifest`
-    : `ScenarioPlayer, DemoViewport, SCENAR_CLASS`;
-  lines.push(`import { ${reactImports} } from "@scenar/react";`);
+  const reactImports = [
+    "ScenarioPlayer",
+    "DemoViewport",
+    "SCENAR_CLASS",
+    "Cursor",
+    "useStepInteractions",
+    "ViewportTransformLayer",
+    "VIEWPORT_TRANSFORM_IDENTITY",
+  ];
+  if (input.hasNarration) reactImports.push("useNarrationManifest");
+  lines.push(`import { ${reactImports.join(", ")} } from "@scenar/react";`);
   lines.push(`import "@scenar/react/theme.css";`);
   lines.push(`import "@scenar/react/styles.css";`);
   lines.push(`import { renderStep } from ${JSON.stringify(renderImport)};`);
@@ -86,26 +109,74 @@ export function generateEmbedEntry(input: EmbedEntryInput): string {
     lines.push(`const _resolveManifestUrl = () => "./narration/manifest.json";`);
   }
 
+  // --- Theme: opt-in dark via ?theme=dark (default light; backward-compatible) ---
+  // Read once at module load from the embed's own URL. `theme=dark` adds the
+  // `dark` class next to SCENAR_CLASS so the `.scenar.dark` tokens apply; any
+  // other value (including absent) renders light, preserving prior behavior.
+  lines.push(``);
+  lines.push(`const _theme = (() => {`);
+  lines.push(`  try { return new URLSearchParams(window.location.search).get("theme"); }`);
+  lines.push(`  catch { return null; }`);
+  lines.push(`})();`);
+  lines.push(`const _rootClass = _theme === "dark" ? SCENAR_CLASS + " dark" : SCENAR_CLASS;`);
+
   // --- App tree ---
+  // The structure mirrors the in-app demo wiring exactly (see DemoViewport's
+  // contract and ViewportTransformLayer's "Cursor must be a sibling" invariant):
+  //   DemoViewport(containerRef)
+  //     └ ViewportTransformLayer(transform)
+  //         └ ScenarioPlayer(embed, onStepChange)
+  //     └ Cursor(target, containerRef)   ← sibling, not a child
+  // `useStepInteractions` reads the current step's `interactions` and drives the
+  // cursor / ripple / drag / viewport state, synced to narration duration.
+  const manifestExpr = input.hasNarration ? "_manifest" : "undefined";
   lines.push(``);
   lines.push(`function _App() {`);
   if (input.hasNarration) {
     lines.push(`  const _manifest = useNarrationManifest(${JSON.stringify(input.scenarioId)}, _resolveManifestUrl);`);
   }
+  lines.push(`  const _containerRef = useRef<HTMLDivElement>(null);`);
+  lines.push(`  const [_stepIndex, _setStepIndex] = useState(0);`);
+  lines.push(`  const [_cursorTarget, _setCursorTarget] = useState<string | undefined>(undefined);`);
+  lines.push(`  const [_showRipple, _setShowRipple] = useState(true);`);
+  lines.push(`  const [_dragging, _setDragging] = useState(false);`);
+  lines.push(`  const [_viewport, _setViewport] = useState(VIEWPORT_TRANSFORM_IDENTITY);`);
+  lines.push(``);
+  // Reset the cursor when the step changes so a prior step's target never
+  // lingers; the new step's interactions re-set it at their scheduled time.
+  lines.push(`  const _handleStepChange = useCallback((_data: any, index: number) => {`);
+  lines.push(`    _setStepIndex(index);`);
+  lines.push(`    _setCursorTarget(undefined);`);
+  lines.push(`  }, []);`);
+  lines.push(``);
+  lines.push(`  useStepInteractions({`);
+  lines.push(`    stepIndex: _stepIndex,`);
+  lines.push(`    narrationManifest: ${manifestExpr},`);
+  lines.push(`    containerRef: _containerRef,`);
+  lines.push(`    setCursorTarget: _setCursorTarget,`);
+  lines.push(`    setShowRipple: _setShowRipple,`);
+  lines.push(`    setDragging: _setDragging,`);
+  lines.push(`    setViewportTransform: _setViewport,`);
+  lines.push(`    steps: _steps,`);
+  lines.push(`  });`);
+  lines.push(``);
   lines.push(`  const _bundle = {`);
   lines.push(`    id: ${JSON.stringify(input.scenarioId)},`);
   lines.push(`    steps: _steps,`);
-  lines.push(`    narrationManifest: ${input.hasNarration ? "_manifest" : "undefined"},`);
+  lines.push(`    narrationManifest: ${manifestExpr},`);
   lines.push(`  };`);
   const open = input.providersPath ? `<_Providers>` : ``;
   const close = input.providersPath ? `</_Providers>` : ``;
   lines.push(`  return (`);
-  lines.push(`    <div className={SCENAR_CLASS}>`);
+  lines.push(`    <div className={_rootClass}>`);
   lines.push(`      ${open}`);
-  lines.push(`      <DemoViewport canonicalWidth={${input.canonicalWidth}} shellHeight={${input.shellHeight}}>`);
-  lines.push(`        <ScenarioPlayer bundle={_bundle} embed>`);
-  lines.push(`          {(data: any, stepIndex: number) => renderStep(data, stepIndex)}`);
-  lines.push(`        </ScenarioPlayer>`);
+  lines.push(`      <DemoViewport containerRef={_containerRef} canonicalWidth={${input.canonicalWidth}} shellHeight={${input.shellHeight}}>`);
+  lines.push(`        <ViewportTransformLayer transform={_viewport}>`);
+  lines.push(`          <ScenarioPlayer bundle={_bundle} embed onStepChange={_handleStepChange}>`);
+  lines.push(`            {(data: any, stepIndex: number) => renderStep(data, stepIndex)}`);
+  lines.push(`          </ScenarioPlayer>`);
+  lines.push(`        </ViewportTransformLayer>`);
+  lines.push(`        <Cursor target={_cursorTarget} containerRef={_containerRef} showRipple={_showRipple} isDragging={_dragging} />`);
   lines.push(`      </DemoViewport>`);
   lines.push(`      ${close}`);
   lines.push(`    </div>`);

package/src/pack/run-pack.d.ts

@@ -0,0 +1,34 @@
+import { type PackManifest } from "./pack-manifest.js";
+/** Options for {@link runPack}. Paths may be relative; they are resolved here. */
+export interface RunPackOptions {
+    /** Path to a scenario directory (must contain steps.ts + a renderStep export). */
+    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). */
+    readonly width?: number;
+    /** Shell/container height in px (default: {@link DEFAULT_VIEWPORT}.height). */
+    readonly shellHeight?: number;
+    /** Keep the generated entry directory for debugging (default: false). */
+    readonly keepTemp?: boolean;
+    /** Progress sink for mid-operation messages. */
+    readonly onLog?: (message: string) => void;
+}
+/** The outcome of a successful pack. */
+export interface PackResult {
+    readonly scenarioId: string;
+    readonly outDir: string;
+    readonly renderFilePath: string;
+    readonly providersPath: string | null;
+    readonly hasNarration: boolean;
+    readonly manifest: PackManifest;
+    readonly totalBytes: number;
+}
+/**
+ * Bundle a scenario directory into a self-contained, hosted embed — the pure
+ * orchestration behind `scenar pack`, with no process/exit coupling so both the
+ * CLI command and the MCP server can call it. Throws on any failure (invalid
+ * directory, bundler error, allowlist violation); the caller formats it.
+ */
+export declare function runPack(options: RunPackOptions): Promise<PackResult>;
+//# sourceMappingURL=run-pack.d.ts.map

package/src/pack/run-pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-pack.d.ts","sourceRoot":"","sources":["../../../src/pack/run-pack.ts"],"names":[],"mappings":"AAMA,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAM5B,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AAED,wCAAwC;AACxC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAmF1E"}