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

package/shared/errors.d.ts

@@ -0,0 +1,31 @@
+/** A redirect, denial or HTTP failure ending the guard/loader chain. */
+export declare class HttpError extends Error {
+    readonly status: number;
+    /** Redirect target for 3xx. */
+    readonly location: string | undefined;
+    /** Safe to show to users (4xx messages); 5xx details stay server-side. */
+    readonly expose: boolean;
+    constructor(status: number, message: string, location?: string);
+}
+/** Options of `redirect()`. */
+export interface RedirectOptions {
+    status?: 301 | 302 | 303 | 307 | 308;
+    /** Allow an absolute `http(s):` URL on another origin (payment providers, SSO). */
+    external?: boolean;
+}
+type RedirectStatus = NonNullable<RedirectOptions["status"]>;
+/**
+ * Redirect (default 302 Found, 303 See Other from actions; 307/308 keep the method). Same-origin
+ * only: relative targets, or absolute URLs on the request's origin; `{ external: true }` allows
+ * other origins. Protocol-relative (`//x`), backslash and control-character targets throw.
+ */
+export declare function redirect(location: string, status?: RedirectStatus | RedirectOptions, options?: RedirectOptions): HttpError;
+/** Refuse access (default 403). */
+export declare function deny(status?: 401 | 403, message?: string): HttpError;
+/** The resource does not exist; renders the nearest `_404`. */
+export declare function notFound(message?: string): HttpError;
+/** Fail with an explicit status; renders the nearest `_error`. */
+export declare function error(status: number, message: string): HttpError;
+/** Whether a value is an `HttpError` thrown by `error()` / `notFound()`. */
+export declare const isHttpError: (value: unknown) => value is HttpError;
+export {};

package/shared/errors.js

@@ -0,0 +1,51 @@
+// Control-flow results for guards, loaders and actions: thrown or returned, never rendered as data.
+import { unsafeTarget } from "./redirect.js";
+/** A redirect, denial or HTTP failure ending the guard/loader chain. */
+export class HttpError extends Error {
+    constructor(status, message, location) {
+        super(message);
+        this.name = "HttpError";
+        this.status = status;
+        this.location = location;
+        this.expose = status < 500;
+    }
+}
+/**
+ * Redirect (default 302 Found, 303 See Other from actions; 307/308 keep the method). Same-origin
+ * only: relative targets, or absolute URLs on the request's origin; `{ external: true }` allows
+ * other origins. Protocol-relative (`//x`), backslash and control-character targets throw.
+ */
+export function redirect(location, status, options) {
+    const opts = typeof status === "object" ? status : options;
+    const code = typeof status === "number" ? status : opts?.status;
+    const external = opts?.external === true;
+    const unsafe = unsafeTarget(location);
+    if (unsafe)
+        throw new Error(`redirect(): unsafe target ${JSON.stringify(location)} (${unsafe})`);
+    if (external && !/^https?:\/\//i.test(location))
+        throw new Error(`redirect(): external target must be an absolute http(s) URL, got ${JSON.stringify(location)}`);
+    const error = new HttpError(code ?? 302, "Redirect", location);
+    // Actions answer a defaulted redirect with 303 (POST → GET); an explicit status is kept.
+    if (code === undefined)
+        Object.defineProperty(error, "defaultStatus", { value: true });
+    // The handler checks absolute targets against the request origin unless external.
+    if (external)
+        Object.defineProperty(error, "external", { value: true });
+    return error;
+}
+/** Refuse access (default 403). */
+export function deny(status = 403, message = status === 401 ? "Unauthorized" : "Forbidden") {
+    return new HttpError(status, message);
+}
+/** The resource does not exist; renders the nearest `_404`. */
+export function notFound(message = "Not found") {
+    return new HttpError(404, message);
+}
+/** Fail with an explicit status; renders the nearest `_error`. */
+export function error(status, message) {
+    if (!Number.isInteger(status) || status < 400 || status > 599)
+        throw new RangeError("error() status must be 4xx or 5xx");
+    return new HttpError(status, message);
+}
+/** Whether a value is an `HttpError` thrown by `error()` / `notFound()`. */
+export const isHttpError = (value) => value instanceof HttpError;

package/shared/head.d.ts

@@ -0,0 +1,57 @@
+import type { Head, HeadLink, HeadMeta, HeadScript, InlineScript } from "./data.js";
+/** One head contribution: `level` −1 document defaults, layouts 0…n−1, page n; `phase` 0 route export, 1 components. */
+export interface RankedHead {
+    readonly level: number;
+    readonly phase: 0 | 1;
+    readonly seq: number;
+    readonly head: Head;
+}
+/** Brand static inline script code (kit `?script` imports, `unsafeInlineScript`). */
+export declare function inlineScript(code: string): InlineScript;
+export declare const isInlineScript: (value: unknown) => value is InlineScript;
+export declare function metaKey(meta: HeadMeta): string;
+export declare function linkKey(link: HeadLink): string;
+export declare function scriptKey(script: HeadScript): string;
+/**
+ * Merge contributions by rank `(level, phase, seq)`, later winning per key. The title template
+ * applies once to the winning title (the output's `title` is final; `titleTemplate` is kept).
+ */
+export declare function rankMerge(entries: readonly RankedHead[]): Head | undefined;
+export interface HeadTagOptions {
+    /** Stylesheet URLs, linked before the head's own stylesheets (capo position 7). */
+    styles?: readonly string[];
+    /** Entries of `styles` written as an inline `<style>` (URL → CSS, with the nonce) instead of a link, in place. */
+    inlineStyles?: Readonly<Record<string, string>> | undefined;
+    /** CSP nonce for inline and external scripts. */
+    nonce?: string | undefined;
+    /**
+     * Mark managed tags `data-rh` (kit updates them on client navigation); entries in `persistent`
+     * (root layout components, never re-rendered in the browser) get `data-rh="0"` and are kept.
+     */
+    managed?: boolean | HeadManaged | undefined;
+}
+export interface HeadManaged {
+    readonly persistent: ReadonlySet<object>;
+}
+export declare function linkTag(link: HeadLink, mark?: string): string;
+export declare function metaTag(meta: HeadMeta, mark?: string): string;
+export declare const jsonLdTag: (data: object, id?: string, mark?: string) => string;
+export declare const BOOT_LIST_END = ",d=document,";
+/**
+ * Bootstrap for `load` / `idle` / `interaction` scripts: `list` (escaped JSON array) inlined, code
+ * for only the strategies the page uses. Injected scripts are async by default.
+ */
+export declare function _scriptBootstrap(strategies: Iterable<string>, list?: string): string;
+/**
+ * Tags for a merged head in capo.js order: base, title, preconnect, async scripts, blocking scripts,
+ * stylesheets (`styles` first), preloads, deferred scripts (+ bootstrap), prefetch, meta / SEO links,
+ * JSON-LD. Charset, viewport and the CSP meta belong to the shell.
+ */
+export declare function headTags(head: Head | undefined, options?: HeadTagOptions): string;
+/** `<html>` attributes (leading space) for shells: the head's `html` over request defaults (i18n `locale`/`dir`). */
+export declare function htmlAttributes(head: Head | undefined, defaults?: {
+    lang?: string | undefined;
+    dir?: string | undefined;
+}): string;
+/** `<body>` attributes (leading space). */
+export declare const bodyAttributes: (head: Head | undefined) => string;

package/shared/head.js

@@ -0,0 +1,242 @@
+// Head merging (rank + dedupe keys) and serialization (capo.js order), shared by server and kit.
+import { escapeJSON } from "@rivetjs/runtime/resume-format";
+import { escapeAttribute, escapeText } from "@rivetjs/runtime/escape";
+const inline = new WeakSet();
+/** Brand static inline script code (kit `?script` imports, `unsafeInlineScript`). */
+export function inlineScript(code) {
+    const script = Object.freeze({ code });
+    inline.add(script);
+    return script;
+}
+export const isInlineScript = (value) => typeof value === "object" && value !== null && inline.has(value);
+export function metaKey(meta) {
+    if (meta.key !== undefined)
+        return "k:" + meta.key;
+    const base = meta.name !== undefined
+        ? "n:" + meta.name
+        : meta.property !== undefined
+            ? "p:" + meta.property
+            : meta.httpEquiv !== undefined
+                ? "h:" + meta.httpEquiv.toLowerCase()
+                : "i:" + meta.itemprop;
+    return meta.media !== undefined ? base + "|" + meta.media : base;
+}
+export function linkKey(link) {
+    if (link.key !== undefined)
+        return "k:" + link.key;
+    const rel = link.rel.toLowerCase();
+    if (rel === "canonical")
+        return "canonical";
+    // hreflang alternates may share an href (`en` and `x-default`); feeds differ by href.
+    if (rel === "alternate")
+        return link.hreflang !== undefined ? `alternate ${link.hreflang} ${link.type ?? ""}` : `alternate ${link.type ?? ""} ${link.href}`;
+    if (rel === "icon" || rel === "apple-touch-icon" || rel === "mask-icon")
+        return `${rel} ${link.sizes ?? ""} ${link.media ?? ""}`;
+    return `${rel} ${link.href || link.imagesrcset || ""} ${link.media ?? ""}`;
+}
+let jsonLdSeq = 0;
+export function scriptKey(script) {
+    if (script.key !== undefined)
+        return "k:" + script.key;
+    if ("src" in script)
+        return "s:" + (script.id ?? script.src);
+    if ("inline" in script)
+        return "i:" + (script.id ?? script.inline.code);
+    // JSON-LD without an id is never deduplicated (several blocks are fine).
+    return script.id !== undefined ? "j:" + script.id : "j#" + jsonLdSeq++;
+}
+/**
+ * Merge contributions by rank `(level, phase, seq)`, later winning per key. The title template
+ * applies once to the winning title (the output's `title` is final; `titleTemplate` is kept).
+ */
+export function rankMerge(entries) {
+    if (!entries.length)
+        return undefined;
+    const sorted = [...entries].sort((a, b) => a.level - b.level || a.phase - b.phase || a.seq - b.seq);
+    let title, template, base;
+    let html, body;
+    const meta = new Map(), links = new Map(), scripts = new Map(), styles = new Map();
+    for (const { head } of sorted) {
+        if (head.title !== undefined)
+            title = head.title;
+        if (head.titleTemplate !== undefined)
+            template = head.titleTemplate;
+        if (head.base)
+            base = head.base;
+        if (head.html)
+            html = { ...html, ...head.html };
+        if (head.body)
+            body = { ...body, ...head.body };
+        for (const entry of head.meta ?? [])
+            meta.set(metaKey(entry), entry);
+        for (const entry of head.links ?? [])
+            links.set(linkKey(entry), entry);
+        for (const entry of head.scripts ?? [])
+            scripts.set(scriptKey(entry), entry);
+        for (const entry of head.styles ?? [])
+            styles.set(entry.key ?? entry.css, entry);
+    }
+    if (title !== undefined && template !== undefined)
+        title = template.replace("%s", title);
+    // The template stays alongside the final title: client head updates template component titles.
+    return {
+        ...(title !== undefined ? { title } : {}),
+        ...(template !== undefined ? { titleTemplate: template } : {}),
+        ...(html ? { html } : {}),
+        ...(body ? { body } : {}),
+        ...(base ? { base } : {}),
+        ...(meta.size ? { meta: [...meta.values()] } : {}),
+        ...(links.size ? { links: [...links.values()] } : {}),
+        ...(scripts.size ? { scripts: [...scripts.values()] } : {}),
+        ...(styles.size ? { styles: [...styles.values()] } : {}),
+    };
+}
+const attr = (name, value) => value === undefined || value === false ? "" : value === true ? " " + name : ` ${name}="${escapeAttribute(value)}"`;
+const LINK_ATTRIBUTES = [
+    "rel",
+    "href",
+    "type",
+    "hreflang",
+    "media",
+    "sizes",
+    "as",
+    "crossorigin",
+    "imagesrcset",
+    "imagesizes",
+    "fetchpriority",
+    "title",
+    "color",
+    "integrity",
+    "referrerpolicy",
+];
+export function linkTag(link, mark = "") {
+    let tag = "<link";
+    for (const name of LINK_ATTRIBUTES)
+        tag += attr(name, link[name]);
+    return tag + mark + ">";
+}
+export function metaTag(meta, mark = "") {
+    const key = meta.name !== undefined
+        ? attr("name", meta.name)
+        : meta.property !== undefined
+            ? attr("property", meta.property)
+            : meta.httpEquiv !== undefined
+                ? attr("http-equiv", meta.httpEquiv)
+                : meta.itemprop !== undefined
+                    ? attr("itemprop", meta.itemprop)
+                    : "";
+    return key ? `<meta${key} content="${escapeAttribute(meta.content)}"${attr("media", meta.media)}${mark}>` : "";
+}
+export const jsonLdTag = (data, id, mark = "") => `<script type="application/ld+json"${attr("id", id)}${mark}>${escapeJSON(JSON.stringify(data))}</script>`;
+const deferred = (s) => s.strategy === "load" || s.strategy === "idle" || s.strategy === "interaction";
+// Script bootstrap (minified by hand), one inline script per page: `{let l=<list>,…}` (block scope).
+// It runs while the head parses, before `load`. List entries: `{ u: src, k, …script properties }`,
+// `k` = index in STRATEGY_CODES. `l` doubles as the policy's allowlist.
+const STRATEGY_CODES = ["load", "idle", "interaction"];
+export const BOOT_LIST_END = ",d=document,";
+const BOOT_CORE = BOOT_LIST_END +
+    'E=addEventListener,p,r=k=>l.map(({u,k:s,...o})=>s==k&&d.head.append(Object.assign(d.createElement("script"),o,{src:p?.createScriptURL(u)??u})));' +
+    // The page's one `rivet-script` policy (unlisted URLs become ""; JSON-only scripts for kit JSON-LD), shared with kit's head manager.
+    'try{d.$rs={p:p=trustedTypes.createPolicy("rivet-script",{createScriptURL:u=>l.some(s=>s.u==u)?u:"",createScript:c=>JSON.parse(c)&&c}),l}}catch{}';
+// Window-level scroll / wheel listeners are passive already; listeners stay attached as no-ops. Touch
+// interaction arrives as pointerdown.
+const BOOT_IDLE = 'let t,n,g=()=>n||(clearTimeout(t),t=setTimeout(()=>{n=1;(self.requestIdleCallback||setTimeout)(()=>r(1),{timeout:4e3})},150));E("scroll",g);g();';
+const BOOT_INTERACTION = 'let i,x=()=>i||(i=r(2));"pointerdown keydown wheel".split(" ").map(e=>E(e,x,!0));';
+/**
+ * Bootstrap for `load` / `idle` / `interaction` scripts: `list` (escaped JSON array) inlined, code
+ * for only the strategies the page uses. Injected scripts are async by default.
+ */
+export function _scriptBootstrap(strategies, list = "[]") {
+    const used = new Set(strategies);
+    const onload = (used.has("load") ? "r(0);" : "") + (used.has("idle") ? BOOT_IDLE : "");
+    return "{let l=" + list + BOOT_CORE + (onload ? `E("load",()=>{${onload}});` : "") + (used.has("interaction") ? BOOT_INTERACTION : "") + "}";
+}
+function scriptTag(script, nonce, mark) {
+    const module = script.type === "module";
+    const strategy = script.strategy ?? "defer";
+    const timing = strategy === "eager" ? " async" : strategy === "defer" && !module ? " defer" : "";
+    return `<script${module ? ' type="module"' : ""}${timing} src="${escapeAttribute(script.src)}"${attr("id", script.id)}${attr("integrity", script.integrity)}${attr("crossorigin", script.crossorigin)}${attr("referrerpolicy", script.referrerpolicy)}${nonce}${mark}></script>`;
+}
+/** Inline `<style>` (unmanaged: never `data-rh`). CSS never contains a closing tag. */
+const styleTag = (style, nonce) => `<style${attr("media", style.media)}${nonce}>${style.css.replace(/<\/(style)/gi, "<\\/$1")}</style>`;
+/** Inline script: its JSON data block (if any) right before it. Code never contains a closing tag. */
+function inlineTag(script, nonce) {
+    if (!isInlineScript(script.inline))
+        throw new TypeError("head script `inline` must be an InlineScript (`?script` import or unsafeInlineScript)");
+    const data = script.data !== undefined ? `<script type="application/json">${escapeJSON(JSON.stringify(script.data))}</script>` : "";
+    return `${data}<script${attr("id", script.id)}${nonce}>${script.inline.code.replace(/<\/(script)/gi, "<\\/$1")}</script>`;
+}
+/**
+ * Tags for a merged head in capo.js order: base, title, preconnect, async scripts, blocking scripts,
+ * stylesheets (`styles` first), preloads, deferred scripts (+ bootstrap), prefetch, meta / SEO links,
+ * JSON-LD. Charset, viewport and the CSP meta belong to the shell.
+ */
+export function headTags(head, options = {}) {
+    const managed = options.managed;
+    const markOf = (entry) => (!managed ? "" : typeof managed === "object" && managed.persistent.has(entry) ? ' data-rh="0"' : ' data-rh=""');
+    const nonce = options.nonce !== undefined ? ` nonce="${options.nonce.replace(/[^\w+/=-]/g, "")}"` : "";
+    // One string per capo.js group (index = order), appended in place.
+    const groups = ["", "", "", "", "", "", "", "", "", "", "", ""];
+    const sheets = options.inlineStyles;
+    for (const href of options.styles ?? []) {
+        const css = sheets && Object.hasOwn(sheets, href) ? sheets[href] : undefined;
+        groups[5] += css !== undefined ? styleTag({ css }, nonce) : `<link rel="stylesheet" href="${escapeAttribute(href)}">`;
+    }
+    // Inline styles after the stylesheets (same group): component rules (motion entrances) win ties over sheet rules.
+    const inlineStyles = head?.styles?.map((style) => styleTag(style, nonce)).join("") ?? "";
+    if (head?.base)
+        groups[0] += `<base href="${escapeAttribute(head.base.href)}"${attr("target", head.base.target)}>`;
+    if (head?.title !== undefined)
+        groups[1] += `<title>${escapeText(head.title)}</title>`;
+    for (const link of head?.links ?? []) {
+        const rel = link.rel.toLowerCase();
+        const group = rel === "preconnect"
+            ? 2
+            : rel === "stylesheet"
+                ? 5
+                : rel === "preload" || rel === "modulepreload"
+                    ? 6
+                    : rel === "prefetch" || rel === "dns-prefetch" || rel === "prerender"
+                        ? 8
+                        : 10;
+        groups[group] += linkTag(link, markOf(link));
+    }
+    groups[5] += inlineStyles;
+    const later = [];
+    for (const script of head?.scripts ?? []) {
+        if ("jsonLd" in script)
+            groups[11] += jsonLdTag(script.jsonLd, script.id, markOf(script));
+        else if ("inline" in script) {
+            const strategy = script.strategy ?? "defer";
+            groups[strategy === "eager" ? 3 : strategy === "blocking" ? 4 : 7] += inlineTag(script, nonce);
+        }
+        else if (deferred(script))
+            later.push(script);
+        else {
+            const strategy = script.strategy ?? "defer";
+            groups[strategy === "eager" ? 3 : strategy === "blocking" ? 4 : 7] += scriptTag(script, nonce, markOf(script));
+        }
+    }
+    if (later.length) {
+        const list = later.map((s) => ({
+            u: s.src,
+            k: STRATEGY_CODES.indexOf(s.strategy),
+            ...(s.type === "module" ? { type: "module" } : {}),
+            ...(s.id ? { id: s.id } : {}),
+            ...(s.integrity ? { integrity: s.integrity } : {}),
+            ...(s.crossorigin ? { crossOrigin: s.crossorigin } : {}),
+            ...(s.referrerpolicy ? { referrerPolicy: s.referrerpolicy } : {}),
+        }));
+        groups[7] += `<script id="rivet-scripts"${nonce}>${_scriptBootstrap(later.map((s) => s.strategy), escapeJSON(JSON.stringify(list)))}</script>`;
+    }
+    for (const meta of head?.meta ?? [])
+        groups[9] += metaTag(meta, markOf(meta));
+    return groups.join("");
+}
+/** `<html>` attributes (leading space) for shells: the head's `html` over request defaults (i18n `locale`/`dir`). */
+export function htmlAttributes(head, defaults = {}) {
+    const html = { ...defaults, ...head?.html };
+    return attr("lang", html.lang) + attr("dir", html.dir) + attr("class", head?.html?.class);
+}
+/** `<body>` attributes (leading space). */
+export const bodyAttributes = (head) => attr("class", head?.body?.class);

package/shared/nonce.d.ts

@@ -0,0 +1,2 @@
+/** Fresh 128-bit CSP nonce (base64) for one response's inline scripts. */
+export declare function nonce(): string;

package/shared/nonce.js

@@ -0,0 +1,23 @@
+// CSP nonces: the one generator behind the node and fetch adapters (Web Crypto, every runtime).
+// 16 fresh CSPRNG bytes per nonce, cut from a pooled 4 KiB `getRandomValues` fill (every byte used once; the pool
+// refills when it runs out) and base64-encoded by table: one `getRandomValues` + `btoa(String.fromCharCode(…))`
+// per request cost ~0.8 µs, this ~0.1 µs.
+const POOL = 4096;
+const pool = new Uint8Array(POOL);
+let at = POOL;
+const DIGITS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+/** Fresh 128-bit CSP nonce (base64) for one response's inline scripts. */
+export function nonce() {
+    if (at + 16 > POOL) {
+        crypto.getRandomValues(pool);
+        at = 0;
+    }
+    let out = "";
+    // 5 groups of 3 bytes → 20 digits, then the 16th byte → 2 digits + "==".
+    for (let end = at + 15; at < end; at += 3) {
+        const n = (pool[at] << 16) | (pool[at + 1] << 8) | pool[at + 2];
+        out += DIGITS[n >> 18] + DIGITS[(n >> 12) & 63] + DIGITS[(n >> 6) & 63] + DIGITS[n & 63];
+    }
+    const last = pool[at++];
+    return out + DIGITS[last >> 2] + DIGITS[(last & 3) << 4] + "==";
+}

package/shared/prefetch-fallback.min.d.ts

@@ -0,0 +1 @@
+export declare const FALLBACK = "(function(m,g){const a=document;if(HTMLScriptElement.supports?.(\"speculationrules\"))return;const r=new Set,v=a.createElement(\"link\").relList.supports?.(\"prefetch\"),u=\"rivet:prefetch\",f={priority:\"low\"},y={capture:!0,passive:!0},s=(t,e)=>a.addEventListener(t,e,y);let i,c=null,n=2;try{n=sessionStorage.getItem(u)||2}catch{}const h=t=>{const e=t.target?.closest?.(m);return e&&g?.test(e.pathname)&&!e.matches(\"[data-rivet-reload],[rel~=external]\")?null:e},p=t=>{const e=navigator.connection;if(!t||e?.saveData||/2g/.test(e?.effectiveType))return;const o=t.href.split(\"#\")[0];if(t.origin!==location.origin||o===location.href.split(\"#\")[0]||r.has(o)||n<1)return;r.size>99&&r.delete(r.values().next().value),r.add(o);const d=()=>v?a.head.append(Object.assign(a.createElement(\"link\"),{rel:\"prefetch\",as:\"document\",href:o})):fetch(o,f).catch(()=>{});if(n==\"1\")return void d();n=\"\",fetch(o,{...f,cache:\"no-store\"}).then(l=>{l.body?.cancel();const T=l.headers.get(\"cache-control\")+\",\"+l.headers.get(\"pragma\");n=/no-(store|cache)|^(?!.*stale-while).*max-age=0\\b/.test(T)?\"0\":\"1\";try{sessionStorage.setItem(u,n)}catch{}n==\"1\"&&d()},()=>{n=2,r.delete(o)})};s(\"pointerover\",t=>{const e=h(t)||null;e!==c&&(clearTimeout(i),c=e,e&&(i=setTimeout(p,65,e)))}),s(\"pointerout\",t=>{c&&!c.contains(t.relatedTarget)&&(clearTimeout(i),c=null)});for(const t of[\"focusin\",\"touchstart\",\"pointerdown\"])s(t,e=>p(h(e)))})";

package/shared/prefetch-fallback.min.js

@@ -0,0 +1,2 @@
+// Generated by build/prefetch-script.ts from client/prefetch-fallback.ts. Do not edit.
+export const FALLBACK = "(function(m,g){const a=document;if(HTMLScriptElement.supports?.(\"speculationrules\"))return;const r=new Set,v=a.createElement(\"link\").relList.supports?.(\"prefetch\"),u=\"rivet:prefetch\",f={priority:\"low\"},y={capture:!0,passive:!0},s=(t,e)=>a.addEventListener(t,e,y);let i,c=null,n=2;try{n=sessionStorage.getItem(u)||2}catch{}const h=t=>{const e=t.target?.closest?.(m);return e&&g?.test(e.pathname)&&!e.matches(\"[data-rivet-reload],[rel~=external]\")?null:e},p=t=>{const e=navigator.connection;if(!t||e?.saveData||/2g/.test(e?.effectiveType))return;const o=t.href.split(\"#\")[0];if(t.origin!==location.origin||o===location.href.split(\"#\")[0]||r.has(o)||n<1)return;r.size>99&&r.delete(r.values().next().value),r.add(o);const d=()=>v?a.head.append(Object.assign(a.createElement(\"link\"),{rel:\"prefetch\",as:\"document\",href:o})):fetch(o,f).catch(()=>{});if(n==\"1\")return void d();n=\"\",fetch(o,{...f,cache:\"no-store\"}).then(l=>{l.body?.cancel();const T=l.headers.get(\"cache-control\")+\",\"+l.headers.get(\"pragma\");n=/no-(store|cache)|^(?!.*stale-while).*max-age=0\\b/.test(T)?\"0\":\"1\";try{sessionStorage.setItem(u,n)}catch{}n==\"1\"&&d()},()=>{n=2,r.delete(o)})};s(\"pointerover\",t=>{const e=h(t)||null;e!==c&&(clearTimeout(i),c=e,e&&(i=setTimeout(p,65,e)))}),s(\"pointerout\",t=>{c&&!c.contains(t.relatedTarget)&&(clearTimeout(i),c=null)});for(const t of[\"focusin\",\"touchstart\",\"pointerdown\"])s(t,e=>p(h(e)))})";

package/shared/prefetch.d.ts

@@ -0,0 +1,54 @@
+import type { DocumentShell } from "../server/render.js";
+/** What a link loads ahead of a document navigation: the HTML (`document`) or the whole page in the background (`prerender`). */
+export type DocumentPrefetch = "document" | "prerender";
+/**
+ * When Chromium acts on the rules (Speculation Rules `eagerness`): `conservative` on pointer / touch
+ * down, `moderate` also after the pointer rests on a link ~200 ms, `eager` sooner still (on desktop:
+ * a short hover; Chromium decides the exact heuristics).
+ */
+export type PrefetchEagerness = "conservative" | "moderate" | "eager";
+/** Document prefetch options (Speculation Rules with a fallback). */
+export interface DocumentPrefetchOptions {
+    /**
+     * App default (`rivetRouter({ prefetch })`): links without their own `data-rivet-prefetch` choice
+     * (plain `<a>` too) prefetch this way. Absent: only links marked `document` / `prerender`.
+     */
+    readonly default?: DocumentPrefetch;
+    /**
+     * The client router intercepts same-app links (every server / static app with more than one
+     * route): those navigations never load a document (the router prefetches their data + page chunk
+     * on intent itself), so only links that load documents take part: `data-rivet-reload` /
+     * `rel=external` links, and — with `routes` — links whose path no route matches.
+     */
+    readonly routed?: boolean;
+    /**
+     * RegExp source over `URL.pathname.slice(1)` matching every path a route of the app (page or
+     * endpoint) matches (generated: `routePathRegExp` in `build/codegen.ts`). Links to other paths load
+     * documents and take part; endpoint paths never do (only when marked `reload`). Implies `routed`.
+     */
+    readonly routes?: string;
+    /** Speculation Rules eagerness (`rivetRouter({ prefetchEagerness })`); default `moderate`. The fallback keeps its own intent timing. */
+    readonly eagerness?: PrefetchEagerness;
+}
+/**
+ * CSS selector of the links prefetched with `kind` (`"all"`: either kind). Routed apps: only
+ * `data-rivet-reload` / `rel=external` links — with `routes`, path-based detection is not a selector
+ * (see `speculationRules`), so the selector leaves it out.
+ */
+export declare function prefetchSelector(kind: DocumentPrefetch | "all", options?: DocumentPrefetchOptions): string;
+/**
+ * Speculation Rules (Chromium) for a page at `url`: document rules over the prefetch selectors,
+ * same origin only (`/*`), not the page itself (either trailing-slash form), `moderate` eagerness by default (pointer resting ~200 ms on a
+ * link, or pointer down). The browser applies them to links added later too (no registry needed).
+ */
+export declare function speculationRules(url: URL, options?: DocumentPrefetchOptions): string;
+/** Head tags: the rules (Chromium) and the inline fallback (`<link rel=prefetch>` / `fetch` on intent elsewhere). */
+export declare function prefetchTags(url: URL, nonce: string | undefined, options?: DocumentPrefetchOptions): string;
+/** Wrap a document shell: every page gets the prefetch tags right before `</head>` (generated `entry.server.tsx`). */
+export declare function documentPrefetch(shell: DocumentShell, options?: DocumentPrefetchOptions): DocumentShell;
+/**
+ * Run `fn` now, or — on a page the browser is prerendering (`<Link prefetch="prerender">`) — once the
+ * user actually navigates to it (`prerenderingchange`). For page-view analytics and other "the user
+ * saw this page" side effects. No-op outside a browser.
+ */
+export declare function whenActivated(fn: () => void): void;

package/shared/prefetch.js

@@ -0,0 +1,74 @@
+import { FALLBACK } from "./prefetch-fallback.min.js";
+/** Links the browser would navigate in this tab (no download, no other target). */
+const SAME_TAB = ":not([download],[target]:not([target=_self]))";
+/** Links of a client-routed app that load a document whatever their path (the router never intercepts them). */
+const RELOAD = "[data-rivet-reload],[rel~=external]";
+/**
+ * CSS selector of the links prefetched with `kind` (`"all"`: either kind). Routed apps: only
+ * `data-rivet-reload` / `rel=external` links — with `routes`, path-based detection is not a selector
+ * (see `speculationRules`), so the selector leaves it out.
+ */
+export function prefetchSelector(kind, options = {}) {
+    const marked = kind === "all" ? "a[data-rivet-prefetch=document],a[data-rivet-prefetch=prerender]" : `a[data-rivet-prefetch=${kind}]`;
+    const any = options.default && (kind === "all" || options.default === kind) ? ",a:not([data-rivet-prefetch])" : "";
+    return `:is(${marked}${any})[href]${options.routed && options.routes === undefined ? `:is(${RELOAD})` : ""}${SAME_TAB}`;
+}
+/** URLPattern-escape a path (`:` `*` `?` `+` `(` `)` `{` `}` `\` are syntax). */
+const pattern = (path) => path.replace(/[\\:*?+(){}]/g, "\\$&");
+/** Script text is JSON: `<` escaped so no `</script` can close it. */
+const json = (value) => JSON.stringify(value).replace(/</g, "\\u003c");
+/**
+ * Speculation Rules (Chromium) for a page at `url`: document rules over the prefetch selectors,
+ * same origin only (`/*`), not the page itself (either trailing-slash form), `moderate` eagerness by default (pointer resting ~200 ms on a
+ * link, or pointer down). The browser applies them to links added later too (no registry needed).
+ */
+export function speculationRules(url, options = {}) {
+    // The page's own path with or without its trailing slash (`/a` and `/a/` are the same page by default).
+    const path = url.pathname.replace(/\/+$/, "");
+    const self = path ? pattern(path) + "{/}?" : "/";
+    // Routed app with its route paths: a reload link, or a path no route matches (URLPattern regexp group).
+    const routes = options.routes;
+    const documents = routes === undefined ? [] : [{ or: [{ selector_matches: RELOAD }, { not: { href_matches: routes ? "/(" + routes + ")" : "/" } }] }];
+    const rule = (kind) => [
+        {
+            source: "document",
+            where: { and: [{ href_matches: "/*" }, { not: { href_matches: self } }, { selector_matches: prefetchSelector(kind, options) }, ...documents] },
+            eagerness: options.eagerness ?? "moderate",
+        },
+    ];
+    return json({ prefetch: rule("document"), prerender: rule("prerender") });
+}
+/** Head tags: the rules (Chromium) and the inline fallback (`<link rel=prefetch>` / `fetch` on intent elsewhere). */
+export function prefetchTags(url, nonce, options = {}) {
+    const attr = nonce !== undefined ? ` nonce="${nonce.replace(/[^\w+/=-]/g, "")}"` : "";
+    const selector = prefetchSelector("all", options);
+    // Routed app with its route paths: the fallback applies the same path rule (a RegExp literal: the source
+    // escapes every `/`, and `<` / line terminators are percent-encoded in it).
+    const routes = options.routes === undefined ? "" : ",/^\\/(?:" + options.routes + ")$/";
+    return (`<script type="speculationrules"${attr}>${speculationRules(url, options)}</script>` + `<script${attr}>${FALLBACK}(${json(selector)}${routes})</script>`);
+}
+/** Wrap a document shell: every page gets the prefetch tags right before `</head>` (generated `entry.server.tsx`). */
+export function documentPrefetch(shell, options = {}) {
+    // Written into the page as a RegExp literal: no `<` (`</script`), no line terminator, no unescaped `/`.
+    if (options.routes !== undefined && /[<\n\r\u2028\u2029]|(^|[^\\])(\\\\)*\//.test(options.routes))
+        throw new TypeError("documentPrefetch: invalid routes source");
+    return (input) => {
+        const parts = shell(input);
+        const tags = prefetchTags(input.url, input.nonce, options);
+        const at = parts.start.lastIndexOf("</head>");
+        return at < 0 ? { start: parts.start + tags, end: parts.end } : { start: parts.start.slice(0, at) + tags + parts.start.slice(at), end: parts.end };
+    };
+}
+/**
+ * Run `fn` now, or — on a page the browser is prerendering (`<Link prefetch="prerender">`) — once the
+ * user actually navigates to it (`prerenderingchange`). For page-view analytics and other "the user
+ * saw this page" side effects. No-op outside a browser.
+ */
+export function whenActivated(fn) {
+    if (typeof document === "undefined")
+        return;
+    if (document.prerendering)
+        document.addEventListener("prerenderingchange", () => fn(), { once: true });
+    else
+        fn();
+}

package/shared/redirect.d.ts

@@ -0,0 +1,6 @@
+/** Absolute URL (has a scheme). */
+export declare const ABSOLUTE: RegExp;
+/** Why `location` cannot be a same-origin redirect target as written, or undefined when it can. */
+export declare function unsafeTarget(location: string): string | undefined;
+/** `target` when it is a same-origin path (`/a/b?c#d`), else `fallback`. Never an absolute or protocol-relative URL. */
+export declare function safeRedirect(target: unknown, fallback?: string): string;

package/shared/redirect.js

@@ -0,0 +1,25 @@
+// Open-redirect guards: `redirect()` targets and user-supplied targets (`?redirectTo=`).
+/** Control characters, backslashes or a leading `//` can make browsers resolve a path to another origin. */
+const UNSAFE = /[\u0000-\u001f\u007f\\]|^\s|^\/\//;
+/** Absolute URL (has a scheme). */
+export const ABSOLUTE = /^[a-z][a-z\d+.-]*:/i;
+/** Why `location` cannot be a same-origin redirect target as written, or undefined when it can. */
+export function unsafeTarget(location) {
+    if (UNSAFE.test(location))
+        return "protocol-relative, backslash or control characters";
+    return undefined;
+}
+/** `target` when it is a same-origin path (`/a/b?c#d`), else `fallback`. Never an absolute or protocol-relative URL. */
+export function safeRedirect(target, fallback = "/") {
+    if (typeof target !== "string" || !target.startsWith("/") || unsafeTarget(target))
+        return fallback;
+    const base = "http://rivet.invalid";
+    let url;
+    try {
+        url = new URL(target, base);
+    }
+    catch {
+        return fallback;
+    }
+    return url.origin === base ? url.pathname + url.search + url.hash : fallback;
+}