@rivetjs/router 0.0.0-stage → 0.1.0-alpha.1

package/build/codegen.js

@@ -0,0 +1,1037 @@
+// Code generation for file routes. Output is ordinary TSX/TS written to `.rivet/` so the Rivet
+// compiler (incl. resume mode) treats it like hand-written application code.
+import { posix } from "node:path";
+import { normalizeBase } from "../shared/base.js";
+const HEADER = "// Generated by @rivetjs/router from the routes directory. Do not edit.\n";
+// Characters a browser-serialized `URL.pathname` holds percent-encoded: the WHATWG path percent-encode
+// set, non-ASCII, and `%` (decoded text: a literal `%` is written `%25`).
+const ENCODED = /[\0- "#%<>?`{}\x7f-\uffff]/;
+// RegExp syntax characters (escaped the way `u` / `v` mode RegExps — and URLPattern regexp groups — accept).
+const SYNTAX = /[\\^$.*+?()[\]{}|/]/g;
+/** One static path segment as a browser-serialized `URL.pathname` holds it, RegExp-escaped. */
+function literal(segment) {
+    let text;
+    try {
+        text = decodeURIComponent(segment);
+    }
+    catch {
+        text = segment;
+    }
+    return [...text]
+        .map((char) => (ENCODED.test(char) ? encodeURIComponent(char).replace(/%[\da-f]{2}/gi, (escape) => escape.toUpperCase()) : char))
+        .join("")
+        .replace(SYNTAX, "\\$&");
+}
+/** Whether some URL path could match both route patterns (static segments differ → no). */
+function overlaps(a, b) {
+    const left = a.split("/").filter(Boolean), right = b.split("/").filter(Boolean);
+    for (let i = 0;; i++) {
+        const x = left[i], y = right[i];
+        if (x?.[0] === "*" || y?.[0] === "*")
+            return true;
+        if (x === undefined || y === undefined)
+            return x === y;
+        if (x[0] !== ":" && y[0] !== ":" && x !== y)
+            return false;
+    }
+}
+const trie = () => ({ end: false, splat: false, kids: new Map() });
+/** Generated dev helper `<head> = (message) => boolean`: true for a benign browser notice (dropped, not forwarded). */
+const DEV_BENIGN = (head) => [
+    "// Benign browser notices (Chrome / Firefox + Safari texts of the ResizeObserver loop), never an app error: dropped like",
+    "// Vite's own overlay and webpack-dev-server do; logged once at debug level.",
+    "let benignLogged = false;",
+    `${head} = (message: string): boolean => {`,
+    "  if (!/^ResizeObserver loop (completed with undelivered notifications|limit exceeded)/.test(message)) return false;",
+    '  if (!benignLogged) (benignLogged = true), console.debug("[rivet] ignored benign browser notice: " + message);',
+    "  return true;",
+    "};",
+];
+/**
+ * Generated dev helper `<head> = (error: unknown) => { message, stack }` for `rivet:client-error`: an Error keeps
+ * its message + stack; an `ErrorEvent` whose `error` is null (ResizeObserver loop, cross-origin script) reports its
+ * message + source location; any other value (`throw null`, a non-Error rejection) its type + value, with the stack
+ * of the reporting site. Was: `String(value)` only ("Browser error: null").
+ */
+const DEV_DESCRIBE = (head) => [
+    `${head} = (error: unknown): { message: string; stack?: string } => {`,
+    "  if (error instanceof Error) return { message: error.message, stack: error.stack };",
+    '  const site = new Error("reported here").stack;',
+    '  if (typeof ErrorEvent !== "undefined" && error instanceof ErrorEvent)',
+    '    return { message: `${error.message || "Uncaught error"} (${error.filename || "unknown source"}:${error.lineno}:${error.colno}; the error event carries no Error)`, stack: site };',
+    "  let value: string;",
+    "  try {",
+    '    value = typeof error === "string" ? error : JSON.stringify(error) ?? String(error);',
+    "  } catch {",
+    "    value = String(error);",
+    "  }",
+    '  return { message: `Non-Error value thrown (${error === null ? "null" : typeof error}): ${value}`, stack: site };',
+    "};",
+];
+/**
+ * RegExp source (no anchors, no leading `/`) over `URL.pathname.slice(1)` that matches every path one
+ * of `patterns` (route patterns: static segments, `:param`, terminal `*splat`; one optional trailing
+ * slash) matches. Shared prefixes are factored (a trie), so the source stays small for large apps.
+ * Valid in `u` / `v` mode and as a URLPattern regexp group (`/(source)`); `""`: only `/` matches.
+ */
+export function routePathRegExp(patterns) {
+    const root = trie();
+    for (const pattern of patterns) {
+        let node = root;
+        for (const part of pattern === "/" ? [] : pattern.replace(/^\/|\/$/g, "").split("/")) {
+            if (node.splat)
+                break;
+            if (part[0] === "*") {
+                node.splat = true;
+                break;
+            }
+            if (part[0] === ":")
+                node = node.param ??= trie();
+            else {
+                const key = literal(part);
+                let next = node.kids.get(key);
+                if (!next)
+                    node.kids.set(key, (next = trie()));
+                node = next;
+            }
+        }
+        node.end = true;
+    }
+    // Alternatives for what follows a node's own segment: nothing (or one `/`), or `/` and a child.
+    const children = (node) => [...[...node.kids].map(([key, kid]) => key + rest(kid)), ...(node.param ? ["[^\\/]+" + rest(node.param)] : [])];
+    const rest = (node) => {
+        if (node.splat)
+            return "(?:\\/.*)?";
+        const kids = children(node);
+        if (!kids.length)
+            return "\\/?";
+        const below = "\\/" + (kids.length > 1 ? "(?:" + kids.join("|") + ")" : kids[0]);
+        return node.end ? "(?:" + below + "|\\/?)" : below;
+    };
+    if (root.splat)
+        return ".*";
+    return [...children(root), ...(root.end ? [""] : [])].join("|");
+}
+const str = JSON.stringify;
+/** JSX lines nesting `inner` in `providers` ([comment, open tag] pairs), outermost first, at `indent`. */
+function wrap(providers, inner, indent) {
+    const pad = (n) => indent + "  ".repeat(n);
+    return [
+        ...providers.flatMap(([comment, open], n) => [pad(n) + comment, pad(n) + open]),
+        pad(providers.length) + inner,
+        ...providers.map((_, n) => pad(providers.length - 1 - n) + "</Provider>"),
+    ];
+}
+/**
+ * Derived resume model (`CodegenOptions.derived`): `app.tsx`'s default export, the page's independent root boundary. Server:
+ * the App with the request's router (`ServerData` comes from the server entry). Browser (its adopt run): the browser
+ * router, the payload as `Revived`, and the contexts the server entry provides (navigation state, search params) as the
+ * browser's; `ready` loads the page modules of the URL first, so the adopt run renders the route synchronously.
+ */
+function rootComponent(transitions, search) {
+    const providers = [
+        ...(transitions
+            ? [["{/* useNavigation(): the browser's navigation signal. */}", "<Provider token={Navigation} value={navigation}>"]]
+            : []),
+        ...(search ? [["{/* useSearchParams(): the browser's. */}", "<Provider token={SearchParams} value={searchParams}>"]] : []),
+    ];
+    return [
+        "",
+        "/** Derived resume model: the page root (independent boundary: its props are the route payload as data). */",
+        "export default function Root(props: { s: RootData }) {",
+        "  if (import.meta.env.SSR) return <App router={serverRouter(useContext(ServerData)!.url)} />;",
+        "  if (!adopting) ((adopting = true), queueMicrotask(() => (adopting = false)));",
+        "  const s = props.s,",
+        "    router = browserRouter(),",
+        "    data = s.d.slice();",
+        "  for (const i of s.n ?? []) data[i] = undefined;",
+        "  const server = { data, url: untrack(router.location), ...(s.e ? { error: s.e } : {}), ...(s.a ? { action: s.a } : {}), ...(s.x ? { byURL: s.x } : {}), ...(s.k ? { deps: s.k } : {}) } as ServerRoutePayload;",
+        "  return (",
+        "    <Provider token={Revived} value={server}>",
+        ...wrap(providers, "<App router={router} />", "      "),
+        "    </Provider>",
+        "  );",
+        "}",
+        "/** Before the adopt run: the page modules of the shown URL (a lazy page renders synchronously once loaded). */",
+        "Root.ready = (): Promise<unknown> | undefined => loadPage(new URL(globalThis.location.href));",
+    ];
+}
+/** Generate the app, server entry, route table and route types for a scanned table. */
+export function generate(table, options) {
+    const outDir = options.outDir ?? ".rivet";
+    const mode = options.mode ?? "server";
+    // Router listeners that alone keep a page resumable (`clientRouter`), else `standalone: false`.
+    const lone = (options.clientRouter ?? mode !== "static") ? "" : ", standalone: false";
+    // Matched URL paths include the base: `/` → `/app`, `/items/:id` → `/app/items/:id`.
+    const base = normalizeBase(options.base);
+    const at = (pattern) => (base ? (pattern === "/" ? base : base + pattern) : pattern);
+    if (mode === "csr") {
+        const servers = [
+            ...new Set(table.routes
+                .flatMap((r) => [r, ...r.layouts])
+                .flatMap((m) => [m.server, m.inline ? m.page : undefined])
+                .filter(Boolean)),
+        ];
+        if (servers.length)
+            throw new Error(`CSR apps have no server; remove or move these modules: ${servers.join(", ")}`);
+    }
+    const source = str(mode === "csr" ? "none" : mode);
+    const kit = options.head === "components";
+    const level = (n, jsx) => (kit ? `<Provider token={HeadLevel} value={${n}}>${jsx}</Provider>` : jsx);
+    const transitions = options.transitions ? (options.transitions === true ? {} : options.transitions) : null;
+    const search = options.searchParams === true;
+    const forms = options.forms === true;
+    const go = options.navigate === true || forms;
+    const params = options.params === true;
+    const active = options.activeLinks === true;
+    const slash = options.trailingSlash === "never" || options.trailingSlash === "always" ? options.trailingSlash : null;
+    const swap = options.announce === false ? "swapRouteQuiet" : "swapRoute";
+    const derived = options.derived === true && mode !== "csr";
+    // Derived model: the Routers swap through `adoptSwap` (the adopt task's route renders are the page load, not a navigation).
+    const swapProp = derived ? "adoptSwap" : swap;
+    const routesDir = options.routesDir.replace(/\/$/, "");
+    const fromOut = (path) => {
+        const relative = posix.relative(outDir, path);
+        return relative.startsWith(".") ? relative : "./" + relative;
+    };
+    const spec = (file) => fromOut(posix.join(routesDir, file));
+    // One binding per distinct module; ids are stable for a given table.
+    const names = new Map();
+    const bind = (file, prefix) => {
+        let name = names.get(file);
+        if (!name)
+            names.set(file, (name = prefix + names.size));
+        return name;
+    };
+    const pages = new Map(), layouts = new Map(), specials = new Map();
+    const servers = new Map();
+    const uniqueRoutes = [];
+    for (const route of table.routes) {
+        if (route.page && !pages.has(route.page))
+            pages.set(route.page, bind(route.page, "Page"));
+        for (const layout of route.layouts)
+            if (layout.page && !layouts.has(layout.page))
+                layouts.set(layout.page, bind(layout.page, "Layout"));
+        for (const file of [route.notFound, route.error])
+            if (file && !specials.has(file))
+                specials.set(file, bind(file, "Special"));
+        for (const file of [route.server, ...route.layouts.map((l) => l.server)])
+            if (file && !servers.has(file))
+                servers.set(file, "server" + servers.size);
+        uniqueRoutes.push(route);
+    }
+    for (const file of [table.notFound, table.error, ...(table.notFounds ?? []).map((n) => n.page)])
+        if (file && !specials.has(file))
+            specials.set(file, bind(file, "Special"));
+    const pageIndex = new Map([...pages.keys()].map((file, i) => [file, i]));
+    const errorViews = new Set([table.error, ...table.routes.map((r) => r.error)].filter(Boolean));
+    // --- app.tsx: universal component tree (server render + resumed browser navigation).
+    const pageRoutes = uniqueRoutes.filter((route) => route.page);
+    // The root `_layout` wraps the routes region and stays mounted; nested layouts persist as levels
+    // (`levelView`). Layout props are accessors of App-level signals the route loads update.
+    const rootLayout = pageRoutes.length && pageRoutes.every((r) => r.layouts[0]?.page && !r.layouts[0].page.includes("/")) ? pageRoutes[0].layouts[0].page : undefined;
+    // Root layout with server exports (sibling or in-file): error renders carry its data only when its loader succeeded.
+    const rootLayoutServer = rootLayout ? Boolean(pageRoutes[0].layouts[0].server || pageRoutes[0].layouts[0].inline) : false;
+    // The page (layouts are levels around it, see `levelView`).
+    // Data-driven: `Page` / `depth` are the matched table row's (see `routeTable`).
+    // Live pages (`export const live = true`) with navigate()/forms in use: `data` is an accessor the
+    // App refreshes in place on same-URL revalidation (`_serveLive`); hoisted, so the prop stays static.
+    const live = go && mode !== "csr" ? pageRoutes.filter((route) => route.live) : [];
+    const pageData = live.length ? "data" : "result.data[depth]";
+    const pageView = () => {
+        const jsx = kit
+            ? `<Provider token={HeadLevel} value={depth}><Page data={${pageData}} params={match.params} url={match.url} /></Provider>`
+            : `<Page data={${pageData}} params={match.params} url={match.url} />`;
+        // `useParams()` in the page: this render's params (the page re-renders per navigation).
+        return params ? `<Provider token={RouteParamsContext} value={signal(match.params)}>${jsx}</Provider>` : jsx;
+    };
+    // Layout table: every layout of a page route (id = `/` + folder); persisted ones (with a component,
+    // except the root layout outside the routes) render as levels with their own Router region.
+    const layoutKey = (module) => posix.dirname(module.page ?? module.server ?? "");
+    const layoutIndex = new Map();
+    const layoutModulesList = [];
+    for (const route of pageRoutes)
+        for (const layout of route.layouts)
+            if (!layoutIndex.has(layoutKey(layout)))
+                layoutIndex.set(layoutKey(layout), layoutModulesList.push(layout) - 1);
+    const indexOf = (module) => layoutIndex.get(layoutKey(module));
+    const persisted = (route) => route.layouts.flatMap((layout, at) => (layout.page && layout.page !== rootLayout ? [at] : []));
+    const useNest = layoutModulesList.length > 0;
+    // Data requests name the layouts whose data the client keeps (only layouts with server exports load).
+    const keeps = mode === "server" && layoutModulesList.some((layout) => layout.server || layout.inline);
+    const levels = Math.max(0, ...pageRoutes.map((route) => persisted(route).length));
+    const nested = levels > 0;
+    const folderParams = (folder) => folder === "." ? [] : folder.split("/").flatMap((part) => /^\[{1,2}(?:\.\.\.)?([A-Za-z_$][\w$]*)\]{1,2}$/.exec(part)?.slice(1) ?? []);
+    const layoutTable = {
+        ids: [...layoutIndex.keys()].map((folder) => (folder === "." ? "/" : "/" + folder)),
+        params: [...layoutIndex.keys()].map(folderParams),
+        kind: layoutModulesList.map((layout) => (layout.page ? 1 : 0) | (layout.server || layout.inline ? 2 : 0)),
+        root: rootLayout ? indexOf(pageRoutes[0].layouts[0]) : -1,
+        routes: pageRoutes.map((route) => [at(route.pattern), route.layouts.map(indexOf)]),
+    };
+    const routeIndex = (route) => pageRoutes.indexOf(route);
+    const slot = (i) => `nest.l[${i}]!`;
+    // Level `k` of `route`: its persisted layout at that depth around the next level's Router, or the page.
+    // Entering level `k + 1`: the persisted layout `i` (at depth `at`) around the next level's Router.
+    // One shared view per (k, i, at) — `enter<j>` in App — instead of one copy per route.
+    const enterKey = (route, k) => {
+        const chain = persisted(route);
+        if (k === chain.length)
+            return null;
+        return `${k}:${indexOf(route.layouts[chain[k]])}:${chain[k]}`;
+    };
+    const enterView = (key) => {
+        const [k, i, at] = key.split(":").map(Number);
+        const name = layouts.get(layoutModulesList[i].page);
+        const inner = `<div data-rivet-outlet="${k + 1}"><Router router={_level(router, nest, ${k + 1}, t)} routes={routes${i}} swap={${swapProp}} hold={() => heldRoutes(${k + 1})} notFound={() => null} /></div>`;
+        const view = level(at, `<${name} data={${slot(i)}.d} params={${slot(i)}.p} url={${slot(i)}.u}>${inner}</${name}>`);
+        return `_enter(${k}, result, url, (t) => ${params ? `<Provider token={RouteParamsContext} value={${slot(i)}.p}>${view}</Provider>` : view})`;
+    };
+    const rootNotFound = table.notFound ? specials.get(table.notFound) : undefined;
+    // Failed loads render the route's nearest `_404` (404) or `_error` (anything else).
+    // One shared view per distinct (`_404`, `_error`) pair — `fail<j>` in App — instead of one copy per route.
+    const failureKey = (route) => `${route.notFound ?? ""}|${route.error ?? ""}`;
+    const failureView = (key) => {
+        const [notFoundFile, errorFile] = key.split("|");
+        const notFound = notFoundFile ? specials.get(notFoundFile) : undefined;
+        const error = errorFile ? specials.get(errorFile) : undefined;
+        const errorView = error
+            ? `<${error} error={failure} />`
+            : `<p role="alert">{isHttpError(failure) && failure.expose ? failure.message : "Something went wrong"}</p>`;
+        return notFound ? `isHttpError(failure) && failure.status === 404 ? <${notFound} url={url} /> : ${errorView}` : errorView;
+    };
+    // Unmatched URLs: the `_404` of the longest matching folder prefix, else the root one.
+    let unmatched = rootNotFound ? `<${rootNotFound} url={url} />` : `<p role="status">Page not found.</p>`;
+    for (const { prefix, page } of [...(table.notFounds ?? [])].reverse())
+        unmatched = `url.pathname === ${str(at(prefix))} || url.pathname.startsWith(${str(at(prefix) + "/")}) ? <${specials.get(page)} url={url} /> : ${unmatched}`;
+    // Route tables, one per Router level: `paths` (compiled once per process: module constants) and
+    // rows [route index, data depth, page, enter view (-1: the page), failure view]. Each level's
+    // `{ paths, route }` defines only the matched route per request; its load / render read the row.
+    const failureKeys = [...new Set(pageRoutes.map(failureKey))];
+    const enterKeys = [];
+    for (const route of pageRoutes)
+        for (let k = 0; k < persisted(route).length; k++)
+            if (!enterKeys.includes(enterKey(route, k)))
+                enterKeys.push(enterKey(route, k));
+    const tables = [
+        { name: "", k: 0, routes: pageRoutes },
+        ...[...new Set(pageRoutes.flatMap((route) => persisted(route).map((at, k) => [indexOf(route.layouts[at]), k + 1])).map((pair) => pair.join(":")))]
+            .map((pair) => pair.split(":").map(Number))
+            .map(([i, k]) => ({ name: String(i), k, routes: pageRoutes.filter((route) => persisted(route).map((at) => indexOf(route.layouts[at]))[k - 1] === i) })),
+    ];
+    const tableRows = ({ k, routes }) => "[" +
+        routes
+            .map((route) => {
+            const enter = nested ? enterKey(route, k) : null;
+            return `[${routeIndex(route)}, ${route.layouts.length}, ${pageIndex.get(route.page)}, ${enter === null ? -1 : enterKeys.indexOf(enter)}, ${failureKeys.indexOf(failureKey(route))}]`;
+        })
+            .join(", ") +
+        "]";
+    // Shared views reachable from a level's rows (a single one is called directly).
+    const pick = (indices, call, at) => indices.slice(0, -1).reduceRight((rest, j) => `${at} === ${j} ? ${call(j)} : ${rest}`, call(indices.at(-1)));
+    const routeTableOf = (table) => {
+        const { name, k, routes } = table;
+        const fails = [...new Set(routes.map((route) => failureKeys.indexOf(failureKey(route))))].sort((a, b) => a - b);
+        const enters = nested
+            ? [...new Set(routes.map((route) => enterKey(route, k)).filter((key) => key !== null))].map((key) => enterKeys.indexOf(key)).sort((a, b) => a - b)
+            : [];
+        const pageRows = routes.some((route) => !nested || enterKey(route, k) === null);
+        const enter = enters.length ? pick(enters, (j) => `enter${j}(result, match.url)`, "row[3]") : "";
+        const page = [
+            `          const Page = page(row[2]), depth = row[1];`,
+            ...(live.length ? [`          const data = LIVE.includes(row[2]) ? _livePage(live, result.data[depth], match.url, depth) : result.data[depth];`] : []),
+            `          return ${pageView()};`,
+        ];
+        const view = !enters.length ? page : pageRows ? [`          if (row[3] >= 0) return ${enter};`, ...page] : [`          return ${enter};`];
+        const usesRow = pageRows || fails.length > 1 || enters.length > 1;
+        // Server: the same chain on the handler's data, synchronously (`_ssrLevel`; undefined in the browser).
+        const land = useNest ? `(result) => _landed(nest, NEST, ${k}, ROUTES${name}[n]![0], result, match)` : "(result) => result";
+        const ok = `(data) => loaded(${kit ? `applyRouteHead(data, ROUTES${name}[n]![1])` : "data"})`;
+        // Derived model: the browser's adopt run answers each level's first load from the revived payload (`Root`).
+        const served = mode === "csr" ? "" : `_ssrLevel(work, ${ok}, failed, ${land}) ?? ${derived ? `revived(work, ${ok}, failed, ${land}) ?? ` : ""}`;
+        return [
+            `  const routes${name} = {`,
+            `    paths: PATHS${name},`,
+            `    route: (n: number) =>`,
+            `      defineRoute(PATHS${name}[n]!, {`,
+            `        load: (work, match) => ${nested ? `_take<Loaded>(${k}, match.url) ?? ` : ""}${served}Promise.all([routeData(work, match, router, ${source}${keeps ? ", _keepIds(nest, NEST, match.url)" : ""}), loadPage(match.url)${transitions ? ", transitions()" : ""}])` +
+                `.then(([data${transitions ? ", page" : ""}]) => ${transitions ? "(_routeModule(page), data)" : "data"})${kit ? `.then((result) => applyRouteHead(result, ROUTES${name}[n]![1]))` : ""}.then(loaded, failed)${useNest ? `.then((result) => _landed(nest, NEST, ${k}, ROUTES${name}[n]![0], result, match))` : ""},`,
+            `        render: (result, match) => {`,
+            ...(usesRow ? [`          const row = ROUTES${name}[n]!;`] : []),
+            `          if (result.failure !== undefined) return ${pick(fails, (j) => `fail${j}(result.failure, match.url)`, "row[4]")};`,
+            ...view,
+            `        },`,
+            `      }),`,
+            `  };`,
+        ].join("\n");
+    };
+    // Endpoint routes (no page) before a dynamic page pattern, as [index in the client's match order, pattern]:
+    // the page pattern alone would claim their URLs for client navigation (the server answers the endpoint).
+    const shadowed = [];
+    // Document routes (server reach): their rows in the client's match table (top-level `PATHS` index, before the splices).
+    const documentFiles = new Set(options.documents ?? []);
+    const documentRows = pageRoutes.flatMap((route, n) => (documentFiles.has(route.page) ? [n] : []));
+    table.routes.forEach((route, i) => {
+        if (!route.page && table.routes.slice(i + 1).some((later) => later.page && /[:*]/.test(later.pattern) && overlaps(later.pattern, route.pattern)))
+            shadowed.push([table.routes.slice(0, i).filter((before) => before.page).length + shadowed.length, at(route.pattern)]);
+    });
+    // Single static page route, server/static mode, nothing navigating in place (Z1): no client router events.
+    const single = mode !== "csr" && pageRoutes.length === 1 && !/[:*]/.test(pageRoutes[0].pattern) && !go && !search && !active && !nested;
+    // Live pages in a single-level app: the top Router keys on the live slot (search-only navigations of the shown
+    // live page refresh it in place); the first navigation entry point starts the key's location sync (`_armLive`).
+    const liveTop = live.length > 0 && !nested;
+    const liveArm = liveTop ? `_armLive(router, live${useNest ? ", nest, NEST" : ""})` : "";
+    // Navigation entry points (link click, popstate, navigate()) start the route effects first (`arm`); with forms,
+    // they install the router brand (`_brand(_go)`) before anything else (warmed data, queued requests).
+    const brand = forms ? "_brand(_go)" : "";
+    const armed = (call) => nested || active || liveTop || forms ? `(${[brand, nested || active ? "arm()" : "", liveArm].filter(Boolean).join(", ")}, ${call})` : call;
+    const app = [
+        HEADER,
+        `/// <reference types="vite/client" />`,
+        ...(derived
+            ? [`import { ${useNest || (pageRoutes.length && params) ? "signal, " : ""}createContext, untrack, useContext, type Context } from "@rivetjs/reactivity";`]
+            : useNest
+                ? [`import { signal, useContext } from "@rivetjs/reactivity";`]
+                : pageRoutes.length && params
+                    ? [`import { signal } from "@rivetjs/reactivity";`]
+                    : []),
+        `import { Router, defineRoute, lazyComponent${single && !go ? "" : ", clientEvent"}${kit || (pageRoutes.length && params) || derived ? ", Provider" : ""} } from "@rivetjs/runtime/dom";`,
+        ...(kit ? [`import { HeadLevel, applyRouteHead } from "@rivetjs/kit";`] : []),
+        ...(derived
+            ? [
+                `import { createRouter as browserRouter, type BrowserRouter } from "@rivetjs/runtime/router/dom";`,
+                `import { createRouter as serverRouter } from "@rivetjs/runtime/router/server";`,
+                ...(transitions ? [`import { Navigation, navigation } from "@rivetjs/router/navigation";`] : []),
+                ...(search ? [`import { SearchParams, searchParams } from "@rivetjs/router/search";`] : []),
+            ]
+            : [`import type { BrowserRouter } from "@rivetjs/runtime/router/dom";`]),
+        `import { routeData, ${mode === "csr" ? "" : "_ssrLevel, "}${swap}, heldRoutes, preloadPage, ${single ? "" : "interceptClick, notePopstate, "}${go ? (live.length ? "_serveLive, _live, _livePage, _liveIntent, " + (liveTop ? "_liveRouter, _armLive, " : nested ? "_liveLevels, " : "") : "_serve, ") : ""}${pageRoutes.length && params ? "RouteParamsContext, " : ""}${mode === "csr" || single ? "" : "prefetchData, "}${single ? "" : "prefetchModule, "}loadModule${single ? "" : ", routableAnchor"}${useNest || derived ? ", ServerData" : ""}${derived ? ", type ServerRoutePayload" : ""}${useNest ? ", _layouts, _landed" + (keeps ? ", _keepIds" : "") + (nested ? ", _level, _enter, _take, _sync" : "") + ", type LayoutTable" : ""}${transitions ? ", _routeModule" : ""}${active ? ", onNavigate, _markActive" : ""}${nested || active ? ", _arm" : ""}${shadowed.length || documentRows.length ? ", _endpoint" : ""}${forms && !single ? ", _brand, _go" : ""} } from "@rivetjs/router/client";`,
+        `import { ${derived ? "HttpError, " : ""}isHttpError } from "@rivetjs/router";`,
+        "",
+        "// Route modules as this file renders them (strict-safe whatever props they declare): data comes",
+        "// from loaders (untyped here), layout props are accessors.",
+        "type PageProps = { data: any; params: any; url: URL };",
+        "type LayoutProps = { data: () => any; params: () => any; url: () => URL; children?: any };",
+        ...(specials.size ? ["type NotFoundProps = { url: URL };", "type ErrorProps = { error: any };"] : []),
+        ...[...layouts].flatMap(([file, name]) => [`import ${name}$ from ${str(spec(file))};`, `const ${name}: (props: LayoutProps) => unknown = ${name}$;`]),
+        ...[...specials].flatMap(([file, name]) => [
+            `import ${name}$ from ${str(spec(file))};`,
+            `const ${name}: (props: ${errorViews.has(file) ? "ErrorProps" : "NotFoundProps"}) => unknown = ${name}$;`,
+        ]),
+        // Page chunks load on navigation intent (hover/focus), not all at once when the page resumes.
+        // Z5: one import per page file in a table; a page's lazy component is created on its first use.
+        // Untyped table: each importer keeps its module's own type (checked against PageProps at `lazyComponent`).
+        `const PAGES = [${[...pages.keys()].map((file) => `() => import(${str(spec(file))})`).join(", ")}];`,
+        "const views: ((props: PageProps) => unknown)[] = [];",
+        "const page = (i: number): ((props: PageProps) => unknown) => (views[i] ??= lazyComponent<PageProps>(PAGES[i]!, undefined, { warm: false }));",
+        ...(useNest ? [`const NEST: LayoutTable = ${str(layoutTable)};`] : []),
+        ...(live.length
+            ? [
+                "// Live pages (page indices): `data` is an accessor, revalidated in place.",
+                `const LIVE: readonly number[] = ${str([...new Set(live.map((route) => pageIndex.get(route.page)))])};`,
+            ]
+            : []),
+        "// Route tables per Router level (see App): paths + [route index, data depth, page, enter view, failure view] rows.",
+        "type Row = readonly [route: number, depth: number, page: number, enter: number, failure: number];",
+        ...tables.flatMap((table) => [
+            `const PATHS${table.name}: readonly string[] = ${str(table.routes.map((route) => at(route.pattern)))};`,
+            `const ROUTES${table.name}: readonly Row[] = ${tableRows(table)};`,
+        ]),
+        ...(shadowed.length || documentRows.length
+            ? [
+                "const modules: (readonly [string, () => unknown])[] = PATHS.map((path, n) => [path, () => preloadPage(page(ROUTES[n]![2]), PAGES[ROUTES[n]![2]]!)]);",
+                ...(documentRows.length
+                    ? [
+                        "// Document routes (their browser graph reaches a server-only module): the browser loads their documents.",
+                        `for (const n of ${str(documentRows)} as const) modules[n] = [PATHS[n]!, _endpoint];`,
+                    ]
+                    : []),
+                ...(shadowed.length
+                    ? [
+                        "// Endpoints the server matches before a dynamic page pattern that also fits them: the browser loads them.",
+                        `for (const [at, path] of ${str(shadowed)} as const) modules.splice(at, 0, [path, _endpoint]);`,
+                    ]
+                    : []),
+            ]
+            : [
+                "const modules: readonly (readonly [string, () => unknown])[] = PATHS.map((path, n) => [path, () => preloadPage(page(ROUTES[n]![2]), PAGES[ROUTES[n]![2]]!)]);",
+            ]),
+        "/** Import the page module for `url` (dev mounts after it, so lazy pages render without a fallback frame). */",
+        "export const loadPage = (url: URL): Promise<unknown> | undefined => loadModule(url, modules);",
+        ...(transitions
+            ? [
+                "// Route transitions + pending UI: loaded on the first navigation intent (browser only).",
+                `const transitions = () => (typeof document === "undefined" ? undefined : import("@rivetjs/router/transitions").then((m) => m.install(${str(transitions)})));`,
+            ]
+            : []),
+        "",
+        `export type AppRouter = Pick<BrowserRouter, "location"> & Partial<Pick<BrowserRouter, "navigate">>;`,
+        "",
+        "type Loaded = { data: readonly unknown[]; failure?: undefined } | { data: readonly unknown[]; failure: unknown };",
+        "const loaded = (result: { data: readonly unknown[] }): Loaded => result;",
+        "/** Dev: send a browser route error to Vite's error overlay (`rivet:client-error`); builds drop it. */",
+        "export const _devError = (error: unknown): void => {",
+        "  if (!import.meta.hot) return;",
+        "  const report = _devDescribe(error);",
+        '  if (!_devBenign(report.message)) import.meta.hot.send("rivet:client-error", report);',
+        "};",
+        ...DEV_BENIGN("export const _devBenign"),
+        ...DEV_DESCRIBE("export const _devDescribe"),
+        "// Dev: failures that are not HTTP errors (data decode, page chunk loads) also reach the overlay.",
+        "const failed = (cause: unknown): Loaded => {",
+        '  if (import.meta.hot && typeof document !== "undefined" && !isHttpError(cause) && (cause as Error | undefined)?.name !== "AbortError") _devError(cause);',
+        '  return { data: [], failure: cause ?? new Error("Route failed") };',
+        "};",
+        ...(derived
+            ? [
+                "",
+                "// Derived resume model: `Root`'s props carry the route payload as data (the page's independent root boundary). In the",
+                "// browser its adopt run provides it as `Revived`; the Router levels' loads of that adopt (one synchronous task: the",
+                "// probe and adopt runs of every unit) answer from it (the server's chain on the same data, as `_ssrLevel`); once the",
+                "// task is over it is spent and every load (navigation, revalidation) fetches.",
+                "type RootData = { d: unknown[]; n?: readonly number[]; e?: { readonly status: number; readonly message: string }; a?: unknown; x?: readonly number[]; k?: unknown };",
+                "const Revived = createContext<ServerRoutePayload | null>(null);",
+                "const spent = new WeakMap<object, boolean>();",
+                "const revived = <R, T>(work: { get<V>(token: Context<V>): V }, ok: (data: ServerRoutePayload) => R, fail: (cause: unknown) => R, land: (result: R) => T): T | undefined => {",
+                "  if (import.meta.env.SSR) return undefined;",
+                "  const server = work.get(Revived);",
+                "  if (!server || spent.get(server)) return undefined;",
+                "  if (!spent.has(server)) (spent.set(server, false), queueMicrotask(() => spent.set(server, true)));",
+                "  let result: R;",
+                "  try {",
+                "    result = server.error ? fail(new HttpError(server.error.status, server.error.message)) : ok(server);",
+                "  } catch (cause) {",
+                "    result = fail(cause);",
+                "  }",
+                "  return land(result);",
+                "};",
+                "// The adopt task's Router renders (probe + adopt runs of `Root`) are the page load: no scroll / focus / announce.",
+                "let adopting = false;",
+                `const adoptSwap = (apply: () => void, next: ParentNode): void => (adopting ? apply() : ${swap}(apply, next));`,
+            ]
+            : []),
+        "",
+        "/** File-routed application: layouts wrap pages; client navigation fetches route data from the server. */",
+        "export function App({ router }: { router: AppRouter }) {",
+        ...(useNest
+            ? [
+                "  // Layout props are App-level signals (resume state carries them): the request's data on the",
+                "  // server, then each navigation's; kept layouts keep theirs. Level keys drive the nested Routers.",
+                `  const server = useContext(ServerData)${derived ? " ?? useContext(Revived)" : ""};`,
+                `  const nest = _layouts(server, router, NEST, ${nested ? levels + 1 : 0});`,
+            ]
+            : []),
+        ...(single
+            ? [
+                "  // One static page route and no navigate()/search params: nothing to route to in the browser, so no",
+                "  // click interception / intent prefetch / popstate listener (links load documents; the runtime stays",
+                "  // unloaded until an interaction needs it).",
+            ]
+            : [
+                // Z1: nothing of the router loads at idle. `preload: "intent"` listeners don't boot a resumed page: the
+                // loader holds the first root-relative link click, loads this chunk and replays the click (intent on a
+                // link prefetches it); the listeners attach whenever the runtime starts.
+                ...(live.length
+                    ? [
+                        "  // The shown live page's data signal: same-URL revalidations refresh it in place.",
+                        `  const live = _live(${source}${liveTop ? ", router" : ""});`,
+                    ]
+                    : []),
+                "  // Router listeners load on interaction: the resume loader holds a cold link click until they attach.",
+                ...(nested || active
+                    ? [
+                        "  // Route effects (nested level sync, `<Link active>` re-marking) start with the first navigation, not at load.",
+                        ...(nested && live.length ? ["  // Level sync: a search-only change of the shown live page moves no level key (refreshed in place)."] : []),
+                        `  const arm = () => _arm(router${nested ? `, () => _sync(router, nest, NEST${live.length ? ", (from, url) => _liveLevels(router, live, nest, NEST, from, url)" : ""})` : ""}${active ? ", () => onNavigate(() => _markActive)" : ""});`,
+                    ]
+                    : []),
+                // URLs no page route matches (endpoints, files, other apps on the origin) are not intercepted: documents.
+                // ROUTER-LAZY: `match` — clicks / intent outside links (a signal handler's button, plain text) never load
+                // this chunk; live pages also watch forms (hover / focus / press inside one warms the page data readers).
+                `  clientEvent(document, "click", (event: MouseEvent) => ${armed("interceptClick(event, router, modules)")}, { preload: "intent", match: "a"${lone} });`,
+                // A resumed page runs a link's own handlers from the resume loader's document capture listener: one that stops
+                // propagation there (a cdk Link's press) would hide the click from the bubbling listener above, which a client
+                // render's delegated dispatch (registered after it) never does. This capture listener (attached after the
+                // loader's) takes exactly those clicks: same-page `#hash` focus, client navigation (resume fuzz T31 /links).
+                ...(mode === "csr"
+                    ? []
+                    : [
+                        `  clientEvent(document, "click", (event: MouseEvent) => event.cancelBubble && ${armed("interceptClick(event, router, modules)")}, { capture: true, preload: "intent", match: "a"${lone} });`,
+                    ]),
+                `  const intent = (event: Event) => {`,
+                ...(forms ? [`    _brand(_go);`] : []),
+                // Z1: the loader boots the router on link intent; the nested-layout / active-link effects arm then.
+                ...(nested || active ? [`    arm();`] : []),
+                // Live pages: focus in a form warms the chunks of the bindings reading the page / layout data.
+                ...(live.length ? [`    _liveIntent(event, live${useNest ? ", nest" : ""});`] : []),
+                `    const anchor = routableAnchor(event, modules);`,
+                ...(transitions ? [`    if (anchor) transitions();`] : []),
+                `    if (!anchor || anchor.getAttribute("data-rivet-prefetch") === "none") return;`,
+                `    const url = new URL(anchor.href);`,
+                `    prefetchModule(url, modules);`,
+                ...(mode === "csr" ? [] : [`    prefetchData(url, ${source}${keeps ? ", _keepIds(nest, NEST, url)" : ""});`]),
+                `  };`,
+                `  clientEvent(document, "pointerover", intent, { passive: true, preload: "intent", match: "${live.length ? "a,form" : "a"}"${lone} });`,
+                `  clientEvent(document, "focusin", intent, { preload: "intent", match: "${live.length ? "a,form" : "a"}"${lone} });`,
+                ...(live.length
+                    ? [
+                        `  clientEvent(document, "pointerdown", (event: PointerEvent) => _liveIntent(event, live${useNest ? ", nest" : ""}), { passive: true, preload: "intent", match: "form"${lone} });`,
+                    ]
+                    : []),
+                `  clientEvent(window, "popstate", (event: PopStateEvent) => ${armed("notePopstate(event)")}, { preload: "intent"${lone} });`,
+            ]),
+        ...(go
+            ? [
+                "  // navigate() / invalidate() from anywhere reach this router.",
+                // Server apps with layouts: `invalidate(key)` keeps loaders using the layout state (deps, kept data).
+                `  clientEvent(document, "rivet:go", () => ${armed(live.length ? `_serveLive(router, live${useNest ? ", nest, NEST" : ""})` : `_serve(router${useNest && mode === "server" ? ", nest, NEST" : ""})`)}, { preload: "intent"${lone} });`,
+            ]
+            : []),
+        ...(rootLayout
+            ? [
+                "  // The root layout wraps the routes region and stays mounted.",
+                `  const layoutData = ${slot(layoutTable.root)}.d, layoutURL = ${slot(layoutTable.root)}.u, noParams = ${slot(layoutTable.root)}.p;`,
+            ]
+            : []),
+        "  // Shared failure views (nearest `_404` for 404s, else `_error` / a generic alert) and level views.",
+        ...failureKeys.map((key, j) => `  const fail${j} = (failure: unknown, url: URL) => ${failureView(key)};`),
+        // One Router per persisted layout (innermost first), then the top-level routes; a level's enter
+        // views (around the next level's Router) come right before the table that uses them.
+        ...[...tables.slice(1)]
+            .sort((a, b) => b.k - a.k)
+            .concat(tables[0])
+            .flatMap((table, index, all) => [
+            ...(all.findIndex((other) => other.k === table.k) === index
+                ? enterKeys.flatMap((key, j) => Number(key.split(":")[0]) === table.k ? [`  const enter${j} = (result: Loaded, url: URL) => ${enterView(key)};`] : [])
+                : []),
+            routeTableOf(table),
+        ]),
+        // The Router sits directly inside an element so the compiler makes it (and `routes`) a resumable
+        // region; the root layout wraps it outside that region and stays mounted.
+        ...(derived ? ["  // Derived model: built where it renders (inside the root layout's adopt run), not passed in ready-made."] : []),
+        `  const view = ${derived ? "() => " : ""}<div data-rivet-routes=""${go ? ' data-rivet-go=""' : ""}><Router router={${nested ? "_level(router, nest, 0, 0)" : liveTop ? "_liveRouter(router, live)" : "router"}} routes={routes} swap={${swapProp}} hold={heldRoutes} notFound={(url) => (${unmatched})} /></div>;`,
+        !rootLayout
+            ? `  return view${derived ? "()" : ""};`
+            : rootLayoutServer
+                ? "  // Server error renders carry the root layout's data when its loader succeeded; else no root layout.\n" +
+                    `  return server?.error && !server.data.length ? view${derived ? "()" : ""} : ${level(0, `<${layouts.get(rootLayout)} data={layoutData} params={noParams} url={layoutURL}>{view${derived ? "()" : ""}}</${layouts.get(rootLayout)}>`)};`
+                : `  return ${level(0, `<${layouts.get(rootLayout)} data={layoutData} params={noParams} url={layoutURL}>{view${derived ? "()" : ""}}</${layouts.get(rootLayout)}>`)};`,
+        "}",
+        ...(derived ? rootComponent(transitions !== null, search) : []),
+        "",
+    ].join("\n");
+    // --- routes.ts: server route table (server modules load lazily, once per process in builds).
+    // Every server loader returns a normalized `ServerModule` (exports found by tag, `server/module.ts`).
+    let serverUsed = false;
+    const serverModule = (file) => {
+        if (!file)
+            return "undefined";
+        serverUsed = true;
+        return `once(async () => serverExports(await import(${str(spec(file))}), ${str(posix.join(routesDir, file))}, true))`;
+    };
+    // Layouts are static imports of the app already; pages stay lazy.
+    const layoutModules = new Map([...layouts.keys()].map((file, i) => [file, "L" + i]));
+    // In-file server exports (`load(…)`, `onGet(…)`… calls): normalized from the page/layout module by tag,
+    // merged with a sibling `*.server.ts` when there is one. Sibling-only routes load the sibling raw.
+    let mergeUsed = false;
+    const serverOf = (module, layout) => {
+        if (!module.inline || !module.page)
+            return serverModule(module.server);
+        serverUsed = true;
+        if (module.server)
+            mergeUsed = true;
+        const own = layout ? layoutModules.get(module.page) : `await import(${str(spec(module.page))})`;
+        const files = str([posix.join(routesDir, module.page), module.server ? posix.join(routesDir, module.server) : ""]);
+        return module.server
+            ? `once(async () => mergeServer(${own}, await import(${str(spec(module.server))}), ${files}))`
+            : `once(async () => serverExports(${own}, ${str(posix.join(routesDir, module.page))}))`;
+    };
+    const routes = [
+        HEADER,
+        `/// <reference types="vite/client" />`,
+        `import type { AppRoute } from "@rivetjs/router/server";`,
+        ...[...layoutModules].map(([file, name]) => `import * as ${name} from ${str(spec(file))};`),
+        "",
+        "// Builds: a module loads once and later requests reuse it. Dev: every request imports (Vite serves",
+        "// the current version after an edit, so nothing stale is pinned).",
+        "const once = <T>(load: () => Promise<T>): (() => Promise<T>) => {",
+        "  if (import.meta.env.DEV) return load;",
+        "  let loaded: Promise<T> | undefined;",
+        "  return () => (loaded ??= load().catch((error: unknown) => ((loaded = undefined), Promise.reject(error))));",
+        "};",
+        "",
+        "export const routes: AppRoute[] = [",
+        ...table.routes.map((route) => `  { id: ${str(route.id)}, pattern: ${str(at(route.pattern))}, page: ${Boolean(route.page)}, layouts: [${route.layouts
+            .map((l) => serverOf(l, true))
+            .join(", ")}]${route.page && route.layouts.length
+            ? `, keys: ${str(route.layouts.map((l) => {
+                const folder = posix.dirname(l.page ?? l.server ?? "");
+                return folder === "." ? "/" : "/" + folder;
+            }))}`
+            : ""}${route.server || route.inline ? `, server: ${serverOf(route, false)}` : ""} },`),
+        "];",
+        "",
+        "type Universal = [number, { head?: unknown }];",
+        "/** Universal modules per route id with their index into the route's data (for `head` exports). */",
+        "export const universal: Record<string, () => Promise<Universal[]>> = {",
+        ...pageRoutes
+            .filter((route, index, all) => all.findIndex((r) => r.id === route.id) === index)
+            .map((route) => {
+            const items = route.layouts.flatMap((l, i) => (l.page ? [`[${i}, ${layoutModules.get(l.page)}] as Universal`] : []));
+            items.push(`import(${str(spec(route.page))}).then((m) => [${route.layouts.length}, m] as Universal)`);
+            return `  ${str(route.id)}: once(() => Promise.all([${items.join(", ")}])),`;
+        }),
+        "};",
+        "",
+    ].join("\n");
+    const routesFile = serverUsed
+        ? routes.replace(`import type { AppRoute } from "@rivetjs/router/server";`, `import { ${mergeUsed ? "mergeServer, " : ""}serverExports, type AppRoute } from "@rivetjs/router/server";`)
+        : routes;
+    // --- entry.server.tsx: render one request inside the precomputed route data.
+    const entry = [
+        HEADER,
+        ...(search ? [`import { signal } from "@rivetjs/reactivity";`] : []),
+        `import { Provider } from "@rivetjs/runtime/server";`,
+        ...(derived ? [`import { _rListen } from "@rivetjs/runtime/server-derived";`] : [`import { createRouter } from "@rivetjs/runtime/router/server";`]),
+        `import { ServerData } from "@rivetjs/router/client";`,
+        ...(transitions ? [`import { Navigation, navigation } from "@rivetjs/router/navigation";`] : []),
+        ...(search ? [`import { SearchParams } from "@rivetjs/router/search";`] : []),
+        `import type { PageInput } from "@rivetjs/router/server";`,
+        derived ? `import Root from "./app.tsx";` : `import { App } from "./app.tsx";`,
+        `export { routes, universal } from "./routes.ts";`,
+        '/** URL base path the route patterns carry (`""`: root); adapters serve files and prerender under it. */',
+        `export const base = ${str(base)};`,
+        "// The server build bundles the handler with the app, so both share one runtime instance.",
+        `export { createApp } from "@rivetjs/router/server";`,
+        ...(options.document && options.prefetch
+            ? [
+                `import shell from ${str(fromOut(options.document))};`,
+                `import { documentPrefetch } from "@rivetjs/router/prefetch";`,
+                "/** Document prefetch (`rivetRouter({ prefetch })`): Speculation Rules + intent fallback in every page's head. */",
+                `export const document = documentPrefetch(shell, ${str({ ...(typeof options.prefetch === "string" ? { default: options.prefetch } : {}), ...(single ? {} : { routed: true, ...(options.prefetchPaths === false ? {} : { routes: routePathRegExp(table.routes.filter((route) => !route.page || !documentFiles.has(route.page)).map((route) => at(route.pattern))) }) }), ...(options.prefetchEagerness && options.prefetchEagerness !== "moderate" ? { eagerness: options.prefetchEagerness } : {}) })});`,
+            ]
+            : options.document
+                ? [`export { default as document } from ${str(fromOut(options.document))};`]
+                : []),
+        ...(kit ? ["/** Pages hold the document start until the shell rendered (component head). */", "export const headComponents = true;"] : []),
+        ...(slash
+            ? [
+                "/** Trailing-slash policy: page requests in the other form answer 308; the static adapter lays files out for it. */",
+                `export const trailingSlash = ${str(slash)};`,
+            ]
+            : []),
+        ...(options.document && options.prefetch
+            ? [
+                "/** Document prefetch on (`rivetRouter({ prefetch })`): islands-only lean pages (bridge D-lean) keep the runtime fetch-ahead. */",
+                "export const fetchAhead = true;",
+            ]
+            : []),
+        ...(options.preloadBackground !== undefined
+            ? [
+                "/** Preload planner background budget (bytes; `rivetRouter({ preload })`): the app's default, adapter options override it. */",
+                `export const preloadBackground = ${options.preloadBackground};`,
+            ]
+            : []),
+        ...(options.routeRules
+            ? [
+                "/** Route rules (`rivetRouter({ routeRules })`): headers + page cache per path pattern; adapter options replace them. */",
+                `export const routeRules = ${JSON.stringify(options.routeRules)};`,
+            ]
+            : []),
+        "",
+        ...(derived
+            ? [
+                "/** Derived resume model: link clicks anywhere in the document are `Root`'s (its App's document click listener). */",
+                "function Links() {",
+                '  _rListen("a[href]");',
+                "  return null;",
+                "}",
+                "/** Derived resume model: the route payload `Root` carries as data (`undefined` loader results listed in `n`). */",
+                "const rootData = (input: PageInput) => {",
+                "  const d: unknown[] = [],",
+                "    n: number[] = [];",
+                "  input.data.forEach((value, i) => (value === undefined ? ((d[i] = null), n.push(i)) : (d[i] = value)));",
+                "  return { d, ...(n.length ? { n } : {}), ...(input.error ? { e: input.error } : {}), ...(input.action ? { a: input.action } : {}), ...(input.byURL ? { x: input.byURL } : {}), ...(input.deps ? { k: input.deps } : {}) };",
+                "};",
+                "",
+            ]
+            : []),
+        "/** Page factory for one request; the app reads the handler's loader results through ServerData. */",
+        "export function page(input: PageInput) {",
+        "  return () => (",
+        `    <Provider token={ServerData} value={{ data: input.data, url: input.url, head: input.head, ...(input.error ? { error: input.error } : {}), ...(input.action ? { action: input.action } : {})${useNest ? ", ...(input.byURL ? { byURL: input.byURL } : {}), ...(input.deps ? { deps: input.deps } : {})" : ""}${kit ? ", ...(input.headSink ? { headSink: input.headSink } : {})" : ""} }}>`,
+        ...wrap([
+            ...(search
+                ? [
+                    [
+                        "{/* useSearchParams(): the request's; resumed regions revive to the browser's signal. */}",
+                        "<Provider token={SearchParams} value={signal(input.url.searchParams)}>",
+                    ],
+                ]
+                : []),
+            ...(transitions
+                ? [
+                    [
+                        "{/* Resumed regions reading useNavigation() revive to the browser's navigation signal. */}",
+                        "<Provider token={Navigation} value={navigation}>",
+                    ],
+                ]
+                : []),
+        ], derived ? "<>\n        <Links />\n        <Root s={rootData(input)} />\n      </>" : "<App router={createRouter(input.url)} />", "      "),
+        "    </Provider>",
+        "  );",
+        "}",
+        "",
+    ].join("\n");
+    // --- entry.client.tsx (CSR): mount the app with the browser router.
+    const client = [
+        HEADER,
+        `/// <reference types="vite/client" />`,
+        `import { mount, type DOMValue } from "@rivetjs/runtime/dom";`,
+        `import { catchError } from "@rivetjs/reactivity";`,
+        `import { createRouter } from "@rivetjs/runtime/router/dom";`,
+        `import { App, _devError } from "./app.tsx";`,
+        "",
+        `const container = document.getElementById("app");`,
+        `if (!container) throw new Error('CSR shell has no element with id "app"');`,
+        "// Dev: render errors no ErrorBoundary handles reach Vite's error overlay (then propagate as before).",
+        "const guarded = (view: () => DOMValue) =>",
+        "  import.meta.hot",
+        "    ? () =>",
+        "        catchError(view, (error) => {",
+        "          _devError(error);",
+        "          throw error;",
+        "        })!",
+        "    : view;",
+        "let dispose = mount(guarded(() => <App router={createRouter()} />), container);",
+        "// Dev: components hot-replace in place (state kept); other app.tsx updates re-mount the app.",
+        "if (import.meta.hot)",
+        `  import.meta.hot.accept("./app.tsx", (next) => {`,
+        "    if (!next) return;",
+        "    dispose();",
+        '    const Next = (next as unknown as typeof import("./app.tsx")).App;',
+        "    dispose = mount(guarded(() => <Next router={createRouter()} />), container);",
+        "  });",
+        "",
+    ].join("\n");
+    // --- dev-mount.tsx (server/static dev): client-renders the app over the server HTML, from the
+    // route data the page embeds (or fetched), then takes hot updates. Client-rendered dev pages load it
+    // directly (it mounts at once); resumed ones through entry.dev.tsx, on their first hot update.
+    const devMount = [
+        HEADER,
+        `/// <reference types="vite/client" />`,
+        `import { mount, Provider } from "@rivetjs/runtime/dom";`,
+        `import { catchError } from "@rivetjs/reactivity";`,
+        `import { createRouter } from "@rivetjs/runtime/router/dom";`,
+        `import { ServerData, dataURL, decodeData, type ServerRoutePayload } from "@rivetjs/router/client";`,
+        `import * as app from "./app.tsx";`,
+        "",
+        "let container: Element | null = null;",
+        "let dispose = () => {};",
+        "let current = app;",
+        'type Body = { data?: unknown[]; head?: ServerRoutePayload["head"]; error?: ServerRoutePayload["error"]; action?: ServerRoutePayload["action"]; deps?: ServerRoutePayload["deps"]; redirect?: string };',
+        "/** Client-render the app into `into` (the page's `[data-rivet-dev]` container), replacing its content. */",
+        "export async function start(into: Element, module: typeof app = current): Promise<void> {",
+        "  container = into;",
+        "  current = module;",
+        "  const url = new URL(location.href);",
+        "  // A client-rendered dev page embeds its route data; resumed pages and hot re-mounts fetch it.",
+        "  let text: string;",
+        `  const embedded = document.getElementById("rivet-dev-data");`,
+        "  if (embedded) {",
+        "    text = embedded.textContent!;",
+        "    embedded.remove();",
+        `  } else text = await (await fetch(dataURL(url), { headers: { accept: "application/json" } })).text();`,
+        "  const body = (await decodeData(text)) as Body;",
+        "  if (body.redirect !== undefined) return location.assign(body.redirect);",
+        "  const server: ServerRoutePayload = { data: body.data ?? [], url, ...(body.head ? { head: body.head } : {}), ...(body.error ? { error: body.error } : {}), ...(body.action ? { action: body.action } : {}), ...(body.deps ? { deps: body.deps } : {}) };",
+        "  // Lazy pages render synchronously once their module is in.",
+        "  await module.loadPage(url);",
+        "  dispose();",
+        `  into.textContent = "";`,
+        "  // Render errors no ErrorBoundary handles reach Vite's error overlay (then propagate as before).",
+        "  const view = () => <Provider token={ServerData} value={server}><module.App router={createRouter()} /></Provider>;",
+        "  dispose = mount(() => catchError(view, (error) => {",
+        "    module._devError(error);",
+        "    throw error;",
+        "  })!, into);",
+        "  // Route stylesheets linked by the server (no flash) give way to Vite's injected <style>s.",
+        `  for (const link of document.querySelectorAll('link[rel="stylesheet"][href$="direct"]')) link.remove();`,
+        "}",
+        "/** Load the current page's modules without rendering (a resumed page then gets their hot updates). */",
+        "export const preload = (): Promise<unknown> | undefined => app.loadPage(new URL(location.href));",
+        "// Once mounted: components hot-replace in place (state kept); other updates reaching app.tsx re-mount",
+        "// the app. Server-only edits (loaders) refetch the route data and re-mount.",
+        '// A client-rendered dev page (`data-rivet-dev=""`) mounts now.',
+        `const page = document.querySelector('[data-rivet-dev=""]');`,
+        "if (page) await start(page);",
+        "if (import.meta.hot) {",
+        `  import.meta.hot.accept("./app.tsx", (next) => next && container && start(container, next as unknown as typeof app));`,
+        `  import.meta.hot.on("rivet:data", () => container && start(container));`,
+        "}",
+        "",
+    ].join("\n");
+    // --- entry.dev.tsx (server/static dev, resumed pages: `data-rivet-dev="resume"`): the page resumes
+    // like production; this client-renders it (dev-mount.tsx) on its first hot update.
+    const dev = [
+        HEADER,
+        `/// <reference types="vite/client" />`,
+        `const container = document.querySelector('[data-rivet-dev="resume"]');`,
+        `const mounter = () => import("./dev-mount.tsx");`,
+        "// Dev a11y checks audit the server markup at load (the runtime that also starts them loads later).",
+        `void import("@rivetjs/runtime/dev/a11y").then((module) => module.start());`,
+        "if (container && import.meta.hot) {",
+        "  const hot = import.meta.hot;",
+        "  let resumed = true;",
+        ...DEV_BENIGN("const benign"),
+        ...DEV_DESCRIBE("const describe"),
+        `  const send = (error: unknown, suffix = "") => {`,
+        `    const report = describe(error);`,
+        `    if (benign(report.message)) return;`,
+        `    hot.send("rivet:client-error", { message: report.message + suffix, stack: report.stack });`,
+        `  };`,
+        "  // Resume errors (missing chunk, changed HTML, a handler or binding throwing) reach the overlay; the",
+        "  // page does not reload (the loader's fallback), so the overlay stays.",
+        `  document.addEventListener("rivet:resume-error", (event) => {`,
+        "    const detail = (event as CustomEvent).detail as { symbol?: string; error?: unknown } | unknown;",
+        `    const error = detail && typeof detail === "object" && "error" in detail ? detail.error : detail;`,
+        `    send(error, detail && typeof detail === "object" && "symbol" in detail ? " (" + String(detail.symbol) + ")" : "");`,
+        "    event.preventDefault();",
+        "  });",
+        "  // Uncaught errors of what the browser creates (a route rendered by the resumed router) too.",
+        `  const uncaught = (event: ErrorEvent | PromiseRejectionEvent) => resumed && send("error" in event ? (event.error ?? event) : event.reason);`,
+        `  addEventListener("error", uncaught);`,
+        `  addEventListener("unhandledrejection", uncaught);`,
+        "  // The page's modules load at idle (no component runs): edits to them then reach this page.",
+        `  const idle = (fn: () => void) => ("requestIdleCallback" in window ? requestIdleCallback(fn) : setTimeout(fn, 200));`,
+        "  idle(() => void mounter().then((module) => module.preload()));",
+        "  // Resumed regions run symbols, not hot-replaceable components: the first code update stops resuming",
+        "  // (disposes the resume runtime) and client-renders the app; from then on components hot-replace in place.",
+        "  const fallback = async () => {",
+        "    if (!resumed) return;",
+        "    resumed = false;",
+        `    document.dispatchEvent(new CustomEvent("rivet:dev-client-render", { detail: { phase: "start" } }));`,
+        `    const state = document.querySelector('script[type="rivet/state"]');`,
+        "    const runtime = state ? (JSON.parse(state.textContent!) as { rt?: string | null }).rt : null;",
+        "    // The loader stops booting the resumed router on link clicks (Z1): the client-rendered app routes them.",
+        "    delete (document as { $r?: { p(): { n?: number[] } } }).$r?.p().n;",
+        "    // The loader's instance: an absolute URL (Vite adds `?import` to a relative one, a second instance).",
+        "    if (runtime) ((await import(/* @vite-ignore */ new URL(runtime, location.href).href)).default as { dispose?(): void }).dispose?.();",
+        "    await (await mounter()).start(container);",
+        `    document.dispatchEvent(new CustomEvent("rivet:dev-client-render", { detail: { phase: "done" } }));`,
+        "  };",
+        "  // DevTools asks for the same switch when its inspection tabs need live components (`rivet:devtools-inspect`).",
+        `  document.addEventListener("rivet:devtools-inspect", () => void fallback());`,
+        `  hot.on("vite:beforeUpdate", (payload) => {`,
+        `    if (payload.updates.some((update) => update.type === "js-update" && !/\\.css(?:$|\\?)/.test(update.path))) void fallback();`,
+        "  });",
+        "  // Server-only edits: a fresh server render (resumed again).",
+        `  hot.on("rivet:data", () => resumed && location.reload());`,
+        "}",
+        "export {};",
+        "",
+    ].join("\n");
+    // --- entry.resume.ts: resume runtime with the router's identified contexts (navigation state with
+    // transitions; search params when read). Neither: the compiler's default resume entry.
+    const contexts = [...(transitions ? ["[Navigation, navigation]"] : []), ...(search ? ["[SearchParams, searchParams]"] : [])];
+    const resumeEntry = [
+        HEADER,
+        `import { createResume } from "@rivetjs/runtime/dom-resume";`,
+        ...(transitions ? [`import { Navigation, navigation } from "@rivetjs/router/navigation";`] : []),
+        ...(search ? [`import { SearchParams, searchParams } from "@rivetjs/router/search";`] : []),
+        "",
+        `export default createResume({ contexts: [${contexts.join(", ")}] });`,
+        "",
+    ].join("\n");
+    // --- routes.d.ts: typed ids, params and hrefs.
+    const ids = [...new Set(table.routes.map((r) => r.id))];
+    const paramsOf = (id) => {
+        const entries = table.routes.filter((r) => r.id === id);
+        const all = new Set(entries.flatMap((r) => r.params));
+        const required = [...all].filter((p) => entries.every((r) => r.params.includes(p)));
+        return all.size ? "{ " + [...all].map((p) => `${p}${required.includes(p) ? "" : "?"}: string`).join("; ") + " }" : "{}";
+    };
+    // Page URL shapes: params and splats become `${string}` (`RoutePath`, `<Link to>`).
+    const literal = (text) => text.replace(/[\\`]|\$\{/g, (c) => "\\" + c);
+    // Static segments as authors write them (patterns are URL-encoded).
+    const pathOf = (pattern) => "`" +
+        pattern
+            .split("/")
+            .map((part) => (/^[:*]/.test(part) ? "${string}" : literal(decodeURIComponent(part))))
+            .join("/") +
+        "`";
+    const paths = [...new Set(pageRoutes.map((r) => pathOf(r.pattern)))];
+    // Loader data per route id: the route module's `load(…)` export (in-file or sibling), found by tag.
+    const typeOf = (module, wrap, sibling) => {
+        const parts = [
+            ...(module.inline && module.page ? [wrap(`typeof import(${str(spec(module.page))})`)] : []),
+            ...(module.server ? [sibling(`typeof import(${str(spec(module.server))})`)] : []),
+        ];
+        return parts.length ? parts.join(" & ") : undefined;
+    };
+    const firstOf = (id) => table.routes.find((r) => r.id === id);
+    const data = ids.flatMap((id) => {
+        const type = typeOf(firstOf(id), (m) => `ModuleData<${m}>`, (m) => `ModuleData<${m}>`);
+        return type ? [`    ${str(id)}: ${type};`] : [];
+    });
+    // Form actions per route id (the page's own module: layouts have none).
+    const actions = ids.flatMap((id) => {
+        const type = typeOf(firstOf(id), (m) => `ModuleActions<${m}>`, (m) => `ModuleActions<${m}>`);
+        return type ? [`    ${str(id)}: ${type};`] : [];
+    });
+    // Layouts by id (file path without extension). Params: the root layout stays mounted and gets
+    // none; nested layouts get the page's params (required when every page under them has it).
+    const layoutIds = new Map();
+    for (const route of pageRoutes)
+        for (const layout of route.layouts)
+            if (layout.page)
+                layoutIds.set(layout.page.replace(/\.[jt]sx$/, ""), layout);
+    const layoutParams = [...layoutIds].map(([id, module]) => {
+        if (module.page === rootLayout)
+            return `    ${str(id)}: {};`;
+        const entries = pageRoutes.filter((r) => r.layouts.some((l) => l.page === module.page));
+        const all = new Set(entries.flatMap((r) => r.params));
+        const required = (p) => entries.every((r) => r.params.includes(p));
+        return `    ${str(id)}: ${all.size ? "{ " + [...all].map((p) => `${p}${required(p) ? "" : "?"}: string`).join("; ") + " }" : "{}"};`;
+    });
+    const layoutData = [...layoutIds].flatMap(([id, module]) => {
+        const type = typeOf(module, (m) => `ModuleData<${m}>`, (m) => `ModuleData<${m}>`);
+        return type ? [`    ${str(id)}: ${type};`] : [];
+    });
+    const lines = [...data, ...actions, ...layoutData].join("\n");
+    const helpers = ["ModuleData", "ModuleActions"].filter((name) => lines.includes(name + "<"));
+    const types = [
+        HEADER,
+        ...(helpers.length ? [`import type { ${helpers.join(", ")} } from "@rivetjs/router";`] : []),
+        'declare module "@rivetjs/router" {',
+        "  interface RouteParams {",
+        ...ids.map((id) => `    ${str(id)}: ${paramsOf(id)};`),
+        "  }",
+        "  interface RouteRegistry {",
+        `    path: ${paths.length ? paths.join(" | ") : "never"};`,
+        "  }",
+        ...(data.length ? ["  interface RouteData {", ...data, "  }"] : []),
+        ...(actions.length ? ["  interface RouteActions {", ...actions, "  }"] : []),
+        ...(layoutParams.length ? ["  interface LayoutParams {", ...layoutParams, "  }"] : []),
+        ...(layoutData.length ? ["  interface LayoutData {", ...layoutData, "  }"] : []),
+        "}",
+        "export {};",
+        "",
+    ].join("\n");
+    // CSR pages mount in the browser: nothing resumes.
+    const resumeModules = mode === "csr" ? [] : [posix.join(outDir, "app.tsx"), ...[...pages.keys(), ...layouts.keys(), ...specials.keys()].map((f) => posix.join(routesDir, f))];
+    return {
+        files: mode === "csr"
+            ? { "app.tsx": app, "entry.client.tsx": client, "routes.d.ts": types }
+            : {
+                "app.tsx": app,
+                "routes.ts": routesFile,
+                "entry.server.tsx": entry,
+                "entry.dev.tsx": dev,
+                "dev-mount.tsx": devMount,
+                "routes.d.ts": types,
+                ...(contexts.length ? { "entry.resume.ts": resumeEntry } : {}),
+            },
+        resumeModules,
+    };
+}