@opentf/web-cli 1.2.0 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentf/web-cli",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "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"
@@ -20,7 +20,7 @@
     "bun": ">=1.0.0"
   },
   "dependencies": {
-    "@opentf/web-compiler": "0.2.0",
+    "@opentf/web-compiler": "0.3.0",
     "@tailwindcss/node": "4.2.2",
     "@tailwindcss/oxide": "4.2.2",
     "rolldown": "1.0.0-rc.17",

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,
@@ -76,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
@@ -94,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");
 
@@ -161,6 +170,24 @@ 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;
@@ -181,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}`),
     });
@@ -190,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 });

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

@@ -7,10 +7,12 @@ import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 import {
+  DATA_FILE,
   buildServerBundle,
   injectHead,
   injectHydrationData,
   injectMarkup,
+  injectRouteData,
   withHtmlLang,
 } from "./shared.js";
 
@@ -81,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
@@ -101,10 +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, hydration } =
-          (await mod.renderRoute(urlPath, params)) ?? { html: "", metadata: {}, hydration: "" };
+          (await mod.renderRoute(urlPath, params, "", { data })) ?? { html: "", metadata: {}, hydration: "" };
         const meta = i18nOn
           ? { ...metadata, links: [...(metadata.links || []), ...alternatesFor(path, locales, defaultLocale)] }
           : metadata;
@@ -117,15 +129,28 @@ export async function runPrerender({ root, pages, webEntry, otfwc, shellHtml, ou
         mkdirSync(dirname(file), { recursive: true });
         writeFileSync(
           file,
-          injectHydrationData(
-            injectMarkup(injectHead(withHtmlLang(shellHtml, locale), head), html),
-            hydration,
+          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}`);
       }
     }
   }

package/src/serve.js

@@ -16,25 +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,
@@ -150,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,
@@ -177,22 +198,45 @@ 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 = injectHydrationData(
-      injectMarkup(injectHead(localizedShell, head), result.html),
-      result.hydration,
+    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, {
@@ -204,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 !== "/") {
@@ -221,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>`, {
@@ -233,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

@@ -73,6 +73,23 @@ export function injectHydrationData(shellHtml, json) {
   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
@@ -413,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(
@@ -428,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");
@@ -442,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`
   );
 }