@textjs/app 0.0.0-stage → 1.0.3

package/src/routing.ts

@@ -0,0 +1,344 @@
+/**
+ * Pure App Router matching: route manifests, segment ranking, params,
+ * not-found resolution and metadata. Shared by the browser router, the Vite
+ * plugin and the `text build` route summary.
+ */
+
+import type { ComponentType } from "react";
+import type { Metadata } from "./config";
+
+export type RouteParams = Record<string, string | string[]>;
+export type SearchParamsRecord = Record<string, string | string[]>;
+
+export interface RouteModule {
+  default?: ComponentType<any>;
+  metadata?: Metadata;
+  generateMetadata?: (props: { params: RouteParams; searchParams: SearchParamsRecord }) => Metadata;
+  /** `"force-dynamic"` marks a route `ƒ Dynamic` even without dynamic segments. */
+  dynamic?: "auto" | "force-static" | "force-dynamic";
+  [key: string]: unknown;
+}
+
+export type LazyRouteModule = () => Promise<RouteModule>;
+export type RouteModuleRef = RouteModule | LazyRouteModule;
+
+export const ROUTE_FILE_KINDS = ["layout", "page", "loading", "error", "not-found"] as const;
+export type RouteFileKind = (typeof ROUTE_FILE_KINDS)[number];
+
+/** One directory of the `app/` tree. */
+export interface RouteSegmentNode {
+  /** Directory name: `""` (root), `"logs"`, `"[id]"`, `"[...slug]"`, `"[[...slug]]"`, `"(group)"`. */
+  segment: string;
+  layout?: RouteModuleRef;
+  page?: RouteModuleRef;
+  loading?: RouteModuleRef;
+  error?: RouteModuleRef;
+  notFound?: RouteModuleRef;
+  /** Source files (project-relative) for DevTools and the build summary. */
+  files?: Partial<Record<RouteFileKind, string>>;
+  children?: RouteSegmentNode[];
+}
+
+export type RouteManifest = RouteSegmentNode;
+
+export type SegmentKind = "static" | "dynamic" | "catchAll" | "optionalCatchAll" | "group";
+
+export interface ParsedSegment {
+  kind: SegmentKind;
+  /** Literal value for static segments, param name for dynamic ones. */
+  name: string;
+}
+
+export function parseSegment(segment: string): ParsedSegment {
+  let m = /^\[\[\.\.\.([^\]]+)\]\]$/.exec(segment);
+  if (m) return { kind: "optionalCatchAll", name: m[1] as string };
+  m = /^\[\.\.\.([^\]]+)\]$/.exec(segment);
+  if (m) return { kind: "catchAll", name: m[1] as string };
+  m = /^\[([^\]]+)\]$/.exec(segment);
+  if (m) return { kind: "dynamic", name: m[1] as string };
+  if (/^\(.+\)$/.test(segment)) return { kind: "group", name: segment };
+  return { kind: "static", name: segment };
+}
+
+const RANK: Record<SegmentKind, number> = { static: 0, group: 1, dynamic: 2, catchAll: 3, optionalCatchAll: 4 };
+
+/** Children ordered by match priority: static > group > [param] > [...slug] > [[...slug]]. */
+export function rankedChildren(node: RouteSegmentNode): RouteSegmentNode[] {
+  const list = node.children ? node.children.slice() : [];
+  return list.sort((a, b) => {
+    const r = RANK[parseSegment(a.segment).kind] - RANK[parseSegment(b.segment).kind];
+    return r !== 0 ? r : a.segment.localeCompare(b.segment);
+  });
+}
+
+export interface RouteMatch {
+  /** Normalized pathname that was matched. */
+  pathname: string;
+  /** Route pattern, e.g. `/deployments/[id]` (`/_not-found` for unmatched paths). */
+  pattern: string;
+  params: RouteParams;
+  /** Segment nodes from the root to the matched leaf. */
+  chain: RouteSegmentNode[];
+  /** `true` when the path did not match a page and the chain ends at the nearest `not-found`. */
+  notFound: boolean;
+  /** `true` for routes with dynamic segments or `dynamic = "force-dynamic"`. */
+  dynamic: boolean;
+}
+
+export function splitPath(pathname: string): string[] {
+  const parts: string[] = [];
+  for (const raw of pathname.split("/")) {
+    if (raw.length === 0) continue;
+    let p = raw;
+    try {
+      p = decodeURIComponent(raw);
+    } catch {
+      // keep the raw segment
+    }
+    parts.push(p);
+  }
+  return parts;
+}
+
+export function normalizePathname(pathname: string): string {
+  const parts = pathname.split("/").filter((p) => p.length > 0);
+  return `/${parts.join("/")}`;
+}
+
+/** Route pattern for a chain of segments (route groups are omitted). */
+export function chainPattern(chain: readonly RouteSegmentNode[]): string {
+  const parts: string[] = [];
+  for (const n of chain) {
+    if (n.segment === "") continue;
+    if (parseSegment(n.segment).kind === "group") continue;
+    parts.push(n.segment);
+  }
+  return `/${parts.join("/")}`;
+}
+
+function matchFrom(node: RouteSegmentNode, parts: readonly string[], i: number, params: RouteParams, chain: RouteSegmentNode[]): RouteSegmentNode[] | null {
+  if (i === parts.length && node.page) return chain;
+  for (const child of rankedChildren(node)) {
+    const seg = parseSegment(child.segment);
+    let next: RouteSegmentNode[] | null = null;
+    switch (seg.kind) {
+      case "static":
+        if (i < parts.length && parts[i] === seg.name) next = matchFrom(child, parts, i + 1, params, [...chain, child]);
+        break;
+      case "group":
+        next = matchFrom(child, parts, i, params, [...chain, child]);
+        break;
+      case "dynamic":
+        if (i < parts.length) {
+          const p = { ...params, [seg.name]: parts[i] as string };
+          next = matchFrom(child, parts, i + 1, p, [...chain, child]);
+          if (next) Object.assign(params, p);
+        }
+        break;
+      case "catchAll":
+      case "optionalCatchAll": {
+        const rest = parts.slice(i);
+        if ((rest.length > 0 || seg.kind === "optionalCatchAll") && child.page) {
+          if (rest.length > 0) params[seg.name] = rest;
+          next = [...chain, child];
+        }
+        break;
+      }
+    }
+    if (next) return next;
+  }
+  return null;
+}
+
+function isForceDynamic(chain: readonly RouteSegmentNode[]): boolean {
+  for (const n of chain) {
+    for (const ref of [n.layout, n.page]) {
+      const mod = peekModule(ref);
+      if (mod?.dynamic === "force-dynamic") return true;
+    }
+  }
+  return false;
+}
+
+export function isDynamicPattern(pattern: string): boolean {
+  return pattern.includes("[");
+}
+
+/** Match a pathname against the manifest. Returns `null` when no page matches. */
+export function matchAppRoutes(manifest: RouteManifest, pathname: string): RouteMatch | null {
+  const parts = splitPath(pathname);
+  const params: RouteParams = {};
+  const chain = matchFrom(manifest, parts, 0, params, [manifest]);
+  if (!chain) return null;
+  const pattern = chainPattern(chain);
+  return {
+    pathname: normalizePathname(pathname),
+    pattern,
+    params,
+    chain,
+    notFound: false,
+    dynamic: isDynamicPattern(pattern) || isForceDynamic(chain),
+  };
+}
+
+/**
+ * Longest chain of segment directories matching a prefix of `pathname`,
+ * truncated at the deepest directory with a `not-found` file (or the root).
+ */
+export function resolveNotFoundChain(manifest: RouteManifest, pathname: string): { chain: RouteSegmentNode[]; params: RouteParams } {
+  const parts = splitPath(pathname);
+  const params: RouteParams = {};
+  let chain: RouteSegmentNode[] = [manifest];
+  let node = manifest;
+  let i = 0;
+  outer: while (i < parts.length) {
+    for (const child of rankedChildren(node)) {
+      const seg = parseSegment(child.segment);
+      if (seg.kind === "static" && parts[i] === seg.name) {
+        chain = [...chain, child];
+        node = child;
+        i++;
+        continue outer;
+      }
+      if (seg.kind === "dynamic") {
+        params[seg.name] = parts[i] as string;
+        chain = [...chain, child];
+        node = child;
+        i++;
+        continue outer;
+      }
+    }
+    break;
+  }
+  let end = 0;
+  for (let k = 0; k < chain.length; k++) if ((chain[k] as RouteSegmentNode).notFound) end = k;
+  return { chain: chain.slice(0, end + 1), params };
+}
+
+/** Match a pathname, falling back to the nearest `not-found` boundary. */
+export function resolveRoute(manifest: RouteManifest, pathname: string): RouteMatch {
+  const match = matchAppRoutes(manifest, pathname);
+  if (match) return match;
+  const { chain, params } = resolveNotFoundChain(manifest, pathname);
+  return {
+    pathname: normalizePathname(pathname),
+    pattern: "/_not-found",
+    params,
+    chain,
+    notFound: true,
+    dynamic: false,
+  };
+}
+
+export interface FlatRoute {
+  pattern: string;
+  dynamic: boolean;
+  /** Project-relative page file, when known. */
+  file?: string;
+  /** Layout files wrapping the page, root first. */
+  layouts: string[];
+}
+
+/** Every page in the manifest, `/` first, then alphabetical. */
+export function flattenRoutes(manifest: RouteManifest): FlatRoute[] {
+  const out: FlatRoute[] = [];
+  const walk = (node: RouteSegmentNode, chain: RouteSegmentNode[]): void => {
+    const next = [...chain, node];
+    if (node.page) {
+      const pattern = chainPattern(next);
+      out.push({
+        pattern,
+        dynamic: isDynamicPattern(pattern) || isForceDynamic(next),
+        file: node.files?.page,
+        layouts: next.map((n) => n.files?.layout).filter((f): f is string => typeof f === "string"),
+      });
+    }
+    for (const c of node.children ?? []) walk(c, next);
+  };
+  walk(manifest, []);
+  return out.sort((a, b) => (a.pattern === "/" ? -1 : b.pattern === "/" ? 1 : a.pattern.localeCompare(b.pattern)));
+}
+
+// ---------------------------------------------------------------------------
+// Modules & metadata
+// ---------------------------------------------------------------------------
+
+const loaded = new WeakMap<LazyRouteModule, RouteModule>();
+
+export function isLazyModule(ref: RouteModuleRef): ref is LazyRouteModule {
+  return typeof ref === "function";
+}
+
+/** The module for `ref` if it is eager or has already loaded. */
+export function peekModule(ref: RouteModuleRef | undefined): RouteModule | undefined {
+  if (ref === undefined) return undefined;
+  return isLazyModule(ref) ? loaded.get(ref) : ref;
+}
+
+export async function loadModule(ref: RouteModuleRef): Promise<RouteModule> {
+  if (!isLazyModule(ref)) return ref;
+  const cached = loaded.get(ref);
+  if (cached) return cached;
+  const mod = await ref();
+  loaded.set(ref, mod);
+  return mod;
+}
+
+export interface ResolvedMetadata {
+  title?: string;
+  description?: string;
+}
+
+function readMetadata(mod: RouteModule | undefined, params: RouteParams, searchParams: SearchParamsRecord): Metadata | undefined {
+  if (!mod) return undefined;
+  if (typeof mod.generateMetadata === "function") {
+    try {
+      return mod.generateMetadata({ params, searchParams });
+    } catch {
+      return mod.metadata;
+    }
+  }
+  return mod.metadata;
+}
+
+/** Merge `metadata` from layouts (root first) and the page, applying `title.template`. */
+export function resolveMetadata(match: RouteMatch, searchParams: SearchParamsRecord = {}): ResolvedMetadata {
+  const out: ResolvedMetadata = {};
+  let template: string | undefined;
+  const leaf = match.chain[match.chain.length - 1];
+  const refs: Array<RouteModuleRef | undefined> = [];
+  for (const n of match.chain) refs.push(n.layout);
+  refs.push(match.notFound ? leaf?.notFound : leaf?.page);
+  for (const ref of refs) {
+    const meta = readMetadata(peekModule(ref), match.params, searchParams);
+    if (!meta) continue;
+    if (typeof meta.description === "string") out.description = meta.description;
+    const t = meta.title;
+    if (t === undefined) continue;
+    if (typeof t === "string") out.title = template ? template.replace("%s", t) : t;
+    else {
+      if (typeof t.absolute === "string") out.title = t.absolute;
+      else if (typeof t.default === "string") out.title = t.default;
+      if (typeof t.template === "string") template = t.template;
+    }
+  }
+  return out;
+}
+
+export function searchParamsToRecord(search: string | URLSearchParams): SearchParamsRecord {
+  const sp = typeof search === "string" ? new URLSearchParams(search) : search;
+  const out: SearchParamsRecord = {};
+  for (const [k, v] of sp) {
+    const prev = out[k];
+    if (prev === undefined) out[k] = v;
+    else out[k] = Array.isArray(prev) ? [...prev, v] : [prev, v];
+  }
+  return out;
+}
+
+/** Format params for display: `{ id: "dpl_1" }`. */
+export function formatParams(params: RouteParams): string {
+  const keys = Object.keys(params);
+  if (keys.length === 0) return "{}";
+  return `{ ${keys.map((k) => `${k}: ${JSON.stringify(params[k])}`).join(", ")} }`;
+}

package/src/server/adapters/build-step.ts

@@ -0,0 +1,135 @@
+/**
+ * The `text build` hooks for middleware, the cache handler and adapters
+ * (kept here so `cli/build.ts` only calls two functions).
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { MiddlewareModule } from "../middleware";
+import { normalizeBasePath, type Rewrite, type TextConfig } from "../../config";
+import { findMiddlewareFile } from "../middleware-node";
+import { compileMatcher } from "../middleware-runtime";
+import type { ApiRoute, AppScan } from "../scan";
+import { toPosix } from "../scan";
+import { bundleServerEntry } from "./bundle";
+import { runAdapter } from "./index";
+import { RUNTIME_BUNDLE, serverRuntimeEntry } from "./runtime-node";
+import { detectAdapter, isAdapterName, type AdapterName, type AdapterResult } from "./shared";
+
+export interface ServerFiles {
+  middlewareFile: string | null;
+  cacheHandlerFile: string | null;
+}
+
+export function serverFiles(root: string, config: TextConfig): ServerFiles {
+  const mw = findMiddlewareFile(root);
+  let cacheHandlerFile: string | null = null;
+  if (config.cacheHandler) {
+    cacheHandlerFile = resolve(root, config.cacheHandler);
+    if (!existsSync(cacheHandlerFile)) throw new Error(`▼ Text.js: cacheHandler ${JSON.stringify(config.cacheHandler)} does not exist.`);
+  }
+  return { middlewareFile: mw ? toPosix(mw) : null, cacheHandlerFile: cacheHandlerFile ? toPosix(cacheHandlerFile) : null };
+}
+
+/** Bundle `.text/server/runtime.mjs` (middleware + cache handler) for `text start`. Returns `true` when written. */
+export async function buildServerRuntime(root: string, config: TextConfig, outDir: string): Promise<boolean> {
+  const files = serverFiles(root, config);
+  if (!files.middlewareFile && !files.cacheHandlerFile) return false;
+  await bundleServerEntry({
+    root,
+    config,
+    code: serverRuntimeEntry(files.middlewareFile, files.cacheHandlerFile),
+    outFile: join(outDir, ".text", "server", RUNTIME_BUNDLE),
+    target: "node",
+  });
+  // Validate the matcher at build time instead of on the first request.
+  const mw = await loadMiddlewareConfig(root, config, outDir);
+  if (mw) compileMatcher(mw.config?.matcher);
+  return true;
+}
+
+const CONFIG_MARK = "\u0000textjs-middleware-config:";
+const EXTRACT_TIMEOUT_MS = 60_000;
+
+/**
+ * `middleware.ts`'s `config` export, read in a short-lived child process: the
+ * build never runs the cache handler, and middleware top-level side effects
+ * (database clients, timers) can't crash or hang it. `null` without middleware.
+ */
+export async function loadMiddlewareConfig(root: string, config: TextConfig, outDir: string): Promise<MiddlewareModule | null> {
+  const { middlewareFile } = serverFiles(root, config);
+  if (!middlewareFile) return null;
+  mkdirSync(join(outDir, ".text"), { recursive: true });
+  const dir = mkdtempSync(join(outDir, ".text", "middleware-config-"));
+  try {
+    const bundle = join(dir, "config.mjs");
+    await bundleServerEntry({
+      root,
+      config,
+      code: `import * as middleware from ${JSON.stringify(middlewareFile)};\nexport const config = middleware.config;`,
+      outFile: bundle,
+      target: "node",
+    });
+    const runner = join(dir, "extract.mjs");
+    writeFileSync(
+      runner,
+      `const m = await import(process.argv[2]);\nprocess.stdout.write(${JSON.stringify(CONFIG_MARK)} + JSON.stringify(m.config ?? null) + "\\n");\nprocess.exit(0);\n`,
+    );
+    const r = spawnSync(process.execPath, [runner, pathToFileURL(bundle).href], { cwd: root, encoding: "utf8", timeout: EXTRACT_TIMEOUT_MS, env: { ...process.env, NODE_ENV: "production" } });
+    const line = (r.stdout ?? "").split("\n").find((l) => l.startsWith(CONFIG_MARK));
+    if (r.error || line === undefined) {
+      const reason = r.error?.message ?? (r.stderr || `exit code ${r.status}`);
+      throw new Error(`▼ Text.js: could not read \`config\` from ${middlewareFile}:\n${reason.trim()}`);
+    }
+    const value = JSON.parse(line.slice(CONFIG_MARK.length)) as MiddlewareModule["config"] | null;
+    return value ? { config: value } : {};
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Resolve `--adapter` (or the environment's default) and validate it. */
+export function resolveAdapter(name: string | undefined, env: Record<string, string | undefined> = process.env): AdapterName | undefined {
+  const value = name ?? env.TEXTJS_ADAPTER ?? detectAdapter(env);
+  if (value === undefined || value === "" || value === "node") return undefined;
+  if (!isAdapterName(value)) throw new Error(`▼ Text.js: unknown adapter ${JSON.stringify(value)}. Use static, bun, vercel or cloudflare.`);
+  return value;
+}
+
+export interface AdapterStep {
+  root: string;
+  config: TextConfig;
+  outDir: string;
+  scan: AppScan;
+  api: ApiRoute[];
+  adapter: AdapterName;
+  print(line?: string): void;
+}
+
+export async function runBuildAdapter(step: AdapterStep): Promise<AdapterResult> {
+  const files = serverFiles(step.root, step.config);
+  const rewrites: Rewrite[] = typeof step.config.rewrites === "function" ? await step.config.rewrites() : (step.config.rewrites ?? []);
+  const middleware = await loadMiddlewareConfig(step.root, step.config, step.outDir);
+  const result = await runAdapter(
+    step.adapter,
+    {
+      root: step.root,
+      outDir: step.outDir,
+      config: step.config,
+      scan: step.scan,
+      api: step.api,
+      basePath: normalizeBasePath(step.config.basePath),
+      rewrites,
+      middlewareFile: files.middlewareFile,
+      cacheHandlerFile: files.cacheHandlerFile,
+      print: step.print,
+    },
+    middleware,
+  );
+  if (step.config.proxy && Object.keys(step.config.proxy).length > 0) {
+    result.notes.push("`proxy` in text.config.ts only runs in `text dev` / `text start` and is not part of adapter output; use rewrites.");
+  }
+  return result;
+}

package/src/server/adapters/bun.ts

@@ -0,0 +1,92 @@
+/**
+ * `text build --adapter bun`: a self-contained `dist/server.js` for
+ * `bun dist/server.js` (static files, middleware, route handlers, SPA document).
+ */
+
+import { join } from "node:path";
+import { bundleServerEntry, frameworkFile } from "./bundle";
+import { serverEntry, type AdapterContext, type AdapterResult } from "./shared";
+
+export const BUN_SERVER_FILE = "server.js";
+
+const BODY = `
+import { existsSync, statSync } from "node:fs";
+import { join, normalize, sep } from "node:path";
+import { loadLiveProduction } from ${JSON.stringify(frameworkFile("server/live-prod.ts"))};
+import { runNodeStyle } from ${JSON.stringify(frameworkFile("server/live-web.ts"))};
+
+const dir = import.meta.dir;
+const self = join(dir, ${JSON.stringify(BUN_SERVER_FILE)});
+
+// Server-rendered routes (\`runtime = "server"\`) and prerendered shells: Bun is a long-lived server, so live sessions run here.
+const live = existsSync(join(dir, ".text", "live-manifest.json"))
+  ? await loadLiveProduction(dir, {
+      middleware: options.middleware,
+      trustProxy: process.env.TRUST_PROXY === "1",
+      origin: process.env.TEXTJS_ORIGIN,
+      onError: (error) => console.error(error),
+    })
+  : null;
+
+function fileResponse(path, immutable) {
+  const file = Bun.file(path);
+  return new Response(file, {
+    headers: {
+      "content-type": file.type,
+      "cache-control": immutable ? "public, max-age=31536000, immutable" : "public, max-age=0, must-revalidate",
+    },
+  });
+}
+
+export const handler = createRequestHandler({
+  ...options,
+  live: live ? (request, url, context) => runNodeStyle(request, url, (req, res) => live.handle(req, res, url), context.clientAddress) : undefined,
+  assets(pathname) {
+    let path = normalize(join(dir, pathname));
+    if ((path !== dir && !path.startsWith(dir + sep)) || path === self) return null;
+    try {
+      // Directories serve their index.html (prerendered console shells).
+      if (statSync(path).isDirectory()) path = join(path, "index.html");
+      if (!statSync(path).isFile()) return null;
+    } catch {
+      return null;
+    }
+    const res = fileResponse(path, pathname.startsWith("/assets/"));
+    if (path.endsWith(".html")) res.headers.set("content-type", "text/html; charset=utf-8");
+    return res;
+  },
+  document() {
+    const res = fileResponse(join(dir, "index.html"), false);
+    res.headers.set("content-type", "text/html; charset=utf-8");
+    return res;
+  },
+});
+
+if (import.meta.main) {
+  const server = Bun.serve({
+    // Live sessions stream server-sent events (15s heartbeats): don't idle them out.
+    idleTimeout: 60,
+    port: Number(process.env.PORT ?? 3000),
+    hostname: process.env.HOSTNAME ?? "0.0.0.0",
+    fetch(request, server) {
+      return handler(request, { clientAddress: server.requestIP(request)?.address }).catch((error) => {
+        console.error(error);
+        return new Response("500 | Internal Server Error", { status: 500 });
+      });
+    },
+  });
+  const stop = () => {
+    live?.close();
+    server.stop();
+    process.exit(0);
+  };
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+  console.log("▼ Text.js ready on http://" + (server.hostname === "0.0.0.0" ? "localhost" : server.hostname) + ":" + server.port + options.basePath);
+}
+`;
+
+export async function adaptBun(ctx: AdapterContext): Promise<AdapterResult> {
+  await bundleServerEntry({ root: ctx.root, config: ctx.config, code: serverEntry(ctx, { body: BODY }), outFile: join(ctx.outDir, BUN_SERVER_FILE), target: "bun" });
+  return { adapter: "bun", output: ctx.outDir, notes: [`Run with: bun ${join(ctx.config.outDir ?? "dist", BUN_SERVER_FILE)}`] };
+}

package/src/server/adapters/bundle.ts

@@ -0,0 +1,97 @@
+/**
+ * Bundle generated server entries (adapter servers, edge middleware,
+ * `text start` runtime) into single self-contained ES modules with Vite.
+ */
+
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { builtinModules } from "node:module";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { build, mergeConfig, type InlineConfig, type Plugin } from "vite";
+import type { TextConfig } from "../../config";
+import { toPosix } from "../scan";
+
+const here = dirname(realpathSync(fileURLToPath(import.meta.url)));
+
+/**
+ * Absolute path of a framework source file (`server/adapters/runtime.ts`),
+ * also when this module runs from `dist/` (the sources ship in `src/`).
+ */
+export function frameworkFile(rel: string): string {
+  const fromHere = join(here, "..", "..", rel);
+  if (existsSync(fromHere)) return toPosix(fromHere);
+  for (let dir = here; dirname(dir) !== dir; dir = dirname(dir)) {
+    const pkgFile = join(dir, "package.json");
+    if (!existsSync(pkgFile)) continue;
+    const pkg = JSON.parse(readFileSync(pkgFile, "utf8")) as { name?: string };
+    if (pkg.name === "@textjs/app" && existsSync(join(dir, "src", rel))) return toPosix(join(dir, "src", rel));
+  }
+  throw new Error(`▼ Text.js: could not locate the framework source file src/${rel}.`);
+}
+
+export type BundleTarget = "node" | "bun" | "webworker" | "edge";
+
+export interface BundleOptions {
+  root: string;
+  config: TextConfig;
+  /** Generated entry module source. */
+  code: string;
+  outFile: string;
+  target: BundleTarget;
+}
+
+const ENTRY = "virtual:textjs/server-entry";
+
+export async function bundleServerEntry(opts: BundleOptions): Promise<void> {
+  const worker = opts.target === "webworker" || opts.target === "edge";
+  const entryPlugin: Plugin = {
+    name: "textjs:server-entry",
+    enforce: "pre",
+    resolveId(id) {
+      return id.endsWith(ENTRY) ? `\0${ENTRY}` : null;
+    },
+    load(id) {
+      return id === `\0${ENTRY}` ? opts.code : null;
+    },
+  };
+  // Workers resolve Node built-ins only by their `node:` names (nodejs_compat); dependencies often import `fs` / `async_hooks`.
+  const builtins: Plugin = {
+    name: "textjs:node-builtins",
+    enforce: "pre",
+    resolveId(id) {
+      if (!worker) return null;
+      if (id.startsWith("node:")) return { id, external: true };
+      return builtinModules.includes(id) && !id.startsWith("_") ? { id: `node:${id}`, external: true } : null;
+    },
+  };
+  const inline: InlineConfig = {
+    configFile: false,
+    root: opts.root,
+    mode: "production",
+    logLevel: "warn",
+    clearScreen: false,
+    publicDir: false,
+    define: worker ? { "process.env.NODE_ENV": JSON.stringify("production") } : undefined,
+    resolve: worker ? { conditions: ["workerd", "worker", "edge-light", "browser", "import", "module", "default"] } : undefined,
+    ssr: {
+      target: worker ? "webworker" : "node",
+      noExternal: true,
+      ...(worker ? { resolve: { conditions: ["workerd", "worker", "edge-light", "import", "module", "default"], externalConditions: ["workerd", "worker"] } } : {}),
+    },
+    build: {
+      ssr: ENTRY,
+      outDir: dirname(opts.outFile),
+      emptyOutDir: false,
+      copyPublicDir: false,
+      target: worker ? "es2022" : "node18",
+      minify: false,
+      reportCompressedSize: false,
+      rollupOptions: {
+        external: worker ? [/^node:/] : undefined,
+        output: { entryFileNames: basename(opts.outFile), format: "es", inlineDynamicImports: true },
+      },
+    },
+    plugins: [entryPlugin, builtins],
+  };
+  await build(opts.config.vite ? mergeConfig(inline, opts.config.vite) : inline);
+}