@scenar/cli 0.1.20 → 0.2.0

package/src/publish/run-publish.ts

@@ -0,0 +1,131 @@
+import { resolve, join, basename } from "node:path";
+import { stat, readFile } from "node:fs/promises";
+import { PACK_MANIFEST_FILE } from "../pack/pack-manifest.js";
+import { buildEmbedSnippet } from "../deploy/embed-snippet.js";
+import { readBundleViewport } from "../bundle/read-viewport.js";
+import type { Viewport } from "../pack/viewport.js";
+import { createGithubPublisher } from "./github.js";
+import {
+  runPublishFlow,
+  validateRepoName,
+  validatePublishPath,
+  normalizePath,
+  type PublishFlowDeps,
+  type PublishResult,
+} from "./publish-flow.js";
+
+/** The servable entry every packed bundle contains at its root. */
+const INDEX_FILE = "index.html";
+
+/** Repo-name rule for the default (same shape as scenario slugs). */
+const REPO_FALLBACK_PATTERN = /^[a-z][a-z0-9-]*[a-z0-9]$/;
+
+/**
+ * Default shared repo for embeds. Many tours live here, each under its own slug
+ * path, so previews never land in the user's source repo. Override with --repo.
+ */
+const DEFAULT_REPO = "scenar-embeds";
+
+/** Options for {@link runPublish}. */
+export interface RunPublishOptions {
+  readonly bundleDir: string;
+  /** Target repository name (default: {@link DEFAULT_REPO}). */
+  readonly repo?: string;
+  /**
+   * Subdirectory within the repo (default: the packed scenario slug). Pass "/"
+   * or "" to publish at the repo root (a dedicated single-tour repo).
+   */
+  readonly path?: string;
+  /** Target GitHub org (default: the authenticated user). */
+  readonly org?: string;
+  /** Create the repo private (GitHub Pages needs Pro for private repos). */
+  readonly private?: boolean;
+  /** Commit message for the published snapshot. */
+  readonly message?: string;
+  /** Progress sink for flow messages. */
+  readonly onLog?: (message: string) => void;
+  /**
+   * Override the publish backend (the gh/git deps). Defaults to the real
+   * {@link createGithubPublisher}; tests inject a fake to avoid live calls.
+   */
+  readonly deps?: Omit<PublishFlowDeps, "log">;
+}
+
+/** The published location plus the derived embed snippet. */
+export interface PublishRunResult {
+  readonly result: PublishResult;
+  readonly viewport: Viewport;
+  readonly recordedViewport: boolean;
+  readonly snippet: string;
+}
+
+/**
+ * Validate a packed bundle and publish it to GitHub Pages — the orchestration
+ * behind `scenar publish`, with no process/exit coupling. Resolves the default
+ * repo name, runs the publish flow, and builds the embed snippet. Throws on an
+ * invalid bundle, an invalid repo name, or any flow failure.
+ */
+export async function runPublish(options: RunPublishOptions): Promise<PublishRunResult> {
+  const onLog = options.onLog ?? (() => {});
+  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 slug = await scenarioSlug(resolvedDir);
+
+  const repo = options.repo ?? DEFAULT_REPO;
+  const repoError = validateRepoName(repo);
+  if (repoError) {
+    throw new Error(`${repoError}. Pass --repo <name> to override.`);
+  }
+
+  // Path defaults to the scenario slug so tours coexist in one repo; an explicit
+  // "/" (or "") publishes at the repo root.
+  const path = normalizePath(options.path ?? slug);
+  const pathError = validatePublishPath(path);
+  if (pathError) {
+    throw new Error(`${pathError}. Pass --path <subpath> to override.`);
+  }
+
+  const deps: PublishFlowDeps = { ...(options.deps ?? createGithubPublisher()), log: onLog };
+  const result = await runPublishFlow(deps, {
+    bundleDir: resolvedDir,
+    repo,
+    path,
+    org: options.org,
+    private: Boolean(options.private),
+    message: options.message ?? "Publish Scenar embed",
+  });
+
+  const { viewport, recorded } = await readBundleViewport(resolvedDir);
+  const snippet = buildEmbedSnippet({ embedUrl: result.pagesUrl, viewport });
+
+  return { result, viewport, recordedViewport: recorded, snippet };
+}
+
+/**
+ * The packed scenario slug (from pack-manifest.json), falling back to the bundle
+ * directory's base name. Used as the default publish subpath. The downstream
+ * validatePublishPath guards the result.
+ */
+async function scenarioSlug(bundleDir: string): Promise<string> {
+  try {
+    const raw = await readFile(join(bundleDir, PACK_MANIFEST_FILE), "utf-8");
+    const id = (JSON.parse(raw) as { scenarioId?: unknown }).scenarioId;
+    if (typeof id === "string" && REPO_FALLBACK_PATTERN.test(id)) return id;
+  } catch {
+    // No/invalid manifest — fall back to the directory name.
+  }
+  return basename(bundleDir);
+}

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

@@ -0,0 +1,31 @@
+/** 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 declare function runRender(options: RunRenderOptions): Promise<RenderResult>;
+//# sourceMappingURL=run-render.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run-render.d.ts","sourceRoot":"","sources":["../../../src/render/run-render.ts"],"names":[],"mappings":"AAQA,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AAED,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAkFhF"}

package/src/render/run-render.js

@@ -0,0 +1,196 @@
+import { resolve, join } from "node:path";
+import { stat, mkdir, access, writeFile, rm } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { loadBundle } from "../util/load-bundle.js";
+import { generateRemotionEntry } from "./generate-entry.js";
+import { resolveProvidersPath } from "./resolve-providers.js";
+import { detectRenderExport } from "./detect-render-export.js";
+/**
+ * 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) {
+    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;
+    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, scenarioId) {
+    if (!outOption) {
+        return resolve(`./${scenarioId}.mp4`);
+    }
+    if (outOption.endsWith(".mp4")) {
+        return resolve(outOption);
+    }
+    return resolve(join(outOption, `${scenarioId}.mp4`));
+}
+async function resolveEntryPoint(input) {
+    // 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) {
+    const resolved = resolve(overridePath);
+    try {
+        await access(resolved);
+    }
+    catch {
+        throw new Error(`Webpack override file not found: ${overridePath}`);
+    }
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(resolved).href));
+    }
+    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);
+    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;
+}
+async function renderScenario(config) {
+    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 = { entryPoint: config.entryPoint };
+    if (config.webpackOverride) {
+        bundleOptions.webpackOverride = config.webpackOverride;
+    }
+    const serveUrl = await bundler.bundle(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",
+        outputLocation: config.outputPath,
+        onProgress: ({ progress }) => {
+            const pct = Math.round(progress * 100);
+            config.onLog(`  Progress: ${pct}%`);
+        },
+    });
+}
+//# sourceMappingURL=run-render.js.map

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

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

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