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

package/build/vite.js

@@ -11,7 +11,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { lstat, mkdir, readdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { rivet, _factsResolve, } from "@rivetjs/compiler/vite";
+import { rivet, _factsResolve, declaredServerOnly, isServerOnly, serverOnlyStub, } from "@rivetjs/compiler/vite";
 import { updateEditorManifest } from "@rivetjs/compiler/editor";
 import { scanRoutes, _serverExportsOf } from "./routes.js";
 import { generate } from "./codegen.js";
@@ -23,14 +23,29 @@ import { compileRules } from "../server/route-cache.js";
 export { mergeRouteCSS } from "./route-css.js";
 import { bundleRouteCSS, devRouteCSS, INLINE_CSS, inlineCSS, mergeRouteCSS, ROUTE_CSS } from "./route-css.js";
 import { devHandler, devReport, listenClientErrors } from "./dev-errors.js";
+import { lazyRowsBuild, lazyRowsHarness } from "./lazy-rows.js";
+import { analyzeReach, serverOnlyOption, RV_REACH } from "./reach.js";
+import { compileRoutes } from "@rivetjs/runtime/router/server";
 import { adapterOptions, targetBuildConfig, targetEntryPlugin } from "../adapters/target-build.js";
 /** The router's own base-path module (its `BASE` reads Vite's `BASE_URL`). */
 const BASE_MODULE = fileURLToPath(new URL("../shared/base.js", import.meta.url));
 /** The router's trailing-slash module (its `TRAILING_SLASH` constant is rewritten when the option is set). */
 const SLASH_MODULE = fileURLToPath(new URL("../shared/slash.js", import.meta.url));
 const SLASH_DEFAULT = '"ignore" as TrailingSlash';
+/** The shell cache loader (`SHELL_BUILD`, rewritten to an `import()` when a route rule has `shell`). */
+const SHELL_MODULE = fileURLToPath(new URL("../server/shell-build.js", import.meta.url));
+/** `SHELL_BUILD`'s declaration in the source (`.ts`, with its type cast) and in the published `.js` (cast stripped). */
+const SHELL_DEFAULT = /export const SHELL_BUILD = undefined(?: as [^;]+)?;/;
+/** The shell cache module the rewritten loader imports (by file path: also what keeps it in the published package). */
+const SHELL_CACHE = fileURLToPath(new URL("../server/shell-cache.js", import.meta.url));
 const posix = (path) => path.split(sep).join("/");
 const EMPTY = "\0rivet-router-empty";
+/** Client build: a document route's page module as `.rivet/app.tsx` imports it (no browser code for the page). */
+const DOCUMENT_PAGE = "\0rivet-document-page:";
+/** Browser stand-in of a server-only module imported only from document routes' graphs (`serverOnlyStub`). */
+const STAND_IN = "\0rivet-server-only:";
+/** The file behind a module id (virtual compiler parts `\0rivet-resume-part:/abs/file.tsx?…` included), no query. */
+const fileOf = (id) => (id.startsWith("\0") ? id.slice(id.indexOf(":") + 1) : id).split("?")[0];
 /** Write generated files whose contents changed; returns whether anything changed. */
 async function sync(dir, files) {
     await mkdir(dir, { recursive: true });
@@ -143,6 +158,8 @@ export async function generateRoutes(root, options = {}) {
         ...(options.preload?.background !== undefined ? { preloadBackground: options.preload.background } : {}),
         ...(options.routeRules && Object.keys(options.routeRules).length ? { routeRules: options.routeRules } : {}),
         ...(options.clientRouter !== undefined ? { clientRouter: options.clientRouter } : {}),
+        ...(options.documents?.length ? { documents: options.documents } : {}),
+        ...(options.derived ? { derived: true } : {}),
     });
     const changed = await sync(resolve(root, outDir), generated.files);
     // No router contexts: the compiler's default resume entry (drop a stale generated one).
@@ -225,6 +242,8 @@ export function rivetRouter(options = {}) {
         ...(options.preload ? { preload: options.preload } : {}),
         ...(options.routeRules ? { routeRules: options.routeRules } : {}),
         ...(options.clientRouter !== undefined ? { clientRouter: options.clientRouter } : {}),
+        // Derived resume model (M2 R5): the generated `Root` boundary carries the route payload as data.
+        ...(options.resume?.model === "derived" && mode !== "csr" ? { derived: true } : {}),
     };
     if (options.routeRules !== undefined) {
         // Checked at config time (same checks as at server start, except the origin `isr` needs: a server option), and
@@ -257,7 +276,9 @@ export function rivetRouter(options = {}) {
                 Object.keys(inlineOption).every((key) => key === "maxTotalBrotli") &&
                 (inlineOption.maxTotalBrotli === undefined || (Number.isSafeInteger(inlineOption.maxTotalBrotli) && inlineOption.maxTotalBrotli >= 0))))
         throw new Error(`rivetRouter: inlineStylesheets must be "auto", "always", "never" or { maxTotalBrotli: <bytes> } (got ${JSON.stringify(inlineOption)})`);
+    const serverOnly = serverOnlyOption(options.serverOnly);
     const slash = options.trailingSlash ?? "ignore";
+    const shellBuild = Object.values(options.routeRules ?? {}).some((rule) => Boolean(rule?.shell));
     if (slash !== "ignore" && slash !== "never" && slash !== "always")
         throw new Error(`rivetRouter: trailingSlash must be "ignore", "never" or "always" (got ${JSON.stringify(slash)})`);
     // Filled in `config`, which runs before the compiler plugin reads it in `configResolved`.
@@ -271,6 +292,11 @@ export function rivetRouter(options = {}) {
         dev: options.dev?.resume !== false,
         // Every app component module a route imports resumes without being listed in `resume.modules`.
         appModules: options.resume?.appModules ?? true,
+        // Lazy rows measurement builds (`RIVET_LAZY_ROWS=on` + the harness flag of the lazy-rows tools): the option on.
+        ...(lazyRowsBuild() ? { lazyRows: true } : {}),
+        // Derived model (M2 R5): `.rivet/app.tsx`'s default export (`Root`) is an independent root boundary (its props =
+        // the route payload as data), like a route module's default export.
+        ...(options.resume?.model === "derived" && mode !== "csr" ? { roots: [...(options.resume.roots ?? []), posix(join(outDir, "app.tsx"))] } : {}),
     };
     // The generated resume entry (when there is one) provides the router's contexts (navigation state,
     // search params) to resumed regions.
@@ -286,6 +312,33 @@ export function rivetRouter(options = {}) {
     };
     let root = process.cwd();
     let table = { routes: [] };
+    // Server reach (`build/reach.ts`): computed in `configResolved` (before any module compiles), re-run in dev after edits.
+    let reach = null, reachDirty = false, reachRun = Promise.resolve(), resolvedConfig = null, resolver = null, patterns = [...serverOnly.modules], building = false;
+    // Document routes' page files (absolute → routes-relative), client builds.
+    let documentPages = new Map();
+    /** Walk the routes' browser graphs; true when the document routes changed (codegen input). */
+    const analyze = async () => {
+        if (!resolvedConfig || mode === "csr")
+            return false;
+        resolver ??= resolvedConfig.createResolver();
+        const resolveFor = resolver;
+        reach = await analyzeReach({
+            root,
+            routesDir: resolve(root, routesDir),
+            table,
+            resolve: (spec, importer) => resolveFor(spec, importer, false, false),
+            serverOnly: patterns,
+            reach: serverOnly.reach,
+            routeModules: new Set(routeModules(table, routesDir).map((file) => resolve(root, file))),
+            config: resolvedConfig,
+        });
+        documentPages = new Map([...reach.documents.keys()].map((page) => [resolve(root, routesDir, page), page]));
+        const documents = [...reach.documents.keys()].sort();
+        if (documents.join("\0") === (codegen.documents ?? []).join("\0"))
+            return false;
+        codegen.documents = documents;
+        return true;
+    };
     const devtools = options.devtools ?? true;
     const css = options.css ? { css: options.css } : {};
     // Filled in `config` and on route changes: in-file server exports leave the browser build.
@@ -432,8 +485,32 @@ export function rivetRouter(options = {}) {
                 },
             };
         },
+        // Server reach: every route's browser graph, before the first module compiles (codegen marks document routes).
+        async configResolved(config) {
+            resolvedConfig = config;
+            resolver = null;
+            building = config.command === "build";
+            patterns = [...serverOnly.modules, ...declaredServerOnly(config.plugins)];
+            if (mode === "csr")
+                return;
+            if (await analyze())
+                await generateRoutes(root, codegen);
+        },
+        buildStart() {
+            if (!building || !reach)
+                return;
+            const client = this.environment?.config?.consumer !== "server";
+            // Warnings once (client build); errors fail either build.
+            if (client)
+                for (const problem of reach.problems)
+                    if (problem.severity === "warning")
+                        this.warn(problem.message);
+            const errors = reach.problems.filter((problem) => problem.severity === "error");
+            if (errors.length)
+                this.error({ message: errors.map((problem) => problem.message).join("\n\n"), plugin: "vite-plugin-rivet-router", pluginCode: RV_REACH });
+        },
         resolveId(id, importer, resolveOptions) {
-            if (id === EMPTY)
+            if (id === EMPTY || id.startsWith(DOCUMENT_PAGE) || id.startsWith(STAND_IN))
                 return id;
             // `x.server.ts` modules hold secrets and server code: never part of a browser graph.
             if (!importer || resolveOptions?.ssr || this.environment?.config?.consumer === "server")
@@ -441,21 +518,51 @@ export function rivetRouter(options = {}) {
             // The compiler's resume grouping resolves every specifier its facts list (type-only imports too): not an import.
             if (_factsResolve(id, importer))
                 return null;
-            if (/\.server(?:\.[cm]?[jt]sx?)?$/.test(id.split("?")[0]) || id === "@rivetjs/router/server-only")
+            const from = fileOf(importer);
+            // Client build: the App's import of a document route's page — the browser never renders it (links load its document).
+            if (building && documentPages.size && /^\.\.?\//.test(id) && from === resolve(root, outDir, "app.tsx")) {
+                const page = documentPages.get(resolve(dirname(from), id.split("?")[0]));
+                if (page)
+                    return DOCUMENT_PAGE + page;
+            }
+            if (isServerOnly(patterns, id)) {
+                // Reached only from document routes' graphs (their resumed parts): a stand-in that throws on use, never the module.
+                if (reach?.documentOnly.has(from))
+                    return STAND_IN + (reach.targets.get(from + "\0" + id) ?? id);
                 this.error({
                     message: `[rivet:router] ${id} is server-only and cannot be imported by browser code (imported from ${posix(importer)})` +
-                        "\n  fix: read it in a server export (`serverLoad`, `serverActions`, `onGet`, …) and pass the data to the page; type-only imports (`import type`) are fine" +
-                        "\n  docs: https://rivetjs.dev/guides/security/server-only-code",
+                        "\n  fix: read it in a server export (`load(…)`, `actions(…)`, `onGet(…)`, …) and pass the data to the page; type-only imports (`import type`) are fine" +
+                        "\n  docs: https://rivetjs.severyn.pro/guides/security/server-only-code",
                     id: importer,
                     plugin: "vite-plugin-rivet-router",
                 });
+            }
+            return null;
+        },
+        load(id) {
+            if (id === EMPTY)
+                return "export {};\n";
+            if (id.startsWith(DOCUMENT_PAGE)) {
+                const page = id.slice(DOCUMENT_PAGE.length);
+                const message = `[rivet:router] ${posix(join(routesDir, page))} is a document route (its browser graph reaches a server-only module): its links load the document, the browser never renders it`;
+                return `export default function DocumentRoute() {\n  throw new Error(${JSON.stringify(message)});\n}\n`;
+            }
+            if (id.startsWith(STAND_IN)) {
+                const key = id.slice(STAND_IN.length);
+                const shown = key.startsWith("/") ? posix(relative(root, key)) : key;
+                return serverOnlyStub(shown, reach?.chains.get(key) ?? [], reach?.names.get(key) ?? []);
+            }
             return null;
         },
-        load: (id) => (id === EMPTY ? "export {};\n" : null),
         // i18n client build: `BASE` is the app base, not the locale's asset base (`BASE_URL`). Only this
         // build's copy of shared/base.ts changes, so other apps' bundles stay byte-identical.
         // `trailingSlash`: the policy constant (client and server bundles); unset, the module stays as is.
         transform(code, id, transformOptions) {
+            if (shellBuild && id.split("?")[0] === SHELL_MODULE) {
+                if (!SHELL_DEFAULT.test(code))
+                    this.error("rivetRouter: server/shell-build.ts no longer declares SHELL_BUILD as expected");
+                return { code: code.replace(SHELL_DEFAULT, `export const SHELL_BUILD = () => import(${JSON.stringify(SHELL_CACHE)});`), map: null };
+            }
             if (slash !== "ignore" && id.split("?")[0] === SLASH_MODULE) {
                 if (!code.includes(SLASH_DEFAULT))
                     this.error("rivetRouter: shared/slash.ts no longer declares TRAILING_SLASH as expected");
@@ -552,6 +659,9 @@ export function rivetRouter(options = {}) {
                     table = next;
                     serverExports.modules.splice(0, serverExports.modules.length, ...routeModules(table, routesDir));
                     inFile = serverFiles(table);
+                    // A new route table (or new document routes): the browser graphs are walked again on the next page request.
+                    if (changed)
+                        reachDirty = true;
                     if (changed && !closed)
                         server.ws.send({ type: "full-reload" });
                     return changed;
@@ -563,6 +673,52 @@ export function rivetRouter(options = {}) {
             const logged = (fn) => (file) => void fn(file).catch((error) => server.config.logger.error("rivet router: " + (error instanceof Error ? (error.stack ?? error.message) : String(error))));
             server.watcher.on("add", logged(regenerate));
             server.watcher.on("unlink", logged(regenerate));
+            // Any source edit can change what a route's browser graph reaches (re-walked lazily, changed files only).
+            const stale = (file) => {
+                if (SOURCE.test(file))
+                    reachDirty = true;
+            };
+            server.watcher.on("add", stale);
+            server.watcher.on("unlink", stale);
+            server.watcher.on("change", stale);
+            // Dev server reach: a page's RV3011 reports on its load (terminal once per report, overlay on every load of an
+            // error); new document routes regenerate the App (full reload).
+            const reported = new Set();
+            let routeMatch;
+            const devReach = async (url) => {
+                if (mode === "csr")
+                    return [];
+                if (reachDirty) {
+                    reachDirty = false;
+                    const run = reachRun.then(async () => {
+                        if (!closed && (await analyze()))
+                            await refresh();
+                    });
+                    reachRun = run.catch(() => { });
+                    await run;
+                }
+                if (!reach?.problems.length)
+                    return [];
+                if (routeMatch?.table !== table) {
+                    const at = (pattern) => (codegen.base ? (pattern === "/" ? codegen.base : codegen.base + pattern) : pattern);
+                    const match = compileRoutes(table.routes.filter((route) => route.page).map((route) => ({ path: at(route.pattern), render: () => route })));
+                    routeMatch = { table, match: (target) => match(target)?.route.render(undefined, null) };
+                }
+                const route = routeMatch.match(url);
+                if (!route)
+                    return [];
+                const files = new Set([route.page, route.notFound, route.error, ...route.layouts.map((layout) => layout.page)].filter(Boolean));
+                const found = reach.problems.filter((problem) => problem.files.some((file) => files.has(file)));
+                for (const problem of found)
+                    if (!reported.has(problem.message)) {
+                        reported.add(problem.message);
+                        if (problem.severity === "error")
+                            server.config.logger.error(problem.message);
+                        else
+                            server.config.logger.warn(problem.message);
+                    }
+                return found;
+            };
             // A source starts using a router feature (search params, navigate(), useParams()): generate it
             // from now on (regenerate + full reload). A dev server never turns one off again.
             const features = async (file) => {
@@ -660,7 +816,7 @@ export function rivetRouter(options = {}) {
                                 ...(i18n ? { i18n: { locales: i18n.locales } } : {}),
                                 onError,
                             });
-                            listener = createListener({ handler: devHandler(handler, server, () => table), compress: false }).listener;
+                            listener = createListener({ handler: devHandler(handler, server, () => table, devReach), compress: false }).listener;
                             listeners.set(entry, listener);
                         }
                         // Vite's base middleware strips the base from `req.url`: route patterns carry it.
@@ -691,6 +847,8 @@ export function rivetRouter(options = {}) {
     return [
         router,
         ...plugins,
+        // Measurement only (`RIVET_LAZY_ROWS=swap`, dev / lazy-rows tools): inert otherwise.
+        lazyRowsHarness(() => resolve(root, outDir, "entry.server.tsx")),
         ...(adapter ? [targetEntryPlugin(adapter, { serverEntry: () => resolve(root, outDir, "entry.server.tsx"), mode: () => mode })] : []),
     ];
 }

package/cli/rivet.js

@@ -4,8 +4,9 @@
 //     Write the app's generated `.rivet/` files (route types, generated app, editor manifest) from its
 //     Vite config without starting Vite. Run before `tsc` / `rivet-check` on a fresh clone.
 //   rivet migrate server-exports [--routes src/routes] [--dry-run]
-//     Rename old `*.server.ts` export names (load, guard, actions, entries, headers, GET…) to
-//     serverLoad, serverGuard, serverActions, serverEntries, serverHeaders, onGet… (scope-aware).
+//     Rewrite magic route server export names (in-file serverLoad, onGet…; sibling load, GET…) to
+//     wrapper calls (`export const loader = load(…)`, `export const GET = onGet(…)`), references renamed
+//     scope-aware, the `@rivetjs/router` import added.
 //   rivet mcp
 //     Start the Rivet MCP server (`@rivetjs/mcp`, stdio) installed in the app; same as `npx @rivetjs/mcp`.
 import { relative } from "node:path";

package/client/dev.js

@@ -7,6 +7,23 @@ import { untrack } from "@rivetjs/reactivity";
 import { devtoolsHook } from "@rivetjs/reactivity/debug";
 import * as client from "./index.js";
 export * from "./index.js";
+// A failed client navigation (`_recover`, index.ts) loads its document after Vite's error overlay showed the error: once
+// the overlay closes, or at once when none opens within 1.5 s (overlay off, error not reported).
+client._recover.defer = (load) => {
+    const open = () => document.querySelector("vite-error-overlay");
+    const until = Date.now() + 1500;
+    const wait = () => {
+        if (open()) {
+            const watch = new MutationObserver(() => open() || (watch.disconnect(), load()));
+            watch.observe(document.documentElement, { childList: true, subtree: true });
+        }
+        else if (Date.now() > until)
+            load();
+        else
+            setTimeout(wait, 100);
+    };
+    wait();
+};
 const hook = devtoolsHook();
 let table = null;
 let shown = null;

package/client/index.d.ts

@@ -77,6 +77,10 @@ export declare const _transitions: {
  * returns runs once the new page is in the document. Returns an unsubscribe function.
  */
 export declare function onNavigate(fn: (nav: NavigationInfo) => void | (() => void)): () => void;
+/** @internal Dev (`dev.ts`): the error overlay shows a failed navigation's error before its document loads. */
+export declare const _recover: {
+    defer?: (load: () => void) => void;
+};
 /** @internal The navigation in flight (read by the transitions module when it installs). */
 export declare const _current: () => NavigationInfo | null;
 /** @internal Run the `onNavigate` callbacks' after-swap functions. */

package/client/index.js

@@ -204,6 +204,8 @@ export function onNavigate(fn) {
     return () => void listeners.delete(fn);
 }
 function started(nav) {
+    if (recovering === undefined)
+        ((recovering = false), addEventListener("error", recover), addEventListener("unhandledrejection", recover));
     // Warmed data for other URLs is no longer wanted: abort it (the target's own stays for its load).
     dropPrefetch(key(nav.to));
     keep = 0;
@@ -217,6 +219,34 @@ function started(nav) {
     }
     _transitions.start?.(nav);
 }
+/** @internal Dev (`dev.ts`): the error overlay shows a failed navigation's error before its document loads. */
+export const _recover = {};
+// Listening (`false`, from the first navigation) / loading the document (`true`); `undefined`: not listening yet.
+let recovering;
+// The URL a navigation just committed (`swapRoute`; until the next frame): its page renders after the commit.
+let rendering;
+/**
+ * A client navigation whose render or commit throws (an uncaught error after the history push: before the routes
+ * region committed the URL, or inside its swap) loads the URL's document instead: URL and page never diverge. `location.replace`: the
+ * history entry is already there. A failing document load does not re-enter: once per URL within 10 s (session storage).
+ */
+function recover() {
+    const href = location.href, at = Date.now();
+    if (recovering || (href !== rendering && (!current || href === committed)))
+        return;
+    try {
+        // `<13-digit ms><href>` of the last recovery.
+        const last = sessionStorage["rivet:recover"];
+        if (last?.slice(13) === href && at - +last.slice(0, 13) < 1e4)
+            return;
+        sessionStorage["rivet:recover"] = at + href;
+    }
+    catch {
+        // No session storage: recover without the cross-document loop guard.
+    }
+    recovering = true;
+    (_recover.defer ?? ((load) => load()))(() => location.replace(href));
+}
 /** @internal The navigation in flight (read by the transitions module when it installs). */
 export const _current = () => current;
 /** @internal Run the `onNavigate` callbacks' after-swap functions. */
@@ -334,6 +364,10 @@ export function swapRoute(apply, next) {
         enter((index = history.state?.i ?? index + 1));
     }
     committed = href;
+    // Until the next frame's first task (the routes region renders the new page after the swap, up to a frame later), an
+    // uncaught error is this navigation's (`recover`).
+    if (nav)
+        ((rendering = href), requestAnimationFrame(() => setTimeout(() => rendering === href && (rendering = undefined))));
     if (nav && _transitions.swap)
         return _transitions.swap(apply, next, nav);
     apply();

package/client/route-context.d.ts

@@ -26,7 +26,7 @@ export declare const ServerData: Context<ServerRoutePayload | null>;
 export declare function actionResult(name?: string): ActionResult | undefined;
 /**
  * Typed: `actionResult<"items/[id]">("save")` (route id, generated `RouteActions`) or
- * `actionResult<typeof serverActions>()`. Pass the name as the second type argument to narrow the
+ * `actionResult<typeof forms>()` (`forms = actions(…)`). Pass the name as the second type argument to narrow the
  * result to that action (`actionResult<"items/[id]", "save">("save")`).
  */
 export declare function actionResult<A extends (keyof RouteActions & string) | Record<string, unknown>, N extends ActionName<A> = ActionName<A>>(name?: N): ActionResultOf<A, N> | undefined;

package/index.d.ts

@@ -1,6 +1,9 @@
 import type { JSX } from "@rivetjs/runtime/jsx-runtime";
 import type { HttpError as HttpErrorType } from "./shared/errors.js";
 import type { ActionFailure } from "./shared/actions.js";
+import type { Deferred, SERVER_EXPORT } from "./shared/server-exports.js";
+export { load, guard, actions, entries, headers, onRequest, onGet, onPost, onPut, onPatch, onDelete, onOptions } from "./shared/server-exports.js";
+export type { ServerExport, ServerKind, Deferred, LoadOptions } from "./shared/server-exports.js";
 export { HttpError, redirect, deny, notFound, error, isHttpError, type RedirectOptions } from "./shared/errors.js";
 export { safeRedirect } from "./shared/redirect.js";
 export { parseCookies } from "./shared/cookie.js";
@@ -16,7 +19,7 @@ export interface RouteParams {
 /** Route id → loader data (routes with a loader). Augmented by the generated `.rivet/routes.d.ts`. */
 export interface RouteData {
 }
-/** Route id → its `serverActions` object type (routes with server code). Augmented by `.rivet/routes.d.ts`. */
+/** Route id → its `actions(…)` object type (routes with server code). Augmented by `.rivet/routes.d.ts`. */
 export interface RouteActions {
 }
 /** Layout id (`_layout`, `items/_layout`) → the params it receives. Augmented by `.rivet/routes.d.ts`. */
@@ -42,42 +45,36 @@ export type RoutePath = RouteRegistry extends {
 /** A page path with optional query and hash: `<Link to>`. */
 export type LinkHref = RoutePath | `${RoutePath}?${string}` | `${RoutePath}#${string}`;
 declare const unchecked: unique symbol;
-/** `PageProps<Unchecked<typeof serverLoad>>`: loader data without the serializability check. */
+/** `PageProps<Unchecked<typeof loader>>`: loader data without the serializability check. */
 export interface Unchecked<T> {
     readonly [unchecked]: T;
 }
 /** Loader data the page receives must survive the resume encoder: no functions, symbols or class instances. */
 export interface NotSerializable<T> {
-    "rivet: loader data must be serializable (plain objects, arrays, primitives, Date, URL, URLSearchParams, RegExp, Map, Set, typed arrays, ArrayBuffer, DataView, Error — no functions, symbols or class instances); opt out with PageProps<Unchecked<typeof serverLoad>>": T;
+    "rivet: loader data must be serializable (plain objects, arrays, primitives, Date, URL, URLSearchParams, RegExp, Map, Set, typed arrays, ArrayBuffer, DataView, Error — no functions, symbols or class instances); opt out with PageProps<Unchecked<typeof loader>>": T;
 }
 type Leaf = string | number | boolean | bigint | null | undefined | Date | URL | URLSearchParams | RegExp | ArrayBuffer | ArrayBufferView;
 type Depth = [never, 0, 1, 2, 3, 4, 5, 6, 7];
 type IsError<T> = T extends Error ? ("stack" extends keyof T ? true : false) : false;
-type Serializable<T, D extends number = 8> = [D] extends [never] ? true : T extends Leaf ? true : T extends symbol | ((...args: never[]) => unknown) ? false : IsError<T> extends true ? true : T extends ReadonlyMap<infer K, infer V> ? Serializable<K, Depth[D]> extends true ? Serializable<V, Depth[D]> : false : T extends ReadonlySet<infer V> ? Serializable<V, Depth[D]> : T extends readonly (infer E)[] ? Serializable<E, Depth[D]> : T extends object ? false extends {
+type Serializable<T, D extends number = 8> = [D] extends [never] ? true : T extends Leaf ? true : T extends Deferred<infer V> ? Serializable<V, D> : T extends symbol | ((...args: never[]) => unknown) ? false : IsError<T> extends true ? true : T extends ReadonlyMap<infer K, infer V> ? Serializable<K, Depth[D]> extends true ? Serializable<V, Depth[D]> : false : T extends ReadonlySet<infer V> ? Serializable<V, Depth[D]> : T extends readonly (infer E)[] ? Serializable<E, Depth[D]> : T extends object ? false extends {
     [K in keyof T]-?: Serializable<T[K], Depth[D]>;
 }[keyof T] ? false : true : true;
-type Returned<L> = L extends (...args: never[]) => infer R ? Awaited<R> : L;
+type Returned<L> = L extends (...args: never[]) => infer R ? (R extends Deferred<infer V> ? Deferred<V> : Awaited<R>) : L;
 /**
- * Data type of a loader (`DataOf<typeof serverLoad>`), checked to be serializable; plain data types
+ * Data type of a loader (`DataOf<typeof loader>`, `loader = load(…)`), checked to be serializable; plain data types
  * pass through unchanged (`DataOf<Item[]>` is `Item[]`).
  */
 export type DataOf<T> = T extends Unchecked<infer L> ? Returned<L> : T extends (...args: never[]) => unknown ? Serializable<Returned<T>> extends true ? Returned<T> : NotSerializable<Returned<T>> : T;
-/** Loader data of an in-file route module (`serverLoad`). */
-export type InlineData<M> = M extends {
-    serverLoad: infer L;
-} ? DataOf<L> : unknown;
-/** Loader data of a sibling `*.server.ts` module (`serverLoad`, or the old `load`). */
-export type ModuleData<M> = M extends {
-    serverLoad: infer L;
-} ? DataOf<L> : M extends {
-    load: infer L;
-} ? DataOf<L> : unknown;
-/** Form actions of a route module (`serverActions`, or a sibling's old `actions`); `{}` without. */
-export type ModuleActions<M> = M extends {
-    serverActions: infer A;
-} ? A : M extends {
-    actions: infer A;
-} ? A : {};
+/** The export of module type `M` tagged as server export kind `K` (by tag, any name); `never` without. */
+type Tagged<M, K> = {
+    [N in keyof M]: M[N] extends {
+        readonly [SERVER_EXPORT]: K;
+    } ? M[N] : never;
+}[keyof M];
+/** Loader data of a route module (`typeof import("./page")`): its `load(…)` export, any name; `unknown` without. */
+export type ModuleData<M> = [Tagged<M, "load">] extends [never] ? unknown : DataOf<Tagged<M, "load">>;
+/** Form actions of a route module: its `actions(…)` export, any name; `{}` without. */
+export type ModuleActions<M> = [Tagged<M, "actions">] extends [never] ? {} : Tagged<M, "actions">;
 /** A string that is not an id of `RouteParams` / `LayoutParams`: `data` and `params` are unusable. */
 export interface UnknownRoute<Id> {
     "rivet: not a route or layout id of this app (see .rivet/routes.d.ts)": Id;
@@ -89,7 +86,7 @@ type LayoutDataOf<D> = D extends LayoutId ? (D extends keyof LayoutData ? Layout
 type LayoutParamsOf<D, P> = D extends LayoutId ? LayoutParams[D] : IsLiteral<D> extends true ? UnknownRoute<D> : P;
 /**
  * Props every page component receives (layouts: `LayoutProps`). `D` is a route id (generated
- * types: `PageProps<"items/[id]">` types data, params), the loader (`PageProps<typeof serverLoad>`
+ * types: `PageProps<"items/[id]">` types data, params), the loader (`PageProps<typeof loader>`
  * infers the data) or the data type.
  */
 export interface PageProps<D = unknown, P extends Record<string, string> = Record<string, string>> {
@@ -125,11 +122,11 @@ type Outcome<R> = R extends HttpErrorType | Response ? never : R extends ActionF
     readonly status?: undefined;
 };
 type ActionsOf<A> = A extends RouteId ? (A extends keyof RouteActions ? RouteActions[A] : {}) : A;
-/** Action names of a route id (`RouteActions`) or an actions object type (`typeof serverActions`). */
+/** Action names of a route id (`RouteActions`) or an actions object type (`typeof forms`, `forms = actions(…)`). */
 export type ActionName<A> = keyof ActionsOf<A> & string;
 /**
  * Typed `actionResult()`: per action name its return value (`redirect()`/`Response` excluded), or
- * the data and status of `fail()`. `A` is a route id or `typeof serverActions`.
+ * the data and status of `fail()`. `A` is a route id or `typeof forms` (`forms = actions(…)`).
  */
 export type ActionResultOf<A, N extends ActionName<A> = ActionName<A>> = {
     [K in N]: {

package/index.js

@@ -1,4 +1,5 @@
-// Route-module API: control-flow helpers and types for guards, loaders and actions.
+// Route-module API: server export wrappers, control-flow helpers and types for guards, loaders and actions.
+export { load, guard, actions, entries, headers, onRequest, onGet, onPost, onPut, onPatch, onDelete, onOptions } from "./shared/server-exports.js";
 export { HttpError, redirect, deny, notFound, error, isHttpError } from "./shared/errors.js";
 export { safeRedirect } from "./shared/redirect.js";
 export { parseCookies } from "./shared/cookie.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rivetjs/router",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.1",
   "description": "File routing for Rivet: loaders, actions, guards, a web-standard request handler, Node / static / edge adapters.",
   "license": "MIT",
   "type": "module",
@@ -114,9 +114,9 @@
     }
   },
   "dependencies": {
-    "@rivetjs/runtime": "0.1.0-alpha.0",
-    "@rivetjs/reactivity": "0.1.0-alpha.0",
-    "@rivetjs/compiler": "0.1.0-alpha.0"
+    "@rivetjs/runtime": "0.1.0-alpha.1",
+    "@rivetjs/reactivity": "0.1.0-alpha.1",
+    "@rivetjs/compiler": "0.1.0-alpha.1"
   },
   "engines": {
     "node": ">=24"

package/server/app.d.ts

@@ -5,7 +5,7 @@ import type { ActionResult, Head, HeadSink, LoaderDeps } from "../shared/data.js
 import { type CSPOptions } from "../shared/csp.js";
 import { type InlineStyleManifest } from "./inline-styles.js";
 import type { TrailingSlash } from "../shared/slash.js";
-import { type AppHandler, type AppRoute, type BodyLimit, type ErrorInfo } from "./handler.js";
+import { type AppHandler, type AppRoute, type BodyLimit, type ErrorInfo, type ShellPhase } from "./handler.js";
 import { type DocumentShell } from "./render.js";
 import type { EarlyHintsOptions } from "./early-hints.js";
 import type { RouteCacheOptions, RouteRules } from "./route-cache.js";
@@ -28,6 +28,12 @@ export interface PageInput {
     readonly byURL?: readonly number[];
     /** Loaders' `event.depends()` keys (absent when none called it): resumed with the layout state for `invalidate(key)`. */
     readonly deps?: LoaderDeps;
+    /** A `data` slot is a deferred loader's handle (`load(fn, { defer: true })`): the page streams (out of order) even without `stream`. */
+    readonly deferred?: true;
+    /** A deferred loader's redirect target, read at the document's end (client redirect). */
+    readonly moved?: () => string | undefined;
+    /** @internal Route rule `shell`: a shell fill / replay (always streams). */
+    readonly shell?: ShellPhase;
 }
 /** Shape of the generated `.rivet/entry.server.tsx` module. */
 export interface GeneratedEntry {