@rangojs/router 0.18.0 → 0.19.0

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;

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

@@ -1,37 +1,81 @@
+/**
+ * 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. An attempt that consumed the whole budget is not
- * retried in place (shell-capture.ts noShellCauses), 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).
+ * 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. Here, in the leaf module, so
- * the testing helper `shellCacheKey` (testing/shell-status.ts) calls it
- * without pulling shell-serve.ts.
+ * 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
@@ -53,12 +97,12 @@ export declare function navigationShellKey(key: string): string;
  * (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 the original 2: under the REPLAY-ONLY capture model
- * (docs/design/ppr-shell-resume.md), the capture Flight render serializes ring-3
- * cached segments that are ALREADY serialized, so it emits the whole shell payload
- * in the first tick and the gate declares quiesce almost immediately (~a few ms).
- * On the old fresh-execution path the Flight dribbled out as handlers ran, so
- * Flight-quiet effectively meant "the shell has rendered" and 2 hops sufficed.
+ * 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
@@ -97,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;

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

@@ -6,29 +6,24 @@
  * from the route's `ppr` path option after the served response is built and calls
  * scheduleShellCapture. The capture then runs as a background task that re-derives
  * the page via `ctx.router.match()` under its OWN derived request context — fresh
- * handle store, `_shellCaptureRun: true` so loaders mask (loader-mask.ts) and every
- * loading() subtree postpones. The render is MIXED-CHAIN: cache()'d segments replay
- * from ring 3, uncached segments execute their handlers fresh. It drives the static
- * prerender to a quiescent shell, aborts to freeze the prelude + postponed state,
- * and stores the pair via putShell. Because it uses match() rather than the HTTP
- * pipeline, the middleware chain (auth, logging) never re-runs — it already ran for
- * the triggering request, and the derived context inherits its post-middleware
- * state (variables, cache store). Guarding is serve-time.
+ * handle store, `_shellCaptureRun: true` so live-lane loaders mask (loader-mask.ts)
+ * and postpone at their loading() or inline <Suspense> boundary. The match is
+ * MIXED-CHAIN: cache()'d segments replay from ring 3, uncached segments execute
+ * their handlers. The record-first step (settleCaptureRecord) waits for the
+ * handler layer, writes the doc record every HIT replays, and renders the
+ * capture's Flight payload from it; the static prerender runs to a quiescent
+ * shell, aborts to freeze the prelude + postponed state, and putShell stores the
+ * pair with the snapshot. Because it uses match() rather than the HTTP pipeline,
+ * the middleware chain (auth, logging) never re-runs — it already ran for the
+ * triggering request, and the derived context inherits its post-middleware state
+ * (variables, cache store). Guarding is serve-time.
  */
 import { type MatchResult } from "../types.js";
-import { SHELL_CAPTURE_MAX_WAIT_MS } from "./shell-capture-constants.js";
 import { type RequestContext, type RouteRecordWindow } from "../server/request-context.js";
 import { type HandleStore } from "../server/handle-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { HandlerContext } from "./handler-context.js";
 import type { SSRModule } from "./types.js";
-/**
- * Default capture budget. Canonical value, raise rationale, and ceiling math
- * live on the leaf module (shell-capture-constants.ts, importable from the ssr
- * graph too). Re-exported here so shell-build-manifest.ts's envelope math
- * keeps its existing import site and cannot drift from the capture.
- */
-export { SHELL_CAPTURE_MAX_WAIT_MS };
 /**
  * Delay before the in-place retry of a capture that produced no usable shell.
  *
@@ -80,6 +75,7 @@ declare const REFUSED_CAPTURE_MAX_MS = 60000;
  * docs/design/ppr-shell-resume.md ("Refused-capture backoff").
  */
 declare const REFUSED_CAPTURE_DEV_MAX_MS = 2000;
+/** True iff `key` is still inside its (exponential) backoff window. */
 declare function isCaptureBackedOff(key: string): boolean;
 /**
  * Record a refused/failed capture, escalating the backoff window exponentially up
@@ -187,15 +183,6 @@ export interface ShellCaptureDebugEvent {
      * same-or-higher priority. 0 = this capture starts immediately.
      */
     queueAhead?: number;
-    /**
-     * Ms the capture gate was HELD waiting for the slowest bake source — a
-     * top-level pushed handle promise or a bake-lane loader container — to
-     * settle, measured from capture start. Bake time is by-design shell latency
-     * (the hole doctrine: top-level promises bake), but it recurs on EVERY
-     * capture of the route and occupies the serialized queue; this field makes
-     * it attributable. Absent when nothing held the gate.
-     */
-    bakeWaitMs?: number;
     /**
      * How long the capture waited for its doc record: the handler layer's
      * promises, async server components and handle pushes settling, then the
@@ -265,19 +252,12 @@ export interface FlightCaptureGate {
  * closing (no holes) fires quiesce immediately for the DATA variant — the
  * TransformStream then closes the readable, so fizz completes with postponed null.
  *
- * `holdUntil` keeps the gate from FREEZING before shell material with real latency
- * has emitted. The hole doctrine bakes TOP-LEVEL pushed handle promises into the
- * shell (resolvedHandleStream awaits them before the handles row emits), but a
- * pushed promise that takes longer than the quiet window would otherwise be frozen
- * out — the handles row would never reach fizz and the prelude would come back
- * trivial. While `holdUntil` is pending, byte-quiet detection keeps running but the
- * gate neither fires nor freezes; once it resolves, the quiet counter restarts so a
- * burst of rows unblocked by it (the resolved handles row) is still captured. It
- * never delays a HOLE from postponing: holes are pending promises that emit no
- * bytes, so holding the gate open longer only ever admits shell rows. Bounded by
- * captureShellHTML's maxWaitMs like every other quiesce input.
+ * Nothing the shell bakes can still be pending here: settleCaptureRecord already
+ * waited for the top-level handle promises and the bake-lane loader containers
+ * before the capture's Flight render began, so the handles row and the baked
+ * loader rows emit at once and only the holes stay silent.
  */
-export declare function gateFlightForCapture(source: ReadableStream<Uint8Array>, quietHops?: number, holdUntil?: Promise<unknown>): FlightCaptureGate;
+export declare function gateFlightForCapture(source: ReadableStream<Uint8Array>): FlightCaptureGate;
 /**
  * The background shell-capture descriptor: everything the capture task needs to
  * store the shell. Built by the integrated PPR serve path (rsc-rendering.ts) from
@@ -324,16 +304,13 @@ export interface ShellCaptureDescriptor {
     tags?: string[];
     /**
      * Per-route capture settle budget in ms (`ppr.captureTimeout`, resolved by
-     * resolvePprConfig). Feeds captureShellHTML's maxWaitMs — the ONE deadline
-     * bounding the whole capture, so it covers BOTH the fizz prerender AND the
-     * deferred-material settle window (the handlesBaked/loader-container
-     * holdUntil that keeps the gate from freezing while top-level pushes are
-     * pending). Undefined = SHELL_CAPTURE_MAX_WAIT_MS (15_000).
+     * resolvePprConfig): the ONE deadline bounding the whole capture — the match,
+     * the record-first settle (settleCaptureRecord), then the fizz prerender with
+     * what is left (captureShellHTML's maxWaitMs). Undefined =
+     * SHELL_CAPTURE_MAX_WAIT_MS (15_000).
      */
     captureTimeout?: number;
     store?: SegmentCacheStore<any>;
-    /** Gates the concise per-attempt capture breadcrumbs (INTERNAL_RANGO_DEBUG). */
-    debug?: boolean;
     /**
      * Cap (serialized UTF-8 bytes) on the entry's capture data snapshot; over it
      * the snapshot is skipped and the shell stored without it (reported once per
@@ -402,22 +379,47 @@ export declare function capShellWindow(ttl: number, swr: number, record: Pick<Ro
  * - `no-shell`: captureShellHTML returned null because the prelude was unusable
  *   or its private capture abort landed before the shell completed, or the
  *   capture ran out of ppr.captureTimeout. Retried once in place, when no
- *   deadline ran out (noShellCauses).
+ *   deadline ran out (CaptureAttemptStats.noShellCause).
  * - `expired`: the route cache() record the capture read (not wrote) ran out
  *   before the store (capShellWindow null): it was near its end (its age,
  *   queue wait). Retried once in place, where a fresh match reads or renders
- *   a newer record; a second `expired`, or no hard-cap budget left for the
+ *   a newer record; an `expired` retry, or no hard-cap budget left for the
  *   retry, is terminal `no-shell` (backoff, warned once per route).
  */
 type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused" | "expired";
 /**
- * Per-attempt observability fields, filled along the capture path (barrier in
- * attemptCapture, the rest in captureAndStoreShell) and folded into the
- * attempt's {@link ShellCaptureDebugEvent} by runShellCapture. A plain mutable
- * bag, not a return value: captureAndStoreShell's outcome type stays a string
- * union its existing callers (producer B, tests) consume unchanged.
+ * What a capture task ends with (runShellCapture): a refusal and a terminal
+ * `expired` are `no-shell`, which the scheduler backs off.
  */
-type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "writeSettleMs" | "preludeBytes" | "snapshotBytes" | "snapshotSkipped" | "untaggedBake" | "storeWrite" | "bakeWaitMs" | "recordSettleMs" | "entryBytes">;
+type CaptureTaskOutcome = "stored" | "redirect" | "no-shell";
+/**
+ * One attempt's record, filled along the capture path (barrier and deadline
+ * causes in attemptCapture, the rest in captureAndStoreShell). runShellCapture
+ * folds the observability fields into the attempt's
+ * {@link ShellCaptureDebugEvent} and reads the rest to decide the retry and
+ * the warning. A plain mutable bag, not a return value: captureAndStoreShell's
+ * outcome type stays a string union producer B consumes unchanged.
+ */
+type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "writeSettleMs" | "preludeBytes" | "snapshotBytes" | "snapshotSkipped" | "untaggedBake" | "storeWrite" | "recordSettleMs" | "entryBytes"> & {
+    /**
+     * Why a no-shell attempt ran out of ppr.captureTimeout (the match, the
+     * handler output, or the prerender after them). A set cause skips the
+     * in-place retry: the attempt's match may still be running.
+     */
+    noShellCause?: string;
+    /**
+     * Dev only: component stacks of the tasks still pending at a no-shell
+     * attempt's abort, reported through prerender's onError (captureShellHTML's
+     * onAbortedTask).
+     */
+    pendingStacks?: string[];
+    /** The route cache() record an `expired` attempt ran out on. */
+    expired?: {
+        route: string;
+        record: RouteRecordWindow;
+        captureMs: number;
+    };
+};
 /**
  * Run the shell capture with a single in-place retry, then store the result.
  *
@@ -430,14 +432,16 @@ type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "write
  * attempt a short beat later usually completes the shell in the SAME background
  * task. That kills the old multi-request warmup where the caller had to re-issue
  * several HTTP requests before a capture stuck. We retry ONLY on `no-shell`
- * that did not run out of ppr.captureTimeout (noShellCauses); a genuine render
- * error is NOT retried — it propagates to scheduleShellCapture's
- * reportCacheError. See docs/design/ppr-shell-resume.md.
+ * that did not run out of ppr.captureTimeout (CaptureAttemptStats.noShellCause),
+ * and on `expired`; a genuine render error is NOT retried — it propagates to
+ * scheduleShellCapture's reportCacheError. See docs/design/ppr-shell-resume.md.
  *
- * `retryDelayMs` is a parameter (defaulting to the module const) so unit tests can
- * drive the retry without a real 400ms wall-clock wait.
+ * `request` and `url` are the capture's own identity (scheduleShellCapture
+ * strips a navigation-only capture's transport parameters). `retryDelayMs` is
+ * a parameter (defaulting to the module const) so unit tests can drive the
+ * retry without a real 400ms wall-clock wait.
  */
-declare function runShellCapture(ctx: HandlerContext<any>, request: Request, env: any, url: URL, reqCtx: RequestContext<any>, ssrModule: SSRModule, descriptor: ShellCaptureDescriptor, retryDelayMs?: number): Promise<CaptureAttemptOutcome>;
+declare function runShellCapture(ctx: HandlerContext<any>, request: Request, env: any, url: URL, reqCtx: RequestContext<any>, ssrModule: SSRModule, descriptor: ShellCaptureDescriptor, retryDelayMs?: number): Promise<CaptureTaskOutcome>;
 /**
  * What the record-first step produced ({@link settleCaptureRecord}):
  * - `record`: the doc record settled; `match` carries its fragments in place
@@ -486,17 +490,6 @@ export type CaptureRecordOutcome = {
  * scope's own write), and the deferred writes settle.
  */
 export declare function settleCaptureRecord(match: MatchResult, derivation: CaptureContextDerivation, capture: Pick<ShellCaptureDescriptor, "key">, deadline: number): Promise<CaptureRecordOutcome>;
-/**
- * Race `work` against an absolute deadline, keeping its value. The losing
- * work is not cancelled (a router match has no abort signal); callers that
- * lose do not start it again (runShellCapture skips its in-place retry).
- */
-export declare function withinDeadline<T>(work: Promise<T>, deadline: number): Promise<{
-    done: true;
-    value: T;
-} | {
-    done: false;
-}>;
 /**
  * The derived capture context and its fresh (mask-funneled) handle store,
  * shared by BOTH shell producers: the runtime background capture
@@ -530,27 +523,31 @@ export declare function deriveShellCaptureContext(reqCtx: RequestContext<any>, d
     url: URL;
 }): CaptureContextDerivation;
 /**
- * Seal handles, derive the quiesce signal, prerender + abort via the SSR module's
- * captureShellHTML, and store the result. Returns the attempt outcome (the caller
- * owns retry/warn decisions — this function no longer warns). Never throws out of
- * the store write: a failed putShell is routed through reportCacheError so the
- * background task stays best-effort, and the attempt still counts as `stored` (the
- * capture worked; only the store I/O failed). `ssrModule.captureShellHTML` MUST be
- * present (eligibility is checked before scheduling).
+ * Derive the quiesce signal, prerender + abort via the SSR module's
+ * captureShellHTML, and store the result. Runs after settleCaptureRecord (both
+ * producers), which sealed the capture's handle store (`reqCtx._handleStore`)
+ * and waited for everything the shell bakes. Returns the attempt outcome (the
+ * caller owns retry/warn decisions). Never throws out of the store write: a
+ * failed putShell is routed through reportCacheError so the background task
+ * stays best-effort, and the attempt still counts as `stored` (the capture
+ * worked; only the store I/O failed). `ssrModule.captureShellHTML` MUST be
+ * present (eligibility is checked before scheduling). `captureStartedAt` is the
+ * capture generation's start, stamped before the match (ShellCacheEntry
+ * .createdAt).
  *
  * A `no-shell` result from captureShellHTML is the only retryable outcome. Every
  * captureShellHTML error propagates to reportCacheError and is NOT retried. The
  * capture handler converts only its own private abort sentinel to null before this
  * layer sees it.
  */
-declare function captureAndStoreShell(ssrModule: SSRModule, rscStream: ReadableStream<Uint8Array>, handleStore: HandleStore, reqCtx: RequestContext<any>, capture: ShellCaptureDescriptor, stats?: CaptureAttemptStats, captureStartedAt?: number): Promise<Exclude<CaptureAttemptOutcome, "redirect">>;
+declare function captureAndStoreShell(ssrModule: SSRModule, rscStream: ReadableStream<Uint8Array>, reqCtx: RequestContext<any>, capture: ShellCaptureDescriptor, captureStartedAt: number, stats?: CaptureAttemptStats): Promise<Exclude<CaptureAttemptOutcome, "redirect">>;
 export { runShellCapture, captureAndStoreShell, delay, SHELL_CAPTURE_RETRY_DELAY_MS, };
 export { isCaptureBackedOff, markCaptureBackoff, clearCaptureBackoff, REFUSED_CAPTURE_BASE_MS, REFUSED_CAPTURE_MAX_MS, REFUSED_CAPTURE_DEV_MAX_MS, };
 /**
  * @internal Reset this module's per-isolate state: the capture stampede
- * guard, the refused-capture backoff, the recorded no-shell causes (which
- * also skip a timed-out capture's in-place retry), the once-per-key warnings
- * and the buffered debug events. Tests only (testing/serve-shell-request.ts
- * resetShellTestState), between requests, never while a capture runs.
+ * guard, the refused-capture backoff, the once-per-key warnings (the shell
+ * path's one registry), the stored-capture sequence and the buffered debug
+ * events. Tests only (testing/serve-shell-request.ts resetShellTestState),
+ * between requests, never while a capture runs.
  */
 export declare function resetShellCaptureStateForTests(): void;

package/dist/types/rsc/shell-serve.d.ts

@@ -16,12 +16,8 @@
  * intent cannot be honored — unlike an undeclared route, which is silent).
  */
 import { type EntryData } from "../server/context.js";
-import type { SearchParamsFilter } from "../cache/search-params-filter.js";
-import type { DocumentShellCacheEntry, ShellCacheEntry, ShellDocumentRead, ShellReadStats, ShellSnapshotFailure, ShellSnapshotRecord, SegmentCacheStore } from "../cache/types.js";
-/** Debug/status header the browser (and e2e assertions) can read: HIT | MISS. */
-export declare const SHELL_STATUS_HEADER = "x-rango-shell";
-/** Partial-navigation status header set only after captured PPR segments are consumed. */
-export declare const PPR_REPLAY_STATUS_HEADER = "x-rango-ppr-replay";
+import type { DocumentShellCacheEntry, ShellCacheEntry, ShellDocumentRead, ShellEntryHead, ShellReadStats, ShellSnapshotFailure, ShellSnapshotRecord, SegmentCacheStore } from "../cache/types.js";
+export { PPR_REPLAY_STATUS_HEADER, SHELL_STATUS_HEADER, buildShellKey, navigationShellKey, partitionShellKey, shellSearchSeed, } from "./shell-capture-constants.js";
 /**
  * Default shell ttl (seconds) for `ppr: true` and for a PartialPrerenderProps
  * that omits `ttl`.
@@ -79,22 +75,6 @@ export declare function normalizeCaptureTimeout(value: unknown): number | undefi
  * inheritance (declaring it on a layout is not supported — a follow-up).
  */
 export declare function resolvePprConfig(entry: EntryData | undefined | null): ResolvedPprConfig | null;
-/**
- * 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.
- */
-export declare function buildShellKey(url: URL, filter?: SearchParamsFilter): string;
-export { navigationShellKey, partitionShellKey, } from "./shell-capture-constants.js";
 /**
  * The forced-MISS query marker. A document HIT that cannot finish its tail
  * reloads the page with it (shellReloadScript); the serve gate renders a
@@ -122,35 +102,24 @@ export declare function withoutShellMissMarker(request: Request): Request | unde
  * did (a server that ignores the marker) it would return without touching
  * the page. window.stop() runs only when it reloads: it keeps the half-sent
  * Flight stream from being closed by DOMContentLoaded, which would throw
- * React's "Connection closed" (#412) before the reload lands. `nonce` is the
- * request's CSP nonce; a ppr route with an active nonce is axis 1
- * (rsc-rendering.ts shellServePlan), so on a HIT it is normally absent.
+ * React's "Connection closed" (#412) before the reload lands.
  */
-export declare function shellReloadScript(nonce?: string): string;
-/** An inline script a shell HIT's tail appends, carrying the CSP nonce if any. */
-export declare function inlineShellScript(body: string, nonce?: string): string;
+export declare function shellReloadScript(): string;
 /**
- * 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).
+ * An inline script a shell HIT's tail appends. It carries no CSP nonce: a
+ * request with an active per-request nonce never reaches a HIT
+ * (rsc-rendering.ts shellServePlan serves it on axis 1).
  */
-export declare function shellSearchSeed(url: URL, filter?: SearchParamsFilter): string;
+export declare function inlineShellScript(body: string): string;
 /**
  * Version gates for a stored shell: reactVersion AND buildVersion must both
  * match the running server. The postponed blob encodes hole positions against
  * one exact tree, so resuming it under a different React OR a different app
  * build tree-mismatches inside resume() — after the 200 + prelude committed,
  * with no recovery. Either mismatch is a miss: the recapture overwrites the
- * same key (self-healing) and the entry otherwise ages out via TTL. An entry
- * with no buildVersion (stored before the field existed) is a miss for the
- * same reason — its build is unknown, so it cannot be proven resumable.
+ * same key (self-healing) and the entry otherwise ages out via TTL.
  */
-export declare function isValidShellHit(entry: ShellCacheEntry, buildVersion: string): boolean;
+export declare function isValidShellHit(entry: Pick<ShellCacheEntry, "reactVersion" | "buildVersion">, buildVersion: string): boolean;
 /**
  * DOCUMENT-half structural gate and type narrowing, without decoding the
  * prelude: the prelude is a string and the postponed blob parses. Partial
@@ -167,7 +136,7 @@ export declare function isValidShellHit(entry: ShellCacheEntry, buildVersion: st
 export declare function hasIntactShellPayload(entry: ShellCacheEntry): entry is DocumentShellCacheEntry;
 /** A document shell ready to serve: its prelude decoded exactly once. */
 export interface ShellDocument {
-    entry: ShellCacheEntry;
+    entry: ShellEntryHead;
     prelude: Uint8Array;
     /** React's postponed state, parse-checked (null = DATA variant). */
     postponed: string | null;
@@ -176,7 +145,7 @@ export interface ShellDocument {
      * after a prelude-first read (SegmentCacheStore.readShellDocument), which
      * only the tail awaits.
      */
-    snapshot: ShellSnapshotRecord[] | undefined | Promise<ShellSnapshotRecord[] | undefined>;
+    snapshot: ShellSnapshotRecord[] | Promise<ShellSnapshotRecord[] | undefined>;
     /** Why a prelude-first read's snapshot is missing (ShellDocumentRead). */
     snapshotFailure?: Promise<ShellSnapshotFailure | undefined>;
     /** The prelude-first read's stats, when perf metrics are on. */
@@ -194,7 +163,8 @@ export interface ShellDocument {
  * A prelude-first `read` (SegmentCacheStore.readShellDocument) already carries
  * the raw bytes and a pending snapshot, so only its postponed blob is checked.
  */
-export declare function openShellDocument(entry: ShellCacheEntry, read?: Pick<ShellDocumentRead, "prelude" | "snapshot" | "snapshotFailure" | "stats">): ShellDocument | null;
+export declare function openShellDocument(entry: ShellCacheEntry): ShellDocument | null;
+export declare function openShellDocument(entry: ShellEntryHead, read: Pick<ShellDocumentRead, "prelude" | "snapshot" | "snapshotFailure" | "stats">): ShellDocument | null;
 /**
  * Prelude enqueue granularity. A streaming compressor in front of the worker
  * emits its first byte only after compressing the whole write it was handed:
@@ -228,7 +198,7 @@ export interface ShellTailTiming {
     snapshotReadMs?: number;
     /** Snapshot JSON.parse CPU (reads 0 on a deployed worker: see bytes). */
     snapshotParseMs?: number;
-    /** Snapshot records by family, e.g. `segment:1/item:5` (no commas: it rides a Server-Timing desc). */
+    /** Snapshot records by family, e.g. `segment:1/loader:2` (no commas: it rides a Server-Timing desc). */
     snapshotRecords?: string;
     /** Records the capture pruned from the snapshot, same format (ShellCacheEntry.prunedRecords). */
     snapshotPruned?: string;
@@ -251,7 +221,7 @@ export interface ShellTailTiming {
 }
 /**
  * Compact single-line form for the console log and the Server-Timing mirror's
- * `desc`: alphanumerics and `=`, `-`, `:`, `/` only (records=segment:1 pruned=item:5),
+ * `desc`: alphanumerics and `=`, `-`, `:`, `/` only (records=segment:1/loader:2 pruned=loader:1),
  * so no quoted-string escaping is needed. Offsets are from the commit; the
  * `-cpu` fields are CPU-only durations.
  */
@@ -317,7 +287,8 @@ export declare function partitionBuildShellCheckDone(pathname: string, routeName
  */
 export declare function notePartitionBuildShellCheck(pathname: string, routeName: string | undefined, found: boolean): void;
 /**
- * @internal Reset the serve path's once-per-key warnings and buffered tail
- * timings. Tests only (testing/serve-shell-request.ts resetShellTestState).
+ * @internal Reset the serve path's once-per-key warnings (the shell path's
+ * one registry), its build-shell probe memo and buffered tail timings. Tests
+ * only (testing/serve-shell-request.ts resetShellTestState).
  */
 export declare function resetShellServeStateForTests(): void;

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

@@ -32,6 +32,8 @@ export interface RscPayload {
         resolvedIds?: string[];
         /** Merged route params from the matched route */
         params?: Record<string, string>;
+        /** Matched route name, when named (transition({ when }) route names). */
+        routeName?: string;
         slots?: Record<string, SlotState>;
         /**
          * Intercept TARGET route names reachable from this location as a

package/dist/types/segment-system.d.ts

@@ -19,6 +19,13 @@ export interface RenderSegmentsOptions {
     forceAwait?: boolean;
     /** Seeded descendant client-route pending state for testing. */
     outletPending?: boolean;
+    /**
+     * This commit's transition({ when }) decision was false
+     * (browser/transition-when.ts): the navigation is urgent, so no segment
+     * animates. Every router <ViewTransition> stays in the tree with each class
+     * "none", so the element type never changes; keys never read this (#995).
+     */
+    transitionGatedOff?: boolean;
     /**
      * Intercept segments to inject into the tree.
      * These are parallel segments from intercept routes that need to be