@rangojs/router 0.21.0 → 0.22.0

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 {};

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

@@ -0,0 +1,170 @@
+/**
+ * Writable prerender store contract for on-demand (ISR-style) prerender refresh.
+ *
+ * The bundled build manifest (store.ts) is immutable and read-only. On-demand
+ * prerender adds a writable durable overlay in front of it: `router.prerender()`
+ * renders a route and writes a versioned envelope here; the serve path reads the
+ * overlay before the bundled manifest.
+ *
+ * This module is types + pure helpers only — no React/RSC/plugin-rsc imports —
+ * so it can be imported by the testing barrel and platform adapters alike.
+ */
+import type { PrerenderEntry } from "./store.js";
+/**
+ * Structured durable-overlay key. Includes the router's cache version so a
+ * deploy that changed the router's server code never reads Flight payloads
+ * that reference its previous build, and so Cloudflare gradual deployments
+ * stay correct (old and new worker versions each read their own namespace).
+ */
+export interface PrerenderKey {
+    routerId: string;
+    /**
+     * The owning router's cache version (its data version, or
+     * `createRouter({ version })`). Opaque: never set or read by app code; a
+     * store keys off it as given.
+     */
+    version: string;
+    routeName: string;
+    /** DJB2 8-hex hash of the canonical params (see param-hash.ts). */
+    paramHash: string;
+}
+/**
+ * @internal What the trigger stamps on a write. TTL is soft staleness metadata
+ * (`staleAt`), never a hard store expiry: hard expiry would delete the entry
+ * a stale-while-revalidate serve needs, and an expired overlay would fall back
+ * to older bundled-manifest content.
+ */
+export interface StoredEntryOptions {
+    /** Seconds until the entry is considered stale. Absent = never stale. */
+    ttl?: number;
+    tags: string[];
+    /** Canonical params, stored for verify-on-read. */
+    params: Record<string, string>;
+}
+/** What a page and a "removed" marker both carry: a store reads either alike. */
+interface StoredEnvelope {
+    v: 1;
+    meta: {
+        /**
+         * When the render started, not when the entry was written: a `markStale()`
+         * at or after it (strictly after in an in-process store) covers the entry.
+         * A `remove()` marker renders nothing and carries its write time.
+         */
+        storedAt: number;
+        /**
+         * Absent = never stale. Soft metadata only; controls `onRevalidate`
+         * scheduling, not serving. Counts the ttl from the write. A store may
+         * lower it (tag markers do).
+         */
+        staleAt?: number;
+        /** The configured ttl in seconds, as a result reports it. Absent = none. */
+        ttl?: number;
+        tags: string[];
+        /** The key's `version` at write time; verified on read. */
+        version: string;
+        /** Verified against the request's params on read (DJB2 collision guard). */
+        params: Record<string, string>;
+    };
+}
+type StoredPage = StoredEnvelope & {
+    entry: PrerenderEntry;
+    removed?: never;
+};
+/**
+ * The "removed" marker (tombstone) stored in place of a page, by
+ * `prerender.remove()` or by a refresh whose render hit `notFound()` (or
+ * declined with `ctx.passthrough()`). A request that finds it is not served
+ * the build-time entry below the overlay. No `entry`: a router from before the
+ * marker rejects it as malformed (a miss) instead of serving an empty page.
+ * `meta` is stamped like a page's for a render outcome, so that marker goes
+ * stale and is rechecked; a `remove()` marker has no `staleAt` and no tags.
+ */
+type StoredTombstone = StoredEnvelope & {
+    removed: true;
+    entry?: never;
+};
+/**
+ * Versioned envelope the router composes on a refresh or a removal and
+ * verifies on every read: a page, or the marker that the page was removed. A
+ * store persists either as given and returns it as stored.
+ */
+export type PrerenderStoredEntry = StoredPage | StoredTombstone;
+/**
+ * The writable durable overlay: plain get/set. Backed in production by a
+ * platform adapter (Cloudflare KV, …) and in dev/tests by an in-memory store.
+ * The router composes the envelope before `set()` and verifies whatever `get()`
+ * returns (shape, `version`, params collision guard), so a store holds no
+ * policy of its own.
+ *
+ * Key everything off the `key` argument (`serializePrerenderKey(key)` carries
+ * `key.version`). Never call `getCacheVersions()` here: the trigger's `set()`
+ * runs outside the producer's request context, where it returns the
+ * whole-build fallback instead of the owning router's version.
+ */
+export interface WritablePrerenderStore {
+    /**
+     * The envelope stored under `key`, or null. Never memoize a miss: a refresh
+     * can write the key after a request missed it. May lower `meta.staleAt` (a
+     * tag marked stale after the entry was written).
+     */
+    get(key: PrerenderKey): Promise<PrerenderStoredEntry | null>;
+    /**
+     * Persist `stored` (a page, or the marker that the page was removed) under
+     * `key`, replacing any previous entry. No expiry.
+     */
+    set(key: PrerenderKey, stored: PrerenderStoredEntry): Promise<void>;
+    delete?(key: PrerenderKey): Promise<void>;
+    /**
+     * Mark the entries of router `routerId` (`PrerenderKey.routerId`) carrying
+     * any of `tags` stale (they keep serving). A mark covers an entry whose
+     * `meta.storedAt` it is at or after (strictly after for an in-process
+     * store), including one `set()` after the mark: a store that marks held
+     * entries in place has to remember its marks. Scope it to that router: routers
+     * behind a host router share one store, and a tag is only meaningful inside
+     * the router whose routes declared it. Optional: without it,
+     * `router.prerender().markStale()` is a no-op for this store.
+     */
+    markStale?(routerId: string, tags: string[]): Promise<void>;
+}
+/**
+ * Serialize a {@link PrerenderKey} to the design's string form:
+ *   `prerender:{routerId}:{version}:{routeName}:{paramHash}`
+ */
+export declare function serializePrerenderKey(key: PrerenderKey): string;
+/**
+ * @internal Compose the versioned envelope the trigger hands to `store.set()`.
+ * `now` is `meta.storedAt`; `staleFrom` (default `now`) is where the ttl
+ * starts counting. Both are passed explicitly so tests stay deterministic.
+ */
+export declare function composeStoredEntry(key: PrerenderKey, entry: PrerenderEntry, options: StoredEntryOptions, now: number, staleFrom?: number): StoredPage;
+/**
+ * @internal Compose the "removed" marker stored in place of a page. Its meta
+ * is a page's (composeStoredEntry), so `ttl` and `tags` mean the same: the
+ * marker of a render outcome is given the route's and is rechecked like a
+ * page; `prerender.remove()` gives neither, and its marker never goes stale.
+ */
+export declare function composeStoredTombstone(key: PrerenderKey, options: StoredEntryOptions, now: number, staleFrom?: number): StoredTombstone;
+/**
+ * @internal Verify a store's answer is safe to serve for this key: the
+ * envelope shape and version tag, the key version, and the stored params
+ * against the request's (the 8-hex DJB2 collision guard, param-hash.ts: a
+ * runtime write keyed off webhook-supplied params must not serve one page's
+ * content under another's URL, nor remove another's page). False means treat
+ * it as a miss. Run by the router on every read, so a third-party store
+ * cannot skip it.
+ */
+export declare function isStoredEntryValidFor(stored: unknown, key: PrerenderKey, params: Record<string, string>): stored is PrerenderStoredEntry;
+/** True once `now` has passed the entry's soft `staleAt`. Never-stale entries never go stale. */
+export declare function isStoredEntryStale(stored: PrerenderStoredEntry, now: number): boolean;
+/**
+ * @internal Lower `meta.staleAt` to `at` when it is unset or later. Shared by
+ * the stores' tag marking so the rule cannot drift between them.
+ */
+export declare function lowerStoredEntryStaleAt(stored: PrerenderStoredEntry, at: number): void;
+/**
+ * @internal `store.get(key)` verified for serving (isStoredEntryValidFor). A
+ * store error (e.g. a KV outage) reads as a miss: the serve path falls back to
+ * the bundled manifest or live handler, and the trigger's stale check renders.
+ */
+export declare function readVerifiedStoredEntry(store: WritablePrerenderStore, key: PrerenderKey, params: Record<string, string>): Promise<PrerenderStoredEntry | null>;
+export {};

package/dist/types/prerender.d.ts

@@ -81,6 +81,26 @@ export interface PrerenderOptions {
      * ```
      */
     concurrency?: number;
+    /**
+     * Opt this route into on-demand (ISR-style) prerender refresh via
+     * `router.prerender()`. `true` uses the router-level `prerender` defaults; an
+     * object overrides them per route.
+     *
+     * Any truthy value opts in — a literal, a spread, or an imported const:
+     * producer retention in the production bundle is driven by the evaluated
+     * route manifest (the same source that sets the runtime od flag), not a
+     * textual scan of the call.
+     *
+     * @example
+     * ```typescript
+     * export const ProductPage = Prerender(
+     *   async () => [{ id: "featured" }],
+     *   async (ctx) => <Product data={await ctx.env.PRODUCTS.get(ctx.params.id)} />,
+     *   { onDemand: { ttl: 3600, tags: ({ params }) => [`product:${params.id}`] } },
+     * );
+     * ```
+     */
+    onDemand?: import("./prerender/on-demand.js").OnDemandOption;
 }
 /**
  * Context passed to Prerender() handlers at build time.
@@ -98,6 +118,13 @@ export interface BuildContext<TParams> {
      * changing build semantics.
      */
     dev: boolean;
+    /**
+     * True when this render is a requestless on-demand refresh driven by
+     * `router.prerender()` (rather than a build-time or dev prerender). The
+     * producer is still requestless — cookies/headers are unavailable — but
+     * `ctx.env` is the live trigger binding, not the shared build env.
+     */
+    onDemand: boolean;
     /**
      * Build-time environment bindings (KV, D1, etc.) supplied by the Vite plugin.
      * Only available when `buildEnv` is configured in rango() options.