@scenar/cli 0.2.1 → 0.4.0

package/example-bundle/embed.js

@@ -0,0 +1 @@
+var ScenarEmbed=function(o){"use strict";var I=Object.defineProperty;var N=(o,u,d)=>u in o?I(o,u,{enumerable:!0,configurable:!0,writable:!0,value:d}):o[u]=d;var E=(o,u,d)=>N(o,typeof u!="symbol"?u+"":u,d);const u="scenar-embed";function g(e){return{source:u,v:1,...e}}function S(e){if(typeof e!="object"||e===null)return!1;const s=e;return s.source===u&&s.v===1}function l(e){return typeof e=="number"&&Number.isFinite(e)}function A(e){if(!S(e))return null;const s=e.type;switch(s){case"started":case"paused":case"completed":case"audioBlocked":return{type:s};case"ready":return l(e.totalSteps)&&typeof e.hasNarration=="boolean"?{type:s,totalSteps:e.totalSteps,hasNarration:e.hasNarration}:null;case"resize":return l(e.widthPx)&&l(e.heightPx)?{type:s,widthPx:e.widthPx,heightPx:e.heightPx}:null;case"stepchange":return l(e.stepIndex)&&l(e.totalSteps)?{type:s,stepIndex:e.stepIndex,totalSteps:e.totalSteps}:null;case"progress":return l(e.stepIndex)&&l(e.totalSteps)&&l(e.fraction)?{type:s,stepIndex:e.stepIndex,totalSteps:e.totalSteps,fraction:e.fraction}:null;case"error":return typeof e.message=="string"?{type:s,message:e.message}:null;default:return null}}function w(e,s={}){const{iframe:t,origin:n}=e,{onEvent:r}=s,a=typeof window<"u",c=i=>{var h;(h=t.contentWindow)==null||h.postMessage(g(i),n)},f=i=>{if(i.source!==t.contentWindow||i.origin!==n)return;const h=A(i.data);h&&(r==null||r(h))};return a&&window.addEventListener("message",f),{play:()=>c({type:"play"}),pause:()=>c({type:"pause"}),seek:i=>c({type:"seek",timeMs:i}),setMuted:i=>c({type:"setMuted",muted:i}),setVolume:i=>c({type:"setVolume",volume:i}),prefetch:()=>c({type:"prefetch"}),destroy:()=>{c({type:"destroy"}),a&&window.removeEventListener("message",f)}}}const T=896,C=480;function M(e,s){return e==="light"?"light":e==="dark"||s?"dark":"light"}function _(e,s){const t=new URL(e);return t.searchParams.set("theme",s),t.toString()}function P(e){return new URL(e).origin}function R(){return typeof document<"u"&&document.documentElement.classList.contains("dark")}function O(e,s){const{src:t,theme:n="auto",onAspectRatio:r,onEvent:a}=s,c=P(t);let f=null;const i=()=>{const m=M(n,R());m!==f&&(f=m,e.src=_(t,m))},h=w({iframe:e,origin:c},{onEvent:m=>{m.type==="resize"&&(r==null||r({widthPx:m.widthPx,heightPx:m.heightPx})),a==null||a(m)}});let p;return n==="auto"&&typeof MutationObserver<"u"&&typeof document<"u"&&(p=new MutationObserver(i),p.observe(document.documentElement,{attributes:!0,attributeFilter:["class"]})),i(),{controller:h,destroy(){p==null||p.disconnect(),h.destroy()}}}const k="scenar-embed",x="Interactive product tour",L=typeof HTMLElement<"u"?HTMLElement:class{};class y extends L{constructor(){super(...arguments);E(this,"iframe",null);E(this,"mount",null)}static get observedAttributes(){return["src","title","theme"]}connectedCallback(){this.iframe||this.render(),this.attach()}disconnectedCallback(){var t;(t=this.mount)==null||t.destroy(),this.mount=null}attributeChangedCallback(t,n,r){if(n!==r){if(t==="title"){this.iframe&&this.iframe.setAttribute("title",this.titleAttr());return}this.isConnected&&this.attach()}}play(){var t;(t=this.mount)==null||t.controller.play()}pause(){var t;(t=this.mount)==null||t.controller.pause()}seek(t){var n;(n=this.mount)==null||n.controller.seek(t)}setMuted(t){var n;(n=this.mount)==null||n.controller.setMuted(t)}setVolume(t){var n;(n=this.mount)==null||n.controller.setVolume(t)}titleAttr(){return this.getAttribute("title")??x}themeAttr(){const t=this.getAttribute("theme");return t==="light"||t==="dark"?t:"auto"}setAspectRatio(t,n){this.style.aspectRatio=`${t} / ${n}`}render(){this.style.display="block",this.style.position="relative",this.style.width="100%",this.setAspectRatio(T,C);const t=document.createElement("iframe");t.setAttribute("title",this.titleAttr()),t.setAttribute("loading","lazy"),t.setAttribute("allow","autoplay; fullscreen"),t.setAttribute("allowfullscreen",""),t.style.cssText="position:absolute;inset:0;width:100%;height:100%;border:0;border-radius:inherit",this.appendChild(t),this.iframe=t}attach(){var n;const t=this.getAttribute("src");!t||!this.iframe||((n=this.mount)==null||n.destroy(),this.mount=O(this.iframe,{src:t,theme:this.themeAttr(),onAspectRatio:({widthPx:r,heightPx:a})=>this.setAspectRatio(r,a),onEvent:r=>this.dispatchEvent(new CustomEvent(`scenar:${r.type}`,{detail:r}))}))}}function b(e=k){typeof customElements>"u"||customElements.get(e)||customElements.define(e,y)}return b(),o.ScenarEmbedElement=y,o.defineScenarEmbed=b,Object.defineProperty(o,Symbol.toStringTag,{value:"Module"}),o}({});

package/example-bundle/pack-manifest.json

@@ -20,6 +20,12 @@
       "sizeBytes": 30458,
       "contentType": "text/css"
     },
+    {
+      "path": "embed.js",
+      "sha256": "87ebc6301237b7b99b1f7eb8ab5e4e89362888b7d03a289af592e0cd38922c99",
+      "sizeBytes": 4574,
+      "contentType": "text/javascript"
+    },
     {
       "path": "index.html",
       "sha256": "242a0d2b71f1cc01a1c61a75fb605ae35997d0d943a9b4bd71fd982c7aef51e3",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenar/cli",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Scenar CLI — validate scenarios, generate narration, and render videos.",
   "license": "Apache-2.0",
   "type": "module",
@@ -39,13 +39,9 @@
     }
   },
   "dependencies": {
-    "@bufbuild/protobuf": "^2.2.2",
-    "@connectrpc/connect": "^2.0.0",
-    "@connectrpc/connect-node": "^2.0.0",
-    "@scenar/core": "0.2.1",
-    "@scenar/preview": "0.2.1",
-    "@scenar/sdk": "0.2.1",
-    "@scenar/stubs": "0.2.1",
+    "@scenar/core": "0.4.0",
+    "@scenar/embed": "0.4.0",
+    "@scenar/sdk": "0.4.0",
     "commander": "^13.0.0",
     "yaml": "^2.7.0"
   },

package/src/__tests__/embed-loader.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from "vitest";
+import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { copyEmbedLoader, EMBED_LOADER_FILE } from "../pack/embed-loader.js";
+
+describe("copyEmbedLoader", () => {
+  it("copies @scenar/embed's loader into the bundle as embed.js (idempotent)", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "scenar-loader-"));
+    try {
+      await copyEmbedLoader(dir);
+
+      const dest = join(dir, EMBED_LOADER_FILE);
+      const info = await stat(dest);
+      expect(info.isFile()).toBe(true);
+      expect(info.size).toBeGreaterThan(0);
+
+      // It is the IIFE loader that registers the custom element.
+      const js = await readFile(dest, "utf-8");
+      expect(js).toContain("scenar-embed");
+
+      // Copying again overwrites cleanly (same bytes) — pack can re-run safely.
+      await copyEmbedLoader(dir);
+      expect(await readFile(dest, "utf-8")).toBe(js);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/__tests__/embed-snippet.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { buildEmbedSnippet } from "../deploy/embed-snippet.js";
+import { buildEmbedSnippet, buildEnhancedEmbedSnippet } from "../embed/embed-snippet.js";
 
 describe("buildEmbedSnippet", () => {
   const embedUrl = "https://d-dep1.scenarusercontent.net/";
@@ -54,3 +54,50 @@ describe("buildEmbedSnippet", () => {
     expect(snippet).toContain("max-width:1280px");
   });
 });
+
+describe("buildEnhancedEmbedSnippet", () => {
+  const viewport = { width: 896, height: 480 };
+
+  it("loads the bundle's sibling embed.js and renders <scenar-embed>", () => {
+    const snippet = buildEnhancedEmbedSnippet({
+      embedUrl: "https://you.github.io/scenar-embeds/welcome/",
+      viewport,
+    });
+    expect(snippet).toContain(
+      '<script type="module" src="https://you.github.io/scenar-embeds/welcome/embed.js"></script>',
+    );
+    expect(snippet).toContain('<scenar-embed');
+    expect(snippet).toContain('src="https://you.github.io/scenar-embeds/welcome/"');
+  });
+
+  it("resolves embed.js relative to the embed URL on a local serve", () => {
+    const snippet = buildEnhancedEmbedSnippet({
+      embedUrl: "http://localhost:4173/",
+      viewport,
+    });
+    expect(snippet).toContain('src="http://localhost:4173/embed.js"');
+  });
+
+  it("uses a default title and honors an explicit one", () => {
+    const def = buildEnhancedEmbedSnippet({ embedUrl: "https://x.test/", viewport });
+    expect(def).toContain('title="Scenar embed"');
+
+    const named = buildEnhancedEmbedSnippet({
+      embedUrl: "https://x.test/",
+      viewport,
+      title: "Welcome tour",
+    });
+    expect(named).toContain('title="Welcome tour"');
+  });
+
+  it("escapes attribute-breaking characters", () => {
+    const snippet = buildEnhancedEmbedSnippet({
+      embedUrl: 'https://x.test/?a="1"/',
+      viewport,
+      title: '<b>"&',
+    });
+    expect(snippet).not.toContain('"1"');
+    expect(snippet).not.toContain("<b>");
+    expect(snippet).toContain("&quot;");
+  });
+});

package/src/__tests__/install-command.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createProgram } from "../index.js";
+
+describe("scenar install (command surface)", () => {
+  beforeEach(() => {
+    process.exitCode = undefined;
+  });
+
+  it("registers the install command", () => {
+    const program = createProgram();
+    const cmd = program.commands.find((c) => c.name() === "install");
+    expect(cmd).toBeDefined();
+    expect(cmd!.description()).toContain("Bootstrap a Scenar demos project");
+  });
+
+  it("takes variadic packages and exposes its options", () => {
+    const program = createProgram();
+    const cmd = program.commands.find((c) => c.name() === "install");
+    expect(cmd!.registeredArguments).toHaveLength(1);
+    expect(cmd!.registeredArguments[0]!.variadic).toBe(true);
+    const opts = cmd!.options.map((o) => o.long);
+    expect(opts).toContain("--dir");
+    expect(opts).toContain("--no-install");
+    expect(opts).toContain("--package-manager");
+  });
+});
+
+describe("scenar install (end-to-end, --no-install)", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "scenar-install-cmd-"));
+    process.exitCode = undefined;
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+  });
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  async function runInstallCommand(args: string[]): Promise<void> {
+    const program = createProgram();
+    program.exitOverride();
+    try {
+      await program.parseAsync(["node", "scenar", "install", ...args]);
+    } catch {
+      // commander throws under exitOverride; assertions cover the outcome
+    }
+  }
+
+  it("scaffolds a runnable starter tour on first run", async () => {
+    await runInstallCommand(["--no-install", "--dir", dir]);
+
+    expect(process.exitCode).not.toBe(1);
+    expect(existsSync(join(dir, "package.json"))).toBe(true);
+    expect(existsSync(join(dir, "tsconfig.json"))).toBe(true);
+    expect(existsSync(join(dir, ".gitignore"))).toBe(true);
+    expect(existsSync(join(dir, "tours/example-tour/steps.ts"))).toBe(true);
+    expect(existsSync(join(dir, "tours/example-tour/index.tsx"))).toBe(true);
+    expect(existsSync(join(dir, "tours/example-tour/.scenar/providers.tsx"))).toBe(true);
+
+    const index = await readFile(join(dir, "tours/example-tour/index.tsx"), "utf-8");
+    expect(index).toContain("renderStep");
+  });
+
+  it("never overwrites authored files on re-run", async () => {
+    await runInstallCommand(["--no-install", "--dir", dir]);
+
+    // Every scaffolded file is author-owned, so edits must survive a re-run.
+    const indexPath = join(dir, "tours/example-tour/index.tsx");
+    const marker = "// EDITED BY AUTHOR — must survive re-run\n";
+    const original = await readFile(indexPath, "utf-8");
+    await writeFile(indexPath, marker + original, "utf-8");
+
+    await runInstallCommand(["--no-install", "--dir", dir]);
+
+    const after = await readFile(indexPath, "utf-8");
+    expect(after.startsWith(marker)).toBe(true);
+  });
+
+  it("records a named dependency in package.json", async () => {
+    await runInstallCommand(["--no-install", "--dir", dir, "@stigmer/react@^1.0.0"]);
+
+    const pkg = JSON.parse(await readFile(join(dir, "package.json"), "utf-8"));
+    expect(pkg.dependencies["@stigmer/react"]).toBe("^1.0.0");
+  });
+
+  it("rejects an invalid --package-manager", async () => {
+    await runInstallCommand(["--no-install", "--dir", dir, "--package-manager", "bun"]);
+    expect(process.exitCode).toBe(1);
+  });
+});

package/src/__tests__/local-url.test.ts

@@ -0,0 +1,17 @@
+import { describe, it, expect } from "vitest";
+import { localViewUrl } from "../serve/local-url.js";
+
+describe("localViewUrl", () => {
+  it("downgrades https to http for *.localhost hosts (local edges serve http)", () => {
+    expect(localViewUrl("https://d-abc.localhost:8787/")).toBe("http://d-abc.localhost:8787/");
+    expect(localViewUrl("https://localhost:8787/")).toBe("http://localhost:8787/");
+  });
+
+  it("leaves production https URLs untouched", () => {
+    expect(localViewUrl("https://d-abc.scenar.ai/")).toBe("https://d-abc.scenar.ai/");
+  });
+
+  it("returns non-URL input unchanged", () => {
+    expect(localViewUrl("not a url")).toBe("not a url");
+  });
+});

package/src/__tests__/run-install.test.ts

@@ -0,0 +1,222 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, mkdir, writeFile, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  runInstall,
+  parseSpec,
+  detectPackageManager,
+  findWorkspaceRoot,
+} from "../install/run-install.js";
+
+const silent = () => {};
+
+describe("parseSpec", () => {
+  const cwd = "/tmp/does-not-matter";
+
+  it("parses a bare name", () => {
+    expect(parseSpec("react", cwd)).toEqual({ name: "react", range: "" });
+  });
+
+  it("parses a scoped bare name", () => {
+    expect(parseSpec("@stigmer/react", cwd)).toEqual({
+      name: "@stigmer/react",
+      range: "",
+    });
+  });
+
+  it("parses name@range", () => {
+    expect(parseSpec("react@^19.0.0", cwd)).toEqual({
+      name: "react",
+      range: "^19.0.0",
+    });
+  });
+
+  it("parses @scope/name@range", () => {
+    expect(parseSpec("@stigmer/react@1.2.0", cwd)).toEqual({
+      name: "@stigmer/react",
+      range: "1.2.0",
+    });
+  });
+
+  it("rejects git/URL specs without a name", () => {
+    expect(() => parseSpec("git+https://example.com/x.git", cwd)).toThrow(
+      /no package name/,
+    );
+  });
+});
+
+describe("detectPackageManager", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "scenar-pm-"));
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it("defaults to npm when no lockfile is present", () => {
+    expect(detectPackageManager(dir)).toBe("npm");
+  });
+
+  it("detects pnpm", async () => {
+    await writeFile(join(dir, "pnpm-lock.yaml"), "", "utf-8");
+    expect(detectPackageManager(dir)).toBe("pnpm");
+  });
+
+  it("detects yarn", async () => {
+    await writeFile(join(dir, "yarn.lock"), "", "utf-8");
+    expect(detectPackageManager(dir)).toBe("yarn");
+  });
+
+  it("detects npm from package-lock.json", async () => {
+    await writeFile(join(dir, "package-lock.json"), "{}", "utf-8");
+    expect(detectPackageManager(dir)).toBe("npm");
+  });
+});
+
+describe("findWorkspaceRoot", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "scenar-ws-"));
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("detects a member via pnpm-workspace.yaml globs", async () => {
+    await writeFile(
+      join(root, "pnpm-workspace.yaml"),
+      "packages:\n  - 'packages/*'\n",
+      "utf-8",
+    );
+    const member = join(root, "packages", "demos");
+    await mkdir(member, { recursive: true });
+    expect(findWorkspaceRoot(member)).toBe(root);
+  });
+
+  it("detects a member via package.json workspaces", async () => {
+    await writeFile(
+      join(root, "package.json"),
+      JSON.stringify({ name: "root", workspaces: ["apps/*"] }),
+      "utf-8",
+    );
+    const member = join(root, "apps", "web");
+    await mkdir(member, { recursive: true });
+    expect(findWorkspaceRoot(member)).toBe(root);
+  });
+
+  it("returns null for a standalone directory", async () => {
+    const standalone = join(root, "standalone");
+    await mkdir(standalone, { recursive: true });
+    expect(findWorkspaceRoot(standalone)).toBeNull();
+  });
+});
+
+describe("runInstall (skipInstall)", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "scenar-install-"));
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  async function readPkg(d: string) {
+    return JSON.parse(await readFile(join(d, "package.json"), "utf-8"));
+  }
+
+  it("scaffolds a fresh project with a runnable starter tour", () => {
+    const result = runInstall({ cwd: dir, packages: [], onLog: silent, skipInstall: true });
+    expect(result.scaffolded).toBe(true);
+    expect(existsSync(join(dir, "package.json"))).toBe(true);
+    expect(existsSync(join(dir, ".gitignore"))).toBe(true);
+    expect(existsSync(join(dir, "tsconfig.json"))).toBe(true);
+    expect(existsSync(join(dir, "tours/example-tour/steps.ts"))).toBe(true);
+    expect(existsSync(join(dir, "tours/example-tour/index.tsx"))).toBe(true);
+    expect(existsSync(join(dir, "tours/example-tour/.scenar/providers.tsx"))).toBe(true);
+  });
+
+  it("records a bare package as '*'", async () => {
+    runInstall({ cwd: dir, packages: ["@stigmer/react"], onLog: silent, skipInstall: true });
+    const pkg = await readPkg(dir);
+    expect(pkg.dependencies["@stigmer/react"]).toBe("*");
+  });
+
+  it("records an explicit range", async () => {
+    runInstall({ cwd: dir, packages: ["@stigmer/react@^1.2.0"], onLog: silent, skipInstall: true });
+    const pkg = await readPkg(dir);
+    expect(pkg.dependencies["@stigmer/react"]).toBe("^1.2.0");
+  });
+
+  it("does not clobber an existing pin when given a bare name", async () => {
+    runInstall({ cwd: dir, packages: ["@stigmer/react@^1.2.0"], onLog: silent, skipInstall: true });
+    runInstall({ cwd: dir, packages: ["@stigmer/react"], onLog: silent, skipInstall: true });
+    const pkg = await readPkg(dir);
+    expect(pkg.dependencies["@stigmer/react"]).toBe("^1.2.0");
+  });
+
+  it("resolves a file: spec's name from its target package.json", async () => {
+    const lib = join(dir, "..", `lib-${Date.now()}`);
+    await mkdir(lib, { recursive: true });
+    await writeFile(
+      join(lib, "package.json"),
+      JSON.stringify({ name: "@local/lib", version: "0.0.0" }),
+      "utf-8",
+    );
+    try {
+      runInstall({
+        cwd: dir,
+        packages: [`file:${lib}`],
+        onLog: silent,
+        skipInstall: true,
+      });
+      const pkg = await readPkg(dir);
+      expect(pkg.dependencies["@local/lib"]).toBe(`file:${lib}`);
+    } finally {
+      await rm(lib, { recursive: true, force: true });
+    }
+  });
+
+  it("uses workspace:* for a workspace member under pnpm", async () => {
+    const root = await mkdtemp(join(tmpdir(), "scenar-ws-install-"));
+    try {
+      await writeFile(join(root, "pnpm-lock.yaml"), "", "utf-8");
+      await writeFile(
+        join(root, "pnpm-workspace.yaml"),
+        "packages:\n  - 'packages/*'\n",
+        "utf-8",
+      );
+      const reactPkg = join(root, "packages", "react");
+      await mkdir(reactPkg, { recursive: true });
+      await writeFile(
+        join(reactPkg, "package.json"),
+        JSON.stringify({ name: "@stigmer/react", version: "0.0.0" }),
+        "utf-8",
+      );
+      const demos = join(root, "packages", "demos");
+      await mkdir(demos, { recursive: true });
+
+      const result = runInstall({
+        cwd: demos,
+        packages: ["@stigmer/react"],
+        onLog: silent,
+        skipInstall: true,
+      });
+
+      expect(result.workspaceRoot).toBe(root);
+      expect(result.packageManager).toBe("pnpm");
+      const pkg = await readPkg(demos);
+      expect(pkg.dependencies["@stigmer/react"]).toBe("workspace:*");
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});

package/src/api.d.ts

@@ -21,11 +21,13 @@ export type { RunPublishOptions, PublishRunResult } from "./publish/run-publish.
 export { runPublishFlow, validateRepoName, validatePublishPath, normalizePath, pagesUrl, repoUrl, } from "./publish/publish-flow.js";
 export type { PublishFlowDeps, PublishOptions, PublishResult, } from "./publish/publish-flow.js";
 export { createGithubPublisher } from "./publish/github.js";
+export { runInstall } from "./install/run-install.js";
+export type { RunInstallOptions, RunInstallResult, ParsedSpec, PackageManager, } from "./install/run-install.js";
 export { validateScenario } from "./validate/scenario-validator.js";
 export { loadScenarioYaml } from "./util/load-yaml.js";
 export { readBundleViewport } from "./bundle/read-viewport.js";
 export type { BundleViewport } from "./bundle/read-viewport.js";
-export { buildEmbedSnippet } from "./deploy/embed-snippet.js";
+export { buildEmbedSnippet } from "./embed/embed-snippet.js";
 export { DEFAULT_VIEWPORT, parseViewport } from "./pack/viewport.js";
 export type { Viewport } from "./pack/viewport.js";
 //# sourceMappingURL=api.d.ts.map

package/src/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrE,YAAY,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG5D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAGnG,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAG7E,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACzE,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACjF,YAAY,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAG7F,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACpF,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,QAAQ,EACR,OAAO,GACR,MAAM,2BAA2B,CAAC;AACnC,YAAY,EACV,eAAe,EACf,cAAc,EACd,aAAa,GACd,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAG5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,YAAY,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACrE,YAAY,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrE,YAAY,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG5D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAGnG,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAG7E,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACzE,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACjF,YAAY,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAG7F,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACpF,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,QAAQ,EACR,OAAO,GACR,MAAM,2BAA2B,CAAC;AACnC,YAAY,EACV,eAAe,EACf,cAAc,EACd,aAAa,GACd,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAG5D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,cAAc,GACf,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,YAAY,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACrE,YAAY,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC"}

package/src/api.js

@@ -18,11 +18,13 @@ export { startBundleServer, createBundleServer } from "./serve/static-server.js"
 export { runPublish } from "./publish/run-publish.js";
 export { runPublishFlow, validateRepoName, validatePublishPath, normalizePath, pagesUrl, repoUrl, } from "./publish/publish-flow.js";
 export { createGithubPublisher } from "./publish/github.js";
+// Install (bootstrap a demos project: scaffold + add deps + run the package manager)
+export { runInstall } from "./install/run-install.js";
 // Validate
 export { validateScenario } from "./validate/scenario-validator.js";
 export { loadScenarioYaml } from "./util/load-yaml.js";
 // Bundle helpers (viewport + embed snippet)
 export { readBundleViewport } from "./bundle/read-viewport.js";
-export { buildEmbedSnippet } from "./deploy/embed-snippet.js";
+export { buildEmbedSnippet } from "./embed/embed-snippet.js";
 export { DEFAULT_VIEWPORT, parseViewport } from "./pack/viewport.js";
 //# sourceMappingURL=api.js.map

package/src/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO;AACP,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAI7C,UAAU;AACV,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAGtD,SAAS;AACT,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGnD,QAAQ;AACR,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAGjF,yBAAyB;AACzB,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAEtD,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,QAAQ,EACR,OAAO,GACR,MAAM,2BAA2B,CAAC;AAMnC,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,WAAW;AACX,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEvD,4CAA4C;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO;AACP,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAI7C,UAAU;AACV,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAGtD,SAAS;AACT,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGnD,QAAQ;AACR,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAGjF,yBAAyB;AACzB,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAEtD,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,QAAQ,EACR,OAAO,GACR,MAAM,2BAA2B,CAAC;AAMnC,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,qFAAqF;AACrF,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAQtD,WAAW;AACX,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEvD,4CAA4C;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/src/api.ts

@@ -43,6 +43,15 @@ export type {
 } from "./publish/publish-flow.js";
 export { createGithubPublisher } from "./publish/github.js";
 
+// Install (bootstrap a demos project: scaffold + add deps + run the package manager)
+export { runInstall } from "./install/run-install.js";
+export type {
+  RunInstallOptions,
+  RunInstallResult,
+  ParsedSpec,
+  PackageManager,
+} from "./install/run-install.js";
+
 // Validate
 export { validateScenario } from "./validate/scenario-validator.js";
 export { loadScenarioYaml } from "./util/load-yaml.js";
@@ -50,6 +59,6 @@ export { loadScenarioYaml } from "./util/load-yaml.js";
 // Bundle helpers (viewport + embed snippet)
 export { readBundleViewport } from "./bundle/read-viewport.js";
 export type { BundleViewport } from "./bundle/read-viewport.js";
-export { buildEmbedSnippet } from "./deploy/embed-snippet.js";
+export { buildEmbedSnippet } from "./embed/embed-snippet.js";
 export { DEFAULT_VIEWPORT, parseViewport } from "./pack/viewport.js";
 export type { Viewport } from "./pack/viewport.js";

package/src/commands/install.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerInstallCommand(program: Command): void;
+//# sourceMappingURL=install.d.ts.map

package/src/commands/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/commands/install.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA+C7D"}

package/src/commands/install.js

@@ -0,0 +1,67 @@
+import * as path from "path";
+import { runInstall } from "../install/run-install.js";
+const PACKAGE_MANAGERS = ["npm", "yarn", "pnpm"];
+export function registerInstallCommand(program) {
+    program
+        .command("install")
+        .description("Bootstrap a Scenar demos project in one step.\n\n" +
+        "Scaffolds a package.json and a runnable starter tour under\n" +
+        "tours/example-tour/ if the directory is empty, adds the given\n" +
+        "component packages as ordinary dependencies, and runs your package\n" +
+        "manager. Re-run any time — existing files are never overwritten, so\n" +
+        "your authored tours are always preserved.\n\n" +
+        "Component packages are consumed as normal dependencies — import and\n" +
+        "compose them into the tours you author under tours/. Specs are\n" +
+        "resolver-agnostic: a registry version (@stigmer/react@1.2.0),\n" +
+        "workspace:*, file:../pkg, or a git URL all work; resolution is your\n" +
+        "package manager's job.\n\n" +
+        "Inside a monorepo, the project is detected as a workspace member and\n" +
+        "the install runs at the workspace root.")
+        .argument("[packages...]", "component packages to add as dependencies (e.g. @stigmer/react)")
+        .option("--dir <path>", "project directory (default: current directory)")
+        .option("--no-install", "scaffold and record dependencies but skip the install")
+        .option("--package-manager <pm>", "force npm | yarn | pnpm instead of auto-detecting")
+        .action(async (packages, options) => {
+        try {
+            const cwd = path.resolve(options.dir ?? process.cwd());
+            const installResult = runInstall({
+                cwd,
+                packages: packages ?? [],
+                onLog: (line) => process.stderr.write(`${line}\n`),
+                skipInstall: options.install === false,
+                packageManager: parsePackageManager(options.packageManager),
+            });
+            printNextSteps(cwd, installResult.installRan);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`\x1b[31mError:\x1b[0m ${msg}\n`);
+            process.exitCode = 1;
+        }
+    });
+}
+function parsePackageManager(value) {
+    if (value === undefined)
+        return undefined;
+    if (PACKAGE_MANAGERS.includes(value)) {
+        return value;
+    }
+    throw new Error(`invalid --package-manager "${value}"; expected one of ${PACKAGE_MANAGERS.join(", ")}.`);
+}
+function printNextSteps(cwd, installRan) {
+    const rel = path.relative(process.cwd(), cwd);
+    // Prefer a short relative path, but fall back to the absolute path when the
+    // target is outside the current directory (avoids a wall of "../").
+    const where = rel === "" ? "." : rel.startsWith("..") ? cwd : rel;
+    process.stderr.write(`\n\x1b[32m✓\x1b[0m Scenar demos project ready in ${where}/\n`);
+    if (!installRan) {
+        process.stderr.write(`  \x1b[33m●\x1b[0m Install skipped — run your package manager before packing.\n`);
+    }
+    process.stderr.write(`  Next:\n`);
+    process.stderr.write(`    1. \`scenar pack tours/example-tour\` to preview the starter tour.\n`);
+    process.stderr.write(`    2. Edit tours/example-tour/index.tsx — swap the shells for your\n`);
+    process.stderr.write(`       real components (add them with \`scenar install <your-pkg>\`).\n`);
+    process.stderr.write(`    3. Wire any data they fetch in tours/example-tour/.scenar/providers.tsx.\n`);
+    process.stderr.write(`    4. \`scenar pack\` then \`scenar publish\` to ship the embed.\n`);
+}
+//# sourceMappingURL=install.js.map

package/src/commands/install.js.map

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