@scenar/cli 0.4.0 → 0.6.0

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

@@ -21,6 +21,12 @@ export interface EmbedEntryInput {
   canonicalWidth: number;
   /** Shell height in px, exposed as --scenar-shell-height. */
   shellHeight: number;
+  /**
+   * Wrap each step's content in `<ScenarioStage>` (backdrop + window shadow),
+   * and paint the backdrop in the static HTML so it shows before the entry
+   * script runs. Opt-in: staged embeds give up the transparent canvas.
+   */
+  stage?: boolean;
 }
 
 /**
@@ -69,6 +75,7 @@ export function generateEmbedEntry(input: EmbedEntryInput): string {
     "ViewportTransformLayer",
     "VIEWPORT_TRANSFORM_IDENTITY",
   ];
+  if (input.stage) reactImports.push("ScenarioStage");
   if (input.hasNarration) reactImports.push("useNarrationManifest");
   lines.push(`import { ${reactImports.join(", ")} } from "@scenar/react";`);
   lines.push(`import "@scenar/react/theme.css";`);
@@ -120,13 +127,37 @@ export function generateEmbedEntry(input: EmbedEntryInput): string {
   lines.push(`})();`);
   lines.push(`const _rootClass = _theme === "dark" ? SCENAR_CLASS + " dark" : SCENAR_CLASS;`);
 
+  // --- Page canvas: transparent when framed, theme surface when top-level ---
+  // The static HTML keeps html/body transparent (see generateEmbedHtml): a
+  // framed embed's canvas then shows the *host page's* background through any
+  // pixel the tour doesn't paint (aspect-ratio rounding slivers, load-in), so
+  // an embed can never flash a white band on a dark docs page. Do NOT pin
+  // `document.documentElement.style.colorScheme` to the resolved theme here —
+  // the `light dark` meta must stay authoritative, because a scheme mismatch
+  // with the framing document is exactly what makes browsers force an opaque
+  // white canvas. Top-level (scenar serve verification, direct bundle links)
+  // has no host background to show through, so paint the theme surface token
+  // for an intentional-looking page instead of the browser's default white.
+  // The body gets the scenar root class so `--scenar-surface` resolves there —
+  // referencing the token keeps this in lockstep with the palette instead of
+  // duplicating hex values that would drift.
+  lines.push(``);
+  lines.push(`if (window.parent === window) {`);
+  lines.push(`  document.body.classList.add(..._rootClass.split(" "));`);
+  lines.push(`  document.body.style.background = "var(--scenar-surface)";`);
+  lines.push(`}`);
+
   // --- App tree ---
   // The structure mirrors the in-app demo wiring exactly (see DemoViewport's
-  // contract and ViewportTransformLayer's "Cursor must be a sibling" invariant):
+  // and ViewportTransformLayer's contracts):
   //   DemoViewport(containerRef)
-  //     └ ViewportTransformLayer(transform)
+  //     └ ViewportTransformLayer(transform, contentRef=cameraRef)
   //         └ ScenarioPlayer(embed, onStepChange)
-  //     └ Cursor(target, containerRef)   ← sibling, not a child
+  //         └ Cursor(target, containerRef=cameraRef)   ← child of the camera
+  // The cursor lives INSIDE the camera so it scales and pans with the content
+  // during viewport transitions — like a recorded pointer under a camera zoom.
+  // Both the cursor and the viewport-transition target math take the camera's
+  // contentRef so canonical coordinates stay correct at any camera state.
   // `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";
@@ -136,6 +167,7 @@ export function generateEmbedEntry(input: EmbedEntryInput): string {
     lines.push(`  const _manifest = useNarrationManifest(${JSON.stringify(input.scenarioId)}, _resolveManifestUrl);`);
   }
   lines.push(`  const _containerRef = useRef<HTMLDivElement>(null);`);
+  lines.push(`  const _cameraRef = 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);`);
@@ -153,6 +185,7 @@ export function generateEmbedEntry(input: EmbedEntryInput): string {
   lines.push(`    stepIndex: _stepIndex,`);
   lines.push(`    narrationManifest: ${manifestExpr},`);
   lines.push(`    containerRef: _containerRef,`);
+  lines.push(`    cameraRef: _cameraRef,`);
   lines.push(`    setCursorTarget: _setCursorTarget,`);
   lines.push(`    setShowRipple: _setShowRipple,`);
   lines.push(`    setDragging: _setDragging,`);
@@ -170,13 +203,19 @@ export function generateEmbedEntry(input: EmbedEntryInput): string {
   lines.push(`  return (`);
   lines.push(`    <div className={_rootClass}>`);
   lines.push(`      ${open}`);
+  // Staged embeds wrap each step's content — not the player chrome — in the
+  // stage, inside the camera, so a zoom scales the whole recording, backdrop
+  // included, while controls keep overlaying the stable content box.
+  const stepRender = input.stage
+    ? `{(data: any, stepIndex: number) => <ScenarioStage>{renderStep(data, stepIndex)}</ScenarioStage>}`
+    : `{(data: any, stepIndex: number) => renderStep(data, stepIndex)}`;
   lines.push(`      <DemoViewport containerRef={_containerRef} canonicalWidth={${input.canonicalWidth}} shellHeight={${input.shellHeight}}>`);
-  lines.push(`        <ViewportTransformLayer transform={_viewport}>`);
+  lines.push(`        <ViewportTransformLayer transform={_viewport} contentRef={_cameraRef}>`);
   lines.push(`          <ScenarioPlayer bundle={_bundle} embed onStepChange={_handleStepChange}>`);
-  lines.push(`            {(data: any, stepIndex: number) => renderStep(data, stepIndex)}`);
+  lines.push(`            ${stepRender}`);
   lines.push(`          </ScenarioPlayer>`);
+  lines.push(`          <Cursor target={_cursorTarget} containerRef={_cameraRef} showRipple={_showRipple} isDragging={_dragging} />`);
   lines.push(`        </ViewportTransformLayer>`);
-  lines.push(`        <Cursor target={_cursorTarget} containerRef={_containerRef} showRipple={_showRipple} isDragging={_dragging} />`);
   lines.push(`      </DemoViewport>`);
   lines.push(`      ${close}`);
   lines.push(`    </div>`);
@@ -197,15 +236,54 @@ export function generateEmbedEntry(input: EmbedEntryInput): string {
  * Produce the index.html that boots the embed. The entry is referenced as an
  * external module script (`<script type="module" src>`) — never inline — so the
  * server CSP (`script-src 'self'`) is satisfied without loosening.
+ *
+ * Canvas contract: the page declares `color-scheme: light dark` and keeps
+ * html/body transparent. When the embed is framed by a same-origin host (the
+ * shipped stigmer.ai layout), the browser propagates the host's color scheme
+ * into the frame; because the embed supports both schemes they always match,
+ * so the iframe canvas stays *transparent* — every pixel the tour doesn't
+ * paint shows the host page's own background, in both themes, even before the
+ * entry script loads. (A scheme mismatch is what makes browsers force an
+ * opaque white canvas — the historical "white band under the embed".) The
+ * margin reset guards against a host stylesheet-less load; the entry paints a
+ * theme surface only when the page is top-level (see generateEmbedEntry).
+ *
+ * Staged embeds (`--stage`) deliberately trade that transparency away: the
+ * scenario floats on a backdrop, so the page pre-paints the same backdrop in
+ * static CSS — before the entry script runs — and there is no flash when the
+ * React-rendered stage takes over. `light-dark()` keys the pre-paint to the
+ * propagated color scheme; the values mirror `--scenar-backdrop` in
+ * @scenar/react's theme/tokens.css (the token itself is not loadable before
+ * the script, so keep the two in sync when retuning the backdrop). Do NOT
+ * pin `colorScheme` here either — the `light dark` meta stays authoritative.
  */
-export function generateEmbedHtml(scenarioId: string, entryFileName: string): string {
+export function generateEmbedHtml(
+  scenarioId: string,
+  entryFileName: string,
+  stage = false,
+): string {
+  const bodyBackground = stage
+    ? [
+        `      body {`,
+        `        background: light-dark(`,
+        `          linear-gradient(135deg, #e7ebf1 0%, #dde3ec 55%, #d3dae6 100%),`,
+        `          linear-gradient(135deg, #16202f 0%, #101827 55%, #0b111d 100%)`,
+        `        );`,
+        `      }`,
+      ]
+    : [];
   return [
     `<!doctype html>`,
     `<html lang="en">`,
     `  <head>`,
     `    <meta charset="utf-8" />`,
     `    <meta name="viewport" content="width=device-width, initial-scale=1" />`,
+    `    <meta name="color-scheme" content="light dark" />`,
     `    <title>${escapeHtml(scenarioId)}</title>`,
+    `    <style>`,
+    `      html, body { margin: 0; background: transparent; }`,
+    ...bodyBackground,
+    `    </style>`,
     `  </head>`,
     `  <body>`,
     `    <div id="root"></div>`,

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

@@ -9,6 +9,12 @@ export interface RunPackOptions {
     readonly width?: number;
     /** Shell/container height in px (default: {@link DEFAULT_VIEWPORT}.height). */
     readonly shellHeight?: number;
+    /**
+     * Float the scenario on a backdrop with a window shadow (screen-recording
+     * framing). Opt-in: a staged embed paints its own background, giving up
+     * the default transparent canvas that lets the host page show through.
+     */
+    readonly stage?: boolean;
     /** Keep the generated entry directory for debugging (default: false). */
     readonly keepTemp?: boolean;
     /** Progress sink for mid-operation messages. */

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

@@ -1 +1 @@
-{"version":3,"file":"run-pack.d.ts","sourceRoot":"","sources":["../../../src/pack/run-pack.ts"],"names":[],"mappings":"AAOA,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,CAyF1E"}
+{"version":3,"file":"run-pack.d.ts","sourceRoot":"","sources":["../../../src/pack/run-pack.ts"],"names":[],"mappings":"AAOA,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;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,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,CA2F1E"}

package/src/pack/run-pack.js

@@ -43,6 +43,7 @@ export async function runPack(options) {
         onLog(`Narration: ${hasNarration ? "yes (manifest found)" : "none"}`);
         onLog(`Output:    ${outDir}`);
         // 1. Generate the browser entry + index.html into the temp dir.
+        const stage = options.stage ?? false;
         const entrySource = generateEmbedEntry({
             scenarioDir,
             renderFilePath,
@@ -51,12 +52,13 @@ export async function runPack(options) {
             providersPath,
             canonicalWidth: width,
             shellHeight,
+            stage,
         });
         await mkdir(tempDir, { recursive: true });
         const entryFileName = "entry.tsx";
         const entryHtmlPath = join(tempDir, "index.html");
         await writeFile(join(tempDir, entryFileName), entrySource, "utf-8");
-        await writeFile(entryHtmlPath, generateEmbedHtml(scenarioId, entryFileName), "utf-8");
+        await writeFile(entryHtmlPath, generateEmbedHtml(scenarioId, entryFileName, stage), "utf-8");
         // 2. Build the static bundle with Vite.
         onLog("Bundling embed with Vite...");
         await runViteBuild({ root: tempDir, outDir, entryHtmlPath });

package/src/pack/run-pack.js.map

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

package/src/pack/run-pack.ts

@@ -27,6 +27,12 @@ export interface RunPackOptions {
   readonly width?: number;
   /** Shell/container height in px (default: {@link DEFAULT_VIEWPORT}.height). */
   readonly shellHeight?: number;
+  /**
+   * Float the scenario on a backdrop with a window shadow (screen-recording
+   * framing). Opt-in: a staged embed paints its own background, giving up
+   * the default transparent canvas that lets the host page show through.
+   */
+  readonly stage?: boolean;
   /** Keep the generated entry directory for debugging (default: false). */
   readonly keepTemp?: boolean;
   /** Progress sink for mid-operation messages. */
@@ -86,6 +92,7 @@ export async function runPack(options: RunPackOptions): Promise<PackResult> {
     onLog(`Output:    ${outDir}`);
 
     // 1. Generate the browser entry + index.html into the temp dir.
+    const stage = options.stage ?? false;
     const entrySource = generateEmbedEntry({
       scenarioDir,
       renderFilePath,
@@ -94,12 +101,13 @@ export async function runPack(options: RunPackOptions): Promise<PackResult> {
       providersPath,
       canonicalWidth: width,
       shellHeight,
+      stage,
     });
     await mkdir(tempDir, { recursive: true });
     const entryFileName = "entry.tsx";
     const entryHtmlPath = join(tempDir, "index.html");
     await writeFile(join(tempDir, entryFileName), entrySource, "utf-8");
-    await writeFile(entryHtmlPath, generateEmbedHtml(scenarioId, entryFileName), "utf-8");
+    await writeFile(entryHtmlPath, generateEmbedHtml(scenarioId, entryFileName, stage), "utf-8");
 
     // 2. Build the static bundle with Vite.
     onLog("Bundling embed with Vite...");

package/src/pack/viewport.d.ts

@@ -19,7 +19,13 @@ export interface Viewport {
     /** Shell/container height in px (ViewportConfig.height; CLI `--shell-height`). */
     readonly height: number;
 }
-/** Defaults matching `DemoViewport`: 896 canonical width, 480 shell height. */
+/**
+ * Pack-time defaults. The width matches `DemoViewport`'s default canonical
+ * width (896); the height is the CLI's own default — `DemoViewport` has no
+ * height default of its own, and the baked `--scenar-shell-height` variable
+ * overrides every per-shell fallback in `@scenar/react`'s `shells/tokens.ts`
+ * (380/420/460/500), so this number is what framed shells actually render at.
+ */
 export declare const DEFAULT_VIEWPORT: Viewport;
 /**
  * Narrow unknown JSON into a {@link Viewport}, or null if it is missing or

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,+EAA+E;AAC/E,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"}

package/src/pack/viewport.js

@@ -1,4 +1,10 @@
-/** Defaults matching `DemoViewport`: 896 canonical width, 480 shell height. */
+/**
+ * Pack-time defaults. The width matches `DemoViewport`'s default canonical
+ * width (896); the height is the CLI's own default — `DemoViewport` has no
+ * height default of its own, and the baked `--scenar-shell-height` variable
+ * overrides every per-shell fallback in `@scenar/react`'s `shells/tokens.ts`
+ * (380/420/460/500), so this number is what framed shells actually render at.
+ */
 export const DEFAULT_VIEWPORT = { width: 896, height: 480 };
 /**
  * Narrow unknown JSON into a {@link Viewport}, or null if it is missing or

package/src/pack/viewport.js.map

@@ -1 +1 @@
-{"version":3,"file":"viewport.js","sourceRoot":"","sources":["../../../src/pack/viewport.ts"],"names":[],"mappings":"AAsBA,+EAA+E;AAC/E,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;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

@@ -20,7 +20,13 @@ export interface Viewport {
   readonly height: number;
 }
 
-/** Defaults matching `DemoViewport`: 896 canonical width, 480 shell height. */
+/**
+ * Pack-time defaults. The width matches `DemoViewport`'s default canonical
+ * width (896); the height is the CLI's own default — `DemoViewport` has no
+ * height default of its own, and the baked `--scenar-shell-height` variable
+ * overrides every per-shell fallback in `@scenar/react`'s `shells/tokens.ts`
+ * (380/420/460/500), so this number is what framed shells actually render at.
+ */
 export const DEFAULT_VIEWPORT: Viewport = { width: 896, height: 480 };
 
 /**