@textjs/app 0.0.0-stage → 1.0.3

package/src/server/live-app.tsx

@@ -0,0 +1,374 @@
+/**
+ * The React half of server-rendered console routes: mounts the App Router in a
+ * headless console root on the server (Bun / Node), applies forwarded input
+ * and exposes the painted `CellBuffer` for the live transport and for Partial
+ * Prerendering. Loaded through Vite's SSR graph in `text dev` and bundled into
+ * `.text/server/live.mjs` by `text build`, so route modules, `@textjs/react`
+ * and this module share one React instance.
+ */
+
+import { useContext, useEffect, type ReactNode } from "react";
+import {
+  CssConsoleDriver,
+  initYoga,
+  InputEngine,
+  type CellBuffer,
+  type ConsoleTarget,
+  type RendererScheduler,
+} from "@textjs/core";
+import { createConsoleRootSync, type ConsoleRoot, type ThemeName } from "@textjs/react";
+import { RouterContext } from "../context";
+import { createMemoryHistory, parseHref, type HistoryAction, type MemoryHistory } from "../history";
+import type { LiveInput } from "../live-protocol";
+import { AppRouter } from "../router";
+import { resolveRoute, type RouteManifest, type RouteModule, type RouteModuleRef, type RouteSegmentNode } from "../routing";
+import { isAsyncComponent, serverComponent, ServerComponentCache, ServerComponentsProvider } from "./server-components";
+
+/** `export const runtime = "server"` in `page.tsx`. */
+export type RouteRuntime = "server" | "client";
+
+export interface LiveAppOptions {
+  /** Eager route manifest (every page imported). */
+  routes: RouteManifest;
+  /** Initial href (`pathname + search`). */
+  path: string;
+  cols: number;
+  rows: number;
+  theme?: ThemeName;
+  /** `document.title` fallback when no route sets one. */
+  defaultTitle?: string;
+  focused?: boolean;
+  /** A frame with changed cells was painted into {@link LiveApp.buffer}. */
+  onFrame?: () => void;
+  /**
+   * The app navigated. `runtime` is the target route's runtime; `delta` is how
+   * far a `"pop"` moved through the history.
+   */
+  onNavigate?: (href: string, action: HistoryAction, runtime: RouteRuntime, delta?: number) => void;
+  /**
+   * May the session render `href` (a server route)? Runs `middleware.ts` for
+   * the target before every server-side route transition. Denied transitions
+   * are handed to the browser as a document load, where middleware answers.
+   */
+  authorize?: (href: string) => Promise<boolean>;
+  onTitle?: (title: string) => void;
+  onError?: (error: unknown) => void;
+}
+
+export interface LiveApp {
+  readonly root: ConsoleRoot;
+  readonly buffer: CellBuffer;
+  readonly history: MemoryHistory;
+  input(event: LiveInput): void;
+  /** Apply a batch of input events (one POST) and paint once. */
+  inputMany?(events: readonly LiveInput[]): void;
+  /** Pause rendering while no browser is attached; resume (and repaint) on attach. */
+  setActive?(active: boolean): void;
+  /** Swap the manifest (dev: a route module changed). Keeps the history. */
+  setRoutes(routes: RouteManifest): void;
+  /** Lay out and paint synchronously. */
+  flush(): void;
+  dispose(): void;
+}
+
+const NULL_CONSOLE: ConsoleTarget = { clear() {}, log() {} };
+
+const timeoutScheduler: RendererScheduler = {
+  request: (cb) => setTimeout(cb, 0),
+  cancel: (h) => clearTimeout(h as ReturnType<typeof setTimeout>),
+};
+
+const prepared = new WeakMap<RouteManifest, RouteManifest>();
+
+/** Wrap async `default` exports (pages, layouts, …) so they render on the console reconciler. */
+export function prepareServerManifest(routes: RouteManifest): RouteManifest {
+  const hit = prepared.get(routes);
+  if (hit) return hit;
+  const wrapRef = (ref: RouteModuleRef | undefined): RouteModuleRef | undefined => {
+    if (ref === undefined || typeof ref === "function") return ref;
+    return isAsyncComponent(ref.default) ? ({ ...ref, default: serverComponent(ref.default as never) } as RouteModule) : ref;
+  };
+  const walk = (node: RouteSegmentNode): RouteSegmentNode => {
+    const out: RouteSegmentNode = { ...node };
+    for (const k of ["layout", "page", "loading", "error", "notFound"] as const) {
+      if (node[k] !== undefined) out[k] = wrapRef(node[k]);
+    }
+    if (node.children) out.children = node.children.map(walk);
+    return out;
+  };
+  const result = walk(routes);
+  prepared.set(routes, result);
+  return result;
+}
+
+/** `true` only when `pathname` matches a page that opts into `runtime = "server"` (HTML routing, new sessions). */
+export function isServerPage(routes: RouteManifest, pathname: string): boolean {
+  const match = resolveRoute(routes, pathname);
+  if (match.notFound) return false;
+  const page = match.chain[match.chain.length - 1]?.page;
+  return page !== undefined && typeof page !== "function" && page.runtime === "server";
+}
+
+/** The runtime of the page `pathname` resolves to (in-app navigation: not-found pages render where they are requested). */
+export function routeRuntime(routes: RouteManifest, pathname: string): RouteRuntime {
+  const match = resolveRoute(routes, pathname);
+  if (match.notFound) return "server";
+  const page = match.chain[match.chain.length - 1]?.page;
+  return page !== undefined && typeof page !== "function" && page.runtime === "server" ? "server" : "client";
+}
+
+function TitleReporter({ fallback, onTitle }: { fallback?: string; onTitle?: (title: string) => void }): ReactNode {
+  const state = useContext(RouterContext);
+  const title = state?.metadata.title ?? fallback;
+  useEffect(() => {
+    if (title !== undefined && onTitle) onTitle(title);
+  }, [title, onTitle]);
+  return null;
+}
+
+function pathOf(href: string): string {
+  const q = href.search(/[?#]/);
+  return q < 0 ? href : href.slice(0, q);
+}
+
+/** Mount a live session's App Router on the server. */
+export async function createLiveApp(options: LiveAppOptions): Promise<LiveApp> {
+  await initYoga();
+  const engine = new InputEngine({ document: null });
+  engine.setFocused(options.focused ?? true);
+  const root = createConsoleRootSync({
+    width: options.cols,
+    height: options.rows,
+    responsive: false,
+    theme: options.theme,
+    input: engine,
+    console: NULL_CONSOLE,
+    clear: "never",
+    scheduler: timeoutScheduler,
+    minFrameInterval: 0,
+    registerGlobal: false,
+    onFrame: (frame) => {
+      if (!frame.skipped) options.onFrame?.();
+    },
+    onCaughtError: (error) => options.onError?.(error),
+    onUncaughtError: (error) => options.onError?.(error),
+    onRecoverableError: () => undefined,
+  });
+  const inner = createMemoryHistory(options.path);
+  const cache = new ServerComponentCache();
+  let routes = prepareServerManifest(options.routes);
+  let fromClient = false;
+  let disposed = false;
+  let lastIndex = inner.index;
+  let navSeq = 0;
+
+  const unlisten = inner.listen((location, action) => {
+    const delta = inner.index - lastIndex;
+    lastIndex = inner.index;
+    if (fromClient) return;
+    options.onNavigate?.(location.href, action, routeRuntime(routes, location.pathname), action === "pop" ? delta : undefined);
+  });
+
+  /**
+   * Route transitions to server pages wait for `authorize` (middleware for the
+   * target). Denied ones become a document load of the target, which runs
+   * middleware over HTTP (redirects, 401s, rewrites).
+   */
+  const guard = (href: string, action: HistoryAction, apply: () => void): void => {
+    const target = parseHref(href, inner.location.pathname).href;
+    if (!options.authorize || routeRuntime(routes, pathOf(target)) === "client") {
+      navSeq++;
+      apply();
+      return;
+    }
+    const seq = ++navSeq;
+    options.authorize(target).then(
+      (ok) => {
+        if (disposed || seq !== navSeq) return;
+        if (ok) apply();
+        else options.onNavigate?.(target, action, "client");
+      },
+      (error: unknown) => {
+        options.onError?.(error);
+        if (!disposed && seq === navSeq) options.onNavigate?.(target, action, "client");
+      },
+    );
+  };
+  const history: MemoryHistory = Object.create(inner, {
+    push: { value: (href: string) => guard(href, "push", () => inner.push(href)) },
+    replace: { value: (href: string) => guard(href, "replace", () => inner.replace(href)) },
+    go: {
+      value: (delta: number) => {
+        const target = inner.entries[inner.index + delta];
+        if (target) guard(target.href, "pop", () => inner.go(delta));
+      },
+    },
+    back: { value: () => history.go(-1) },
+    forward: { value: () => history.go(1) },
+  }) as MemoryHistory;
+
+  const render = (): void => {
+    root.render(
+      <ServerComponentsProvider cache={cache}>
+        <AppRouter routes={routes} history={history} theme={options.theme} documentTitle={false} errorStore={null}>
+          <TitleReporter fallback={options.defaultTitle} onTitle={options.onTitle} />
+        </AppRouter>
+      </ServerComponentsProvider>,
+    );
+  };
+  render();
+
+  let active = true;
+  const applyInput = (event: LiveInput): void => {
+    if (root.unmounted) return;
+    switch (event.type) {
+      case "key":
+      case "paste":
+      case "wheel":
+        engine.emit(event.type, event as never);
+        break;
+      case "focus":
+        engine.setFocused(event.focused);
+        break;
+      case "resize":
+        root.renderer.resize(event.cols, event.rows);
+        break;
+      case "nav": {
+        const href = parseHref(event.href, inner.location.pathname).href;
+        if (href === inner.location.href) break;
+        // Browser Back / Forward: move through the same entries when they line up, so both histories agree.
+        const delta = event.delta;
+        const aligned = delta !== undefined && inner.entries[inner.index + delta]?.href === href;
+        guard(href, "pop", () => {
+          fromClient = true;
+          try {
+            if (aligned) inner.go(delta);
+            else inner.push(href);
+          } finally {
+            fromClient = false;
+          }
+          // Onto a client-rendered route: hand the document over.
+          if (routeRuntime(routes, inner.location.pathname) === "client") options.onNavigate?.(inner.location.href, "pop", "client");
+        });
+        break;
+      }
+    }
+  };
+
+  return {
+    root,
+    history,
+    get buffer() {
+      return root.renderer.buffer;
+    },
+    input: applyInput,
+    inputMany(events) {
+      if (events.length <= 1 || !active) {
+        for (const e of events) applyInput(e);
+        return;
+      }
+      // One paint for the whole batch; React still commits between events.
+      root.renderer.pause();
+      try {
+        for (const e of events) applyInput(e);
+      } finally {
+        if (!root.unmounted) root.renderer.resume();
+      }
+    },
+    setActive(next) {
+      if (next === active || root.unmounted) return;
+      active = next;
+      if (next) root.renderer.resume();
+      else root.renderer.pause();
+    },
+    setRoutes(next) {
+      routes = prepareServerManifest(next);
+      cache.clear();
+      if (!root.unmounted) render();
+    },
+    flush() {
+      if (!root.unmounted) root.flushSyncRender();
+    },
+    dispose() {
+      disposed = true;
+      unlisten();
+      cache.clear();
+      if (!root.unmounted) root.unmount();
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Partial Prerendering
+// ---------------------------------------------------------------------------
+
+export interface ShellCall {
+  method: "clear" | "log";
+  args: string[];
+}
+
+export interface PrerenderShellOptions {
+  routes: RouteManifest;
+  path: string;
+  cols: number;
+  rows: number;
+  theme?: ThemeName;
+}
+
+/**
+ * Render the static shell of a route: the first committed frame, with every
+ * `<Suspense>` boundary that is still waiting (async server components,
+ * `use()`, lazy modules) showing its fallback. `fetch` never resolves while
+ * rendering, so data loaded in effects stays in its loading state too.
+ *
+ * Returns the exact `console.clear()` / `console.log()` calls the client's
+ * driver would make for this frame (curtain included).
+ */
+export async function prerenderShell(options: PrerenderShellOptions): Promise<ShellCall[]> {
+  await initYoga();
+  const g = globalThis as { fetch?: typeof fetch };
+  const realFetch = g.fetch;
+  g.fetch = (() => new Promise<Response>(() => undefined)) as unknown as typeof fetch;
+  // Any error the render hit (caught by an error boundary, `redirect()` / `notFound()` included)
+  // means the first frame is not the route's shell: never bake it into HTML.
+  const errors: unknown[] = [];
+  const root = createConsoleRootSync({
+    width: options.cols,
+    height: options.rows,
+    responsive: false,
+    theme: options.theme,
+    input: new InputEngine({ document: null }),
+    console: NULL_CONSOLE,
+    clear: "never",
+    scheduler: { request: () => null, cancel: () => undefined },
+    minFrameInterval: 0,
+    registerGlobal: false,
+    onCaughtError: (error) => void errors.push(error),
+    onUncaughtError: (error) => void errors.push(error),
+    onRecoverableError: () => undefined,
+  });
+  try {
+    const history = createMemoryHistory(options.path);
+    root.render(
+      <ServerComponentsProvider cache={new ServerComponentCache()}>
+        <AppRouter routes={prepareServerManifest(options.routes)} history={history} theme={options.theme} documentTitle={false} errorStore={null} />
+      </ServerComponentsProvider>,
+    );
+    root.flushSyncRender();
+    if (errors.length > 0) {
+      const first = errors[0];
+      throw new Error(`rendering ${options.path} threw: ${first instanceof Error ? first.message : String(first)}`, { cause: first });
+    }
+    if (history.location.href !== parseHref(options.path).href) throw new Error(`rendering ${options.path} navigated to ${history.location.href}`);
+    const calls: ShellCall[] = [];
+    const capture: ConsoleTarget = {
+      clear: () => void calls.push({ method: "clear", args: [] }),
+      log: (...args: unknown[]) => void calls.push({ method: "log", args: args.map(String) }),
+    };
+    new CssConsoleDriver({ console: capture, curtain: true }).render(root.renderer.buffer);
+    return calls;
+  } finally {
+    root.unmount();
+    g.fetch = realFetch;
+  }
+}

package/src/server/live-build.ts

@@ -0,0 +1,258 @@
+/**
+ * `text build` step for server-rendered routes and Partial Prerendering:
+ *
+ * 1. `.text/server/live.mjs` — the SSR bundle (every route, the App Router and
+ *    the console renderer) that renders live sessions in `text start` and
+ *    the static shells below.
+ * 2. `assets/player-[hash].js` — the frame player, when any page is
+ *    `export const runtime = "server"`.
+ * 3. Static shells: each static route's first frame inlined into its HTML
+ *    (`index.html`, `<route>/index.html`; server routes under `.text/pages/`).
+ * 4. `.text/live-manifest.json` — what `text start` needs to serve them.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { gzipSync } from "node:zlib";
+import { build, mergeConfig, type InlineConfig, type Rollup } from "vite";
+import { normalizeBasePath, type TextConfig } from "../config";
+import type { ShellCall } from "./live-app";
+import { textjsLivePlugin } from "./live-dev";
+import { createLiveHtml, listServerPages, VIRTUAL_LIVE, VIRTUAL_PLAYER } from "./live-routes";
+import { injectShell, shellPath, shellScript } from "./ppr";
+import { LIVE_MANIFEST, type LiveManifest } from "./live-manifest";
+import { listPages, type AppScan } from "./scan";
+
+export { LIVE_MANIFEST, type LiveManifest } from "./live-manifest";
+
+/** How long one route may take to prerender before it streams without a shell. */
+export const PRERENDER_TIMEOUT_MS = 10_000;
+
+type PrerenderResult = { calls: ShellCall[] } | { error: string };
+
+const RESULT_MARK = "\u0000textjs-prerender:";
+
+/**
+ * Prerender shells in a disposable child process: route modules' top-level
+ * side effects (timers, sockets, a patched `fetch`) can't hang or leak into the
+ * build, and each route gets `timeoutMs`. The child exits once its results are
+ * written.
+ */
+export async function prerenderInChild(
+  liveBundle: string,
+  job: { paths: string[]; cols: number; rows: number; theme?: string; timeoutMs: number },
+): Promise<Record<string, PrerenderResult>> {
+  if (job.paths.length === 0) return {};
+  const runner = join(dirname(liveBundle), `prerender-${process.pid}-${Date.now()}.mjs`);
+  writeFileSync(
+    runner,
+    `const job = JSON.parse(process.argv[3]);
+const out = {};
+const timeout = (ms) => new Promise((_, reject) => setTimeout(() => reject(new Error("timed out after " + ms + "ms")), ms).unref?.());
+try {
+  const entry = await Promise.race([import(process.argv[2]), timeout(job.timeoutMs)]);
+  for (const path of job.paths) {
+    try {
+      const calls = await Promise.race([entry.prerenderShell({ routes: entry.routes, path, cols: job.cols, rows: job.rows, theme: job.theme }), timeout(job.timeoutMs)]);
+      out[path] = { calls };
+    } catch (error) {
+      out[path] = { error: error instanceof Error ? error.message : String(error) };
+    }
+  }
+} catch (error) {
+  for (const path of job.paths) out[path] ??= { error: error instanceof Error ? error.message : String(error) };
+}
+process.stdout.write(${JSON.stringify(RESULT_MARK)} + JSON.stringify(out) + "\\n", () => process.exit(0));
+`,
+  );
+  try {
+    const budget = job.timeoutMs * job.paths.length + 30_000;
+    const output = await new Promise<string>((resolveRun) => {
+      const child = spawn(process.execPath, [runner, pathToFileURL(liveBundle).href, JSON.stringify(job)], { stdio: ["ignore", "pipe", "inherit"], env: process.env });
+      let stdout = "";
+      child.stdout.setEncoding("utf8");
+      child.stdout.on("data", (chunk: string) => {
+        stdout += chunk;
+      });
+      const timer = setTimeout(() => child.kill("SIGKILL"), budget);
+      child.on("close", () => {
+        clearTimeout(timer);
+        resolveRun(stdout);
+      });
+      child.on("error", () => {
+        clearTimeout(timer);
+        resolveRun(stdout);
+      });
+    });
+    const line = output.split("\n").find((l) => l.startsWith(RESULT_MARK));
+    if (line === undefined) return Object.fromEntries(job.paths.map((p) => [p, { error: "the prerender process exited without results" }]));
+    return JSON.parse(line.slice(RESULT_MARK.length)) as Record<string, PrerenderResult>;
+  } finally {
+    rmSync(runner, { force: true });
+  }
+}
+
+export interface LiveBuildOptions {
+  root: string;
+  config: TextConfig;
+  outDir: string;
+  scan: AppScan;
+  /** Build plugins (the caller passes `textjsVitePlugin(config)`). */
+  plugins: InlineConfig["plugins"];
+  /** Per-route prerender budget (default {@link PRERENDER_TIMEOUT_MS}). */
+  prerenderTimeoutMs?: number;
+}
+
+export interface LiveBuildResult {
+  manifest: LiveManifest;
+  shells: number;
+  staticRoutes: number;
+  /** Routes whose shell could not be prerendered, with the reason. */
+  skipped: Array<{ pattern: string; reason: string }>;
+  player: { bytes: number; gzip: number } | null;
+}
+
+const META = ".text";
+
+function htmlFileFor(pattern: string, server: boolean): string {
+  const dir = pattern === "/" ? "" : pattern.slice(1);
+  if (server) return join(META, "pages", dir, "index.html");
+  return dir ? join(dir, "index.html") : "index.html";
+}
+
+/** Run after the client build. Returns `null` when there is nothing to do. */
+export async function buildLiveRoutes(o: LiveBuildOptions): Promise<LiveBuildResult | null> {
+  const { config, outDir, scan } = o;
+  const basePath = normalizeBasePath(config.basePath);
+  const serverPages = listServerPages(scan);
+  const serverSet = new Set(serverPages.map((p) => p.pattern));
+  const pages = listPages(scan);
+  const ppr = config.ppr !== false;
+  const staticPages = ppr ? pages.filter((p) => !p.dynamic) : [];
+  if (serverPages.length === 0 && staticPages.length === 0) return null;
+
+  const withVite = (c: InlineConfig): InlineConfig => (config.vite ? mergeConfig(c, config.vite) : c);
+  const serverDir = join(outDir, META, "server");
+  await build(
+    withVite({
+      configFile: false,
+      root: o.root,
+      mode: "production",
+      logLevel: "error",
+      clearScreen: false,
+      build: {
+        ssr: VIRTUAL_LIVE,
+        outDir: serverDir,
+        emptyOutDir: false,
+        target: "node18",
+        rollupOptions: { output: { entryFileNames: "live.mjs", format: "es" } },
+      },
+      ssr: { noExternal: [/^@textjs\//] },
+      plugins: o.plugins,
+    }),
+  );
+
+  let player: LiveBuildResult["player"] = null;
+  let playerUrl: string | null = null;
+  if (serverPages.length > 0) {
+    const out = (await build(
+      withVite({
+        configFile: false,
+        root: o.root,
+        base: basePath ? `${basePath}/` : "/",
+        mode: "production",
+        logLevel: "error",
+        clearScreen: false,
+        publicDir: false,
+        build: {
+          outDir,
+          emptyOutDir: false,
+          target: "es2022",
+          modulePreload: false,
+          rollupOptions: { input: { player: VIRTUAL_PLAYER }, output: { entryFileNames: "assets/player-[hash].js", format: "es" } },
+        },
+        // The player imports only @textjs/core: no React, no route modules.
+        plugins: textjsLivePlugin({ appDir: config.appDir, root: o.root }),
+      }),
+    )) as Rollup.RollupOutput | Rollup.RollupOutput[];
+    const outputs = Array.isArray(out) ? out : [out];
+    const chunk = outputs.flatMap((r) => r.output).find((c): c is Rollup.OutputChunk => c.type === "chunk" && c.isEntry);
+    if (chunk) {
+      const code = readFileSync(join(outDir, chunk.fileName));
+      player = { bytes: code.length, gzip: gzipSync(code).length };
+      playerUrl = `${basePath}/${chunk.fileName}`;
+    }
+  }
+
+  const title = config.title ?? "\u25BC Text.js";
+  const manifest: LiveManifest = {
+    version: 1,
+    basePath,
+    title,
+    viewport: config.viewport ?? {},
+    player: playerUrl,
+    serverRoutes: serverPages.map((p) => p.pattern),
+    pages: {},
+    liveHtml: null,
+    ...(config.live ? { live: config.live } : {}),
+  };
+  const write = (rel: string, html: string): void => {
+    const file = join(outDir, rel);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, html);
+  };
+  const liveDoc = (shell?: string): string => createLiveHtml({ title, basePath, viewport: config.viewport, playerSrc: playerUrl ?? "", shell });
+  if (playerUrl) {
+    manifest.liveHtml = join(META, "live.html");
+    write(manifest.liveHtml, liveDoc());
+  }
+
+  const skipped: LiveBuildResult["skipped"] = [];
+  let shells = 0;
+  if (staticPages.length > 0) {
+    const indexFile = join(outDir, "index.html");
+    const template = existsSync(indexFile) ? readFileSync(indexFile, "utf8") : null;
+    const vp = config.viewport ?? {};
+    const wanted = staticPages.filter((p) => serverSet.has(p.pattern) || template !== null);
+    const results = await prerenderInChild(join(serverDir, "live.mjs"), {
+      paths: wanted.map((p) => p.pattern),
+      cols: vp.width ?? 120,
+      rows: vp.height ?? 36,
+      theme: vp.theme,
+      timeoutMs: o.prerenderTimeoutMs ?? PRERENDER_TIMEOUT_MS,
+    });
+    for (const page of wanted) {
+      const server = serverSet.has(page.pattern);
+      try {
+        const result = results[page.pattern] ?? { error: "prerendering did not finish" };
+        if ("error" in result) throw new Error(result.error);
+        const script = shellScript(result.calls, shellPath(basePath, page.pattern));
+        const rel = htmlFileFor(page.pattern, server);
+        write(rel, server ? liveDoc(script) : injectShell(template as string, script));
+        manifest.pages[page.pattern] = rel;
+        shells++;
+      } catch (error) {
+        skipped.push({ pattern: page.pattern, reason: error instanceof Error ? error.message : String(error) });
+      }
+    }
+  }
+  write(join(META, LIVE_MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`);
+  return { manifest, shells, staticRoutes: staticPages.length, skipped, player };
+}
+
+/** Bytes of every client `.js` asset except the frame player (for size comparisons). */
+export function clientBundleBytes(outDir: string): { bytes: number; gzip: number } {
+  let bytes = 0;
+  let gzip = 0;
+  const dir = join(outDir, "assets");
+  if (!existsSync(dir)) return { bytes, gzip };
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith(".js") || name.startsWith("player-")) continue;
+    const buf = readFileSync(join(dir, name));
+    bytes += buf.length;
+    gzip += gzipSync(buf).length;
+  }
+  return { bytes, gzip };
+}