@rangojs/router 0.17.0 → 0.19.0

package/dist/types/router/segment-resolution/loader-snapshot.d.ts

@@ -4,30 +4,27 @@
  *
  * A bake-lane loader (lane rule: see resolveLoaderData, loader-cache.ts)
  * executes during shell capture; its settled container bakes into the prelude
- * while nested promises postpone as holes. To keep a HIT's fresh
- * payload byte-identical to that frozen prelude, the capture pins the container
- * in the shell snapshot:
+ * while nested promises postpone as holes. To keep a HIT's fresh payload in
+ * agreement with that frozen prelude, the capture pins the container in the
+ * shell snapshot. Everything outside a hole is pinned; the one exception is a
+ * server-component element holding a promise, which is a hole as a whole (see
+ * elideLoaderContainer):
  *
- *   - elide:   deep-walk the settled container; a PENDING nested promise is a
- *              hole, replaced by {@link LOADER_HOLE_KEY} — and since
- *              loader-cache masks every nested thenable at capture
- *              ({@link maskNestedContainerThenables}), nested promises are
- *              ALWAYS pending here for new captures. The SETTLED-marker branch
- *              below is legacy: it fires only if a settled thenable reaches
- *              elide anyway, and the overlay keeps decoding SETTLED markers
- *              from pre-mask snapshots. The result is promise-free and
- *              Flight-serializable.
+ *   - elide:   deep-walk the settled container; a nested promise is a hole,
+ *              replaced by {@link LOADER_HOLE_KEY}. loader-cache masks every
+ *              nested thenable at capture ({@link maskNestedContainerThenables},
+ *              a never-settling promise), so the promise shape alone decides:
+ *              a value that settled in time does not bake (#692). The result
+ *              is promise-free and Flight-serializable.
  *   - overlay: on a HIT the loader runs fresh (only the loader body can mint
  *              the live nested promises), then the recorded container is laid
  *              over it: recorded paths win (they are what the prelude froze),
  *              hole-marker paths take the fresh run's value (the live hole),
- *              SETTLED-marker paths become Promise.resolve(pinned) — consumers
- *              wrote use(data.x) against a promise-shaped container, and
- *              handing them the raw value throws React #438 on every HIT (the
- *              storefront PDP regression) — and fresh-only paths pass through
- *              (they cannot contradict prelude bytes that never rendered them).
+ *              and fresh-only paths pass through (they cannot contradict
+ *              prelude bytes that never rendered them).
  */
-export { maskNestedContainerThenables } from "./mask-nested.js";
+import { maskNestedContainerThenables } from "./mask-nested.js";
+export { maskNestedContainerThenables };
 /**
  * Marker object standing in for a pending nested promise in a recorded loader
  * container. Shape-checked (not identity-checked) because the record round-trips
@@ -38,26 +35,6 @@ export interface LoaderHoleMarker {
     [LOADER_HOLE_KEY]: 1;
 }
 export declare function isLoaderHoleMarker(value: unknown): value is LoaderHoleMarker;
-/**
- * Marker wrapping the inlined value of a NESTED promise that settled during
- * capture. The value baked (physics), but the container key was a promise —
- * the overlay must hand consumers a Promise.resolve(value), not the raw value,
- * or an unconditional use(data.x) throws React #438 on every HIT. The ROOT
- * container is never wrapped: loader-cache overlays against the awaited fresh
- * container value.
- */
-export declare const LOADER_SETTLED_KEY: "$rangoLoaderSettled";
-export interface LoaderSettledMarker {
-    [LOADER_SETTLED_KEY]: 1;
-    value: unknown;
-    /**
-     * Present when the pinned subtree contains hole markers. Computed once at
-     * capture (elide already visits every node) so the per-HIT overlay never
-     * rescans the pinned structure to pick its rehydration path.
-     */
-    holes?: 1;
-}
-export declare function isLoaderSettledMarker(value: unknown): value is LoaderSettledMarker;
 export type ElideResult = {
     state: "ok";
     value: unknown;
@@ -66,25 +43,33 @@ export type ElideResult = {
     state: "rejected";
 };
 /**
- * Deep-elide a settled bake-lane container for recording. Settled nested
- * promises pin their value behind a settled marker (they baked, but consumers
- * hold a promise-shaped key); pending ones become hole markers; a REJECTED
- * nested promise poisons the record (error UI must never bake into a shared
- * shell) — the caller refuses the capture. Only plain objects/arrays are
- * traversed; anything else (Date, Map, class instance) is a pinned leaf.
- * Cycles are cut as pinned references (best effort — Flight rejects true
- * cycles later regardless).
+ * Deep-elide a settled bake-lane container for recording. Nested promises
+ * become hole markers: the capture masked each of them (never settles), so
+ * it postponed as a hole. A REJECTED container poisons the record (error UI
+ * must never bake into a shared shell) — the caller refuses the capture.
+ * Plain data objects, arrays and the props of host, Suspense/Fragment and
+ * client-reference elements are
+ * traversed copy-on-write (an element through cloneElementWithProps); a shared
+ * subtree or a cycle resolves to the same elided result. An element Flight
+ * renders by calling user code (see rendersOnServer) is a leaf, or ONE hole
+ * marker when a thenable sits anywhere in its props: the pin encode calls that
+ * component, so a marker inside its props would reach it. Anything else
+ * (Date, Map, class instance, lazy node) is a pinned leaf.
  *
  * The ROOT container promise-chain unwraps with NO marker: loader-cache
  * overlays against the AWAITED fresh container, so the recorded root must be
  * the unwrapped structure. Everything below it goes through elideNested.
  */
-export declare function elideLoaderContainer(value: unknown, seen?: Set<object>): Promise<ElideResult>;
+export declare function elideLoaderContainer(value: unknown, seen?: Map<object, ElideResult>): Promise<ElideResult>;
 /**
  * Overlay a recorded (elided) container onto the fresh run's container for a
  * shell HIT. Recorded wins per path; hole markers take the fresh value (the
  * live nested promise); fresh-only object keys pass through. Where the shapes
  * disagree structurally, recorded wins wholesale — it is what the prelude
- * froze, and parity beats freshness inside the shell.
+ * froze, and parity beats freshness inside the shell. Copy-on-write: a
+ * recorded subtree without markers comes back by identity. A recorded element
+ * is rebuilt through cloneElementWithProps only at its marker paths, so its
+ * other props stay pinned; props the fresh element adds do not pass through
+ * (the prelude rendered the element without them).
  */
 export declare function overlayLoaderContainer(fresh: unknown, recorded: unknown): unknown;

package/dist/types/router/segment-resolution/mask-nested.d.ts

@@ -1,13 +1,16 @@
 /**
- * Capture-side nested-thenable masking — the mechanism behind "nested-promise
- * shape is the liveness declaration" for BOTH bake-lane loader containers
- * (loader-cache.ts) and pushed handle containers (the capture handle store's
- * push wrap in rsc/shell-capture.ts).
+ * Capture-side nested thenables. Masking is the mechanism behind "nested-
+ * promise shape is the liveness declaration" for the loader lane: bake-lane
+ * loader containers (loader-cache.ts) and DSL loader handle pushes (the
+ * capture handle store's push wrap in rsc/shell-capture.ts). Handler handle
+ * pushes are handler output and bake: the capture waits for their nested
+ * promises instead (settleNestedThenables).
  *
  * Deliberately a LEAF module: loader-mask (the other natural home) imports
  * request-context, so any funnel importing the mask from there inherits that
- * graph. This module imports only is-thenable.
+ * graph. This module imports only is-thenable and react.
  */
+import { type ReactElement } from "react";
 /**
  * A promise that never settles — the masked stand-in for a per-request value
  * during shell capture. The consuming Suspense subtree suspends forever, so
@@ -18,11 +21,63 @@
  */
 export declare function createMaskedLoaderPromise<T = unknown>(): Promise<T>;
 /**
- * Deep-copy a container with every NESTED thenable replaced by a masked
+ * A data object the container walks descend into: prototype Object.prototype
+ * or null, and no symbol `$$typeof`. React elements, lazy nodes and references
+ * are plain objects too, told apart by that symbol (Flight switches on it).
+ * They are React's, not data: an element's dev-only fields (`_debugStack`,
+ * `_debugTask`, `_debugInfo`, `ref`) are non-enumerable, so a key-by-key copy
+ * drops them and dev Flight refuses it ("Attempted to render <x> without
+ * development properties", issue #942).
+ */
+export declare function isPlainDataObject(value: unknown): value is Record<string, unknown>;
+/**
+ * cloneElement with only the given props replaced, keeping React's dev key
+ * validation. React 19 dev cloneElement resets `_store.validated`, so a
+ * keyless child of a static children list (validated at creation) would warn
+ * "Each child in a list should have a unique key" once cloned. Pass only the
+ * props that change: cloneElement re-parents the element (owner) when its
+ * config carries `ref`.
+ */
+export declare function cloneElementWithProps(element: ReactElement, props: Record<string, unknown>): ReactElement;
+/**
+ * Resolves once `value` and every thenable reachable from it through plain
+ * data objects, arrays and React element props has settled, following what
+ * each thenable resolves to. A rejection counts as settled: the consumer that
+ * encodes the value reports it. Other objects are leaves (the same walk as
+ * maskNestedContainerThenables), so a promise inside a Map is not waited for.
+ * An element is walked through its props only (`<X data={promise} />` in a
+ * handle value is handler output too), never its owner or type, and is never
+ * rebuilt: nothing is copied, only awaited.
+ *
+ * The capture waits on this for HANDLER handle pushes (shell-capture.ts):
+ * handler output is baked, so its promises must settle before the doc record
+ * encodes the handles every HIT replays.
+ */
+export declare function settleNestedThenables(value: unknown): Promise<void>;
+/**
+ * True when `value` is a thenable or holds one where the capture's loader
+ * push funnel masks it (maskNestedContainerThenables): through plain data
+ * objects, arrays and React element props. Such a push stays out of a shell's
+ * record and reaches a HIT only from a run of its loader there, so a HIT
+ * keeps it; a push without one is the record's (HandleStore.pushRestored).
+ */
+export declare function holdsThenable(value: unknown): boolean;
+/**
+ * Optional single-walk report for maskNestedContainerThenables: `thenable`
+ * flips true when the walk masked at least one thenable. The capture push
+ * funnel reads it for a loader push: a container with a masked nested
+ * promise keeps its loader tag, so the handle encode never waits on a mask.
+ * Same single-pass shape as elideLoaderContainer's `hasHole`.
+ */
+export interface MaskReport {
+    thenable: boolean;
+}
+/**
+ * Copy a container with every NESTED thenable replaced by a masked
  * (never-resolving) promise. Applied during shell capture to (a) bake-lane
- * loader containers (loader-cache.ts) and (b) pushed handle containers
- * (shell-capture.ts capture store push wrap) — the two rango-owned funnels
- * where consumers declare per-request data by promise SHAPE.
+ * loader containers (loader-cache.ts) and (b) DSL loader handle pushes
+ * (shell-capture.ts capture store push wrap) — the rango-owned funnels where
+ * a loader declares per-request data by promise SHAPE.
  *
  * Why: a nested promise that happened to SETTLE before the capture's quiet
  * window closed used to bake its value into the SHARED shell (and, for
@@ -34,20 +89,14 @@ export declare function createMaskedLoaderPromise<T = unknown>(): Promise<T>;
  * Masking makes the consuming subtree postpone as a hole no matter when the
  * promise settles: liveness by declaration, not by racing the window.
  *
- * Only plain objects/arrays are traversed; other values are leaves. The INPUT
- * IS NEVER MUTATED — handler-side loader consumption (the consumption-lane
- * rule, semantic-matrix PPR3) shares the raw container and must keep real
- * values. Cycles are preserved as cycles in the copy.
+ * Plain data objects, arrays and React element props are traversed: JSX
+ * carrying a promise (`<Reviews data={fetchReviews()} />`) declares
+ * per-request data the same way a plain container does. Other values, lazy
+ * nodes included, are leaves. Copy-on-write: a subtree without a thenable
+ * comes back by identity, so an element is rebuilt only when its props hold
+ * one, and then through cloneElementWithProps, which keeps its type, key,
+ * owner, dev fields and key validation. The INPUT IS NEVER MUTATED: a handler
+ * that reads the loader (`ctx.use`) reads the raw container and must keep
+ * real values. Cycles are preserved as cycles in the copy.
  */
-/**
- * Optional single-walk report for maskNestedContainerThenables: `thenable`
- * flips true when the walk masked at least one thenable. The shell fast path
- * reads it at handle-push time — a pushed container with a nested thenable
- * declares per-request data, and a shell entry whose HANDLER layer made such
- * a declaration cannot be served handler-free (the hole would never fill).
- * Same single-pass shape as elideLoaderContainer's `hasHole`.
- */
-export interface MaskReport {
-    thenable: boolean;
-}
 export declare function maskNestedContainerThenables(value: unknown, seen?: Map<object, unknown>, report?: MaskReport): unknown;

package/dist/types/router/segment-resolution/view-transition-default.d.ts

@@ -19,9 +19,11 @@ import type { EntryData } from "../../server/context";
  * (or "auto") value is left untouched because it already means "wrap" at the
  * gate, which also avoids needless object allocation and payload growth.
  *
- * `when`: a server-only predicate. It is STRIPPED from the returned config (a
- * function cannot cross Flight or the segment cache). PPR routes evaluate it
- * from the manifest before the pipeline; other routes record it here for the
- * existing post-handler gate. Used by both fresh and revalidation resolution.
+ * `when`: a client reference the server never calls. It is STRIPPED here so no
+ * segment record (segment cache, prerender artifact, shell snapshot) carries
+ * it: those stores JSON-serialize the config and would silently drop it on
+ * some stores and keep it on others. rsc/attach-transition-when.ts attaches it
+ * from the route definition right before Flight instead. Used by both fresh
+ * and revalidation resolution.
  */
-export declare function applyViewTransitionDefault(transition: EntryData["transition"], viewTransitionDefault: "auto" | false | undefined, segmentId?: string): EntryData["transition"];
+export declare function applyViewTransitionDefault(transition: EntryData["transition"], viewTransitionDefault: "auto" | false | undefined): EntryData["transition"];

package/dist/types/router/transition-when.d.ts

@@ -1,13 +1,27 @@
 import { type EntryData } from "../server/context.js";
 import type { RequestContext } from "../server/request-context.js";
-import type { TransitionWhenContext } from "../types/segments.js";
-export type TransitionWhenErrorReporter = (error: unknown, segmentId: string) => void;
-export declare function createTransitionWhenContext<TEnv>(ctx: RequestContext<TEnv>, target?: {
-    params: Record<string, string>;
+import type { TransitionWhenSite } from "../transition-when-ref.js";
+import type { TransitionWhenFn } from "../types/segments.js";
+/** A matched entry's transition({ when }) and where it was declared. */
+export interface TransitionWhenRecord {
+    readonly when: TransitionWhenFn;
+    readonly site: TransitionWhenSite;
+}
+/**
+ * Record the transition({ when }) references of a matched entry chain, keyed
+ * by the segment id each entry resolves to. The server never calls them:
+ * rsc/attach-transition-when.ts attaches them to the payload's segments right
+ * before Flight, and the browser decides (browser/transition-when.ts).
+ *
+ * Recorded from the static route definition on EVERY match (fresh, cache hit,
+ * prerender, PPR replay) because stored segments never carry them:
+ * applyViewTransitionDefault strips `when` at resolution, since segment stores
+ * JSON-serialize the transition config (dropping a function on some stores,
+ * keeping it by reference on others). Segment ids follow resolution: an
+ * entry's shortCode, and `${owner.shortCode}.${slot}` for a rendered parallel
+ * slot.
+ */
+export declare function recordTransitionWhenRefs<TEnv>(entries: readonly EntryData[] | undefined, ctx: RequestContext<TEnv>, route?: {
     routeName?: string;
-}): TransitionWhenContext<Record<string, string>, TEnv>;
-/** Evaluate server-only transition gates before handlers on a PPR route. */
-export declare function evaluatePprTransitionWhen<TEnv>(entries: EntryData[], ctx: RequestContext<TEnv>, target: {
-    params: Record<string, string>;
-    routeName?: string;
-}, reportError: TransitionWhenErrorReporter): void;
+    pattern?: string;
+}): void;

package/dist/types/rsc/attach-transition-when.d.ts

@@ -0,0 +1,18 @@
+import type { MatchResult } from "../types.js";
+import type { getRequestContext } from "../server/request-context.js";
+/**
+ * Attach transition({ when }) references to a payload's segments, right before
+ * Flight. Returns a copy for every segment it changes: the input segments may
+ * be the records a cache, prerender, or shell snapshot holds.
+ *
+ * Only a segment that carries `transition` gets its predicate. The config
+ * itself never varies per request, so the segment key and the <ViewTransition>
+ * wrapper depend only on the route definition (#995); the browser decides for
+ * every committed segment, kept ones included (#989).
+ *
+ * Render-time backstop for an invalid `when` that route discovery did not see
+ * (a route evaluated lazily at runtime): it throws the discovery error. A
+ * plain function reaching Flight would otherwise fail with React's generic
+ * "Functions cannot be passed directly to Client Components", or be dropped.
+ */
+export declare function attachTransitionWhen(segments: MatchResult["segments"], ctx: ReturnType<typeof getRequestContext>): MatchResult["segments"];

package/dist/types/rsc/full-payload.d.ts

@@ -12,6 +12,7 @@ import type { RscPayload } from "./types.js";
 import type { HandlerContext } from "./handler-context.js";
 import type { RequestContext } from "../server/request-context.js";
 import type { HandleStore } from "../server/handle-store.js";
+import type { Theme } from "../theme/types.js";
 /**
  * Build the metadata payload for a full (non-partial) document render.
  *
@@ -20,3 +21,23 @@ import type { HandleStore } from "../server/handle-store.js";
  *   derived-context store.
  */
 export declare function buildFullPayload(m: MatchResult, ctx: HandlerContext<any>, url: URL, reqCtx: RequestContext<any>, handleStore: HandleStore): RscPayload;
+/**
+ * The theme a document payload carries as `metadata.initialTheme` (the
+ * ThemeProvider's first state), read with no identity guard: it is the
+ * router's own read, not handler code (#971).
+ *
+ * A render other visitors may be served carries the no-cookie default, not
+ * the rendering visitor's theme: a shell capture, and a render the document
+ * cache runs whose response opted in before next() (documentCacheStoresRender,
+ * #978). The shell, its ShellCacheEntry.initialTheme and the stored document
+ * serve every visitor, and ThemeProvider re-syncs only from an explicitly
+ * stored theme, so a visitor with none kept the first visitor's
+ * `useTheme().theme` for the page's lifetime. A visitor with a stored theme
+ * gets it pre-paint (theme script) and in the provider after mount.
+ *
+ * Any other render carries the visitor's theme (the unmatched-route 404 reads
+ * it without this function, rsc/handler.ts); when that differs from the
+ * default it marks `_payloadVisitorTheme`, and the document cache does not
+ * store the response.
+ */
+export declare function payloadInitialTheme(reqCtx: Pick<RequestContext<any>, "_themeConfig" | "_shellCaptureRun" | "_readTheme" | "_documentCacheRender" | "_payloadVisitorTheme" | "res">): Theme | undefined;

package/dist/types/rsc/handler.d.ts

@@ -6,4 +6,4 @@
  */
 import type { CreateRSCHandlerOptions } from "./types.js";
 import type { RouterRequestInput } from "../router/router-interfaces.js";
-export declare function createRSCHandler<TEnv = unknown, TRoutes extends Record<string, string> = Record<string, string>>(options: CreateRSCHandlerOptions<TEnv, TRoutes>): (request: Request, input?: RouterRequestInput<TEnv>) => Promise<Response>;
+export declare function createRSCHandler<TEnv = unknown, TRoutes extends Record<string, string> = Record<string, string>>(options: CreateRSCHandlerOptions<TEnv, TRoutes>): (incomingRequest: Request, input?: RouterRequestInput<TEnv>) => Promise<Response>;

package/dist/types/rsc/response-cache-serve.d.ts

@@ -3,28 +3,27 @@
  *
  * Owns the single response-cache contract — cache-scope resolution from the
  * matched entry tree, condition eval, key resolution (route key() > store
- * keyGenerator > default), tag resolution, pre-handler-callback timing, and the
- * fresh-hit / SWR-revalidate / miss-write branches — for BOTH the production
+ * keyGenerator > default, CacheScope.resolveKeyFrom), tag resolution,
+ * pre-handler-callback timing, and the fresh-hit / SWR-revalidate /
+ * miss-write branches — for BOTH the production
  * response-route handler (rsc/response-route-handler.ts) and the dispatch testing
  * primitive (testing/dispatch.ts), so the two can never drift.
  *
  * Plugin-rsc hazard: cache-scope.ts pulls @vitejs/plugin-rsc (via segment-codec),
  * which the non-Vite unit-test runner cannot resolve, and this module is on the
- * testing barrel's EAGER graph (dispatch imports it). So `createCacheScope` and
- * `resolveCacheTags` are NOT imported here at runtime — they are INJECTED by the
- * caller (production imports them statically; dispatch lazy-imports them only once
- * a response route matches). The only runtime imports here are plugin-rsc-free
+ * testing barrel's EAGER graph (dispatch imports it). So `createCacheScope` is
+ * NOT imported here at runtime — it is INJECTED by the caller (production
+ * imports it statically; dispatch lazy-imports it only once a response route
+ * matches). The only runtime imports here are plugin-rsc-free
  * (helpers' isCacheableStatus/finalizeResponse, traverseBack); cache-scope is a
  * type-only import (erased at build).
  */
 import type { CacheScope } from "../cache/cache-scope.js";
-import type { PartialCacheOptions } from "../types.js";
-import type { RequestContext } from "../server/request-context.js";
+import { type RequestContext } from "../server/request-context.js";
 import type { EntryCacheConfig, EntryData } from "../server/context.js";
-/** Injected cache-scope builders (kept off this module's runtime import graph). */
+/** Injected cache-scope builder (kept off this module's runtime import graph). */
 export interface CacheScopeDeps {
     createCacheScope: (config: EntryCacheConfig | undefined, parent?: CacheScope | null) => CacheScope | null;
-    resolveCacheTags: (config: PartialCacheOptions | false, ctx: RequestContext | undefined) => string[] | undefined;
 }
 export interface ServeResponseRouteWithCacheArgs {
     reqCtx: RequestContext;
@@ -40,7 +39,11 @@ export interface ServeResponseRouteWithCacheArgs {
  * applies (no scope, disabled, condition false, or store lacks get/putResponse)
  * so the caller falls through to a plain `executeHandler()` run.
  *
- * Must run inside runWithRequestContext (reads the ambient request context via
- * the helpers and reqCtx.waitUntil for background writes).
+ * Must run inside runWithRequestContext for `reqCtx` (reads the ambient
+ * request context via the helpers and reqCtx.waitUntil for background writes).
+ * Outside it, the route runs uncached: the scope resolves `key()`, a store
+ * keyGenerator and `condition()` against the ambient context, and without
+ * it a keyGenerator was skipped and the entry landed on the broad default
+ * key.
  */
 export declare function serveResponseRouteWithCache(args: ServeResponseRouteWithCacheArgs): Promise<Response | undefined>;

package/dist/types/rsc/shell-build-manifest.d.ts

@@ -31,10 +31,8 @@ export interface BuildShellEntry {
     entry: ShellCacheEntry;
     /** Resolved ppr ttl (seconds) — drives staleness/recapture, never expiry. */
     ttl: number;
-    swr?: number;
     /** The putShell-barrier tag union baked at build (static + recorded). */
     tags?: string[];
-    routeName: string;
 }
 interface ShellManifestModule {
     /** Manifest key (pathname — see shell-manifest-key.ts) -> asset specifier. */
@@ -46,7 +44,10 @@ interface ShellManifestModule {
 declare global {
     var __loadShellManifestModule: (() => Promise<ShellManifestModule>) | undefined;
 }
-/** Reset the memoized manifest (unit tests swap the global loader). */
+/**
+ * Reset the memoized manifest (unit tests swap the global loader) and the
+ * shell path's once-per-key warnings, the tag-check one included.
+ */
 export declare function resetBuildShellManifestForTests(): void;
 export interface BuildShellHit {
     entry: DocumentShellCacheEntry;
@@ -73,6 +74,14 @@ export interface DevShellLookup {
     /** Resolved `ppr.captureTimeout` (ms) — the endpoint's capture honors it. */
     captureTimeout?: number;
 }
+/**
+ * Whether a build-time shell exists for `pathname` (the caller checks the
+ * request is search-less, like the entries lookupBuildShell serves): a
+ * manifest entry for the path in production, a Prerender route in dev. No
+ * asset load and no dev capture: it only decides whether a request that
+ * cannot read the build shell deserves a warning.
+ */
+export declare function hasBuildShell(pathname: string, dev?: DevShellLookup): Promise<boolean>;
 /**
  * Look up the baked shell entry for a request, applying every serve gate:
  * search-less requests only (the build captured the bare pathname; a

package/dist/types/rsc/shell-capture-constants.d.ts

@@ -1,30 +1,121 @@
+/**
+ * React-free leaf of the PPR shell path: its constants, the shell key
+ * builders, the status header names and bypass reasons, and the once-per-key
+ * warning registry. The ssr graph (ssr/index.tsx), the testing barrels
+ * (testing/shell-status.ts) and cookie-store.ts import from here without
+ * pulling the capture orchestration module or shell-serve.ts (React).
+ */
+import type { SearchParamsFilter } from "../cache/search-params-filter.js";
 /**
  * Default upper bound on the capture prerender wait before forcing the abort
  * that freezes the shell — the ONLY wall-clock on the capture path, and a
  * pathological guard: it should never fire once the caller's `quiesce` is a
  * task-quantized, frozen-byte signal (the capture gate in shell-capture.ts).
- *
- * Leaf module on purpose (imports nothing): shell-capture.ts re-exports it
- * (single import site for the rsc graph — shell-build-manifest.ts sizes the
- * dev fetch envelope from that re-export) and ssr/index.tsx uses it as
- * captureShellHTML's own fallback; the ssr graph must not pull the capture
- * orchestration module for one number.
+ * ssr/index.tsx uses it as captureShellHTML's own fallback.
  *
  * 15s, raised from 5s: captures are background work (waitUntil), so the budget
  * costs latency-to-HIT only — never a served response — and 5s spuriously
  * refused legitimately-slow deferred shell material (a real storefront's meta
  * chains settle at ~7s). Ceiling math: workerd's waitUntil lifetime is ~30s
- * past response completion, and a guaranteed two-attempt envelope needs
- * 2x budget + the in-place retry delay + store I/O, i.e. budget <= ~14s. The
- * 15s default deliberately sits just past that: attempt 1 always gets its
- * full 15s, but when it consumed the whole budget the in-place RETRY may be
- * truncated by the platform kill on workerd — degrading to the existing
- * best-effort contract (the key stays MISS; a later request re-captures).
+ * past response completion. An attempt that consumed the whole budget is not
+ * retried in place (shell-capture.ts CaptureAttemptStats.noShellCause), so
+ * the envelope is one budget plus store I/O; the retry follows only an
+ * attempt that ended early (a cold-module abort). Past the ceiling the
+ * platform kill degrades to the existing best-effort contract (the key stays
+ * MISS; a later request re-captures).
  * Node/dev and build-time captures have no waitUntil ceiling. The per-route
  * `ppr.captureTimeout` knob remains for tightening below the default. See
  * docs/design/ppr-shell-resume.md (Cost model).
  */
 export declare const SHELL_CAPTURE_MAX_WAIT_MS = 15000;
+/** Debug/status header on a ppr document response: `HIT` | `MISS`. */
+export declare const SHELL_STATUS_HEADER: string;
+/**
+ * Partial-navigation replay status header, set only after the captured
+ * segment record was consumed (`HIT`) or with the reason it was not.
+ */
+export declare const PPR_REPLAY_STATUS_HEADER: string;
+/**
+ * Bounded reasons a partial request to a ppr route falls open to the ordinary
+ * match (`x-rango-ppr-replay: BYPASS; reason=<reason>`). One list for the
+ * producer (rsc-rendering.ts) and the parser (testing/shell-status.ts): a
+ * reason the parser does not list parses as null.
+ */
+export declare const PPR_REPLAY_BYPASS_REASONS: readonly ["method", "dynamic", "nonce", "store-unavailable", "passive-read-unsupported", "no-navigation-context", "prerender-store", "intercept", "cache-disabled", "read-error", "no-entry", "invalid-version", "corrupt-entry", "no-segment-snapshot", "snapshot-miss", "explicit-cache-hit"];
+/** One of {@link PPR_REPLAY_BYPASS_REASONS}. */
+export type PprReplayBypassReason = (typeof PPR_REPLAY_BYPASS_REASONS)[number];
+/**
+ * The shell key's search portion (`?`-prefixed sorted search with the
+ * cache.searchParams filter applied, or "") — ALSO the string the capture and
+ * resume SSR renders seed their store location with (SSRRenderOptions.search
+ * / ShellCaptureOptions.search / ShellResumeOptions.search). Search is part
+ * of shell identity, so static-part `useSearchParams` reads render exactly
+ * what the key names; deriving seed and key from this one helper is what
+ * keeps capture, resume, and lookup byte-agreed (drift = replay mismatch or
+ * permanent MISS).
+ */
+export declare function shellSearchSeed(url: URL, filter?: SearchParamsFilter): string;
+/**
+ * Shell cache key: host + pathname + sorted search + a `:shell` namespace suffix
+ * (so it can never collide with a document-cache key; the store further isolates
+ * the shell family internally).
+ *
+ * The key includes the request HOST: in a multi-tenant host-router deployment
+ * (one worker, one shared KV/runtime-cache store) a host-less key would serve
+ * tenant A's captured shell to tenant B's users.
+ *
+ * `filter` is the request's compiled `cache.searchParams` config
+ * (ctx._searchParamsFilter): excluded params collapse onto one shell slot.
+ * Callers on the serve/capture path MUST pass it -- key drift between capture
+ * and lookup makes every shell request a permanent miss. The testing helper
+ * `shellCacheKey` (testing/shell-status.ts) builds its key with it too.
+ */
+export declare function buildShellKey(url: URL, filter?: SearchParamsFilter): string;
+/**
+ * The shell key for one request partition (cache-scope.ts
+ * resolveShellPartition): the route cache() `key()` or store keyGenerator
+ * result that partitions the route's record partitions its shell too, so
+ * each partition captures and serves its own.
+ *
+ * The partition is URI-encoded: it is request-derived, and raw it could end
+ * in a suffix another key is built with (navigationShellKey), so a partition
+ * `gold:navigation` named gold's navigation entry and its document shell
+ * replayed to gold's navigations. Encoded, it holds no `:` or `|`.
+ */
+export declare function partitionShellKey(key: string, partition: string): string;
+/**
+ * The navigation-only entry beside a document shell key (a cold partial
+ * request's capture, rsc-rendering.ts). A suffix after the (encoded)
+ * partition: partitionShellKey keeps the two unambiguous.
+ */
+export declare function navigationShellKey(key: string): string;
+/**
+ * Fixed number of macrotask hops between `quiesce` resolving and the abort. These
+ * give React's fizz worker turns to flush the settled shell into the prelude and
+ * mark still-pending boundaries as POSTPONED (rather than errored) before
+ * controller.abort() lands. Not a wall-clock wait. Taken by captureShellHTML
+ * (ssr/index.tsx) and by the testing SSR stub (testing/serve-shell-request.ts),
+ * so the stub freezes the same Flight the real capture would.
+ *
+ * Why 16 and not 2: the capture's Flight input is the doc record's stored
+ * fragments (settleCaptureRecord, shell-capture.ts), already serialized, so the
+ * render emits the whole shell payload in the first tick and the gate declares
+ * quiesce within a few ms, before fizz has rendered the shell to <body>. When
+ * the capture Flight dribbled out as handlers ran, Flight-quiet meant "the shell
+ * has rendered" and 2 hops sufficed.
+ *
+ * Hops alone are NOT render-readiness: fizz cannot emit even <html> until the
+ * payload root settles, nor complete a shell whose client components are
+ * still loading — real module-runner I/O in dev (100ms+ cold), which no fixed
+ * count of near-zero-cost task hops can buy. captureShellHTML therefore
+ * awaits the payload-settled signal (SsrRootOptions.onPayloadSettled) and
+ * then the client-reference loads in flight in the isolate (captureClientLoads),
+ * deadline-bounded, between quiesce and these hops; the hops then only flush
+ * the settled tree and mark pending boundaries POSTPONED. Still task-based
+ * (masked loaders never emit, so more hops never lets a hole settle). Bounded
+ * by maxWaitMs end to end.
+ */
+export declare const POST_QUIESCE_TASK_HOPS = 16;
 /**
  * Hard cap on one capture TASK — runShellCapture end to end (both attempts +
  * the in-place retry delay). SHELL_CAPTURE_MAX_WAIT_MS arms only inside
@@ -50,3 +141,16 @@ export declare const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25000;
  * rule: resolveLoaderData (router/segment-resolution/loader-cache.ts).
  */
 export declare const PPR_LANE_HINT: string;
+/** Whether {@link warnOnce} already warned for `scope` and `key`. */
+export declare function hasWarnedOnce(scope: string, key: string): boolean;
+/**
+ * `console.warn(message())` once per `scope` and `key`; `message` is built only
+ * when it prints. Returns true when it warned.
+ */
+export declare function warnOnce(scope: string, key: string, message: () => string): boolean;
+/**
+ * @internal Forget every once-per-key shell warning. Tests only: the capture,
+ * serve and build-shell resets (testing/serve-shell-request.ts
+ * resetShellTestState) call it.
+ */
+export declare function resetShellWarningsForTests(): void;