@rangojs/router 0.17.0 → 0.18.0

package/README.md

@@ -524,8 +524,9 @@ parityDescribe("add to cart", (f) => {
 ```
 
 `runMiddleware`, `renderHandler` (Server Component handlers rendered to a
-real Flight tree), `renderRoute` (DOM tests) and the cache assertions follow
-the same pattern. See the [`/testing` skill](./skills/testing/SKILL.md).
+real Flight tree), `serveShellRequest` (a `ppr` route's real shell capture and
+HIT), `renderRoute` (DOM tests) and the cache assertions follow the same
+pattern. See the [`/testing` skill](./skills/testing/SKILL.md).
 
 ## Everything else, when you need it
 

package/dist/types/browser/cookie-name.d.ts

@@ -12,6 +12,12 @@
  */
 /** Default prefix when `stateCookiePrefix` is unset or empty after sanitization. */
 export declare const DEFAULT_STATE_COOKIE_PREFIX = "rango-state";
+/**
+ * The fresh-reads cookie name for a router's resolved state cookie name
+ * (`{prefix}_{routerId}`; the prefix never contains `_`, see
+ * router/state-cookie-name.ts).
+ */
+export declare function freshReadsCookieName(stateCookieName: string): string;
 /** Internal response header carrying the keepClientCache() directive. */
 export declare const KEEP_CACHE_HEADER = "x-rango-keep-cache";
 /** True for a per-client signal header. */

package/dist/types/browser/history-state.d.ts

@@ -18,6 +18,22 @@ export declare function buildHistoryState(userState: unknown, routerState?: {
  * relying on the Navigation API.
  */
 export declare function pushHistoryWithIdx(state: Record<string, unknown> | null, url: string, replace: boolean): void;
+/**
+ * The forced-MISS reload marker (`SHELL_MISS_PARAM` in rsc/shell-serve.ts,
+ * which the browser bundle must not import): a degraded PPR shell HIT
+ * reloads the page with it, and the server renders a marked request like a
+ * cache miss.
+ */
+export declare const SHELL_MISS_MARKER: string;
+/**
+ * Drop the forced-MISS marker from the address bar at boot, keeping the
+ * history entry's state (initBrowserApp calls it before any location read).
+ * Left in place, a refresh or a shared link would stay off the shell and the
+ * app's search params would carry it. The server strips the same marker from
+ * the request before rendering (shell-serve.ts withoutShellMissMarker), so
+ * the page was rendered for the clean URL and the hydrating client agrees.
+ */
+export declare function stripShellMissMarker(): void;
 /**
  * Merge server-set location state into the current history entry.
  * Replaces the current history state and dispatches notification event

package/dist/types/cache/cache-key-utils.d.ts

@@ -2,8 +2,8 @@
  * Shared Cache Key Utilities
  *
  * Deterministic normalization of search params and route params
- * for cache key generation. Used by cache-runtime, cache-scope,
- * document-cache, and loader-cache.
+ * for cache key generation, and the composition of nested cache() keys.
+ * Used by cache-runtime, cache-scope, document-cache, and loader-cache.
  */
 import type { SearchParamsFilter } from "./search-params-filter.js";
 /**
@@ -41,3 +41,18 @@ export declare function sortedRouteParams(params: Record<string, string> | undef
  * tier-specific suffixes (`:rsc`/`:html`, segment hash) after this base.
  */
 export declare function cacheKeyBase(host: string, pathname: string, searchParams?: URLSearchParams, params?: Record<string, string>, filter?: SearchParamsFilter): string;
+/**
+ * The record key, or shell partition, of nested keyed cache() scopes (#970)
+ * from its parts, outermost first: the chain's `key()` results and, for an
+ * inner scope without its own `key()`, that scope's default key
+ * (CacheScope.resolveKeyFrom). One part is returned raw, so a single keyed
+ * scope keeps its key byte for byte. Two or more are joined by `|`, each
+ * URI-encoded (like partitionShellKey, rsc/shell-capture-constants.ts): an
+ * encoded part holds no `|`, so every tuple maps to its own key, of any
+ * depth. Raw, `("a|b", "c")` and `("a", "b|c")` named one record. A composed
+ * key holds no `:` either, so a single raw result with one (a prefixed
+ * `tier:...`, a `doc:` default key) never equals it; an unprefixed raw result
+ * can. Shared with the testing helper `shellCacheKey`, which composes a
+ * nested partition the same way.
+ */
+export declare function composeCacheKeys(parts: readonly string[]): string;

package/dist/types/cache/cache-policy.d.ts

@@ -42,6 +42,23 @@ export declare function resolveTtl(explicit: number | undefined, defaults: Cache
  * non-finite/negative (degrade rather than feed bad math into expiry).
  */
 export declare function resolveSwrWindow(explicit: number | undefined, defaults: CacheDefaults | undefined): number;
+/**
+ * Minimum age (ms) of a stale PPR shell before a HIT schedules its recapture.
+ * A shell capped to a route cache() record inside its swr window is stale
+ * from the start (rsc/shell-capture.ts capShellWindow), so without a floor
+ * every HIT of it recaptured, and a capture's store write is one KV write per
+ * key: Cloudflare KV accepts one per second per key. Inside the floor the
+ * stale shell is still served. Per isolate: each isolate's stale HIT past the
+ * floor can schedule one (stampede-guarded per isolate).
+ */
+export declare const SHELL_MIN_RECAPTURE_INTERVAL_MS = 1000;
+/**
+ * Whether a stale shell HIT schedules its recapture (see the floor above).
+ * Fails open: an entry without a numeric `createdAt` recaptures.
+ */
+export declare function staleShellRecaptureDue(entry: {
+    readonly createdAt?: number;
+}, now: number): boolean;
 /**
  * Compute staleAt and expiresAt timestamps from TTL and SWR window.
  *

package/dist/types/cache/cache-scope.d.ts

@@ -12,6 +12,7 @@ import type { ResolvedSegment } from "../types.js";
 import type { SegmentCacheStore } from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
 export declare function resolveCacheTags(config: PartialCacheOptions | false, ctx: RequestContext | undefined): string[] | undefined;
+type CacheKeyFn = NonNullable<PartialCacheOptions["key"]>;
 /**
  * Discriminated outcome of a route cache lookup — see
  * {@link CacheScope.lookupRouteDetailed} for what each status licenses.
@@ -56,6 +57,18 @@ export declare class CacheScope {
     readonly parent: CacheScope | null;
     /** Explicit store from cache() options, if specified */
     private readonly explicitStore;
+    /**
+     * @internal The `key()` functions that partition this scope's records,
+     * outermost first: every cache() on the parent chain that sets one, this
+     * scope's last (#970). `cache(false)` adds none and does not cut the chain,
+     * so a cache() re-enabled under it stays in the partition. Before, the
+     * innermost config alone decided the key: an inner cache() without `key()`
+     * wrote under the default key and an inner `key()` dropped the outer one,
+     * so a request in one partition HIT another partition's inner records.
+     */
+    readonly keyFns: readonly CacheKeyFn[];
+    /** Whether this scope's own config sets `key()` (the last of keyFns). */
+    private readonly hasOwnKey;
     constructor(config: PartialCacheOptions | false, parent?: CacheScope | null, defaultKeyPrefix?: "doc" | undefined, 
     /**
      * @internal shortCode of the outermost cache() entry of this scope's
@@ -106,6 +119,57 @@ export declare class CacheScope {
      * @internal
      */
     private resolveKey;
+    /**
+     * A shell captured from a route record this request read or wrote must not
+     * outlive it (noteRouteRecordWindow). The implicit doc scope's own record
+     * is the shell's, so it notes nothing.
+     */
+    private noteRecordWindow;
+    /**
+     * @internal This scope's record key for `defaultKey`, resolved once per
+     * request: a ppr route's shell partition (resolvePartition) and the record
+     * lookup share the `key()` runs, and a rejection is shared too.
+     *
+     * With `key()` functions on the chain (keyFns) the parts are their results,
+     * outermost first, composed by composeCacheKeys (a single part raw), so a
+     * nested cache() keys its records within the enclosing partition (#970).
+     * A scope whose own config sets no `key()` appends its own default key
+     * (resolveDefaultKey). Reusing the outer `key()` result alone would give
+     * every route under the inner cache() one record: a `key()` replaces the
+     * whole default key, so an outer key that names no route (`tier:gold`)
+     * would make `/a` HIT `/b`'s record. A scope with its own `key()` adds no
+     * default key: a `key()` is a full override, and no keyGenerator runs.
+     * Without `key()` on the chain it is resolveDefaultKey alone. With one but
+     * no request context it rejects (keyWithoutContextError).
+     *
+     * Each `key()` result lives on the request context (`_resolvedCacheKeys`),
+     * by function: it runs once per request whatever the default key
+     * (document, partial or `doc` shell prefix) and however many scopes share
+     * it (sibling routes under one keyed cache()). A shell capture, whose
+     * context is `Object.create` of the request's (shell-capture.ts), reads the
+     * foreground's results through the prototype chain and never runs `key()`
+     * itself: a `key()` calling `cookies()` would trip the capture guard there,
+     * and a capture must store the partition its request resolved.
+     */
+    resolveKeyFrom(defaultKey: string): Promise<string>;
+    /**
+     * @internal The request partition of a ppr route's shell under this scope
+     * (resolveShellPartition): the chain's `key()` results, composed like the
+     * record key but without the default key, which the URL-based shell key
+     * already carries. A scope without its own `key()` whose store has a
+     * keyGenerator adds that result when it differs from the `doc` default
+     * key, as an unkeyed scope's partition always did: the record is split by
+     * it, so the shell must be too. Undefined (synchronously, with no work)
+     * when nothing can partition; null when nothing does.
+     */
+    resolvePartition(pathname: string, params: Record<string, string> | undefined): Promise<string | null> | undefined;
+    /** The chain's `key()` results, each once per request (memoizedKey). */
+    private resolveKeyResults;
+    /**
+     * This scope's store keyGenerator result for `defaultKey` (once per request
+     * and default key), else `defaultKey` (resolveCacheKey).
+     */
+    private resolveDefaultKey;
     /**
      * @internal Whether a cache read/write is allowed for the current request:
      * the scope is enabled AND its `condition` (if any) returns true. "read"
@@ -205,6 +269,21 @@ export declare class CacheScope {
      */
     cacheRoute(pathname: string, params: Record<string, string>, segments: ResolvedSegment[], isIntercept?: boolean): Promise<void>;
 }
+/**
+ * @internal The request partition of a ppr route's shell: with a route
+ * cache() scope, its CacheScope.resolvePartition (the chain's `key()`
+ * results, composed, plus a keyGenerator's contribution for a scope without
+ * its own `key()` (#970)); with none, the app store's keyGenerator result
+ * given the document default key. Undefined (synchronously, with no work)
+ * when neither applies: the shell key stays host + path + filtered search.
+ * Resolves to null when the partition is the default key itself (a
+ * keyGenerator that returns it unchanged): that partitions nothing, so the
+ * shell stays unpartitioned and keeps its build shell. The shell's key, its
+ * read and capture, and partial replay all use it, so a visitor is only
+ * served its own partition. A rejected promise is a failed key resolution:
+ * the caller serves no shell.
+ */
+export declare function resolveShellPartition(routeScope: CacheScope | null | undefined, appStore: SegmentCacheStore | null | undefined, pathname: string, params: Record<string, string> | undefined): Promise<string | null> | undefined;
 /**
  * Create a cache scope from entry's cache config. `shortCode` is the cache()
  * entry's: a scope nested in an enabled parent keeps the parent's boundary
@@ -221,24 +300,29 @@ type ShellImplicitCacheMarker = NonNullable<RequestContext["_shellImplicitCache"
  * {@link resolveShellImplicitCacheScope} (routes that derived no scope) and
  * the explicit-scope composition sites (capture doc record in the cache-store
  * middleware, seeded replay fallback in withCacheLookup) so both ends of the
- * shell contract resolve the SAME canonical document key.
+ * shell contract resolve the SAME canonical document key. A document HIT
+ * tail's marker carries the entry's own key (`fixedDocKey`), which wins over
+ * key resolution.
  */
 export declare function createShellImplicitDocScope(marker: ShellImplicitCacheMarker): CacheScope;
 /**
- * Shell fast path: when the route tree derived NO cache scope and the current
- * request context carries the `_shellImplicitCache` marker (a shell capture,
- * an eligible HIT tail, or a normal partial navigation replay), substitute an
- * implicit doc-level scope so withCacheLookup/withCacheStore treat the WHOLE
- * matched route as a cache() boundary — the shell entry IS a cache() of the
- * handler layer, with loaders as the live carve-outs
- * (resolveFreshLoadersAndYield).
+ * The doc record scope: when the current request context carries the
+ * `_shellImplicitCache` marker (a shell capture, a document HIT tail, or a
+ * normal partial navigation replay), substitute an implicit doc-level scope
+ * so withCacheLookup/withCacheStore treat the WHOLE matched route as a
+ * cache() boundary — the shell entry IS a cache() of the handler layer, with
+ * loaders as the live carve-outs (resolveFreshLoadersAndYield).
  *
- * An existing scope — including an explicit cache(false) opt-out — always
- * wins HERE: the consumer's cache() semantics (their ttl/swr/store/condition)
- * are never overridden, and cache(false) keeps the tail on the full handler
- * re-run path. On the navigation-replay serve path the marker still composes
- * with an explicit scope downstream (withCacheLookup's seeded fallback after
- * an explicit-tier miss) — see `onExplicitHit` on `_shellImplicitCache`.
+ * A document HIT tail (`docTail`) always gets the implicit scope: it replays
+ * the shell's own record and never consults a route-derived scope, whose
+ * opt-outs the serve gate evaluated before the commit (shellServePlan). Every
+ * other marker leaves an existing scope — including an explicit cache(false)
+ * — in place: the consumer's cache() semantics (their ttl/swr/store/condition)
+ * are never overridden. On the navigation-replay serve path the marker still
+ * composes with an explicit scope downstream (withCacheLookup's seeded
+ * fallback after an explicit-tier miss) — see `onExplicitHit` on
+ * `_shellImplicitCache`; during a capture, recordShellCaptureDocRecord
+ * (cache-store.ts) writes the record for such a scope.
  */
 export declare function resolveShellImplicitCacheScope(scope: CacheScope | null): CacheScope | null;
 export {};

package/dist/types/cache/cache-tag.d.ts

@@ -10,6 +10,54 @@
  * profile/DSL tags before storing.
  */
 import { type RequestContext } from "../server/request-context.js";
+import { type LoaderIdentityRead } from "../server/context.js";
+/**
+ * Arm the record tag owners for `ctx`: its match resolved a cache scope, so
+ * it can write a route cache() record (match-api.ts). A capture's or
+ * background re-render's derived context inherits the flag.
+ */
+export declare function armRecordTagOwners(ctx?: RequestContext | undefined): void;
+/** Whether `ctx` records tag owners (see armRecordTagOwners). */
+export declare function recordTagOwnersArmed(ctx?: RequestContext | undefined): boolean;
+/**
+ * Call `fn(arg)` inside segment `segmentId`'s tag scope: tags recorded while
+ * it or its async continuations run (outside a loader body) are owned by that
+ * segment. Unarmed, it is a plain call.
+ */
+export declare function runInSegmentTagScope<R, A = undefined>(segmentId: string, fn: (arg: A) => R, arg?: A): R;
+/**
+ * Record that the current owner reads loader `loaderId`'s value (ctx.use),
+ * so the loader's tags follow the reader onto a record. The DSL funnel
+ * starting a loader (resolveLoaderData, inside the DSL loader scope but no
+ * loader body) is not a reader.
+ */
+export declare function linkLoaderTags(loaderId: string, ctx?: RequestContext | undefined): void;
+/**
+ * Record `tags` as loader `loaderId`'s own, read outside its body (its
+ * cache() config tags, or a loader-cache HIT's stored tags):
+ * recordRequestTags with an explicit owner.
+ */
+export declare function recordLoaderTags(loaderId: string, tags: Iterable<string> | undefined, ctx?: RequestContext | undefined): void;
+/**
+ * The tags segment `segmentId`'s content recorded in `ctx`: its own, plus
+ * those of every loader it consumed, transitively.
+ */
+export declare function getSegmentTags(ctx: RequestContext, segmentId: string): ReadonlySet<string>;
+/**
+ * Record `tags` onto each of `segmentIds` (a route cache() HIT replaying
+ * those segments): a record written from the replay, such as a shell
+ * capture's doc record (match-middleware/cache-store.ts), then carries them
+ * as a fresh render's record would. Unarmed, a no-op.
+ */
+export declare function recordSegmentTags(segmentIds: readonly string[], tags: Iterable<string> | undefined, ctx?: RequestContext | undefined): void;
+/**
+ * The owner of the loaders a shell capture bakes (loader-cache.ts bake
+ * lane): their data is shell material that no handler reads, so their tags
+ * reach the shell through this owner (shell-capture.ts), not a record.
+ */
+export declare const SHELL_BAKE_TAG_OWNER: string;
+/** Link loader `loaderId`'s tags to `ownerId` (see SHELL_BAKE_TAG_OWNER). */
+export declare function linkLoaderTagsTo(ownerId: string, loaderId: string, ctx?: RequestContext | undefined): void;
 export declare function normalizeTag(tag: string): string | null;
 export declare function normalizeTags(tags: Iterable<string>): string[];
 /**
@@ -32,14 +80,15 @@ export declare function normalizeTags(tags: Iterable<string>): string[];
  *    cache" in its tree. This is PPR's DERIVATIVE invalidation: PPR is
  *    execution-PRESERVING (everything still runs underneath; only document bytes
  *    are shortcut), so its tags ride this existing instrument rather than a
- *    first-class ppr key/tag API. The shell-expiry invariant holds by
- *    construction — baked ⇒ evicts (bake-lane loaders execute during capture and
- *    record here), hole ⇒ fresh (masked loaders behind a renderable loading()
- *    never execute during capture, so nothing under a hole can tag the shell).
+ *    first-class ppr key/tag API. Whatever renders into the shell records here,
+ *    at capture or on the route's cache() record the capture replays. A masked
+ *    live-lane loader never executes at capture, so its own tags reach a shell
+ *    only through a handler that reads it (ctx.use).
  *
- * Inside a cache() DSL segment the render-callable form records at the DOCUMENT
- * level, not the segment (only the "use cache" runtime enters the tag scope) — a
- * documented semantic, not a filtered one. An empty/whitespace-only tag is
+ * Inside a route cache() boundary the render-callable form also tags that
+ * route's cache() record, which re-records it on every HIT (#957). A loader's
+ * tags reach the record only when a handler consumes its value (ctx.use);
+ * see runInSegmentTagScope / linkLoaderTags. An empty/whitespace-only tag is
  * dropped in both forms (the render-callable form silently, via normalizeTags in
  * recordRequestTags; the scope form with a dev warning).
  *
@@ -63,6 +112,42 @@ export declare function normalizeTags(tags: Iterable<string>): string[];
  */
 export declare function cacheTag(...tags: string[]): void;
 export declare function recordRequestTags(tags: Iterable<string> | undefined, ctx?: RequestContext | undefined): void;
+/**
+ * Arm the per-execution loader tag sets for `ctx`: its match resolved a
+ * loader bound with its own cache() (match-api.ts, bindsLoaderCache), or such
+ * a binding started (loader-cache.ts). A loader-cache MISS captures its own
+ * execution and encodes either way.
+ */
+export declare function armLoaderTagSets(ctx?: RequestContext | undefined): void;
+/** Whether `ctx` records per-execution loader tag sets (armLoaderTagSets). */
+export declare function loaderTagSetsArmed(ctx: RequestContext | undefined): boolean;
+/**
+ * Call `fn`, adding every tag recorded in its async chain
+ * (recordRequestTags, recordLoaderTags) to `into`, until a loader body
+ * started inside it takes over with its own set.
+ */
+export declare function captureRecordedTags<T>(into: Set<string>, fn: () => T): T;
+/** `into` also answers for every tag `from` records. */
+export declare function linkRecordedTags(into: Set<string>, from: Set<string>): void;
+/** Mark a loader's value promise as carrying `tags` (see readValueTags). */
+export declare function tagLoaderValue(value: object, tags: Set<string>): void;
+/** A loader value's tags also answer for `tags` (tagLoaderValue). */
+export declare function linkValueTags(value: object, tags: Set<string>): void;
+/** The current execution reads a loader's value: it takes on its tags. */
+export declare function readValueTags(value: object): void;
+/**
+ * A loader-cache HIT restores the read its entry's MISS recorded onto the
+ * value's set, so an unkeyed reader of the value refuses it as it would on
+ * the MISS (loader-cache.ts identity mark).
+ */
+export declare function markIdentityRead(set: Set<string>, read: LoaderIdentityRead): void;
+/**
+ * The identity read `root`'s execution recorded, or one a set it links to
+ * recorded, nearest first (breadth-first, so the execution's own read wins).
+ */
+export declare function recordedIdentityRead(root: Set<string>): LoaderIdentityRead | undefined;
+/** `root`'s tags plus those of every set it links to, transitively. */
+export declare function flattenRecordedTags(root: Set<string>): Set<string>;
 /**
  * Run a function within a cache tag scope. Any cacheTag() calls inside `fn`
  * accumulate into the returned Set.

package/dist/types/cache/cf/cf-base64.d.ts

@@ -1,4 +1,10 @@
 /** Encode ArrayBuffer to base64 string. */
 export declare function bufferToBase64(buffer: ArrayBuffer): string;
+/** Encode bytes (a view's own region only) to a base64 string. */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/** Decode a base64 string to bytes. Throws on a character outside the alphabet. */
+export declare function base64ToBytes(base64: string): Uint8Array;
+/** The byte length `base64` decodes to (padded or not), without decoding. */
+export declare function base64ByteLength(base64: string): number;
 /** Decode base64 string to ArrayBuffer. */
 export declare function base64ToBuffer(base64: string): ArrayBuffer;

package/dist/types/cache/cf/cf-cache-constants.d.ts

@@ -110,3 +110,14 @@ export declare const EDGE_READ_TIMEOUT_MS = 20;
  * Override per store via `CFCacheStoreOptions.kvReadTimeoutMs` (<= 0 disables).
  */
 export declare const KV_READ_TIMEOUT_MS = 170;
+/**
+ * Floor (ms) on the budget for reading a PPR shell's snapshot, the rest of a
+ * frame whose head and prelude were already read. A document HIT has sent
+ * its prelude by then and cannot render the rest without the snapshot's doc
+ * record, so a timed-out read degrades the HIT (the entry is replaced, the
+ * page reloads once into a MISS; rsc-rendering.ts degradeUnreplayableShell).
+ * That costs far more than waiting, so a slow body read gets at least this
+ * long; `kvReadTimeoutMs` above it wins, and `kvReadTimeoutMs <= 0` still
+ * disables the bound.
+ */
+export declare const SHELL_SNAPSHOT_READ_MIN_TIMEOUT_MS = 1000;