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

package/server/strict-csp.d.ts

@@ -0,0 +1,7 @@
+import { type CSPOptions } from "../shared/csp.js";
+/**
+ * Strict CSP: only nonce'd scripts and what they load run; no plugins, no `<base>` hijacking.
+ * `{ trustedTypes: true }` also enforces Trusted Types (`csp: (nonce) => strictCSP(nonce, { trustedTypes: true })`);
+ * `{ directives }` merges extra directives (`cspPolicy`).
+ */
+export declare const strictCSP: (nonce: string, options?: CSPOptions) => string;

package/server/strict-csp.js

@@ -0,0 +1,18 @@
+// `strictCSP` with `directives`: own module so `createApp` loads the directive merge only when an app passes
+// directives (dynamic import); the default policy is `nonceCSP` (shared/csp.ts).
+import { nonceCSP } from "../shared/csp.js";
+import { cspPolicy } from "../shared/csp-directives.js";
+/**
+ * Strict CSP: only nonce'd scripts and what they load run; no plugins, no `<base>` hijacking.
+ * `{ trustedTypes: true }` also enforces Trusted Types (`csp: (nonce) => strictCSP(nonce, { trustedTypes: true })`);
+ * `{ directives }` merges extra directives (`cspPolicy`).
+ */
+export const strictCSP = (nonce, options) => options?.directives
+    ? cspPolicy([
+        ["script-src", [`'nonce-${nonce}'`, "'strict-dynamic'"]],
+        ["object-src", ["'none'"]],
+        ["base-uri", ["'none'"]],
+    ], options, false, 
+    // Inline `<style>`s (inlined stylesheets, head styles) carry the nonce: allowed by a `style-src` the app sets.
+    [`'nonce-${nonce}'`])
+    : nonceCSP(nonce, options);

package/server-only.d.ts

@@ -0,0 +1 @@
+export {};

package/server-only.js

@@ -0,0 +1,3 @@
+// Marker: `import "@rivetjs/router/server-only"` in a module that must never reach a browser bundle.
+// Browser builds of the router plugin fail on this import; on the server it is empty.
+export {};

package/shared/actions.d.ts

@@ -0,0 +1,10 @@
+/** A failed action: HTTP `status` plus the data the page (or the enhanced submit) receives. */
+export declare class ActionFailure<T = unknown> {
+    readonly status: number;
+    readonly data: T;
+    constructor(status: number, data: T);
+}
+/** Fail an action with a 4xx status (e.g. 400 for invalid input) and the data to render. */
+export declare function fail<T>(status: number, data: T): ActionFailure<T>;
+/** Whether a value is an `ActionFailure` returned by `fail()`. */
+export declare const isActionFailure: (value: unknown) => value is ActionFailure;

package/shared/actions.js

@@ -0,0 +1,18 @@
+// Action results that are not success: returned by an action to answer with a 4xx status and data
+// (validation failures). The page still renders (loaders run) and receives the data as the action
+// result; enhanced (JSON) submits get `{ action: { name, result, status } }` with that status.
+/** A failed action: HTTP `status` plus the data the page (or the enhanced submit) receives. */
+export class ActionFailure {
+    constructor(status, data) {
+        this.status = status;
+        this.data = data;
+    }
+}
+/** Fail an action with a 4xx status (e.g. 400 for invalid input) and the data to render. */
+export function fail(status, data) {
+    if (!Number.isInteger(status) || status < 400 || status > 499)
+        throw new RangeError("fail() status must be 4xx");
+    return new ActionFailure(status, data);
+}
+/** Whether a value is an `ActionFailure` returned by `fail()`. */
+export const isActionFailure = (value) => value instanceof ActionFailure;

package/shared/base.d.ts

@@ -0,0 +1,8 @@
+/** Normalize a base (`/app/`, `/app`, `/`, `./`) to `""` (root) or `/app` (no trailing slash). */
+export declare function normalizeBase(base: string | undefined): string;
+/** The app's base path without trailing slash; `""` at the root. */
+export declare const BASE: string;
+/** An app path (`/items/1?q`) as a URL path under the base; other forms (full, relative URLs) unchanged. */
+export declare function withBase(to: string, base?: string): string;
+/** Whether a URL path lies under the base (the app's routes can serve it). */
+export declare function underBase(pathname: string, base?: string): boolean;

package/shared/base.js

@@ -0,0 +1,20 @@
+// App base path (`rivetRouter({ base: "/app" })` or Vite's `base`): Vite replaces
+// `import.meta.env.BASE_URL` in every module it builds (client and server bundles); outside Vite
+// (plain Node) it is the root. Route patterns in the generated files already carry the base;
+// these helpers serve code that takes app paths (`<Link to>`, `navigate()`).
+/** Normalize a base (`/app/`, `/app`, `/`, `./`) to `""` (root) or `/app` (no trailing slash). */
+export function normalizeBase(base) {
+    if (!base || !base.startsWith("/"))
+        return "";
+    return base.replace(/\/+$/, "");
+}
+/** The app's base path without trailing slash; `""` at the root. */
+export const BASE = normalizeBase(import.meta.env?.BASE_URL);
+/** An app path (`/items/1?q`) as a URL path under the base; other forms (full, relative URLs) unchanged. */
+export function withBase(to, base = BASE) {
+    return base && to.startsWith("/") && !to.startsWith("//") ? base + to : to;
+}
+/** Whether a URL path lies under the base (the app's routes can serve it). */
+export function underBase(pathname, base = BASE) {
+    return !base || pathname === base || pathname.startsWith(base + "/");
+}

package/shared/cookie.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Parse a `Cookie` request header (RFC 6265 §5.4 shape): `name=value` pairs split on `;`, names and
+ * values trimmed, one pair of surrounding double quotes removed, values percent-decoded (a value that
+ * is not valid percent-encoding is kept as written). The first occurrence of a name wins (browsers
+ * send the most specific path first); pairs without `=` or with an empty name are skipped.
+ */
+export declare function parseCookies(header: string | null | undefined): Map<string, string>;

package/shared/cookie.js

@@ -0,0 +1,32 @@
+// Cookie header parsing: the one implementation behind `event.cookies` (server/handler.ts) and
+// `@rivetjs/i18n` locale resolution (`requestSource`).
+/**
+ * Parse a `Cookie` request header (RFC 6265 §5.4 shape): `name=value` pairs split on `;`, names and
+ * values trimmed, one pair of surrounding double quotes removed, values percent-decoded (a value that
+ * is not valid percent-encoding is kept as written). The first occurrence of a name wins (browsers
+ * send the most specific path first); pairs without `=` or with an empty name are skipped.
+ */
+export function parseCookies(header) {
+    const out = new Map();
+    if (!header)
+        return out;
+    for (const part of header.split(";")) {
+        const at = part.indexOf("=");
+        if (at < 0)
+            continue;
+        const name = part.slice(0, at).trim();
+        if (!name || out.has(name))
+            continue;
+        const raw = part
+            .slice(at + 1)
+            .trim()
+            .replace(/^"(.*)"$/, "$1");
+        try {
+            out.set(name, decodeURIComponent(raw));
+        }
+        catch {
+            out.set(name, raw);
+        }
+    }
+    return out;
+}

package/shared/csp-directives.d.ts

@@ -0,0 +1,9 @@
+import { type CSPOptions } from "./csp.js";
+/**
+ * The policy string for `generated` (directive → sources, in order) merged with `options.directives`
+ * and the Trusted Types directives. `meta`: the policy goes into a `<meta>` (header-only directives throw).
+ * `styles`: the sources of the page's own `<style>` elements (nonce / hashes: inlined stylesheets, head styles), added
+ * to a `style-src` / `style-src-elem` the options set (none set: inline styles are not restricted). A list with
+ * `'unsafe-inline'` is left as given (a nonce or hash would turn it off).
+ */
+export declare function cspPolicy(generated: readonly (readonly [string, readonly string[]])[], options: CSPOptions | undefined, meta?: boolean, styles?: readonly string[]): string;

package/shared/csp-directives.js

@@ -0,0 +1,85 @@
+// CSP directive merge + validation (`directives` option): loaded only by apps that pass directives
+// (`createApp` dynamic import, `strictCSP` / static `hashCSP`), so the default policy carries none of it.
+import { trustedTypesDirectives } from "./csp.js";
+/** CSP Level 3 directive names (+ Trusted Types, `upgrade-insecure-requests`, reporting). */
+const DIRECTIVES = new Set([
+    "default-src",
+    "script-src",
+    "script-src-elem",
+    "script-src-attr",
+    "style-src",
+    "style-src-elem",
+    "style-src-attr",
+    "img-src",
+    "font-src",
+    "connect-src",
+    "media-src",
+    "object-src",
+    "child-src",
+    "frame-src",
+    "worker-src",
+    "manifest-src",
+    "fenced-frame-src",
+    "base-uri",
+    "form-action",
+    "frame-ancestors",
+    "sandbox",
+    "upgrade-insecure-requests",
+    "report-uri",
+    "report-to",
+    "webrtc",
+]);
+/** Ignored by browsers in a `<meta>` policy (CSP3 §3.3): header only. */
+const HEADER_ONLY = new Set(["frame-ancestors", "report-uri", "report-to", "sandbox"]);
+// One source expression: no whitespace, no directive / policy separators, nothing that breaks out of an attribute.
+const SOURCE = /^[^\s;,"'<>\\]+$|^'[A-Za-z0-9+/=_-]+'$/;
+/**
+ * The policy string for `generated` (directive → sources, in order) merged with `options.directives`
+ * and the Trusted Types directives. `meta`: the policy goes into a `<meta>` (header-only directives throw).
+ * `styles`: the sources of the page's own `<style>` elements (nonce / hashes: inlined stylesheets, head styles), added
+ * to a `style-src` / `style-src-elem` the options set (none set: inline styles are not restricted). A list with
+ * `'unsafe-inline'` is left as given (a nonce or hash would turn it off).
+ */
+export function cspPolicy(generated, options, meta = false, styles = []) {
+    const policy = new Map(generated.map(([name, sources]) => [name, [...sources]]));
+    const extra = options?.directives;
+    if (extra) {
+        for (const [raw, value] of Object.entries(extra)) {
+            const name = raw.toLowerCase();
+            if (name === "require-trusted-types-for" || name === "trusted-types")
+                throw new TypeError(`CSP directive "${raw}": use the trustedTypes option`);
+            if (!DIRECTIVES.has(name))
+                throw new TypeError(`Unknown CSP directive "${raw}"`);
+            if (meta && HEADER_ONLY.has(name))
+                throw new TypeError(`CSP directive "${name}" is ignored in a <meta> policy: send it as a header from your host`);
+            const sources = value === true ? [] : typeof value === "string" ? value.split(/\s+/).filter(Boolean) : [...value];
+            for (const source of sources)
+                if (typeof source !== "string" || !SOURCE.test(source))
+                    throw new TypeError(`Invalid CSP source ${JSON.stringify(source)} in "${name}"`);
+            if (name === "script-src" || name === "script-src-elem") {
+                // Additive: the generated sources (nonce / hashes) are what lets the page's own scripts run.
+                const list = policy.get(name) ?? (name === "script-src-elem" ? [...(policy.get("script-src") ?? [])] : []);
+                for (const source of sources)
+                    if (!list.includes(source))
+                        list.push(source);
+                policy.set(name, list);
+            }
+            else {
+                policy.delete(name);
+                policy.set(name, sources);
+            }
+        }
+    }
+    if (styles.length)
+        for (const name of ["style-src", "style-src-elem"]) {
+            const list = policy.get(name);
+            if (list && !list.includes("'unsafe-inline'"))
+                for (const source of styles)
+                    if (!list.includes(source))
+                        list.push(source);
+        }
+    let out = "";
+    for (const [name, sources] of policy)
+        out += (out ? "; " : "") + (sources.length ? `${name} ${sources.join(" ")}` : name);
+    return out + trustedTypesDirectives(options);
+}

package/shared/csp-hash.d.ts

@@ -0,0 +1,39 @@
+import type { CSPOptions } from "./csp.js";
+/** A page's inline code a hash policy must allow. */
+export interface InlineSources {
+    /** Bodies of the executable inline scripts, in page order (duplicates kept: callers dedupe the hashes). */
+    readonly scripts: string[];
+    /** Bodies of the `<style>` elements (only when asked: `styles`). */
+    readonly styles: string[];
+    /** Origins of third-party script files (`<script src>`, the kit `#rivet-scripts` bootstrap list). */
+    readonly origins: Set<string>;
+}
+/** Collect what a hash policy for `html` allows; `styles`: also the `<style>` bodies (the options set a `style-src`). */
+export declare function inlineSources(html: string, styles: boolean): InlineSources;
+/** Byte ranges (`[start, end)`) of what a stored page's hash policy allows, and where its nonce attributes are. */
+export interface NoncedSources {
+    /** Bodies of the executable inline scripts that carry the nonce. */
+    readonly scripts: [number, number][];
+    /** Bodies of the `<style>` elements that carry the nonce (only when asked: `styles`). */
+    readonly styles: [number, number][];
+    /** Origins of third-party script files whose `<script src>` carries the nonce (and of the kit `#rivet-scripts` list in a nonce'd bootstrap). */
+    readonly origins: Set<string>;
+    /** Start offsets of each ` nonce="…"` attribute (`' nonce="'.length + nonce.length + 1` long). */
+    readonly attrs: number[];
+}
+/**
+ * Collect what the hash policy of a nonce-rendered page allows: only `<script>` / `<style>` / `<link>` start tags that
+ * carry ` nonce="<nonce>"` (the renderer's own elements). `text`: the page as one character per byte (latin1), so
+ * offsets are byte offsets; `utf8(start, end)`: those bytes as text (script URLs, the bootstrap list). Null — the page
+ * must not be stored — when the nonce appears anywhere else (script text, an attribute value, a malformed tag): a
+ * stored copy would hand one nonce to every visitor, or the tag is not one the renderer wrote.
+ */
+export declare function noncedSources(text: string, nonce: string, styles: boolean, utf8: (start: number, end: number) => string): NoncedSources | null;
+/**
+ * The hash policy: `script-src` = the scripts' hashes + `'self'` + script origins, `object-src` / `base-uri` `'none'`,
+ * merged with `options` (`cspPolicy`; `meta`: header-only directives throw). Hashes are CSP sources (`'sha256-…'`).
+ * (`'strict-dynamic'` would not do: it trusts the scripts a trusted script inserts with `createElement("script")`, but
+ * an `import()` is fetched with the importing script's nonce, and a hash-allowed script has none — Chromium and Firefox
+ * block it (WebKit allows it); the resume loader imports its chunks. Pinned in `tests/route-cache-csp.test.ts`.)
+ */
+export declare function hashPolicy(scripts: Iterable<string>, origins: Iterable<string>, styles: readonly string[], options: CSPOptions | undefined, meta: boolean): string;

package/shared/csp-hash.js

@@ -0,0 +1,121 @@
+import { cspPolicy } from "./csp-directives.js";
+import { BOOT_LIST_END } from "./head.js";
+const SCRIPT = /<script\b([^>]*)>([\s\S]*?)<\/script\s*>/gi;
+const STYLE = /<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi;
+// Inline scripts script-src governs: no `src`, and no type, a JavaScript one or `speculationrules` (router document prefetch).
+const executable = (attrs) => {
+    if (/\ssrc\s*=/i.test(attrs))
+        return false;
+    const type = /\stype\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i.exec(attrs);
+    const value = (type?.[1] ?? type?.[2] ?? type?.[3] ?? "").trim().toLowerCase();
+    return value === "" || value === "module" || value === "text/javascript" || value === "application/javascript" || value === "speculationrules";
+};
+/** Collect what a hash policy for `html` allows; `styles`: also the `<style>` bodies (the options set a `style-src`). */
+export function inlineSources(html, styles) {
+    const scripts = [];
+    const origins = new Set();
+    for (const [, attrs = "", body = ""] of html.matchAll(SCRIPT)) {
+        if (executable(attrs))
+            scripts.push(body);
+        const src = /\ssrc\s*=\s*"([^"]*)"/i.exec(attrs)?.[1];
+        if (src)
+            addOrigin(origins, src.replaceAll("&amp;", "&"));
+        else if (/\sid\s*=\s*"rivet-scripts"/i.test(attrs))
+            bootOrigins(body, origins);
+    }
+    const out = [];
+    if (styles)
+        for (const [, body = ""] of html.matchAll(STYLE))
+            out.push(body);
+    return { scripts, styles: out, origins };
+}
+const NONCE_LEAD = ' nonce="';
+// A whole start tag the renderer writes: `<script|style|link` + attributes (quoted values without `<`) + `>`.
+const NONCED_TAG = /^<(script|style|link)((?:\s+[^\s"'<>/=]+(?:\s*=\s*(?:"[^"<]*"|'[^'<]*'|[^\s"'=<>`]+))?)*)\s*\/?>$/i;
+/**
+ * Collect what the hash policy of a nonce-rendered page allows: only `<script>` / `<style>` / `<link>` start tags that
+ * carry ` nonce="<nonce>"` (the renderer's own elements). `text`: the page as one character per byte (latin1), so
+ * offsets are byte offsets; `utf8(start, end)`: those bytes as text (script URLs, the bootstrap list). Null — the page
+ * must not be stored — when the nonce appears anywhere else (script text, an attribute value, a malformed tag): a
+ * stored copy would hand one nonce to every visitor, or the tag is not one the renderer wrote.
+ */
+export function noncedSources(text, nonce, styles, utf8) {
+    const scripts = [];
+    const out = [];
+    const origins = new Set();
+    const attrs = [];
+    if (!nonce)
+        return null;
+    const attr = NONCE_LEAD + nonce + '"';
+    for (let at = text.indexOf(nonce); at >= 0; at = text.indexOf(nonce, at + nonce.length)) {
+        const start = at - NONCE_LEAD.length;
+        if (start < 0 || !text.startsWith(attr, start))
+            return null;
+        const open = text.lastIndexOf("<", start);
+        const close = text.indexOf(">", at);
+        const tag = open < 0 || close < 0 ? null : NONCED_TAG.exec(text.slice(open, close + 1));
+        if (!tag)
+            return null;
+        attrs.push(start);
+        const name = tag[1].toLowerCase();
+        if (name === "link")
+            continue;
+        const end = text.indexOf(name === "script" ? "</script" : "</style", close + 1);
+        if (end < 0)
+            return null;
+        if (name === "style") {
+            if (styles)
+                out.push([close + 1, end]);
+            continue;
+        }
+        const attributes = tag[2];
+        if (executable(attributes))
+            scripts.push([close + 1, end]);
+        const src = /\ssrc\s*=\s*"([^"]*)"/i.exec(attributes);
+        if (src) {
+            // The value's bytes (`"` excluded): the attributes start right after `<script`.
+            const end = open + 1 + name.length + src.index + src[0].length - 1;
+            addOrigin(origins, utf8(end - src[1].length, end).replaceAll("&amp;", "&"));
+        }
+        else if (/\sid\s*=\s*"rivet-scripts"/i.test(attributes))
+            bootOrigins(utf8(close + 1, end), origins);
+    }
+    return { scripts, styles: out, origins, attrs };
+}
+function addOrigin(origins, src) {
+    const url = URL.canParse(src) ? new URL(src) : null;
+    if (url && (url.protocol === "https:" || url.protocol === "http:"))
+        origins.add(url.origin);
+}
+/** Kit script bootstrap: `{let l=<JSON list>,d=document,…`; the list ends at the first cut that parses. */
+function bootOrigins(body, origins) {
+    if (!body.startsWith("{let l="))
+        return;
+    for (let at = body.indexOf(BOOT_LIST_END); at > 0; at = body.indexOf(BOOT_LIST_END, at + 1)) {
+        let list;
+        try {
+            list = JSON.parse(body.slice(7, at));
+        }
+        catch {
+            continue;
+        }
+        for (const entry of list)
+            if (typeof entry.u === "string")
+                addOrigin(origins, entry.u);
+        break;
+    }
+}
+/**
+ * The hash policy: `script-src` = the scripts' hashes + `'self'` + script origins, `object-src` / `base-uri` `'none'`,
+ * merged with `options` (`cspPolicy`; `meta`: header-only directives throw). Hashes are CSP sources (`'sha256-…'`).
+ * (`'strict-dynamic'` would not do: it trusts the scripts a trusted script inserts with `createElement("script")`, but
+ * an `import()` is fetched with the importing script's nonce, and a hash-allowed script has none — Chromium and Firefox
+ * block it (WebKit allows it); the resume loader imports its chunks. Pinned in `tests/route-cache-csp.test.ts`.)
+ */
+export function hashPolicy(scripts, origins, styles, options, meta) {
+    return cspPolicy([
+        ["script-src", [...new Set(scripts), "'self'", ...origins]],
+        ["object-src", ["'none'"]],
+        ["base-uri", ["'none'"]],
+    ], options, meta, [...new Set(styles)]);
+}

package/shared/csp.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Extra CSP directives, merged with the generated policy. A value is a source list (string split on
+ * whitespace, or an array); `true` / `[]` / `""` is a directive without sources (`upgrade-insecure-requests`).
+ */
+export type CSPDirectives = Readonly<Record<string, string | readonly string[] | true>>;
+/** Content Security Policy options: directives, nonces and Trusted Types. */
+export interface CSPOptions {
+    /**
+     * Enforce Trusted Types: `require-trusted-types-for 'script'` with the runtime's `rivet` policy
+     * (template HTML) allowed. Pass policy names to allow your own as well.
+     */
+    readonly trustedTypes?: boolean | readonly string[];
+    /**
+     * Extra directives (`{ "script-src": "'wasm-unsafe-eval'", "worker-src": ["'self'", "blob:"] }`).
+     * `script-src` (and `script-src-elem`, when given) sources are added to the generated ones (nonce /
+     * hashes, `'self'`); `object-src` / `base-uri` replace the generated `'none'`; other directives are
+     * appended. Names are checked (unknown → `TypeError`); Trusted Types go through `trustedTypes`.
+     * Nothing is added implicitly (no `'unsafe-inline'`).
+     */
+    readonly directives?: CSPDirectives;
+}
+export { cspPolicy } from "./csp-directives.js";
+/** The default strict nonce policy (+ Trusted Types): what `strictCSP` returns without `directives`. */
+export declare const nonceCSP: (nonce: string, options?: CSPOptions) => string;
+/** The Trusted Types directives for `options` (empty when off), each prefixed with `; `. */
+export declare function trustedTypesDirectives(options: CSPOptions | undefined): string;

package/shared/csp.js

@@ -0,0 +1,13 @@
+// CSP options shared by the server (nonce policy) and the static adapter (hash policy).
+// The directive merge + validation lives in its own module (`csp-directives.ts`): apps without
+// `directives` never load it (`createApp` imports it dynamically; `strictCSP` / `hashCSP` statically).
+export { cspPolicy } from "./csp-directives.js";
+/** The default strict nonce policy (+ Trusted Types): what `strictCSP` returns without `directives`. */
+export const nonceCSP = (nonce, options) => `script-src 'nonce-${nonce}' 'strict-dynamic'; object-src 'none'; base-uri 'none'` + trustedTypesDirectives(options);
+/** The Trusted Types directives for `options` (empty when off), each prefixed with `; `. */
+export function trustedTypesDirectives(options) {
+    const names = options?.trustedTypes;
+    if (!names)
+        return "";
+    return `; require-trusted-types-for 'script'; trusted-types ${["rivet", ...(names === true ? [] : names)].join(" ")}`;
+}

package/shared/data.d.ts

@@ -0,0 +1,175 @@
+/** Query flag marking a client-navigation data request. */
+export declare const DATA_PARAM = "_rivet";
+/** Data requests: comma-separated ids of the layouts whose data the client still has (loaders skipped). */
+export declare const KEEP_PARAM = "_rivet_keep";
+/** `_rivet_keep` entry naming the page's own loader (`invalidate(key)` of layout keys only: same URL). */
+export declare const KEEP_PAGE = ".";
+/**
+ * `search` (`?a&b=c d`) without the router's own params (`_rivet`, `_rivet_keep`), every other byte
+ * as sent: loaders see the page URL's query exactly, so their keys match on HTML and data requests.
+ */
+export declare function withoutRivet(search: string): string;
+/** Dependency keys (`event.depends()`) per loader, route data order; undefined: none. Omitted when no loader called it. */
+export type LoaderDeps = readonly (readonly string[] | undefined)[];
+/**
+ * Document head a route (or a component, with `@rivetjs/kit`) contributes. Merged by rank: inner
+ * route levels win; within a level components win over the route's `head` export.
+ */
+export interface Head {
+    title?: string;
+    /** `"%s · Shop"`: applied once to the merged title; innermost wins. */
+    titleTemplate?: string;
+    /** `<html>` attributes (needs the kit head hold; merged per attribute). */
+    html?: {
+        lang?: string;
+        dir?: "ltr" | "rtl" | "auto";
+        class?: string;
+    };
+    body?: {
+        class?: string;
+    };
+    base?: {
+        href: string;
+        target?: string;
+    };
+    meta?: readonly HeadMeta[];
+    /** `<link>` tags; keyed per rel (one `canonical`; alternates by hreflang/type; others by href). */
+    links?: readonly HeadLink[];
+    scripts?: readonly HeadScript[];
+    /** Inline `<style>` blocks (trusted CSS, request nonce; deduped by `key`, else by text). Never managed: client navigation keeps them. */
+    styles?: readonly HeadStyle[];
+}
+/** An inline head `<style>` (component CSS such as `@rivetjs/motion` entrance rules). */
+export interface HeadStyle {
+    /** Trusted CSS text (a `</style` sequence is escaped). */
+    css: string;
+    /** Dedupe key (default: the CSS text). */
+    key?: string;
+    media?: string;
+}
+/** A head `<meta>`. */
+export interface HeadMeta {
+    name?: string;
+    property?: string;
+    httpEquiv?: string;
+    itemprop?: string;
+    content: string;
+    /** e.g. `theme-color` per color scheme; part of the dedupe key. */
+    media?: string;
+    /** Explicit dedupe key. */
+    key?: string;
+}
+/** A head `<link>`. */
+export interface HeadLink {
+    rel: string;
+    href: string;
+    type?: string;
+    hreflang?: string;
+    media?: string;
+    sizes?: string;
+    as?: string;
+    crossorigin?: "anonymous" | "use-credentials";
+    imagesrcset?: string;
+    imagesizes?: string;
+    fetchpriority?: "high" | "low" | "auto";
+    title?: string;
+    color?: string;
+    integrity?: string;
+    referrerpolicy?: string;
+    key?: string;
+}
+/** When a script runs: in the head while parsing (`blocking`, `eager` = async, `defer`) or later from a tiny bootstrap. */
+export type ScriptStrategy = "blocking" | "eager" | "defer" | "load" | "idle" | "interaction";
+/** Static inline script code (see `inlineScript`); plain strings are refused. */
+export interface InlineScript {
+    readonly code: string;
+}
+/** A head script: external (`src`), inline code, or a JSON-LD data block. */
+export type HeadScript = {
+    src: string;
+    type?: "module" | "classic";
+    /** Default `defer`. */
+    strategy?: ScriptStrategy;
+    id?: string;
+    integrity?: string;
+    crossorigin?: "anonymous" | "use-credentials";
+    referrerpolicy?: string;
+    key?: string;
+} | {
+    inline: InlineScript;
+    /** Position in the head (inline scripts always run while parsing). Default `defer`. */
+    strategy?: "blocking" | "eager" | "defer";
+    /** JSON the script reads from `document.currentScript.previousElementSibling`. */
+    data?: unknown;
+    id?: string;
+    key?: string;
+} | {
+    jsonLd: object;
+    id?: string;
+    key?: string;
+};
+/** Request collector of component head entries (`@rivetjs/kit`), provided through `ServerData`. */
+export interface HeadSink {
+    /** Record `head` for route level `level`; after the hold, returns the markup body-valid entries write in place. */
+    push(level: number, head: Head, component?: string): string | undefined;
+    /** CSP nonce of the response (inline scripts carry it). */
+    readonly nonce: string | undefined;
+}
+/** An action's outcome (form POST `?/name`): its return value, or the data and status of `fail()`. */
+export interface ActionResult {
+    readonly name: string;
+    readonly result: unknown;
+    /** Set when the action failed (`fail(status, data)`): the response status; `result` is the data. */
+    readonly status?: number;
+}
+/** The `error` member of a JSON answer: a request that failed (guard, action, loader, 404/405/413…). */
+export interface AnswerError {
+    readonly status: number;
+    readonly message: string;
+}
+/**
+ * The handler's JSON answer to an enhanced action POST (`?/name` with `accept: application/json`),
+ * resume-format encoded (`encodeData`); `@rivetjs/forms` decodes it. Exactly one of `action`,
+ * `redirect` or `error` is set.
+ */
+export interface ActionAnswer {
+    /** The action ran: its return value, or the data and status of `fail()`. */
+    readonly action?: ActionResult;
+    /** Single flight (`x-rivet-revalidate` request header, status < 400): the page's re-run loader data, layouts outermost first. */
+    readonly data?: readonly unknown[];
+    /** Single flight: the route head for the fresh data (when the app has a `head` hook). */
+    readonly head?: Head;
+    /** Single flight: the loaders' `event.depends()` keys (absent when none called it). */
+    readonly deps?: LoaderDeps;
+    /** A redirect (guard, `redirect()` in the action, a request handler's 3xx) the client follows; `status` is its 3xx. */
+    readonly redirect?: string;
+    readonly status?: number;
+    readonly error?: AnswerError;
+}
+/** The handler's JSON answer to a client-navigation data request (`?_rivet=data`), resume-format encoded. */
+export interface DataAnswer {
+    /** Loader results, layouts outermost first (`undefined` for the `keep` indices). */
+    readonly data?: readonly unknown[];
+    readonly status?: number;
+    readonly head?: Head;
+    /** Indices into `data` of kept layouts the server skipped (`_rivet_keep`). */
+    readonly keep?: readonly number[];
+    /** Indices of layouts whose loader read the URL. */
+    readonly byURL?: readonly number[];
+    readonly deps?: LoaderDeps;
+    readonly redirect?: string;
+    /** A guard or request handler answered with a non-redirect Response: load the document instead. */
+    readonly reload?: true;
+    readonly error?: AnswerError;
+}
+/** Loader results for one URL: layouts outermost first, then the page. */
+export interface RoutePayload {
+    readonly data: readonly unknown[];
+    readonly head?: Head;
+    /** Data requests: indices into `data` of layouts the server skipped (the client keeps their data). */
+    readonly kept?: readonly number[];
+    /** Data requests: indices of layouts whose loader read the URL (reloaded on every URL change). */
+    readonly byURL?: readonly number[];
+    /** Keys the loaders that ran passed to `event.depends()` (absent: none did). */
+    readonly deps?: LoaderDeps;
+}

package/shared/data.js

@@ -0,0 +1,22 @@
+// Wire contract between the server handler and the client router.
+/** Query flag marking a client-navigation data request. */
+export const DATA_PARAM = "_rivet";
+/** Data requests: comma-separated ids of the layouts whose data the client still has (loaders skipped). */
+export const KEEP_PARAM = "_rivet_keep";
+/** `_rivet_keep` entry naming the page's own loader (`invalidate(key)` of layout keys only: same URL). */
+export const KEEP_PAGE = ".";
+/**
+ * `search` (`?a&b=c d`) without the router's own params (`_rivet`, `_rivet_keep`), every other byte
+ * as sent: loaders see the page URL's query exactly, so their keys match on HTML and data requests.
+ */
+export function withoutRivet(search) {
+    if (!search.includes(DATA_PARAM))
+        return search;
+    let out = "";
+    for (const part of search.slice(1).split("&")) {
+        const name = part.split("=", 1)[0];
+        if (name !== DATA_PARAM && name !== KEEP_PARAM)
+            out += (out ? "&" : "?") + part;
+    }
+    return out;
+}