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

package/build/dev-errors.d.ts

@@ -0,0 +1,23 @@
+import type { ViteDevServer } from "vite";
+import type { DevSymbolInfo } from "@rivetjs/compiler/vite";
+import type { RouteTable } from "./routes.js";
+import type { AppHandler, ErrorInfo } from "../server/handler.js";
+/** A resume symbol the compiler plugin compiled for dev SSR (`DevResume.describe`). */
+type Describe = (id: string) => DevSymbolInfo | undefined;
+/**
+ * Dev `onError`: source-map the stack, log it, send it to Vite's overlay (open pages, e.g. during
+ * client navigation) and remember it for the request's dev error page.
+ */
+export declare function devReport(server: ViteDevServer, table: () => RouteTable, routesPath: string, describe?: Describe): (error: unknown, _request: Request, info?: ErrorInfo) => void;
+/** Browser errors forwarded by the dev entry (`import.meta.hot.send("rivet:client-error")`) open that page's overlay. */
+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. `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, reach?: (url: URL) => Promise<readonly {
+    readonly severity: "error" | "warning";
+    readonly message: string;
+}[]>): AppHandler;
+export {};

package/build/dev-errors.js

@@ -0,0 +1,247 @@
+// Dev server error surfaces (`vite serve` only; never part of a build): server failures reach Vite's
+// error overlay and a dev error page with the source-mapped stack, unmatched URLs list the route
+// table, and browser errors the dev entry forwards (`rivet:client-error`) open the overlay too.
+import { AsyncLocalStorage } from "node:async_hooks";
+import { join } from "node:path";
+import { compileRoutes } from "@rivetjs/runtime/router/server";
+import { escapeAttribute, escapeText } from "@rivetjs/runtime/escape";
+import { escapeJSON } from "@rivetjs/runtime/resume-format";
+const failures = new AsyncLocalStorage();
+/** JSON for an inline `<script>` (no `</script>` / `<!--`, no raw U+2028/U+2029), as resume state. */
+const scriptJSON = (value) => escapeJSON(JSON.stringify(value));
+const overlayOn = (server) => {
+    const hmr = server.config.server.hmr;
+    return !(hmr === false || (typeof hmr === "object" && hmr.overlay === false));
+};
+/** Diagnostic code (`RV1001`…) of an error that carries one, as an overlay message prefix. */
+const codeOf = (error) => {
+    const code = error?.code;
+    return typeof code === "string" && /^RV\d{4}$/.test(code) ? `[${code}] ` : "";
+};
+/**
+ * Dev `onError`: source-map the stack, log it, send it to Vite's overlay (open pages, e.g. during
+ * client navigation) and remember it for the request's dev error page.
+ */
+export function devReport(server, table, routesPath, describe) {
+    return (error, _request, info) => {
+        if (error instanceof Error)
+            server.ssrFixStacktrace(error);
+        // Without info: a render failure reported by a custom renderer (app renders report `phase: "render"`).
+        const phase = info?.phase ?? "render";
+        const route = info?.route;
+        const file = route === undefined ? undefined : table().routes.find((entry) => entry.id === route)?.page;
+        const text = error instanceof Error ? error.message : String(error);
+        const symbol = describe && resumeSymbol(text, describe);
+        const id = symbol?.file ?? (file ? join(routesPath, file) : undefined);
+        const note = symbol ? symbolNote(text, symbol) : describe ? missingNote(text) : "";
+        const message = codeOf(error) + text + note;
+        const stack = error instanceof Error ? (error.stack ?? "") : "";
+        server.config.logger.error(`[rivet] ${phase} failed${route === undefined ? "" : ` (route "${route}")`}: ${note ? message + "\n" : ""}${stack || message}`);
+        const failure = { message, stack, phase, route, id, ...(symbol ? { loc: { file: symbol.file, line: symbol.line, column: symbol.column } } : {}) };
+        failures.getStore()?.push(failure);
+        if (overlayOn(server))
+            server.ws.send({ type: "error", err: overlayError(failure) });
+    };
+}
+const overlayError = (failure) => ({
+    message: `${failure.phase} failed${failure.route === undefined ? "" : ` in route "${failure.route}"`}: ${failure.message}`,
+    stack: failure.stack,
+    plugin: "rivet",
+    ...(failure.id ? { id: failure.id } : {}),
+    ...(failure.loc ? { loc: failure.loc } : {}),
+});
+// Symbol ids in resume recorder errors: `Cannot resume <id>: capture `<name>` …` (dev; `#<n>` without names), `… no chunk for <id>`.
+const SYMBOL_ID = /(?:^|[\s(])((?:[\w.@-]+\/)*[\w.@-]+\.[cm]?[jt]sx?#[\w$]+)/;
+/** The resume symbol a recorder error names, when the dev server compiled it. */
+function resumeSymbol(message, describe) {
+    const id = SYMBOL_ID.exec(message)?.[1];
+    return id === undefined ? undefined : describe(id);
+}
+const KINDS = {
+    event: "event handler",
+    attr: "attribute binding",
+    bind: "text binding",
+    region: "child region",
+    model: "model:",
+    effect: "clientEffect",
+    clientEvent: "clientEvent",
+    computed: "computed",
+    equals: "equals comparator",
+    fn: "function",
+    slot: "slot",
+    spread: "spread",
+};
+/** `in <Component> (file:line:col), <kind>; capture `name` (file:line:col)` for an error naming a symbol. */
+function symbolNote(message, symbol) {
+    const where = (line, column) => `${symbol.module}:${line}:${column}`;
+    let note = `\n  in <${symbol.component === "default" ? "default export" : symbol.component}> (${where(symbol.line, symbol.column)}), ${KINDS[symbol.kind] ?? symbol.kind} ${symbol.id}`;
+    // `capture `name`` (dev manifest names, Function Bridge T19) or `capture #<n>` (no names).
+    const named = /capture `([^`]+)`/.exec(message)?.[1];
+    const index = named === undefined ? /capture #(\d+)/.exec(message)?.[1] : undefined;
+    const capture = named !== undefined ? symbol.captures.find((c) => c.name === named) : index === undefined ? undefined : symbol.captures[Number(index)];
+    if (capture)
+        note += `\n  capture \`${capture.name}\` (${where(capture.line, capture.column)})`;
+    return note;
+}
+/** Dev note for a symbol the dev manifest has no chunk for (no SSR compile defined it). */
+const missingNote = (message) => {
+    const id = /no chunk for (\S+)/.exec(message)?.[1];
+    return id === undefined
+        ? ""
+        : `\n  dev: no module the dev server compiled in resume mode defines ${id.replace(/[.,;]$/, "")} (is ${id.slice(0, id.indexOf("#"))} in resume.modules?)`;
+};
+/** Browser errors forwarded by the dev entry (`import.meta.hot.send("rivet:client-error")`) open that page's overlay. */
+export function listenClientErrors(server) {
+    server.ws.on("rivet:client-error", (data, client) => {
+        const message = String(data?.message ?? "Unknown error");
+        // Benign ResizeObserver loop notice (older dev clients still forward it): no overlay, no error log.
+        if (/^ResizeObserver loop (completed with undelivered notifications|limit exceeded)/.test(message))
+            return;
+        const stack = typeof data?.stack === "string" ? data.stack : "";
+        server.config.logger.error(`[rivet] browser error: ${stack || message}`);
+        if (overlayOn(server))
+            client.send({ type: "error", err: { message: "Browser error: " + message, stack, plugin: "rivet" } });
+    });
+}
+let matcher;
+const matches = (table, url) => {
+    if (matcher?.table !== table)
+        matcher = { table, match: compileRoutes(table.routes.map((route) => ({ path: route.pattern, render: () => route }))) };
+    return matcher.match(url) != null;
+};
+/** The `_404` an unmatched URL renders (longest folder prefix, else the root one). */
+const notFoundFor = (table, path) => table.notFounds?.find(({ prefix }) => path === prefix || path.startsWith(prefix + "/"))?.page ?? table.notFound;
+/** Route patterns, once each, in table order: `[pattern, endpoint-only]`. */
+const patterns = (table) => {
+    const seen = new Map();
+    for (const route of table.routes)
+        if (!seen.has(route.pattern))
+            seen.set(route.pattern, !route.page);
+    return [...seen];
+};
+const nonceOf = (response) => /'nonce-([^']+)'/.exec(response.headers.get("content-security-policy") ?? "")?.[1];
+const nonceAttr = (nonce) => (nonce === undefined ? "" : ` nonce="${escapeAttribute(nonce)}"`);
+const html = (response, body) => {
+    const headers = new Headers(response.headers);
+    headers.delete("content-length");
+    headers.set("content-type", "text/html; charset=utf-8");
+    return new Response(body, { status: response.status, headers });
+};
+/** Insert markup before the document's last `</body>` (else append). */
+const inject = (page, markup) => {
+    const at = page.lastIndexOf("</body>");
+    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) => 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}" +
+    "@media (prefers-color-scheme:dark){body{background:#151518;color:#e8e8ec}pre{background:#222228}.message{color:#ff8a8a}small{color:#9a9aa6}a{color:#8ab4ff}}";
+const devPage = (title, body, scripts) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">` +
+    `<title>${escapeText(title)}</title><style>${STYLE}</style></head><body><main>${body}</main>${scripts}</body></html>`;
+/** Vite's client (HMR, overlay) plus a reload when server code changes (`rivet:data`) or the route table does. */
+const devClient = (server, nonce) => `<script type="module"${nonceAttr(nonce)}>import { createHotContext } from ${scriptJSON(server.config.base + "@vite/client")};` +
+    `createHotContext("/@rivet/dev-page").on("rivet:data", () => location.reload());</script>`;
+/** Route list markup: static patterns link to their page. */
+const routeList = (server, table) => {
+    const items = patterns(table).map(([pattern, endpoint]) => {
+        const label = `<code>${escapeText(pattern)}</code>`;
+        const link = !endpoint && !/[:*]/.test(pattern) ? `<a href="${escapeAttribute(server.config.base + pattern.slice(1))}">${label}</a>` : label;
+        return `<li>${link}${endpoint ? " <small>endpoint</small>" : ""}</li>`;
+    });
+    return items.length ? `<ul id="rivet-dev-routes">${items.join("")}</ul>` : "<p>No routes yet: add a page under the routes directory.</p>";
+};
+/** HTML comment (`--` cannot appear inside one). */
+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. `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, 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"))
+            return response;
+        const nonce = nonceOf(response);
+        const routes = table();
+        const failure = seen[0];
+        if (failure && response.status >= 500) {
+            const own = failure.route === undefined ? undefined : routes.routes.find((entry) => entry.id === failure.route);
+            const overlay = overlayOn(server) ? overlayScript(server, failure, nonce) : "";
+            const where = comment(`rivet dev: ${failure.phase} failed${failure.route === undefined ? "" : ` in route "${failure.route}"`}: ${failure.message}`);
+            // The app's `_error` view renders as in production; the overlay shows the details over it.
+            if (own?.error ?? routes.error)
+                return html(response, inject(await response.text(), where + overlay));
+            const body = `<h1>Server error</h1><p id="rivet-dev-where">${failure.route === undefined ? "" : `Route <code>${escapeText(failure.route)}</code>, `}phase <code>${escapeText(failure.phase)}</code></p>` +
+                `<pre class="message">${escapeText(failure.message)}</pre>${failure.stack ? `<pre class="stack">${escapeText(failure.stack)}</pre>` : ""}` +
+                "<p><small>Development only: production answers with a generic message and a digest. Add an <code>_error</code> page to render your own.</small></p>";
+            return html(response, devPage(`${response.status} · ${failure.message}`, body, devClient(server, nonce) + overlay));
+        }
+        if (response.status === 404 && request.method === "GET" && !matches(routes, new URL(request.url))) {
+            const path = new URL(request.url).pathname;
+            const list = patterns(routes)
+                .map(([pattern]) => pattern)
+                .join(" ");
+            if (notFoundFor(routes, path))
+                return html(response, inject(await response.text(), comment(`rivet dev: no route matches ${path}. Routes: ${list}`)));
+            const body = `<h1>No route matches <code>${escapeText(path)}</code></h1><p>Routes:</p>${routeList(server, routes)}` +
+                "<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;
+    };
+}
+/**
+ * A render that fails after the response started (status sent; e.g. the resume state, encoded at the
+ * end of the shell) ends the document early (failure marker, or an errored body): the page then ends
+ * with the hint comment and opens the overlay itself (the ws message only reaches pages already
+ * open), and reloads on the next update.
+ */
+function lateFailures(response, seen, server, nonce) {
+    const reader = response.body.getReader();
+    const encoder = new TextEncoder();
+    const before = seen.length;
+    const hint = (failure) => {
+        const where = comment(`rivet dev: ${failure.phase} failed${failure.route === undefined ? "" : ` in route "${failure.route}"`}: ${failure.message}`);
+        const reload = `<script type="module"${nonceAttr(nonce)}>import { createHotContext } from ${scriptJSON(server.config.base + "@vite/client")};` +
+            `const hot = createHotContext("/@rivet/dev-page");hot.on("rivet:data", () => location.reload());hot.on("vite:beforeUpdate", () => location.reload());</script>`;
+        return encoder.encode(where + (overlayOn(server) ? overlayScript(server, failure, nonce) : "") + reload);
+    };
+    const body = new ReadableStream({
+        async pull(controller) {
+            let chunk;
+            try {
+                chunk = await reader.read();
+            }
+            catch (error) {
+                const failure = seen[0];
+                if (!failure)
+                    return controller.error(error);
+                controller.enqueue(hint(failure));
+                return controller.close();
+            }
+            if (!chunk.done)
+                return controller.enqueue(chunk.value);
+            // A failure reported while the body streamed (the document closed with its failure marker).
+            if (seen.length > before)
+                controller.enqueue(hint(seen[before]));
+            controller.close();
+        },
+        cancel: (reason) => reader.cancel(reason),
+    });
+    return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+}

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

@@ -0,0 +1,31 @@
+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 = wrapper(…)` per rewritten export. */
+    readonly renamed: readonly string[];
+    /** Exports left alone, with the reason. */
+    readonly skipped: readonly string[];
+}
+/**
+ * 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>;