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

package/server/app.js

@@ -0,0 +1,335 @@
+import { headTags, rankMerge } from "../shared/head.js";
+import { nonceCSP } from "../shared/csp.js";
+import { inlineStylesFor } from "./inline-styles.js";
+import { escapeJSON } from "@rivetjs/runtime/resume-format";
+import { createHandler, _digest, encodeData } from "./handler.js";
+import { renderDocument } from "./render.js";
+import { SHELL_BUILD } from "./shell-build.js";
+// `route-cache.ts` `ROUTE_CACHE` (same registered symbol; that module loads only with rules).
+const ROUTE_CACHE = Symbol.for("rivet.routeCache");
+// `early-hints.ts` `EARLY_HINTS` (same registered symbol; that module loads only with `earlyHints`).
+const EARLY_HINTS = Symbol.for("rivet.earlyHints");
+const RENDER_FAILED = Symbol.for("rivet.renderFailed");
+/** Route export levels: layouts outermost first, then the page (undefined entries skipped). */
+const ranked = (heads, defaults) => [
+    ...(defaults ? [{ level: -1, phase: 0, seq: 0, head: defaults }] : []),
+    ...heads.flatMap((head, level) => (head ? [{ level, phase: 0, seq: 0, head }] : [])),
+];
+/**
+ * Merge heads outer → inner: inner wins per key (title; meta by name/property/http-equiv/itemprop
+ * + media; one canonical; alternates by hreflang; other links by rel + href; scripts by id/src).
+ */
+export function mergeHeads(heads) {
+    return rankMerge(ranked(heads));
+}
+/** Component head collector of one request: entries until the hold releases, then late entries render in place. */
+function createSink(nonce, late) {
+    let seq = 0, closed = false;
+    const entries = [];
+    return {
+        nonce,
+        entries,
+        close: () => void (closed = true),
+        push(level, head, component) {
+            if (!closed) {
+                entries.push({ level, phase: 1, seq: seq++, head });
+                return undefined;
+            }
+            // After the shell: only body-valid tags (links, scripts, styles) still apply, where they render.
+            if (head.title !== undefined || head.titleTemplate !== undefined || head.meta?.length || head.html || head.body || head.base)
+                late(`${component ?? "A head component"} rendered after the shell (inside a streamed Async boundary): title/meta/html changes are ignored there`);
+            return (headTags({ ...(head.links ? { links: head.links } : {}), ...(head.scripts ? { scripts: head.scripts } : {}), ...(head.styles ? { styles: head.styles } : {}) }, { nonce }) || undefined);
+        },
+    };
+}
+/** Create the app's request handler. */
+export function createApp(config) {
+    const { entry, manifest, dev = false, styles = [], routeStyles } = config;
+    const inlineFor = config.inlineStyles ? inlineStylesFor(config.inlineStyles) : undefined;
+    const option = config.csp ?? nonceCSP;
+    let csp = typeof option === "object" ? (nonce) => nonceCSP(nonce, option) : option;
+    // `directives`: the merge module loads at startup (pay-per-use, dynamic import) and checks them once —
+    // a mistake rejects at startup (unhandled: the process fails like a synchronous throw would); requests
+    // arriving before it settles wait for it, later ones take the synchronous path.
+    let directives = typeof option === "object" && option.directives
+        ? import("./strict-csp.js").then(({ strictCSP }) => {
+            strictCSP("", option);
+            csp = (nonce) => strictCSP(nonce, option);
+            directives = null;
+        })
+        : null;
+    // Route export contributions behind each merged head (rank merge with component entries).
+    const levels = new WeakMap();
+    // Early hints: the per-route Link values live in `early-hints.ts`, loaded at startup only with `earlyHints`.
+    const hintOption = dev ? undefined : config.earlyHints;
+    let hinter;
+    let hintLoading = hintOption
+        ? import("./early-hints.js").then(({ createHinter }) => {
+            hinter = createHinter(hintOption, { styles, routeStyles, inlineFor, base: entry.base ?? "", runtime: manifest?.runtime });
+            hintLoading = null;
+        })
+        : null;
+    const warned = new Set();
+    const document = config.document ?? entry.document;
+    if (!document)
+        throw new TypeError("createApp: no document shell (pass `document` or generate the entry with one)");
+    const moveScript = (to, nonce) => to === undefined ? "" : `<script${scriptAttrs(nonce)}>location.replace(${JSON.stringify(to).replace(/</g, "\\u003c")})</script>`;
+    const scriptAttrs = (nonce) => (nonce !== undefined ? ` nonce="${nonce.replace(/[^\w+/=-]/g, "")}"` : "");
+    // Dev pages: what the data endpoint would answer for this URL, so the client mount needs no request.
+    const devAround = (page, status, nonce, locale, mode) => {
+        const list = typeof config.devScripts === "function" ? config.devScripts(locale) : (config.devScripts ?? []);
+        const scripts = list.map((src) => `<script type="module" src="${src}"${scriptAttrs(nonce)}></script>`).join("");
+        // Resumed dev pages: the dev entry only takes over (client render) on the first hot update.
+        if (mode === "resume")
+            return { start: `<div data-rivet-dev="resume" style="display:contents">`, end: `</div>${scripts}` };
+        const body = page.error
+            ? { error: page.error }
+            : {
+                data: page.data,
+                status,
+                ...(page.head ? { head: page.head } : {}),
+                ...(page.action ? { action: page.action } : {}),
+                ...(page.deps ? { deps: page.deps } : {}),
+            };
+        return {
+            start: `<div data-rivet-dev="" style="display:contents">`,
+            end: `</div><script type="application/json" id="rivet-dev-data">${escapeJSON(encodeData(body))}</script>${scripts}`,
+        };
+    };
+    const respond = (page, status, headers, nonce, request, locals, routeId) => {
+        if (directives || fragments || hintLoading)
+            return Promise.all([directives, fragments, hintLoading]).then(() => respond(page, status, headers, nonce, request, locals, routeId));
+        const extra = routeId === undefined || !routeStyles ? undefined : typeof routeStyles === "function" ? routeStyles(routeId) : routeStyles[routeId];
+        if (extra && "then" in extra)
+            return extra.then((list) => render(page, status, headers, nonce, request, locals, list, routeId));
+        return render(page, status, headers, nonce, request, locals, extra, routeId);
+    };
+    // Failures after the document started (the status is sent): reported with a digest, which the page's failure marker carries.
+    const report = config.onError ?? ((error, _request, info) => console.error("[rivet] digest " + info?.digest + ":", error));
+    const render = (page, status, headers, nonce, request, locals, extra, routeId) => {
+        const pageStyles = extra?.length ? [...styles, ...extra] : styles;
+        const inlineStyles = inlineFor?.(pageStyles);
+        let sink;
+        if (entry.headComponents) {
+            sink = createSink(nonce, (message) => {
+                if (dev)
+                    console.error("[rivet] " + message);
+                // Once per message (component + text: bounded by the app's code), not per URL (unbounded).
+                else if (!warned.has(message))
+                    (warned.add(message), console.warn("[rivet] " + message));
+            });
+            page = { ...page, headSink: sink };
+        }
+        const signal = request.signal;
+        if (hinter && routeId !== undefined) {
+            if (!sink)
+                hinter.learn(routeId, page.head);
+            const links = hinter.links(routeId);
+            if (links.length && !headers.has("link"))
+                headers.set("link", links.join(", "));
+        }
+        if (csp && nonce !== undefined && !headers.has("content-security-policy"))
+            headers.set("content-security-policy", csp(nonce));
+        const i18n = config.i18n;
+        const locale = i18n && typeof locals?.locale === "string" && i18n.locales.includes(locals.locale) ? locals.locale : undefined;
+        const variant = locale ? i18n.locales.indexOf(locale) : 0;
+        const built = (i18n && i18n.manifests?.[locale ?? i18n.locales[0]]) || manifest;
+        const devMode = built || !config.devResume ? undefined : typeof config.devResume.mode === "function" ? config.devResume.mode(locale) : config.devResume.mode;
+        const pageManifest = built || config.devResume?.manifest;
+        // Dev check mode streams nothing: a shell fill's deferred data waits in place there (not an in-order read).
+        if (page.shell && devMode === "check")
+            page.shell.plain = true;
+        const dir = locals?.dir === "rtl" || locals?.dir === "ltr" ? locals.dir : undefined;
+        const exports = page.head ? (levels.get(page.head) ?? ranked([page.head], config.head)) : ranked([], config.head);
+        // Root layout component entries stay in the browser (that layout never re-renders there).
+        const persistent = new Set();
+        const option = config.preload?.background ?? entry.preloadBackground;
+        const background = typeof option === "function" ? option(page.url) : option;
+        const leanOption = config.preload?.lean;
+        const lean = typeof leanOption === "function" ? leanOption(page.url) : leanOption;
+        const ahead = config.preload?.ahead ?? entry.fetchAhead;
+        const run = () => renderDocument(entry.page(page), {
+            head: page.head,
+            nonce,
+            url: page.url,
+            status,
+            styles: pageStyles,
+            ...(inlineStyles ? { inlineStyles } : {}),
+            ...(locale ? { locale } : {}),
+            ...(dir ? { dir } : {}),
+            ...(sink ? { managed: { persistent } } : {}),
+        }, {
+            document,
+            ...(sink
+                ? {
+                    hold: {
+                        head: () => {
+                            sink.close();
+                            for (const { level, head } of sink.entries)
+                                if (level === 0)
+                                    for (const entry of [...(head.meta ?? []), ...(head.links ?? []), ...(head.scripts ?? [])])
+                                        persistent.add(entry);
+                            const merged = rankMerge([...exports, ...sink.entries]);
+                            if (routeId !== undefined)
+                                hinter?.learn(routeId, merged);
+                            return merged;
+                        },
+                    },
+                }
+                : {}),
+            ...(pageManifest ? { manifest: pageManifest } : {}),
+            ...(variant ? { variant } : {}),
+            // Deferred loaders: their boundaries stream out of order (shell first) even when the app set no `stream`.
+            // Shell routes (`routeRules` `shell`) always stream: the stored shell ends where the first boundary would stream.
+            ...(config.stream ? { stream: config.stream } : page.deferred || page.shell ? { stream: {} } : {}),
+            ...(background !== undefined || lean || ahead
+                ? { preload: { ...(background !== undefined ? { background } : {}), ...(lean ? { lean } : {}), ...(ahead ? { ahead } : {}) } }
+                : {}),
+            signal,
+            ...(nonce !== undefined ? { nonce } : {}),
+            onError: (error) => {
+                // Route rules: a page that rendered an error fallback is not stored (`route-cache.ts` `RENDER_FAILED`).
+                request[RENDER_FAILED] = true;
+                const digest = _digest();
+                report(error, request, { digest, phase: "render", ...(routeId !== undefined ? { route: routeId } : {}) });
+                return digest;
+            },
+            ...(config.devScripts && !built ? { around: devAround(page, status, nonce, locale, devMode) } : {}),
+            // Deferred loaders' redirects (status already sent): the browser navigates at the document's end.
+            ...(page.moved ? { epilogue: () => moveScript(page.moved(), nonce) } : {}),
+            ...(devMode === "check" ? { discardState: true } : {}),
+        }, { status, headers });
+        return withCache
+            ? withCache({
+                cache: config.renderCache,
+                ...(variant ? { variant } : {}),
+                ...(nonce !== undefined ? { nonce } : {}),
+                signal,
+                resumable: pageManifest !== undefined,
+            }, run)
+            : run();
+    };
+    // `renderCache`: the scope module (AsyncLocalStorage) loads at startup, pay-per-use like `directives`.
+    let withCache;
+    let fragments = config.renderCache
+        ? import("@rivetjs/runtime/server-cache").then((module) => {
+            withCache = module.withRenderCache;
+            fragments = null;
+        })
+        : null;
+    const app = createHandler({
+        routes: entry.routes,
+        dev,
+        // Every locale's build shares one runtime; any manifest names the built-in decoders' chunk.
+        builtins: () => (manifest ?? (config.i18n?.manifests && Object.values(config.i18n.manifests)[0]) ?? config.devResume?.manifest)?.builtins,
+        ...(config.onError ? { onError: config.onError } : {}),
+        ...(config.maxBody !== undefined ? { maxBody: config.maxBody } : {}),
+        ...(hintOption
+            ? {
+                earlyHints(route, request) {
+                    const send = request[EARLY_HINTS];
+                    if (send) {
+                        const links = hinter?.links(route.id) ?? [];
+                        if (links.length)
+                            send(links);
+                    }
+                },
+            }
+            : {}),
+        async head(route, data, match) {
+            const modules = await entry.universal[route.id]?.();
+            if (!modules)
+                return config.head ? rankMerge(ranked([], config.head)) : undefined;
+            const heads = [];
+            for (const [index, module] of modules) {
+                const head = module.head;
+                heads[index] = typeof head === "function" ? head({ data: data[index], params: match.params, url: match.url }) : head;
+            }
+            const contributions = ranked(heads, config.head);
+            const merged = rankMerge(contributions);
+            if (merged)
+                levels.set(merged, contributions);
+            return merged;
+        },
+        // A layout whose `head` is a function of its data reruns its loader (the merged head needs it).
+        async keepable(route) {
+            const modules = await entry.universal[route.id]?.();
+            const out = [];
+            for (const [index, module] of modules ?? [])
+                if (typeof module.head === "function")
+                    out[index] = false;
+            return out;
+        },
+        render: (input) => respond({
+            data: input.data,
+            // Shell fills: a URL whose named query reads outside the rule's key are recorded (`shell-cache.ts`).
+            url: input.shell?.url ?? input.url,
+            head: input.head,
+            ...(input.action ? { action: input.action } : {}),
+            ...(input.byURL ? { byURL: input.byURL } : {}),
+            ...(input.deps ? { deps: input.deps } : {}),
+            ...(input.deferred ? { deferred: input.deferred } : {}),
+            ...(input.moved ? { moved: input.moved } : {}),
+            ...(input.shell ? { shell: input.shell } : {}),
+        }, input.status, input.headers, input.nonce, input.request, input.locals, input.route.id),
+        renderError: async (input) => respond({
+            // The outermost layouts' data (error pages render inside the layouts that loaded).
+            data: input.layouts ?? [],
+            url: input.url,
+            head: { title: input.status === 404 ? "Not found" : "Error" },
+            error: { status: input.status, message: input.message },
+        }, input.status, input.headers, input.nonce, input.request, await errorLocals(input.locals, input.request, input.url)),
+    });
+    const given = config.routeRules ?? entry.routeRules;
+    if (!given || !Object.keys(given).length)
+        return app;
+    // Dev: headers only (a stored page would hide edits); `shell` rules probe (track reads, log why a shell would not be stored).
+    const rules = dev
+        ? Object.fromEntries(Object.entries(given).map(([pattern, rule]) => [
+            pattern,
+            { ...(rule.headers ? { headers: rule.headers } : {}), ...(rule.shell !== undefined ? { shell: devShell(rule) } : {}) },
+        ]))
+        : given;
+    const shelled = Object.values(rules).some((rule) => rule.shell);
+    if (shelled && !SHELL_BUILD)
+        throw new TypeError("createApp: `shell` route rules need a build whose `rivetRouter({ routeRules })` has a `shell` rule (it bundles the shell cache)");
+    // Route rules: their module loads at startup (pay-per-use); malformed rules reject there (unhandled: the process
+    // fails like a synchronous throw would). Requests before it settles wait for it.
+    const policy = {
+        policy: (nonce) => (csp ? csp(nonce) : false),
+        // The default / `CSPOptions` nonce policy becomes hashes in stored pages; a `csp` function keeps its nonce per page.
+        hash: config.csp === undefined ? {} : typeof config.csp === "object" ? config.csp : null,
+    };
+    let cached = null;
+    // Shell rules: the shell cache module loads with the rules module (pay-per-use: only apps with `shell` rules).
+    const loading = Promise.all([import("./route-cache.js"), SHELL_BUILD && shelled ? SHELL_BUILD() : undefined]).then(([{ withRouteRules }, shells]) => (cached = withRouteRules(app, rules, policy, entry.base ?? "", config.routeCache, shells, {
+        dev,
+        build: manifest?.runtime ?? "",
+    })));
+    const handler = (request, context) => (cached ? cached(request, context) : loading.then((ready) => ready(request, context)));
+    // The node adapter's fast path (a stored page before a Request is built), once the module loaded.
+    Object.defineProperty(handler, ROUTE_CACHE, { get: () => (cached ? cached[ROUTE_CACHE] : undefined) });
+    return handler;
+    // Dev shell rules: keys only (the probe never stores, so no times and no fixed origin).
+    function devShell(rule) {
+        if (rule.shell === false)
+            return false;
+        const own = typeof rule.shell === "object" ? rule.shell : {};
+        const cache = typeof rule.cache === "object" ? rule.cache : {};
+        const query = own.query ?? cache.query;
+        const varies = own.varies ?? cache.varies;
+        return { maxAge: 0, ...(query !== undefined ? { query } : {}), ...(varies ? { varies } : {}) };
+    }
+    // Error pages without a settled locale: the app's resolver, else the URL's locale prefix.
+    async function errorLocals(locals, request, url) {
+        const i18n = config.i18n;
+        if (!i18n || (typeof locals.locale === "string" && i18n.locales.includes(locals.locale)))
+            return locals;
+        let locale = await i18n.resolve?.(request);
+        if (!locale || !i18n.locales.includes(locale)) {
+            const first = url.pathname.split("/")[1]?.toLowerCase();
+            locale = i18n.locales.find((l) => l.toLowerCase() === first);
+        }
+        return locale ? { ...locals, locale } : locals;
+    }
+}

package/server/body.d.ts

@@ -0,0 +1,20 @@
+/** Where a directly attached page body goes. Web-standard: no Node types. */
+export interface BodySink {
+    /**
+     * One chunk: a view into a pooled slab. Call `done` once its bytes are no longer needed (written out,
+     * copied, or dropped) — the slab is reused after every handed-off view of it is done. Returns a wait
+     * when the sink applies backpressure; throws once the sink is closed (the render then ends).
+     */
+    write(chunk: Uint8Array, done: () => void): Promise<void> | undefined;
+    /** The body is complete. */
+    end(): void;
+    /** The render failed after the Response was handed out. */
+    error(error: unknown): void;
+}
+/**
+ * Own property of `renderPage` / `renderDocument` Responses: `(sink) => boolean`. True: every body byte
+ * (already rendered and later) goes to `sink` and the Response's `body` stream stays unread forever;
+ * false: the stream was already read (a copied Response, a consumer that started) — read the body.
+ */
+export declare const DIRECT_BODY: unique symbol;
+export type DirectBody = (sink: BodySink) => boolean;

package/server/body.js

@@ -0,0 +1,8 @@
+// Direct page bodies: a host adapter (node) takes a rendered page's bytes straight from the renderer's
+// slabs instead of reading the web `ReadableStream` (no queue, read promises or per-chunk races).
+/**
+ * Own property of `renderPage` / `renderDocument` Responses: `(sink) => boolean`. True: every body byte
+ * (already rendered and later) goes to `sink` and the Response's `body` stream stays unread forever;
+ * false: the stream was already read (a copied Response, a consumer that started) — read the body.
+ */
+export const DIRECT_BODY = Symbol.for("rivet.body");

package/server/deferred.d.ts

@@ -0,0 +1,12 @@
+import type { RequestEvent } from "./handler.js";
+/**
+ * The `Deferred<T>` handle of a started deferred loader. Its only property (`then`) is non-enumerable: the resume encoder
+ * writes it as an empty object (a resumed page's layout data signal holds it; client navigations carry resolved values).
+ * Dev: a Proxy that throws `DeferredDataError` when code reads a field (`data.title`) instead of rendering the handle
+ * through a boundary.
+ */
+export declare function deferredHandle(promise: Promise<unknown>, dev: boolean): object;
+/** Start deferred loader `i` now (with the request); a rejection is the boundary's, never an unhandled one. */
+export declare function startDeferred(run: () => unknown): Promise<unknown>;
+/** A deferred loader's event view: reads like its loader view, but `setHeader(s)` / `cookies.set` / `cookies.delete` throw. */
+export declare function lateEvent(event: RequestEvent): RequestEvent;

package/server/deferred.js

@@ -0,0 +1,60 @@
+// One handle per deferred slot per request: a frozen object whose non-enumerable `then` follows the loader's promise, so
+// every await form works (`Async` / `resource` fetchers, `await data`, `Promise.all`). Ruling (PPR-T01): per request, not
+// spec D3's request-independent handle resolved against the render scope — that one failed `await data` (the
+// continuation runs outside the owner, the render scope is gone) and would need AsyncLocalStorage; shell-cache H-replay
+// (T3) re-runs the page with live handles anyway, H-holes (T6) must swap a retained handle for the hit's (frame swap).
+const DOCS = "https://rivetjs.severyn.pro/guides/routing/loading-data#deferred-loaders";
+// The only string keys a handle answers in dev: what promise / boundary / encoder / JSON code reads.
+const ALLOWED = new Set(["then", "toJSON", "constructor", "valueOf", "toString"]);
+const devGet = (target, key, receiver) => {
+    if (typeof key === "symbol" || ALLOWED.has(key))
+        return Reflect.get(target, key, receiver);
+    const error = new TypeError("Deferred loader data read synchronously (`data." +
+        key +
+        "`): `load(fn, { defer: true })` data is a Deferred handle — render it through `<Async load={() => data}>` or `resource(() => data)` (" +
+        DOCS +
+        ")");
+    error.name = "DeferredDataError";
+    throw error;
+};
+const DEV_TRAPS = { get: devGet };
+/**
+ * The `Deferred<T>` handle of a started deferred loader. Its only property (`then`) is non-enumerable: the resume encoder
+ * writes it as an empty object (a resumed page's layout data signal holds it; client navigations carry resolved values).
+ * Dev: a Proxy that throws `DeferredDataError` when code reads a field (`data.title`) instead of rendering the handle
+ * through a boundary.
+ */
+export function deferredHandle(promise, dev) {
+    const handle = Object.freeze(Object.defineProperty({}, "then", { value: (ok, fail) => promise.then(ok, fail) }));
+    return dev ? new Proxy(handle, DEV_TRAPS) : handle;
+}
+/** Start deferred loader `i` now (with the request); a rejection is the boundary's, never an unhandled one. */
+export function startDeferred(run) {
+    const promise = new Promise((resolve) => resolve(run()));
+    promise.catch(() => { });
+    return promise;
+}
+const late = (what) => () => {
+    throw new TypeError(`A deferred loader cannot ${what}: the response head is sent before it settles (use a non-deferred loader or a guard)`);
+};
+const lateCookies = (cookies) => ({
+    get: cookies.get,
+    getAll: cookies.getAll,
+    set: late("set cookies"),
+    delete: late("delete cookies"),
+});
+/** A deferred loader's event view: reads like its loader view, but `setHeader(s)` / `cookies.set` / `cookies.delete` throw. */
+export function lateEvent(event) {
+    return new Proxy(event, {
+        get(target, key) {
+            if (key === "setHeader")
+                return late("set headers");
+            if (key === "setHeaders")
+                return late("set headers");
+            if (key === "cookies")
+                return lateCookies(target.cookies);
+            const value = Reflect.get(target, key, target);
+            return value;
+        },
+    });
+}

package/server/early-hints.d.ts

@@ -0,0 +1,34 @@
+import type { Head } from "../shared/data.js";
+/** `createApp({ earlyHints })`. */
+export interface EarlyHintsOptions {
+    /** Also hint the resume runtime entry (`rel=modulepreload`): pages that start it early (visible preloads). Default false. */
+    readonly runtime?: boolean;
+    /** Extra `Link` values sent as given, e.g. `"<https://cdn.example>; rel=preconnect"`. */
+    readonly links?: readonly string[];
+}
+/** Registered symbol: a per-request `(links) => void` the node adapter puts on the Request it builds (one writer of 103s). */
+export declare const EARLY_HINTS: unique symbol;
+export type HintWriter = (links: readonly string[]) => void;
+/** Whether `url` is a build asset below `base` (hashed file name, served immutable). */
+export declare const isAsset: (url: string, base: string) => boolean;
+/** `<url>; rel=preload; as=style` per linked (not inlined) build-asset stylesheet. */
+export declare function styleLinks(urls: readonly string[], inline: Readonly<Record<string, string>> | undefined, base?: string): string[];
+/**
+ * Build-asset font preloads of a merged head: build files are the same for every visitor; anything else in a head may
+ * come from loader data (preconnects, images) and is left out.
+ */
+export declare function headLinks(head: Head | undefined, base?: string): string[];
+/** Per route id: its `Link` values, re-derived when the learned head links change. */
+export interface Hinter {
+    links(routeId: string): readonly string[];
+    /** A render's merged head: its build-asset font preloads become the route's from now on. */
+    learn(routeId: string, head: Head | undefined): void;
+}
+/** `createApp`'s hinter: `styles` + the route's `routeStyles` (not inlined), learned head links, `links`, the runtime. */
+export declare function createHinter(option: true | EarlyHintsOptions, app: {
+    readonly styles: readonly string[];
+    readonly routeStyles?: Readonly<Record<string, readonly string[]>> | ((routeId: string) => unknown);
+    readonly inlineFor?: (list: readonly string[]) => Readonly<Record<string, string>> | undefined;
+    readonly base: string;
+    readonly runtime?: string | undefined;
+}): Hinter;

package/server/early-hints.js

@@ -0,0 +1,63 @@
+/** Registered symbol: a per-request `(links) => void` the node adapter puts on the Request it builds (one writer of 103s). */
+export const EARLY_HINTS = Symbol.for("rivet.earlyHints");
+// A URL written into a header value: no whitespace / controls, nothing that ends the `<…>` or splits the list.
+const SAFE = /^[^\s\0-\x1f\x7f<>"',;\\]+$/;
+const TOKEN = /^[\w./+-]+$/;
+/** Whether `url` is a build asset below `base` (hashed file name, served immutable). */
+export const isAsset = (url, base) => url.startsWith(base + "/assets/");
+/** `<url>; rel=preload; as=style` per linked (not inlined) build-asset stylesheet. */
+export function styleLinks(urls, inline, base = "") {
+    const out = [];
+    for (const url of urls)
+        if (!(inline && Object.hasOwn(inline, url)) && SAFE.test(url) && isAsset(url, base))
+            out.push(`<${url}>; rel=preload; as=style`);
+    return out;
+}
+/**
+ * Build-asset font preloads of a merged head: build files are the same for every visitor; anything else in a head may
+ * come from loader data (preconnects, images) and is left out.
+ */
+export function headLinks(head, base = "") {
+    const out = [];
+    for (const link of head?.links ?? []) {
+        const value = linkValue(link, base);
+        if (value)
+            out.push(value);
+    }
+    return out;
+}
+function linkValue(link, base) {
+    if (!SAFE.test(link.href))
+        return undefined;
+    const rel = link.rel.toLowerCase();
+    const cors = link.crossorigin === "use-credentials" ? "; crossorigin=use-credentials" : link.crossorigin ? "; crossorigin" : "";
+    if (rel === "preload" && link.as === "font" && isAsset(link.href, base))
+        return `<${link.href}>; rel=preload; as=font${link.type && TOKEN.test(link.type) ? "; type=" + link.type : ""}${cors}`;
+    return undefined;
+}
+/** `createApp`'s hinter: `styles` + the route's `routeStyles` (not inlined), learned head links, `links`, the runtime. */
+export function createHinter(option, app) {
+    const extra = option === true
+        ? []
+        : [...(option.links ?? []), ...(option.runtime && app.runtime && SAFE.test(app.runtime) ? [`<${app.runtime}>; rel=modulepreload`] : [])];
+    const learned = new Map();
+    const memo = new Map();
+    return {
+        links(routeId) {
+            let links = memo.get(routeId);
+            if (links)
+                return links;
+            const own = app.routeStyles && typeof app.routeStyles !== "function" ? app.routeStyles[routeId] : undefined;
+            const list = own?.length ? [...app.styles, ...own] : app.styles;
+            const head = learned.get(routeId);
+            links = [...styleLinks(list, app.inlineFor?.(list), app.base), ...(head ? head.split("\n") : []), ...extra];
+            memo.set(routeId, links);
+            return links;
+        },
+        learn(routeId, head) {
+            const value = headLinks(head, app.base).join("\n");
+            if (value !== (learned.get(routeId) ?? ""))
+                (value ? learned.set(routeId, value) : learned.delete(routeId), memo.delete(routeId));
+        },
+    };
+}