@opentf/web 0.7.0 → 0.9.0

package/runtime/router.js

@@ -11,12 +11,14 @@
 // NOTE: passing route params to a page via its `props` argument
 // (`function Page(props) { props.params.id }`) and layout `props.children`
 // composition both require signal-free page props, which the compiler does not
-// emit yet — for now pages read params via the reactive `router.params`.
+// emit yet — for now pages read params via the reactive `router.params`, and a
+// route loader's data via the reactive `router.data` (docs/DATA.md).
 
 import { clearError, reportError } from "../core/errors.js";
 import { signal } from "../core/signals.js";
 import { beginHydration, cursor, endHydration } from "./hydrate.js";
 import { runCleanup, runMount } from "./mount.js";
+import { fetchRouteData, readInlineRouteData } from "./route-data.js";
 
 const isBrowser = typeof window !== "undefined";
 
@@ -34,9 +36,10 @@ const state = {
   searchParams: signal(new URLSearchParams(isBrowser ? window.location.search : "")),
   params: signal({}),
   locale: signal(null),
+  data: signal(undefined),
 };
 
-export const routes = { pages: {}, layouts: {}, notFound: null };
+export const routes = { pages: {}, layouts: {}, notFound: null, loaderRoutes: new Set() };
 let guard = null;
 let rootEl = null;
 
@@ -135,14 +138,19 @@ export const router = {
   get locale() {
     return state.locale.value;
   },
+  get data() {
+    return state.data.value;
+  },
   push: (path) => navigate(path),
   replace: (path) => navigate(path, true),
 };
 
-/** Derive the route ("/counter", "/") from a `.../app/<route>/page.jsx` path. */
+/** Derive the route ("/counter", "/") from a `.../app/<route>/page.jsx` path. The
+ *  lookahead pins `/app` to a complete path segment, so a route folder that merely
+ *  starts with "app" (`/appointments`) isn't clipped. */
 function routeFromPath(filePath) {
   const r = filePath
-    .replace(/^.*\/app/, "")
+    .replace(/^.*\/app(?=\/)/, "")
     .replace(/\/(page|layout|404)\.(jsx|tsx|mdx|md)$/, "");
   return r === "" ? "/" : r;
 }
@@ -162,6 +170,22 @@ export function registerRoutes(modules) {
   }
 }
 
+/**
+ * Register which route *patterns* (`"/todos"`, `"/items/[id]"`) have a server
+ * loader (docs/DATA.md) — the toolchain discovers `loader.{js,ts}` files and
+ * passes the list via `mountApp({ loaders })`. `navigate` only fetches
+ * `<path>/__data.json` for routes in this set; `matchRoute` returns the same
+ * pattern string, so membership is a plain Set lookup.
+ */
+export function registerLoaderRoutes(paths) {
+  routes.loaderRoutes = new Set(paths || []);
+}
+
+/** Set the reactive `router.data` directly (server render and tests). */
+export function setRouteData(data) {
+  state.data.value = data;
+}
+
 /** Layout entries that wrap `route`, outermost (root) first. */
 export function layoutChain(route) {
   const chain = [];
@@ -255,11 +279,14 @@ async function resolveModule(entry) {
  * so a page reading `router.pathname`/`params`/`query` resolves to the route being
  * pre-rendered. The client uses `navigate` instead.
  */
-export function setRouteState({ pathname = "/", search = "", params = {}, locale } = {}) {
+export function setRouteState({ pathname = "/", search = "", params = {}, locale, data } = {}) {
   state.pathname.value = normalizePath(pathname);
   state.searchParams.value = new URLSearchParams(search);
   state.params.value = params;
   state.locale.value = locale !== undefined ? locale : resolveLocale(pathname).locale;
+  // Always assigned (even when the caller passed none) so a loader-less render
+  // never shows a previous route's stale data.
+  state.data.value = data;
 }
 
 /**
@@ -270,9 +297,16 @@ export function setRouteState({ pathname = "/", search = "", params = {}, locale
 export function matchRoute(pathname) {
   pathname = resolveLocale(pathname).path;
   for (const route in routes.pages) {
+    // `[param]` / `[...rest]` become named groups; literal parts are regex-escaped
+    // (a `v1.0` folder must not match `v1X0`).
     const pattern = route
-      .replace(/\[\.\.\.([^\]]+)\]/g, "(?<$1>.+)")
-      .replace(/\[([^\]]+)\]/g, "(?<$1>[^/]+)");
+      .split(/(\[\.\.\.[^\]]+\]|\[[^\]]+\])/)
+      .map((part) => {
+        if (part.startsWith("[...")) return `(?<${part.slice(4, -1)}>.+)`;
+        if (part.startsWith("[")) return `(?<${part.slice(1, -1)}>[^/]+)`;
+        return part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      })
+      .join("");
     const m = pathname.match(new RegExp(`^${pattern}/?$`));
     if (m) {
       const params = { ...(m.groups || {}) };
@@ -285,12 +319,20 @@ export function matchRoute(pathname) {
   return null;
 }
 
+// Monotonic navigation sequence: a navigation that awaited its loader-data fetch
+// commits only if no newer navigation started meanwhile (stale data must never
+// win over a later click).
+let navSeq = 0;
+
 /**
- * Navigate to `path`. Runs an optional route guard, swaps the rendered page
- * (tearing down the previous one's lifecycle), and updates window.history.
+ * Navigate to `path`. Runs an optional route guard, fetches the route's loader
+ * data when it has any (docs/DATA.md — fetch *then* commit, like the guard),
+ * swaps the rendered page (tearing down the previous one's lifecycle), and
+ * updates window.history.
  */
 export async function navigate(path, replace = false, isPop = false, hydrate = false) {
   if (!path || !rootEl) return;
+  const seq = ++navSeq;
   const url = new URL(path, window.location.origin);
 
   if (guard) {
@@ -323,10 +365,30 @@ export async function navigate(path, replace = false, isPop = false, hydrate = f
     matchRoute(url.pathname) ||
     (routes.notFound ? { entry: routes.notFound, params: {}, route: null } : null);
 
+  // Loader data (docs/DATA.md): resolved before any state write / history push /
+  // DOM swap, mirroring the guard's "settle before commit" flow. First paint over
+  // server HTML reads the inlined payload; every other navigation (SPA nav, dev/CSR
+  // first load, popstate) fetches the `<path>/__data.json` endpoint. A failed fetch
+  // is reported and the navigation commits with `data === undefined`.
+  let data;
+  if (match && match.route && routes.loaderRoutes.has(match.route)) {
+    if (hydrate) {
+      data = readInlineRouteData();
+    } else {
+      try {
+        data = await fetchRouteData(url.pathname, url.search);
+      } catch (e) {
+        reportError(e, { phase: "data", path: url.pathname });
+      }
+      if (seq !== navSeq) return; // a newer navigation superseded this one
+    }
+  }
+
   state.pathname.value = normalizePath(url.pathname);
   state.searchParams.value = url.searchParams;
   state.params.value = match ? match.params : {};
   state.locale.value = resolveLocale(url.pathname).locale;
+  state.data.value = data;
 
   if (!isPop) {
     if (replace) window.history.replaceState({}, "", path);
@@ -412,12 +474,15 @@ export async function navigate(path, replace = false, isPop = false, hydrate = f
  * @param {Function} [opts.guard]  optional `(to, tools) => …` route guard.
  * @param {"spa"|"mpa"} [opts.nav]  navigation mode (default "spa"); "mpa" disables
  *   client-side link interception so every navigation is a full page load.
+ * @param {string[]} [opts.loaders]  route patterns that have a server loader
+ *   (docs/DATA.md) — navigation fetches `<path>/__data.json` for these.
  */
-export function mountApp({ pages, target, guard: g, i18n, nav } = {}) {
+export function mountApp({ pages, target, guard: g, i18n, nav, loaders } = {}) {
   rootEl = target || (isBrowser ? document.getElementById("app") : null);
   navMode = nav === "mpa" ? "mpa" : "spa";
   if (i18n) configureI18n(i18n);
   if (pages) registerRoutes(pages);
+  if (loaders) registerLoaderRoutes(loaders);
   guard = g || null;
   // In MPA mode the browser owns navigation (full loads push real history entries),
   // so there is no client-side history to react to — only wire popstate for SPA.
@@ -439,6 +504,12 @@ export function mountApp({ pages, target, guard: g, i18n, nav } = {}) {
     typeof rootEl.hasAttribute === "function" &&
     rootEl.hasAttribute("data-otfw-hydrate")
   );
+  // The flag is seeded `true` from the sentinel at module load (so eagerly-defined
+  // framework components adopt on upgrade — see hydrate.js). If this mount is NOT
+  // hydrating after all (no sentinel, or an empty root), clear it now so the CSR build
+  // below — and every later navigation — builds fresh. The hydrate path clears it itself
+  // (via `endHydration` in `navigate`'s `finally`) once first paint is adopted.
+  if (!hydrate) endHydration();
   return navigate(
     window.location.pathname + window.location.search + window.location.hash,
     true,

package/server/adapters/node.d.ts

@@ -0,0 +1,28 @@
+// Type definitions for the Node.js adapter (SPEC §11.4).
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { RequestHandler } from "../api.js";
+
+export interface NodeAdapterOptions {
+  /** Response for requests that match no API route (default: a 404). */
+  fallback?: (request: Request) => Response | Promise<Response>;
+}
+
+/** Build a WHATWG `Request` from a Node `IncomingMessage`. */
+export function toWebRequest(req: IncomingMessage, options?: { protocol?: string }): Promise<Request>;
+
+/** Write a WHATWG `Response` to a Node `ServerResponse`. */
+export function sendWebResponse(res: ServerResponse, webRes: Response): Promise<void>;
+
+/**
+ * Turn a Fetch handler into a Node `(req, res)` listener:
+ *
+ *   import { createServer } from "node:http";
+ *   import { apiHandler } from "./dist/server/api.js";
+ *   import { toNodeListener } from "@opentf/web/server/adapters/node";
+ *   createServer(toNodeListener(apiHandler)).listen(3000);
+ */
+export function toNodeListener(
+  handler: RequestHandler,
+  options?: NodeAdapterOptions,
+): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/server/adapters/node.js

@@ -0,0 +1,74 @@
+// Node.js adapter for OTF Web API routes (SPEC §11.4). The API handler speaks the
+// standard Fetch `Request`/`Response`; Bun, Cloudflare Workers, and Deno provide
+// those natively, but `node:http` speaks its own `IncomingMessage`/`ServerResponse`.
+// This adapter translates between the two so `dist/server/api.js` runs on Node.
+//
+//   import { createServer } from "node:http";
+//   import { apiHandler } from "./dist/server/api.js";
+//   import { toNodeListener } from "@opentf/web/server/adapters/node";
+//   createServer(toNodeListener(apiHandler)).listen(3000);
+
+/** Build a WHATWG `Request` from a Node `IncomingMessage`. */
+export async function toWebRequest(req, { protocol = "http" } = {}) {
+  const host = req.headers.host ?? "localhost";
+  const url = `${protocol}://${host}${req.url}`;
+  const method = req.method ?? "GET";
+  const headers = new Headers();
+  for (const [k, v] of Object.entries(req.headers)) {
+    if (Array.isArray(v)) for (const one of v) headers.append(k, one);
+    else if (v != null) headers.set(k, v);
+  }
+  // GET/HEAD must not carry a body; everything else streams the request in.
+  const hasBody = method !== "GET" && method !== "HEAD";
+  const body = hasBody ? await readBody(req) : undefined;
+  return new Request(url, { method, headers, body });
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}
+
+/** Write a WHATWG `Response` to a Node `ServerResponse`. */
+export async function sendWebResponse(res, webRes) {
+  const headers = {};
+  webRes.headers.forEach((value, key) => {
+    if (key !== "set-cookie") headers[key] = value;
+  });
+  // `Headers` iteration collapses repeated Set-Cookie values into one string, which
+  // breaks multi-cookie responses (session + CSRF). Recover the individual cookies;
+  // Node accepts an array header value and writes one Set-Cookie line per entry.
+  const cookies = webRes.headers.getSetCookie?.() ?? [];
+  if (cookies.length > 0) headers["set-cookie"] = cookies;
+  res.writeHead(webRes.status, headers);
+  if (webRes.body) {
+    const buf = Buffer.from(await webRes.arrayBuffer());
+    res.end(buf);
+  } else {
+    res.end();
+  }
+}
+
+/**
+ * Turn a Fetch handler `(request) => Response | null` into a Node
+ * `(req, res)` listener. A `null` result (no API route matched) becomes the
+ * optional `fallback(request)` response, or a 404.
+ */
+export function toNodeListener(handler, { fallback } = {}) {
+  return async (req, res) => {
+    try {
+      const request = await toWebRequest(req);
+      let webRes = await handler(request);
+      if (!webRes) webRes = fallback ? await fallback(request) : new Response("Not Found", { status: 404 });
+      await sendWebResponse(res, webRes);
+    } catch (e) {
+      if (!res.headersSent) res.writeHead(500, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: "Internal Server Error" }));
+      console.error("✗ API (node adapter):", e?.stack ?? e);
+    }
+  };
+}

package/server/api.d.ts

@@ -0,0 +1,106 @@
+// Type definitions for file-based API routes (SPEC §11). Authoring handlers in
+// TypeScript: annotate the method exports with `ApiHandler` and the `_middleware`
+// default export with `Middleware`.
+//
+//   import type { ApiHandler, Middleware } from "@opentf/web/server";
+//   export const GET: ApiHandler = (request, { params }) => Response.json({ id: params.id });
+
+type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Route params resolved from `[param]` / `[...rest]` segments. A `[param]` segment
+ * resolves to a `string`; a `[...rest]` catch-all resolves to a `string[]`. Values
+ * arrive percent-decoded (`/users/John%20Doe` → `"John Doe"`).
+ */
+export type RouteParams = Record<string, string | string[]>;
+
+/** Per-request context, passed as the second argument to handlers and middleware. */
+export interface ApiContext {
+  /** Dynamic route params resolved from the matched path. */
+  params: RouteParams;
+  /** Parsed query-string parameters. */
+  query: Record<string, string>;
+  /** The parsed request URL. */
+  url: URL;
+  /**
+   * Mutable per-request bag. Middleware writes to it (e.g. an authenticated user
+   * or a validated body) and downstream middleware / the handler reads from it.
+   */
+  locals: Record<string, unknown>;
+}
+
+/**
+ * An HTTP method handler (`GET`, `POST`, …). Receives the standard Fetch `Request`
+ * plus the {@link ApiContext}. Should return (or throw) a `Response`; a plain value
+ * is a convenience that gets JSON-encoded.
+ */
+export type ApiHandler = (request: Request, context: ApiContext) => MaybePromise<Response>;
+
+/** Continue to the next middleware, or ultimately the route handler. */
+export type NextFn = () => Promise<Response>;
+
+/**
+ * Folder middleware — the default export of a `_middleware.{js,ts}` file. Applies
+ * to its folder and everything nested under it; multiple middleware compose
+ * outermost-first. Call `next()` to continue, or return a `Response` to
+ * short-circuit (e.g. an auth guard).
+ */
+export type Middleware = (request: Request, context: ApiContext, next: NextFn) => MaybePromise<Response>;
+
+/**
+ * The composed request handler produced by {@link createApiHandler}: resolves to a
+ * `Response`, or `null` when no API route matched (so the caller can fall through
+ * to SSR or a 404).
+ */
+export type RequestHandler = (request: Request) => Promise<Response | null>;
+
+/** A discovered route module: its method-named handler exports, keyed by method. */
+export type RouteModule = Partial<Record<string, ApiHandler>>;
+
+/** A discovered `_middleware` module: the middleware is the default export. */
+export interface MiddlewareModule {
+  default?: Middleware;
+  middleware?: Middleware;
+}
+
+export interface FetchHandlerOptions {
+  /** Response for requests that match no API route (default: a 404). */
+  fallback?: (request: Request) => MaybePromise<Response>;
+}
+
+export interface ApiHandlerOptions {
+  /**
+   * Absolute path of the app directory the module keys live under. When given, the
+   * route is derived by stripping this exact prefix (the CLI always passes it);
+   * without it a `/app` path-segment heuristic is used.
+   */
+  appDir?: string;
+}
+
+/** Derive the route path from an `app/**/route.{js,ts}` file path (folder = URL). */
+export function apiRouteFromPath(filePath: string, appDir?: string): string;
+
+/** Derive the folder route a `_middleware` file governs from its file path. */
+export function middlewareScopeFromPath(filePath: string, appDir?: string): string;
+
+/**
+ * Build the API request handler from discovered route + middleware modules (both
+ * keyed by absolute file path so routes are derived from the path).
+ */
+export function createApiHandler(
+  routeModules?: Record<string, RouteModule>,
+  middlewareModules?: Record<string, MiddlewareModule>,
+  options?: ApiHandlerOptions,
+): RequestHandler;
+
+/**
+ * Wrap a {@link RequestHandler} into a total Fetch handler that always returns a
+ * `Response` — a `null` (no route matched) becomes the `fallback` or a 404. Use it
+ * to mount the handler on Fetch-native runtimes (Bun, Cloudflare Workers, Deno):
+ *
+ *   export default { fetch: createFetchHandler(apiHandler) };
+ */
+export function createFetchHandler(
+  handler: RequestHandler,
+  options?: FetchHandlerOptions,
+): (request: Request) => Promise<Response>;

package/server/api.js

@@ -0,0 +1,208 @@
+// File-based API routes for the OTF Web runtime — the API backend (ARCHITECTURE
+// §6, SPEC §11). An endpoint is a `route.{js,ts}` file — the API analogue of a
+// page's `page.{jsx,tsx}` — so the folder is the URL (`app/api/users/[id]/route.ts`
+// → `/api/users/:id`), exactly like pages. Handlers are *plain server modules*
+// (not JSX/DOM-compiled): each exports named functions per HTTP method that take a
+// standard `Request` and return a standard `Response`, portable across Bun / Node /
+// Cloudflare Workers (SPEC §11.1). A folder may hold a `page.*` or a `route.*`, not
+// both — the toolchain errors on the conflict (like Next.js's App Router).
+//
+// This module is runtime-agnostic: `createApiHandler` turns a discovered route
+// map into a single `(request) => Response | null` function. `null` means "no
+// API route matched" so the caller (dev/serve/adapter) can fall through to SSR
+// or a 404. Matching reuses the `[param]` / `[...rest]` convention and regex
+// approach of the page router (runtime/router.js `matchRoute`) so behavior is
+// identical across pages and API and across every deployment target.
+
+const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+
+/**
+ * Strip the app-directory prefix from a route/middleware file path. When the
+ * caller knows the app dir (the CLI always does), the exact prefix is removed —
+ * unambiguous even for an `app/app/...` folder. Without it, fall back to the last
+ * complete `/app` path segment; the lookahead keeps folders that merely *start*
+ * with "app" (`/appointments`, `/apps`) intact.
+ */
+function stripAppDir(filePath, appDir) {
+  if (appDir) {
+    const base = appDir.replace(/\/+$/, "");
+    if (filePath.startsWith(base + "/")) return filePath.slice(base.length);
+  }
+  return filePath.replace(/^.*\/app(?=\/)/, "");
+}
+
+/**
+ * Derive the API route path from a `.../app/<...>/route.{js,ts}` file path — the
+ * folder is the URL, mirroring `routeFromPath` in the page router.
+ * `app/api/status/route.js` → `/api/status`, `app/api/users/[id]/route.ts` →
+ * `/api/users/[id]`, `app/route.js` → `/`. Pass `appDir` (the absolute app
+ * directory) when known so the prefix is stripped exactly.
+ */
+export function apiRouteFromPath(filePath, appDir) {
+  const r = stripAppDir(filePath, appDir).replace(/\/route\.(jsx?|tsx?)$/, "");
+  return r === "" ? "/" : r;
+}
+
+/** The folder route a `_middleware.{js,ts}` file governs: `app/api/_middleware.js`
+ *  → `/api` (applies to `/api` and everything nested under it). */
+export function middlewareScopeFromPath(filePath, appDir) {
+  const r = stripAppDir(filePath, appDir).replace(/\/_middleware\.(jsx?|tsx?)$/, "");
+  return r === "" ? "/" : r;
+}
+
+/** Compile a route path with `[param]` / `[...rest]` segments to a matcher regex.
+ *  Named groups become route params; literal parts are regex-escaped (a `v1.0`
+ *  folder must not match `v1X0`); the optional trailing slash is tolerated. */
+function compilePattern(route) {
+  const src = route
+    .split(/(\[\.\.\.[^\]]+\]|\[[^\]]+\])/)
+    .map((part) => {
+      if (part.startsWith("[...")) return `(?<${part.slice(4, -1)}>.+)`;
+      if (part.startsWith("[")) return `(?<${part.slice(1, -1)}>[^/]+)`;
+      return part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    })
+    .join("");
+  return new RegExp(`^${src}/?$`);
+}
+
+// Percent-decode a matched param segment; malformed input stays raw rather than throwing.
+const decodeParam = (s) => {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+};
+
+const normalize = (p) => (p || "/").replace(/(.)\/+$/, "$1");
+
+/** The `Allow` header value for a handler module: the methods it exports, plus the
+ *  auto-provided HEAD (when GET exists) and OPTIONS. */
+function allowedMethods(mod) {
+  const set = new Set(METHODS.filter((m) => typeof mod[m] === "function"));
+  if (set.has("GET")) set.add("HEAD");
+  set.add("OPTIONS");
+  return [...set].join(", ");
+}
+
+/**
+ * Build the API request handler from a discovered route + middleware map.
+ *
+ * @param {Record<string, object>} routeModules  `{ [absFilePath]: moduleNamespace }`
+ *        — each module exports method handlers (`GET`, `POST`, …).
+ * @param {Record<string, object>} middlewareModules  `{ [absFilePath]: moduleNamespace }`
+ *        for `_middleware.{js,ts}` files; the middleware is the default export.
+ * @param {{ appDir?: string }} [options]  `appDir` — the absolute app directory the
+ *        module keys live under, for exact route derivation (the CLI passes it).
+ * @returns {(request: Request) => Promise<Response | null>}
+ */
+export function createApiHandler(routeModules = {}, middlewareModules = {}, { appDir } = {}) {
+  const routes = [];
+  for (const file in routeModules) {
+    const route = apiRouteFromPath(file, appDir);
+    routes.push({ route, pattern: compilePattern(route), module: routeModules[file], dynamic: route.includes("[") });
+  }
+  // Static routes before dynamic, longer (more specific) before shorter, so the
+  // most specific match wins deterministically regardless of discovery order.
+  routes.sort((a, b) => a.dynamic - b.dynamic || b.route.length - a.route.length);
+
+  const middleware = [];
+  for (const file in middlewareModules) {
+    const mod = middlewareModules[file];
+    const fn = mod.default ?? mod.middleware;
+    if (typeof fn === "function") middleware.push({ scope: middlewareScopeFromPath(file, appDir), fn });
+  }
+  // Outermost (shortest scope) runs first, so `/api/_middleware` wraps `/api/users/_middleware`.
+  middleware.sort((a, b) => a.scope.length - b.scope.length);
+
+  return async function handle(request) {
+    const url = new URL(request.url);
+    const pathname = normalize(url.pathname);
+
+    let matched = null;
+    let params = {};
+    for (const r of routes) {
+      const m = pathname.match(r.pattern);
+      if (!m) continue;
+      matched = r;
+      params = { ...(m.groups || {}) };
+      // Params reach handlers percent-decoded (`/users/John%20Doe` → "John Doe");
+      // catch-all segments are split first so an encoded `%2F` never adds a segment.
+      for (const k in params) {
+        params[k] = r.route.includes(`[...${k}]`)
+          ? params[k].split("/").map(decodeParam)
+          : decodeParam(params[k]);
+      }
+      break;
+    }
+    if (!matched) return null; // no API route — fall through to SSR / 404
+
+    // Shared per-request context. `locals` is the channel middleware uses to pass
+    // data (auth user, validated body) down to the handler.
+    const context = {
+      params,
+      query: Object.fromEntries(url.searchParams),
+      url,
+      locals: {},
+    };
+
+    const dispatch = async (req) => {
+      const mod = matched.module;
+      const method = req.method.toUpperCase();
+      const fn = mod[method];
+      if (typeof fn === "function") return fn(req, context);
+      // Auto HEAD from GET (drop the body); auto OPTIONS; else 405.
+      if (method === "HEAD" && typeof mod.GET === "function") {
+        const got = await mod.GET(req, context);
+        // GET may lean on the plain-value → JSON convenience; HEAD must then carry
+        // the same status/headers that GET response would have had.
+        const res = got instanceof Response ? got : Response.json(got);
+        return new Response(null, { status: res.status, headers: res.headers });
+      }
+      if (method === "OPTIONS") return new Response(null, { status: 204, headers: { Allow: allowedMethods(mod) } });
+      return new Response(null, { status: 405, headers: { Allow: allowedMethods(mod) } });
+    };
+
+    // Compose the applicable middleware chain around dispatch (outermost first).
+    // The root scope ("/", from an `app/_middleware.*`) governs every route.
+    const chain = middleware.filter(
+      (mw) => mw.scope === "/" || pathname === mw.scope || pathname.startsWith(mw.scope + "/"),
+    );
+    let next = dispatch;
+    for (let i = chain.length - 1; i >= 0; i--) {
+      const { fn } = chain[i];
+      const downstream = next;
+      next = (req) => fn(req, context, () => downstream(req));
+    }
+
+    try {
+      const res = await next(request);
+      if (res instanceof Response) return res;
+      if (res === undefined) {
+        throw new Error(`API handler for ${request.method} ${pathname} returned no Response`);
+      }
+      return Response.json(res); // lenient: a plain value becomes a JSON response
+    } catch (e) {
+      if (e instanceof Response) return e; // handlers/middleware may throw a Response
+      console.error(`✗ API ${request.method} ${pathname}:`, e?.stack ?? e);
+      return Response.json({ error: "Internal Server Error" }, { status: 500 });
+    }
+  };
+}
+
+/**
+ * Wrap an API handler (`(request) => Response | null`) into a total Fetch handler
+ * that always returns a `Response` — a `null` (no route matched) becomes the
+ * optional `fallback(request)` or a 404. Fetch-native runtimes (Bun, Cloudflare
+ * Workers, Deno) can export it directly:
+ *
+ *   import { apiHandler } from "./dist/server/api.js";
+ *   export default { fetch: createFetchHandler(apiHandler) };
+ */
+export function createFetchHandler(handler, { fallback } = {}) {
+  return async (request) => {
+    const res = await handler(request);
+    if (res) return res;
+    return fallback ? fallback(request) : new Response("Not Found", { status: 404 });
+  };
+}