@rangojs/router 0.17.0 → 0.19.0

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, 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`.
@@ -80,53 +76,56 @@ export declare function normalizeCaptureTimeout(value: unknown): number | undefi
  */
 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.
+ * The forced-MISS query marker. A document HIT that cannot finish its tail
+ * reloads the page with it (shellReloadScript); the serve gate renders a
+ * request carrying it on axis 1, with no shell read and no capture, so the
+ * reload can never be a HIT that degrades again. The handler drops it from
+ * the request on entry (withoutShellMissMarker) and keeps only the flag
+ * (RequestContext._shellForcedMiss), so nothing else sees it.
+ */
+export declare const SHELL_MISS_PARAM: string;
+/**
+ * The request without the forced-MISS marker, or undefined when it carries
+ * none. The handler calls it before anything reads the request: left in, the
+ * marker reached `ctx.request.url`, `originalUrl`, middleware, and the SSR
+ * search seed (so `useSearchParams` rendered it), and a `"use cache"` key
+ * built from the request URL was never read again. GET and HEAD only: the
+ * reload is a navigation, and a request with a body cannot be re-created
+ * without re-streaming it. The substring test keeps the URL parse off every
+ * other request.
  */
-export declare function buildShellKey(url: URL, filter?: SearchParamsFilter): string;
+export declare function withoutShellMissMarker(request: Request): Request | undefined;
 /**
- * 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).
+ * The inline script a degraded document HIT ends with: reload once into a
+ * forced MISS. The marker in the URL is the loop bound — a request carrying
+ * it is never a HIT, so this script never runs on the reload, and if it ever
+ * 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.
  */
-export declare function shellSearchSeed(url: URL, filter?: SearchParamsFilter): string;
+export declare function shellReloadScript(): string;
+/**
+ * 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 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.
- */
-export declare function isValidShellHit(entry: ShellCacheEntry, buildVersion: string): boolean;
-/**
- * DOCUMENT-half integrity gate and type narrowing, run BEFORE the HIT response
- * commits: a stored entry whose prelude is not decodable base64 or whose
- * postponed blob is not parseable JSON would otherwise throw AFTER the 200 +
- * full static prelude flushed (`serveShellHit` decodes at stream construction,
- * `resumeShellHTML` parses in the tail) — the client gets a visually complete
- * page that never hydrates, re-served on every request until the entry ages
- * out (no eviction path exists; failure schedules no recapture by itself).
- * Checking here turns a corrupt entry (store-layer fault) into a plain MISS
- * the recapture overwrites. Cost: one duplicate decode/parse per HIT, sub-ms
- * against a prelude flush that dominates the path.
+ * same key (self-healing) and the entry otherwise ages out via TTL.
+ */
+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
+ * replay (which never serves the prelude) and the build-manifest read-through
+ * use it as-is; the document HIT path runs it inside
+ * {@link openShellDocument}, whose single decode is the prelude's check.
  *
  * navigationOnly entries store no document half (prelude/postponed absent) and
  * therefore never pass. The partial-replay path skips this gate for them
@@ -135,8 +134,47 @@ export declare function isValidShellHit(entry: ShellCacheEntry, buildVersion: st
  * capture).
  */
 export declare function hasIntactShellPayload(entry: ShellCacheEntry): entry is DocumentShellCacheEntry;
-/** Decode a base64 prelude back into bytes for stream composition. */
-export declare function base64ToBytes(b64: string): Uint8Array;
+/** A document shell ready to serve: its prelude decoded exactly once. */
+export interface ShellDocument {
+    entry: ShellEntryHead;
+    prelude: Uint8Array;
+    /** React's postponed state, parse-checked (null = DATA variant). */
+    postponed: string | null;
+    /**
+     * The capture snapshot: on the entry, or still arriving on its own promise
+     * after a prelude-first read (SegmentCacheStore.readShellDocument), which
+     * only the tail awaits.
+     */
+    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. */
+    stats?: ShellReadStats;
+}
+/**
+ * Pre-commit integrity gate for a document HIT, and its only prelude decode.
+ * A stored entry whose prelude is not decodable base64 or whose postponed blob
+ * is not parseable JSON would otherwise throw AFTER the 200 + full static
+ * prelude flushed (`resumeShellHTML` parses in the tail) — the client gets a
+ * visually complete page that never hydrates, re-served on every request
+ * until the entry ages out. Returning null here turns a corrupt entry
+ * (store-layer fault) into a plain MISS the recapture overwrites. The decoded
+ * bytes are what serveShellHit enqueues, so the check costs no second decode.
+ * 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): 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:
+ * one 629 KB enqueue delayed the first compressed byte by the full prelude's
+ * compression time (brotli-6 5.1 ms, gzip-6 1.1 ms in Node zlib with a flush
+ * per write; workerd's CompressionStream emits nothing until the whole write is
+ * compressed), while 32 KB chunks emit within 0.1 ms and cost slightly more
+ * in total compression (0.55-0.70 ms) than one write (issue #941).
+ */
+export declare const SHELL_PRELUDE_CHUNK_BYTES: number;
 /** True when the store implements the shell entry family. */
 export declare function hasShellFamily(store: SegmentCacheStore | undefined): store is SegmentCacheStore & {
     getShell: NonNullable<SegmentCacheStore["getShell"]>;
@@ -152,8 +190,22 @@ export declare function hasShellFamily(store: SegmentCacheStore | undefined): st
 export interface ShellTailTiming {
     key: string;
     outcome: "complete" | "redirect" | "error";
+    /** The capture snapshot available to the tail (read and parsed). */
+    snapshotMs?: number;
+    /** Snapshot bytes read after the commit (prelude-first stores). */
+    snapshotBytes?: number;
+    /** Snapshot bytes read after the commit, excluding the parse. */
+    snapshotReadMs?: number;
+    /** Snapshot JSON.parse CPU (reads 0 on a deployed worker: see bytes). */
+    snapshotParseMs?: number;
+    /** 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;
     /** Loader-family seed decode (only when the entry carried a snapshot). */
     seedMs?: number;
+    /** The seed decode's own duration: Flight deserialization, CPU only. */
+    seedCpuMs?: number;
     /** Tail router.match() settled. */
     matchMs?: number;
     /** Tail stream (resume output) handed to the response stream. */
@@ -168,12 +220,13 @@ export interface ShellTailTiming {
     tailBytes?: number;
 }
 /**
- * Compact single-line form for the console log and the dev Server-Timing
- * mirror's `desc`. Plain alphanumerics/`=`/`-` only — no quoted-string
- * escaping needed.
+ * Compact single-line form for the console log and the Server-Timing mirror's
+ * `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.
  */
 export declare function describeShellTailTiming(timing: ShellTailTiming): string;
-/** Buffer one terminal tail timing for the dev Server-Timing mirror. */
+/** Buffer one terminal tail timing for the Server-Timing mirror. */
 export declare function publishShellTailTiming(timing: ShellTailTiming): void;
 /**
  * Consume (read-and-clear) the buffered tail timing for `key`, so one tail
@@ -198,3 +251,44 @@ export declare function warnShellStoreMissingOnce(key: string): void;
  * the missing-store warning above (an undeclared route stays silent).
  */
 export declare function warnPprNonceActiveOnce(key: string): void;
+/**
+ * Dev only (the caller gates on NODE_ENV): warn once per route that the
+ * route's cache() entry reduces an explicit `ppr.ttl` or `ppr.swr`. `shell`
+ * is what the capture stores for a record written just now
+ * (shell-capture.ts capShellWindow), so the message states the values the
+ * shell actually gets. A ppr value the cap leaves whole (or raises: the
+ * cap can move a record's stale time into the shell's swr) is silent, and
+ * so is a ppr config that sets no ttl/swr.
+ */
+export declare function warnPprWindowCappedOnce(routeName: string, ppr: {
+    ttl?: number;
+    swr?: number;
+}, shell: {
+    ttl: number;
+    swr: number;
+}, cache: {
+    ttl: number;
+    swr: number;
+}): void;
+/**
+ * Whether a partitioned request needs no build-shell probe: its route was
+ * already warned, or its path was already found without one.
+ */
+export declare function partitionBuildShellCheckDone(pathname: string, routeName: string | undefined): boolean;
+/**
+ * Record a partitioned request's build-shell probe, and warn once per route
+ * when it found one: the route has a build-time shell its requests cannot
+ * read. The route's request partition (a `cache({ key })` enclosing it, at
+ * any depth (#970), or the store's keyGenerator) keys the shell per
+ * partition, and the build captured only
+ * the default one, so each partition captures at runtime. Same
+ * declared-intent-cannot-be-honored doctrine as the warnings above; a path
+ * with no build shell stays silent.
+ */
+export declare function notePartitionBuildShellCheck(pathname: string, routeName: string | undefined, found: boolean): void;
+/**
+ * @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
@@ -208,6 +210,13 @@ export interface SSRModule {
         origin?: string;
         /** Each component error the prerender reports (never the capture's own abort). */
         onError?: (error: unknown) => void;
+        /**
+         * React's errorInfo for each task still pending at the capture's abort
+         * (its componentStack is computed when read).
+         */
+        onAbortedTask?: (errorInfo: {
+            componentStack?: string;
+        } | undefined) => void;
     }) => Promise<{
         prelude: Uint8Array;
         postponed: string | null;

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

package/dist/types/server/context.d.ts

@@ -1,7 +1,7 @@
+import type { ServerRouteLocation } from "../types/segments.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { ReactNode } from "react";
 import type { PartialCacheOptions, ErrorBoundaryHandler, Handler, LoaderDefinition, MiddlewareFn, NotFoundBoundaryHandler, ShouldRevalidateFn, TransitionConfig } from "../types";
-import type { DefaultRouteName } from "../types/global-namespace.js";
 import type { ContextVar } from "../context-var.js";
 /**
  * Performance metric entry for a single measured operation
@@ -106,6 +106,15 @@ export type LoaderEntry = {
      * appears on navigation-lane entries.
      */
     awaitBeforeFlush?: true;
+    /**
+     * loader(Def, { ssr: false }) on every DSL evaluation, document and
+     * navigation: the loader's PPR bake lane (loader-cache.ts
+     * resolveLoaderData). The bake/seed key rides on it, so a client
+     * navigation's shell replay pins exactly the loaders a document HIT pins,
+     * whatever the entry's loading(). awaitBeforeFlush cannot carry that: a
+     * navigation evaluation never has it.
+     */
+    bake?: true;
 };
 /**
  * Segments state for intercept context
@@ -123,20 +132,22 @@ export type InterceptSegmentsState = {
  * Context passed to intercept selector functions (when())
  * Contains navigation context to determine if interception should occur.
  *
+ * `from` / `to` have the shape transition({ when }) sees, without `state`:
+ * history state never reaches the server.
+ *
  * Note: when() is evaluated during route matching, BEFORE middleware runs.
  * So ctx.get()/ctx.use() are not available, but env (platform bindings) is.
  *
  * @internal This type is an implementation detail and may change without notice.
  */
 export type InterceptSelectorContext<TEnv = any> = {
-    from: URL;
-    to: URL;
-    params: Record<string, string>;
+    /** Where the navigation comes from: the intercept source while one is open. */
+    from: ServerRouteLocation;
+    /** The navigation target. */
+    to: ServerRouteLocation;
     request: Request;
     env: TEnv;
     segments: InterceptSegmentsState;
-    fromRouteName?: DefaultRouteName;
-    toRouteName?: DefaultRouteName;
 };
 /**
  * Selector function for conditional interception
@@ -408,24 +419,130 @@ export declare function getParallelSlotCount(parallels: ParallelEntries | EntryD
 export declare function track(label: string, depth?: number): () => void;
 /**
  * Check if the current execution is inside a cache() DSL boundary.
- * Returns false inside loader execution — loaders are always fresh
- * (never cached), so non-cacheable reads are safe.
+ * Returns false inside loader execution: a route cache() does not store
+ * loader values, so non-cacheable reads are safe. A loader bound with its own
+ * cache() stores its value; recordLoaderIdentityRead guards that.
  */
 export declare function isInsideCacheScope(): boolean;
 /**
- * Read guard for a non-cacheable variable (`createVar({ cache: false })` or a
- * `ctx.set(..., { cache: false })` write). Callers check isNonCacheable() first
- * so ordinary reads never reach the scope lookups.
+ * What a refused identity read says (guardIdentityRead): its `verb`, and per
+ * refusing scope the text after "<surface> cannot be <verb> ...": why the
+ * value must not reach that scope, and what to do instead. `fix.warning` is
+ * the fix the capture's refusal warning gives (shell-capture.ts
+ * refuseOnCaptureGuard).
+ */
+export interface IdentityReadWording {
+    /** "called" for a function (cookies(), ctx.get()), "read" for a property (the theme getters). */
+    verb: LoaderIdentityReadVerb;
+    fix: {
+        useCache: string;
+        cacheScope: string;
+        capture: string;
+        warning: string;
+    };
+    /**
+     * False when the read is recorded later, by the returned view's read
+     * methods (cookies(), headers()): a view taken outside a loader and read
+     * inside one still counts, and a cookie write alone is not a read.
+     */
+    record?: false;
+}
+/**
+ * The one guard every request-identity read goes through: cookies(),
+ * headers(), the theme reads (cookie-store.ts readGuardedTheme), a
+ * non-cacheable ctx.get() (assertNonCacheableReadAllowed), and the raw reads
+ * `ctx.request.headers` and `getRequestContext().cookie()` / `.cookies()`
+ * (cookie-store.ts guardRequestHeaders, guardRawCookieRead; #976). Each surface keeps
+ * its own wording; the ladder and its exemptions are shared, so the surfaces
+ * refuse in exactly the same places:
  *
- * Throws inside a "use cache" body: the key does not include the value, so the
- * first caller's value would be stored and served to later callers (#925). A
- * loader body entered INSIDE the cached function is exempt, the same baked-copy
- * trade isInsideCacheScope() makes for cache(). A cached function called FROM a
- * loader is not: the loader re-runs, the cached body does not. The body scope
- * records the exec scope it was entered in, so the exemption holds only while
- * that is still the innermost one.
+ * 0. A cache's own key(), store keyGenerator, condition() and tags(), and
+ *    onError, read freely and record nothing (runIdentityExempt,
+ *    cache/cache-exec-scope.ts): the value picks or labels the entry, or is
+ *    only observed; it is never rendered. A cached body, loader body or
+ *    funnel they start is guarded again.
+ * 1. A PPR shell capture (`ctx` is the capture's derived context,
+ *    `_shellCaptureRun`) trips first: the capture context is flagged (so a
+ *    caught throw still refuses the capture) and the read throws. The shell is
+ *    shared per host+URL, and every HIT replays what the capture read. There
+ *    is no loader-body exemption here: a bake-lane loader and a loader a
+ *    handler awaits both bake.
+ * 2. A "use cache" body throws: the key does not include the value, so the
+ *    first caller's would be stored and served to later callers. That holds
+ *    for a loader body entered inside the cached function too (`await
+ *    ctx.use(Loader)` there): its value is part of what the function returns.
+ *    Before, a non-cacheable ctx.get() there was exempt while cookies() threw,
+ *    and the entry stored the first request's value.
+ * 3. A cache() boundary throws, except inside a loader body
+ *    (isInsideCacheScope): a route cache() never stores loader values.
+ * 4. The read is allowed, and recorded on the current loader execution for a
+ *    loader cache() fill without key() (#972, recordLoaderIdentityRead)
+ *    unless `wording.record` defers it to the returned view.
+ *
+ * Outside these scopes every read is allowed, a live loader's included. The
+ * response directives (invalidateClientCache(), keepClientCache()) record
+ * nothing and are not captured reads: they take refuseInCacheScope alone.
+ */
+export declare function guardIdentityRead(ctx: unknown, surface: string, wording: IdentityReadWording): void;
+/**
+ * Steps 2 and 3 of guardIdentityRead: throw when a "use cache" body or a
+ * cache() boundary would store what `surface` produces.
+ */
+export declare function refuseInCacheScope(surface: string, { verb, fix }: IdentityReadWording): void;
+/**
+ * The capture refusal for a request-scoped read (cookies(), headers(), a
+ * { cache: false } variable): the message after the surface, and the fix the
+ * refusal warning gives. `what` names the data that would leak.
  */
-export declare function assertNonCacheableReadAllowed(keyOrVar: string | ContextVar<unknown>): void;
+export declare function requestReadCaptureFix(what: string): Pick<IdentityReadWording["fix"], "capture" | "warning">;
+/**
+ * Read guard for a non-cacheable variable (`createVar({ cache: false })` or a
+ * `ctx.set(..., { cache: false })` write), through guardIdentityRead.
+ * Callers check isNonCacheable() first so ordinary reads never reach the
+ * scope lookups. `requestCtx` is the ambient request context, whose capture
+ * flag the guard reads.
+ */
+export declare function assertNonCacheableReadAllowed(keyOrVar: string | ContextVar<unknown>, requestCtx?: unknown): void;
+/** How the identity error words a read: a function call or a property read. */
+export type LoaderIdentityReadVerb = "called" | "read";
+/** A request-identity read a loader execution made (recordLoaderIdentityRead). */
+export interface LoaderIdentityRead {
+    /**
+     * The read as the error names it: "cookies()", "headers()",
+     * `ctx.get() for a non-cacheable variable "x"`, "ctx.theme" or
+     * "getRequestContext().theme".
+     */
+    surface: string;
+    /** "called" for a function, "read" for a property (the theme getters). */
+    verb: LoaderIdentityReadVerb;
+    /** The loader body that made the read. */
+    bodyId: string | undefined;
+    /**
+     * The cached loader whose value carries a read another loader made
+     * (loader-cache.ts identity mark): its readers read it through `via`.
+     */
+    via?: string;
+}
+/**
+ * Record a request-identity read (cookies(), headers(), a non-cacheable
+ * ctx.get()) on the current loader execution (#972).
+ *
+ * isInsideCacheScope() exempts loader bodies because a route cache() never
+ * stores their values. A loader bound with its own cache() does: with no key()
+ * and no store keyGenerator its entry is keyed by loader, host, path and
+ * params only, and an enclosing route cache() key does not partition it
+ * (#974). A cookies() read there stored the first visitor's session and served
+ * it to everyone for the TTL. The read is recorded on the execution, not
+ * thrown at the call: a reader that starts the loader before its binding does
+ * runs it outside any fill, and the binding's MISS then reuses that run. The
+ * fill checks what its execution recorded, through the same links as its tags
+ * (cache-tag.ts recordedIdentityRead), so both orders fail the same way.
+ * Response directives do not record: a key cannot make a skipped body's side
+ * effect reach a HIT.
+ */
+export declare function recordLoaderIdentityRead(surface: string, verb?: LoaderIdentityReadVerb): void;
+/** The error a loader cache() fill with no declared key fails with (#972). */
+export declare function loaderCacheIdentityError(read: LoaderIdentityRead, cachedLoaderId: string): Error;
 /**
  * Check if the current execution is inside a DSL loader scope
  * (wrapped by runInsideLoaderScope). Used by rendered() barrier
@@ -439,6 +556,10 @@ export declare function isInsideLoaderScope(): boolean;
  * Takes scalars so the already-latched path allocates nothing.
  */
 export declare function latchCachedHeaderScope(kind: CachedHeaderScope["kind"], routeKey?: string): void;
+/** True inside ANY loader execution — DSL loader scope or a loader body
+ *  (however invoked). The "loaders always re-run fresh" exemptions key off
+ *  this. */
+export declare function isInsideAnyLoaderScope(): boolean;
 /**
  * The one ppr opt-in predicate: a page route entry that DECLARED `ppr`
  * (`false` and undefined mean plain axis 1). Shared by the serve path
@@ -506,21 +627,32 @@ export declare function assertCachedHeaderWriteAllowed(surface: string, surfaceP
 export declare function runInsideLoaderScope<T>(fn: () => T): T;
 /**
  * Run `fn` inside a loader BODY scope. Marks loader-function execution for the
- * cache-purity guard only (isInsideCacheScope), WITHOUT affecting
+ * cache() purity guard only (isInsideCacheScope), WITHOUT affecting
  * isInsideLoaderScope()/rendered() gating. Applied to every loader body (DSL
  * and handler-invoked via ctx.use) so request-scoped reads inside a loader
- * never trip the cache-scope guards — loaders always run fresh.
+ * never trip the cache() guard — a route cache() never stores loader values.
+ * A "use cache" body the loader was entered in still refuses them
+ * (guardIdentityRead).
  */
-export declare function runInsideLoaderBodyScope<T>(fn: () => T, loaderId?: string, handlerInvoked?: boolean): T;
+export declare function runInsideLoaderBodyScope<T>(fn: () => T, loaderId?: string, tags?: Set<string>): T;
+/** The innermost loader body's execution tag set (runInsideLoaderBodyScope). */
+export declare function getLoaderBodyTags(): Set<string> | undefined;
 /**
  * The $$id of the loader whose body is currently executing, or undefined
  * outside any loader body. Used by the shell-capture identity guard
- * (cookie-store.ts) so its refusal warning can name the loader that read
+ * (guardIdentityRead) so its refusal warning can name the loader that read
  * cookies()/headers() instead of blaming a lane it cannot see — the old
  * hardcoded "bake-lane loader" text misled a live-lane debugging session
  * (issue #672, secondary).
  */
 export declare function getCurrentLoaderBodyId(): string | undefined;
+/**
+ * The innermost loader body running here, or around it through the
+ * ctx.use(Loader) chain, whose id `match` accepts (HandleStore.push, the
+ * shell capture's push funnel). A body `stop` accepts, and `match` does not,
+ * ends the walk: nothing around it is returned.
+ */
+export declare function findEnclosingLoaderBody(match: (loaderId: string) => boolean, stop?: (loaderId: string) => boolean): string | undefined;
 /**
  * True while `loaderId`'s body, or a loader it awaits via ctx.use at any
  * depth, is executing. The loader-level cache records these pushes
@@ -528,16 +660,6 @@ export declare function getCurrentLoaderBodyId(): string | undefined;
  * reader runs in that request only reaches the page through the replay.
  */
 export declare function isInsideLoaderBody(loaderId: string): boolean;
-/**
- * True while a HANDLER-invoked loader body (`await ctx.use(Loader)` from a
- * handler, not the DSL segment funnel) is executing. The consumption-lane
- * rule keys off this: handler consumption yields a BAKED copy in every shared
- * artifact — cache(), "use cache", and the PPR shell — so the shell-capture
- * identity guard (cookie-store.ts) permits cookies()/headers() here, exactly
- * like the cache-purity guards do. DSL segment loaders (live lane masked at
- * capture, bake lane guarded) never set the flag.
- */
-export declare function isInsideHandlerInvokedLoaderBody(): boolean;
 /**
  * Check if the current execution is inside a handle push callback (sync or an
  * async callback's continuation). Used by the handler-to-loader deadlock guard

package/dist/types/server/cookie-store.d.ts

@@ -7,6 +7,8 @@
  * Writes append Set-Cookie to the response stub.
  */
 import type { CookieOptions } from "../router/middleware-types.js";
+import type { Theme } from "../theme/types.js";
+import { type RequestContext } from "./request-context.js";
 /**
  * A single cookie entry returned by get() and getAll().
  */
@@ -63,6 +65,37 @@ export interface ReadonlyHeaders {
     [Symbol.iterator](): HeadersIterator<[string, string]>;
 }
 type HeadersIterator<T> = IterableIterator<T>;
+/**
+ * Run the identity guard for a raw cookie read on `ctx`
+ * (request-context.ts `cookie()` / `cookies()`). Before #976 they were plain
+ * reads of the Cookie header that no shared scope refused. The guard reads
+ * the ambient context, as cookies() does, and falls back to `ctx`.
+ */
+export declare function guardRawCookieRead(ctx: RequestContext<any>, surface: "getRequestContext().cookie()" | "getRequestContext().cookies()"): void;
+/**
+ * Guard `request.headers` like headers() (#976): the request every ctx
+ * exposes (request context, handler, middleware and loader `ctx.request`)
+ * gets an own getter that runs guardIdentityRead against the ambient request
+ * context, so a read inside a ppr capture, a cache() boundary, a "use cache"
+ * body or an unkeyed loader cache() fill refuses as cookies() does. A Request
+ * argument keys a "use cache" entry by its URL only (cache-runtime.ts), so a
+ * header read there baked the first caller's value into the shared entry.
+ * The router's own reads go through requestHeaders() (request-headers.ts).
+ * Idempotent; returns `request`.
+ */
+export declare function guardRequestHeaders(request: Request): Request;
+/** The public reads of the visitor's theme cookie that readGuardedTheme guards. */
+export type ThemeReadSurface = "ctx.theme" | "getRequestContext().theme";
+/**
+ * `ctx`'s theme through guardIdentityRead: the one body of every public theme
+ * read (the handler and middleware `ctx.theme`, handler-context.ts and
+ * middleware.ts, and `getRequestContext().theme`, request-context.ts). The
+ * guard reads the ambient context, as cookies() does, and falls back to
+ * `ctx`; the value is `ctx`'s unguarded `_readTheme()`, which the router's
+ * own payload read (payloadInitialTheme, rsc/full-payload.ts) calls directly.
+ * Undefined without a theme config.
+ */
+export declare function readGuardedTheme(ctx: RequestContext<any> | undefined, surface: ThemeReadSurface): Theme | undefined;
 /**
  * Get the original request headers (read-only).
  *