@rangojs/router 0.6.0 → 0.8.0

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

@@ -30,8 +30,6 @@ import type { KVNamespace, CFCacheReadDebugEvent, CFCacheDebug, CFCacheStoreOpti
 export type { KVNamespace, CFCacheReadDebugEvent, CFCacheDebug, CFCacheStoreOptions, };
 export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     readonly supportsPassiveShellReads: true;
-    /** True when constructed without KV: the shell family no-ops (see ctor). */
-    readonly shellFamilyInert?: boolean;
     readonly defaults?: CacheDefaults;
     readonly keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
     private readonly namespace?;
@@ -43,6 +41,8 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     private readonly kvReadTimeoutMs;
     private readonly debug?;
     private readonly kv?;
+    /** True when constructed without KV: no durable tag history (see ctor). */
+    readonly tagHistoryInert?: boolean;
     private readonly onRevalidateTag?;
     private readonly tagPurge?;
     private readonly tagInvalidationTtl?;
@@ -257,15 +257,26 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      */
     setItem(key: string, value: string, options?: CacheItemOptions): Promise<void>;
     /**
-     * Warn once per isolate that the shell family is inert: getShell/putShell
-     * are ONLY called for routes that declared the `ppr` path option, so firing
-     * here (not in the constructor) scopes the warning to apps that actually
-     * use PPR — a KV-less CFCacheStore is a perfectly fine config otherwise.
-     * Without it, the correctness-first fail-open (issue #651) is invisible:
-     * every ppr route is a permanent MISS with zero diagnostics.
+     * Warn once per isolate that a TAGGED shell landed on a store with no
+     * eviction path for it: no KV (markers) and no tagPurge (purge-by-tag).
+     * The shell still caches and expires by ttl+swr, but updateTag()/
+     * revalidateTag() cannot reach it — silent staleness a consumer who tagged
+     * the route clearly did not intend. Fired from putShell (not the
+     * constructor) so an untagged edge-only ppr config stays warning-free.
      * @internal
      */
-    private warnShellFamilyInertOnce;
+    private warnShellTagsNoEvictionOnce;
+    /**
+     * Generation gate for shell writes and the capture scheduler
+     * (isTagsInvalidatedSince). With KV it is the durable marker cascade.
+     * Without KV there are no markers: in purge mode the per-request memo is
+     * the only signal — a capture racing THIS request's updateTag() is still
+     * rejected (read-your-own-writes), while cross-request races are bounded
+     * by ttl+swr exactly like the data families' purge-mode writes. Without
+     * either, fail open (ttl/swr-only semantics, warned at putShell).
+     * @internal
+     */
+    private isShellGenerationInvalidated;
     /**
      * Get a cached PPR shell entry from Cache API, falling through to KV and
      * promoting a valid KV hit. Both tiers store one envelope so the prelude,
@@ -278,13 +289,14 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
         shouldRevalidate?: boolean;
     } | null>;
     /**
-     * Store a PPR shell envelope in Cache API and, when its retention meets KV's
-     * 60-second floor, KV. The shared write is registered with waitUntil and
-     * awaited so invalidation rejection can be acknowledged to the capture
-     * scheduler. Short-lived shells remain useful in L1 even though KV rejects
-     * them.
+     * Store a PPR shell envelope in Cache API and, when KV is configured and
+     * the retention meets its 60-second floor, KV. The shared write is
+     * registered with waitUntil and awaited so invalidation rejection can be
+     * acknowledged to the capture scheduler. Short-lived shells remain useful
+     * in L1 even though KV rejects them; a KV-less store is L1-only by design
+     * (edge-only ppr — see the section comment).
      */
-    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
+    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | "uncacheable" | void>;
     /** Rebuild the public shell entry from its validated storage envelope. */
     private shellEnvelopeToEntry;
     /** Build the Cache API representation of the coupled shell envelope. */
@@ -569,7 +581,9 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * Shell tag-generation gate (SegmentCacheStore.isTagsInvalidatedSince): the
      * SAME KV markers used by runtime envelopes also evict immutable build shells
      * and captures whose write races updateTag(). Thin public wrapper over the
-     * private envelope check (marker >= since, fail open).
+     * shell generation check (marker >= since, fail open); KV-less it degrades
+     * to the per-request memo in purge mode and to false otherwise — see
+     * isShellGenerationInvalidated.
      */
     isTagsInvalidatedSince(tags: string[], sinceMs: number): Promise<boolean>;
     invalidateTags(tags: string[]): Promise<void>;

package/dist/types/cache/shell-snapshot.d.ts

@@ -90,7 +90,7 @@ export declare class RecordingShellStore<TEnv = unknown> implements SegmentCache
         entry: ShellCacheEntry;
         shouldRevalidate?: boolean;
     } | null>;
-    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
+    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | "uncacheable" | void>;
     invalidateTags(tags: string[]): Promise<void>;
 }
 /** True iff `store` is a RecordingShellStore (duck-typed across module copies). */
@@ -181,6 +181,6 @@ export declare class SeededShellStore<TEnv = unknown> implements SegmentCacheSto
         entry: ShellCacheEntry;
         shouldRevalidate?: boolean;
     } | null>;
-    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
+    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | "uncacheable" | void>;
     invalidateTags(tags: string[]): Promise<void>;
 }

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

@@ -161,18 +161,37 @@ export interface SegmentCacheStore<TEnv = unknown> {
      * @param tags - Optional cache tags for invalidation (participates in
      *   invalidateTags via the same tag machinery as the item family)
      * @returns `invalidated` when a generation marker rejected the write,
-     *   `stored` when acknowledged, or void for stores without acknowledgements.
+     *   `stored` when acknowledged, `uncacheable` when the entry can NEVER be
+     *   stored under the current configuration (every retry would refuse
+     *   identically — the capture scheduler backs the key off instead of
+     *   recapturing per MISS; CFCacheStore returns it for a tag set whose
+     *   Cache-Tag header overflows in KV-less purge mode), or void for stores
+     *   without acknowledgements.
      */
-    putShell?(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
+    putShell?(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | "uncacheable" | void>;
     /**
      * Declares the shell family present-but-inert: getShell/putShell exist but
-     * no-op (CFCacheStore without a KV namespace). scheduleShellCapture skips
-     * captures whose only write target is inert — the background render would be
-     * dead work that still occupies the per-isolate serialized capture queue
-     * (a promise-heavy route bakes for seconds per MISS with nothing stored).
-     * Absent/false means the family, when present, actually stores.
+     * no-op (a custom store whose backing tier is conditionally unavailable).
+     * scheduleShellCapture skips captures whose only write target is inert —
+     * the background render would be dead work that still occupies the
+     * per-isolate serialized capture queue (a promise-heavy route bakes for
+     * seconds per MISS with nothing stored). Absent/false means the family,
+     * when present, actually stores. The built-in stores never declare it:
+     * CFCacheStore is L1-only without KV (edge-only ppr), not inert.
      */
     shellFamilyInert?: boolean;
+    /**
+     * Declares isTagsInvalidatedSince present-but-inert: the store implements
+     * the method but has no DURABLE invalidation history behind it (a KV-less
+     * CFCacheStore answers from the per-request memo at best). Runtime shells
+     * tolerate that — purge eviction plus ttl/swr bound their staleness — but
+     * a TAGGED build-manifest shell is immutable with no ttl of its own, so
+     * serving it on such a store would make updateTag() a permanent no-op for
+     * it. The build-shell read-through declines tagged entries on this flag
+     * (same declared-intent-cannot-be-honored doctrine as a store missing the
+     * method entirely). Absent/false means answers are durably backed.
+     */
+    tagHistoryInert?: boolean;
     /**
      * Get a cached function result by key.
      * Returns the serialized value, optional handle data, and staleness flag.

package/dist/types/client-urls/server-projection.d.ts

@@ -1,6 +1,6 @@
 import type { SearchSchemaValue } from "../search-params.js";
 import type { TrailingSlashMode } from "../types.js";
-import type { UrlPatterns } from "../urls/pattern-types.js";
+import type { PartialPrerenderProps, UrlPatterns } from "../urls/pattern-types.js";
 import type { ClientTransitionConfig, ClientUrlPatterns } from "./types.js";
 export interface ClientUrlReference {
     readonly $$typeof: symbol;
@@ -10,6 +10,15 @@ export type ClientUrlDefinitionSource = ClientUrlReference | ClientUrlPatterns;
 export interface ClientUrlProjectionOptions {
     readonly search?: Readonly<Record<string, SearchSchemaValue>>;
     readonly trailingSlash?: TrailingSlashMode;
+    /**
+     * The `ppr` path option, JSON-projected. Materialization passes it onto
+     * the group route's server `path()` verbatim, so the manifest entry
+     * carries it and the runtime shell capture/serve lanes engage exactly as
+     * for a hand-written server route (search is part of shell identity —
+     * the capture render seeds the key's own search, so group static parts
+     * may read useSearchParams).
+     */
+    readonly ppr?: true | Readonly<PartialPrerenderProps>;
 }
 export interface ClientUrlProjectionRoute {
     readonly id: string;

package/dist/types/client-urls/types.d.ts

@@ -15,7 +15,7 @@ export interface ClientUrlItem {
 export type ClientUrlItemInput = ClientUrlItem | readonly ClientUrlItemInput[];
 export type ClientUrlItems = readonly ClientUrlItemInput[];
 export type ClientUrlUse = () => ClientUrlItems;
-export type ClientPathOptions<TName extends string = string, TSearch extends SearchSchema = SearchSchema> = Pick<PathOptions<TName, TSearch>, "name" | "search" | "trailingSlash">;
+export type ClientPathOptions<TName extends string = string, TSearch extends SearchSchema = SearchSchema> = Pick<PathOptions<TName, TSearch>, "name" | "search" | "trailingSlash" | "ppr">;
 export type ClientPathFn = <const TPattern extends string, const TName extends string = UnnamedRoute, const TSearch extends SearchSchema = {}>(pattern: TPattern, component: ComponentType, optionsOrUse?: ClientPathOptions<TName, TSearch> | ClientUrlUse, use?: ClientUrlUse) => ClientUrlItem & TypedRouteItem<TName, TPattern, unknown, TSearch>;
 export type ClientLayoutFn = <const TItems extends ClientUrlItems>(component: ComponentType, children: () => TItems) => ClientUrlItem & TypedLayoutItem<ExtractRoutes<TItems>>;
 /**
@@ -104,7 +104,10 @@ export interface ClientUrlHelpers {
      * Pass `{ stream: "navigation" }` to await this loader before first flush
      * on DOCUMENT requests (see {@link LoaderOptions}) — the opt-in for loaders
      * whose data, handle pushes, or thrown notFound()/redirect() must be in the
-     * SSR'd HTML. Per-loader: a dynamic sibling keeps streaming.
+     * SSR'd HTML. Per-loader: a dynamic sibling keeps streaming. Under a
+     * `ppr` group route the flag BAKES: the loader executes at shell capture
+     * and its settled return freezes into the shell (nested promises stay
+     * live holes).
      */
     readonly loader: <TData>(definition: LoaderDefinition<TData>, optionsOrUse?: LoaderOptions | ClientUrlUse, use?: ClientUrlUse) => ClientUrlItem;
     readonly loading: (component: ReactNode) => ClientUrlItem;

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

@@ -28,15 +28,15 @@ import { type RequestContext } from "../../server/request-context.js";
 export declare function isShellCaptureActive(reqCtx?: RequestContext<any> | undefined): boolean;
 export { createMaskedLoaderPromise } from "./mask-nested.js";
 /**
- * Lane decision for an entry's loaders under PPR (the loading() value decides;
- * docs/design/loader-container-bake.md):
- *
- * - RENDERABLE loading() (the LoaderBoundary Suspense fallback) — the LIVE
- *   lane: masked at capture, guaranteed fresh on every serve. Returns true.
- * - No loading() (absent, or explicitly `false`, incl. `loading(x, { ssr:
- *   false })` under the SSR manifest) — the BAKE lane: the loader executes
- *   during capture, its settled container bakes, nested pending promises hole
- *   at the consumer's own Suspense. Returns false.
+ * Entry-level lane input for an entry's loaders under PPR (the loading()
+ * value; docs/design/loader-container-bake.md). The CAPTURE decision itself
+ * is per LOADER in loader-cache.ts: a `stream: "navigation"`
+ * (awaitBeforeFlush) loader BAKES at capture regardless of this value — the
+ * flag's document promise ("data in the HTML before first flush") maps to
+ * the frozen prelude — while every other loader is LIVE (masked at capture,
+ * fresh on every serve), postponing at loading() or an inline Suspense.
+ * This helper still gates which entries pass a bake segment key for the
+ * legacy loading()-less shape and the HIT-tail seed overlay.
  *
  * Mirrors segment-system's isRenderableLoading so the mask decision and the
  * tree's boundary placement can never disagree.

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

@@ -126,9 +126,10 @@ export interface ShellCaptureDebugEvent {
      *   the capture was not attempted
      * - skip-capacity: the isolate capture queue is full; a later request may retry
      * - skip-inert-store: the resolved store's shell family is missing or
-     *   declared inert (SegmentCacheStore.shellFamilyInert — a CFCacheStore
-     *   without a KV namespace); nothing could store the result, so the
-     *   background render was not scheduled at all
+     *   declared inert (SegmentCacheStore.shellFamilyInert — a custom store
+     *   whose backing tier is unavailable; built-in stores never declare it);
+     *   nothing could store the result, so the background render was not
+     *   scheduled at all
      * - skip-queue-timeout: the capture waited past CAPTURE_QUEUE_WAIT_BUDGET_MS
      *   behind other captures and was dropped unrun (no backoff — the route is
      *   not doomed, the isolate was busy; a later request re-probes). Carries
@@ -160,7 +161,7 @@ export interface ShellCaptureDebugEvent {
     /** A bake-lane loader settled into a shell that uses TTL/SWR-only invalidation. */
     untaggedBake?: true;
     /** Outcome reported by a store that supports shell-write acknowledgements. */
-    storeWrite?: "stored" | "invalidated";
+    storeWrite?: "stored" | "invalidated" | "uncacheable";
     /** Consecutive failure count in the key's backoff entry, when one exists. */
     backoffFailures?: number;
     /** Ms remaining in the key's backoff window, when one exists. */

package/dist/types/urls/path-helper-types.d.ts

@@ -151,7 +151,10 @@ export type PathHelpers<TEnv> = {
      * Pass `{ stream: "navigation" }` to await this loader before first flush
      * on DOCUMENT requests (see {@link LoaderOptions}) — the opt-in for loaders
      * whose data, handle pushes, or thrown notFound()/redirect() must be in the
-     * SSR'd HTML. Per-loader: a dynamic sibling keeps streaming.
+     * SSR'd HTML. Per-loader: a dynamic sibling keeps streaming. Under a
+     * `ppr` route the flag BAKES: the loader executes at shell capture and
+     * its settled return freezes into the shell (nested promises stay live
+     * holes) — the pre-flush promise applied to the prelude.
      */
     loader: <TData>(loaderDef: LoaderDefinition<TData>, optionsOrUse?: LoaderOptions | (() => LoaderUseItem[]), use?: () => LoaderUseItem[]) => LoaderItem;
     /**

package/dist/types/vite/plugins/client-ref-dedup.d.ts

@@ -4,17 +4,6 @@ import type { Plugin } from "vite";
  * Handles scoped packages (@org/name) and nested node_modules.
  * Returns null if the path doesn't contain a valid package reference.
  *
- * NOTE: This is a lossy transformation. It maps a specific submodule path
- * (e.g., pkg/internal/context.js) to the package root (pkg). The load()
- * hook then re-exports via the bare specifier, which resolves to the
- * package entry point. This works for packages that barrel-export their
- * "use client" symbols from the root, which covers the common case
- * (component libraries like @mantine/core, @chakra-ui/react, etc.).
- * Packages whose client symbols are only available from deep subpaths
- * (not re-exported from the root) would lose those symbols after the
- * rewrite. A more precise approach would resolve through the package's
- * exports map to find the correct entry point, but that adds significant
- * complexity for a rare edge case.
  * See: https://github.com/cloudflare/vinext/pull/413
  */
 export declare function extractPackageName(absolutePath: string): string | null;