@rangojs/router 0.17.0 → 0.18.0

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

@@ -17,7 +17,7 @@
  */
 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";
+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. */
@@ -94,6 +94,41 @@ export declare function resolvePprConfig(entry: EntryData | undefined | null): R
  * 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
+ * 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 withoutShellMissMarker(request: Request): Request | undefined;
+/**
+ * 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. `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.
+ */
+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;
 /**
  * The shell key's search portion (`?`-prefixed sorted search with the
  * cache.searchParams filter applied, or "") — ALSO the string the capture and
@@ -117,16 +152,11 @@ export declare function shellSearchSeed(url: URL, filter?: SearchParamsFilter):
  */
 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.
+ * 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 +165,46 @@ 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: ShellCacheEntry;
+    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[] | undefined | 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, 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 +220,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/item:5` (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 +250,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 pruned=item:5),
+ * 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 +281,43 @@ 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 and buffered tail
+ * timings. Tests only (testing/serve-shell-request.ts resetShellTestState).
+ */
+export declare function resetShellServeStateForTests(): void;

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

@@ -208,6 +208,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/server/context.d.ts

@@ -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
@@ -408,15 +417,64 @@ 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;
+/**
+ * Throw if called during the ACTIVE background shell-capture render
+ * (`_shellCaptureRun` true on the derived request context built by
+ * shell-capture.ts). The captured shell is shared across every user hitting
+ * the URL, so a request-scoped read here would bake one user's cookies,
+ * headers, or per-request variables into markup served to others — same
+ * hazard as the cache scopes above, at the document tier. DSL segment loaders
+ * need no exemption: the live lane is masked (never executed) during capture,
+ * and the bake lane is exactly what this guard exists for.
+ *
+ * It covers everything the capture waits for, not only synchronous handler
+ * code: a promise the handler passes or pushes, an async server component,
+ * and a loader the handler awaits (`await ctx.use(Loader)`) all run under the
+ * capture context and all bake. The last one used to be exempt (the
+ * consumption-lane rule, #672/#674): while a HIT re-ran handlers, a slot
+ * handler's `ctx.use` of an identity loader rendered per visitor on the HIT.
+ * Now every HIT replays the capture's copy, so the exemption would bake the
+ * capturing request's identity into every visitor's page. The cache()
+ * guards above keep it (a cache() HIT is a separate tier).
+ *
+ * Keys off `_shellCaptureRun`, NOT the `_shellCapture` descriptor: the descriptor
+ * is also present during the FOREGROUND render (it means "a capture is wanted"),
+ * and the foreground must read cookies/headers normally to serve the real user.
+ * Only the derived capture context sets `_shellCaptureRun`.
+ *
+ * Applies only to the READ surfaces (cookies(), headers(), a { cache: false }
+ * variable, and the theme reads through tripShellCaptureGuard) whose values
+ * become markup. Response directives
+ * (invalidateClientCache(), keepClientCache()) stay callable: during capture
+ * they are header effects on a discarded response, and on the live HIT path
+ * the full pipeline runs so their headers flow to the client normally.
+ *
+ * The throw can be caught by the code that made the read, so the guard also
+ * flags the capture context; the capture refuses on the flag
+ * (shell-capture.ts refuseOnCaptureGuard), nothing is stored, and every
+ * request keeps getting the normal axis-1 render.
+ */
+export declare function assertNotInsideShellCapture(ctx: unknown, fnName: string): void;
+/**
+ * True when `ctx` is the active capture render (assertNotInsideShellCapture
+ * above). On true the capture context is flagged with the read (`surface`,
+ * e.g. "cookies()", "ctx.theme") and the fix the refusal warning gives, plus
+ * the loader body (if any) that made the read, and the caller throws.
+ */
+export declare function tripShellCaptureGuard(ctx: unknown, surface: string, fix: string): 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.
  *
+ * Throws during a PPR shell capture (`requestCtx` is the ambient request
+ * context; assertNotInsideShellCapture): the shell is shared per host+URL.
+ *
  * 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
@@ -425,7 +483,47 @@ export declare function isInsideCacheScope(): boolean;
  * records the exec scope it was entered in, so the exemption holds only while
  * that is still the innermost one.
  */
-export declare function assertNonCacheableReadAllowed(keyOrVar: string | ContextVar<unknown>): void;
+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 +537,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
@@ -511,11 +613,13 @@ export declare function runInsideLoaderScope<T>(fn: () => T): T;
  * and handler-invoked via ctx.use) so request-scoped reads inside a loader
  * never trip the cache-scope guards — loaders always run fresh.
  */
-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
+ * (assertNotInsideShellCapture) 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).
@@ -528,16 +632,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

@@ -63,6 +63,27 @@ export interface ReadonlyHeaders {
     [Symbol.iterator](): HeadersIterator<[string, string]>;
 }
 type HeadersIterator<T> = IterableIterator<T>;
+/** The public reads of the visitor's theme cookie that assertThemeReadAllowed guards. */
+export type ThemeReadSurface = "ctx.theme" | "getRequestContext().theme";
+/**
+ * Guard for a read of the visitor's theme: the handler and middleware
+ * `ctx.theme` (handler-context.ts, middleware.ts) and `getRequestContext().theme`
+ * (request-context.ts). The theme is the visitor's theme cookie, so it is an
+ * identity read like cookies(): it refuses in the same scopes, in the same
+ * order (refusingCacheScope, then tripShellCaptureGuard in context.ts), with
+ * the same exemption (a loader body under cache(); at capture there is none).
+ * Before #971 each read was a plain cookie read, so a ppr shell, a cache()
+ * entry or a "use cache" entry stored the first visitor's theme and served it
+ * to every later visitor.
+ *
+ * A read the guards allow is recorded on the current loader execution, as a
+ * cookies() read method records it (#972, recordLoaderIdentityRead).
+ *
+ * `ctx` is the request context at read time, as cookies() reads it. The
+ * router's own payload read (payloadInitialTheme, rsc/full-payload.ts) goes
+ * through the unguarded `_readTheme()`.
+ */
+export declare function assertThemeReadAllowed(ctx: unknown, surface: ThemeReadSurface): void;
 /**
  * Get the original request headers (read-only).
  *