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

package/client/live.d.ts

@@ -0,0 +1,57 @@
+import { type Signal } from "@rivetjs/reactivity";
+import { type DataSource, type Navigator } from "./index.js";
+import { type LayoutTable, type Layouts } from "./layouts.js";
+/** @internal The App's live-page slot (resume state carries it): the shown live page's data signal and URL. */
+export interface LivePage {
+    /** Data source of the app (`server` / `static`). */
+    readonly m: DataSource;
+    /** The shown live page's data signal (unset: no live page rendered yet). */
+    s?: Signal<unknown>;
+    /** Its URL (`pathname + search`). */
+    u?: string;
+    /** Its index in the route data (= its layout count). */
+    d?: number;
+    /** Refresh generation: only the newest in-place refresh applies. */
+    n?: number;
+    /** Single-level apps: the top Router's key, set (`equals: false`: a same-URL revalidation re-runs the Router)
+     * on every location change except a fragment-only one or a search-only one of the shown live page. */
+    k?: Signal<string>;
+    /** The shown URL without its fragment (what `k` was last set for, or the search-only URL refreshed in place). */
+    h?: string;
+    /** `k` follows the location (effect started by the first navigation entry point). */
+    a?: true;
+    /** The data signal whose reader chunks were warmed (`_liveIntent`: once per page render). */
+    w?: Signal<unknown>;
+}
+type Located = {
+    location(): URL;
+};
+/** @internal Generated `App`: the live-page slot (`router`: single-level apps, whose top Router keys on `k`). */
+export declare function _live(m: DataSource, router?: Located): LivePage;
+/**
+ * @internal Generated `App` intent listeners (focusin, pointerdown): an interaction inside a form of the shown live
+ * page warms the chunks of the resumed bindings that read its data (and the layouts' data), so a submit's in-place
+ * refresh needs no round trip after the answer. Resumed pages only (the resume runtime's `rivet.warm` hook).
+ */
+export declare function _liveIntent(event: Event, live: LivePage, state?: Layouts): void;
+/** @internal Generated `App`: the top Router's navigator — route work keyed on the slot's `k`. */
+export declare const _liveRouter: (router: Located, live: LivePage) => Located;
+/**
+ * @internal Generated `App` navigation entry points (link click, popstate, `rivet:go`): once, start the effect
+ * that moves `k` with the location — except for a search-only change of the shown live page, refreshed in place.
+ */
+export declare function _armLive(router: Located & Navigator, live: LivePage, state?: Layouts, table?: LayoutTable): void;
+/**
+ * @internal Generated `App` of a nested-layout app (`_sync`'s `inPlace`): a search-only change of the shown live
+ * page (`from`: the URL `_sync` saw last) refreshes it in place — no level key moves, the layouts keep their data
+ * unless their loaders read the URL. A failed loader re-renders the page level (`_bump` + `_sync`).
+ */
+export declare function _liveLevels(router: Located & Navigator, live: LivePage, state: Layouts, table: LayoutTable, from: string, url: URL): boolean;
+/** @internal Generated route render of a live page: its `data` accessor (a new signal per render). */
+export declare function _livePage(slot: LivePage, value: unknown, url: URL, depth: number): () => unknown;
+/**
+ * @internal Generated `App` (`rivet:go`) when some page is live: same-URL revalidations of the shown
+ * live page refresh in place; everything else is served like `_serve`.
+ */
+export declare function _serveLive(router: Navigator, live: LivePage, state?: Layouts, table?: LayoutTable): void;
+export {};

package/client/live.js

@@ -0,0 +1,170 @@
+// Live pages (`export const live = true` in a page module): the page's `data` prop is an accessor
+// backed by a signal, and same-URL revalidation (an enhanced form submit, `invalidate()`, an
+// `invalidate(key)` that reruns the page loader) updates it — and the layouts that reran — in place.
+// The page is not re-rendered: page-local state (an open drawer, typed input, focus, scroll) survives.
+// Search-only navigations of the shown live page (`?new` with JS, `setSearchParams`, back / forward between
+// them) refresh it in place too (single-level apps: the top Router keys on the slot's `k`, not the URL; nested
+// layout levels: `_sync` leaves every level key as it is, `_liveLevels`).
+// Used by the generated `App` only when some page is live (pay-per-use: apps without one never import it).
+import { batch, effect, signal, untrack } from "@rivetjs/reactivity";
+import { _clearPrefetch, _current, _dropPrefetch, _inPlace, _perform, routeData } from "./index.js";
+import { _bump, _depsLoaded, _invalidating, _keepIds, _plan, _refreshed, _stale, _sync } from "./layouts.js";
+import { _take } from "./navigate.js";
+const pageOf = (url) => url.href.split("#")[0];
+/** @internal Generated `App`: the live-page slot (`router`: single-level apps, whose top Router keys on `k`). */
+export function _live(m, router) {
+    if (!router)
+        return { m };
+    const h = pageOf(untrack(router.location));
+    return { m, k: signal(h, { equals: false }), h };
+}
+/**
+ * @internal Generated `App` intent listeners (focusin, pointerdown): an interaction inside a form of the shown live
+ * page warms the chunks of the resumed bindings that read its data (and the layouts' data), so a submit's in-place
+ * refresh needs no round trip after the answer. Resumed pages only (the resume runtime's `rivet.warm` hook).
+ */
+export function _liveIntent(event, live, state) {
+    const warm = globalThis[Symbol.for("rivet.warm")];
+    if (!warm || !live.s || live.w === live.s || !event.target?.closest?.("form"))
+        return;
+    live.w = live.s;
+    warm(live.s);
+    if (state)
+        for (const layout of state.l)
+            if (layout)
+                warm(layout.d);
+}
+/** @internal Generated `App`: the top Router's navigator — route work keyed on the slot's `k`. */
+export const _liveRouter = (router, live) => ({
+    location() {
+        live.k();
+        return untrack(router.location);
+    },
+});
+/**
+ * @internal Generated `App` navigation entry points (link click, popstate, `rivet:go`): once, start the effect
+ * that moves `k` with the location — except for a search-only change of the shown live page, refreshed in place.
+ */
+export function _armLive(router, live, state, table) {
+    if (live.a || !live.k)
+        return;
+    live.a = true;
+    let seen;
+    effect(() => {
+        const url = router.location();
+        untrack(() => {
+            const shown = live.h, page = pageOf(url), 
+            // The same full URL again: a revalidation (the runtime router re-set it); else a fragment-only change.
+            again = url.href === seen;
+            seen = url.href;
+            if (page === shown)
+                return void (again && live.k.set(page));
+            const from = new URL(shown);
+            live.h = page;
+            if (live.s && live.u === from.pathname + from.search && url.pathname === from.pathname) {
+                // The shown live page, another search (same route and params): the Router keeps it, its data refreshes in place.
+                live.u = url.pathname + url.search;
+                void refresh(router, live, url, undefined, state && table ? _keepIds(state, table, url) : undefined, _inPlace, state, table, () => live.k.set(live.h));
+            }
+            else
+                live.k.set(page);
+        });
+    });
+}
+/**
+ * @internal Generated `App` of a nested-layout app (`_sync`'s `inPlace`): a search-only change of the shown live
+ * page (`from`: the URL `_sync` saw last) refreshes it in place — no level key moves, the layouts keep their data
+ * unless their loaders read the URL. A failed loader re-renders the page level (`_bump` + `_sync`).
+ */
+export function _liveLevels(router, live, state, table, from, url) {
+    const shown = new URL(from);
+    if (!live.s || live.u !== shown.pathname + shown.search || url.pathname !== shown.pathname || url.search === shown.search)
+        return false;
+    live.u = url.pathname + url.search;
+    void refresh(router, live, url, undefined, _keepIds(state, table, url), _inPlace, state, table, () => {
+        _bump();
+        _sync(router, state, table);
+    });
+    return true;
+}
+/** @internal Generated route render of a live page: its `data` accessor (a new signal per render). */
+export function _livePage(slot, value, url, depth) {
+    const data = signal(value);
+    slot.s = data;
+    slot.u = url.pathname + url.search;
+    slot.d = depth;
+    return data;
+}
+/**
+ * @internal Generated `App` (`rivet:go`) when some page is live: same-URL revalidations of the shown
+ * live page refresh in place; everything else is served like `_serve`.
+ */
+export function _serveLive(router, live, state, table) {
+    for (const request of _take())
+        if (!inPlace(router, live, request, state, table))
+            _perform(router, request, state, table);
+}
+function inPlace(router, live, request, state, table) {
+    const { url, done } = request;
+    const target = request.invalidate;
+    // Not a revalidation, no client router, another page shown, or a navigation in flight: the regular path.
+    if (!target || !router.navigate || !live.s || live.u !== url.pathname + url.search || _current())
+        return false;
+    let keep;
+    if (typeof target === "function") {
+        _dropPrefetch();
+        const plan = _plan(state, table, url, target);
+        // Nothing matched, or layouts only (they refresh in place already): the regular path.
+        if (plan && !plan.page)
+            return false;
+        // The page's loader reruns; layouts whose keys did not match stay kept.
+        if (plan) {
+            _invalidating(url, plan.drop);
+            keep = _keepIds(state, table, url);
+        }
+        else
+            _stale();
+    }
+    else
+        _clearPrefetch();
+    void refresh(router, live, url, typeof target === "object" ? target : undefined, keep, done, state, table);
+    return true;
+}
+async function refresh(router, live, url, fresh, keep, done, state, table, 
+// A search navigation: its Router commit on a failed loader (else none: the regular rerun).
+search) {
+    const n = (live.n = (live.n ?? 0) + 1);
+    let result;
+    if (fresh?.data) {
+        // An enhanced action's single-flight answer: no request.
+        result = { data: fresh.data };
+        _depsLoaded(url, fresh.data.length, fresh.deps);
+        if (fresh.head?.title !== undefined)
+            document.title = fresh.head.title;
+    }
+    else
+        try {
+            // Detached from any navigation (a redirect answer navigates and never settles).
+            result = await routeData({ signal: new AbortController().signal, get: () => null }, { url }, router, live.m, keep);
+        }
+        catch {
+            // A failed loader: the page re-renders with the route's error view (a search navigation: its Router commit).
+            if (!search)
+                return _perform(router, { url, invalidate: true, done }, state, table);
+            if (n === live.n)
+                search();
+            return;
+        }
+    // A newer refresh, or a navigation that started meanwhile, wins (a search navigation: the one in flight is its own).
+    const nav = _current();
+    if (n === live.n && (!nav || (search && nav.to.pathname + nav.to.search === live.u)) && live.u === location.pathname + location.search) {
+        batch(() => {
+            if (state && table)
+                _refreshed(state, table, url, result);
+            live.s.set(result.data[live.d]);
+        });
+        done();
+    }
+    else if (!search)
+        done();
+}

package/client/navigate.d.ts

@@ -0,0 +1,71 @@
+import type { LinkHref } from "../index.js";
+import type { Head, LoaderDeps } from "../shared/data.js";
+/** Options of `navigate()`. */
+export interface NavigateOptions {
+    /** Replace the current history entry instead of pushing one. */
+    replace?: boolean;
+    /** App keys merged into the new entry's `history.state` (the router adds `i` and `rivet`). */
+    state?: Readonly<Record<string, unknown>>;
+    /** `false`: keep the scroll position instead of scrolling to the top / `#hash` target. */
+    scroll?: boolean;
+    /** `false`: leave focus where it is instead of moving it to the new page's heading. */
+    focus?: boolean;
+    /** View transition types for this navigation (like `<Link transition>`); `false`: no animation. */
+    transition?: string | readonly string[] | false;
+}
+/** @internal A queued request, served by the app router (`_serve`). */
+export interface NavigateRequest extends NavigateOptions {
+    readonly url: URL;
+    /** Same URL, fresh route data (`invalidate()`); data already in hand skips the request; a key test reruns matching loaders only. */
+    readonly invalidate?: true | FreshData | ((key: string) => boolean);
+    readonly done: () => void;
+}
+/** @internal Take the queued requests (the app router serves them). */
+export declare const _take: () => NavigateRequest[];
+/**
+ * @internal The router brand's entry (`_brand`, booted App only: its `rivet:go` listener serves the request): a
+ * navigation (outside the base path: a document load) or, with `invalidate`, fresh data for the shown URL.
+ */
+export declare function _go(url: URL, invalidate?: true | FreshData): Promise<void>;
+/** Route data in the data-endpoint shape (an enhanced action's single-flight answer). */
+export interface FreshData {
+    readonly data?: readonly unknown[];
+    readonly head?: Head;
+    /** The loaders' `event.depends()` keys (the answer's `deps`). */
+    readonly deps?: LoaderDeps;
+}
+/**
+ * What `invalidate()` reruns: loaders that called `event.depends(key)` with a matching key — one key
+ * (a `URL` counts as its `href`), any of a list, or those a predicate accepts (it gets each key).
+ */
+export type InvalidateTarget = string | URL | readonly (string | URL)[] | ((key: string) => boolean);
+/**
+ * Navigate like a link click, from anywhere (event handlers, effects, other libraries): same
+ * `rivet:navigate` (cancelable) event, transitions, pending state, announcer, focus and scroll
+ * bookkeeping. Resolves once the new page committed (or immediately for a hash-only change, a
+ * canceled navigation or the current URL). `to` strings starting with `/` are app paths (the URL base
+ * path is added). Cross-origin URLs, URLs outside the base and pages without a client router load
+ * the document (`location.assign`; the promise then never settles). Non-HTTP(S) URLs reject.
+ */
+export declare function navigate(to: LinkHref | (string & {}) | URL, options?: NavigateOptions): Promise<void>;
+/**
+ * Re-run the current page's loaders (fresh route data for the same URL) and re-render it in place:
+ * no history entry, transition, scroll or focus move (the focused control keeps focus by id). Also
+ * clears the intent-prefetch cache. `fresh` (data in the data-endpoint shape, such as an enhanced
+ * action's single-flight answer) skips the request. Resolves when the fresh page committed; without
+ * a client router the document reloads.
+ *
+ * `invalidate(key | keys | (key) => boolean)`: only the loaders whose `event.depends()` keys match
+ * rerun (one data request; the others are kept). The page re-renders when its own loader reruns;
+ * otherwise only the layouts that reran update in place. Nothing matches: no request. Keys not known
+ * yet (dev mounts, apps without layouts before their first client navigation): every loader reruns.
+ */
+export declare function invalidate(target?: FreshData | InvalidateTarget): Promise<void>;
+/** Alias of `invalidate()`. */
+export declare const revalidate: typeof invalidate;
+/**
+ * Navigate to the current path with new search params (the hash is dropped). `update`: the new
+ * params, or a function of a copy of the current ones. Like any search change, the route re-runs
+ * (loaders, page re-render); scroll and focus stay unless `scroll` / `focus` say otherwise.
+ */
+export declare function setSearchParams(update: URLSearchParams | Record<string, string> | ((current: URLSearchParams) => URLSearchParams | Record<string, string> | void), options?: NavigateOptions): Promise<void>;

package/client/navigate.js

@@ -0,0 +1,120 @@
+import { underBase, withBase } from "../shared/base.js";
+import { slashPath, TRAILING_SLASH } from "../shared/slash.js";
+const queue = [];
+/** @internal Take the queued requests (the app router serves them). */
+export const _take = () => queue.splice(0);
+/**
+ * @internal The router brand's entry (`_brand`, booted App only: its `rivet:go` listener serves the request): a
+ * navigation (outside the base path: a document load) or, with `invalidate`, fresh data for the shown URL.
+ */
+export function _go(url, invalidate) {
+    if (!invalidate && !underBase(url.pathname))
+        return (location.assign(url.href), new Promise(() => { }));
+    if (!invalidate && TRAILING_SLASH !== "ignore")
+        url.pathname = slashPath(url.pathname, TRAILING_SLASH);
+    return new Promise((done) => {
+        queue.push({ url, ...(invalidate ? { invalidate } : {}), done });
+        document.dispatchEvent(new CustomEvent("rivet:go"));
+    });
+}
+// Unserved requests wait this long for the router, then load the document.
+const WAIT = 10_000;
+function serve(url, options, fallback) {
+    return new Promise((resolve) => {
+        const d = document;
+        const ask = () => pending() && d.dispatchEvent(new CustomEvent("rivet:go"));
+        let timer;
+        // Only the resumed-page wait (below) listens.
+        const settle = () => timer && (clearTimeout(timer), d.removeEventListener("rivet:attach", ask));
+        const request = { ...options, url, done: () => (settle(), resolve()) };
+        const pending = () => queue.includes(request);
+        const drop = () => (settle(), queue.splice(queue.indexOf(request), 1), fallback());
+        queue.push(request);
+        ask();
+        if (!pending())
+            return;
+        // No App listening (the app was built without navigate() detected) or no resume loader: a document load.
+        const loader = d.$r;
+        if (!loader || !d.querySelector("[data-rivet-go]"))
+            return drop();
+        // Resumed page: the App's listener attaches when the resume runtime drains its pending listeners (at idle, or
+        // before the first delegated handler runs) and says so (`rivet:attach`): ask again then; its chunk loads on the
+        // first `rivet:go`. Boot the runtime now; no answer within WAIT: a document load.
+        d.addEventListener("rivet:attach", ask);
+        timer = setTimeout(() => pending() && drop(), WAIT);
+        if (!loader.r?.())
+            loader.b?.();
+    });
+}
+/**
+ * Navigate like a link click, from anywhere (event handlers, effects, other libraries): same
+ * `rivet:navigate` (cancelable) event, transitions, pending state, announcer, focus and scroll
+ * bookkeeping. Resolves once the new page committed (or immediately for a hash-only change, a
+ * canceled navigation or the current URL). `to` strings starting with `/` are app paths (the URL base
+ * path is added). Cross-origin URLs, URLs outside the base and pages without a client router load
+ * the document (`location.assign`; the promise then never settles). Non-HTTP(S) URLs reject.
+ */
+export function navigate(to, options = {}) {
+    if (typeof document === "undefined")
+        return Promise.reject(new Error("navigate() needs a browser"));
+    // App paths (`/items/1`) get the URL base path; full and relative URLs are taken as they are.
+    const url = new URL(typeof to === "string" ? withBase(to) : to, location.href);
+    if (!/^https?:$/.test(url.protocol))
+        return Promise.reject(new TypeError("navigate() requires an HTTP(S) URL"));
+    const load = () => location[options.replace ? "replace" : "assign"](url.href);
+    // Another origin, or outside the app's base path: a document load.
+    if (url.origin !== location.origin || !underBase(url.pathname)) {
+        load();
+        return new Promise(() => { });
+    }
+    // `rivetRouter({ trailingSlash })`: the app's paths in their canonical form (folded away by default).
+    if (TRAILING_SLASH !== "ignore")
+        url.pathname = slashPath(url.pathname, TRAILING_SLASH);
+    return serve(url, options, load);
+}
+/**
+ * Re-run the current page's loaders (fresh route data for the same URL) and re-render it in place:
+ * no history entry, transition, scroll or focus move (the focused control keeps focus by id). Also
+ * clears the intent-prefetch cache. `fresh` (data in the data-endpoint shape, such as an enhanced
+ * action's single-flight answer) skips the request. Resolves when the fresh page committed; without
+ * a client router the document reloads.
+ *
+ * `invalidate(key | keys | (key) => boolean)`: only the loaders whose `event.depends()` keys match
+ * rerun (one data request; the others are kept). The page re-renders when its own loader reruns;
+ * otherwise only the layouts that reran update in place. Nothing matches: no request. Keys not known
+ * yet (dev mounts, apps without layouts before their first client navigation): every loader reruns.
+ */
+export function invalidate(target) {
+    if (typeof document === "undefined")
+        return Promise.resolve();
+    return serve(new URL(location.href), { invalidate: invalidation(target) }, () => location.reload());
+}
+const href = (key) => (typeof key === "string" ? key : key.href);
+function invalidation(target) {
+    if (typeof target === "function")
+        return target;
+    if (typeof target === "string" || target instanceof URL) {
+        const key = href(target);
+        return (k) => k === key;
+    }
+    if (Array.isArray(target)) {
+        const keys = new Set(target.map(href));
+        return (k) => keys.has(k);
+    }
+    return target?.data ? target : true;
+}
+/** Alias of `invalidate()`. */
+export const revalidate = invalidate;
+/**
+ * Navigate to the current path with new search params (the hash is dropped). `update`: the new
+ * params, or a function of a copy of the current ones. Like any search change, the route re-runs
+ * (loaders, page re-render); scroll and focus stay unless `scroll` / `focus` say otherwise.
+ */
+export function setSearchParams(update, options = {}) {
+    const url = new URL(location.href);
+    const current = new URLSearchParams(url.search);
+    const next = typeof update === "function" ? (update(current) ?? current) : update;
+    url.search = new URLSearchParams(next).toString();
+    url.hash = "";
+    return navigate(url, { scroll: false, focus: false, ...options });
+}

package/client/navigation.d.ts

@@ -0,0 +1,28 @@
+import { type Context, type Signal } from "@rivetjs/reactivity";
+/** How a navigation started. */
+export type NavigationType = "push" | "replace" | "back" | "forward";
+/** State of the client navigation in flight (`useNavigation()`). */
+export interface NavigationState {
+    /** `submitting` is reserved for enhanced forms. */
+    readonly state: "idle" | "loading" | "submitting";
+    /** Destination of the navigation in flight. */
+    readonly location: URL | null;
+    readonly from: URL | null;
+    readonly type: NavigationType | null;
+    /** Indicator visible: set after `pending.delay`, kept at least `pending.minDuration`. */
+    readonly shown: boolean;
+}
+/** Navigation state when nothing is loading. */
+export declare const IDLE: NavigationState;
+/** Browser navigation state (the transitions module writes it; idle on the server and without transitions). */
+export declare const navigation: Signal<NavigationState>;
+/**
+ * Resumable navigation context: the server entry provides `navigation` under this id, so resumed
+ * regions that read it revive to the browser signal (`createResume({ contexts })`).
+ */
+export declare const Navigation: Context<() => NavigationState>;
+/** @internal Route commits record the shown search and run `search` (set by search.ts when loaded). */
+export declare const _searchSync: {
+    shown?: string;
+    search?: () => void;
+};

package/client/navigation.js

@@ -0,0 +1,14 @@
+// Navigation state shared by the router client, the lazy transitions module and resumed components.
+// Kept tiny: the resume entry imports it (the context must exist before any component resumes).
+import { createContext, signal } from "@rivetjs/reactivity";
+/** Navigation state when nothing is loading. */
+export const IDLE = Object.freeze({ state: "idle", location: null, from: null, type: null, shown: false });
+/** Browser navigation state (the transitions module writes it; idle on the server and without transitions). */
+export const navigation = signal(IDLE);
+/**
+ * Resumable navigation context: the server entry provides `navigation` under this id, so resumed
+ * regions that read it revive to the browser signal (`createResume({ contexts })`).
+ */
+export const Navigation = createContext(navigation, { id: "rivet:navigation" });
+/** @internal Route commits record the shown search and run `search` (set by search.ts when loaded). */
+export const _searchSync = {};

package/client/params.d.ts

@@ -0,0 +1,16 @@
+import { type Context } from "@rivetjs/reactivity";
+import type { RouteId, RouteParams } from "../index.js";
+/** @internal Route params of the rendered route (generated apps provide it per route render). */
+export declare const RouteParamsContext: Context<() => Readonly<Record<string, string>>>;
+/**
+ * The current route's params: `const params = useParams<"items/[id]">(); params().id`. Call during
+ * component setup. Pages re-render per navigation, so their value is that page's; nested layouts
+ * stay mounted and see the current route's params; the root layout (outside the routes) sees `{}`.
+ */
+export declare function useParams<R extends RouteId = never>(): () => Readonly<[R] extends [never] ? Record<string, string> : RouteParams[R]>;
+/**
+ * The current URL's search params, updated when a navigation commits (also in the root layout and
+ * resumed regions): `const search = useSearchParams(); search().get("q")`. Call during component setup.
+ * Treat the value as read-only; change it with `setSearchParams`.
+ */
+export declare function useSearchParams(): () => URLSearchParams;

package/client/params.js

@@ -0,0 +1,28 @@
+// Route params and search params accessors for components under file routes. Both are signals, so a
+// resumed binding that reads them revives without running component code:
+// - params: each page render provides `signal(match.params)` (the page re-renders on every
+//   navigation, so the signal of a mounted page never changes; its value resumes with the page);
+//   persisted nested layouts get their App-level params signal (updated in place);
+// - search: an identified context (the server provides the request's, resumed regions revive to
+//   the browser signal that route commits update), also live in the root layout.
+import { createContext, signal, useContext } from "@rivetjs/reactivity";
+import { SearchParams } from "./search.js";
+const none = signal(Object.freeze({}));
+/** @internal Route params of the rendered route (generated apps provide it per route render). */
+export const RouteParamsContext = createContext(none);
+/**
+ * The current route's params: `const params = useParams<"items/[id]">(); params().id`. Call during
+ * component setup. Pages re-render per navigation, so their value is that page's; nested layouts
+ * stay mounted and see the current route's params; the root layout (outside the routes) sees `{}`.
+ */
+export function useParams() {
+    return useContext(RouteParamsContext);
+}
+/**
+ * The current URL's search params, updated when a navigation commits (also in the root layout and
+ * resumed regions): `const search = useSearchParams(); search().get("q")`. Call during component setup.
+ * Treat the value as read-only; change it with `setSearchParams`.
+ */
+export function useSearchParams() {
+    return useContext(SearchParams);
+}

package/client/route-context.d.ts

@@ -0,0 +1,32 @@
+import { type Context } from "@rivetjs/reactivity";
+import type { ActionResult, HeadSink, RoutePayload } from "../shared/data.js";
+import type { ActionName, ActionResultOf, RouteActions } from "../index.js";
+/** Server render input handed to routes through context (never serialized: no id). */
+export interface ServerRoutePayload extends RoutePayload {
+    readonly url: URL;
+    /** Set when the handler failed the request (rendered by the route's error view). */
+    readonly error?: {
+        readonly status: number;
+        readonly message: string;
+    };
+    /** The form action the request performed (no-JS POST). */
+    readonly action?: ActionResult;
+    /** Server render with `@rivetjs/kit`: the request's component head collector. */
+    readonly headSink?: HeadSink;
+    /** Layouts whose loader read the URL: never kept by client navigation (unknown: none kept). */
+    readonly byURL?: readonly number[];
+}
+/** Context with the route data the server already loaded for this render. */
+export declare const ServerData: Context<ServerRoutePayload | null>;
+/**
+ * The result of the form action this page was rendered after (a no-JS POST to `?/name`), when
+ * `name` matches (any action when omitted). Call during component setup (server render; dev client
+ * mount). In the browser each action result answers once, so later client renders start clean.
+ */
+export declare function actionResult(name?: string): ActionResult | undefined;
+/**
+ * Typed: `actionResult<"items/[id]">("save")` (route id, generated `RouteActions`) or
+ * `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/client/route-context.js

@@ -0,0 +1,21 @@
+// Server render input handed to routes through context, and the form action result read from it.
+import { createContext, useContext } from "@rivetjs/reactivity";
+/** Context with the route data the server already loaded for this render. */
+export const ServerData = createContext(null);
+let actionsRead;
+export function actionResult(name) {
+    const server = useContext(ServerData);
+    const action = server?.action;
+    if (!server || !action || (name !== undefined && action.name !== name))
+        return undefined;
+    if (typeof document !== "undefined") {
+        actionsRead ??= new WeakMap();
+        let read = actionsRead.get(server);
+        if (!read)
+            actionsRead.set(server, (read = new Set()));
+        if (read.has(action.name))
+            return undefined;
+        read.add(action.name);
+    }
+    return action;
+}

package/client/scroll.d.ts

@@ -0,0 +1,16 @@
+/** Key the current history entry (merged into its state) and make it the shown one. */
+export declare function enter(i: number): void;
+/**
+ * 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 declare function leave(here: boolean, i: number): void;
+/** Restore the current entry's saved position; false when there is none. */
+export declare function restoreScroll(): boolean;
+/** Make `element` the focus (programmatically focusable when it is not already). */
+export declare function focusOn(element: HTMLElement): void;
+/** The element a URL's fragment names, if any. */
+export declare function fragmentTarget(url: URL): HTMLElement | null;
+/** Hash-only navigation: scroll to and focus the fragment's target; no fragment scrolls to the top. */
+export declare function reveal(url: URL): void;