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

package/client/scroll.js

@@ -0,0 +1,80 @@
+const SCROLL = "rivet:scroll:";
+let seq = 0;
+// Scroll key of the entry the page shows; unknown until the first client navigation.
+let shown;
+let manual = false;
+/** Key the current history entry (merged into its state) and make it the shown one. */
+export function enter(i) {
+    const state = history.state;
+    const key = typeof state?.rivet === "number" ? state.rivet : Date.now() * 1000 + (seq++ % 1000);
+    if (state?.i !== i || state?.rivet !== key)
+        history.replaceState({ ...state, i, rivet: key }, "");
+    shown = key;
+}
+/**
+ * Before a navigation leaves the shown entry: take scroll restoration over from the browser (once)
+ * and save the position. `here`: `history.state` still belongs to that entry (link clicks), so it
+ * can be keyed now if no navigation keyed it yet.
+ */
+export function leave(here, i) {
+    if (!manual) {
+        manual = true;
+        history.scrollRestoration = "manual";
+        // Reloads and cross-document traversals restore natively: hand control back while unloading.
+        addEventListener("pagehide", () => (history.scrollRestoration = "auto"));
+        addEventListener("pageshow", (event) => event.persisted && (history.scrollRestoration = "manual"));
+    }
+    if (here && shown === undefined)
+        enter(i);
+    if (shown === undefined)
+        return;
+    try {
+        sessionStorage.setItem(SCROLL + shown, JSON.stringify([scrollX, scrollY]));
+    }
+    catch {
+        /* Storage may be unavailable (private mode); scroll restoration degrades to top. */
+    }
+}
+/** Restore the current entry's saved position; false when there is none. */
+export function restoreScroll() {
+    const state = history.state;
+    let position = null;
+    if (typeof state?.rivet === "number") {
+        try {
+            position = JSON.parse(sessionStorage.getItem(SCROLL + state.rivet) ?? "null");
+        }
+        catch {
+            position = null;
+        }
+    }
+    if (position)
+        scrollTo(position[0], position[1]);
+    return !!position;
+}
+/** Make `element` the focus (programmatically focusable when it is not already). */
+export function focusOn(element) {
+    if (!element.hasAttribute("tabindex"))
+        element.setAttribute("tabindex", "-1");
+    element.focus({ preventScroll: true });
+}
+/** The element a URL's fragment names, if any. */
+export function fragmentTarget(url) {
+    if (!url.hash)
+        return null;
+    try {
+        return document.getElementById(decodeURIComponent(url.hash.slice(1)));
+    }
+    catch {
+        return null;
+    }
+}
+/** Hash-only navigation: scroll to and focus the fragment's target; no fragment scrolls to the top. */
+export function reveal(url) {
+    const target = fragmentTarget(url);
+    if (target) {
+        target.scrollIntoView();
+        focusOn(target);
+    }
+    else if (!url.hash)
+        scrollTo(0, 0);
+}

package/client/search.d.ts

@@ -0,0 +1,8 @@
+import { type Context, type Signal } from "@rivetjs/reactivity";
+/** Browser search params of the shown page (route commits update it; a fresh object per change). */
+export declare const searchParams: Signal<URLSearchParams>;
+/**
+ * Resumable search params context (`useSearchParams()`): the server entry provides the request's,
+ * resumed regions revive to `searchParams`.
+ */
+export declare const SearchParams: Context<() => URLSearchParams>;

package/client/search.js

@@ -0,0 +1,17 @@
+// Search params state (`useSearchParams()`), in its own module so apps that never read search params
+// ship none of it: the router client syncs the signal only through the `_searchSync` hook set below.
+import { createContext, signal } from "@rivetjs/reactivity";
+import { _searchSync } from "./navigation.js";
+// The shown page's search (`_searchSync.shown`, set per route commit): this module may load mid-navigation.
+let shown = _searchSync.shown ?? (typeof location === "undefined" ? "" : location.search);
+/** Browser search params of the shown page (route commits update it; a fresh object per change). */
+export const searchParams = signal(new URLSearchParams(shown));
+/**
+ * Resumable search params context (`useSearchParams()`): the server entry provides the request's,
+ * resumed regions revive to `searchParams`.
+ */
+export const SearchParams = createContext(searchParams, { id: "rivet:search" });
+_searchSync.search = () => {
+    if (_searchSync.shown !== shown)
+        searchParams.set(new URLSearchParams((shown = _searchSync.shown)));
+};

package/client/tailwind.css

@@ -0,0 +1,8 @@
+/* @rivetjs/router Tailwind v4 variants: `@import "@rivetjs/router/tailwind.css";` after `@import "tailwindcss";`.
+   nav-pending:  while the navigation indicator shows (html[data-rivet-pending], after the delay)
+   link-pending: on the clicked link until the new page commits (a[data-rivet-pending])
+   nav-back / nav-forward: during a back / forward transition (html[data-rivet-transition]) */
+@custom-variant nav-pending (html[data-rivet-pending] &);
+@custom-variant link-pending (&[data-rivet-pending]);
+@custom-variant nav-back (html[data-rivet-transition~="back"] &);
+@custom-variant nav-forward (html[data-rivet-transition~="forward"] &);

package/client/transition-helpers.d.ts

@@ -0,0 +1,28 @@
+import type { NavigationInfo } from "./index.js";
+/** A page module's `export const transition`: extra types, `false` (never animate into it), or per navigation. */
+export type RouteTransition = false | {
+    types?: readonly string[];
+} | ((nav: NavigationInfo) => false | {
+    types?: readonly string[];
+});
+/**
+ * View transition types of a navigation, or null for an instant swap. Defaults (`push`, `replace`,
+ * `back`, `forward`) are always first; link `data-transition` wins over the route's `transition`.
+ */
+export declare function transitionTypes(nav: NavigationInfo): string[] | null;
+/** `data-vt-name` elements by name, one per name (duplicates drop the name). */
+export declare function namedElements(root: ParentNode | null): Map<string, HTMLElement | null>;
+/** Names present exactly once on both sides: the shared elements of a transition. */
+export declare function sharedNames(before: Map<string, HTMLElement | null>, after: Map<string, HTMLElement | null>): string[];
+/**
+ * Indicator timer: `show` after `delay` unless finished first; once shown, `hide` no earlier than
+ * `minDuration` after showing. `start` while running keeps the timers (redirects, quick re-clicks).
+ */
+export declare function indicator(delay: number, minDuration: number, show: () => void, hide: () => void, clock?: {
+    now(): number;
+    set(fn: () => void, ms: number): unknown;
+    clear(handle: unknown): void;
+}): {
+    start(): void;
+    finish(): void;
+};

package/client/transition-helpers.js

@@ -0,0 +1,63 @@
+const NAME = "data-vt-name";
+/**
+ * View transition types of a navigation, or null for an instant swap. Defaults (`push`, `replace`,
+ * `back`, `forward`) are always first; link `data-transition` wins over the route's `transition`.
+ */
+export function transitionTypes(nav) {
+    let route = nav.route;
+    if (typeof route === "function")
+        route = route(nav);
+    const link = nav.transition?.trim();
+    if (link === "none" || (route === false && !link))
+        return null;
+    return [nav.type, ...(link ? link.split(/\s+/) : route ? (route.types ?? []) : [])];
+}
+/** `data-vt-name` elements by name, one per name (duplicates drop the name). */
+export function namedElements(root) {
+    const names = new Map();
+    for (const element of root?.querySelectorAll(`[${NAME}]`) ?? []) {
+        const name = element.getAttribute(NAME);
+        names.set(name, names.has(name) ? null : element);
+    }
+    return names;
+}
+/** Names present exactly once on both sides: the shared elements of a transition. */
+export function sharedNames(before, after) {
+    return [...before].filter(([name, element]) => element && after.get(name)).map(([name]) => name);
+}
+/**
+ * Indicator timer: `show` after `delay` unless finished first; once shown, `hide` no earlier than
+ * `minDuration` after showing. `start` while running keeps the timers (redirects, quick re-clicks).
+ */
+export function indicator(delay, minDuration, show, hide, clock = {
+    now: () => Date.now(),
+    set: (fn, ms) => setTimeout(fn, ms),
+    clear: (handle) => clearTimeout(handle),
+}) {
+    let timer, shownAt = null, running = false;
+    return {
+        start() {
+            if (timer !== undefined && !running)
+                clock.clear(timer), (timer = undefined);
+            if (running)
+                return;
+            running = true;
+            if (shownAt === null)
+                timer = clock.set(() => ((timer = undefined), (shownAt = clock.now()), show()), delay);
+        },
+        finish() {
+            running = false;
+            if (shownAt === null) {
+                if (timer !== undefined)
+                    clock.clear(timer), (timer = undefined);
+                return hide();
+            }
+            const rest = minDuration - (clock.now() - shownAt);
+            const done = () => ((timer = undefined), (shownAt = null), hide());
+            if (rest > 0)
+                timer = clock.set(done, rest);
+            else
+                done();
+        },
+    };
+}

package/client/transitions.css

@@ -0,0 +1,90 @@
+/* @rivetjs/router route transitions: import from the app stylesheet (`@import "@rivetjs/router/transitions.css";`).
+   The router names the routes region `rivet-page` and shared elements (`data-vt-name`) only while a
+   transition runs, and sets `html[data-rivet-transition="push|replace|back|forward …types"]`. */
+
+/* Layout chrome stays still: only the routes region and shared elements animate. */
+::view-transition-old(root),
+::view-transition-new(root) {
+  animation: none;
+}
+/* Input during the animation reaches the new page. */
+::view-transition {
+  pointer-events: none;
+}
+
+/* Default: the page area cross-fades. */
+::view-transition-group(rivet-page) {
+  animation-duration: 200ms;
+}
+::view-transition-old(rivet-page) {
+  animation: 200ms ease both rivet-fade-out;
+}
+::view-transition-new(rivet-page) {
+  animation: 200ms ease both rivet-fade-in;
+}
+
+/* Opt-in slides: add `rivet-slide` to the html element (or copy these rules with your own selector). */
+html.rivet-slide[data-rivet-transition~="push"]::view-transition-old(rivet-page),
+html.rivet-slide[data-rivet-transition~="forward"]::view-transition-old(rivet-page) {
+  animation: 200ms ease both rivet-slide-out-left;
+}
+html.rivet-slide[data-rivet-transition~="push"]::view-transition-new(rivet-page),
+html.rivet-slide[data-rivet-transition~="forward"]::view-transition-new(rivet-page) {
+  animation: 200ms ease both rivet-slide-in-right;
+}
+html.rivet-slide[data-rivet-transition~="back"]::view-transition-old(rivet-page) {
+  animation: 200ms ease both rivet-slide-out-right;
+}
+html.rivet-slide[data-rivet-transition~="back"]::view-transition-new(rivet-page) {
+  animation: 200ms ease both rivet-slide-in-left;
+}
+
+/* Pending indicator: a thin indeterminate bar while `html[data-rivet-pending]` (after the delay). */
+html[data-rivet-pending]::before {
+  content: "";
+  position: fixed;
+  inset: 0 0 auto 0;
+  z-index: 2147483647;
+  height: 2px;
+  background: currentColor;
+  transform-origin: 0 50%;
+  animation: rivet-progress 1.2s ease-in-out infinite;
+  pointer-events: none;
+}
+
+@keyframes rivet-fade-out {
+  to { opacity: 0; }
+}
+@keyframes rivet-fade-in {
+  from { opacity: 0; }
+}
+@keyframes rivet-slide-out-left {
+  to { opacity: 0; transform: translateX(-8%); }
+}
+@keyframes rivet-slide-in-right {
+  from { opacity: 0; transform: translateX(8%); }
+}
+@keyframes rivet-slide-out-right {
+  to { opacity: 0; transform: translateX(8%); }
+}
+@keyframes rivet-slide-in-left {
+  from { opacity: 0; transform: translateX(-8%); }
+}
+@keyframes rivet-progress {
+  0% { transform: scaleX(0); }
+  50% { transform: scaleX(0.6); }
+  100% { transform: scaleX(1); opacity: 0; }
+}
+
+/* `reducedMotion: "allow"` leaves motion to CSS: remove it here. */
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-group(*),
+  ::view-transition-old(*),
+  ::view-transition-new(*) {
+    animation: none !important;
+  }
+  html[data-rivet-pending]::before {
+    animation: none;
+    transform: scaleX(0.6);
+  }
+}

package/client/transitions.d.ts

@@ -0,0 +1,21 @@
+import { type NavigationInfo } from "./index.js";
+export { indicator, namedElements, sharedNames, transitionTypes, type RouteTransition } from "./transition-helpers.js";
+/** Options of route transitions: view transitions, reduced motion and the pending indicator. */
+export interface TransitionOptions {
+    /** `false`: pending UI only, instant swaps (default true). */
+    viewTransitions?: boolean;
+    /** `"skip"` (default): no view transition under `prefers-reduced-motion: reduce`; `"allow"`: CSS decides. */
+    reducedMotion?: "skip" | "allow";
+    /** Indicator timing (ms): `html[data-rivet-pending]` / `useNavigation().shown` after `delay`, kept ≥ `minDuration`. */
+    pending?: {
+        delay?: number;
+        minDuration?: number;
+    };
+}
+/** `rivet:before-swap` detail: the navigation, whether it animates, and `defer(promise)` (awaited ≤ 500 ms). */
+export interface BeforeSwapDetail extends NavigationInfo {
+    readonly animate: boolean;
+    defer(promise: PromiseLike<unknown>): void;
+}
+/** Install the hooks (idempotent); generated apps call it when this module loads. */
+export declare function install(options?: TransitionOptions): void;

package/client/transitions.js

@@ -0,0 +1,156 @@
+// Route transitions + pending UI, loaded on the first navigation intent of apps built with
+// `rivetRouter({ transitions })`. Wraps each route commit in a same-document View Transition when
+// supported and enabled; drives the navigation signal and the pending attributes. No inline styles:
+// transition names are CSSOM assignments, which a strict `style-src` does not block.
+import { _afterSwap, _current, _transitions, settle } from "./index.js";
+import { IDLE, navigation } from "./navigation.js";
+import { indicator, namedElements, sharedNames, transitionTypes } from "./transition-helpers.js";
+export { indicator, namedElements, sharedNames, transitionTypes } from "./transition-helpers.js";
+const ROUTES = "[data-rivet-routes]";
+const PENDING = "data-rivet-pending";
+let installed = false;
+/** Install the hooks (idempotent); generated apps call it when this module loads. */
+export function install(options = {}) {
+    if (installed || typeof document === "undefined")
+        return;
+    installed = true;
+    const doc = document, html = doc.documentElement;
+    let anchor, nav = null, running = null;
+    const state = (shown) => nav ? { state: "loading", location: nav.to, from: nav.from, type: nav.type, shown } : { ...IDLE };
+    const timing = indicator(options.pending?.delay ?? 200, options.pending?.minDuration ?? 300, () => {
+        html.setAttribute(PENDING, "");
+        navigation.set(state(true));
+    }, () => {
+        html.removeAttribute(PENDING);
+        if (!nav)
+            navigation.set(IDLE);
+    });
+    // Clicked link: `data-rivet-pending` (+ `<Link pending>` classes) until the commit.
+    const mark = (next) => {
+        if (anchor === next)
+            return;
+        if (anchor) {
+            anchor.removeAttribute(PENDING);
+            anchor.classList.remove(...classes(anchor));
+        }
+        anchor = next;
+        if (anchor) {
+            anchor.setAttribute(PENDING, "");
+            anchor.classList.add(...classes(anchor));
+        }
+    };
+    const start = (next) => {
+        nav = next;
+        running?.skipTransition();
+        doc.querySelector(ROUTES)?.setAttribute("aria-busy", "true");
+        mark(next.anchor);
+        navigation.set(state(html.hasAttribute(PENDING)));
+        timing.start();
+    };
+    const finish = () => {
+        nav = null;
+        doc.querySelector(ROUTES)?.removeAttribute("aria-busy");
+        mark(undefined);
+        timing.finish();
+        // Held indicator: the state stays loading (shown) until it hides.
+        if (!html.hasAttribute(PENDING))
+            navigation.set(IDLE);
+    };
+    const event = (type, detail, cancelable = false) => doc.dispatchEvent(new CustomEvent(type, { detail, cancelable }));
+    _transitions.start = start;
+    _transitions.swap = (apply, next, info) => {
+        const types = transitionTypes(info);
+        const reduced = options.reducedMotion !== "allow" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+        const animate = !!types && options.viewTransitions !== false && typeof doc.startViewTransition === "function" && !reduced && doc.visibilityState === "visible" && !info.visual;
+        // Superseded (a newer navigation started): `apply` discards; leave that navigation's state alone.
+        const current = () => nav === info || nav === null;
+        const host = doc.querySelector(ROUTES);
+        const named = [];
+        const name = (element, value) => {
+            if (!element)
+                return;
+            element.style.viewTransitionName = value;
+            const group = element.getAttribute("data-vt-class");
+            if (group && "viewTransitionClass" in element.style)
+                element.style.viewTransitionClass = group;
+            named.push(element);
+        };
+        let shared = [], incoming = new Map(), transition = null;
+        const update = () => {
+            if (!current())
+                return apply();
+            try {
+                apply();
+            }
+            finally {
+                for (const value of shared)
+                    name(incoming.get(value), value);
+                settle(new URL(location.href));
+                finish();
+                _afterSwap();
+                event("rivet:after-swap", info);
+            }
+        };
+        const done = () => {
+            if (running === transition)
+                running = null;
+            for (const element of named) {
+                element.style.viewTransitionName = "";
+                if ("viewTransitionClass" in element.style)
+                    element.style.viewTransitionClass = "";
+            }
+            if (host)
+                host.style.viewTransitionName = "";
+            html.removeAttribute("data-rivet-transition");
+            if (current())
+                event("rivet:navigated", info);
+        };
+        const run = () => {
+            if (!animate || !current()) {
+                update();
+                return done();
+            }
+            // Shared elements: names present once on both sides, assigned on the old DOM before the
+            // snapshot and on the new DOM inside `update`. The routes region animates as `rivet-page`.
+            incoming = namedElements(next);
+            const outgoing = namedElements(host);
+            shared = sharedNames(outgoing, incoming);
+            for (const value of shared)
+                name(outgoing.get(value), value);
+            if (host)
+                host.style.viewTransitionName = "rivet-page";
+            html.setAttribute("data-rivet-transition", types.join(" "));
+            running?.skipTransition();
+            try {
+                transition = doc.startViewTransition({ update, types: types });
+            }
+            catch {
+                // Before `types` (Chrome < 125): callback form; CSS keys off html[data-rivet-transition].
+                transition = doc.startViewTransition(update);
+            }
+            running = transition;
+            // Skipped before it animates (a newer navigation started): `ready` rejects, nothing to report.
+            transition.ready.catch(() => { });
+            transition.updateCallbackDone.catch((error) => queueMicrotask(() => {
+                throw error;
+            }));
+            transition.finished.then(done, done);
+        };
+        const deferred = [];
+        event("rivet:before-swap", { ...info, animate, defer: (promise) => void deferred.push(promise) });
+        if (!deferred.length)
+            return run();
+        let timeout;
+        void Promise.race([Promise.allSettled(deferred), new Promise((resolve) => (timeout = setTimeout(resolve, 500)))]).then(() => {
+            clearTimeout(timeout);
+            run();
+        });
+    };
+    // A navigation already in flight when this module arrived (first click before any intent).
+    const pending = _current();
+    if (pending)
+        start(pending);
+}
+function classes(anchor) {
+    return (anchor.getAttribute("data-rivet-pending-class") ?? "").split(/\s+/).filter(Boolean);
+}

package/index.d.ts

@@ -0,0 +1,135 @@
+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";
+export { slashPath, TRAILING_SLASH, type TrailingSlash } from "./shared/slash.js";
+export { BASE, withBase } from "./shared/base.js";
+export { ActionFailure, fail, isActionFailure } from "./shared/actions.js";
+export type { RequestEvent, ServerModule, Cookies, CookieOptions, ActionResult, Platform } from "./server/handler.js";
+export type { Head, HeadLink, HeadMeta, HeadScript, HeadSink, HeadStyle, InlineScript, ScriptStrategy } from "./shared/data.js";
+export type { ActionAnswer, AnswerError, DataAnswer } from "./shared/data.js";
+/** Route id → params. Augmented by the generated `.rivet/routes.d.ts`. */
+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 `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`. */
+export interface LayoutParams {
+}
+/** Layout id → loader data (layouts with a loader). Augmented by `.rivet/routes.d.ts`. */
+export interface LayoutData {
+}
+/** Ids of the app's file routes (e.g. `blog/[slug]`). */
+export type RouteId = keyof RouteParams & string;
+/** Ids of the app's `_layout` modules: the file path without extension (`_layout`, `(shop)/_layout`). */
+export type LayoutId = keyof LayoutParams & string;
+/** Augmented by the generated `.rivet/routes.d.ts`: `path` is the union of the app's page URL shapes. */
+export interface RouteRegistry {
+}
+/**
+ * URL paths of the app's pages: params and splats are `${string}` (`"/" | \`/items/${string}\``).
+ * Plain `string` until codegen ran (no `.rivet/routes.d.ts` in the program).
+ */
+export type RoutePath = RouteRegistry extends {
+    path: infer P extends string;
+} ? P : string;
+/** 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 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 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 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 ? (R extends Deferred<infer V> ? Deferred<V> : Awaited<R>) : L;
+/**
+ * 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;
+/** 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;
+}
+type IsLiteral<D> = D extends string ? (string extends D ? false : true) : false;
+type PageData<D> = D extends RouteId ? (D extends keyof RouteData ? RouteData[D] : undefined) : IsLiteral<D> extends true ? UnknownRoute<D> : DataOf<D>;
+type PageParams<D, P> = D extends RouteId ? RouteParams[D] : IsLiteral<D> extends true ? UnknownRoute<D> : P;
+type LayoutDataOf<D> = D extends LayoutId ? (D extends keyof LayoutData ? LayoutData[D] : undefined) : IsLiteral<D> extends true ? UnknownRoute<D> : DataOf<D>;
+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 loader>`
+ * infers the data) or the data type.
+ */
+export interface PageProps<D = unknown, P extends Record<string, string> = Record<string, string>> {
+    data: PageData<D>;
+    params: Readonly<PageParams<D, P>>;
+    url: URL;
+}
+/**
+ * Props of a live page (`export const live = true`): `data` is an accessor. Same-URL revalidation (an
+ * enhanced form submit, `invalidate()`) updates it in place — the page is not re-rendered, so its
+ * local state (an open drawer, typed input, focus) survives. `D` as in `PageProps`.
+ */
+export interface LivePageProps<D = unknown, P extends Record<string, string> = Record<string, string>> {
+    data: () => PageData<D>;
+    params: Readonly<PageParams<D, P>>;
+    url: URL;
+}
+/**
+ * Props of a `_layout.tsx` component. Accessors: the root layout stays mounted across navigations.
+ * `D` is a layout id (`LayoutProps<"items/_layout">`), the loader or the data type.
+ */
+export interface LayoutProps<D = unknown, P = {}> {
+    data: () => LayoutDataOf<D>;
+    params: () => Readonly<LayoutParamsOf<D, P>>;
+    url: () => URL;
+    children?: JSX.Element;
+}
+type Outcome<R> = R extends HttpErrorType | Response ? never : R extends ActionFailure<infer F> ? {
+    readonly result: F;
+    readonly status: number;
+} : {
+    readonly result: R;
+    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 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 forms` (`forms = actions(…)`).
+ */
+export type ActionResultOf<A, N extends ActionName<A> = ActionName<A>> = {
+    [K in N]: {
+        readonly name: K;
+    } & Outcome<Awaited<ActionsOf<A>[K] extends (...args: never[]) => infer R ? R : never>>;
+}[N];

package/index.js

@@ -0,0 +1,8 @@
+// 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";
+export { slashPath, TRAILING_SLASH } from "./shared/slash.js";
+export { BASE, withBase } from "./shared/base.js";
+export { ActionFailure, fail, isActionFailure } from "./shared/actions.js";