@scenar/cli 0.3.0 → 0.5.0

package/src/install/scaffold.js

@@ -0,0 +1,231 @@
+import * as fs from "fs";
+import * as path from "path";
+/**
+ * Base dependencies every Scenar demos project needs to author tours. The
+ * starter tour is built from `@scenar/react` shells, so `@scenar/react` is
+ * recorded as `"*"` (resolves to the latest published — pin it once you know
+ * the version you want). React is constrained to the major the `@scenar/*`
+ * packages target so the embed and the user's real components (added later)
+ * share a single React.
+ */
+export const BASE_DEPENDENCIES = {
+    "@scenar/react": "*",
+    react: "^19.0.0",
+    "react-dom": "^19.0.0",
+};
+/**
+ * Scaffold a fresh Scenar demos project in `dir`.
+ *
+ * Creates a minimal `package.json`, a `tsconfig.json` tuned for JSX, a
+ * `.gitignore` that ignores build output, and a runnable **starter tour** under
+ * `tours/example-tour/` (a `steps.ts` timeline, an `index.tsx` that exports
+ * `renderStep`, and a `.scenar/providers.tsx`). The starter is built from
+ * `@scenar/react` shells so `scenar pack` works immediately; the author then
+ * swaps in their real components and wires data in `providers.tsx`.
+ *
+ * Existing files are never overwritten — this only fills in what is missing, so
+ * it is safe to re-run.
+ */
+export function scaffoldProject(dir) {
+    const created = [];
+    writeIfMissing(dir, "package.json", renderPackageJson(path.basename(dir)), created);
+    writeIfMissing(dir, "tsconfig.json", TSCONFIG, created);
+    writeIfMissing(dir, ".gitignore", GITIGNORE, created);
+    writeIfMissing(dir, path.join(TOUR_DIR, "steps.ts"), TOUR_STEPS, created);
+    writeIfMissing(dir, path.join(TOUR_DIR, "index.tsx"), TOUR_INDEX, created);
+    writeIfMissing(dir, path.join(TOUR_DIR, ".scenar", "providers.tsx"), TOUR_PROVIDERS, created);
+    return { created };
+}
+function writeIfMissing(dir, relPath, content, created) {
+    const target = path.join(dir, relPath);
+    if (fs.existsSync(target))
+        return;
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content, "utf-8");
+    created.push(relPath);
+}
+function renderPackageJson(name) {
+    const pkg = {
+        name: toPackageName(name),
+        version: "0.0.0",
+        private: true,
+        type: "module",
+        scripts: {
+            pack: `scenar pack ${TOUR_DIR}`,
+        },
+        dependencies: { ...BASE_DEPENDENCIES },
+    };
+    return JSON.stringify(pkg, null, 2) + "\n";
+}
+/** Coerce a directory name into a valid npm package name. */
+function toPackageName(dirName) {
+    const slug = dirName
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug.length > 0 ? slug : "scenar-demos";
+}
+/** Where the starter tour is scaffolded (also the default `pack` target). */
+const TOUR_DIR = "tours/example-tour";
+const TSCONFIG = `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"]
+  },
+  "include": ["tours"]
+}
+`;
+const GITIGNORE = `node_modules/
+
+# Packed embeds — regenerate with \`scenar pack\`
+*-bundle/
+`;
+const TOUR_STEPS = `import type { ScenarioStep } from "@scenar/core";
+
+/** The screen shown at a given step (maps to a view in index.tsx). */
+export type ExampleScreen = "login" | "dashboard";
+
+/** Data snapshot for one step of the tour. */
+export interface ExampleStepData {
+  /** Address-bar URL shown in the browser chrome (no scheme). */
+  readonly url: string;
+  /** Which screen is shown at this step. */
+  readonly screen: ExampleScreen;
+}
+
+/**
+ * The tour timeline. \`delayMs\` is the dwell before each step (the first is
+ * shown immediately); \`narration\` is the spoken script synthesized by
+ * \`scenar narrate\`.
+ */
+export const steps: ScenarioStep<ExampleStepData>[] = [
+  {
+    delayMs: 0,
+    narration: "Sign in to your workspace.",
+    data: { url: "app.example.com/login", screen: "login" },
+  },
+  {
+    delayMs: 2400,
+    narration: "And you land on your dashboard.",
+    data: { url: "app.example.com/home", screen: "dashboard" },
+  },
+];
+`;
+const TOUR_INDEX = `import type { ReactNode } from "react";
+import {
+  BrowserView,
+  DashboardPage,
+  LoginCardPage,
+  type SideNavItem,
+} from "@scenar/react";
+import type { ExampleStepData } from "./steps";
+
+/**
+ * renderStep: a pure (data, stepIndex) -> ReactNode. Both \`scenar pack\` (embed)
+ * and \`scenar render\` (video) consume this contract.
+ *
+ * This starter draws CSS-only @scenar/react shells so it packs with no extra
+ * setup. To show your REAL product UI, install your components
+ * (\`scenar install <your-pkg>\`), import and render them here, and wire any data
+ * they fetch in .scenar/providers.tsx.
+ */
+export function renderStep(data: ExampleStepData, stepIndex: number): ReactNode {
+  return (
+    <BrowserView url={"https://" + data.url} contentKey={String(stepIndex)}>
+      {data.screen === "login" ? <LoginScreen /> : <DashboardScreen />}
+    </BrowserView>
+  );
+}
+
+function LoginScreen(): ReactNode {
+  return (
+    <LoginCardPage
+      appName="Example"
+      subtitle="Sign in to your workspace"
+      fields={[
+        { label: "Email", value: "you@example.com", type: "email" },
+        { label: "Password", type: "password" },
+      ]}
+      submitLabel="Sign in"
+    />
+  );
+}
+
+const SIDEBAR: SideNavItem[] = [
+  { label: "Workspace", isSection: true },
+  { label: "Overview", active: true },
+  { label: "Projects" },
+];
+
+function DashboardScreen(): ReactNode {
+  return (
+    <DashboardPage
+      appName="Example"
+      userName="You"
+      navLinks={[{ label: "Home", active: true }]}
+      sidebarItems={SIDEBAR}
+    >
+      <div style={{ padding: 20 }}>
+        <h2
+          style={{
+            margin: 0,
+            fontSize: 15,
+            fontWeight: 600,
+            color: "var(--scenar-foreground)",
+          }}
+        >
+          Welcome back
+        </h2>
+      </div>
+    </DashboardPage>
+  );
+}
+`;
+const TOUR_PROVIDERS = `/**
+ * .scenar/providers.tsx — wraps every step of THIS tour in \`scenar pack\` (embed)
+ * and \`scenar render\` (video).
+ *
+ * You only need this when your tour renders real, data-fetching components that
+ * need a client/provider to render in isolation (no backend). A tour built only
+ * from @scenar/react shells (like the starter) can leave this as a pass-through
+ * or delete it.
+ *
+ * Recommended pattern for Connect-RPC SDKs (e.g. @stigmer/react): mock data with
+ * an in-process router transport — no network, no service worker — and resolve
+ * the embed's light/dark mode from \`getEmbedColorMode()\`. Fill in your client,
+ * provider, and fixtures, then return the provider instead of the fragment:
+ *
+ *   import "@your-org/react/styles.css";
+ *   import { createRouterTransport } from "@connectrpc/connect";
+ *   import { getEmbedColorMode } from "@scenar/react";
+ *   import { YourClient } from "@your-org/sdk";
+ *   import { YourProvider } from "@your-org/react";
+ *   import { YourController } from "@your-org/protos/...";
+ *
+ *   const transport = createRouterTransport((router) => {
+ *     router.service(YourController, { get: () => yourFixtureObject });
+ *   });
+ *   const client = new YourClient({ baseUrl: "/", customTransport: transport });
+ *
+ *   export function PreviewProviders({ children }: { readonly children: ReactNode }) {
+ *     return (
+ *       <YourProvider client={client} colorMode={getEmbedColorMode()}>
+ *         {children}
+ *       </YourProvider>
+ *     );
+ *   }
+ */
+import type { ReactNode } from "react";
+
+export function PreviewProviders({ children }: { readonly children: ReactNode }) {
+  return <>{children}</>;
+}
+`;
+//# sourceMappingURL=scaffold.js.map

package/src/install/scaffold.js.map

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

package/src/install/scaffold.ts

@@ -0,0 +1,253 @@
+import * as fs from "fs";
+import * as path from "path";
+
+/**
+ * Base dependencies every Scenar demos project needs to author tours. The
+ * starter tour is built from `@scenar/react` shells, so `@scenar/react` is
+ * recorded as `"*"` (resolves to the latest published — pin it once you know
+ * the version you want). React is constrained to the major the `@scenar/*`
+ * packages target so the embed and the user's real components (added later)
+ * share a single React.
+ */
+export const BASE_DEPENDENCIES: Readonly<Record<string, string>> = {
+  "@scenar/react": "*",
+  react: "^19.0.0",
+  "react-dom": "^19.0.0",
+};
+
+/** Result of scaffolding a fresh demos project. */
+export interface ScaffoldResult {
+  /** Files created, relative to the project directory. */
+  readonly created: readonly string[];
+}
+
+/**
+ * Scaffold a fresh Scenar demos project in `dir`.
+ *
+ * Creates a minimal `package.json`, a `tsconfig.json` tuned for JSX, a
+ * `.gitignore` that ignores build output, and a runnable **starter tour** under
+ * `tours/example-tour/` (a `steps.ts` timeline, an `index.tsx` that exports
+ * `renderStep`, and a `.scenar/providers.tsx`). The starter is built from
+ * `@scenar/react` shells so `scenar pack` works immediately; the author then
+ * swaps in their real components and wires data in `providers.tsx`.
+ *
+ * Existing files are never overwritten — this only fills in what is missing, so
+ * it is safe to re-run.
+ */
+export function scaffoldProject(dir: string): ScaffoldResult {
+  const created: string[] = [];
+
+  writeIfMissing(dir, "package.json", renderPackageJson(path.basename(dir)), created);
+  writeIfMissing(dir, "tsconfig.json", TSCONFIG, created);
+  writeIfMissing(dir, ".gitignore", GITIGNORE, created);
+  writeIfMissing(dir, path.join(TOUR_DIR, "steps.ts"), TOUR_STEPS, created);
+  writeIfMissing(dir, path.join(TOUR_DIR, "index.tsx"), TOUR_INDEX, created);
+  writeIfMissing(dir, path.join(TOUR_DIR, ".scenar", "providers.tsx"), TOUR_PROVIDERS, created);
+
+  return { created };
+}
+
+function writeIfMissing(
+  dir: string,
+  relPath: string,
+  content: string,
+  created: string[],
+): void {
+  const target = path.join(dir, relPath);
+  if (fs.existsSync(target)) return;
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, content, "utf-8");
+  created.push(relPath);
+}
+
+function renderPackageJson(name: string): string {
+  const pkg = {
+    name: toPackageName(name),
+    version: "0.0.0",
+    private: true,
+    type: "module",
+    scripts: {
+      pack: `scenar pack ${TOUR_DIR}`,
+    },
+    dependencies: { ...BASE_DEPENDENCIES },
+  };
+  return JSON.stringify(pkg, null, 2) + "\n";
+}
+
+/** Coerce a directory name into a valid npm package name. */
+function toPackageName(dirName: string): string {
+  const slug = dirName
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug.length > 0 ? slug : "scenar-demos";
+}
+
+/** Where the starter tour is scaffolded (also the default `pack` target). */
+const TOUR_DIR = "tours/example-tour";
+
+const TSCONFIG = `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"]
+  },
+  "include": ["tours"]
+}
+`;
+
+const GITIGNORE = `node_modules/
+
+# Packed embeds — regenerate with \`scenar pack\`
+*-bundle/
+`;
+
+const TOUR_STEPS = `import type { ScenarioStep } from "@scenar/core";
+
+/** The screen shown at a given step (maps to a view in index.tsx). */
+export type ExampleScreen = "login" | "dashboard";
+
+/** Data snapshot for one step of the tour. */
+export interface ExampleStepData {
+  /** Address-bar URL shown in the browser chrome (no scheme). */
+  readonly url: string;
+  /** Which screen is shown at this step. */
+  readonly screen: ExampleScreen;
+}
+
+/**
+ * The tour timeline. \`delayMs\` is the dwell before each step (the first is
+ * shown immediately); \`narration\` is the spoken script synthesized by
+ * \`scenar narrate\`.
+ */
+export const steps: ScenarioStep<ExampleStepData>[] = [
+  {
+    delayMs: 0,
+    narration: "Sign in to your workspace.",
+    data: { url: "app.example.com/login", screen: "login" },
+  },
+  {
+    delayMs: 2400,
+    narration: "And you land on your dashboard.",
+    data: { url: "app.example.com/home", screen: "dashboard" },
+  },
+];
+`;
+
+const TOUR_INDEX = `import type { ReactNode } from "react";
+import {
+  BrowserView,
+  DashboardPage,
+  LoginCardPage,
+  type SideNavItem,
+} from "@scenar/react";
+import type { ExampleStepData } from "./steps";
+
+/**
+ * renderStep: a pure (data, stepIndex) -> ReactNode. Both \`scenar pack\` (embed)
+ * and \`scenar render\` (video) consume this contract.
+ *
+ * This starter draws CSS-only @scenar/react shells so it packs with no extra
+ * setup. To show your REAL product UI, install your components
+ * (\`scenar install <your-pkg>\`), import and render them here, and wire any data
+ * they fetch in .scenar/providers.tsx.
+ */
+export function renderStep(data: ExampleStepData, stepIndex: number): ReactNode {
+  return (
+    <BrowserView url={"https://" + data.url} contentKey={String(stepIndex)}>
+      {data.screen === "login" ? <LoginScreen /> : <DashboardScreen />}
+    </BrowserView>
+  );
+}
+
+function LoginScreen(): ReactNode {
+  return (
+    <LoginCardPage
+      appName="Example"
+      subtitle="Sign in to your workspace"
+      fields={[
+        { label: "Email", value: "you@example.com", type: "email" },
+        { label: "Password", type: "password" },
+      ]}
+      submitLabel="Sign in"
+    />
+  );
+}
+
+const SIDEBAR: SideNavItem[] = [
+  { label: "Workspace", isSection: true },
+  { label: "Overview", active: true },
+  { label: "Projects" },
+];
+
+function DashboardScreen(): ReactNode {
+  return (
+    <DashboardPage
+      appName="Example"
+      userName="You"
+      navLinks={[{ label: "Home", active: true }]}
+      sidebarItems={SIDEBAR}
+    >
+      <div style={{ padding: 20 }}>
+        <h2
+          style={{
+            margin: 0,
+            fontSize: 15,
+            fontWeight: 600,
+            color: "var(--scenar-foreground)",
+          }}
+        >
+          Welcome back
+        </h2>
+      </div>
+    </DashboardPage>
+  );
+}
+`;
+
+const TOUR_PROVIDERS = `/**
+ * .scenar/providers.tsx — wraps every step of THIS tour in \`scenar pack\` (embed)
+ * and \`scenar render\` (video).
+ *
+ * You only need this when your tour renders real, data-fetching components that
+ * need a client/provider to render in isolation (no backend). A tour built only
+ * from @scenar/react shells (like the starter) can leave this as a pass-through
+ * or delete it.
+ *
+ * Recommended pattern for Connect-RPC SDKs (e.g. @stigmer/react): mock data with
+ * an in-process router transport — no network, no service worker — and resolve
+ * the embed's light/dark mode from \`getEmbedColorMode()\`. Fill in your client,
+ * provider, and fixtures, then return the provider instead of the fragment:
+ *
+ *   import "@your-org/react/styles.css";
+ *   import { createRouterTransport } from "@connectrpc/connect";
+ *   import { getEmbedColorMode } from "@scenar/react";
+ *   import { YourClient } from "@your-org/sdk";
+ *   import { YourProvider } from "@your-org/react";
+ *   import { YourController } from "@your-org/protos/...";
+ *
+ *   const transport = createRouterTransport((router) => {
+ *     router.service(YourController, { get: () => yourFixtureObject });
+ *   });
+ *   const client = new YourClient({ baseUrl: "/", customTransport: transport });
+ *
+ *   export function PreviewProviders({ children }: { readonly children: ReactNode }) {
+ *     return (
+ *       <YourProvider client={client} colorMode={getEmbedColorMode()}>
+ *         {children}
+ *       </YourProvider>
+ *     );
+ *   }
+ */
+import type { ReactNode } from "react";
+
+export function PreviewProviders({ children }: { readonly children: ReactNode }) {
+  return <>{children}</>;
+}
+`;

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

@@ -48,6 +48,17 @@ export declare 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).
  */
 export declare function generateEmbedHtml(scenarioId: string, entryFileName: string): string;
 //# sourceMappingURL=generate-embed-entry.d.ts.map

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;;;;;;;;;;;;;;;;;;;;;;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"}
+{"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,CAqKjE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAoBnF"}

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

@@ -88,6 +88,25 @@ export function generateEmbedEntry(input) {
     lines.push(`  catch { return null; }`);
     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):
@@ -162,6 +181,17 @@ export function generateEmbedEntry(input) {
  * 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).
  */
 export function generateEmbedHtml(scenarioId, entryFileName) {
     return [
@@ -170,7 +200,11 @@ export function generateEmbedHtml(scenarioId, entryFileName) {
         `  <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; }`,
+        `    </style>`,
         `  </head>`,
         `  <body>`,
         `    <div id="root"></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

@@ -120,6 +120,26 @@ 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):
@@ -197,6 +217,17 @@ 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).
  */
 export function generateEmbedHtml(scenarioId: string, entryFileName: string): string {
   return [
@@ -205,7 +236,11 @@ export function generateEmbedHtml(scenarioId: string, entryFileName: string): st
     `  <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; }`,
+    `    </style>`,
     `  </head>`,
     `  <body>`,
     `    <div id="root"></div>`,

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

@@ -10,7 +10,7 @@ export interface PackFile {
     /** Content type the server binds into the presign and the edge serves. */
     readonly contentType: string;
 }
-/** The deploy instruction file `scenar deploy` consumes. */
+/** The deploy instruction file the upload backend consumes. */
 export interface PackManifest {
     readonly schemaVersion: number;
     readonly scenarioId: string;