@scenar/cli 0.1.20 → 0.2.1

package/src/render/run-render.ts

@@ -0,0 +1,287 @@
+import { resolve, join } from "node:path";
+import { stat, mkdir, access, writeFile, rm } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { loadBundle, type CliBundle } from "../util/load-bundle.js";
+import { generateRemotionEntry } from "./generate-entry.js";
+import { resolveProvidersPath } from "./resolve-providers.js";
+import { detectRenderExport } from "./detect-render-export.js";
+
+/** Options for {@link runRender}. Paths may be relative; resolved here. */
+export interface RunRenderOptions {
+  readonly scenarioDir: string;
+  readonly out?: string;
+  readonly fps?: number;
+  readonly width?: number;
+  readonly height?: number;
+  readonly compositionId?: string;
+  readonly entry?: string;
+  readonly webpackOverride?: string;
+  readonly onLog?: (message: string) => void;
+}
+
+/** The outcome of a successful render. */
+export interface RenderResult {
+  readonly scenarioId: string;
+  readonly outputPath: string;
+  readonly steps: number;
+  readonly hasNarration: boolean;
+  readonly entryAutoGenerated: boolean;
+  readonly fps: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * Render a scenario directory to an MP4 via Remotion — the pure orchestration
+ * behind `scenar render`, with no process/exit coupling. Throws on any failure
+ * (missing directory, missing Remotion peer deps, render error). The caller
+ * formats the result/error.
+ */
+export async function runRender(options: RunRenderOptions): Promise<RenderResult> {
+  const onLog = options.onLog ?? (() => {});
+  const scenarioDir = resolve(options.scenarioDir);
+
+  const info = await stat(scenarioDir).catch(() => null);
+  if (!info) {
+    throw new Error(`${options.scenarioDir} does not exist.`);
+  }
+  if (!info.isDirectory()) {
+    throw new Error(
+      `${options.scenarioDir} is not a directory. ` +
+        "The render command requires a scenario directory (with steps.ts).",
+    );
+  }
+
+  const fps = options.fps ?? 30;
+  const width = options.width ?? 1920;
+  const height = options.height ?? 1080;
+
+  let tempDir: string | undefined;
+  try {
+    const bundle = await loadBundle(scenarioDir);
+    const scenarioId = bundle.id;
+    const compositionId = options.compositionId ?? scenarioId;
+    const outputPath = resolveOutputPath(options.out, scenarioId);
+
+    const { entryPoint, generated } = await resolveEntryPoint({
+      entryOption: options.entry,
+      scenarioDir,
+      scenarioId,
+      compositionId,
+      hasNarration: !!bundle.narrationManifest,
+      fps,
+      width,
+      height,
+    });
+    tempDir = generated?.tempDir;
+
+    const webpackOverride = options.webpackOverride
+      ? await loadWebpackOverride(options.webpackOverride)
+      : undefined;
+
+    onLog(`Scenario: ${scenarioId}`);
+    onLog(`Steps:    ${bundle.steps.length}`);
+    onLog(`Audio:    ${bundle.narrationManifest ? "yes (manifest found)" : "none"}`);
+    onLog(`Entry:    ${generated ? "(auto-generated)" : entryPoint}`);
+    if (generated?.providersPath) {
+      onLog(`Providers: ${generated.providersPath}`);
+    }
+    if (webpackOverride) {
+      onLog("Webpack:  custom override loaded");
+    }
+    onLog(`Output:   ${outputPath}`);
+    onLog(`Config:   ${width}x${height} @ ${fps}fps`);
+
+    await renderScenario({
+      bundle,
+      entryPoint,
+      compositionId,
+      outputPath,
+      fps,
+      width,
+      height,
+      webpackOverride,
+      onLog,
+    });
+
+    return {
+      scenarioId,
+      outputPath,
+      steps: bundle.steps.length,
+      hasNarration: !!bundle.narrationManifest,
+      entryAutoGenerated: !!generated,
+      fps,
+      width,
+      height,
+    };
+  } finally {
+    if (tempDir) {
+      await rm(tempDir, { recursive: true, force: true }).catch(() => {});
+    }
+  }
+}
+
+function resolveOutputPath(outOption: string | undefined, scenarioId: string): string {
+  if (!outOption) {
+    return resolve(`./${scenarioId}.mp4`);
+  }
+  if (outOption.endsWith(".mp4")) {
+    return resolve(outOption);
+  }
+  return resolve(join(outOption, `${scenarioId}.mp4`));
+}
+
+interface EntryResolutionInput {
+  entryOption: string | undefined;
+  scenarioDir: string;
+  scenarioId: string;
+  compositionId: string;
+  hasNarration: boolean;
+  fps: number;
+  width: number;
+  height: number;
+}
+
+interface EntryResolutionResult {
+  entryPoint: string;
+  generated?: {
+    tempDir: string;
+    providersPath: string | null;
+  };
+}
+
+async function resolveEntryPoint(input: EntryResolutionInput): Promise<EntryResolutionResult> {
+  // Explicit --entry: use as-is, no generation.
+  if (input.entryOption) {
+    const resolved = resolve(input.entryOption);
+    try {
+      await access(resolved);
+    } catch {
+      throw new Error(`Remotion entry point not found: ${input.entryOption}`);
+    }
+    return { entryPoint: resolved };
+  }
+
+  // Auto-generate: detect renderStep export, find providers, write temp entry.
+  const renderFilePath = await detectRenderExport(input.scenarioDir);
+  const providersPath = await resolveProvidersPath(input.scenarioDir);
+
+  const entrySource = generateRemotionEntry({
+    scenarioDir: input.scenarioDir,
+    renderFilePath,
+    scenarioId: input.scenarioId,
+    hasNarration: input.hasNarration,
+    providersPath,
+    fps: input.fps,
+    width: input.width,
+    height: input.height,
+    compositionId: input.compositionId,
+  });
+
+  // Write the entry inside the scenario directory so webpack's standard
+  // node_modules resolution walks up from here into the consumer project.
+  // A /tmp/ location would fail because no node_modules exist there.
+  const tempDir = join(input.scenarioDir, ".scenar-render");
+  await mkdir(tempDir, { recursive: true });
+
+  const entryPath = join(tempDir, "index.tsx");
+  await writeFile(entryPath, entrySource, "utf-8");
+
+  return { entryPoint: entryPath, generated: { tempDir, providersPath } };
+}
+
+async function loadWebpackOverride(overridePath: string): Promise<(config: unknown) => unknown> {
+  const resolved = resolve(overridePath);
+  try {
+    await access(resolved);
+  } catch {
+    throw new Error(`Webpack override file not found: ${overridePath}`);
+  }
+
+  let mod: Record<string, unknown>;
+  try {
+    mod = (await import(pathToFileURL(resolved).href)) as Record<string, unknown>;
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to import webpack override from ${overridePath}:\n${detail}`);
+  }
+
+  const override = (mod.default ?? mod.webpackOverride) as unknown;
+  if (typeof override !== "function") {
+    throw new Error(
+      `${overridePath} does not export a webpack override function.\n\n` +
+        "Expected a default export or named 'webpackOverride' export:\n\n" +
+        '  import type { WebpackOverrideFn } from "@remotion/bundler";\n\n' +
+        "  const webpackOverride: WebpackOverrideFn = (config) => ({\n" +
+        "    ...config,\n" +
+        "    // your overrides\n" +
+        "  });\n\n" +
+        "  export default webpackOverride;\n",
+    );
+  }
+
+  return override as (config: unknown) => unknown;
+}
+
+interface RenderConfig {
+  bundle: CliBundle;
+  entryPoint: string;
+  compositionId: string;
+  outputPath: string;
+  fps: number;
+  width: number;
+  height: number;
+  webpackOverride?: (config: unknown) => unknown;
+  onLog: (message: string) => void;
+}
+
+async function renderScenario(config: RenderConfig): Promise<void> {
+  const bundler = await import("@remotion/bundler").catch(() => {
+    throw new Error(
+      "Could not load @remotion/bundler.\nInstall it: pnpm add @remotion/bundler@4.0.448",
+    );
+  });
+
+  const renderer = await import("@remotion/renderer").catch(() => {
+    throw new Error(
+      "Could not load @remotion/renderer.\nInstall it: pnpm add @remotion/renderer@4.0.448",
+    );
+  });
+
+  config.onLog("Bundling Remotion project...");
+
+  const bundleOptions: Record<string, unknown> = { entryPoint: config.entryPoint };
+  if (config.webpackOverride) {
+    bundleOptions.webpackOverride = config.webpackOverride;
+  }
+  const serveUrl = await (bundler.bundle as (opts: Record<string, unknown>) => Promise<string>)(
+    bundleOptions,
+  );
+
+  config.onLog(`Selecting composition: ${config.compositionId}`);
+  const composition = await renderer.selectComposition({
+    serveUrl,
+    id: config.compositionId,
+  });
+
+  config.onLog(
+    `Composition: ${composition.width}x${composition.height} @ ${composition.fps}fps, ` +
+      `${composition.durationInFrames} frames ` +
+      `(${(composition.durationInFrames / composition.fps).toFixed(1)}s)`,
+  );
+
+  const outDir = resolve(config.outputPath, "..");
+  await mkdir(outDir, { recursive: true });
+
+  config.onLog("Rendering...");
+  await renderer.renderMedia({
+    composition,
+    serveUrl,
+    codec: "h264" as const,
+    outputLocation: config.outputPath,
+    onProgress: ({ progress }: { progress: number }) => {
+      const pct = Math.round(progress * 100);
+      config.onLog(`  Progress: ${pct}%`);
+    },
+  });
+}

package/src/serve/request-path.d.ts

@@ -0,0 +1,23 @@
+/** File served for a directory request ("/" or any path ending in "/"). */
+export declare const INDEX_FILE = "index.html";
+/** Content type for an extension the bundle contract does not recognise. */
+export declare const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+/**
+ * Resolve an incoming request URL path to a clean, bundle-relative file path —
+ * or null if the request is malformed or attempts to escape the bundle root.
+ *
+ * Pure: no filesystem access. The caller maps the returned relative path onto
+ * disk (and 404s if the file is absent). This is the security-critical core of
+ * the local server, so it is isolated and exhaustively unit-tested:
+ *   - percent-decoding (rejecting malformed encodings),
+ *   - directory requests mapped to {@link INDEX_FILE},
+ *   - rejection of "", ".", ".." segments and backslash/NUL injection.
+ *
+ * A defence-in-depth absolute-path containment check still runs in the server
+ * after this resolves, but this function alone must never yield a traversing
+ * path.
+ */
+export declare function resolveStaticPath(urlPath: string): string | null;
+/** Canonical content type for a bundle file path, keyed on its final extension. */
+export declare function contentTypeFor(relativePath: string): string;
+//# sourceMappingURL=request-path.d.ts.map

package/src/serve/request-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-path.d.ts","sourceRoot":"","sources":["../../../src/serve/request-path.ts"],"names":[],"mappings":"AAEA,2EAA2E;AAC3E,eAAO,MAAM,UAAU,eAAe,CAAC;AAEvC,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,6BAA6B,CAAC;AAE/D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAyBhE;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAG3D"}

package/src/serve/request-path.js

@@ -0,0 +1,52 @@
+import { CONTENT_TYPE_BY_EXTENSION, finalExtension } from "../pack/bundle-contract.js";
+/** File served for a directory request ("/" or any path ending in "/"). */
+export const INDEX_FILE = "index.html";
+/** Content type for an extension the bundle contract does not recognise. */
+export const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+/**
+ * Resolve an incoming request URL path to a clean, bundle-relative file path —
+ * or null if the request is malformed or attempts to escape the bundle root.
+ *
+ * Pure: no filesystem access. The caller maps the returned relative path onto
+ * disk (and 404s if the file is absent). This is the security-critical core of
+ * the local server, so it is isolated and exhaustively unit-tested:
+ *   - percent-decoding (rejecting malformed encodings),
+ *   - directory requests mapped to {@link INDEX_FILE},
+ *   - rejection of "", ".", ".." segments and backslash/NUL injection.
+ *
+ * A defence-in-depth absolute-path containment check still runs in the server
+ * after this resolves, but this function alone must never yield a traversing
+ * path.
+ */
+export function resolveStaticPath(urlPath) {
+    // Keep only the path; drop any query string or fragment defensively.
+    const pathOnly = urlPath.split(/[?#]/, 1)[0] ?? "";
+    let decoded;
+    try {
+        decoded = decodeURIComponent(pathOnly);
+    }
+    catch {
+        return null; // malformed percent-encoding
+    }
+    // Requests are absolute-path form; reject separator/NUL injection outright.
+    if (!decoded.startsWith("/"))
+        return null;
+    if (decoded.includes("\0") || decoded.includes("\\"))
+        return null;
+    // A directory request ("/" or trailing slash) serves the index document.
+    const withIndex = decoded === "/" || decoded.endsWith("/") ? decoded + INDEX_FILE : decoded;
+    const segments = withIndex.replace(/^\/+/, "").split("/");
+    for (const segment of segments) {
+        // Empty (double-slash), current-dir, and parent-dir segments are all
+        // rejected: the charset is otherwise permissive and "." is a valid char.
+        if (segment === "" || segment === "." || segment === "..")
+            return null;
+    }
+    return segments.join("/");
+}
+/** Canonical content type for a bundle file path, keyed on its final extension. */
+export function contentTypeFor(relativePath) {
+    const ext = finalExtension(relativePath);
+    return CONTENT_TYPE_BY_EXTENSION[ext] ?? DEFAULT_CONTENT_TYPE;
+}
+//# sourceMappingURL=request-path.js.map

package/src/serve/request-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-path.js","sourceRoot":"","sources":["../../../src/serve/request-path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEvF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CAAC;AAEvC,4EAA4E;AAC5E,MAAM,CAAC,MAAM,oBAAoB,GAAG,0BAA0B,CAAC;AAE/D;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,qEAAqE;IACrE,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAEnD,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,CAAC,6BAA6B;IAC5C,CAAC;IAED,4EAA4E;IAC5E,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAElE,yEAAyE;IACzE,MAAM,SAAS,GAAG,OAAO,KAAK,GAAG,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC;IAE5F,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1D,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,qEAAqE;QACrE,yEAAyE;QACzE,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;IACzE,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,cAAc,CAAC,YAAoB;IACjD,MAAM,GAAG,GAAG,cAAc,CAAC,YAAY,CAA2C,CAAC;IACnF,OAAO,yBAAyB,CAAC,GAAG,CAAC,IAAI,oBAAoB,CAAC;AAChE,CAAC"}

package/src/serve/request-path.ts

@@ -0,0 +1,55 @@
+import { CONTENT_TYPE_BY_EXTENSION, finalExtension } from "../pack/bundle-contract.js";
+
+/** File served for a directory request ("/" or any path ending in "/"). */
+export const INDEX_FILE = "index.html";
+
+/** Content type for an extension the bundle contract does not recognise. */
+export const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+
+/**
+ * Resolve an incoming request URL path to a clean, bundle-relative file path —
+ * or null if the request is malformed or attempts to escape the bundle root.
+ *
+ * Pure: no filesystem access. The caller maps the returned relative path onto
+ * disk (and 404s if the file is absent). This is the security-critical core of
+ * the local server, so it is isolated and exhaustively unit-tested:
+ *   - percent-decoding (rejecting malformed encodings),
+ *   - directory requests mapped to {@link INDEX_FILE},
+ *   - rejection of "", ".", ".." segments and backslash/NUL injection.
+ *
+ * A defence-in-depth absolute-path containment check still runs in the server
+ * after this resolves, but this function alone must never yield a traversing
+ * path.
+ */
+export function resolveStaticPath(urlPath: string): string | null {
+  // Keep only the path; drop any query string or fragment defensively.
+  const pathOnly = urlPath.split(/[?#]/, 1)[0] ?? "";
+
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(pathOnly);
+  } catch {
+    return null; // malformed percent-encoding
+  }
+
+  // Requests are absolute-path form; reject separator/NUL injection outright.
+  if (!decoded.startsWith("/")) return null;
+  if (decoded.includes("\0") || decoded.includes("\\")) return null;
+
+  // A directory request ("/" or trailing slash) serves the index document.
+  const withIndex = decoded === "/" || decoded.endsWith("/") ? decoded + INDEX_FILE : decoded;
+
+  const segments = withIndex.replace(/^\/+/, "").split("/");
+  for (const segment of segments) {
+    // Empty (double-slash), current-dir, and parent-dir segments are all
+    // rejected: the charset is otherwise permissive and "." is a valid char.
+    if (segment === "" || segment === "." || segment === "..") return null;
+  }
+  return segments.join("/");
+}
+
+/** Canonical content type for a bundle file path, keyed on its final extension. */
+export function contentTypeFor(relativePath: string): string {
+  const ext = finalExtension(relativePath) as keyof typeof CONTENT_TYPE_BY_EXTENSION;
+  return CONTENT_TYPE_BY_EXTENSION[ext] ?? DEFAULT_CONTENT_TYPE;
+}

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

@@ -0,0 +1,31 @@
+import type { Viewport } from "../pack/viewport.js";
+import { type BundleServerHandle } from "./static-server.js";
+/** Options for {@link runServe}. */
+export interface RunServeOptions {
+    readonly bundleDir: string;
+    /** Port to bind; 0 lets the OS choose a free one. */
+    readonly port: number;
+    /** Host/interface to bind (default: localhost). */
+    readonly host?: string;
+}
+/** A running preview server plus the derived presentation details. */
+export interface ServeResult {
+    /** The running server (call .close() to stop). */
+    readonly handle: BundleServerHandle;
+    /** The browser-clickable URL (https→http downgraded for *.localhost). */
+    readonly url: string;
+    /** A ready-to-paste responsive <iframe> snippet for this URL. */
+    readonly snippet: string;
+    /** The viewport used for the snippet (recorded, or the default). */
+    readonly viewport: Viewport;
+    /** Whether the snippet's viewport came from the bundle (vs. the default). */
+    readonly recordedViewport: boolean;
+}
+/**
+ * Validate a packed bundle directory and start serving it — the orchestration
+ * behind `scenar serve`, with no process/exit coupling so both the CLI command
+ * and the MCP server can call it. The returned handle keeps running until the
+ * caller closes it. Throws on an invalid bundle or an unavailable port.
+ */
+export declare function runServe(options: RunServeOptions): Promise<ServeResult>;
+//# sourceMappingURL=run-serve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run-serve.d.ts","sourceRoot":"","sources":["../../../src/serve/run-serve.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAKhF,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACpC;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CA2B7E"}

package/src/serve/run-serve.js

@@ -0,0 +1,35 @@
+import { resolve, join } from "node:path";
+import { stat } from "node:fs/promises";
+import { buildEmbedSnippet } from "../deploy/embed-snippet.js";
+import { localViewUrl } from "../deploy/deploy-flow.js";
+import { readBundleViewport } from "../bundle/read-viewport.js";
+import { startBundleServer } from "./static-server.js";
+/** The servable entry every packed bundle contains at its root. */
+const INDEX_FILE = "index.html";
+/**
+ * Validate a packed bundle directory and start serving it — the orchestration
+ * behind `scenar serve`, with no process/exit coupling so both the CLI command
+ * and the MCP server can call it. The returned handle keeps running until the
+ * caller closes it. Throws on an invalid bundle or an unavailable port.
+ */
+export async function runServe(options) {
+    const resolvedDir = resolve(options.bundleDir);
+    const info = await stat(resolvedDir).catch(() => null);
+    if (!info || !info.isDirectory()) {
+        throw new Error(`${options.bundleDir} is not a directory. Pass a bundle produced by \`scenar pack\`.`);
+    }
+    const indexInfo = await stat(join(resolvedDir, INDEX_FILE)).catch(() => null);
+    if (!indexInfo || !indexInfo.isFile()) {
+        throw new Error(`no ${INDEX_FILE} in ${options.bundleDir}. Run \`scenar pack\` to produce a servable bundle first.`);
+    }
+    const handle = await startBundleServer({
+        rootDir: resolvedDir,
+        port: options.port,
+        host: options.host,
+    });
+    const url = localViewUrl(handle.url);
+    const { viewport, recorded } = await readBundleViewport(resolvedDir);
+    const snippet = buildEmbedSnippet({ embedUrl: url, viewport });
+    return { handle, url, snippet, viewport, recordedViewport: recorded };
+}
+//# sourceMappingURL=run-serve.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run-serve.js","sourceRoot":"","sources":["../../../src/serve/run-serve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAEhE,OAAO,EAAE,iBAAiB,EAA2B,MAAM,oBAAoB,CAAC;AAEhF,mEAAmE;AACnE,MAAM,UAAU,GAAG,YAAY,CAAC;AAyBhC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,OAAwB;IACrD,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAE/C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IACvD,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,GAAG,OAAO,CAAC,SAAS,iEAAiE,CACtF,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAC9E,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CACb,MAAM,UAAU,OAAO,OAAO,CAAC,SAAS,2DAA2D,CACpG,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC;QACrC,OAAO,EAAE,WAAW;QACpB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,IAAI,EAAE,OAAO,CAAC,IAAI;KACnB,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACrC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,MAAM,kBAAkB,CAAC,WAAW,CAAC,CAAC;IACrE,MAAM,OAAO,GAAG,iBAAiB,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;IAE/D,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,QAAQ,EAAE,CAAC;AACxE,CAAC"}

package/src/serve/run-serve.ts

@@ -0,0 +1,68 @@
+import { resolve, join } from "node:path";
+import { stat } from "node:fs/promises";
+import { buildEmbedSnippet } from "../deploy/embed-snippet.js";
+import { localViewUrl } from "../deploy/deploy-flow.js";
+import { readBundleViewport } from "../bundle/read-viewport.js";
+import type { Viewport } from "../pack/viewport.js";
+import { startBundleServer, type BundleServerHandle } from "./static-server.js";
+
+/** The servable entry every packed bundle contains at its root. */
+const INDEX_FILE = "index.html";
+
+/** Options for {@link runServe}. */
+export interface RunServeOptions {
+  readonly bundleDir: string;
+  /** Port to bind; 0 lets the OS choose a free one. */
+  readonly port: number;
+  /** Host/interface to bind (default: localhost). */
+  readonly host?: string;
+}
+
+/** A running preview server plus the derived presentation details. */
+export interface ServeResult {
+  /** The running server (call .close() to stop). */
+  readonly handle: BundleServerHandle;
+  /** The browser-clickable URL (https→http downgraded for *.localhost). */
+  readonly url: string;
+  /** A ready-to-paste responsive <iframe> snippet for this URL. */
+  readonly snippet: string;
+  /** The viewport used for the snippet (recorded, or the default). */
+  readonly viewport: Viewport;
+  /** Whether the snippet's viewport came from the bundle (vs. the default). */
+  readonly recordedViewport: boolean;
+}
+
+/**
+ * Validate a packed bundle directory and start serving it — the orchestration
+ * behind `scenar serve`, with no process/exit coupling so both the CLI command
+ * and the MCP server can call it. The returned handle keeps running until the
+ * caller closes it. Throws on an invalid bundle or an unavailable port.
+ */
+export async function runServe(options: RunServeOptions): Promise<ServeResult> {
+  const resolvedDir = resolve(options.bundleDir);
+
+  const info = await stat(resolvedDir).catch(() => null);
+  if (!info || !info.isDirectory()) {
+    throw new Error(
+      `${options.bundleDir} is not a directory. Pass a bundle produced by \`scenar pack\`.`,
+    );
+  }
+  const indexInfo = await stat(join(resolvedDir, INDEX_FILE)).catch(() => null);
+  if (!indexInfo || !indexInfo.isFile()) {
+    throw new Error(
+      `no ${INDEX_FILE} in ${options.bundleDir}. Run \`scenar pack\` to produce a servable bundle first.`,
+    );
+  }
+
+  const handle = await startBundleServer({
+    rootDir: resolvedDir,
+    port: options.port,
+    host: options.host,
+  });
+
+  const url = localViewUrl(handle.url);
+  const { viewport, recorded } = await readBundleViewport(resolvedDir);
+  const snippet = buildEmbedSnippet({ embedUrl: url, viewport });
+
+  return { handle, url, snippet, viewport, recordedViewport: recorded };
+}

package/src/serve/static-server.d.ts

@@ -0,0 +1,38 @@
+import { type Server } from "node:http";
+/** A running bundle server: where it is reachable and how to stop it. */
+export interface BundleServerHandle {
+    /** The base URL the bundle is served at (e.g. http://localhost:4173/). */
+    readonly url: string;
+    /** The port the server actually bound (useful when port 0 was requested). */
+    readonly port: number;
+    /** Stop accepting connections and release the port. */
+    close(): Promise<void>;
+}
+/** Options for {@link startBundleServer}. */
+export interface StartBundleServerOptions {
+    /** Bundle directory to serve (a `scenar pack` output). */
+    readonly rootDir: string;
+    /** Port to bind; 0 lets the OS pick a free one (handy in tests). */
+    readonly port: number;
+    /** Host/interface to bind. Defaults to "localhost". */
+    readonly host?: string;
+}
+/**
+ * Create (but do not start) an HTTP server that serves a packed bundle as a
+ * static site. Only GET/HEAD are allowed; every response carries the bundle
+ * contract's canonical content type and `Cache-Control: no-cache` (a local
+ * preview should always reflect the latest pack, never a stale asset).
+ *
+ * No CSP or other security headers are emitted: that envelope is the serving
+ * edge's responsibility (and is enforced + tested in scenar-cloud). A local
+ * preview deliberately matches the headerless behaviour of a plain static host
+ * such as GitHub Pages — the other Phase 1 target — so what you see locally is
+ * what a `scenar publish` visitor sees.
+ */
+export declare function createBundleServer(rootDir: string): Server;
+/**
+ * Start an HTTP server for a packed bundle and resolve once it is listening.
+ * Rejects if the port is already in use (the caller surfaces a clear message).
+ */
+export declare function startBundleServer(options: StartBundleServerOptions): Promise<BundleServerHandle>;
+//# sourceMappingURL=static-server.d.ts.map

package/src/serve/static-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-server.d.ts","sourceRoot":"","sources":["../../../src/serve/static-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,MAAM,EAAuB,MAAM,WAAW,CAAC;AAMjG,yEAAyE;AACzE,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQ1D;AA4CD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAuBhG"}