@velumo/cli 0.1.0-beta.0

package/src/index.ts

@@ -0,0 +1,1273 @@
+#!/usr/bin/env node
+
+import type { Dirent } from "node:fs";
+import { realpathSync } from "node:fs";
+import { createServer, type ServerResponse } from "node:http";
+import {
+  copyFile,
+  mkdir,
+  readFile,
+  readdir,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import {
+  basename,
+  dirname,
+  extname,
+  isAbsolute,
+  relative,
+  resolve,
+} from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  compileDeck,
+  compileMarkdownDeck,
+  loadConfig,
+  validateDeck,
+} from "@velumo/compiler";
+import type { Manifest } from "@velumo/core";
+import { effectsCss } from "@velumo/effects";
+import { defaultThemeCss } from "@velumo/renderer-dom";
+
+export const cliPackageName = "@velumo/cli";
+
+const cliDistDir = dirname(fileURLToPath(import.meta.url));
+const runtimeDistDir = dirname(
+  fileURLToPath(import.meta.resolve("@velumo/runtime")),
+);
+const rendererDomDistDir = dirname(
+  fileURLToPath(import.meta.resolve("@velumo/renderer-dom")),
+);
+const effectsDistDir = dirname(
+  fileURLToPath(import.meta.resolve("@velumo/effects")),
+);
+
+const browserRuntimeAssets = {
+  "browser-overview.js": () => resolve(cliDistDir, "browser-overview.js"),
+  "browser-presenter.js": () => resolve(cliDistDir, "browser-presenter.js"),
+  "browser-runtime.js": () => resolve(cliDistDir, "browser-runtime.js"),
+  "browser-spatial.js": () => resolve(cliDistDir, "browser-spatial.js"),
+  "browser-sync.js": () => resolve(cliDistDir, "browser-sync.js"),
+  "browser-timer.js": () => resolve(cliDistDir, "browser-timer.js"),
+  "camera.js": () => resolve(runtimeDistDir, "camera.js"),
+  "background-renderer.js": () =>
+    resolve(rendererDomDistDir, "background-renderer.js"),
+  "camera-adapter.js": () => resolve(rendererDomDistDir, "camera-adapter.js"),
+  "dom-renderer.js": () => resolve(rendererDomDistDir, "dom-renderer.js"),
+  "slide-thumbnail.js": () => resolve(rendererDomDistDir, "slide-thumbnail.js"),
+  "spatial-renderer.js": () =>
+    resolve(rendererDomDistDir, "spatial-renderer.js"),
+  "controller.js": () => resolve(runtimeDistDir, "controller.js"),
+  "cue-dispatcher.js": () => resolve(runtimeDistDir, "cue-dispatcher.js"),
+  "action-dispatcher.js": () => resolve(runtimeDistDir, "action-dispatcher.js"),
+  "default-theme.js": () => resolve(rendererDomDistDir, "default-theme.js"),
+  "effects.js": () => fileURLToPath(import.meta.resolve("@velumo/effects")),
+  "effects-css.js": () => resolve(effectsDistDir, "effects-css.js"),
+  "controls.js": () => fileURLToPath(import.meta.resolve("@velumo/controls")),
+  "hash.js": () => resolve(runtimeDistDir, "hash.js"),
+  "html-sanitize.js": () => resolve(rendererDomDistDir, "html-sanitize.js"),
+  "layout-renderer.js": () => resolve(rendererDomDistDir, "layout-renderer.js"),
+  "notes.js": () => resolve(runtimeDistDir, "notes.js"),
+  "registry.js": () => resolve(runtimeDistDir, "registry.js"),
+  "runtime.js": () => fileURLToPath(import.meta.resolve("@velumo/runtime")),
+  "scene-player.js": () => resolve(runtimeDistDir, "scene-player.js"),
+  "spatial.js": () => resolve(runtimeDistDir, "spatial.js"),
+  "theme-bundle.js": () => resolve(runtimeDistDir, "theme-bundle.js"),
+  "renderer-dom.js": () =>
+    fileURLToPath(import.meta.resolve("@velumo/renderer-dom")),
+  "theme-fonts.js": () => resolve(rendererDomDistDir, "theme-fonts.js"),
+  "theme-tokens.js": () => resolve(rendererDomDistDir, "theme-tokens.js"),
+  "timeline.js": () => resolve(runtimeDistDir, "timeline.js"),
+} as const;
+
+type BrowserRuntimeAssetName = keyof typeof browserRuntimeAssets;
+const browserRuntimeAssetNames = Object.keys(
+  browserRuntimeAssets,
+) as BrowserRuntimeAssetName[];
+const defaultThemeCssAssetName = "default-theme.css";
+const effectsCssAssetName = "effects.css";
+
+function usage(): string {
+  return [
+    "Usage:",
+    "  velumo validate <entry>",
+    "  velumo create <name> [--template typescript|markdown] [--force]",
+    "  velumo dev [--config <path>] [--entry <path>] [--port <port>] [--open]",
+    "  velumo build [--config <path>] [--entry <path>] [--outDir <path>]",
+    "  velumo preview [--dir <path>] [--port <port>] [--open]",
+  ].join("\n");
+}
+
+type CreateTemplate = "typescript" | "markdown";
+
+interface CreateOptions {
+  readonly targetPath: string;
+  readonly template: CreateTemplate;
+  readonly force: boolean;
+}
+
+interface DevOptions {
+  readonly configPath?: string;
+  readonly entryPath?: string;
+  readonly port: number;
+  readonly open: boolean;
+}
+
+interface BuildOptions {
+  readonly configPath?: string;
+  readonly entryPath?: string;
+  readonly outDir?: string;
+}
+
+interface BuildProject {
+  readonly entryPath: string;
+  readonly outDir: string;
+  readonly projectRoot: string;
+}
+
+interface PreviewOptions {
+  readonly dir: string;
+  readonly port: number;
+  readonly open: boolean;
+}
+
+function createUsage(): string {
+  return "Usage: velumo create <name> [--template typescript|markdown] [--force]";
+}
+
+function sanitizePackageName(name: string): string {
+  const sanitized = name
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  return sanitized.length === 0 ? "velumo-deck" : sanitized;
+}
+
+function parseCreateArgs(args: readonly string[]): CreateOptions | string {
+  const [name, ...rest] = args;
+
+  if (name === undefined) {
+    return createUsage();
+  }
+
+  let template: CreateTemplate = "typescript";
+  let force = false;
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+
+    if (arg === "--force") {
+      force = true;
+      continue;
+    }
+
+    if (arg === "--template") {
+      const value = rest[index + 1];
+
+      if (value !== "typescript" && value !== "markdown") {
+        return `Invalid template: ${value ?? ""}`;
+      }
+
+      template = value;
+      index += 1;
+      continue;
+    }
+
+    return `Unknown create option: ${arg}`;
+  }
+
+  return {
+    targetPath: isAbsolute(name) ? name : resolve(process.cwd(), name),
+    template,
+    force,
+  };
+}
+
+async function directoryHasEntries(path: string): Promise<boolean> {
+  try {
+    return (await readdir(path)).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function resolveCliPath(path: string): string {
+  return isAbsolute(path) ? path : resolve(process.cwd(), path);
+}
+
+function deckEntryForTemplate(template: CreateTemplate): string {
+  return template === "markdown" ? "src/deck.md" : "src/deck.ts";
+}
+
+function packageJsonFor(targetPath: string): string {
+  return `${JSON.stringify(
+    {
+      name: sanitizePackageName(basename(targetPath)),
+      type: "module",
+      scripts: {
+        dev: "velumo dev",
+        build: "velumo build",
+        preview: "velumo preview",
+      },
+      dependencies: {
+        "@velumo/core": "0.0.0",
+      },
+      devDependencies: {
+        "@velumo/cli": "0.0.0",
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function defaultDevPort(): number {
+  const devDefaults = parseDevArgs([]);
+  return typeof devDefaults === "string" ? 5173 : devDefaults.port;
+}
+
+function readmeFor(targetPath: string, template: CreateTemplate): string {
+  const name = sanitizePackageName(basename(targetPath));
+  const entry = deckEntryForTemplate(template);
+  const devPort = defaultDevPort();
+
+  return `# ${name}
+
+A Velumo presentation.
+
+## Getting started
+
+\`\`\`bash
+npm install
+\`\`\`
+
+> Requires \`@velumo/core\` and \`@velumo/cli\` to be resolvable —
+> either run this from inside the velumo monorepo workspace, or once
+> those packages are published to a registry.
+
+Edit your deck in \`${entry}\`.
+
+## Scripts
+
+- \`npm run dev\` — start the local dev server at http://localhost:${devPort}
+  (opening a browser is manual — the dev server does not auto-open one)
+- \`npm run build\` — build a static output to \`dist/\`
+- \`npm run preview\` — serve the \`dist/\` build locally
+`;
+}
+
+function configFor(template: CreateTemplate): string {
+  return `import { defineConfig } from "@velumo/core";
+
+export default defineConfig({
+  entry: "${deckEntryForTemplate(template)}",
+});
+`;
+}
+
+function typescriptDeckTemplate(): string {
+  return `import { deck, markdown, slide } from "@velumo/core";
+
+export default deck({
+  title: "Velumo Demo",
+  slides: [
+    slide("intro", {
+      layers: [markdown("# Velumo Demo\\n\\nStart forging your story.")],
+    }),
+  ],
+});
+`;
+}
+
+function markdownDeckTemplate(): string {
+  return `---
+title: Velumo Demo
+---
+
+# Velumo Demo
+
+Start forging your story.
+`;
+}
+
+async function writeGeneratedFiles(options: CreateOptions): Promise<void> {
+  await mkdir(resolve(options.targetPath, "src"), { recursive: true });
+  await mkdir(resolve(options.targetPath, "public", "assets"), {
+    recursive: true,
+  });
+
+  await writeFile(
+    resolve(options.targetPath, "package.json"),
+    packageJsonFor(options.targetPath),
+  );
+  await writeFile(
+    resolve(options.targetPath, "velumo.config.ts"),
+    configFor(options.template),
+  );
+  await writeFile(
+    resolve(options.targetPath, "README.md"),
+    readmeFor(options.targetPath, options.template),
+  );
+  await writeFile(
+    resolve(options.targetPath, "public", "assets", ".gitkeep"),
+    "",
+  );
+
+  if (options.template === "markdown") {
+    await writeFile(
+      resolve(options.targetPath, "src", "deck.md"),
+      markdownDeckTemplate(),
+    );
+    return;
+  }
+
+  await writeFile(
+    resolve(options.targetPath, "src", "deck.ts"),
+    typescriptDeckTemplate(),
+  );
+}
+
+async function runCreate(args: readonly string[]): Promise<number> {
+  const options = parseCreateArgs(args);
+
+  if (typeof options === "string") {
+    console.error(options);
+    return 1;
+  }
+
+  if (!options.force && (await directoryHasEntries(options.targetPath))) {
+    console.error(`Target directory already exists: ${options.targetPath}`);
+    return 1;
+  }
+
+  await writeGeneratedFiles(options);
+  console.log(`Created Velumo project at ${options.targetPath}`);
+  return 0;
+}
+
+function parseDevArgs(args: readonly string[]): DevOptions | string {
+  let configPath: string | undefined;
+  let entryPath: string | undefined;
+  let port = 5173;
+  let open = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--config") {
+      const value = args[index + 1];
+
+      if (value === undefined) {
+        return "Missing value for --config";
+      }
+
+      configPath = resolveCliPath(value);
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--entry") {
+      const value = args[index + 1];
+
+      if (value === undefined) {
+        return "Missing value for --entry";
+      }
+
+      entryPath = resolveCliPath(value);
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--port") {
+      const value = args[index + 1];
+      const parsedPort = Number(value);
+
+      if (
+        !Number.isInteger(parsedPort) ||
+        parsedPort < 1 ||
+        parsedPort > 65535
+      ) {
+        return `Invalid port: ${value ?? ""}`;
+      }
+
+      port = parsedPort;
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--open") {
+      open = true;
+      continue;
+    }
+
+    return `Unknown dev option: ${arg}`;
+  }
+
+  return {
+    configPath,
+    entryPath,
+    port,
+    open,
+  };
+}
+
+function parseBuildArgs(args: readonly string[]): BuildOptions | string {
+  let configPath: string | undefined;
+  let entryPath: string | undefined;
+  let outDir: string | undefined;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--config") {
+      const value = args[index + 1];
+
+      if (value === undefined) {
+        return "Missing value for --config";
+      }
+
+      configPath = resolveCliPath(value);
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--entry") {
+      const value = args[index + 1];
+
+      if (value === undefined) {
+        return "Missing value for --entry";
+      }
+
+      entryPath = resolveCliPath(value);
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--outDir") {
+      const value = args[index + 1];
+
+      if (value === undefined) {
+        return "Missing value for --outDir";
+      }
+
+      outDir = resolveCliPath(value);
+      index += 1;
+      continue;
+    }
+
+    return `Unknown build option: ${arg}`;
+  }
+
+  return { configPath, entryPath, outDir };
+}
+
+function parsePreviewArgs(args: readonly string[]): PreviewOptions | string {
+  let dir = resolve(process.cwd(), "dist");
+  let port = 4173;
+  let open = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--dir") {
+      const value = args[index + 1];
+
+      if (value === undefined) {
+        return "Missing value for --dir";
+      }
+
+      dir = resolveCliPath(value);
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--port") {
+      const value = args[index + 1];
+      const parsedPort = Number(value);
+
+      if (
+        !Number.isInteger(parsedPort) ||
+        parsedPort < 1 ||
+        parsedPort > 65535
+      ) {
+        return `Invalid port: ${value ?? ""}`;
+      }
+
+      port = parsedPort;
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--open") {
+      open = true;
+      continue;
+    }
+
+    return `Unknown preview option: ${arg}`;
+  }
+
+  return { dir, port, open };
+}
+
+async function resolveDevProject(options: DevOptions): Promise<{
+  readonly entryPath: string;
+  readonly projectRoot: string;
+}> {
+  if (options.entryPath !== undefined) {
+    return {
+      entryPath: options.entryPath,
+      projectRoot:
+        options.configPath === undefined
+          ? process.cwd()
+          : dirname(options.configPath),
+    };
+  }
+
+  const configPath =
+    options.configPath ?? resolve(process.cwd(), "velumo.config.ts");
+  const loadedConfig = await loadConfig(configPath);
+
+  if (loadedConfig.entryPath === undefined) {
+    throw new Error(`config entry is missing: ${configPath}`);
+  }
+
+  return {
+    entryPath: loadedConfig.entryPath,
+    projectRoot: loadedConfig.projectRoot,
+  };
+}
+
+async function resolveBuildProject(
+  options: BuildOptions,
+): Promise<BuildProject> {
+  if (
+    options.entryPath !== undefined &&
+    options.outDir !== undefined &&
+    options.configPath === undefined
+  ) {
+    return {
+      entryPath: options.entryPath,
+      outDir: options.outDir,
+      projectRoot: process.cwd(),
+    };
+  }
+
+  const configPath =
+    options.configPath ?? resolve(process.cwd(), "velumo.config.ts");
+  const loadedConfig = await loadConfig(configPath);
+  const entryPath =
+    options.entryPath === undefined
+      ? loadedConfig.entryPath
+      : options.entryPath;
+
+  if (entryPath === undefined) {
+    throw new Error(`config entry is missing: ${configPath}`);
+  }
+
+  return {
+    entryPath,
+    outDir:
+      options.outDir ??
+      loadedConfig.outDir ??
+      resolve(loadedConfig.projectRoot, "dist"),
+    projectRoot: loadedConfig.projectRoot,
+  };
+}
+
+async function compileDevManifest(entryPath: string): Promise<Manifest> {
+  const extension = extname(entryPath);
+
+  if (extension === ".ts" || extension === ".tsx") {
+    return compileDeck(entryPath);
+  }
+
+  if (extension === ".md" || extension === ".markdown") {
+    return compileMarkdownDeck(entryPath);
+  }
+
+  throw new Error(`unsupported dev entry extension: ${extension}`);
+}
+
+function send(
+  response: ServerResponse,
+  statusCode: number,
+  body: string | Buffer,
+  contentType: string,
+): void {
+  response.writeHead(statusCode, { "content-type": contentType });
+  response.end(body);
+}
+
+function contentTypeFor(path: string): string {
+  switch (extname(path).toLowerCase()) {
+    case ".css":
+      return "text/css; charset=utf-8";
+    case ".gif":
+      return "image/gif";
+    case ".html":
+      return "text/html; charset=utf-8";
+    case ".jpg":
+    case ".jpeg":
+      return "image/jpeg";
+    case ".js":
+      return "text/javascript; charset=utf-8";
+    case ".json":
+      return "application/json; charset=utf-8";
+    case ".mp3":
+      return "audio/mpeg";
+    case ".mp4":
+      return "video/mp4";
+    case ".png":
+      return "image/png";
+    case ".svg":
+      return "image/svg+xml";
+    case ".txt":
+      return "text/plain; charset=utf-8";
+    case ".webp":
+      return "image/webp";
+    default:
+      return "application/octet-stream";
+  }
+}
+
+async function readProjectIndexHtml(
+  projectRoot: string,
+): Promise<string | undefined> {
+  const path = resolve(projectRoot, "index.html");
+
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (
+      error !== null &&
+      typeof error === "object" &&
+      "code" in error &&
+      (error as { code: unknown }).code === "ENOENT"
+    ) {
+      return undefined;
+    }
+
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(
+      `Failed to read project index.html at ${path}: ${message}; falling back to generated shell`,
+    );
+    return undefined;
+  }
+}
+
+function indexHtml(
+  manifestPath = "/velumo/manifest.json",
+  browserAssetBase = "/velumo/",
+): string {
+  const browserRuntimePath = `${browserAssetBase}browser-runtime.js`;
+  const runtimePath = `${browserAssetBase}runtime.js`;
+  const rendererDomPath = `${browserAssetBase}renderer-dom.js`;
+  const defaultThemeCssPath = `${browserAssetBase}${defaultThemeCssAssetName}`;
+  const effectsCssPath = `${browserAssetBase}${effectsCssAssetName}`;
+
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title>Velumo Dev</title>
+    <style>
+      html, body { margin: 0; height: 100%; overflow: hidden; background: #000; }
+      body { display: flex; align-items: center; justify-content: center; }
+      #velumo-root { width: min(100vw, calc(100vh * 16 / 9)); aspect-ratio: 16 / 9; }
+    </style>
+    <link rel="stylesheet" href="${defaultThemeCssPath}">
+    <link rel="stylesheet" href="${effectsCssPath}">
+  </head>
+  <body>
+    <main id="velumo-root"></main>
+    <script type="importmap">
+      {
+        "imports": {
+          "@velumo/runtime": ${JSON.stringify(runtimePath)},
+          "@velumo/renderer-dom": ${JSON.stringify(rendererDomPath)}
+        }
+      }
+    </script>
+    <script type="module">
+      import { mountVelumoBrowserRuntime } from ${JSON.stringify(browserRuntimePath)};
+
+      await mountVelumoBrowserRuntime({
+        root: document.querySelector("#velumo-root"),
+        manifestUrl: ${JSON.stringify(manifestPath)},
+      });
+    </script>
+  </body>
+</html>
+`;
+}
+
+function presenterHtml(
+  manifestPath = "/velumo/manifest.json",
+  browserAssetBase = "/velumo/",
+): string {
+  const browserPresenterPath = `${browserAssetBase}browser-presenter.js`;
+  const runtimePath = `${browserAssetBase}runtime.js`;
+  const rendererDomPath = `${browserAssetBase}renderer-dom.js`;
+  const defaultThemeCssPath = `${browserAssetBase}${defaultThemeCssAssetName}`;
+
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title>Velumo Presenter View</title>
+    <!-- The slide previews are real DOM renderers; load the default theme so its
+         (renderer-scoped) typography + layout rules — including the var() that
+         resolves to the active theme's fonts — apply to the previews. The active
+         theme's own css + @font-face ride the renderer injection. -->
+    <link rel="stylesheet" href="${defaultThemeCssPath}">
+    <style>
+      :root {
+        color-scheme: dark;
+        font-family: ui-serif, Georgia, "Times New Roman", serif;
+      }
+
+      body {
+        margin: 0;
+        min-height: 100vh;
+        background:
+          radial-gradient(circle at 20% 10%, rgba(251, 191, 36, 0.18), transparent 30rem),
+          linear-gradient(135deg, #0f172a 0%, #111827 58%, #1f2937 100%);
+        color: #f8fafc;
+      }
+
+      #velumo-presenter-root {
+        min-height: 100vh;
+        padding: 1.5rem;
+        box-sizing: border-box;
+      }
+
+      [data-velumo-presenter="mounted"] {
+        display: grid;
+        gap: 1rem;
+      }
+
+      [data-velumo-presenter-slides] {
+        display: grid;
+        grid-template-columns: minmax(0, 1.5fr) minmax(18rem, 0.8fr);
+        gap: 1rem;
+      }
+
+      [data-velumo-presenter-current],
+      [data-velumo-presenter-next],
+      [data-velumo-presenter-notes],
+      [data-velumo-presenter-controls],
+      [data-velumo-presenter-header] {
+        border: 1px solid rgba(248, 250, 252, 0.18);
+        border-radius: 1rem;
+        padding: 1rem;
+        background: rgba(15, 23, 42, 0.72);
+      }
+
+      [data-velumo-presenter-controls] {
+        display: flex;
+        gap: 0.75rem;
+      }
+
+      button {
+        border: 1px solid rgba(251, 191, 36, 0.6);
+        border-radius: 999px;
+        padding: 0.6rem 1rem;
+        background: #fbbf24;
+        color: #111827;
+        font-weight: 700;
+      }
+
+      [data-velumo-fragment="hidden"] {
+        display: none;
+      }
+
+      [data-velumo-presenter-preview] {
+        aspect-ratio: 16 / 9;
+        width: 100%;
+        overflow: hidden;
+      }
+    </style>
+  </head>
+  <body>
+    <main id="velumo-presenter-root"></main>
+    <script type="importmap">
+      {
+        "imports": {
+          "@velumo/runtime": ${JSON.stringify(runtimePath)},
+          "@velumo/renderer-dom": ${JSON.stringify(rendererDomPath)}
+        }
+      }
+    </script>
+    <script type="module">
+      import { mountVelumoPresenterView } from ${JSON.stringify(browserPresenterPath)};
+      import { mountSlideThumbnail } from "@velumo/renderer-dom";
+
+      await mountVelumoPresenterView({
+        root: document.querySelector("#velumo-presenter-root"),
+        manifestUrl: ${JSON.stringify(manifestPath)},
+        mountThumbnail: mountSlideThumbnail,
+      });
+    </script>
+  </body>
+</html>
+`;
+}
+
+function isPathInside(parentPath: string, candidatePath: string): boolean {
+  const relativePath = relative(parentPath, candidatePath);
+
+  return (
+    relativePath === "" ||
+    (!relativePath.startsWith("..") && !isAbsolute(relativePath))
+  );
+}
+
+async function servePublicAsset(
+  projectRoot: string,
+  pathname: string,
+  response: ServerResponse,
+): Promise<boolean> {
+  const publicRoot = resolve(projectRoot, "public");
+  const assetPath = resolve(publicRoot, `.${pathname}`);
+
+  if (!isPathInside(publicRoot, assetPath)) {
+    send(response, 403, "Forbidden", "text/plain; charset=utf-8");
+    return true;
+  }
+
+  try {
+    const assetStat = await stat(assetPath);
+
+    if (!assetStat.isFile()) {
+      return false;
+    }
+
+    send(response, 200, await readFile(assetPath), contentTypeFor(assetPath));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function copyPublicFiles(
+  sourceDir: string,
+  targetDir: string,
+): Promise<void> {
+  let entries: Dirent[];
+  try {
+    entries = await readdir(sourceDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  await mkdir(targetDir, { recursive: true });
+
+  for (const entry of entries) {
+    const sourcePath = resolve(sourceDir, entry.name);
+    const targetPath = resolve(targetDir, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyPublicFiles(sourcePath, targetPath);
+      continue;
+    }
+
+    if (entry.isFile()) {
+      await mkdir(dirname(targetPath), { recursive: true });
+      await copyFile(sourcePath, targetPath);
+    }
+  }
+}
+
+async function readBrowserRuntimeAsset(
+  assetName: BrowserRuntimeAssetName,
+): Promise<Buffer> {
+  return readFile(browserRuntimeAssets[assetName]());
+}
+
+async function copyBrowserRuntimeAssets(outDir: string): Promise<void> {
+  const targetDir = resolve(outDir, "velumo");
+  await mkdir(targetDir, { recursive: true });
+
+  await Promise.all(
+    browserRuntimeAssetNames.map(async (assetName) => {
+      await writeFile(
+        resolve(targetDir, assetName),
+        await readBrowserRuntimeAsset(assetName),
+      );
+    }),
+  );
+}
+
+async function writeDefaultThemeCssAsset(outDir: string): Promise<void> {
+  const targetDir = resolve(outDir, "velumo");
+  await mkdir(targetDir, { recursive: true });
+  await writeFile(
+    resolve(targetDir, defaultThemeCssAssetName),
+    defaultThemeCss,
+  );
+  await writeFile(resolve(targetDir, effectsCssAssetName), effectsCss);
+}
+
+function browserRuntimeAssetNameForPath(
+  pathname: string,
+): BrowserRuntimeAssetName | undefined {
+  const prefix = "/velumo/";
+
+  if (!pathname.startsWith(prefix)) {
+    return undefined;
+  }
+
+  const assetName = pathname.slice(prefix.length) as BrowserRuntimeAssetName;
+  return browserRuntimeAssetNames.includes(assetName) ? assetName : undefined;
+}
+
+async function serveBrowserRuntimeAsset(
+  pathname: string,
+  response: ServerResponse,
+): Promise<boolean> {
+  const assetName = browserRuntimeAssetNameForPath(pathname);
+
+  if (assetName === undefined) {
+    return false;
+  }
+
+  send(
+    response,
+    200,
+    await readBrowserRuntimeAsset(assetName),
+    contentTypeFor(assetName),
+  );
+  return true;
+}
+
+function serveDefaultThemeCssAsset(
+  pathname: string,
+  response: ServerResponse,
+): boolean {
+  if (pathname !== `/velumo/${defaultThemeCssAssetName}`) {
+    return false;
+  }
+
+  send(
+    response,
+    200,
+    defaultThemeCss,
+    contentTypeFor(defaultThemeCssAssetName),
+  );
+  return true;
+}
+
+function serveEffectsCssAsset(
+  pathname: string,
+  response: ServerResponse,
+): boolean {
+  if (pathname !== `/velumo/${effectsCssAssetName}`) {
+    return false;
+  }
+
+  send(response, 200, effectsCss, contentTypeFor(effectsCssAssetName));
+  return true;
+}
+
+async function runBuild(args: readonly string[]): Promise<number> {
+  const options = parseBuildArgs(args);
+
+  if (typeof options === "string") {
+    console.error(options);
+    return 1;
+  }
+
+  let project: BuildProject;
+
+  try {
+    project = await resolveBuildProject(options);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : "config error");
+    return 1;
+  }
+
+  const validation = await validateDeck(project.entryPath);
+
+  for (const warning of validation.warnings) {
+    console.log(`WARN: ${warning}`);
+  }
+
+  if (!validation.valid) {
+    for (const error of validation.errors) {
+      console.error(`ERROR: ${error}`);
+    }
+
+    return 1;
+  }
+
+  let manifest: Manifest;
+
+  try {
+    manifest = await compileDevManifest(project.entryPath);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : "build failed");
+    return 1;
+  }
+
+  await mkdir(project.outDir, { recursive: true });
+  await copyPublicFiles(resolve(project.projectRoot, "public"), project.outDir);
+  await copyBrowserRuntimeAssets(project.outDir);
+  await writeDefaultThemeCssAsset(project.outDir);
+  await writeFile(
+    resolve(project.outDir, "manifest.json"),
+    JSON.stringify(manifest, null, 2),
+  );
+  const projectShell = await readProjectIndexHtml(project.projectRoot);
+  await writeFile(
+    resolve(project.outDir, "index.html"),
+    projectShell ?? indexHtml("manifest.json", "./velumo/"),
+  );
+  await writeFile(
+    resolve(project.outDir, "velumo", "presenter.html"),
+    presenterHtml("../manifest.json", "./"),
+  );
+  console.log(`Built Velumo output at ${project.outDir}`);
+  return 0;
+}
+
+async function serveStaticFile(
+  rootDir: string,
+  pathname: string,
+  response: ServerResponse,
+): Promise<void> {
+  const requestedPath = pathname === "/" ? "/index.html" : pathname;
+  const filePath = resolve(rootDir, `.${requestedPath}`);
+
+  if (!isPathInside(rootDir, filePath)) {
+    send(response, 403, "Forbidden", "text/plain; charset=utf-8");
+    return;
+  }
+
+  try {
+    const fileStat = await stat(filePath);
+
+    if (!fileStat.isFile()) {
+      send(response, 404, "Not found", "text/plain; charset=utf-8");
+      return;
+    }
+
+    send(response, 200, await readFile(filePath), contentTypeFor(filePath));
+  } catch {
+    send(response, 404, "Not found", "text/plain; charset=utf-8");
+  }
+}
+
+async function runPreview(args: readonly string[]): Promise<number> {
+  const options = parsePreviewArgs(args);
+
+  if (typeof options === "string") {
+    console.error(options);
+    return 1;
+  }
+
+  if (options.open) {
+    console.log(
+      "Open requested; browser launch is not implemented in this Ward.",
+    );
+  }
+
+  const server = createServer(async (request, response) => {
+    const url = new URL(request.url ?? "/", `http://${request.headers.host}`);
+    await serveStaticFile(options.dir, url.pathname, response);
+  });
+
+  return new Promise((resolveExitCode) => {
+    server.once("error", (error) => {
+      console.error(error.message);
+      resolveExitCode(1);
+    });
+
+    server.listen(options.port, "localhost", () => {
+      console.log(
+        `Velumo preview server running at http://localhost:${options.port}`,
+      );
+    });
+  });
+}
+
+async function runDev(args: readonly string[]): Promise<number> {
+  const options = parseDevArgs(args);
+
+  if (typeof options === "string") {
+    console.error(options);
+    return 1;
+  }
+
+  let project: Awaited<ReturnType<typeof resolveDevProject>>;
+
+  try {
+    project = await resolveDevProject(options);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : "config error");
+    return 1;
+  }
+
+  if (options.open) {
+    console.log(
+      "Open requested; browser launch is not implemented in this Ward.",
+    );
+  }
+
+  const server = createServer(async (request, response) => {
+    const url = new URL(request.url ?? "/", `http://${request.headers.host}`);
+
+    if (url.pathname === "/") {
+      const projectShell = await readProjectIndexHtml(project.projectRoot);
+      const shell = projectShell ?? indexHtml();
+      send(response, 200, shell, "text/html; charset=utf-8");
+      return;
+    }
+
+    if (url.pathname === "/velumo/presenter.html") {
+      send(response, 200, presenterHtml(), "text/html; charset=utf-8");
+      return;
+    }
+
+    if (await serveBrowserRuntimeAsset(url.pathname, response)) {
+      return;
+    }
+
+    if (serveDefaultThemeCssAsset(url.pathname, response)) {
+      return;
+    }
+
+    if (serveEffectsCssAsset(url.pathname, response)) {
+      return;
+    }
+
+    if (url.pathname === "/velumo/manifest.json") {
+      try {
+        send(
+          response,
+          200,
+          JSON.stringify(await compileDevManifest(project.entryPath)),
+          "application/json; charset=utf-8",
+        );
+      } catch (error) {
+        send(
+          response,
+          500,
+          error instanceof Error ? error.message : "invalid manifest",
+          "text/plain; charset=utf-8",
+        );
+      }
+
+      return;
+    }
+
+    if (await servePublicAsset(project.projectRoot, url.pathname, response)) {
+      return;
+    }
+
+    if (url.pathname === "/manifest.json") {
+      try {
+        send(
+          response,
+          200,
+          JSON.stringify(await compileDevManifest(project.entryPath)),
+          "application/json; charset=utf-8",
+        );
+      } catch (error) {
+        send(
+          response,
+          500,
+          error instanceof Error ? error.message : "invalid manifest",
+          "text/plain; charset=utf-8",
+        );
+      }
+
+      return;
+    }
+
+    send(response, 404, "Not found", "text/plain; charset=utf-8");
+  });
+
+  return new Promise((resolveExitCode) => {
+    server.once("error", (error) => {
+      console.error(error.message);
+      resolveExitCode(1);
+    });
+
+    server.listen(options.port, "localhost", () => {
+      console.log(
+        `Velumo dev server running at http://localhost:${options.port}`,
+      );
+    });
+  });
+}
+
+async function runValidate(entryPath: string | undefined): Promise<number> {
+  if (entryPath === undefined) {
+    console.error(usage());
+    return 1;
+  }
+
+  const result = await validateDeck(entryPath);
+
+  for (const warning of result.warnings) {
+    console.log(`WARN: ${warning}`);
+  }
+
+  if (!result.valid) {
+    for (const error of result.errors) {
+      console.error(`ERROR: ${error}`);
+    }
+
+    return 1;
+  }
+
+  console.log(`Valid deck: ${entryPath}`);
+  return 0;
+}
+
+export async function main(args = process.argv.slice(2)): Promise<number> {
+  const [command, ...rest] = args;
+
+  if (command === "validate") {
+    return runValidate(rest[0]);
+  }
+
+  if (command === "create") {
+    return runCreate(rest);
+  }
+
+  if (command === "dev") {
+    return runDev(rest);
+  }
+
+  if (command === "build") {
+    return runBuild(rest);
+  }
+
+  if (command === "preview") {
+    return runPreview(rest);
+  }
+
+  console.error(usage());
+  return 1;
+}
+
+function isDirectInvocation(
+  moduleUrl: string,
+  argvScript: string | undefined,
+): boolean {
+  if (argvScript === undefined) {
+    return false;
+  }
+  try {
+    return moduleUrl === pathToFileURL(realpathSync(argvScript)).href;
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(import.meta.url, process.argv[1])) {
+  process.exitCode = await main();
+}