@scenar/cli 0.9.1 → 0.11.0

package/src/__tests__/scenario-validator.test.ts

@@ -44,6 +44,66 @@ describe("validateScenario", () => {
     expect(validateScenario(s).valid).toBe(true);
   });
 
+  // --- Presenter (per-step opt-in, requires narration) ---
+
+  it("accepts presenter: true on a narrated step", () => {
+    const s = validScenario();
+    s.steps[0] = { ...s.steps[0]!, presenter: true } as typeof s.steps[0];
+    expect(validateScenario(s).valid).toBe(true);
+  });
+
+  it("accepts presenter: false on a step without narration", () => {
+    const s = validScenario();
+    s.steps[0] = {
+      view: "intro",
+      delayMs: 0,
+      presenter: false,
+    } as unknown as typeof s.steps[0];
+    expect(validateScenario(s).valid).toBe(true);
+  });
+
+  it("rejects presenter: true on a step without narration, naming step, field, and rule", () => {
+    const s = validScenario();
+    s.steps[0] = {
+      view: "intro",
+      delayMs: 0,
+      presenter: true,
+    } as unknown as typeof s.steps[0];
+
+    const result = validateScenario(s);
+    expect(result.valid).toBe(false);
+    expect(result.errors[0]!.path).toBe("steps[0].presenter");
+    expect(result.errors[0]!.reason).toBe(
+      "presenter requires narration_text — a presenter clip is derived from the step's narration audio.",
+    );
+  });
+
+  it("rejects presenter: true when narrationText is empty", () => {
+    const s = validScenario();
+    s.steps[0] = {
+      ...s.steps[0]!,
+      narrationText: "",
+      presenter: true,
+    } as typeof s.steps[0];
+
+    const result = validateScenario(s);
+    expect(result.valid).toBe(false);
+    expect(result.errors[0]!.path).toBe("steps[0].presenter");
+  });
+
+  it("rejects a non-boolean presenter", () => {
+    const s = validScenario();
+    s.steps[0] = {
+      ...s.steps[0]!,
+      presenter: "yes",
+    } as unknown as typeof s.steps[0];
+
+    const result = validateScenario(s);
+    expect(result.valid).toBe(false);
+    expect(result.errors[0]!.path).toBe("steps[0].presenter");
+    expect(result.errors[0]!.reason).toBe("presenter must be a boolean.");
+  });
+
   // --- Root-level errors ---
 
   it("rejects null", () => {
@@ -349,4 +409,118 @@ describe("validateScenario", () => {
     expect(result.valid).toBe(false);
     expect(result.errors.length).toBeGreaterThanOrEqual(4);
   });
+
+  // --- Soundtrack ---
+
+  it("accepts a valid soundtrack, including explicit 0.0 volumes", () => {
+    const result = validateScenario({
+      steps: [{ view: "x", delayMs: 0 }],
+      soundtrack: {
+        musicSrc: "./soundtrack/music.mp3",
+        musicVolume: 0.25,
+        duckingVolume: 0,
+        sfx: true,
+      },
+    });
+    expect(result.valid).toBe(true);
+  });
+
+  it("accepts a soundtrack with only sfx (no music)", () => {
+    const result = validateScenario({
+      steps: [{ view: "x", delayMs: 0 }],
+      soundtrack: { sfx: true },
+    });
+    expect(result.valid).toBe(true);
+  });
+
+  it("rejects a non-object soundtrack", () => {
+    const result = validateScenario({
+      steps: [{ view: "x", delayMs: 0 }],
+      soundtrack: "music.mp3",
+    });
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: "soundtrack" }),
+    );
+  });
+
+  it("rejects an empty musicSrc", () => {
+    const result = validateScenario({
+      steps: [{ view: "x", delayMs: 0 }],
+      soundtrack: { musicSrc: "" },
+    });
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: "soundtrack.musicSrc" }),
+    );
+  });
+
+  it.each([
+    ["musicVolume above 1", { musicVolume: 1.2 }, "soundtrack.musicVolume"],
+    ["musicVolume negative", { musicVolume: -0.1 }, "soundtrack.musicVolume"],
+    ["musicVolume non-numeric", { musicVolume: "loud" }, "soundtrack.musicVolume"],
+    ["duckingVolume above 1", { duckingVolume: 2 }, "soundtrack.duckingVolume"],
+  ])("rejects %s", (_name, soundtrack, expectedPath) => {
+    const result = validateScenario({
+      steps: [{ view: "x", delayMs: 0 }],
+      soundtrack,
+    });
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: expectedPath }),
+    );
+  });
+
+  it("rejects a non-boolean sfx", () => {
+    const result = validateScenario({
+      steps: [{ view: "x", delayMs: 0 }],
+      soundtrack: { sfx: "yes" },
+    });
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: "soundtrack.sfx" }),
+    );
+  });
+
+  it("accepts valid title cards, one-sided or both", () => {
+    for (const titleCards of [
+      { intro: { title: "Acme", subtitle: "Fast", logoSrc: "./logo.png" } },
+      { outro: { title: "Try it", ctaText: "acme.dev", durationMs: 4000 } },
+      { intro: { title: "Acme" }, outro: { title: "Bye" } },
+    ]) {
+      const result = validateScenario({
+        steps: [{ view: "x", delayMs: 0 }],
+        titleCards,
+      });
+      expect(result.valid).toBe(true);
+    }
+  });
+
+  it("rejects a non-object titleCards", () => {
+    const result = validateScenario({
+      steps: [{ view: "x", delayMs: 0 }],
+      titleCards: "intro",
+    });
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: "titleCards" }),
+    );
+  });
+
+  it.each([
+    ["a missing title", { intro: {} }, "titleCards.intro.title"],
+    ["an empty title", { outro: { title: "" } }, "titleCards.outro.title"],
+    ["an empty subtitle", { intro: { title: "T", subtitle: "" } }, "titleCards.intro.subtitle"],
+    ["an empty logoSrc", { intro: { title: "T", logoSrc: "" } }, "titleCards.intro.logoSrc"],
+    ["an empty ctaText", { outro: { title: "T", ctaText: "" } }, "titleCards.outro.ctaText"],
+    ["a zero durationMs", { intro: { title: "T", durationMs: 0 } }, "titleCards.intro.durationMs"],
+    [
+      "a negative durationMs",
+      { intro: { title: "T", durationMs: -100 } },
+      "titleCards.intro.durationMs",
+    ],
+  ])("rejects a card with %s", (_name, titleCards, expectedPath) => {
+    const result = validateScenario({
+      steps: [{ view: "x", delayMs: 0 }],
+      titleCards,
+    });
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({ path: expectedPath }),
+    );
+  });
 });

package/src/__tests__/stage-assets.test.ts

@@ -0,0 +1,269 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, mkdir, readFile, writeFile, rm, access } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { stageRenderAssets } from "../render/stage-assets.js";
+import {
+  SFX_DEST_PATHS,
+  isRemoteUrl,
+  resolveMusicAsset,
+  resolveSfxAssetPaths,
+} from "../util/soundtrack-assets.js";
+import { resolveLogoAsset } from "../util/scenario-assets.js";
+
+let scenarioDir: string;
+let publicDir: string;
+
+beforeEach(async () => {
+  scenarioDir = await mkdtemp(join(tmpdir(), "scenar-stage-"));
+  publicDir = join(scenarioDir, ".scenar-render", "public");
+});
+
+afterEach(async () => {
+  await rm(scenarioDir, { recursive: true, force: true });
+});
+
+async function exists(path: string): Promise<boolean> {
+  return access(path).then(
+    () => true,
+    () => false,
+  );
+}
+
+describe("stageRenderAssets", () => {
+  it("stages narration clips flat at the public root (srcs are ./step-N.mp3)", async () => {
+    await mkdir(join(scenarioDir, "narration"), { recursive: true });
+    await writeFile(join(scenarioDir, "narration", "step-0.mp3"), "audio-0");
+    await writeFile(join(scenarioDir, "narration", "step-2.mp3"), "audio-2");
+    await writeFile(join(scenarioDir, "narration", "manifest.json"), "{}");
+
+    const staged = await stageRenderAssets({
+      scenarioDir,
+      publicDir,
+      hasNarration: true,
+    });
+
+    expect(staged).toBe(2);
+    expect(await readFile(join(publicDir, "step-0.mp3"), "utf-8")).toBe("audio-0");
+    expect(await readFile(join(publicDir, "step-2.mp3"), "utf-8")).toBe("audio-2");
+    // The manifest itself is imported by the entry, never served.
+    expect(await exists(join(publicDir, "manifest.json"))).toBe(false);
+  });
+
+  it("stages presenter clips flat at the public root beside narration (srcs are ./step-N.mp4)", async () => {
+    await mkdir(join(scenarioDir, "narration"), { recursive: true });
+    await writeFile(join(scenarioDir, "narration", "step-0.mp3"), "audio-0");
+    await writeFile(join(scenarioDir, "narration", "manifest.json"), "{}");
+    await mkdir(join(scenarioDir, "presenter"), { recursive: true });
+    await writeFile(join(scenarioDir, "presenter", "step-0.mp4"), "clip-0");
+    await writeFile(join(scenarioDir, "presenter", "manifest.json"), "{}");
+    await writeFile(join(scenarioDir, "presenter", ".presenter-cache.json"), "{}");
+
+    const staged = await stageRenderAssets({
+      scenarioDir,
+      publicDir,
+      hasNarration: true,
+      hasPresenter: true,
+    });
+
+    // step-0.mp3 + step-0.mp4 — same basename, different extensions, no collision.
+    expect(staged).toBe(2);
+    expect(await readFile(join(publicDir, "step-0.mp3"), "utf-8")).toBe("audio-0");
+    expect(await readFile(join(publicDir, "step-0.mp4"), "utf-8")).toBe("clip-0");
+    // Manifests are imported by the entry; the cache never leaves the scenario.
+    expect(await exists(join(publicDir, "manifest.json"))).toBe(false);
+    expect(await exists(join(publicDir, ".presenter-cache.json"))).toBe(false);
+  });
+
+  it("stages no presenter clips when the scenario has none", async () => {
+    const staged = await stageRenderAssets({
+      scenarioDir,
+      publicDir,
+      hasNarration: false,
+      hasPresenter: false,
+    });
+    expect(staged).toBe(0);
+  });
+
+  it("stages the music asset at its scenario-relative path", async () => {
+    await mkdir(join(scenarioDir, "soundtrack"), { recursive: true });
+    await writeFile(join(scenarioDir, "soundtrack", "music.mp3"), "music-bytes");
+
+    const staged = await stageRenderAssets({
+      scenarioDir,
+      publicDir,
+      hasNarration: false,
+      soundtrack: { musicSrc: "./soundtrack/music.mp3" },
+    });
+
+    expect(staged).toBe(1);
+    expect(await readFile(join(publicDir, "soundtrack", "music.mp3"), "utf-8")).toBe(
+      "music-bytes",
+    );
+  });
+
+  it("stages the built-in SFX set at the shared destinations", async () => {
+    const clickSource = join(scenarioDir, "fake-click.mp3");
+    const keystrokeSource = join(scenarioDir, "fake-keystroke.mp3");
+    await writeFile(clickSource, "click-bytes");
+    await writeFile(keystrokeSource, "keystroke-bytes");
+
+    const staged = await stageRenderAssets({
+      scenarioDir,
+      publicDir,
+      hasNarration: false,
+      soundtrack: { sfx: true },
+      sfxPaths: { click: clickSource, keystroke: keystrokeSource },
+    });
+
+    expect(staged).toBe(2);
+    expect(await readFile(join(publicDir, SFX_DEST_PATHS.click), "utf-8")).toBe("click-bytes");
+    expect(await readFile(join(publicDir, SFX_DEST_PATHS.keystroke), "utf-8")).toBe(
+      "keystroke-bytes",
+    );
+  });
+
+  it("stages title-card logos at their scenario-relative paths", async () => {
+    await writeFile(join(scenarioDir, "logo.png"), "logo-bytes");
+
+    const staged = await stageRenderAssets({
+      scenarioDir,
+      publicDir,
+      hasNarration: false,
+      titleCards: { intro: { title: "Acme", logoSrc: "./logo.png" } },
+    });
+
+    expect(staged).toBe(1);
+    expect(await readFile(join(publicDir, "logo.png"), "utf-8")).toBe("logo-bytes");
+  });
+
+  it("stages a logo shared by intro and outro exactly once", async () => {
+    await writeFile(join(scenarioDir, "logo.png"), "logo-bytes");
+
+    const staged = await stageRenderAssets({
+      scenarioDir,
+      publicDir,
+      hasNarration: false,
+      titleCards: {
+        intro: { title: "Acme", logoSrc: "./logo.png" },
+        outro: { title: "Bye", logoSrc: "./logo.png" },
+      },
+    });
+
+    expect(staged).toBe(1);
+  });
+
+  it("stages nothing (and reports zero) for a silent, card-less scenario", async () => {
+    const staged = await stageRenderAssets({
+      scenarioDir,
+      publicDir,
+      hasNarration: false,
+    });
+    expect(staged).toBe(0);
+    expect(await exists(publicDir)).toBe(false);
+  });
+
+  it("skips remote music URLs — they are referenced, not copied", async () => {
+    const staged = await stageRenderAssets({
+      scenarioDir,
+      publicDir,
+      hasNarration: false,
+      soundtrack: { musicSrc: "https://cdn.example.com/music.mp3" },
+    });
+    expect(staged).toBe(0);
+  });
+
+  it("fails loudly when the music file is missing (a silent render otherwise)", async () => {
+    await expect(
+      stageRenderAssets({
+        scenarioDir,
+        publicDir,
+        hasNarration: false,
+        soundtrack: { musicSrc: "./soundtrack/missing.mp3" },
+      }),
+    ).rejects.toThrow(/not found/);
+  });
+
+  it("fails loudly when a card's logo file is missing (a broken card otherwise)", async () => {
+    await expect(
+      stageRenderAssets({
+        scenarioDir,
+        publicDir,
+        hasNarration: false,
+        titleCards: { outro: { title: "Bye", logoSrc: "./missing.png" } },
+      }),
+    ).rejects.toThrow(/not found/);
+  });
+});
+
+describe("resolveMusicAsset", () => {
+  it("rejects paths escaping the scenario directory", async () => {
+    await expect(resolveMusicAsset(scenarioDir, "../outside.mp3")).rejects.toThrow(
+      /outside the scenario directory/,
+    );
+  });
+
+  it("returns null for remote URLs", async () => {
+    expect(await resolveMusicAsset(scenarioDir, "https://cdn.example.com/a.mp3")).toBeNull();
+  });
+});
+
+describe("resolveLogoAsset", () => {
+  it("rejects paths escaping the scenario directory", async () => {
+    await expect(
+      resolveLogoAsset(scenarioDir, "../outside.png", "titleCards.intro.logoSrc"),
+    ).rejects.toThrow(/outside the scenario directory/);
+  });
+
+  it("returns null for remote URLs", async () => {
+    expect(
+      await resolveLogoAsset(
+        scenarioDir,
+        "https://cdn.example.com/logo.png",
+        "titleCards.intro.logoSrc",
+      ),
+    ).toBeNull();
+  });
+
+  it("rejects extensions the deploy contract cannot serve — svg above all", async () => {
+    await writeFile(join(scenarioDir, "logo.svg"), "<svg/>");
+    await expect(
+      resolveLogoAsset(scenarioDir, "./logo.svg", "titleCards.intro.logoSrc"),
+    ).rejects.toThrow(/not a supported image format/);
+  });
+
+  it("accepts every allowlisted raster format", async () => {
+    for (const ext of ["png", "jpg", "jpeg", "gif", "webp", "avif"]) {
+      await writeFile(join(scenarioDir, `logo.${ext}`), "bytes");
+      const asset = await resolveLogoAsset(
+        scenarioDir,
+        `./logo.${ext}`,
+        "titleCards.intro.logoSrc",
+      );
+      expect(asset?.destRelPath).toBe(`logo.${ext}`);
+    }
+  });
+});
+
+describe("isRemoteUrl", () => {
+  it.each([
+    ["https://cdn.example.com/a.mp3", true],
+    ["http://x/a.mp3", true],
+    ["./soundtrack/music.mp3", false],
+    ["soundtrack/music.mp3", false],
+  ])("%s -> %s", (src, expected) => {
+    expect(isRemoteUrl(src)).toBe(expected);
+  });
+});
+
+describe("resolveSfxAssetPaths", () => {
+  it("resolves the real assets from a workspace context", async () => {
+    // This test file lives inside the repo, where @scenar/react is
+    // installed — the same resolution a consumer project gets.
+    const fromDir = dirname(fileURLToPath(import.meta.url));
+    const paths = resolveSfxAssetPaths(fromDir);
+    expect(await exists(paths.click)).toBe(true);
+    expect(await exists(paths.keystroke)).toBe(true);
+  });
+});

package/src/commands/narrate.js

@@ -6,7 +6,7 @@ export function registerNarrateCommand(program) {
         "Accepts a YAML file, a TypeScript steps file, or a directory\n" +
         "containing scenario subdirectories (each with a steps.ts).")
         .argument("<file-or-dir>", "path to scenario file (.yaml/.ts) or directory")
-        .option("--tts <provider>", "TTS provider: echogarden, edge-tts, or openai", "echogarden")
+        .option("--tts <provider>", "TTS provider: echogarden, edge-tts, openai, or elevenlabs", "echogarden")
         .option("--out <dir>", "output directory for audio files")
         .option("--voice <voice>", "voice name (provider-specific)")
         .option("--base-url <path>", "URL path prefix for src fields in manifest")

package/src/commands/narrate.js.map

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

package/src/commands/narrate.ts

@@ -17,7 +17,7 @@ export function registerNarrateCommand(program: Command): void {
         "containing scenario subdirectories (each with a steps.ts).",
     )
     .argument("<file-or-dir>", "path to scenario file (.yaml/.ts) or directory")
-    .option("--tts <provider>", "TTS provider: echogarden, edge-tts, or openai", "echogarden")
+    .option("--tts <provider>", "TTS provider: echogarden, edge-tts, openai, or elevenlabs", "echogarden")
     .option("--out <dir>", "output directory for audio files")
     .option("--voice <voice>", "voice name (provider-specific)")
     .option("--base-url <path>", "URL path prefix for src fields in manifest")

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

@@ -1 +1 @@
-{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../../src/commands/pack.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkBpC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuD1D"}
+{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../../src/commands/pack.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkBpC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA6D1D"}

package/src/commands/pack.js

@@ -22,8 +22,12 @@ export function registerPackCommand(program) {
         "Output defaults to ./<scenario-id>-bundle. Use --out to override.")
         .argument("<dir>", "path to a scenario directory (must contain steps.ts)")
         .option("--out <path>", "output directory for the bundle")
-        .option("--width <number>", `canonical viewport width in px (default: ${DEFAULT_WIDTH})`, String(DEFAULT_WIDTH))
-        .option("--shell-height <number>", `shell height in px (default: ${DEFAULT_SHELL_HEIGHT})`, String(DEFAULT_SHELL_HEIGHT))
+        // No commander defaults on the viewport flags: an absent flag must stay
+        // absent so the scenario's own authored viewport can apply (resolution
+        // in runPack: flags > authored > default). A baked-in default here made
+        // `createScenario({ viewport })` silently unreachable.
+        .option("--width <number>", `canonical viewport width in px (default: the scenario's authored viewport, else ${DEFAULT_WIDTH})`)
+        .option("--shell-height <number>", `shell height in px (default: the scenario's authored viewport, else ${DEFAULT_SHELL_HEIGHT})`)
         .option("--stage", "float the scenario on a backdrop with a window shadow (screen-recording framing); " +
         "the embed paints its own background instead of staying transparent")
         .option("--keep-temp", "keep the generated entry directory for debugging")
@@ -32,8 +36,8 @@ export function registerPackCommand(program) {
             const result = await runPack({
                 scenarioDir: dir,
                 outDir: options.out,
-                width: Number(options.width) || DEFAULT_WIDTH,
-                shellHeight: Number(options.shellHeight) || DEFAULT_SHELL_HEIGHT,
+                width: parseViewportFlag("--width", options.width),
+                shellHeight: parseViewportFlag("--shell-height", options.shellHeight),
                 stage: options.stage ?? false,
                 keepTemp: options.keepTemp,
                 onLog: (message) => process.stderr.write(`${message}\n`),
@@ -49,6 +53,21 @@ export function registerPackCommand(program) {
         }
     });
 }
+/**
+ * Parse a viewport flag into a positive number, or `undefined` when the flag
+ * was not given. A malformed value errors instead of silently falling back —
+ * the previous `Number(x) || DEFAULT` coercion turned `--width 128O` (typo)
+ * into a default-size bundle with no warning.
+ */
+function parseViewportFlag(flag, value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`${flag} must be a positive number, got "${value}".`);
+    }
+    return parsed;
+}
 function formatBytes(bytes) {
     if (bytes < 1024)
         return `${bytes} B`;

package/src/commands/pack.js.map

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

package/src/commands/pack.ts

@@ -36,11 +36,17 @@ export function registerPackCommand(program: Command): void {
     )
     .argument("<dir>", "path to a scenario directory (must contain steps.ts)")
     .option("--out <path>", "output directory for the bundle")
-    .option("--width <number>", `canonical viewport width in px (default: ${DEFAULT_WIDTH})`, String(DEFAULT_WIDTH))
+    // No commander defaults on the viewport flags: an absent flag must stay
+    // absent so the scenario's own authored viewport can apply (resolution
+    // in runPack: flags > authored > default). A baked-in default here made
+    // `createScenario({ viewport })` silently unreachable.
+    .option(
+      "--width <number>",
+      `canonical viewport width in px (default: the scenario's authored viewport, else ${DEFAULT_WIDTH})`,
+    )
     .option(
       "--shell-height <number>",
-      `shell height in px (default: ${DEFAULT_SHELL_HEIGHT})`,
-      String(DEFAULT_SHELL_HEIGHT),
+      `shell height in px (default: the scenario's authored viewport, else ${DEFAULT_SHELL_HEIGHT})`,
     )
     .option(
       "--stage",
@@ -53,8 +59,8 @@ export function registerPackCommand(program: Command): void {
         const result = await runPack({
           scenarioDir: dir,
           outDir: options.out,
-          width: Number(options.width) || DEFAULT_WIDTH,
-          shellHeight: Number(options.shellHeight) || DEFAULT_SHELL_HEIGHT,
+          width: parseViewportFlag("--width", options.width),
+          shellHeight: parseViewportFlag("--shell-height", options.shellHeight),
           stage: options.stage ?? false,
           keepTemp: options.keepTemp,
           onLog: (message) => process.stderr.write(`${message}\n`),
@@ -73,6 +79,21 @@ export function registerPackCommand(program: Command): void {
     });
 }
 
+/**
+ * Parse a viewport flag into a positive number, or `undefined` when the flag
+ * was not given. A malformed value errors instead of silently falling back —
+ * the previous `Number(x) || DEFAULT` coercion turned `--width 128O` (typo)
+ * into a default-size bundle with no warning.
+ */
+function parseViewportFlag(flag: string, value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${flag} must be a positive number, got "${value}".`);
+  }
+  return parsed;
+}
+
 function formatBytes(bytes: number): string {
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KiB`;

package/src/commands/presenter.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"presenter.d.ts","sourceRoot":"","sources":["../../../src/commands/presenter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiBpC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyF/D"}