@rangojs/router 0.20.0 → 0.22.0

package/src/handles/deferred-resolution.ts

@@ -88,9 +88,20 @@ async function resolveValues(values: unknown[]): Promise<unknown[]> {
  * A hung handle promise blocks the full render like any unresolved await (no
  * handle-specific timeout). Partial / action payloads keep streaming via
  * `handleStore.stream()`.
+ *
+ * `recordedOnly` is a PPR shell capture's render (full-payload.ts): the
+ * snapshot is cut down to the pushes the capture's record keeps
+ * (getDataForSegment's `excludeLoaderPushes`, the filter captureHandles
+ * writes the record with). A HIT restores that record and hydrates with it,
+ * so a push the record leaves out must not be in the prelude either: it
+ * rendered an element no HIT's hydration data matched (issue #1035). Which
+ * pushes a record keeps is the capture funnel's decision (shell-capture.ts
+ * deriveShellCaptureContext: today it leaves out a deferred loader push and
+ * one holding a masked promise), not this function's.
  */
 export async function* resolvedHandleStream(
   handleStore: HandleStore,
+  recordedOnly?: boolean,
 ): AsyncGenerator<HandleData, void, unknown> {
   // Drain stream() (NOT getData()) for the converged snapshot: consuming a
   // stream arms the store's late-push guard (LateHandlePushError for pushes
@@ -109,9 +120,34 @@ export async function* resolvedHandleStream(
   for await (const data of handleStore.stream("settled")) {
     snapshot = data;
   }
+  if (recordedOnly) snapshot = recordedHandleData(handleStore, snapshot);
   yield await resolveDeferredHandleValues(snapshot);
 }
 
+/**
+ * `snapshot` without the pushes a record leaves out. A shell capture renders
+ * (resolvedHandleStream) and waits (settleCaptureRecord) on this cut only: a
+ * promise the record drops has no slot in the prelude, and waiting for it
+ * could refuse a capture for a value the shell does not hold.
+ */
+export function recordedHandleData(
+  handleStore: HandleStore,
+  snapshot: HandleData,
+): HandleData {
+  const segmentIds = new Set<string>();
+  for (const handleName in snapshot) {
+    for (const segmentId in snapshot[handleName]) segmentIds.add(segmentId);
+  }
+  const recorded: HandleData = {};
+  for (const segmentId of segmentIds) {
+    const kept = handleStore.getDataForSegment(segmentId, true);
+    for (const handleName in kept) {
+      (recorded[handleName] ??= {})[segmentId] = kept[handleName];
+    }
+  }
+  return recorded;
+}
+
 /**
  * Resolve the deferred (Promise) values in ONE segment's handle bucket
  * (`handleName -> entries[]`). Same shallow + drop-rejections rule as

package/src/internal-suspense-audit.ts

@@ -0,0 +1,12 @@
+// Turns on the suspense audit (suspense-audit.ts) in a dev build. Only this
+// repo sets INTERNAL_RANGO_SUSPENSE_AUDIT: the e2e webServers and fixtures of
+// the router test-app and cloudflare-basic, and the router's vitest config.
+// A consumer's dev server and tests never print the audit's errors.
+//
+// Runtime fallback for non-Vite contexts (vitest, Node). In the Vite pipeline
+// the discovery plugin replaces this module with the build-time-resolved flag
+// (vite/inject-client-debug.ts), as it does for internal-debug.ts. Keep this
+// module to the single export: the transform replaces the whole file.
+export const INTERNAL_RANGO_SUSPENSE_AUDIT: boolean =
+  typeof process !== "undefined" &&
+  Boolean((process as any).env?.INTERNAL_RANGO_SUSPENSE_AUDIT);

package/src/loader-store.ts

@@ -29,9 +29,10 @@
  *     reclaim a bucket that is about to be reused, and is held until any
  *     in-flight load settles.
  *
- * The store is intentionally module-level: each browser tab is its own JS
- * realm, so there is no cross-request pollution. Server renders never mutate
- * the store — the hook falls back to `OutletContext.loaderData`.
+ * Each router's NavigationStore owns one (navigation-store.ts), and hooks reach
+ * it through NavigationStoreContext: the router store is the single source of
+ * truth. Server renders have no store — the hook falls back to
+ * `OutletContext.loaderData`.
  */
 
 import { unwrapsSynchronously } from "./thenable-status.js";
@@ -597,10 +598,4 @@ export class LoaderStore {
   }
 }
 
-/**
- * Module-level singleton. Each browser tab gets its own; SSR never mutates it.
- * The hook falls through to `OutletContext.loaderData` during the server render.
- */
-export const loaderStore: LoaderStore = new LoaderStore();
-
 export const EMPTY_LOADER_SNAPSHOT: LoaderEntry = EMPTY_SNAPSHOT;

package/src/outlet-provider.tsx

@@ -1,8 +1,14 @@
 "use client";
 
-import { useContext, useMemo, type ReactNode } from "react";
+import {
+  useContext,
+  useMemo,
+  type ComponentProps,
+  type ReactNode,
+} from "react";
 import { OutletContext, type OutletContextValue } from "./outlet-context.js";
 import type { ResolvedSegment } from "./types.js";
+import { AuditedOutlet } from "./suspense-audit-react.js";
 
 /**
  * Outlet content provider — stores parent context for useLoader chain walking.
@@ -57,3 +63,21 @@ export function OutletProvider({
     <OutletContext.Provider value={value}>{children}</OutletContext.Provider>
   );
 }
+
+// Dev only (suspense-audit.ts): OutletProvider with the segment's mount
+// tracked under it. Chosen where the element is created, inside a NODE_ENV
+// test: see AuditedRouteContent (route-content-wrapper.tsx).
+export function AuditedOutletProvider({
+  children,
+  ...props
+}: ComponentProps<typeof OutletProvider>): ReactNode {
+  return (
+    <OutletProvider {...props}>
+      {props.segment ? (
+        <AuditedOutlet segmentId={props.segment.id}>{children}</AuditedOutlet>
+      ) : (
+        children
+      )}
+    </OutletProvider>
+  );
+}

package/src/prerender/build-shell-capture.ts

@@ -21,6 +21,7 @@
  */
 
 import type { ShellCacheEntry } from "../cache/types.js";
+import type { RouterVersions } from "../router-versions.js";
 import type { MatchResult } from "../types.js";
 import { MemorySegmentCacheStore } from "../cache/memory-segment-store.js";
 import {
@@ -105,13 +106,14 @@ export interface BuildShellCaptureOptions {
   /** Build-time env bindings (rango plugin buildEnv), if configured. */
   buildEnv?: unknown;
   /**
-   * The MAIN build's version (the version plugin's value folded into the
-   * shipped worker) — NOT the temp server's own version-plugin value. The
-   * serve-side isValidShellHit gate compares entry.buildVersion against the
-   * running worker's ctx.version; stamping the temp server's would make every
-   * build entry an eternal MISS.
+   * The versions the SHIPPED build serves this router with (the build table,
+   * or the router's consumer-set version) — NOT the temp server's own
+   * version-plugin stamp. The serve-side isValidShellHit gate compares
+   * entry.buildVersion against the running worker's ctx.version, which is the
+   * document version; stamping the temp server's would make every build entry
+   * an eternal MISS.
    */
-  buildVersion: string;
+  versions: RouterVersions;
   /**
    * The SSR half, composed by the plugin from the temp server's SSR
    * environment runner (react-dom/static prerender + Flight client), with the
@@ -192,7 +194,7 @@ async function attemptBuildCapture(
     cacheStore: new MemorySegmentCacheStore(),
     themeConfig: router.themeConfig ?? null,
     stateCookieName: router.resolvedStateCookieName,
-    version: opts.buildVersion,
+    versions: opts.versions,
   });
   // Scope registry lookups (root-scope/search-schema) per router during the
   // bake, mirroring rsc/handler.ts on the request path (#762).
@@ -215,7 +217,7 @@ async function attemptBuildCapture(
 
   const descriptor: ShellCaptureDescriptor = {
     key: opts.key,
-    buildVersion: opts.buildVersion,
+    buildVersion: opts.versions.document,
     ttl: opts.ttl,
     swr: opts.swr,
     tags: opts.tags,
@@ -448,7 +450,7 @@ async function runBuildCaptureFinal(
         // buildFullPayload reads only ctx.router.* and ctx.version.
         {
           router,
-          version: opts.buildVersion,
+          version: opts.versions.document,
         } as unknown as HandlerContext<any>,
         url,
         derivedCtx,

package/src/prerender/cloudflare.ts

@@ -0,0 +1,130 @@
+/**
+ * Cloudflare KV writable prerender store (`@rangojs/router/prerender/cloudflare`).
+ *
+ * Backs the durable overlay for on-demand prerender on Cloudflare. Self-contained
+ * (no CFCacheStore construction constraints): entries are stored under the
+ * versioned key `prerender:{routerId}:{version}:{routeName}:{paramHash}`, and
+ * tag invalidation uses the same timestamp-marker technique as the runtime cache
+ * — a per-tag KV marker holding the ms epoch of the last invalidation; a read
+ * treats the entry as stale (never deleted) when any of its tags' markers is at
+ * or after the entry's storedAt.
+ *
+ * Key design constraints (see docs/design/ondemand-prerender.md, Store Model):
+ * - staleAt is SOFT metadata; entries are written with NO KV expirationTtl. Hard
+ *   expiry would delete the entry SWR needs and re-expose older bundled-manifest
+ *   content below the overlay.
+ * - Prerender keys are route + params + variant only — never host-namespaced, so
+ *   a refresh from a different host than the serve request still hits.
+ * - Invalidation is mark-stale, not delete (deleting would re-expose the manifest
+ *   entry as the result of an "invalidation").
+ * - Tag markers use a prerender-specific prefix, separate from the runtime cache's
+ *   `updateTag()`/`revalidateTag()` namespace, and are scoped by router id
+ *   (`{prefix}{encodeURIComponent(routerId)}/{tag}`): routers sharing one KV
+ *   namespace (an app behind a host router) must not mark each other's entries.
+ * - Markers carry no expiry: an entry without a `ttl` never goes stale by
+ *   itself, so an expired marker would silently drop an invalidation.
+ */
+
+import type { KVNamespace } from "../cache/cf/cf-cache-types.js";
+import {
+  lowerStoredEntryStaleAt,
+  serializePrerenderKey,
+  type PrerenderKey,
+  type PrerenderStoredEntry,
+  type WritablePrerenderStore,
+} from "./writable-store.js";
+
+/** Prerender tag markers live in their own namespace, separate from the runtime cache. */
+const PRERENDER_TAG_MARKER_PREFIX = "__rango_pr_tag__/";
+
+export interface KVPrerenderStoreOptions {
+  /** Injectable clock for `markStale` markers in deterministic tests. Defaults to Date.now. */
+  now?: () => number;
+}
+
+/**
+ * Create a {@link WritablePrerenderStore} backed by a Cloudflare KV namespace.
+ *
+ * @example
+ * ```ts
+ * import { createKVPrerenderStore } from "@rangojs/router/prerender/cloudflare";
+ *
+ * createRouter<Env>({
+ *   prerender: (env) => ({
+ *     store: createKVPrerenderStore(env.PRERENDER_KV),
+ *     ttl: 3600,
+ *     onRevalidate: (target, e) => e.PRERENDER_QUEUE.send({ target }),
+ *   }),
+ * });
+ * ```
+ */
+export function createKVPrerenderStore(
+  kv: KVNamespace,
+  options: KVPrerenderStoreOptions = {},
+): WritablePrerenderStore {
+  const now = options.now ?? (() => Date.now());
+  function markerKey(routerId: string, tag: string): string {
+    // An encoded id holds no "/", so the id/tag split is unambiguous.
+    return `${PRERENDER_TAG_MARKER_PREFIX}${encodeURIComponent(routerId)}/${tag}`;
+  }
+
+  async function readTagMarker(
+    routerId: string,
+    tag: string,
+  ): Promise<number | null> {
+    const raw = await kv.get(markerKey(routerId, tag));
+    if (!raw) return null;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : null;
+  }
+
+  return {
+    async get(key: PrerenderKey): Promise<PrerenderStoredEntry | null> {
+      const raw = await kv.get(serializePrerenderKey(key));
+      if (!raw) return null;
+
+      let stored: PrerenderStoredEntry;
+      try {
+        stored = JSON.parse(raw) as PrerenderStoredEntry;
+      } catch {
+        // Corrupt entry: treat as a miss rather than crash the serve path.
+        return null;
+      }
+
+      // Tag invalidation is mark-stale: a tag marked at or after the write
+      // forces the entry stale (it still serves). Shape is verified by the
+      // router; an already-stale entry skips the marker reads.
+      const meta = stored?.meta;
+      if (
+        meta?.tags?.length &&
+        !(meta.staleAt != null && meta.staleAt <= now())
+      ) {
+        const markers = await Promise.all(
+          meta.tags.map((tag) => readTagMarker(key.routerId, tag)),
+        );
+        if (markers.some((m) => m != null && m >= meta.storedAt)) {
+          lowerStoredEntryStaleAt(stored, meta.storedAt);
+        }
+      }
+
+      return stored;
+    },
+
+    async set(key: PrerenderKey, stored: PrerenderStoredEntry): Promise<void> {
+      // No expirationTtl: staleAt is soft metadata (see file header).
+      await kv.put(serializePrerenderKey(key), JSON.stringify(stored));
+    },
+
+    async delete(key: PrerenderKey): Promise<void> {
+      await kv.delete(serializePrerenderKey(key));
+    },
+
+    async markStale(routerId: string, tags: string[]): Promise<void> {
+      if (tags.length === 0) return;
+      const marker = String(now());
+      await Promise.all(
+        tags.map((tag) => kv.put(markerKey(routerId, tag), marker)),
+      );
+    },
+  };
+}