@rangojs/router 0.20.0 → 0.22.0

package/dist/types/prerender/create-prerender-trigger.d.ts

@@ -0,0 +1,121 @@
+/**
+ * `router.prerender()` trigger factory.
+ *
+ * Builds the `router.prerender` binder: `(runtime) => runner`, the runner being
+ * the per-target callable (plus `.many` / `.remove` / `.markStale`) from router-supplied
+ * deps. Pure and testable: all router internals (reverse, match, the producer,
+ * the request handler) arrive as injected functions, so this module has no RSC
+ * imports and can be unit-tested with fakes.
+ *
+ * One verb, dispatched by route after the match:
+ * - A `Prerender(..., { onDemand })` route takes the requestless render into
+ *   the prerender store (docs/design/ondemand-prerender.md), then, when the
+ *   app cache store is shared and an origin resolves, a warm request that
+ *   rebuilds the runtime caches on top of the new entry.
+ * - Every other route is warmed: a cookie-free GET through the router's own
+ *   handler in which every runtime cache read misses and every write replaces
+ *   the entry (docs/design/prerender-every-route.md).
+ *
+ * Contract highlights:
+ * - Requestless: the producer render never inherits the caller's request state.
+ * - A refresh always renders and replaces; `onlyIfStale` is the cron-sweep
+ *   opt-in and the only path that returns `already-fresh`.
+ * - A failed render/store keeps the previous entry (replace-on-success).
+ * - A `notFound()` in the render is not a failure: it stores a "removed"
+ *   marker in place of the page, stamped with the route's ttl and tags so it
+ *   is rechecked like a page. `prerender.remove()` stores one without
+ *   rendering, which never goes stale. A Passthrough build handler that
+ *   declines (`ctx.passthrough()`) stores one too, so its live handler answers.
+ * - A page and a render's marker (a `notFound()` or a decline) carry the
+ *   render's start as `storedAt`, so a `markStale()` that lands during the
+ *   render marks the result; `staleAt` counts the ttl from the write. A
+ *   `remove()` marker renders nothing and carries its write time.
+ * - An on-demand target is path-only (its key carries no search); a warm
+ *   target keeps its search params, which cache keys carry.
+ * - A warm writes only to a store shared beyond the place the call runs.
+ */
+import type { SerializedSegmentData } from "../cache/types.js";
+import type { HandlerCacheConfig } from "../rsc/types.js";
+import type { ExecutionContext } from "../types/request-scope.js";
+import type { OnDemandRouteConfig, PrerenderConfig, PrerenderFn, PrerenderResult } from "./on-demand.js";
+/** Route metadata the trigger needs, resolved from a pathname by the router. */
+export interface PrerenderMatchInfo {
+    routeName: string;
+    params: Record<string, string>;
+    /** True when the route opted into on-demand (Prerender(..., { onDemand })). */
+    isOnDemand: boolean;
+    /** True when the route is wrapped in Passthrough(). */
+    isPassthrough: boolean;
+}
+/**
+ * Raw producer output (matchForPrerender's main-variant shape). `onDemandConfig`
+ * is the route's `onDemand: { ttl, tags }` object (the `tags` callback can't
+ * ride the serialized trie), read from the loaded route entry during production.
+ */
+export interface ProducerOutput {
+    segments: SerializedSegmentData[];
+    handles: string;
+    routeName: string;
+    params: Record<string, string>;
+    passthrough?: true;
+    /** The render hit `notFound()` and nothing else failed: no page to store. */
+    notFound?: true;
+    onDemandConfig?: OnDemandRouteConfig;
+}
+export interface PrerenderTriggerDeps<TEnv = any> {
+    routerId: string;
+    /**
+     * The key version: the router's data version (resolvePrerenderVersion),
+     * resolved per refresh (once per `.many()` batch), as the request handler
+     * resolves it per request.
+     */
+    resolveVersion: () => string;
+    /** True when running under Vite dev (drives the producer context's `dev`). */
+    isDev: () => boolean;
+    /**
+     * True under the Vite dev server (isViteDevServer): the one place the
+     * memory store counts as shared, and so where the not-shared warning fires.
+     */
+    isViteDevServer: () => boolean;
+    /** Load the per-router manifest/trie before matching, as router.fetch does. */
+    ensureManifest: () => Promise<void>;
+    /** Resolve the env-scoped prerender config (factory or object); undefined when unconfigured. */
+    resolveConfig: (env: TEnv, ctx: ExecutionContext | undefined) => PrerenderConfig<TEnv> | undefined;
+    /** Reverse an object target to a pathname; undefined when the route name is unknown. */
+    reverse: (route: string, params: Record<string, string>) => string | undefined;
+    /** Match a pathname to route metadata; null when nothing matches. */
+    matchRoute: (pathname: string) => PrerenderMatchInfo | null | Promise<PrerenderMatchInfo | null>;
+    /** Run the requestless producer (matchForPrerender with onDemand). May throw. */
+    runProducer: (input: {
+        pathname: string;
+        isPassthrough: boolean;
+        env: TEnv;
+        dev: boolean;
+    }) => Promise<ProducerOutput | null>;
+    /**
+     * Resolve `createRouter({ cache })` (factory or object) for a warm;
+     * undefined when the router has none. May throw, like the prerender factory.
+     */
+    resolveCacheConfig: (env: TEnv, ctx: ExecutionContext) => HandlerCacheConfig | undefined;
+    /** The router's own request handler (`router.fetch`): where a warm is dispatched. */
+    fetch: (request: Request, input: {
+        env: TEnv;
+        ctx: ExecutionContext;
+    }) => Promise<Response>;
+    /** The origin of the request the runner is called from, when there is one. */
+    ambientOrigin: () => string | undefined;
+}
+/** Thrown by the trigger when `throwOnError: true` and the operation did not succeed. */
+export declare class PrerenderError extends Error {
+    readonly result: Extract<PrerenderResult, {
+        ok: false;
+    }>;
+    /** `operation` is the runner call that failed; the message names it. */
+    constructor(result: Extract<PrerenderResult, {
+        ok: false;
+    }>, operation?: "prerender" | "remove");
+}
+/**
+ * Create the `router.prerender` callable. See {@link PrerenderTriggerDeps}.
+ */
+export declare function createPrerenderTrigger<TEnv = any, TRoutes = {}>(deps: PrerenderTriggerDeps<TEnv>): PrerenderFn<TEnv, TRoutes>;

package/dist/types/prerender/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Public on-demand prerender surface (`@rangojs/router/prerender`).
+ *
+ * Store contracts, config/result/target types, and the in-memory store (usable
+ * as a durable overlay in single-process node/Vercel functions, and as a test
+ * fake). The Cloudflare KV adapter lives in `@rangojs/router/prerender/cloudflare`.
+ */
+export { PrerenderError } from "./create-prerender-trigger.js";
+export { createMemoryPrerenderStore, type MemoryPrerenderStore, type MemoryPrerenderStoreOptions, } from "./memory-prerender-store.js";
+export { serializePrerenderKey, type PrerenderKey, type PrerenderStoredEntry, type WritablePrerenderStore, } from "./writable-store.js";
+export type { OnDemandOption, OnDemandRouteConfig, PrerenderConfig, PrerenderFn, PrerenderResult, PrerenderWarmCaches, PrerenderManyOptions, PrerenderRunner, PrerenderRunOptions, PrerenderRuntime, PrerenderTarget, PrerenderTargetObject, } from "./on-demand.js";
+export type { PrerenderEntry } from "./store.js";

package/dist/types/prerender/memory-prerender-store.d.ts

@@ -0,0 +1,29 @@
+/**
+ * In-memory writable prerender store.
+ *
+ * Backs the zero-config dev overlay and the `@rangojs/router/testing` fake.
+ * A plain Map — no per-isolate null memoization (a later set() must be visible
+ * after an earlier miss), no React/RSC deps.
+ */
+import { type PrerenderKey, type PrerenderStoredEntry, type WritablePrerenderStore } from "./writable-store.js";
+export interface MemoryPrerenderStore extends WritablePrerenderStore {
+    delete(key: PrerenderKey): Promise<void>;
+    markStale(routerId: string, tags: string[]): Promise<void>;
+    /** Synchronous read by structured key (tests). */
+    peek(key: PrerenderKey): PrerenderStoredEntry | null;
+    /** All stored [serializedKey, entry] pairs (tests). */
+    entries(): [string, PrerenderStoredEntry][];
+    /** Drop every entry. */
+    clear(): void;
+    readonly size: number;
+}
+export interface MemoryPrerenderStoreOptions {
+    /** Injectable clock for `markStale` in deterministic tests. Defaults to Date.now. */
+    now?: () => number;
+}
+/**
+ * Create an in-memory {@link WritablePrerenderStore} with test-inspection
+ * helpers. Invalidation is mark-stale (sets `staleAt`), never delete — matching
+ * the durable v1 contract so the entry keeps serving until refreshed.
+ */
+export declare function createMemoryPrerenderStore(options?: MemoryPrerenderStoreOptions): MemoryPrerenderStore;

package/dist/types/prerender/on-demand.d.ts

@@ -0,0 +1,272 @@
+/**
+ * Public type surface for on-demand (ISR-style) prerender: the router
+ * `prerender` config option, the `router.prerender({ env, ctx })` runner, its typed
+ * target, and the inspectable result union.
+ *
+ * Types only — safe to import from router options, the public interfaces, the
+ * testing barrel, and platform adapters without pulling RSC deps.
+ */
+import type { ExecutionContext } from "../types/request-scope.js";
+import type { IsEmptyObject, ParamsFor } from "../reverse.js";
+import type { WritablePrerenderStore } from "./writable-store.js";
+import type { ShellCaptureRefusal } from "../rsc/shell-capture-constants.js";
+declare const prerenderTargetBrand: unique symbol;
+/**
+ * The target `onRevalidate` receives: a plain `{ route, params }` that goes
+ * straight into a queue message. The type-only brand (never present at
+ * runtime) lets the runner (`router.prerender({ env })(target)` / `.many()`) accepts it with no cast on a
+ * router typed with named routes, while a hand-written `{ route: "typo" }`
+ * stays a type error there. After a JSON round trip, assert it back:
+ * `JSON.parse(raw) as PrerenderTargetObject`.
+ */
+export interface PrerenderTargetObject {
+    route: string;
+    params: Record<string, string>;
+    readonly [prerenderTargetBrand]: true;
+}
+/**
+ * Route map used to type the object target. When the fluent `TRoutes` phantom is
+ * empty (the common `createRouter().routes(...)` case leaves it `{}`), fall back
+ * to the generated global route map — the same fallback `Prerender<"name">` and
+ * `reverse` use — so `router.prerender({ route, params })` stays typed without an
+ * explicit route-type parameter.
+ */
+type PrerenderRouteMap<TRoutes> = keyof TRoutes extends never ? keyof Rango.GeneratedRouteMap extends never ? {} : Rango.GeneratedRouteMap : TRoutes;
+/**
+ * Typed object target, derived from the router's route map the same way
+ * `reverse` is. No-param routes may omit `params`.
+ */
+type PrerenderRouteTarget<TRoutes> = {
+    [TName in keyof PrerenderRouteMap<TRoutes> & string]: IsEmptyObject<ParamsFor<PrerenderRouteMap<TRoutes>, TName>> extends true ? {
+        route: TName;
+        params?: Record<string, never>;
+    } : {
+        route: TName;
+        params: ParamsFor<PrerenderRouteMap<TRoutes>, TName>;
+    };
+}[keyof PrerenderRouteMap<TRoutes> & string];
+/**
+ * A prerender target: a typed named-route object, a path-like string/URL
+ * (`router.reverse()` output composes for free), or the `onRevalidate` target.
+ */
+export type PrerenderTarget<TRoutes = {}> = string | URL | PrerenderRouteTarget<TRoutes> | PrerenderTargetObject;
+/** Env + platform capabilities bound once by `router.prerender({ env, ctx })`. */
+export interface PrerenderRuntime<TEnv = any> {
+    /** The live env: the producer's `ctx.env` (not the build's `buildEnv`). */
+    env: TEnv;
+    /** Cloudflare `ExecutionContext`; absent on node/Vercel. */
+    ctx?: ExecutionContext;
+    /**
+     * The origin a warm requests a path or `{ route, params }` target on, for
+     * example `"https://shop.example"`. Cache keys carry the host, so a warm
+     * must request the host visitors use. A full-URL target uses its own
+     * origin; without this option the runner uses the origin of the request it
+     * is called from (an action, a route handler, `onRevalidate`), and with
+     * neither a warm returns `skipped-no-origin`. An on-demand route's
+     * requestless render never needs it.
+     */
+    origin?: string;
+}
+/** Per-call options of the bound runner. */
+export interface PrerenderRunOptions {
+    /** Throw on failure instead of returning an `{ ok: false }` result. */
+    throwOnError?: boolean;
+    /**
+     * Only refresh what is cold or stale (cron-sweep opt-in), and the only
+     * path that can return `already-fresh`. On an on-demand route the stored
+     * entry is rendered only when stale. On any other route the warm reads its
+     * caches normally instead of forcing misses, so a fresh entry is left
+     * alone, a stale one refreshes and a missing one is written.
+     */
+    onlyIfStale?: boolean;
+}
+/** Per-call options of the bound runner's `.many()`. */
+export interface PrerenderManyOptions extends PrerenderRunOptions {
+    /** Max concurrent renders in a batch (default 1; any invalid value is 1). */
+    concurrency?: number;
+}
+/**
+ * What a warm request wrote, by cache. On a result of the warm path, and on
+ * an on-demand result whose route was also warmed.
+ */
+export interface PrerenderWarmCaches {
+    /**
+     * Store writes that landed, by store family: `record` (route `cache()`),
+     * `item` (`"use cache"` and loader `cache()`), `response` (the document
+     * cache and response routes), `shell` (the `ppr` shell).
+     */
+    writes: {
+        record: number;
+        item: number;
+        response: number;
+        shell: number;
+    };
+    /**
+     * The `ppr` shell; absent on a route without `ppr`. `fresh` is
+     * `onlyIfStale` finding a servable shell; `not-eligible` is a request the
+     * shell path passed on (an active nonce, a store without shells, the
+     * route's own `cache()` opt-out, a buffered response).
+     */
+    shell?: "stored" | "fresh" | "refused" | "no-shell" | "not-eligible" | "skipped-capacity" | "skipped-queue-timeout" | "error";
+    /** Why the capture refused to store the shell. */
+    refusal?: ShellCaptureRefusal;
+    /** The document cache, when `createDocumentCacheMiddleware` ran. */
+    document?: "stored" | "not-cacheable";
+}
+/**
+ * Inspectable result, one per target. The trigger does not force callers
+ * into try/catch; `throwOnError: true` opts into throwing for admin/CI
+ * endpoints. `path` says what ran: `on-demand` is the requestless render of a
+ * `Prerender(..., { onDemand })` route into the prerender store, `warm` is a
+ * request through the router's handler that rewrites the route's runtime
+ * caches.
+ */
+export type PrerenderResult = {
+    ok: true;
+    path: "on-demand";
+    /**
+     * `already-fresh` only occurs with `onlyIfStale: true`.
+     *
+     * `removed`: a "removed" marker is stored in place of the page, and
+     * requests no longer get the page or its build-time entry. It is
+     * `ok: true`, so count it in sweep results. Written by
+     * `prerender.remove()` (permanent until a refresh without
+     * `onlyIfStale`; `tags` empty, no `ttl`), or by a refresh in which a
+     * `notFound()` was the only thing that went wrong, anywhere in the
+     * render: the route handler, a layout or parallel slot handler, any
+     * server component. That marker has the route's `tags` and `ttl` and is
+     * rechecked like a page. `onlyIfStale` finding a fresh marker reports
+     * `removed` too. When the data source may be failing, throw anything
+     * else: that is `render-failed` and keeps the page.
+     */
+    status: "rendered" | "already-fresh" | "removed";
+    target: string;
+    routeName: string;
+    /** Opaque, for debugging/logs only — not a stable format. */
+    key: string;
+    tags: string[];
+    /** Absent = never stale. */
+    ttl?: number;
+    /**
+     * The warm request that followed the store write. Absent when the app
+     * store is not shared, no origin resolved, or nothing was rendered.
+     */
+    caches?: PrerenderWarmCaches;
+} | {
+    ok: true;
+    path: "warm";
+    /** `already-fresh` only occurs with `onlyIfStale: true`. */
+    status: "warmed" | "already-fresh";
+    /** The absolute URL that was requested. */
+    target: string;
+    routeName: string;
+    /** The warm response's HTTP status. */
+    responseStatus: number;
+    caches: PrerenderWarmCaches;
+} | {
+    ok: false;
+    /** Absent when no route matched: every other result is past the match. */
+    path?: "on-demand" | "warm";
+    status: "no-match" | "no-store" | "skipped-personalized" | "skipped-unsupported-target" | "skipped-passthrough" | "skipped-not-on-demand" | "skipped-store-not-shared" | "skipped-no-origin" | "shell-not-stored" | "skipped-uncached" | "render-failed" | "store-failed";
+    target: string;
+    routeName?: string;
+    /** The warm response's HTTP status, when a warm request ran. */
+    responseStatus?: number;
+    caches?: PrerenderWarmCaches;
+    error?: unknown;
+};
+/**
+ * Per-route on-demand opt-in, carried inside `PrerenderOptions.onDemand`. Any
+ * truthy spelling works (literal, spread, imported const): producer retention
+ * is driven by the evaluated route manifest, not a textual scan of the call.
+ */
+export interface OnDemandRouteConfig {
+    /** Soft TTL (seconds) for entries refreshed for this route. Overrides the router `ttl`. */
+    ttl?: number;
+    /**
+     * Tags stamped on the stored entry, addressable via
+     * the runner's `markStale()`. A separate namespace from `cacheTag()` /
+     * `updateTag()` / `revalidateTag()`, which never reach the prerender store.
+     */
+    tags?: string[] | ((target: {
+        params: Record<string, string>;
+    }) => string[]);
+}
+export type OnDemandOption = boolean | OnDemandRouteConfig;
+/**
+ * Env-resolved prerender store configuration. Same union shape as the `cache`
+ * option: a plain object or a factory resolved per request/per call, never at
+ * `createRouter()` time.
+ */
+export interface PrerenderConfig<TEnv = any> {
+    store: WritablePrerenderStore;
+    /**
+     * Default soft TTL (seconds) for a route whose `onDemand` sets none. Absent
+     * = never stale. Soft: a stale entry keeps serving; staleness only decides
+     * whether `onRevalidate` is scheduled. Entries never expire.
+     */
+    ttl?: number;
+    /**
+     * Stale-while-revalidate: its presence is the opt-in. Scheduled through
+     * `waitUntil` on a stale overlay hit (the stale entry still serves) with
+     * the JSON-serializable target and the live env. Runs at most once per
+     * stale key per isolate while one is in flight (one running longer than
+     * 15 s counts as finished, so a hung call cannot block the key), so
+     * `(target, env, ctx) => router.prerender({ env, ctx })(target, { onlyIfStale: true })`
+     * is safe in a single process; across isolates, point it at a queue, which
+     * owns dedup. Pass `onlyIfStale` in the call that runs later: a job queued
+     * for a page that `prerender.remove()` then removed finds the marker and
+     * renders nothing, where a plain refresh would bring the page back.
+     */
+    onRevalidate?: (target: PrerenderTargetObject, env: TEnv, 
+    /** The stale request's execution context; absent where none exists. */
+    ctx?: ExecutionContext) => void | Promise<void>;
+}
+/**
+ * @internal Per-request resolution of the prerender config plus the key
+ * version. Threaded onto the request context by the RSC handler and read by
+ * the serve-path overlay lookup.
+ */
+export interface ResolvedPrerender<TEnv = any> {
+    /** The resolved config; the store is `config.store`. */
+    config: PrerenderConfig<TEnv>;
+    routerId: string;
+    /** The router's cache version for overlay keys (resolvePrerenderVersion). */
+    version: string;
+}
+/**
+ * The runner `router.prerender({ env, ctx })` returns: callable per target,
+ * plus `.many` / `.remove` / `.markStale`. Typing rides the phantom `TRoutes`
+ * accumulator, like `reverse`.
+ */
+export interface PrerenderRunner<TRoutes = {}> {
+    (target: PrerenderTarget<TRoutes>, options?: PrerenderRunOptions): Promise<PrerenderResult>;
+    many(targets: ReadonlyArray<PrerenderTarget<TRoutes>>, options?: PrerenderManyOptions): Promise<PrerenderResult[]>;
+    /**
+     * Remove an on-demand route's page without rendering: a "removed" marker is
+     * stored in place of it. Requests then get a 404 (a `Passthrough` route: its
+     * live handler), never the build-time entry. Permanent: no `ttl`, no
+     * `onRevalidate`, left by `onlyIfStale`, until a `prerender(target)`
+     * without `onlyIfStale` renders the page again. It is a write like a
+     * refresh's, and the last write wins. `{ ok: true, status: "removed" }`; a
+     * route that is not on-demand is `skipped-not-on-demand`. `.many` is the
+     * batch form.
+     */
+    remove: {
+        (target: PrerenderTarget<TRoutes>, options?: Pick<PrerenderRunOptions, "throwOnError">): Promise<PrerenderResult>;
+        many(targets: ReadonlyArray<PrerenderTarget<TRoutes>>, options?: Omit<PrerenderManyOptions, "onlyIfStale">): Promise<PrerenderResult[]>;
+    };
+    /**
+     * Mark this router's stored entries carrying one of `tags` stale. Marking only: the
+     * entries keep serving, and a stale hit schedules `onRevalidate` when one is
+     * configured. Nothing is deleted or re-rendered here.
+     */
+    markStale(tags: string[]): Promise<void>;
+}
+/**
+ * The `router.prerender` function: binds the runtime (`env`, `ctx`) and returns
+ * the {@link PrerenderRunner}. Binding does no work; the config factory is
+ * resolved per call.
+ */
+export type PrerenderFn<TEnv = any, TRoutes = {}> = (runtime: PrerenderRuntime<TEnv>) => PrerenderRunner<TRoutes>;
+export {};

package/dist/types/prerender/producer-guard.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Requestless-prerender guard.
+ *
+ * The on-demand producer renders a route with only route params + env — never
+ * the triggering request's cookies, headers, geo, or session (see the design's
+ * Producer Semantics). Personalized reads during a producer render would bake
+ * one visitor's data into a payload shared with everyone for that route.
+ *
+ * The producer marks its own request context with `_onDemandProducer: true`. The
+ * standalone request-scoped helpers a handler reaches for — `cookies()`,
+ * `headers()`, `invalidateClientCache()`, `keepClientCache()` — call
+ * {@link assertNotInsidePrerenderProducer}, which throws
+ * {@link PrerenderPersonalizationError}; the producer catches it and maps to a
+ * `skipped-personalized` result, leaving any existing entry untouched. (The
+ * producer context's own `ctx.cookie`/`header`/etc. remain the pre-existing
+ * build-time no-op stubs over empty synthetic state — the guard covers the
+ * standalone helpers, which are the reads that would otherwise see real request
+ * data.)
+ */
+/** Thrown when a producer render touches request-specific state. */
+export declare class PrerenderPersonalizationError extends Error {
+    /** Cross-realm-safe brand (instanceof can fail across bundle/realm boundaries). */
+    readonly isPrerenderPersonalizationError: true;
+    constructor(api: string);
+}
+export declare function isPrerenderPersonalizationError(value: unknown): value is PrerenderPersonalizationError;
+/**
+ * Throw {@link PrerenderPersonalizationError} when `ctx` is a requestless
+ * on-demand producer context. A no-op for the live request path and the
+ * build/dev prerender paths (which do not set `_onDemandProducer`), so existing
+ * callers are unaffected.
+ */
+export declare function assertNotInsidePrerenderProducer(ctx: unknown, api: string): void;

package/dist/types/prerender/shell-manifest-key.d.ts

@@ -1,18 +1 @@
-/**
- * Build shell manifest key, shared by the producer (the build's shell
- * prerender phase, vite/discovery/shell-prerender-phase.ts) and the consumer
- * (the runtime read-through, rsc/shell-build-manifest.ts) so the format
- * cannot drift. Dependency-free: the producer runs node-side in the plugin,
- * the consumer in the RSC runtime.
- *
- * PATHNAME-ONLY by design. Host-free because the build knows no request
- * host. Router-free because the router id ($$id) is a hash of
- * filePath:lineNumber of the TRANSFORMED source, which differs between the
- * discovery temp server's dev-style transform chain and the main build's —
- * a temp-realm router id can never be looked up by the shipped worker. The
- * producer instead detects pathname collisions across routers at build time
- * and declines both entries (loudly), keeping the key unambiguous. This is
- * a manifest namespace, never a store keyspace: the runtime shell key
- * (host + pathname + search + ":shell") stays untouched.
- */
-export declare function buildShellManifestKey(pathname: string): string;
+export declare function buildShellManifestKey(routerId: string, pathname: string): string;

package/dist/types/prerender/warm-request.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The mark and record of a `router.prerender()` warm request
+ * (docs/design/prerender-every-route.md, "The synthetic request"). The
+ * trigger marks the `Request` it dispatches, the handler puts the record on
+ * the request context (`RequestContext._prerenderWarm`), and each cache layer
+ * reads the context where it reads its store. No runtime imports: the cache
+ * layers import this without pulling the trigger.
+ */
+import type { HandlerCacheConfig } from "../rsc/types.js";
+import type { ShellCaptureDebugEvent } from "../rsc/shell-capture.js";
+import type { PrerenderWarmCaches } from "./on-demand.js";
+/** What one warm request did: written by the layers, read by the trigger. */
+export interface PrerenderWarmRecord extends PrerenderWarmCaches {
+    /**
+     * `replace`: every runtime cache read misses and the writes replace the
+     * entries. `fill` (`onlyIfStale`): reads are normal; the record only reports.
+     */
+    mode: "replace" | "fill";
+    /**
+     * The `createRouter({ cache })` config the trigger gated on its scope. The
+     * handler uses it instead of resolving the option again, so the store that
+     * was checked is the store that is written.
+     */
+    cacheConfig: HandlerCacheConfig;
+    /** The surface an identity guard refused (server/context.ts guardIdentityRead). */
+    identity?: string;
+    /**
+     * The request's render errors: the handler adopts this list as
+     * `RequestContext._renderErrors`, so what the layers push lands here.
+     */
+    renderErrors: unknown[];
+}
+/** What the helpers read; a derived capture context inherits the record. */
+export interface WarmContext {
+    _prerenderWarm?: PrerenderWarmRecord;
+    _shellCaptureRun?: boolean;
+}
+export declare function createWarmRecord(mode: PrerenderWarmRecord["mode"], cacheConfig: HandlerCacheConfig): PrerenderWarmRecord;
+/** The mark is the object: a clone or a rebuilt request carries none. */
+export declare function markWarmRequest(request: Request, record: PrerenderWarmRecord): void;
+export declare function readWarmMark(request: Request): PrerenderWarmRecord | undefined;
+/**
+ * True when this request must read every runtime cache as a miss. A flag read
+ * at each read point, not a store wrapper: a route's or loader's own
+ * `cache({ store })` bypasses the app store (CacheScope.getStore), and the
+ * "use cache" in-flight dedup lives outside the store, so a wrapper would
+ * miss both.
+ *
+ * False in the warm's own shell capture (`_shellCaptureRun`): it runs after
+ * the warm's writes settled and must replay them, or it would render every
+ * handler a second time and could bake another generation than the one just
+ * written.
+ */
+export declare function isWarmReplace(ctx: WarmContext | null | undefined): boolean;
+/** Count a store write that landed. No-op outside a warm. */
+export declare function noteWarmWrite(ctx: WarmContext | null | undefined, family: keyof PrerenderWarmCaches["writes"]): void;
+/** Record the document cache's outcome; its store write counts through noteWarmWrite. */
+export declare function noteWarmDocument(ctx: WarmContext | null | undefined, outcome: NonNullable<PrerenderWarmCaches["document"]>): void;
+/** Record the surface an identity guard (guardIdentityRead) is about to refuse. */
+export declare function noteWarmIdentityRead(ctx: WarmContext | null | undefined, surface: string): void;
+/**
+ * Fold one capture event into the record: the last attempt's outcome stands.
+ * The skips a forced capture never takes and the `backoff` notice leave it.
+ */
+export declare function noteWarmShellEvent(record: PrerenderWarmRecord, event: ShellCaptureDebugEvent): void;

package/dist/types/prerender/warm.d.ts

@@ -0,0 +1,65 @@
+/**
+ * One `router.prerender()` warm request: build the synthetic visitor request,
+ * dispatch it through the router's own handler, wait for everything it
+ * scheduled, and read back what it wrote
+ * (docs/design/prerender-every-route.md, "The synthetic request"). The handler
+ * is an injected `fetch`, so unit tests drive this with a fake.
+ */
+import { type CollectingExecutionContext } from "../cache/background-task.js";
+import type { HandlerCacheConfig } from "../rsc/types.js";
+import type { ExecutionContext } from "../types/request-scope.js";
+import type { PrerenderResult, PrerenderWarmCaches } from "./on-demand.js";
+import { type PrerenderWarmRecord } from "./warm-request.js";
+/**
+ * How long a warm waits for its response body and background work: a capture
+ * that waited out the queue budget, then ran to its hard cap.
+ */
+export declare const WARM_SETTLE_BUDGET_MS: number;
+export interface WarmRequestInput<TEnv> {
+    /** The absolute URL a visitor requests. */
+    url: URL;
+    mode: PrerenderWarmRecord["mode"];
+    /** The gated `createRouter({ cache })` config; the handler writes to its store. */
+    cacheConfig: HandlerCacheConfig;
+    env: TEnv;
+    /** The context `cacheConfig` was resolved with. */
+    ctx: CollectingExecutionContext;
+    /** `router.fetch`. */
+    fetch: (request: Request, input: {
+        env: TEnv;
+        ctx: ExecutionContext;
+    }) => Promise<Response>;
+    /** Tests shorten the wait. */
+    settleBudgetMs?: number;
+}
+export interface WarmRequestOutcome {
+    record: PrerenderWarmRecord;
+    /** Absent when the handler threw before answering. */
+    responseStatus?: number;
+    /** The handler's throw, a body that failed mid-stream, or a wait that ran out. */
+    error?: unknown;
+}
+/**
+ * Dispatch one warm: a GET with `accept: text/html` and nothing else, so it
+ * lands in the partition a header-less visitor lands in. The response is
+ * drained and dropped: what it rendered reaches a visitor only through a
+ * store.
+ */
+export declare function runWarmRequest<TEnv>(input: WarmRequestInput<TEnv>): Promise<WarmRequestOutcome>;
+/** The per-cache detail a result carries. */
+export declare function warmCaches(record: PrerenderWarmRecord): PrerenderWarmCaches;
+/**
+ * A warm's status from what it recorded, first match wins. An identity
+ * refusal comes ahead of the render failure it usually also causes (the guard
+ * throws). `record.shell` is set only for a `ppr` route (shellServePlan).
+ */
+export declare function warmStatus(outcome: WarmRequestOutcome): WarmStatus;
+type WarmStatus = Extract<PrerenderResult, {
+    ok: true;
+    path: "warm";
+}>["status"] | Extract<PrerenderResult, {
+    ok: false;
+}>["status"];
+/** The `PrerenderResult` of a finished warm. */
+export declare function composeWarmResult(outcome: WarmRequestOutcome, target: string, routeName: string): PrerenderResult;
+export {};