@textjs/app 0.0.0-stage → 1.0.2

package/src/cli/build.ts

@@ -0,0 +1,182 @@
+import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { gzipSync } from "node:zlib";
+import { build, mergeConfig, type InlineConfig } from "vite";
+import { ENGINE_NAME, VERSION } from "@textjs/core";
+import { normalizeBasePath } from "../config";
+import { listApiRoutes, listPages, scanApp } from "../server/scan";
+import { buildLiveRoutes } from "../server/live-build";
+import { listServerPages } from "../server/live-routes";
+import { textjsVitePlugin, VIRTUAL_API } from "../vite-plugin";
+import { buildServerRuntime, resolveAdapter, runBuildAdapter, serverFiles } from "../server/adapters/build-step";
+import type { AdapterResult } from "../server/adapters/shared";
+import { loadTextConfig } from "./config";
+import { brand, color, fail, formatBytes, LEGEND, ok, routeTable, SERVER_LEGEND, summarize, type SummaryRoute } from "./ui";
+
+export interface BuildOptions {
+  root: string;
+  /** Deploy adapter (`--adapter`); defaults to `TEXTJS_ADAPTER`, or Vercel / Cloudflare Pages when building there. */
+  adapter?: string;
+  /** Print the summary (default `true`). */
+  log?: boolean;
+}
+
+export interface BuildManifest {
+  version: string;
+  engine: string;
+  basePath: string;
+  routes: Array<{ pattern: string; type: "static" | "dynamic"; file?: string }>;
+  api: Array<{ pattern: string }>;
+  firstLoad: { bytes: number; gzip: number };
+}
+
+export interface BuildResult {
+  outDir: string;
+  routes: SummaryRoute[];
+  manifest: BuildManifest;
+  output: string;
+  durationMs: number;
+  /** Deploy output written by `--adapter`. */
+  adapter?: AdapterResult;
+}
+
+/** `.text/` inside the output directory holds build metadata and the API server bundle. */
+export const META_DIR = ".text";
+
+function jsFiles(dir: string): string[] {
+  const out: string[] = [];
+  const walk = (d: string): void => {
+    for (const name of readdirSync(d)) {
+      const p = join(d, name);
+      if (name === META_DIR) continue;
+      if (statSync(p).isDirectory()) walk(p);
+      else if (name.endsWith(".js")) out.push(p);
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+export async function buildApp(opts: BuildOptions): Promise<BuildResult> {
+  const log = opts.log ?? true;
+  const lines: string[] = [];
+  const print = (s = ""): void => {
+    lines.push(s);
+    if (log) console.log(s);
+  };
+  const started = performance.now();
+  const { config } = await loadTextConfig(opts.root, "build");
+  const outDir = resolve(opts.root, config.outDir ?? "dist");
+
+  print(`   ${brand()}`);
+  print();
+  print("   Creating an optimized console production build...");
+  print();
+
+  const base: InlineConfig = {
+    configFile: false,
+    root: opts.root,
+    mode: "production",
+    logLevel: "warn",
+    clearScreen: false,
+    build: { outDir, emptyOutDir: true },
+    plugins: [textjsVitePlugin({ ...config, root: opts.root })],
+  };
+  const scan = scanApp(opts.root, config.appDir ?? "app");
+  let adapterName: ReturnType<typeof resolveAdapter>;
+  try {
+    adapterName = resolveAdapter(opts.adapter);
+  } catch (error) {
+    print(fail(error instanceof Error ? error.message : String(error)));
+    throw error;
+  }
+  let hasMiddleware = false;
+  const api = listApiRoutes(scan);
+  try {
+    await build(config.vite ? mergeConfig(base, config.vite) : base);
+    if (api.length > 0) await buildApiServer();
+    hasMiddleware = (await buildServerRuntime(opts.root, config, outDir)) && serverFiles(opts.root, config).middlewareFile !== null;
+  } catch (error) {
+    print(fail(color.red("Failed to compile.")));
+    print();
+    print(error instanceof Error ? (error.stack ?? error.message) : String(error));
+    throw error;
+  }
+
+  async function buildApiServer(): Promise<void> {
+    const serverBuild: InlineConfig = {
+      configFile: false,
+      root: opts.root,
+      mode: "production",
+      logLevel: "warn",
+      clearScreen: false,
+      build: {
+        ssr: VIRTUAL_API,
+        outDir: join(outDir, META_DIR, "server"),
+        emptyOutDir: true,
+        target: "node18",
+        rollupOptions: { output: { entryFileNames: "api.mjs", format: "es" } },
+      },
+      // Bundle the framework into api.mjs so `text start` runs on plain Node.
+      ssr: { noExternal: ["@textjs/app", /^@textjs\//] },
+      plugins: [textjsVitePlugin({ ...config, root: opts.root })],
+    };
+    await build(config.vite ? mergeConfig(serverBuild, config.vite) : serverBuild);
+  }
+
+  const compiledMs = performance.now() - started;
+  print(ok(`Compiled successfully in ${(compiledMs / 1000).toFixed(1)}s`));
+
+  const pages = listPages(scan);
+  print(ok("Collecting route data"));
+  print(ok(`Generating static console cells (${pages.filter((p) => !p.dynamic).length}/${pages.length})`));
+
+  let bytes = 0;
+  let gzip = 0;
+  for (const f of jsFiles(outDir)) {
+    const buf = readFileSync(f);
+    bytes += buf.length;
+    gzip += gzipSync(buf).length;
+  }
+  // Partial Prerendering shells + server-rendered routes (after measuring the client bundle).
+  const live = await buildLiveRoutes({ root: opts.root, config, outDir, scan, plugins: [textjsVitePlugin({ ...config, root: opts.root })] });
+  if (live) {
+    const player = live.player ? `, frame player ${formatBytes(live.player.bytes)} (${formatBytes(live.player.gzip)} gzip)` : "";
+    print(ok(`Prerendering console shells (${live.shells}/${live.staticRoutes})${live.manifest.serverRoutes.length > 0 ? ` · ${live.manifest.serverRoutes.length} server-rendered` : ""}${player}`));
+    for (const s of live.skipped) print(color.gray(`   ${s.pattern} streams without a shell: ${s.reason.split("\n")[0]}`));
+  }
+  const routes = summarize(pages, api, new Set(listServerPages(scan).map((p) => p.pattern)));
+  const manifest: BuildManifest = {
+    version: VERSION,
+    engine: ENGINE_NAME,
+    basePath: normalizeBasePath(config.basePath),
+    routes: pages.map((p) => ({ pattern: p.pattern, type: p.dynamic ? "dynamic" : "static", file: p.file })),
+    api: api.map((a) => ({ pattern: a.pattern })),
+    firstLoad: { bytes, gzip },
+  };
+  mkdirSync(join(outDir, META_DIR), { recursive: true });
+  writeFileSync(join(outDir, META_DIR, "routes-manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+  print(ok("Finalizing console optimization"));
+  print();
+  print(routeTable(routes));
+  print(`+ First Load JS shared by all${" ".repeat(13)}${formatBytes(bytes)} ${color.gray(`(${formatBytes(gzip)} gzip)`)}`);
+  if (hasMiddleware) print(`ƒ Middleware`);
+  print();
+  print(routes.some((r) => r.server) ? `${LEGEND}\n${SERVER_LEGEND}` : LEGEND);
+  print();
+  let adapter: AdapterResult | undefined;
+  if (adapterName) {
+    try {
+      adapter = await runBuildAdapter({ root: opts.root, config, outDir, scan, api, adapter: adapterName, print });
+    } catch (error) {
+      print(fail(color.red(`Adapter ${adapterName} failed.`)));
+      print();
+      print(error instanceof Error ? error.message : String(error));
+      throw error;
+    }
+    print(ok(`Adapter ${color.bold(adapter.adapter)} → ${relative(opts.root, adapter.output) || "."}`));
+    for (const note of adapter.notes) print(color.gray(`   ${note}`));
+    print();
+  }
+  return { outDir, routes, manifest, output: lines.join("\n"), durationMs: performance.now() - started, adapter };
+}

package/src/cli/config.ts

@@ -0,0 +1,72 @@
+import { existsSync } from "node:fs";
+import { basename, join } from "node:path";
+import { loadConfigFromFile } from "vite";
+import { txWarn } from "@textjs/core";
+import type { TextConfig } from "../config";
+
+/** Every `TextConfig` key; the `Record` type fails typecheck when a new option is not listed. */
+const CONFIG_KEYS: Record<keyof TextConfig, true> = {
+  viewport: true,
+  devIndicators: true,
+  showMirrorDefault: true,
+  outDir: true,
+  appDir: true,
+  basePath: true,
+  title: true,
+  hints: true,
+  action: true,
+  proxy: true,
+  rewrites: true,
+  configureServer: true,
+  vite: true,
+  cacheHandler: true,
+  ppr: true,
+  live: true,
+  server: true,
+};
+
+/** Warn (once each) about keys Text.js does not read. */
+export function warnUnknownConfigKeys(config: object, file: string): void {
+  for (const key of Object.keys(config)) if (!(key in CONFIG_KEYS)) txWarn("TX029", JSON.stringify(key), basename(file));
+}
+
+export const CONFIG_FILES = ["text.config.ts", "text.config.mts", "text.config.js", "text.config.mjs"] as const;
+
+export function findConfigFile(root: string): string | null {
+  for (const name of CONFIG_FILES) {
+    const p = join(root, name);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * Run `fn` and put `process.env.NODE_ENV` back afterwards. Vite's module
+ * runner (the Node config loader) sets an unset `NODE_ENV` to
+ * `"development"`, which would make the following `vite build` bundle
+ * React's development builds.
+ */
+export async function preservingNodeEnv<T>(fn: () => Promise<T>): Promise<T> {
+  const before = process.env.NODE_ENV;
+  try {
+    return await fn();
+  } finally {
+    if (before === undefined) delete process.env.NODE_ENV;
+    else process.env.NODE_ENV = before;
+  }
+}
+
+/**
+ * Load `text.config.ts`. Bun runs TypeScript dependencies natively, so the
+ * config is bundled with esbuild; on Node, Vite's module runner transforms
+ * TypeScript workspace packages (`@textjs/app` sources) imported by the config.
+ */
+export async function loadTextConfig(root: string, command: "serve" | "build", mode = command === "build" ? "production" : "development"): Promise<{ config: TextConfig; file: string | null }> {
+  const file = findConfigFile(root);
+  if (!file) return { config: {}, file: null };
+  const loader = typeof process.versions.bun === "string" ? "bundle" : "runner";
+  const loaded = await preservingNodeEnv(() => loadConfigFromFile({ command, mode }, file, root, "silent", undefined, loader));
+  const config = (loaded?.config ?? {}) as TextConfig;
+  warnUnknownConfigKeys(config, file);
+  return { config, file };
+}

package/src/cli/dev.ts

@@ -0,0 +1,54 @@
+import { relative } from "node:path";
+import { createServer, mergeConfig, type InlineConfig, type ViteDevServer } from "vite";
+import { textjsVitePlugin, type TextLogger } from "../vite-plugin";
+import { loadTextConfig } from "./config";
+import { banner, color, devtoolsHint, ok } from "./ui";
+
+export interface DevOptions {
+  root: string;
+  port?: number;
+  host?: string | boolean;
+  /** Print logs (default `true`). */
+  log?: boolean;
+}
+
+export function cliLogger(enabled = true): TextLogger {
+  return {
+    info: (m) => {
+      if (enabled) console.log(color.gray(m));
+    },
+    error: (m) => {
+      if (enabled) console.error(color.red(m));
+    },
+  };
+}
+
+export async function startDevServer(opts: DevOptions): Promise<ViteDevServer> {
+  const started = performance.now();
+  const { config, file } = await loadTextConfig(opts.root, "serve");
+  const log = opts.log ?? true;
+  const inline: InlineConfig = {
+    configFile: false,
+    root: opts.root,
+    mode: "development",
+    logLevel: log ? "warn" : "silent",
+    clearScreen: false,
+    server: { port: opts.port ?? 3000, host: opts.host, strictPort: false },
+    plugins: [textjsVitePlugin({ ...config, root: opts.root, logger: cliLogger(log) })],
+  };
+  const server = await createServer(config.vite ? mergeConfig(inline, config.vite) : inline);
+  await server.listen();
+  if (log) {
+    const urls = server.resolvedUrls;
+    const lines: Array<[string, string]> = [["Local", color.cyan(urls?.local[0] ?? `http://localhost:${opts.port ?? 3000}`)]];
+    if (urls?.network[0]) lines.push(["Network", color.cyan(urls.network[0])]);
+    if (file) lines.push(["Config", relative(opts.root, file)]);
+    console.log(`\n${banner(lines)}\n`);
+    console.log(ok("Starting..."));
+    console.log(ok(`Ready in ${Math.round(performance.now() - started)}ms`));
+    console.log("");
+    console.log(devtoolsHint());
+    console.log("");
+  }
+  return server;
+}

package/src/cli/index.ts

@@ -0,0 +1,185 @@
+// Command modules (Vite, the dev server, the MCP server) load lazily: `text mcp`
+// must own stdout before any third-party module runs.
+import { spawn } from "node:child_process";
+import { resolve } from "node:path";
+import { txError, txMessage, VERSION } from "@textjs/core";
+import { brand, color, fail } from "./ui";
+
+export interface ParsedArgs {
+  command: string;
+  dir: string;
+  port?: number;
+  host?: string | boolean;
+  /** `text proxy --target <url>`. */
+  target?: string;
+  /** `text proxy --allow-origin <origin>` (repeatable). */
+  allowOrigins: string[];
+  /** `text build --adapter <static|bun|vercel|cloudflare>`. */
+  adapter?: string;
+  /** `text run --path <pathname>`. */
+  path?: string;
+  help: boolean;
+  version: boolean;
+}
+
+export function parseArgs(argv: readonly string[]): ParsedArgs {
+  const out: ParsedArgs = { command: "", dir: ".", allowOrigins: [], help: false, version: false };
+  const positional: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i] as string;
+    if (a === "-h" || a === "--help") out.help = true;
+    else if (a === "-v" || a === "--version") out.version = true;
+    else if (a === "-p" || a === "--port") out.port = Number(argv[++i]);
+    else if (a.startsWith("--port=")) out.port = Number(a.slice(7));
+    else if (a === "--path") out.path = argv[++i];
+    else if (a.startsWith("--path=")) out.path = a.slice(7);
+    else if (a === "--adapter") out.adapter = argv[++i];
+    else if (a.startsWith("--adapter=")) out.adapter = a.slice(10);
+    else if (a === "--target") out.target = argv[++i];
+    else if (a.startsWith("--target=")) out.target = a.slice(9);
+    else if (a === "--allow-origin") {
+      const v = argv[++i];
+      if (v) out.allowOrigins.push(v);
+    } else if (a.startsWith("--allow-origin=")) out.allowOrigins.push(a.slice(15));
+    else if (a === "-H" || a === "--host" || a === "--hostname") {
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("-") && /[.:]|localhost/.test(next)) {
+        out.host = next;
+        i++;
+      } else out.host = true;
+    } else if (a.startsWith("--host=")) out.host = a.slice(7);
+    else positional.push(a);
+  }
+  out.command = positional[0] ?? "";
+  if (positional[1]) out.dir = positional[1];
+  if (out.port !== undefined && !Number.isFinite(out.port)) out.port = undefined;
+  return out;
+}
+
+export const HELP = `Usage: text <command> [options] [dir]
+
+Commands:
+  dev      Start the development server (Vite + React Fast Refresh)
+  build    Create an optimized console production build
+  start    Serve the production build
+  run      Render the app in this terminal (Bun)
+  proxy    Bridge textjs.org/opencode to your local OpenCode server
+           (same as bunx @textjs/opencode proxy)
+  mcp      Serve the app to coding agents over MCP (stdio, Bun)
+
+Options:
+  -p, --port <port>   Port (default 3000; proxy 4096)
+  --path <pathname>   run: initial route (default /)
+  --adapter <name>    build: static | bun | vercel | cloudflare
+  --target <url>      proxy: OpenCode server URL (default: discover)
+  --allow-origin <o>  proxy: allow another browser origin
+  -H, --host [host]   Expose on the network (optionally bind a host)
+  -v, --version       Print the Text.js version
+  -h, --help          Show this help
+`;
+
+/** Commands that import route files as TypeScript and so need Bun. */
+const BUN_COMMANDS = new Set(["run", "mcp"]);
+const REEXEC_ENV = "TEXTJS_REEXEC_BUN";
+
+/**
+ * Re-run this CLI under Bun (same script and arguments, inherited stdio,
+ * forwarded signals). Resolves with the child's exit code, or `null` when
+ * Bun is not installed.
+ */
+export function reexecUnderBun(argv: readonly string[], script = process.argv[1]): Promise<number | null> {
+  if (!script || process.env[REEXEC_ENV]) return Promise.resolve(null);
+  return new Promise((done) => {
+    const child = spawn("bun", [script, ...argv], { stdio: "inherit", env: { ...process.env, [REEXEC_ENV]: "1" } });
+    const signals = ["SIGINT", "SIGTERM", "SIGHUP"] as const;
+    const forward = (signal: NodeJS.Signals): void => void child.kill(signal);
+    for (const s of signals) process.on(s, forward);
+    const finish = (code: number | null): void => {
+      for (const s of signals) process.off(s, forward);
+      done(code);
+    };
+    child.once("error", () => finish(null));
+    child.once("exit", (code, signal) => finish(code ?? (signal ? 1 : 0)));
+  });
+}
+
+export async function main(argv: readonly string[]): Promise<number> {
+  const args = parseArgs(argv);
+  if (args.version) {
+    console.log(`Text.js v${VERSION}`);
+    return 0;
+  }
+  if (BUN_COMMANDS.has(args.command) && !args.help && typeof process.versions.bun !== "string") {
+    const code = await reexecUnderBun(argv);
+    if (code !== null) return code;
+    // No Bun: `text mcp` reports TX019 on stderr (stdout is reserved for JSON-RPC).
+    if (args.command === "mcp") {
+      process.stderr.write(`${txMessage("TX019", "mcp", "mcp")}\n`);
+      return 1;
+    }
+  }
+  if (args.command === "mcp") {
+    // Owns stdout (JSON-RPC) and its own flags; see `text mcp --help`.
+    const { runMcpCli } = await import("../mcp/cli");
+    return runMcpCli(argv);
+  }
+  if (args.help || args.command === "" || args.command === "help") {
+    console.log(`\n   ${brand()}\n   The Console Framework for the Web\n`);
+    console.log(HELP);
+    return args.command === "" && !args.help ? 1 : 0;
+  }
+  const root = resolve(args.dir);
+  try {
+    switch (args.command) {
+      case "dev": {
+        const { startDevServer } = await import("./dev");
+        const server = await startDevServer({ root, port: args.port, host: args.host });
+        const stop = async (): Promise<void> => {
+          await server.close();
+          process.exit(0);
+        };
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+        await new Promise<never>(() => undefined);
+        return 0;
+      }
+      case "build": {
+        const { buildApp } = await import("./build");
+        await buildApp({ root, adapter: args.adapter });
+        return 0;
+      }
+      case "start": {
+        const { startProductionServer } = await import("./start");
+        const s = await startProductionServer({ root, port: args.port, host: typeof args.host === "string" ? args.host : args.host ? "0.0.0.0" : undefined });
+        const stop = async (): Promise<void> => {
+          await s.close();
+          process.exit(0);
+        };
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+        await new Promise<never>(() => undefined);
+        return 0;
+      }
+      case "run": {
+        if (typeof process.versions.bun !== "string") throw txError("TX019", "run", "run");
+        const { runInTerminal } = await import("./run");
+        const app = await runInTerminal({ root, path: args.path });
+        await app.waitUntilExit();
+        return 0;
+      }
+      case "proxy": {
+        // One implementation: the bridge lives in @textjs/opencode (`bunx @textjs/opencode proxy`).
+        const { runProxy } = await import("@textjs/opencode");
+        return await runProxy({ port: args.port, target: args.target, allowOrigins: args.allowOrigins });
+      }
+      default:
+        console.error(fail(txMessage("TX020", color.bold(args.command))));
+        if (args.command === "deploy") console.error(color.gray("   To deploy, run text build --adapter <static|bun|vercel|cloudflare>."));
+        console.log(HELP);
+        return 1;
+    }
+  } catch (error) {
+    if (args.command !== "build") console.error(fail(error instanceof Error ? error.message : String(error)));
+    return 1;
+  }
+}

package/src/cli/run.ts

@@ -0,0 +1,124 @@
+/**
+ * `text run` — render the `app/` directory in the terminal: same routes,
+ * layouts, components and route handlers, drawn with truecolor ANSI instead
+ * of `console.log`. Runs on Bun (route files are imported as TypeScript).
+ */
+
+import { existsSync } from "node:fs";
+import { relative } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createElement } from "react";
+import { txError } from "@textjs/core";
+import { renderToTerminal, type TerminalInput, type TerminalOutput, type TerminalRoot } from "@textjs/react/terminal";
+import type { ThemeName } from "@textjs/react";
+import { createMemoryHistory } from "../history";
+import { AppRouter } from "../router";
+import { ROUTE_FILE_KINDS, type RouteManifest, type RouteModule, type RouteSegmentNode } from "../routing";
+import { matchApiRoute, scanApp, toApiManifest, toPosix, type AppScan, type ScannedSegment } from "../server/scan";
+import { runRouteHandler, type RouteHandlerModule } from "../server/http";
+import { installServerJsxRuntime } from "../server/bun-jsx";
+import { prepareServerManifest } from "../server/live-app";
+import { ServerComponentCache, ServerComponentsProvider } from "../server/server-components";
+import { loadTextConfig } from "./config";
+
+export interface RunOptions {
+  root: string;
+  /** Initial pathname (default `/`). */
+  path?: string;
+  theme?: ThemeName;
+  stdin?: TerminalInput;
+  stdout?: TerminalOutput;
+  /** Skip `text.config.ts` (tests). */
+  skipConfig?: boolean;
+}
+
+const importFile = (file: string): Promise<RouteModule> => import(pathToFileURL(file).href) as Promise<RouteModule>;
+
+/** A route manifest whose modules are imported on demand from disk. */
+export function toRuntimeManifest(scan: AppScan): RouteManifest {
+  const convert = (s: ScannedSegment): RouteSegmentNode | null => {
+    const node: RouteSegmentNode = { segment: s.segment, files: {} };
+    let has = false;
+    for (const kind of ROUTE_FILE_KINDS) {
+      const f = s.files[kind];
+      if (!f) continue;
+      has = true;
+      const key = kind === "not-found" ? "notFound" : kind;
+      (node as unknown as Record<string, unknown>)[key] = () => importFile(f);
+      (node.files as Record<string, string>)[kind] = toPosix(relative(scan.root, f));
+    }
+    const children = s.children.map(convert).filter((c): c is RouteSegmentNode => c !== null);
+    if (children.length > 0) node.children = children;
+    return has || children.length > 0 || s.segment === "" ? node : null;
+  };
+  return convert(scan.tree) as RouteManifest;
+}
+
+/** Import every route module up front (no Suspense flashes on the first frame). */
+export async function loadRuntimeManifest(scan: AppScan): Promise<RouteManifest> {
+  const manifest = toRuntimeManifest(scan);
+  const tasks: Array<Promise<void>> = [];
+  const walk = (node: RouteSegmentNode): void => {
+    for (const key of ["layout", "page", "loading", "error", "notFound"] as const) {
+      const ref = node[key];
+      if (typeof ref === "function") tasks.push(ref().then((m) => void (node[key] = m)));
+    }
+    node.children?.forEach(walk);
+  };
+  walk(manifest);
+  await Promise.all(tasks);
+  return manifest;
+}
+
+/**
+ * Wrap `fetch` so same-origin paths (`fetch("/api/health")`) run the app's
+ * route handlers in-process, exactly as `text dev` would serve them.
+ */
+export function createLocalFetch(scan: AppScan, base: typeof fetch = fetch, origin = "http://localhost:3000"): typeof fetch {
+  const api = toApiManifest(scan);
+  const local = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const raw = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    if (!raw.startsWith("/") || raw.startsWith("//")) return base(input, init);
+    const url = new URL(raw, origin);
+    const hit = matchApiRoute(api, url.pathname);
+    if (!hit) return new Response("Not Found", { status: 404 });
+    const mod = (await import(pathToFileURL(hit.file).href)) as RouteHandlerModule;
+    const request = input instanceof Request ? new Request(url, input) : new Request(url, init);
+    return runRouteHandler(mod, request, hit.params);
+  };
+  return Object.assign(local, { preconnect: () => undefined }) as unknown as typeof fetch;
+}
+
+/** Render the app in the terminal. Resolves once it is mounted. */
+export async function runInTerminal(opts: RunOptions): Promise<TerminalRoot> {
+  const scan = scanApp(opts.root);
+  if (!existsSync(scan.appDir)) throw txError("TX018", opts.root);
+  let theme = opts.theme;
+  if (!opts.skipConfig && theme === undefined) {
+    const { config } = await loadTextConfig(opts.root, "serve");
+    const t = (config as { viewport?: { theme?: unknown } }).viewport?.theme;
+    if (typeof t === "string") theme = t as ThemeName;
+  }
+  const g = globalThis as { fetch: typeof fetch };
+  const originalFetch = g.fetch;
+  g.fetch = createLocalFetch(scan, originalFetch);
+  const history = createMemoryHistory(opts.path ?? "/");
+  // `async function` components (e.g. `runtime = "server"` pages) render like in `text dev`.
+  installServerJsxRuntime(opts.root);
+  const routes = prepareServerManifest(await loadRuntimeManifest(scan));
+  const app = await renderToTerminal(
+    createElement(ServerComponentsProvider, { cache: new ServerComponentCache() }, createElement(AppRouter, { routes, history, theme, documentTitle: false, errorStore: null })),
+    {
+      stdin: opts.stdin,
+      stdout: opts.stdout,
+      theme,
+      onExit: () => {
+        g.fetch = originalFetch;
+      },
+    },
+  );
+  void app.waitUntilExit().then(() => {
+    g.fetch = originalFetch;
+  });
+  return app;
+}