@opentf/web-cli 1.1.0 → 1.3.0

package/README.md

@@ -39,7 +39,10 @@ otfw serve          # build, then server-render each route per request (SSR)
   Picks port 3000 (scanning upward), or `--port` for an explicit one. Phase 1: the page
   becomes interactive via the client bundle (CSR mount); hydration is a later phase.
 
-`OTFWC_BIN` overrides the compiler binary location (used for compiler development).
+`OTFWC_BIN` overrides the compiler binary location. Published installs under
+`node_modules` use the packaged compiler, even when the app lives inside a Cargo
+workspace; this repository's own source checkout may build and use
+`target/debug/otfwc` for compiler development.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentf/web-cli",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "OTF Web dev toolchain — the Rolldown-driven CSR dev server, production build, and SSG.",
   "type": "module",
   "bin": {
@@ -11,7 +11,7 @@
   },
   "scripts": {
     "test": "bun test tests/",
-    "test:e2e": "bun tests/e2e/serve.mjs && bun tests/e2e/hydrate-browser.mjs"
+    "test:e2e": "bun tests/e2e/serve.mjs && bun tests/e2e/build-data.mjs && bun tests/e2e/hydrate-browser.mjs"
   },
   "files": [
     "src"

package/src/build.js

@@ -14,13 +14,19 @@ import {
   writeFileSync,
 } from "node:fs";
 import { basename, join } from "node:path";
+import { pathToFileURL } from "node:url";
 
 import { compileCss, usesTailwind } from "./tailwind.js";
 import {
   EXTENSIONS,
+  assertNoRouteConflicts,
   cssPlugin,
+  discoverLoaders,
   discoverPages,
+  emitApiBundle,
+  emitLoaderBundle,
   entrySource,
+  loaderRoutePath,
   injectBeforeBody,
   loadConfig,
   loadDocsPlugins,
@@ -29,6 +35,7 @@ import {
   readHtmlShell,
   runBlogFeed,
   runDocsSearchIndex,
+  runLlmsFiles,
   runLastUpdated,
   stampHydrateSentinel,
 } from "./shared.js";
@@ -36,17 +43,37 @@ import { fmtMs, step } from "./reporter.js";
 
 const hash = (s) => Bun.hash(s).toString(16).padStart(16, "0").slice(0, 8);
 
-// Site origin for absolute canonical / sitemap URLs. Priority: `--base-url=` flag,
-// then `otfw.config` (`{ site: { url } }`), else "" (relative canonicals, sitemap
-// skipped with a warning).
-function resolveBaseUrl(config) {
-  const flag = process.argv.find((a) => a.startsWith("--base-url="));
+// Site origin for absolute canonical / sitemap/feed URLs. Priority: `--base-url=`
+// flag, then `otfw.config` (`{ site: { url } }`).
+export function resolveBaseUrl(config, argv = process.argv) {
+  const flag = argv.find((a) => a.startsWith("--base-url="));
   if (flag) return flag.slice("--base-url=".length).replace(/\/+$/, "");
   if (config?.site?.url) return String(config.site.url).replace(/\/+$/, "");
   return "";
 }
 
+export function buildRequiresBaseUrl(config, argv = process.argv) {
+  return argv.includes("--ssg") || !!config?.docs || !!config?.blog;
+}
+
+function requireBaseUrl(config, argv = process.argv) {
+  const baseUrl = resolveBaseUrl(config, argv);
+  if (baseUrl || !buildRequiresBaseUrl(config, argv)) return baseUrl;
+  console.error(
+    `✗ site.url is required for this production build.\n` +
+      `  Add it to otfw.config.js:\n\n` +
+      `  export default defineDocsConfig({\n` +
+      `    site: { url: "https://example.com" }\n` +
+      `  })\n\n` +
+      `  Or pass --base-url=https://example.com`,
+  );
+  process.exit(1);
+}
+
 export async function runBuild(options = {}) {
+  const projectRoot = process.cwd();
+  const config = await loadConfig(projectRoot);
+  const baseUrl = requireBaseUrl(config);
   const { root, appDir, webEntry, otfwc, exclude } = loadProject();
   const t0 = performance.now();
 
@@ -55,6 +82,7 @@ export async function runBuild(options = {}) {
     console.error(`✗ no page.jsx files found under ${appDir}`);
     process.exit(1);
   }
+  assertNoRouteConflicts(appDir, exclude);
 
   // Build the client for hydration when there will be server markup to adopt — the
   // SSR server (`runBuild({ hydrate: true })`) and `--ssg` pre-rendered pages. A
@@ -63,7 +91,6 @@ export async function runBuild(options = {}) {
 
   // Docs generator: resolve `@opentf/web-docs/nav` to the build-time nav tree when
   // the project has a `docs` config block.
-  const config = await loadConfig(root);
   const docsPlugins = await loadDocsPlugins(root, appDir, config, exclude);
 
   const outDir = join(root, "dist");
@@ -74,7 +101,9 @@ export async function runBuild(options = {}) {
   const tmp = join(root, ".otfw");
   mkdirSync(tmp, { recursive: true });
   const entry = join(tmp, "entry.js");
-  writeFileSync(entry, entrySource(pages, appDir, undefined, config?.i18n, config?.nav));
+  const loaderFiles = discoverLoaders(appDir, exclude);
+  const loaderRoutes = loaderFiles.map((f) => loaderRoutePath(f, appDir));
+  writeFileSync(entry, entrySource(pages, appDir, undefined, config?.i18n, config?.nav, loaderRoutes));
 
   console.log("\n  OTF Web — production build\n");
 
@@ -141,11 +170,28 @@ export async function runBuild(options = {}) {
   const chunks = result.output.filter((o) => o.type === "chunk").length;
   buildStep.done(`Compiled ${pages.length} routes · bundled ${chunks} chunks`);
 
+  // Route loaders (docs/DATA.md): emit the server bundle to dist/server/loaders.js
+  // — `otfw serve` imports it per request, and the SSG pre-render below runs it at
+  // build time (so this must precede the SSG step).
+  let loaders = null;
+  if (loaderFiles.length > 0) {
+    const loaderStep = step("Bundling route loaders");
+    await emitLoaderBundle({
+      root,
+      appDir,
+      webEntry,
+      exclude,
+      i18n: config?.i18n,
+      outDir: join(outDir, "server"),
+    });
+    loaders = (await import(pathToFileURL(join(outDir, "server", "loaders.js")).href)).loaders;
+    loaderStep.done(`Route loaders — ${loaderFiles.length} → dist/server/loaders.js`);
+  }
+
   // SSG: pre-render each route into static HTML using the shell we just composed
   // (so per-route files carry the same bundle + stylesheet links).
   let ssg = null;
   if (process.argv.includes("--ssg")) {
-    const baseUrl = resolveBaseUrl(config);
     const { runPrerender } = await import("./prerender.js");
     // Per-page last-updated map (git/frontmatter) for the article:modified_time tag.
     const lastUpdated = await runLastUpdated(root, appDir, config, exclude);
@@ -162,6 +208,7 @@ export async function runBuild(options = {}) {
       docsPlugins,
       lastUpdated,
       i18n: config?.i18n,
+      loaders,
       onCompile: (id) => ssgStep.update(`compiling ${basename(id)}  (${++ssgCompiled})`),
       onRender: (done, total) => ssgStep.update(`rendering ${done}/${total}`),
     });
@@ -171,6 +218,12 @@ export async function runBuild(options = {}) {
     );
   }
 
+  // API routes (SPEC §11/§13): emit the server handler bundle to dist/server/api.js
+  // so a deploy adapter (Bun/Node/CF Workers) can serve /api/* in production.
+  const apiStep = step("Bundling API routes");
+  const api = await emitApiBundle({ root, appDir, webEntry, exclude, outDir: join(outDir, "server") });
+  apiStep.done(api ? `API routes — ${api.routes.length} → dist/server/api.js` : "API routes — none");
+
   // Copy the public/ directory (static assets served at the root), if present.
   const publicDir = join(root, "public");
   if (existsSync(publicDir)) cpSync(publicDir, outDir, { recursive: true });
@@ -185,13 +238,20 @@ export async function runBuild(options = {}) {
     searchStep.done(`Search index — ${search?.pages ?? 0} page(s)`);
   }
 
-  // Blog RSS feed (when a `blog` block + site URL are configured). Written after the
-  // public/ copy so a project-supplied feed override isn't clobbered.
+  // Blog RSS + Atom feeds (when a `blog` block is configured). Written
+  // after the public/ copy so project-supplied feed overrides aren't clobbered.
   if (config?.blog) {
-    const feedStep = step("Generating RSS feed");
-    const feed = await runBlogFeed(root, appDir, config, outDir, resolveBaseUrl(config), exclude);
-    if (feed) feedStep.done(`RSS feed — ${feed.count} post(s) → ${feed.path}`);
-    else feedStep.done("RSS feed — skipped");
+    const feedStep = step("Generating blog feeds");
+    const feed = await runBlogFeed(root, appDir, config, outDir, baseUrl, exclude);
+    if (feed) feedStep.done(`Blog feeds — ${feed.count} post(s) → ${feed.paths.join(", ")}`);
+    else feedStep.done("Blog feeds — skipped");
+  }
+
+  if (config?.docs || config?.blog) {
+    const llmsStep = step("Generating LLM context");
+    const llms = await runLlmsFiles(root, appDir, pages, config, outDir, baseUrl);
+    if (llms) llmsStep.done(`LLM context — ${llms.paths.join(", ")}`);
+    else llmsStep.done("LLM context — skipped");
   }
 
   console.log(`\n  → dist/  ready in ${fmtMs(performance.now() - t0)}\n`);

package/src/dev.js

@@ -18,16 +18,23 @@
 
 import { rolldown } from "rolldown";
 import { existsSync, mkdirSync, readFileSync, statSync, watch, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
 
 import { compileCss, usesTailwind } from "./tailwind.js";
 import { overlayClient } from "./overlay.js";
 import {
   EXTENSIONS,
   MIME,
+  assertNoRouteConflicts,
+  buildApiBundle,
+  buildLoaderBundle,
   cssPlugin,
+  discoverApiRoutes,
+  discoverLoaders,
   discoverPages,
   entrySource,
+  loaderRoutePath,
   injectBeforeBody,
   loadConfig,
   loadDocsPlugins,
@@ -97,6 +104,7 @@ export async function runDev() {
     console.error(`✗ no page.jsx files found under ${appDir}`);
     process.exit(1);
   }
+  assertNoRouteConflicts(appDir, exclude);
 
   const config = await loadConfig(root);
   const docsPlugins = await loadDocsPlugins(root, appDir, config, exclude);
@@ -104,7 +112,10 @@ export async function runDev() {
   const devDir = join(root, ".dev");
   mkdirSync(devDir, { recursive: true });
   const entryFile = join(devDir, "entry.js");
-  writeFileSync(entryFile, entrySource(pages, appDir, toRouteUrl, config?.i18n, config?.nav));
+  const loaderRoutes = () => discoverLoaders(appDir, exclude).map((f) => loaderRoutePath(f, appDir));
+  const writeEntry = () =>
+    writeFileSync(entryFile, entrySource(pages, appDir, toRouteUrl, config?.i18n, config?.nav, loaderRoutes()));
+  writeEntry();
 
   let server;
   const publish = (msg) => server?.publish("hmr", JSON.stringify(msg));
@@ -184,6 +195,88 @@ export async function runDev() {
     return routeCache.get(file);
   }
 
+  // API routes (SPEC §11) are plain server modules under app/api/. In dev they're
+  // built lazily on the first /api/* request and rebuilt after an edit (the watcher
+  // clears the cache). `bust` busts the ESM import cache so edits take effect.
+  let apiBundle = null;
+  let apiBuilt = false;
+  let apiVersion = 0;
+  async function getApi() {
+    if (!apiBuilt) {
+      try {
+        apiBundle = await buildApiBundle({ root, appDir, webEntry, exclude, bust: ++apiVersion });
+      } catch (e) {
+        console.error(`✗ API build failed: ${e?.message ?? e}`);
+        apiBundle = await brokenApiStub(e);
+      }
+      apiBuilt = true;
+    }
+    return apiBundle;
+  }
+  // A failed API build must not silently serve the SPA shell for endpoint URLs:
+  // stand in with a handler that 500s exactly the discovered endpoints (real
+  // matching semantics via createApiHandler) until the next successful rebuild.
+  async function brokenApiStub(err) {
+    try {
+      const serverApi = pathToFileURL(join(dirname(webEntry), "server", "index.js")).href;
+      const { createApiHandler } = await import(serverApi);
+      // Strip ANSI color codes — the bundler's terminal diagnostic goes into JSON here.
+      const msg = String(err?.message ?? err).replace(/\u001b\[[0-9;]*m/g, "");
+      const fail = () => Response.json({ error: `API routes failed to build: ${msg}` }, { status: 500 });
+      const stub = Object.fromEntries(
+        ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"].map((m) => [m, fail]),
+      );
+      const { routes } = discoverApiRoutes(appDir, exclude);
+      return {
+        handler: createApiHandler(Object.fromEntries(routes.map((f) => [f, stub])), {}, { appDir }),
+        routes,
+        cleanup: () => {},
+      };
+    } catch {
+      return null;
+    }
+  }
+  function invalidateApi() {
+    try {
+      apiBundle?.cleanup();
+    } catch {}
+    apiBundle = null;
+    apiBuilt = false;
+  }
+
+  // Route loaders (docs/DATA.md) are plain server modules like API routes, and get
+  // the same treatment: built lazily on the first `__data.json` request, rebuilt
+  // after an edit (the watcher clears the cache), ESM cache busted per rebuild.
+  let loaderBundle = null;
+  let loadersBuilt = false;
+  let loaderVersion = 0;
+  async function getLoaders() {
+    if (!loadersBuilt) {
+      try {
+        loaderBundle = await buildLoaderBundle({
+          root,
+          appDir,
+          webEntry,
+          exclude,
+          i18n: config?.i18n,
+          bust: ++loaderVersion,
+        });
+      } catch (e) {
+        console.error(`✗ loader build failed: ${e?.message ?? e}`);
+        loaderBundle = null;
+      }
+      loadersBuilt = true;
+    }
+    return loaderBundle;
+  }
+  function invalidateLoaders() {
+    try {
+      loaderBundle?.cleanup();
+    } catch {}
+    loaderBundle = null;
+    loadersBuilt = false;
+  }
+
   // The module graph powers precise invalidation; build it in the background so it
   // never blocks startup. Until it's ready, a change clears every cache (safe).
   let graph = { has: () => false, affected: () => new Set() };
@@ -217,12 +310,30 @@ export async function runDev() {
   const watcher = watch(appDir, { recursive: true }, (_evt, name) => {
     if (!name) return;
     const file = join(appDir, name);
+    // An API endpoint/middleware edit (any `route.*` / `_middleware.*` file) rebuilds
+    // the API bundle on the next request and triggers a reload.
+    if (/^(route|_middleware)\.(jsx?|tsx?)$/.test(name.split("/").pop())) {
+      invalidateApi();
+      publish({ type: "reload" });
+      return;
+    }
+    // A loader edit rebuilds the loader bundle on the next data request; a new or
+    // deleted loader.* also changes the route set baked into the entry, so the
+    // entry is rewritten and its cached chunk dropped (a stale set would make SPA
+    // nav skip the fetch — or fetch a 404).
+    if (/^loader\.(js|ts)$/.test(name.split("/").pop())) {
+      invalidateLoaders();
+      writeEntry();
+      entryCode = null;
+      publish({ type: "reload" });
+      return;
+    }
     if (/\.(mdx|md|[jt]sx|css)$/.test(name)) {
       if (/^(page|layout|404)\.(mdx|md|[jt]sx)$/.test(name.split("/").pop()) && !pages.includes(file)) {
         const fresh = discoverPages(appDir, exclude);
         pages.length = 0;
         pages.push(...fresh);
-        writeFileSync(entryFile, entrySource(pages, appDir, toRouteUrl, config?.i18n, config?.nav));
+        writeEntry();
       }
       onChange(file);
     }
@@ -234,6 +345,8 @@ export async function runDev() {
     try {
       watcher.close();
     } catch {}
+    invalidateApi();
+    invalidateLoaders();
     process.exit(0);
   };
   process.once("SIGINT", shutdown);
@@ -242,6 +355,8 @@ export async function runDev() {
     try {
       watcher.close();
     } catch {}
+    invalidateApi();
+    invalidateLoaders();
   });
 
   // Import map (so `@opentf/web` resolves to the shared runtime chunk) + entry + the
@@ -303,6 +418,29 @@ export async function runDev() {
       if (pathname.startsWith(ROUTE_PREFIX) && pathname.endsWith(".js")) {
         return js(await serveRoute(fromRouteUrl(pathname)));
       }
+      // API endpoints (route.* files, at any path — SPEC §11): a matched handler's
+      // Response wins; a miss falls through to static assets / the SPA shell, so pages
+      // and endpoints coexist. `getApi()` is O(1) after the first build (or a no-op
+      // when the app has no route.* files).
+      {
+        const api = await getApi();
+        const res = api ? await api.handler(req) : null;
+        if (res) return res;
+      }
+      // The route-loader data endpoint (docs/DATA.md): `<path>/__data.json` is a
+      // reserved suffix — answered here (SPA navigation fetches it) and never
+      // allowed to fall through to assets or the SPA shell, so a miss is a 404.
+      if (pathname === "/__data.json" || pathname.endsWith("/__data.json")) {
+        try {
+          const bundle = await getLoaders();
+          const res = bundle ? await bundle.loaders.handle(req) : null;
+          if (res) return res;
+        } catch (e) {
+          console.error(`✗ loader failed for ${pathname}: ${e?.message ?? e}`);
+          return Response.json({ error: "Internal Server Error" }, { status: 500 });
+        }
+        return Response.json(null, { status: 404 });
+      }
       if (pathname !== "/") {
         const asset = await serveStatic(pathname);
         if (asset) return asset;

package/src/prerender.js

@@ -6,7 +6,15 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
-import { buildServerBundle, injectHead, injectMarkup, withHtmlLang } from "./shared.js";
+import {
+  DATA_FILE,
+  buildServerBundle,
+  injectHead,
+  injectHydrationData,
+  injectMarkup,
+  injectRouteData,
+  withHtmlLang,
+} from "./shared.js";
 
 // "/" → dist/index.html, "/post/1" → dist/post/1/index.html, "/fr/about" → dist/fr/about/index.html.
 function htmlPathFor(outDir, route) {
@@ -75,7 +83,7 @@ function escapeXml(s) {
  * Pre-render the app to static HTML files under `outDir`. Returns
  * `{ count, skipped, failed }`.
  */
-export async function runPrerender({ root, pages, webEntry, otfwc, shellHtml, outDir, baseUrl = "", docsPlugins = [], lastUpdated = {}, i18n = null, onCompile, onRender }) {
+export async function runPrerender({ root, pages, webEntry, otfwc, shellHtml, outDir, baseUrl = "", docsPlugins = [], lastUpdated = {}, i18n = null, loaders = null, onCompile, onRender }) {
   const { mod, cleanup } = await buildServerBundle({ root, pages, webEntry, otfwc, docsPlugins, i18n, onCompile });
 
   // i18n (docs/I18N.md §6): pre-render each route once per locale. The default
@@ -95,9 +103,20 @@ export async function runPrerender({ root, pages, webEntry, otfwc, shellHtml, ou
     for (const locale of locales) {
       const urlPath = localizeFor(path, locale, defaultLocale);
       try {
+        // Route loader (docs/DATA.md): run it at build time with no `request` and
+        // an empty query (a query-dependent loader needs `otfw serve`). The result
+        // is threaded into the render (`router.data`), inlined into the HTML, and
+        // written as a sibling `__data.json` — per locale, since a localized
+        // loader can return locale-dependent data.
+        const m = loaders?.match(urlPath);
+        let data;
+        let dataJson = "";
+        if (m) ({ data, json: dataJson } = await loaders.loadSerialized(m, { query: {} }));
+
         // Passing the localized URL pins router.locale (resolveLocale) and still
         // matches the locale-agnostic route table, so `t()` renders in `locale`.
-        const { html, metadata } = (await mod.renderRoute(urlPath, params)) ?? { html: "", metadata: {} };
+        const { html, metadata, hydration } =
+          (await mod.renderRoute(urlPath, params, "", { data })) ?? { html: "", metadata: {}, hydration: "" };
         const meta = i18nOn
           ? { ...metadata, links: [...(metadata.links || []), ...alternatesFor(path, locales, defaultLocale)] }
           : metadata;
@@ -108,11 +127,30 @@ export async function runPrerender({ root, pages, webEntry, otfwc, shellHtml, ou
         if (iso) head += `\n<meta property="article:modified_time" content="${escapeXml(iso)}">`;
         const file = htmlPathFor(outDir, urlPath);
         mkdirSync(dirname(file), { recursive: true });
-        writeFileSync(file, injectMarkup(injectHead(withHtmlLang(shellHtml, locale), head), html));
+        writeFileSync(
+          file,
+          injectRouteData(
+            injectHydrationData(
+              injectMarkup(injectHead(withHtmlLang(shellHtml, locale), head), html),
+              hydration,
+            ),
+            dataJson,
+          ),
+        );
+        if (m) {
+          // The static data file SPA navigation fetches on a plain static host —
+          // byte-identical to the inline payload ("null" when the loader returned
+          // undefined, so a 200 still parses as JSON).
+          const dataFile =
+            urlPath === "/" ? join(outDir, DATA_FILE) : join(outDir, urlPath, DATA_FILE);
+          mkdirSync(dirname(dataFile), { recursive: true });
+          writeFileSync(dataFile, dataJson || "null");
+        }
         rendered.push(urlPath);
       } catch (e) {
         failed.push(urlPath);
-        console.error(`✗ pre-render failed for ${urlPath}: ${e?.message ?? e}`);
+        const why = e?.otfwNotFound ? "loader called notFound()" : (e?.message ?? e);
+        console.error(`✗ pre-render failed for ${urlPath}: ${why}`);
       }
     }
   }
@@ -123,7 +161,10 @@ export async function runPrerender({ root, pages, webEntry, otfwc, shellHtml, ou
     const result = await mod.renderRoute("/__otfw_404__");
     if (result) {
       const head = mod.renderHead({ robots: "noindex", ...result.metadata }, { baseUrl });
-      writeFileSync(join(outDir, "404.html"), injectMarkup(injectHead(shellHtml, head), result.html));
+      writeFileSync(
+        join(outDir, "404.html"),
+        injectHydrationData(injectMarkup(injectHead(shellHtml, head), result.html), result.hydration),
+      );
     }
   } catch {
     /* no 404 page */

package/src/serve.js

@@ -16,24 +16,28 @@
 //   • anything else → SSR: render the route's markup + <head>, inject into the
 //     shell, return text/html.
 //
-// Hydration (Phase 2.0): the client build is the hydrate target and the shell's
-// `#app` carries the `data-otfw-hydrate` sentinel, so the client *adopts* the
-// server-rendered DOM on first paint (no rebuild/flash) for leaf routes that the
-// hydrate backend can emit an adopt factory for; anything it can't (layout chains,
-// child components, lists/conditionals — see docs/HYDRATION.md §4) falls back to a
-// clean CSR mount. The per-request HTML is real either way (first paint, dynamic
-// content, SEO).
+// Hydration (Phase 2, complete — docs/HYDRATION.md §4): the client build is the
+// hydrate target and the shell's `#app` carries the `data-otfw-hydrate` sentinel,
+// so the client *adopts* the server-rendered DOM on first paint (no rebuild/flash)
+// — pages, layout chains, keyed lists, conditionals, and component islands with
+// rich props (2.0/2.5/2.1a–d). A route the adopt walk can't handle falls back to
+// a clean CSR mount per component. The per-request HTML is real either way (first
+// paint, dynamic content, SEO).
 
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { pathToFileURL } from "node:url";
 
 import { runBuild } from "./build.js";
 import {
   MIME,
   buildServerBundle,
+  discoverApiRoutes,
   discoverPages,
   injectHead,
+  injectHydrationData,
   injectMarkup,
+  injectRouteData,
   loadConfig,
   loadDocsPlugins,
   loadProject,
@@ -149,19 +153,37 @@ export async function runServe() {
 
   const { mod, cleanup } = await buildServerBundle({ root, pages, webEntry, otfwc, docsPlugins, i18n });
 
-  const shutdown = () => {
+  // API routes (SPEC §11): the client build already emitted the handler bundle to
+  // dist/server/api.js (build.js `emitApiBundle`). Import it and hold it live;
+  // `apiHandler(req)` returns a Response or null (no route matched).
+  const apiFile = join(distDir, "server", "api.js");
+  let api = null;
+  if (existsSync(apiFile)) {
+    const apiMod = await import(pathToFileURL(apiFile).href);
+    api = { handler: apiMod.apiHandler, routes: discoverApiRoutes(appDir, exclude).routes };
+  }
+
+  // Route loaders (docs/DATA.md): the client build emitted the registry bundle to
+  // dist/server/loaders.js (build.js `emitLoaderBundle`). Import it and hold it
+  // live; per request it runs the matched page's loader (threaded into the render
+  // as `router.data`) and answers the `<path>/__data.json` endpoint.
+  const loadersFile = join(distDir, "server", "loaders.js");
+  const loaders = existsSync(loadersFile)
+    ? (await import(pathToFileURL(loadersFile).href)).loaders
+    : null;
+
+  const cleanupAll = () => {
     try {
       cleanup();
     } catch {}
+  };
+  const shutdown = () => {
+    cleanupAll();
     process.exit(0);
   };
   process.once("SIGINT", shutdown);
   process.once("SIGTERM", shutdown);
-  process.once("exit", () => {
-    try {
-      cleanup();
-    } catch {}
-  });
+  process.once("exit", cleanupAll);
 
   // Serve a built asset from dist/ (only regular files; a directory path falls
   // through to SSR). `dist/` already contains hashed assets, copied public/ files,
@@ -176,20 +198,46 @@ export async function runServe() {
     });
   }
 
-  // SSR one navigation: render the route's markup + <head>, inject into the shell.
-  async function render(url) {
-    const result = await mod.renderRoute(url.pathname, null, url.search);
-    if (!result) {
-      const notFound = join(distDir, "404.html");
-      const body = existsSync(notFound) ? readFileSync(notFound) : "<h1>404 — Not Found</h1>";
-      return new Response(body, { status: 404, headers: { "content-type": "text/html" } });
+  // The 404 response: the pre-built dist/404.html when present, else a bare body.
+  function renderNotFound() {
+    const notFound = join(distDir, "404.html");
+    const body = existsSync(notFound) ? readFileSync(notFound) : "<h1>404 — Not Found</h1>";
+    return new Response(body, { status: 404, headers: { "content-type": "text/html" } });
+  }
+
+  // SSR one navigation: run the route's loader (if any), render the markup +
+  // <head>, inject into the shell.
+  async function render(url, req) {
+    // Loader first — `notFound()` must resolve before anything renders. The check
+    // is a property (`otfwNotFound`), not instanceof: the loader bundle is its own
+    // module graph. On notFound, re-render as the unmatched sentinel path so the
+    // registered 404 page is served with HTTP 404 (same as a route miss). Any
+    // other loader throw propagates to the 500 branch in `fetch`.
+    let data;
+    let dataJson = "";
+    const m = loaders?.match(url.pathname);
+    if (m) {
+      try {
+        ({ data, json: dataJson } = await loaders.loadSerialized(m, {
+          request: req,
+          query: Object.fromEntries(url.searchParams),
+        }));
+      } catch (e) {
+        if (e?.otfwNotFound === true) return render(new URL("/__otfw_404__", url), req);
+        throw e;
+      }
     }
+    const result = await mod.renderRoute(url.pathname, null, url.search, { data });
+    if (!result) return renderNotFound();
     const meta = i18nOn
       ? { ...result.metadata, links: [...(result.metadata.links || []), ...alternatesFor(stripLocale(url.pathname))] }
       : result.metadata;
     const head = mod.renderHead(meta, { path: url.pathname, baseUrl });
     const localizedShell = i18nOn ? withHtmlLang(shell, localeOf(url.pathname)) : shell;
-    const html = injectMarkup(injectHead(localizedShell, head), result.html);
+    const html = injectRouteData(
+      injectHydrationData(injectMarkup(injectHead(localizedShell, head), result.html), result.hydration),
+      dataJson,
+    );
     // 200 for a real route; 404 when the path fell back to the registered 404 page.
     return new Response(html, {
       status: result.status ?? 200,
@@ -200,6 +248,22 @@ export async function runServe() {
   const server = serve(startPort, explicitPort, {
     async fetch(req) {
       const url = new URL(req.url);
+      // API endpoints (route.* files, at any path — SPEC §11) are checked first —
+      // before the asset branch, matching `otfw dev` — so an endpoint path with a
+      // dotted segment (`/api/v1.0`) still resolves. A matched handler's Response
+      // wins; a miss falls through to assets / SSR, so pages and endpoints coexist.
+      if (api) {
+        const res = await api.handler(req);
+        if (res) return res;
+      }
+      // The route-loader data endpoint (docs/DATA.md): `<path>/__data.json` is a
+      // reserved suffix, answered before the asset branch below would swallow it
+      // (it has a file extension) and never falling through to SSR (a catch-all
+      // page would happily match the suffix as a path segment) — a miss is a 404.
+      if (url.pathname === "/__data.json" || url.pathname.endsWith("/__data.json")) {
+        const res = loaders ? await loaders.handle(req) : null;
+        return res ?? Response.json(null, { status: 404 });
+      }
       // A path with a file extension is an asset request; serve it from dist/. A
       // miss on a real asset is a 404 (don't fall through to the SSR shell).
       if (/\.[a-z0-9]+$/i.test(url.pathname) && url.pathname !== "/") {
@@ -217,7 +281,7 @@ export async function runServe() {
         }
       }
       try {
-        return await render(url);
+        return await render(url, req);
       } catch (e) {
         console.error(`✗ SSR failed for ${url.pathname}: ${e?.message ?? e}`);
         return new Response(`<pre>SSR error: ${e?.message ?? e}</pre>`, {
@@ -229,6 +293,8 @@ export async function runServe() {
   });
 
   console.log(`\n  OTF Web SSR server`);
-  console.log(`  → http://localhost:${server.port}  (${pages.length} routes, server-rendered)`);
+  const apiNote = api ? `, ${api.routes.length} API routes` : "";
+  const loaderNote = loaders ? `, ${loaders.routes.length} loaders` : "";
+  console.log(`  → http://localhost:${server.port}  (${pages.length} routes, server-rendered${apiNote}${loaderNote})`);
   console.log(`  ✓ ready in ${Date.now() - bootStart}ms\n`);
 }

package/src/shared.js

@@ -59,6 +59,37 @@ export function injectMarkup(shellHtml, markup) {
   return shellHtml.replace(/(<div id="app"[^>]*>)\s*(<\/div>)/, (_m, open, close) => `${open}${markup}${close}`);
 }
 
+/**
+ * Embed the island hydration payload (`renderRoute().hydration`) as a
+ * `<script type="application/json" id="__otfw_h">` the client reads at upgrade so
+ * components resume from rich JS props (compiler-driven data hydration). Placed before
+ * `</body>`; a deferred module bundle runs after parse, so the payload is always in the
+ * DOM first. `json` is already `<`-escaped by the server collector, so it can't break out
+ * of the script. No-op for an empty payload. Uses a function replacer so `$` in the JSON
+ * stays literal.
+ */
+export function injectHydrationData(shellHtml, json) {
+  if (!json) return shellHtml;
+  return injectBeforeBody(shellHtml, `<script type="application/json" id="__otfw_h">${json}</script>`);
+}
+
+/** The reserved per-route data filename/URL suffix (mirrors the runtime's
+ *  `DATA_FILE` in `@opentf/web` runtime/route-data.js). */
+export const DATA_FILE = "__data.json";
+
+/**
+ * Embed a route loader's data (docs/DATA.md) as a `<script type="application/json"
+ * id="__otfw_data">` the client router reads on first paint (instead of fetching
+ * `<path>/__data.json`). A separate script from the island payload above — the two
+ * channels have independent shapes and readers. `json` comes `<`-escaped from
+ * `serializeRouteData`; no-op for an empty payload (route without a loader, or an
+ * undefined loader result).
+ */
+export function injectRouteData(shellHtml, json) {
+  if (!json) return shellHtml;
+  return injectBeforeBody(shellHtml, `<script type="application/json" id="__otfw_data">${json}</script>`);
+}
+
 /**
  * Stamp the `data-otfw-hydrate` sentinel onto the shell's `#app` container, telling
  * the client to *adopt* the server-rendered DOM on first paint instead of rebuilding
@@ -105,10 +136,45 @@ export function findUp(name, from) {
   }
 }
 
+function hasLocalCompilerWorkspace(workspace) {
+  return !!workspace && existsSync(join(workspace, "crates", "otfw_cli", "Cargo.toml"));
+}
+
+export function resolveCompiler({
+  cliDir = dirname(fileURLToPath(import.meta.url)),
+  env = process.env,
+  resolvePackagedCompiler = otfwcPath,
+  findWorkspace = findUp,
+  ensure = ensureCompiler,
+} = {}) {
+  if (env.OTFWC_BIN) return { otfwc: env.OTFWC_BIN, workspace: null };
+
+  let packagedError = null;
+  try {
+    return { otfwc: resolvePackagedCompiler(), workspace: null };
+  } catch (e) {
+    packagedError = e;
+  }
+
+  const installedPackage = cliDir.split(/[\\/]/).includes("node_modules");
+  const workspace = installedPackage ? null : findWorkspace("Cargo.toml", cliDir);
+  if (hasLocalCompilerWorkspace(workspace)) {
+    const otfwc = join(workspace, "target", "debug", "otfwc");
+    ensure(otfwc, workspace);
+    return { otfwc, workspace };
+  }
+
+  fail(
+    `${packagedError?.message ?? "cannot resolve @opentf/web-compiler prebuilt binary"}\n` +
+      `  No local otfwc compiler workspace was found to build from source.`,
+  );
+}
+
 /**
  * Resolve the project and toolchain: the app being built (cwd), the runtime
  * package, the `otfwc` compiler, and the excluded routes. Exits with a clear
- * message on any hard failure. Builds the compiler on demand from the workspace.
+ * message on any hard failure. Source checkouts can build the compiler on demand
+ * from this repo's Cargo workspace; published installs use @opentf/web-compiler.
  */
 export function loadProject() {
   const root = process.cwd();
@@ -129,25 +195,9 @@ export function loadProject() {
     fail(`cannot resolve "@opentf/web" from ${root}\n  add it to your dependencies.`);
   }
 
-  // Locate the `otfwc` compiler. Published: the prebuilt binary from `@opentf/web-compiler`
-  // (a dependency of this CLI). In this repo's own dev (a Cargo workspace is found
-  // above the CLI): the cargo `target/debug` build, rebuilt on demand. `OTFWC_BIN`
-  // overrides both.
-  const cliDir = dirname(fileURLToPath(import.meta.url));
-  const workspace = findUp("Cargo.toml", cliDir);
-  let otfwc;
-  if (process.env.OTFWC_BIN) {
-    otfwc = process.env.OTFWC_BIN;
-  } else if (workspace) {
-    otfwc = join(workspace, "target", "debug", "otfwc");
-    ensureCompiler(otfwc, workspace);
-  } else {
-    try {
-      otfwc = otfwcPath();
-    } catch (e) {
-      fail(e.message);
-    }
-  }
+  // Locate the `otfwc` compiler. Explicit overrides win, then the packaged
+  // compiler binary, then this repo's local Rust workspace as a source fallback.
+  const { otfwc, workspace } = resolveCompiler();
 
   // Route directories to skip during discovery — comma-separated names in
   // EXCLUDE_ROUTES. None are excluded by default.
@@ -162,6 +212,19 @@ function ensureCompiler(otfwc, workspace) {
   if (existsSync(otfwc)) return;
   if (!workspace) fail(`otfwc compiler not found at ${otfwc}`);
   console.log("building compiler (cargo build -p otfw_cli)…");
+  const cargo = Bun.spawnSync(["cargo", "--version"], {
+    cwd: workspace,
+    stdout: "ignore",
+    stderr: "pipe",
+  });
+  if (cargo.error || cargo.exitCode !== 0) {
+    fail(
+      `cannot build otfwc because cargo is not available.\n` +
+        `  This source checkout needs Rust/Cargo to build ${otfwc}.\n` +
+        `  Install Rust in the build environment, set OTFWC_BIN to an existing otfwc binary,\n` +
+        `  or build with the published @opentf/web-cli package so @opentf/web-compiler can use its prebuilt binary.`,
+    );
+  }
   const b = Bun.spawnSync(["cargo", "build", "-p", "otfw_cli"], {
     cwd: workspace,
     stdout: "inherit",
@@ -271,43 +334,86 @@ export async function runDocsSearchIndex(root, config, siteDir, onProgress) {
 }
 
 /**
- * Generate the blog RSS feed when the project has a `blog` config and a base URL.
- * Scans the post folders, renders RSS 2.0, and writes `<siteDir>/<blogDir>/rss.xml`.
- * A project-supplied `public/<blogDir>/rss.xml` takes precedence (it overwrites ours
- * on the public/ copy). Returns `{ path, url, count }` or null (no blog / no base URL
- * / package missing). Resolved from the app's `@opentf/web-docs`.
+ * Generate blog feeds when the project has a `blog` config and a base URL. Scans the
+ * post folders, renders RSS 2.0 + Atom 1.0, and writes them under
+ * `<siteDir>/<blogDir>/`. Project-supplied `public/<blogDir>/{rss,atom}.xml` files
+ * take precedence independently. Returns `{ paths, urls, count }` or null (no blog /
+ * no base URL / all feeds overridden / package missing). Resolved from the app's
+ * `@opentf/web-docs`.
  */
 export async function runBlogFeed(root, appDir, config, siteDir, baseUrl, exclude = new Set()) {
   const blog = config?.blog;
   if (!blog) return null;
   if (!baseUrl) {
-    console.warn("⚠ blog RSS feed skipped: no site URL (pass --base-url or set otfw.config)");
+    console.warn("⚠ blog feeds skipped: no site URL (pass --base-url or set otfw.config)");
     return null;
   }
   const contentDir = blog.dir ?? "blog";
-  if (existsSync(join(root, "public", contentDir, "rss.xml"))) return null; // honor override
   try {
     const entry = Bun.resolveSync("@opentf/web-docs/build", root);
-    const { loadPosts, renderBlogFeed } = await import(pathToFileURL(entry).href);
+    const { loadPosts, renderAtomFeed, renderBlogFeed } = await import(pathToFileURL(entry).href);
     const posts = loadPosts({ appDir, contentDir, exclude });
-    const feedPath = `/${contentDir}/rss.xml`;
     const title = blog.title || (config?.docs?.title ? `${config.docs.title} Blog` : "Blog");
-    const xml = renderBlogFeed({
-      posts,
-      baseUrl,
-      feedPath,
-      channel: {
-        title,
-        description: blog.description || title,
-        link: `/${contentDir}`,
+    const channel = {
+      title,
+      description: blog.description || title,
+      link: `/${contentDir}`,
+    };
+    const feeds = [
+      {
+        file: "rss.xml",
+        path: `/${contentDir}/rss.xml`,
+        render: renderBlogFeed,
       },
-    });
-    const out = join(siteDir, contentDir, "rss.xml");
-    mkdirSync(dirname(out), { recursive: true });
-    writeFileSync(out, xml);
-    return { path: feedPath, url: baseUrl.replace(/\/+$/, "") + feedPath, count: posts.length };
+      {
+        file: "atom.xml",
+        path: `/${contentDir}/atom.xml`,
+        render: renderAtomFeed,
+      },
+    ];
+    const written = [];
+    for (const feed of feeds) {
+      if (existsSync(join(root, "public", contentDir, feed.file))) continue; // honor override
+      const out = join(siteDir, contentDir, feed.file);
+      mkdirSync(dirname(out), { recursive: true });
+      writeFileSync(out, feed.render({ posts, baseUrl, feedPath: feed.path, channel }));
+      written.push(feed.path);
+    }
+    if (!written.length) return null;
+    const origin = baseUrl.replace(/\/+$/, "");
+    return { paths: written, urls: written.map((path) => origin + path), count: posts.length };
+  } catch (e) {
+    console.warn(`⚠ blog feeds skipped: ${e?.message ?? e}`);
+    return null;
+  }
+}
+
+/**
+ * Generate `/llms.txt` and `/llms-full.txt` for docs/blog sites from the same
+ * filesystem route list used by the app build. Project-supplied public files override
+ * each output independently.
+ */
+export async function runLlmsFiles(root, appDir, pages, config, siteDir, baseUrl) {
+  if (!config?.docs && !config?.blog) return null;
+  const outputs = [
+    { file: "llms.txt", render: "renderLlmsTxt" },
+    { file: "llms-full.txt", render: "renderLlmsFullTxt" },
+  ].filter((out) => !existsSync(join(root, "public", out.file)));
+  if (!outputs.length) return null;
+
+  try {
+    const entry = Bun.resolveSync("@opentf/web-docs/build", root);
+    const mod = await import(pathToFileURL(entry).href);
+    const written = [];
+    for (const out of outputs) {
+      const render = mod[out.render];
+      if (typeof render !== "function") continue;
+      writeFileSync(join(siteDir, out.file), render({ appDir, pages, baseUrl, config }));
+      written.push(`/${out.file}`);
+    }
+    return written.length ? { paths: written } : null;
   } catch (e) {
-    console.warn(`⚠ blog RSS feed skipped: ${e?.message ?? e}`);
+    console.warn(`⚠ llms.txt skipped: ${e?.message ?? e}`);
     return null;
   }
 }
@@ -324,6 +430,325 @@ export function discoverPages(dir, exclude) {
   return out;
 }
 
+/**
+ * Discover file-based API routes anywhere under `app/` (SPEC §11). An endpoint is a
+ * `route.{js,ts}` file (the API analogue of `page.{jsx,tsx}`); its folder is the URL.
+ * Returns `{ routes, middleware }` — absolute paths to `route.*` handler modules and
+ * to `_middleware.{js,ts}` files (folder middleware) respectively.
+ */
+export function discoverApiRoutes(appDir, exclude = new Set()) {
+  const routes = [];
+  const middleware = [];
+  const walk = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (!exclude.has(entry.name)) walk(join(dir, entry.name));
+        continue;
+      }
+      const name = entry.name;
+      const full = join(dir, name);
+      if (/^route\.(jsx?|tsx?)$/.test(name)) routes.push(full);
+      else if (/^_middleware\.(jsx?|tsx?)$/.test(name)) middleware.push(full);
+    }
+  };
+  walk(appDir);
+  return { routes, middleware };
+}
+
+/**
+ * Strip the app-directory prefix from a route file path. With `appDir` the exact
+ * prefix is removed (unambiguous even for `app/app/...`); without it, fall back to
+ * the last complete `/app` path segment — the lookahead keeps folders that merely
+ * start with "app" (`/appointments`) intact.
+ */
+function stripAppPrefix(filePath, appDir) {
+  if (appDir) {
+    const base = appDir.replace(/\/+$/, "");
+    if (filePath.startsWith(base + "/")) return filePath.slice(base.length);
+  }
+  return filePath.replace(/^.*\/app(?=\/)/, "");
+}
+
+/** The page URL for a `.../app/<...>/page.{mdx,md,jsx,tsx}` file (folder = URL). */
+export function pageRouteFromPath(filePath, appDir) {
+  const r = stripAppPrefix(filePath, appDir).replace(/\/page\.(mdx|md|jsx|tsx)$/, "");
+  return r === "" ? "/" : r;
+}
+
+/** The route URL for a `.../app/<...>/route.{js,ts}` file (folder = URL). */
+function apiRoutePath(filePath, appDir) {
+  const r = stripAppPrefix(filePath, appDir).replace(/\/route\.(jsx?|tsx?)$/, "");
+  return r === "" ? "/" : r;
+}
+
+/**
+ * Discover route loaders anywhere under `app/` (docs/DATA.md). A loader is a
+ * `loader.{js,ts}` file sibling to a `page.*` — the data analogue of a `route.*`
+ * endpoint. Strictly `js|ts` (no `x` variants): loaders are plain server modules,
+ * never JSX. Returns absolute file paths.
+ */
+export function discoverLoaders(appDir, exclude = new Set()) {
+  const out = [];
+  const walk = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (!exclude.has(entry.name)) walk(join(dir, entry.name));
+      } else if (/^loader\.(js|ts)$/.test(entry.name)) out.push(join(dir, entry.name));
+    }
+  };
+  walk(appDir);
+  return out;
+}
+
+/** The page route a `.../app/<...>/loader.{js,ts}` file feeds (folder = URL). */
+export function loaderRoutePath(filePath, appDir) {
+  const r = stripAppPrefix(filePath, appDir).replace(/\/loader\.(js|ts)$/, "");
+  return r === "" ? "/" : r;
+}
+
+/**
+ * Detect folders that hold both a `page.*` and a `route.*` — they'd resolve to the
+ * same URL. Returns the conflicting `{ path, page, route }` entries (empty = none).
+ * A page and an endpoint cannot own the same path (as in Next.js's App Router).
+ */
+export function detectRouteConflicts(appDir, exclude = new Set()) {
+  const pageByRoute = new Map();
+  for (const p of discoverPages(appDir, exclude)) {
+    if (/\/page\.(mdx|md|jsx|tsx)$/.test(p)) pageByRoute.set(pageRouteFromPath(p, appDir), p);
+  }
+  const conflicts = [];
+  for (const r of discoverApiRoutes(appDir, exclude).routes) {
+    const path = apiRoutePath(r, appDir);
+    if (pageByRoute.has(path)) conflicts.push({ path, page: pageByRoute.get(path), route: r });
+  }
+  return conflicts;
+}
+
+/**
+ * Detect misplaced `loader.*` files (docs/DATA.md): a loader feeds the page in
+ * its folder, so one without a sibling `page.*` — including one placed next to a
+ * `route.*` endpoint — has nothing to feed. Returns `{ loader, route, reason }`.
+ */
+export function detectLoaderConflicts(appDir, exclude = new Set()) {
+  const conflicts = [];
+  for (const loader of discoverLoaders(appDir, exclude)) {
+    const dir = dirname(loader);
+    const hasPage = ["page.jsx", "page.tsx", "page.mdx", "page.md"].some((f) => existsSync(join(dir, f)));
+    if (hasPage) continue;
+    const hasRoute = ["route.js", "route.ts"].some((f) => existsSync(join(dir, f)));
+    conflicts.push({
+      loader,
+      route: loaderRoutePath(loader, appDir),
+      reason: hasRoute
+        ? "sits next to a route.* API endpoint (endpoints take a Request; loaders feed pages)"
+        : "has no sibling page.* to feed",
+    });
+  }
+  return conflicts;
+}
+
+/** Print the route/page/loader conflicts and exit — shared by build, dev, and serve. */
+export function assertNoRouteConflicts(appDir, exclude = new Set()) {
+  const conflicts = detectRouteConflicts(appDir, exclude);
+  if (conflicts.length > 0) {
+    const lines = conflicts.map((c) => `  ${c.path}\n    page:  ${c.page}\n    route: ${c.route}`).join("\n");
+    fail(`a page and an API route cannot resolve to the same path:\n${lines}\n  Move one to a different folder.`);
+  }
+  const loaderConflicts = detectLoaderConflicts(appDir, exclude);
+  if (loaderConflicts.length > 0) {
+    const lines = loaderConflicts.map((c) => `  ${c.route}\n    loader: ${c.loader}\n    ${c.reason}`).join("\n");
+    fail(`a loader.* file must sit next to the page.* it feeds:\n${lines}`);
+  }
+}
+
+/**
+ * Entry source for the API handler bundle: statically import every route +
+ * middleware module (keyed by absolute path so `createApiHandler` can derive the
+ * route from the path), then export the composed `Request → Response | null`
+ * handler. Mirrors `serverEntrySource` for the page/SSG bundle.
+ */
+export function apiEntrySource({ routes, middleware }, appDir) {
+  const rImports = routes.map((p, i) => `import * as r${i} from ${JSON.stringify(p)};`).join("\n");
+  const mImports = middleware.map((p, i) => `import * as m${i} from ${JSON.stringify(p)};`).join("\n");
+  const rMap = routes.map((p, i) => `  [${JSON.stringify(p)}]: r${i},`).join("\n");
+  const mMap = middleware.map((p, i) => `  [${JSON.stringify(p)}]: m${i},`).join("\n");
+  // `appDir` pins the exact prefix to strip from the keys — route derivation stays
+  // correct for folders whose name starts with "app" and for nested app/app dirs.
+  const opts = appDir ? `\n{ appDir: ${JSON.stringify(appDir)} },\n` : "\n";
+  return (
+    `import { createApiHandler } from "@opentf/web/server";\n` +
+    `${rImports}\n${mImports}\n` +
+    `export const apiHandler = createApiHandler(\n{\n${rMap}\n},\n{\n${mMap}\n},${opts});\n`
+  );
+}
+
+/**
+ * Build the API handler bundle and import it. Returns `{ handler, cleanup }`
+ * where `handler(request)` resolves to a `Response` or `null` (no API route
+ * matched). Route modules are *plain server code* — bundled as ESM without the
+ * `otfwc` DOM transform. Bare (npm / node builtin) imports stay external and are
+ * resolved at runtime from the project's node_modules, so server deps and native
+ * modules aren't dragged into the bundle. Returns `null` when there are no routes.
+ */
+export async function buildApiBundle({ root, appDir, webEntry, exclude, tmpName = ".otfw-api", bust }) {
+  const discovered = discoverApiRoutes(appDir, exclude);
+  if (discovered.routes.length === 0) return null;
+
+  const tmp = join(root, tmpName);
+  mkdirSync(tmp, { recursive: true });
+  const entry = join(tmp, "api-entry.js");
+  writeFileSync(entry, apiEntrySource(discovered, appDir));
+
+  const serverApi = join(dirname(webEntry), "server", "index.js");
+  // `bust` versions the emitted *filename* so `otfw dev` picks up handler edits on
+  // rebuild — Bun's ESM cache is keyed by file path and ignores a `?v=` query, so
+  // only a genuinely new path re-evaluates the module.
+  const outName = bust ? `api.${bust}.js` : "api.js";
+  await build({
+    input: entry,
+    platform: "node",
+    resolve: {
+      alias: { "@opentf/web/server": serverApi, "@opentf/web": webEntry },
+      extensions: EXTENSIONS,
+    },
+    // Keep npm/node builtins external — server handlers resolve them at runtime.
+    external: (id) => !id.startsWith(".") && !id.startsWith("/") && !id.startsWith("@opentf/web"),
+    output: { dir: join(tmp, "out"), format: "esm", entryFileNames: outName },
+    checks: { pluginTimings: false },
+  });
+
+  const mod = await import(pathToFileURL(join(tmp, "out", outName)).href);
+  return {
+    handler: mod.apiHandler,
+    routes: discovered.routes,
+    cleanup: () => rmSync(tmp, { recursive: true, force: true }),
+  };
+}
+
+/**
+ * Emit the API handler bundle to `outDir/api.js` for production/deploy (SPEC §13,
+ * `dist/server/`). Unlike `buildApiBundle` (which bundles to a temp dir and imports
+ * it for `dev`/`serve`), this writes a persistent, self-contained ESM module that
+ * exports `apiHandler` — the runtime dispatcher (`createApiHandler`) is bundled in;
+ * npm/node deps stay external and resolve at the deploy target. A deploy adapter
+ * (`server/adapters/`) imports this file and hands requests to `apiHandler`.
+ * Returns `{ routes }`, or `null` when the project has no API routes.
+ */
+export async function emitApiBundle({ root, appDir, webEntry, exclude, outDir }) {
+  const discovered = discoverApiRoutes(appDir, exclude);
+  if (discovered.routes.length === 0) return null;
+
+  const tmp = join(root, ".otfw-api-build");
+  mkdirSync(tmp, { recursive: true });
+  const entry = join(tmp, "api-entry.js");
+  writeFileSync(entry, apiEntrySource(discovered, appDir));
+
+  const serverApi = join(dirname(webEntry), "server", "index.js");
+  mkdirSync(outDir, { recursive: true });
+  await build({
+    input: entry,
+    platform: "node",
+    resolve: { alias: { "@opentf/web/server": serverApi, "@opentf/web": webEntry }, extensions: EXTENSIONS },
+    external: (id) => !id.startsWith(".") && !id.startsWith("/") && !id.startsWith("@opentf/web"),
+    output: { dir: outDir, format: "esm", entryFileNames: "api.js" },
+    checks: { pluginTimings: false },
+  });
+  rmSync(tmp, { recursive: true, force: true });
+  return { routes: discovered.routes };
+}
+
+/**
+ * Entry source for the loader bundle (docs/DATA.md): statically import every
+ * `loader.{js,ts}` module (keyed by absolute path so the registry derives each
+ * route from it) and export the composed registry. Mirrors `apiEntrySource`.
+ */
+export function loaderEntrySource(loaderFiles, appDir, i18n = null) {
+  const imports = loaderFiles.map((p, i) => `import * as l${i} from ${JSON.stringify(p)};`).join("\n");
+  const map = loaderFiles.map((p, i) => `  [${JSON.stringify(p)}]: l${i},`).join("\n");
+  const i18nOpt =
+    i18n && Array.isArray(i18n.locales) && i18n.locales.length
+      ? `, i18n: ${JSON.stringify({ locales: i18n.locales, defaultLocale: i18n.defaultLocale })}`
+      : "";
+  const opts = `\n{ appDir: ${JSON.stringify(appDir ?? "")}${i18nOpt} },\n`;
+  return (
+    `import { createLoaderRegistry } from "@opentf/web/server";\n` +
+    `${imports}\n` +
+    `export const loaders = createLoaderRegistry(\n{\n${map}\n},${opts});\n`
+  );
+}
+
+/**
+ * Build the loader bundle and import it. Returns `{ loaders, files, cleanup }`
+ * where `loaders` is the registry (`match`/`load`/`loadSerialized`/`handle` —
+ * see `createLoaderRegistry`), or `null` when the app has no loader files.
+ * Loaders are *plain server code*, bundled exactly like the API handler bundle:
+ * no `otfwc` DOM transform, npm/node builtins external (DB drivers and native
+ * modules resolve at runtime from the project's node_modules).
+ */
+export async function buildLoaderBundle({ root, appDir, webEntry, exclude, i18n, tmpName = ".otfw-loaders", bust }) {
+  const files = discoverLoaders(appDir, exclude);
+  if (files.length === 0) return null;
+
+  const tmp = join(root, tmpName);
+  mkdirSync(tmp, { recursive: true });
+  const entry = join(tmp, "loaders-entry.js");
+  writeFileSync(entry, loaderEntrySource(files, appDir, i18n));
+
+  const serverApi = join(dirname(webEntry), "server", "index.js");
+  // Versioned filename, not a `?v=` query — Bun's ESM cache ignores the query for
+  // file URLs, so only a new path re-evaluates the rebuilt module (see buildApiBundle).
+  const outName = bust ? `loaders.${bust}.js` : "loaders.js";
+  await build({
+    input: entry,
+    platform: "node",
+    resolve: {
+      alias: { "@opentf/web/server": serverApi, "@opentf/web": webEntry },
+      extensions: EXTENSIONS,
+    },
+    external: (id) => !id.startsWith(".") && !id.startsWith("/") && !id.startsWith("@opentf/web"),
+    output: { dir: join(tmp, "out"), format: "esm", entryFileNames: outName },
+    checks: { pluginTimings: false },
+  });
+
+  const mod = await import(pathToFileURL(join(tmp, "out", outName)).href);
+  return {
+    loaders: mod.loaders,
+    files,
+    cleanup: () => rmSync(tmp, { recursive: true, force: true }),
+  };
+}
+
+/**
+ * Emit the loader bundle to `outDir/loaders.js` for production (`dist/server/`,
+ * next to `api.js`) — `otfw serve` imports it and runs loaders per request /
+ * serves the `<path>/__data.json` endpoint. Returns `{ files }`, or `null` when
+ * the app has no loader files.
+ */
+export async function emitLoaderBundle({ root, appDir, webEntry, exclude, i18n, outDir }) {
+  const files = discoverLoaders(appDir, exclude);
+  if (files.length === 0) return null;
+
+  const tmp = join(root, ".otfw-loaders-build");
+  mkdirSync(tmp, { recursive: true });
+  const entry = join(tmp, "loaders-entry.js");
+  writeFileSync(entry, loaderEntrySource(files, appDir, i18n));
+
+  const serverApi = join(dirname(webEntry), "server", "index.js");
+  mkdirSync(outDir, { recursive: true });
+  await build({
+    input: entry,
+    platform: "node",
+    resolve: { alias: { "@opentf/web/server": serverApi, "@opentf/web": webEntry }, extensions: EXTENSIONS },
+    external: (id) => !id.startsWith(".") && !id.startsWith("/") && !id.startsWith("@opentf/web"),
+    output: { dir: outDir, format: "esm", entryFileNames: "loaders.js" },
+    checks: { pluginTimings: false },
+  });
+  rmSync(tmp, { recursive: true, force: true });
+  return { files };
+}
+
 /** The optional `app/routeGuard.{js,ts}` path, or null. */
 export function findGuard(appDir) {
   return [join(appDir, "routeGuard.js"), join(appDir, "routeGuard.ts")].find(
@@ -339,7 +764,7 @@ export function findGuard(appDir) {
  * The production build imports the file directly (Rolldown code-splits it); the dev
  * server passes a `/__route/…` URL so the route compiles on first navigation.
  */
-export function entrySource(pages, appDir, loaderUrl = (p) => p, i18n = null, nav = null) {
+export function entrySource(pages, appDir, loaderUrl = (p) => p, i18n = null, nav = null, loaderRoutes = []) {
   const map = pages
     .map((p) => `    [${JSON.stringify(p)}]: () => import(${JSON.stringify(loaderUrl(p))}),`)
     .join("\n");
@@ -353,11 +778,14 @@ export function entrySource(pages, appDir, loaderUrl = (p) => p, i18n = null, na
   // Navigation mode (otfw.config `nav`): "mpa" disables client-side link interception
   // (docs/HYDRATION.md §7). Only emitted when explicitly "mpa"; "spa" is the default.
   const navOpt = nav === "mpa" ? `\n  nav: "mpa",` : "";
+  // Route patterns with a server loader (docs/DATA.md) — the router fetches
+  // `<path>/__data.json` for these on navigation.
+  const loadersOpt = loaderRoutes.length ? `\n  loaders: ${JSON.stringify(loaderRoutes)},` : "";
   return (
     `import { mountApp } from "@opentf/web";\n` +
     (guard ? `import guard from ${JSON.stringify(guard)};\n` : "") +
     `mountApp({\n  pages: {\n${map}\n  },\n` +
-    `  target: document.getElementById("app"),${guard ? "\n  guard," : ""}${i18nOpt}${navOpt}\n});\n`
+    `  target: document.getElementById("app"),${guard ? "\n  guard," : ""}${i18nOpt}${navOpt}${loadersOpt}\n});\n`
   );
 }