@rivetjs/router 0.1.0-alpha.0 → 0.1.0-alpha.1

package/build/codegen.js

@@ -122,6 +122,40 @@ function wrap(providers, inner, indent) {
         ...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";
@@ -152,6 +186,9 @@ export function generate(table, options) {
     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);
@@ -246,7 +283,7 @@ export function generate(table, options) {
     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={${swap}} hold={() => heldRoutes(${k + 1})} notFound={() => null} /></div>`;
+        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})`;
     };
@@ -309,7 +346,9 @@ export function generate(table, options) {
         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 served = mode === "csr" ? "" : `_ssrLevel(work, (data) => loaded(${kit ? `applyRouteHead(data, ROUTES${name}[n]![1])` : "data"}), failed, ${land}) ?? `;
+        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},`,
@@ -329,6 +368,9 @@ export function generate(table, options) {
     // 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)]);
@@ -346,16 +388,25 @@ export function generate(table, options) {
     const app = [
         HEADER,
         `/// <reference types="vite/client" />`,
-        ...(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) ? ", Provider" : ""} } from "@rivetjs/runtime/dom";`,
+        ...(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";`] : []),
-        `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 ? ", ServerData, _layouts, _landed" + (keeps ? ", _keepIds" : "") + (nested ? ", _level, _enter, _take, _sync" : "") + ", type LayoutTable" : ""}${transitions ? ", _routeModule" : ""}${active ? ", onNavigate, _markActive" : ""}${nested || active ? ", _arm" : ""}${shadowed.length ? ", _endpoint" : ""}${forms && !single ? ", _brand, _go" : ""} } from "@rivetjs/router/client";`,
-        `import { isHttpError } from "@rivetjs/router";`,
+        ...(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.",
@@ -386,11 +437,21 @@ export function generate(table, options) {
             `const PATHS${table.name}: readonly string[] = ${str(table.routes.map((route) => at(route.pattern)))};`,
             `const ROUTES${table.name}: readonly Row[] = ${tableRows(table)};`,
         ]),
-        ...(shadowed.length
+        ...(shadowed.length || documentRows.length
             ? [
                 "const modules: (readonly [string, () => unknown])[] = PATHS.map((path, n) => [path, () => preloadPage(page(ROUTES[n]![2]), PAGES[ROUTES[n]![2]]!)]);",
-                "// 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]);`,
+                ...(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]]!)]);",
@@ -421,6 +482,34 @@ export function generate(table, options) {
         '  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 }) {",
@@ -428,7 +517,7 @@ export function generate(table, options) {
             ? [
                 "  // 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);",
+                `  const server = useContext(ServerData)${derived ? " ?? useContext(Revived)" : ""};`,
                 `  const nest = _layouts(server, router, NEST, ${nested ? levels + 1 : 0});`,
             ]
             : []),
@@ -519,32 +608,43 @@ export function generate(table, options) {
         ]),
         // 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.
-        `  const view = <div data-rivet-routes=""${go ? ' data-rivet-go=""' : ""}><Router router={${nested ? "_level(router, nest, 0, 0)" : liveTop ? "_liveRouter(router, live)" : "router"}} routes={routes} swap={${swap}} hold={heldRoutes} notFound={(url) => (${unmatched})} /></div>;`,
+        ...(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;"
+            ? `  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 : ${level(0, `<${layouts.get(rootLayout)} data={layoutData} params={noParams} url={layoutURL}>{view}</${layouts.get(rootLayout)}>`)};`
-                : `  return ${level(0, `<${layouts.get(rootLayout)} data={layoutData} params={noParams} url={layoutURL}>{view}</${layouts.get(rootLayout)}>`)};`,
+                    `  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).
-    const serverModule = (file) => (file ? `once(() => import(${str(spec(file))}))` : "undefined");
+    // 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 (`serverLoad`…): normalized from the page/layout module, merged with a
-    // sibling `*.server.ts` when there is one. Sibling-only routes load the sibling as before.
-    let inlineUsed = false;
+    // 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);
-        inlineUsed = true;
+        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}, false, ${str(posix.join(routesDir, module.page))}))`;
+            : `once(async () => serverExports(${own}, ${str(posix.join(routesDir, module.page))}))`;
     };
     const routes = [
         HEADER,
@@ -584,20 +684,20 @@ export function generate(table, options) {
         "};",
         "",
     ].join("\n");
-    const routesFile = inlineUsed
-        ? routes.replace(`import type { AppRoute } from "@rivetjs/router/server";`, `import { mergeServer, serverExports, type AppRoute } from "@rivetjs/router/server";`)
+    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";`,
-        `import { createRouter } from "@rivetjs/runtime/router/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";`,
-        `import { App } from "./app.tsx";`,
+        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)};`,
@@ -608,7 +708,7 @@ export function generate(table, options) {
                 `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.map((route) => at(route.pattern))) }) }), ...(options.prefetchEagerness && options.prefetchEagerness !== "moderate" ? { eagerness: options.prefetchEagerness } : {}) })});`,
+                `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))};`]
@@ -639,6 +739,23 @@ export function generate(table, options) {
             ]
             : []),
         "",
+        ...(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 () => (",
@@ -660,7 +777,7 @@ export function generate(table, options) {
                     ],
                 ]
                 : []),
-        ], "<App router={createRouter(input.url)} />", "      "),
+        ], derived ? "<>\n        <Links />\n        <Root s={rootData(input)} />\n      </>" : "<App router={createRouter(input.url)} />", "      "),
         "    </Provider>",
         "  );",
         "}",
@@ -844,7 +961,7 @@ export function generate(table, options) {
             .join("/") +
         "`";
     const paths = [...new Set(pageRoutes.map((r) => pathOf(r.pattern)))];
-    // Loader data per route id: the route module's `serverLoad` (in-file) or sibling loader.
+    // 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))})`)] : []),
@@ -854,7 +971,7 @@ export function generate(table, options) {
     };
     const firstOf = (id) => table.routes.find((r) => r.id === id);
     const data = ids.flatMap((id) => {
-        const type = typeOf(firstOf(id), (m) => `InlineData<${m}>`, (m) => `ModuleData<${m}>`);
+        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).
@@ -878,11 +995,11 @@ export function generate(table, options) {
         return `    ${str(id)}: ${all.size ? "{ " + [...all].map((p) => `${p}${required(p) ? "" : "?"}: string`).join("; ") + " }" : "{}"};`;
     });
     const layoutData = [...layoutIds].flatMap(([id, module]) => {
-        const type = typeOf(module, (m) => `InlineData<${m}>`, (m) => `ModuleData<${m}>`);
+        const type = typeOf(module, (m) => `ModuleData<${m}>`, (m) => `ModuleData<${m}>`);
         return type ? [`    ${str(id)}: ${type};`] : [];
     });
     const lines = [...data, ...actions, ...layoutData].join("\n");
-    const helpers = ["InlineData", "ModuleData", "ModuleActions"].filter((name) => lines.includes(name + "<"));
+    const helpers = ["ModuleData", "ModuleActions"].filter((name) => lines.includes(name + "<"));
     const types = [
         HEADER,
         ...(helpers.length ? [`import type { ${helpers.join(", ")} } from "@rivetjs/router";`] : []),

package/build/dev-errors.d.ts

@@ -13,7 +13,11 @@ export declare function devReport(server: ViteDevServer, table: () => RouteTable
 export declare function listenClientErrors(server: ViteDevServer): void;
 /**
  * Wrap the dev app handler: a reported 5xx page gets the dev error page (no `_error` view) or the
- * overlay over the app's `_error` view; an unmatched URL without a `_404` lists the routes.
+ * overlay over the app's `_error` view; an unmatched URL without a `_404` lists the routes. `reach`: the page's server
+ * reach reports (RV3011, `build/reach.ts`): an error opens the overlay over the rendered page.
  */
-export declare function devHandler(handler: AppHandler, server: ViteDevServer, table: () => RouteTable): AppHandler;
+export declare function devHandler(handler: AppHandler, server: ViteDevServer, table: () => RouteTable, reach?: (url: URL) => Promise<readonly {
+    readonly severity: "error" | "warning";
+    readonly message: string;
+}[]>): AppHandler;
 export {};

package/build/dev-errors.js

@@ -133,8 +133,9 @@ const inject = (page, markup) => {
     return at < 0 ? page + markup : page.slice(0, at) + markup + page.slice(at);
 };
 /** Inline module script opening Vite's overlay on this page (the request's ws message reached only pages already open). */
-const overlayScript = (server, failure, nonce) => `<script type="module"${nonceAttr(nonce)}>import { ErrorOverlay } from ${scriptJSON(server.config.base + "@vite/client")};` +
-    `document.body.appendChild(new ErrorOverlay(${scriptJSON(overlayError(failure))}));</script>`;
+const overlayScript = (server, failure, nonce) => overlayOf(server, overlayError(failure), nonce);
+const overlayOf = (server, error, nonce) => `<script type="module"${nonceAttr(nonce)}>import { ErrorOverlay } from ${scriptJSON(server.config.base + "@vite/client")};` +
+    `document.body.appendChild(new ErrorOverlay(${scriptJSON(error)}));</script>`;
 const STYLE = "body{margin:0;font:15px/1.5 system-ui,sans-serif;background:#fff;color:#1b1b1f}main{max-width:72rem;margin:0 auto;padding:2rem 1rem}" +
     "h1{font-size:1.4rem;margin:0 0 .5rem}code,pre{font-family:ui-monospace,SFMono-Regular,Menlo,monospace}pre{overflow:auto;padding:1rem;border-radius:6px;background:#f4f4f6;white-space:pre-wrap}" +
     ".message{color:#b00020;font-weight:600}ul{padding-left:1.2rem}li{margin:.15rem 0}small{color:#6b6b76}" +
@@ -157,10 +158,16 @@ const routeList = (server, table) => {
 const comment = (text) => `<!-- ${text.replace(/--/g, "- -")} -->`;
 /**
  * Wrap the dev app handler: a reported 5xx page gets the dev error page (no `_error` view) or the
- * overlay over the app's `_error` view; an unmatched URL without a `_404` lists the routes.
+ * overlay over the app's `_error` view; an unmatched URL without a `_404` lists the routes. `reach`: the page's server
+ * reach reports (RV3011, `build/reach.ts`): an error opens the overlay over the rendered page.
  */
-export function devHandler(handler, server, table) {
+export function devHandler(handler, server, table, reach) {
     return async (request, context) => {
+        // A page document (not a data request): its route's server reach errors first (the walk may regenerate the App).
+        const url = new URL(request.url);
+        const reachErrors = reach && request.method === "GET" && !url.searchParams.has("_rivet") && (request.headers.get("accept") ?? "text/html").includes("text/html")
+            ? (await reach(url)).filter((problem) => problem.severity === "error")
+            : [];
         const seen = [];
         const response = await failures.run(seen, () => handler(request, context));
         if (!(response.headers.get("content-type") ?? "").startsWith("text/html"))
@@ -191,6 +198,10 @@ export function devHandler(handler, server, table) {
                 "<p><small>Development only: add a <code>_404</code> page to render your own.</small></p>";
             return html(response, devPage("404 · " + path, body, devClient(server, nonce)));
         }
+        if (reachErrors.length && response.status < 400 && overlayOn(server)) {
+            const error = { message: reachErrors.map((problem) => problem.message).join("\n\n"), stack: "", plugin: "vite-plugin-rivet-router" };
+            return html(response, inject(await response.text(), comment(error.message) + overlayOf(server, error, nonce)));
+        }
         return response.body ? lateFailures(response, seen, server, nonce) : response;
     };
 }

package/build/lazy-rows.d.ts

@@ -0,0 +1,19 @@
+import type { Plugin } from "vite";
+/** The measurement mode env var: `swap` here; `on` / `off` belong to the runtime (server lazy row records, LAZY-ROWS T4, read at render). */
+export declare const LAZY_ROWS_ENV = "RIVET_LAZY_ROWS";
+/** Set by the measurement tools for their build children: production builds honour `RIVET_LAZY_ROWS` only with it. */
+export declare const LAZY_ROWS_HARNESS_ENV = "RIVET_LAZY_ROWS_HARNESS";
+/** Whether the swap harness applies to a Vite run (`command`): dev server, or a harness build. `on` / `off` → null (runtime
+ * values, no build change). Throws on unknown values. */
+export declare function lazyRowsMode(command: "serve" | "build", env?: Readonly<Record<string, string | undefined>>): "swap" | null;
+/**
+ * Lazy rows proper (LAZY-ROWS T5, `on`): a build whose resume runtime materialises them needs
+ * `rivetRouter({ resume: { lazyRows: true } })`. The measurement tools (docs-kit `check-examples`,
+ * `scripts/lazy-rows/probe.ts`) build app configs they do not own: with `RIVET_LAZY_ROWS=on` AND `LAZY_ROWS_HARNESS_ENV`
+ * (which only they set for their build children) `rivetRouter` turns the option on for that build (LAZY-T5B).
+ */
+export declare function lazyRowsBuild(env?: Readonly<Record<string, string | undefined>>): boolean;
+/** The runtime module the server entry imports in swap mode (no package export: not public API). */
+export declare function lazyRowsModule(): string;
+/** Vite plugin: in swap mode the generated server entry (`entry`) installs the swap row hook before anything else. */
+export declare function lazyRowsHarness(entry: () => string): Plugin;

package/build/lazy-rows.js

@@ -0,0 +1,59 @@
+// Lazy collection rows, T1 measurement harness (spec docs/design/specs/2026-10-19-lazy-collection-rows-design.md §3.4, R2):
+// `RIVET_LAZY_ROWS=swap` renders every For row inside a resumable region unrecorded and re-creates the region in the
+// browser on the first interaction (create + swap). A bytes / server-CPU baseline only — it must never ship (the event
+// target is replaced under the pointer, inputs lose their value, focus moves), so it is no option of `rivet.config` /
+// `rivetRouter()`: only this environment variable turns it on, and only in the dev server or in a build whose environment
+// also carries `LAZY_ROWS_HARNESS_ENV` (docs-kit `check-examples` / `scripts/lazy-rows/probe.ts` set it for their
+// build children). Everything it adds is server code (`@rivetjs/runtime` `server-lazy-swap.ts`, installed first by the
+// generated server entry): browser bundles are unchanged.
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+/** The measurement mode env var: `swap` here; `on` / `off` belong to the runtime (server lazy row records, LAZY-ROWS T4, read at render). */
+export const LAZY_ROWS_ENV = "RIVET_LAZY_ROWS";
+/** Set by the measurement tools for their build children: production builds honour `RIVET_LAZY_ROWS` only with it. */
+export const LAZY_ROWS_HARNESS_ENV = "RIVET_LAZY_ROWS_HARNESS";
+/** Whether the swap harness applies to a Vite run (`command`): dev server, or a harness build. `on` / `off` → null (runtime
+ * values, no build change). Throws on unknown values. */
+export function lazyRowsMode(command, env = process.env) {
+    const value = env[LAZY_ROWS_ENV];
+    if (!value || value === "on" || value === "off")
+        return null;
+    if (value !== "swap")
+        throw new Error(`${LAZY_ROWS_ENV}=${value}: the only measurement mode is "swap" ("on" / "off": server lazy row records)`);
+    if (command === "serve" || env[LAZY_ROWS_HARNESS_ENV] === "1")
+        return "swap";
+    console.warn(`rivetRouter: ${LAZY_ROWS_ENV}=swap ignored: a measurement mode for the dev server and the lazy-rows tools only`);
+    return null;
+}
+/**
+ * Lazy rows proper (LAZY-ROWS T5, `on`): a build whose resume runtime materialises them needs
+ * `rivetRouter({ resume: { lazyRows: true } })`. The measurement tools (docs-kit `check-examples`,
+ * `scripts/lazy-rows/probe.ts`) build app configs they do not own: with `RIVET_LAZY_ROWS=on` AND `LAZY_ROWS_HARNESS_ENV`
+ * (which only they set for their build children) `rivetRouter` turns the option on for that build (LAZY-T5B).
+ */
+export function lazyRowsBuild(env = process.env) {
+    return env[LAZY_ROWS_ENV] === "on" && env[LAZY_ROWS_HARNESS_ENV] === "1";
+}
+/** The runtime module the server entry imports in swap mode (no package export: not public API). */
+export function lazyRowsModule() {
+    return join(dirname(createRequire(import.meta.url).resolve("@rivetjs/runtime/server-resume")), "server-lazy-swap.ts");
+}
+/** Vite plugin: in swap mode the generated server entry (`entry`) installs the swap row hook before anything else. */
+export function lazyRowsHarness(entry) {
+    let active = false;
+    return {
+        name: "vite-plugin-rivet-lazy-rows",
+        enforce: "pre",
+        config(_config, env) {
+            active = lazyRowsMode(env.command) !== null;
+            if (active)
+                console.warn(`rivetRouter: ${LAZY_ROWS_ENV}=swap: For rows render unrecorded (measurement build, never ship it)`);
+        },
+        transform(code, id, options) {
+            if (!active || !options?.ssr || id.split("?")[0] !== entry())
+                return null;
+            // A call, not a bare import: the runtime package is `sideEffects: false`.
+            return { code: `import { _lazyRowsSwap } from ${JSON.stringify(lazyRowsModule())};\n_lazyRowsSwap();\n` + code, map: null };
+        },
+    };
+}

package/build/migrate.d.ts

@@ -1,15 +1,31 @@
-export declare const RENAMES: Readonly<Record<string, string>>;
+import type TS from "typescript";
+/** Wrapper and conventional export name per former magic name. */
+export declare const WRAPPERS: Readonly<Record<string, {
+    readonly wrapper: string;
+    readonly name: string;
+}>>;
+/** Former sibling `*.server.ts` names → the in-file name they meant. */
+export declare const SIBLING: Readonly<Record<string, string>>;
 export interface MigrateReport {
     /** Changed files (absolute) → new contents. */
     readonly changes: ReadonlyMap<string, string>;
-    /** `file: old → new` per renamed export. */
+    /** `file: old → new = wrapper(…)` per rewritten export. */
     readonly renamed: readonly string[];
     /** Exports left alone, with the reason. */
     readonly skipped: readonly string[];
 }
 /**
- * Compute the migration for `*.server.ts` modules under `routesDir`; references are searched in every
- * source module under `projectDir`. Nothing is written (see `writeMigration`).
+ * Compute the migration for route modules under `routesDir` (pages, layouts, plain `.ts` endpoints,
+ * sibling `*.server.ts`); references are searched in every source module under `projectDir`. Nothing is
+ * written (see `writeMigration`).
  */
 export declare function migrateServerExports(projectDir: string, routesDir: string): Promise<MigrateReport>;
+/** Migrate one module's text on its own (no other modules: references elsewhere are not renamed). */
+export declare function migrateSource(ts: typeof TS, text: string, fileName: string): {
+    text: string;
+    renamed: readonly string[];
+    skipped: readonly string[];
+};
+/** The migration over in-memory `texts` (absolute paths); `targets`: the route modules to rewrite. */
+export declare function migrateTexts(ts: typeof TS, texts: ReadonlyMap<string, string>, targets: readonly string[], root: string): MigrateReport;
 export declare function writeMigration(report: MigrateReport): Promise<void>;