@rangojs/router 0.0.0-experimental.116 → 0.0.0-experimental.118

package/src/browser/response-adapter.ts

@@ -24,6 +24,26 @@ export function emptyResponse(): Response {
   return new Response(null, { status: 200 });
 }
 
+/**
+ * Whether an RSC content response carries a server-stamped router identity
+ * (`X-RSC-Router-Id`) that DIFFERS from the id this client expects (its own
+ * routerId, also sent as `_rsc_rid`). Pre-decode integrity check: lets a caller
+ * refuse a foreign app's payload before `createFromFetch` imports its chunks.
+ *
+ * True ONLY when both the header and the expected id are present and differ. An
+ * absent header (control-only reload/redirect responses are not stamped) or an
+ * absent expected id (e.g. before the client is seeded) is a pass-through —
+ * never a false reject.
+ */
+export function isForeignRouterId(
+  response: Response,
+  expectedId: string | undefined,
+): boolean {
+  const got = response.headers.get("X-RSC-Router-Id");
+  if (!got || !expectedId) return false;
+  return got !== expectedId;
+}
+
 /**
  * Handle the X-RSC-Reload control header (server requests a full page reload on
  * a version mismatch). Returns a short-circuit response when the header is
@@ -56,11 +76,17 @@ export function handleReloadHeader(
  *
  * If the response has no body, onComplete fires synchronously.
  * If signal is provided, an abort cancels the tracking reader.
+ *
+ * `silent` suppresses the stream-error log. Prefetch passes it: a speculative,
+ * low-priority prefetch that is aborted or never consumed can error its stream
+ * benignly, which is not worth surfacing. The fresh-navigation path keeps the
+ * log (default), where a stream error reflects a real failed navigation.
  */
 export function teeWithCompletion(
   response: Response,
   onComplete: () => void,
   signal?: AbortSignal,
+  silent = false,
 ): Response {
   if (!response.body) {
     onComplete();
@@ -84,7 +110,7 @@ export function teeWithCompletion(
       onComplete();
     }
   })().catch((error) => {
-    if (!signal?.aborted) {
+    if (!silent && !signal?.aborted) {
       console.error("[Browser] Error reading tracking stream:", error);
     }
     onComplete();

package/src/browser/rsc-router.tsx

@@ -23,6 +23,7 @@ import type { EventController } from "./event-controller.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 import { initRangoState } from "./rango-state.js";
 import { initPrefetchCache } from "./prefetch/cache.js";
+import { setPrefetchDecoder } from "./prefetch/fetch.js";
 import { setAppVersion } from "./app-version.js";
 import {
   isInterceptSegment,
@@ -116,10 +117,12 @@ export interface BrowserAppContext {
   /** App version for prefetch version mismatch detection */
   version?: string;
   /**
-   * Live app-shell ref. Cross-app navigations replace its contents so the
-   * NavigationProvider and renderSegments pick up the target app's
-   * rootLayout, basename, and version without consumer rerenders. Theme,
-   * warmup, and prefetch TTL are document-lifetime (see AppShell).
+   * App-shell ref, read through on each render so renderSegments and the
+   * NavigationProvider see rootLayout/basename/version without closing over a
+   * stale snapshot. Set once from the initial payload and not swapped within a
+   * session: a cross-app navigation is a full document load (X-RSC-Reload), so
+   * the target app establishes its own shell on load. Theme, warmup, and
+   * prefetch TTL are document-lifetime too (see AppShell).
    */
   appShellRef?: import("./app-shell.js").AppShellRef;
 }
@@ -212,11 +215,11 @@ export async function initBrowserApp(
   // Create composable utilities
   const client = createNavigationClient(deps);
 
-  // Capture the per-router app-shell so cross-app navigations can replace
-  // it atomically. rootLayout, basename, and version live here and are
-  // read through the ref at call time rather than closed over. Theme,
-  // warmup, and prefetch TTL are deliberately excluded — they are
-  // document-lifetime and stay stable across smooth cross-app transitions.
+  // Capture the per-router app-shell. rootLayout, basename, and version live
+  // here and are read through the ref at call time rather than closed over.
+  // It is set once from the initial payload and not swapped within a session:
+  // a cross-app navigation is a full document load (X-RSC-Reload), so the
+  // target app establishes its own shell on load.
   const version = initialPayload.metadata?.version;
   const appShellRef = createAppShellRef({
     routerId: initialPayload.metadata?.routerId,
@@ -238,9 +241,14 @@ export async function initBrowserApp(
     initPrefetchCache(prefetchCacheTTL);
   }
 
-  // Create a bound renderSegments that reads rootLayout through the shell
-  // ref. On app switch the ref is updated before the tree re-renders, so
-  // the new app's Document (rootLayout) replaces the previous one.
+  // Wire the RSC decoder so prefetches decode eagerly and warm the route's
+  // client chunks (same createFromFetch the navigation client uses).
+  setPrefetchDecoder((response) => deps.createFromFetch<RscPayload>(response));
+
+  // Create a bound renderSegments that reads rootLayout through the shell ref.
+  // The shell is set once at init and not swapped within a session (a cross-app
+  // navigation is a full document load), so this always renders this app's
+  // Document; reading through the ref just avoids closing over a stale value.
   const renderSegments = (
     segments: ResolvedSegment[],
     options?: RenderSegmentsOptions,
@@ -280,7 +288,6 @@ export async function initBrowserApp(
     onUpdate: (update) => store.emitUpdate(update),
     renderSegments,
     version: version,
-    appShellRef,
   });
 
   // Connect action redirect → navigation bridge (now that both are initialized)

package/src/browser/server-action-bridge.ts

@@ -27,6 +27,7 @@ import {
   emptyResponse,
   handleReloadHeader,
   teeWithCompletion,
+  isForeignRouterId,
 } from "./response-adapter.js";
 import { mergeLocationState } from "./history-state.js";
 import { classifyActionOutcome } from "./action-coordinator.js";
@@ -260,6 +261,26 @@ export function createServerActionBridge(
           return emptyResponse();
         }
 
+        // Integrity check (pre-decode): a foreign app's action response must
+        // not be decoded + applied here. This is the one decode-and-apply path
+        // the post-decode partial-update guard does NOT cover (the action
+        // bridge has its own createFromFetch -> onUpdate). Ordered after the
+        // reload/redirect handlers, which steer control responses first.
+        // Reloads via window.location.reload() rather than navigating to a
+        // target (as the navigation-client guard does): an action has no
+        // navigation target, so reloading the current URL re-syncs the
+        // document against the server-applied action effect.
+        if (
+          !handle.signal.aborted &&
+          isForeignRouterId(response, store.getRouterId?.())
+        ) {
+          log("action router id mismatch, reloading to re-sync");
+          handle.complete(undefined);
+          resolveStreamComplete();
+          window.location.reload();
+          return new Promise<Response>(() => {});
+        }
+
         // Start streaming immediately when response arrives
         if (!handle.signal.aborted) {
           streamingToken = handle.startStreaming();

package/src/browser/types.ts

@@ -32,8 +32,10 @@ export type HandleData = Record<string, Record<string, unknown[]>>;
 export interface RscMetadata {
   pathname: string;
   segments: ResolvedSegment[];
-  /** Router instance ID. When this changes between navigations, the client
-   *  forces a full tree replacement (app switch via host router). */
+  /** Router instance ID — the current app's identity. A mismatch with the
+   *  client's id (sent as _rsc_rid) is detected server-side and answered with
+   *  X-RSC-Reload (full document load), so the client never swaps apps
+   *  in-session; within a session this always equals the current app. */
   routerId?: string;
   isPartial?: boolean;
   isError?: boolean;
@@ -433,12 +435,6 @@ export interface NavigationStore {
   markCacheAsStale(): void;
   markCacheAsStaleAndBroadcast(): void;
   clearHistoryCache(): void;
-  /**
-   * Clear this tab's nav + prefetch caches without broadcasting or rotating
-   * shared state. Intended for app-switch transitions that affect only this
-   * tab's session.
-   */
-  clearHistoryCacheLocal(): void;
   broadcastCacheInvalidation(): void;
 
   // Cross-tab refresh callback (set by navigation bridge)
@@ -556,13 +552,6 @@ export interface NavigationBridge {
   getVersion(): string | undefined;
   /** Update the RSC version (e.g. after HMR). Clears prefetch cache. */
   updateVersion(newVersion: string): void;
-  /**
-   * Replace the active app-shell snapshot (rootLayout, basename, version)
-   * atomically. Used on cross-app navigations when the response's routerId
-   * indicates the user entered a different app. Theme, warmup, and prefetch
-   * TTL are document-lifetime and not part of the shell.
-   */
-  updateAppShell(next: import("./app-shell.js").AppShell): void;
 }
 
 /**

package/src/cache/cache-runtime.ts

@@ -32,7 +32,11 @@ import {
 export { isCachedFunction };
 import { serializeResult, deserializeResult } from "./segment-codec.js";
 import { createHandleStore } from "../server/handle-store.js";
-import { restoreHandles } from "./handle-snapshot.js";
+import {
+  restoreHandles,
+  encodeHandles,
+  decodeHandles,
+} from "./handle-snapshot.js";
 import { startHandleCapture, type HandleCapture } from "./handle-capture.js";
 import { sortedSearchString } from "./cache-key-utils.js";
 import { runBackground } from "./background-task.js";
@@ -170,7 +174,8 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         if (cached.handles && hasTaintedArgs) {
           const handleStore = requestCtx?._handleStore;
           if (handleStore) {
-            restoreHandles(cached.handles, handleStore);
+            const r = await decodeHandles(cached.handles);
+            if (r) restoreHandles(r, handleStore);
           }
         }
         return result;
@@ -186,7 +191,8 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         if (cached.handles && hasTaintedArgs) {
           const handleStore = requestCtx?._handleStore;
           if (handleStore) {
-            restoreHandles(cached.handles, handleStore);
+            const r = await decodeHandles(cached.handles);
+            if (r) restoreHandles(r, handleStore);
           }
         }
         // Background revalidation — must capture handles if tainted args present.
@@ -242,8 +248,11 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             bgStopCapture?.();
             const serialized = await serializeResult(freshResult);
             if (serialized !== null) {
+              const encodedHandles = bgCapture?.data
+                ? await encodeHandles(bgCapture.data)
+                : undefined;
               await store.setItem!(cacheKey, serialized, {
-                handles: bgCapture?.data,
+                handles: encodedHandles,
                 ttl: profile.ttl,
                 swr: profile.swr,
                 tags: profile.tags,
@@ -317,8 +326,11 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       try {
         const serialized = await serializeResult(result);
         if (serialized !== null) {
+          const encodedHandles = capture?.data
+            ? await encodeHandles(capture.data)
+            : undefined;
           await store.setItem!(cacheKey, serialized, {
-            handles: capture?.data,
+            handles: encodedHandles,
             ttl: profile.ttl,
             swr: profile.swr,
             tags: profile.tags,

package/src/cache/cache-scope.ts

@@ -17,7 +17,12 @@ import {
   _getRequestContext,
 } from "../server/request-context.js";
 import { serializeSegments, deserializeSegments } from "./segment-codec.js";
-import { captureHandles, restoreHandles } from "./handle-snapshot.js";
+import {
+  captureHandles,
+  restoreHandles,
+  encodeHandles,
+  decodeHandles,
+} from "./handle-snapshot.js";
 import { sortedSearchString, sortedRouteParams } from "./cache-key-utils.js";
 import {
   DEFAULT_ROUTE_TTL,
@@ -251,10 +256,16 @@ export class CacheScope {
       // Deserialize segments
       const segments = await deserializeSegments(cached.segments);
 
-      // Replay handle data
+      // Replay handle data. An empty string means the route pushed no handles —
+      // skip the decode entirely (the common case). Otherwise decode the
+      // Flight-encoded blob; a decode failure skips handle restore but keeps the
+      // valid cached segments.
       const handleStore = _getRequestContext()?._handleStore;
-      if (handleStore) {
-        restoreHandles(cached.handles, handleStore);
+      if (handleStore && cached.handles) {
+        const handlesRecord = await decodeHandles(cached.handles);
+        if (handlesRecord) {
+          restoreHandles(handlesRecord, handleStore);
+        }
       }
 
       if (INTERNAL_RANGO_DEBUG) {
@@ -367,12 +378,17 @@ export class CacheScope {
           );
         }
 
-        // Serialize non-loader segments only
-        const serializedSegments = await serializeSegments(nonLoaderSegments);
+        // Serialize segments and Flight-encode handles in parallel. Handles go
+        // through the codec (not raw into the entry) so Promise/ReactNode handle
+        // values survive a JSON-serializing store — see encodeHandles.
+        const [serializedSegments, encodedHandles] = await Promise.all([
+          serializeSegments(nonLoaderSegments),
+          encodeHandles(handles),
+        ]);
 
         const data: CachedEntryData = {
           segments: serializedSegments,
-          handles,
+          handles: encodedHandles,
           expiresAt: Date.now() + ttl * 1000,
         };
 

package/src/cache/cf/cf-cache-store.ts

@@ -116,8 +116,8 @@ interface KVSegmentEnvelope {
 interface KVItemEnvelope {
   /** RSC-serialized return value */
   v: string;
-  /** Handle data */
-  h?: Record<string, Record<string, unknown[]>>;
+  /** RSC-encoded handle data (see handle-snapshot.ts encodeHandles) */
+  h?: string;
   /** When entry becomes stale (ms epoch) */
   s: number;
   /** When entry hard-expires (ms epoch) */
@@ -278,7 +278,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * @internal
    */
   private deriveBaseUrl(): string {
-    const fallback = "https://rsc-cache.internal.com/";
+    const fallback = "https://rsc-dummy-host-1.com/";
 
     const ctx = _getRequestContext();
     if (!ctx?.request) {
@@ -638,7 +638,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
       const data = (await response.json()) as {
         value: string;
-        handles?: Record<string, Record<string, unknown[]>>;
+        handles?: string;
       };
 
       if (!isStale || isRevalidating) {

package/src/cache/handle-snapshot.ts

@@ -9,6 +9,109 @@
 import type { ResolvedSegment } from "../types.js";
 import type { HandleStore } from "../server/handle-store.js";
 import type { SegmentHandleData } from "./types.js";
+import { serializeResult, deserializeResult } from "./segment-codec.js";
+
+/**
+ * Bound on the background cache-write encode of handle data. A pushed handle
+ * value can be a Promise (request-context push-a-promise) or a Promise<ReactNode>
+ * (Breadcrumbs content), which the Flight encoder awaits while draining. The
+ * encode runs in waitUntil/runBackground, so a never-resolving handle value
+ * would otherwise pin a background slot indefinitely; on timeout the entry's
+ * handles coalesce to empty rather than hanging or poisoning the whole write.
+ */
+const HANDLE_ENCODE_TIMEOUT_MS = 5000;
+
+type HandleRecord = Record<string, SegmentHandleData>;
+
+// captureHandles builds a per-segment map keyed by every cached segment id, even
+// segments that pushed nothing (their entry is an empty object). "No handle data"
+// means no segment has any handle, in which case we skip the Flight encode and
+// store an empty string — so the common handle-free route pays neither an encode
+// on write nor a decode on every cache hit.
+function hasHandleData(handles: HandleRecord): boolean {
+  for (const segId in handles) {
+    for (const _ in handles[segId]) return true;
+  }
+  return false;
+}
+
+function withTimeout<T>(p: Promise<T>, ms: number, onTimeout: T): Promise<T> {
+  let timer: ReturnType<typeof setTimeout>;
+  const timeout = new Promise<T>((resolve) => {
+    timer = setTimeout(() => resolve(onTimeout), ms);
+  });
+  return Promise.race([
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        return v;
+      },
+      (e) => {
+        clearTimeout(timer);
+        throw e;
+      },
+    ),
+    timeout,
+  ]);
+}
+
+/**
+ * Encode a captured handle map to a string for cache storage.
+ *
+ * Handle values can be Promises or React elements (e.g. Breadcrumbs `content`).
+ * JSON.stringify destroys those (Promise -> {}, ReactNode non-representable), so
+ * persisting the raw map silently corrupts non-scalar handle values on stores
+ * that serialize to JSON (the Cloudflare cache). Routing the map through the same
+ * RSC-Flight codec the segments/value already use awaits Promises and serializes
+ * React elements, so the stored field is a lossless, JSON-safe string. The
+ * in-memory store keeps the same string by reference, so both backends replay
+ * identical decoded values.
+ */
+export async function encodeHandles(handles: HandleRecord): Promise<string> {
+  // No handle was pushed anywhere — store an empty marker (decoded as "skip").
+  if (!hasHandleData(handles)) return "";
+  return encodeHandleValue(handles);
+}
+
+/**
+ * Decode a stored handle string back to a handle map. Returns null on any
+ * decode failure (e.g. a cross-version entry read under a pinned static
+ * version), so the caller can skip handle restore without discarding the
+ * otherwise-valid cached segments alongside it.
+ */
+export function decodeHandles(encoded: string): Promise<HandleRecord | null> {
+  return decodeHandleValue<HandleRecord>(encoded);
+}
+
+/**
+ * Encode an arbitrary handle-data value to a Flight string. Used directly by the
+ * prerender/static pipeline, whose static path holds a single segment's
+ * `SegmentHandleData` (not a segId-keyed map). Bounded by the same timeout as
+ * encodeHandles; failure/timeout coalesces to "". The caller owns the empty
+ * check (an empty value still encodes to a non-empty Flight string, so skip the
+ * call when there is nothing to store).
+ */
+export async function encodeHandleValue(value: unknown): Promise<string> {
+  const encoded = await withTimeout(
+    serializeResult(value),
+    HANDLE_ENCODE_TIMEOUT_MS,
+    null,
+  );
+  return encoded ?? "";
+}
+
+/**
+ * Decode a Flight-encoded handle-data string. Returns null on any decode
+ * failure so the caller can skip handle restore without discarding valid
+ * cached/prerendered segments.
+ */
+export async function decodeHandleValue<T>(encoded: string): Promise<T | null> {
+  try {
+    return await deserializeResult<T>(encoded);
+  } catch {
+    return null;
+  }
+}
 
 /**
  * Capture handle data for a set of segments from the handle store.

package/src/cache/memory-segment-store.ts

@@ -12,7 +12,6 @@ import type {
   CacheGetResult,
   CacheItemResult,
   CacheItemOptions,
-  SegmentHandleData,
 } from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
 import {
@@ -56,7 +55,9 @@ interface CachedResponseEntry {
 
 interface CachedItemEntry {
   value: string;
-  handles?: Record<string, SegmentHandleData>;
+  /** RSC-encoded handle data (see handle-snapshot.ts encodeHandles). Stored as
+   *  the encoded string by reference, identical to the JSON-serializing stores. */
+  handles?: string;
   expiresAt: number;
   staleAt: number;
 }

package/src/cache/types.ts

@@ -175,8 +175,10 @@ export interface SegmentCacheStore<TEnv = unknown> {
 export interface CacheItemResult {
   /** RSC-serialized return value */
   value: string;
-  /** Handle data captured during execution (breadcrumbs, metadata, etc.) */
-  handles?: Record<string, SegmentHandleData>;
+  /** RSC-encoded handle data captured during execution (breadcrumbs, metadata,
+   *  etc.). Encoded via the Flight codec so Promise/ReactNode handle values
+   *  survive JSON-serializing stores — see handle-snapshot.ts encodeHandles. */
+  handles?: string;
   /** Whether the entry is stale and should be revalidated */
   shouldRevalidate: boolean;
 }
@@ -185,8 +187,8 @@ export interface CacheItemResult {
  * Options for setItem() for function-level caching ("use cache").
  */
 export interface CacheItemOptions {
-  /** Handle data to store alongside the value */
-  handles?: Record<string, SegmentHandleData>;
+  /** RSC-encoded handle data to store alongside the value (see encodeHandles). */
+  handles?: string;
   /** Time-to-live in seconds */
   ttl?: number;
   /** Stale-while-revalidate window in seconds */
@@ -227,8 +229,10 @@ export interface SerializedSegmentData {
 export interface CachedEntryData {
   /** Serialized segments for this entry */
   segments: SerializedSegmentData[];
-  /** Handle data keyed by segment ID */
-  handles: Record<string, SegmentHandleData>;
+  /** RSC-encoded handle data keyed by segment ID. Encoded via the Flight codec
+   *  (see handle-snapshot.ts encodeHandles) so Promise/ReactNode handle values
+   *  round-trip through JSON-serializing stores instead of being flattened. */
+  handles: string;
   /** Expiration timestamp (ms since epoch) */
   expiresAt: number;
 }

package/src/prerender/store.ts

@@ -8,14 +8,14 @@
  * that anchors import() resolution relative to the manifest file.
  */
 
-import type {
-  SerializedSegmentData,
-  SegmentHandleData,
-} from "../cache/types.js";
+import type { SerializedSegmentData } from "../cache/types.js";
 
 export interface PrerenderEntry {
   segments: SerializedSegmentData[];
-  handles: Record<string, SegmentHandleData>;
+  /** RSC-encoded handle map (see handle-snapshot.ts encodeHandles); "" when the
+   *  route pushed no handles. Encoded so Promise/ReactNode handle values survive
+   *  the JSON-serialized build artifact / dev wire, identical to the runtime cache. */
+  handles: string;
 }
 
 export interface PrerenderStore {
@@ -28,7 +28,9 @@ export interface PrerenderStore {
 
 export interface StaticEntry {
   encoded: string;
-  handles: Record<string, unknown[]>;
+  /** RSC-encoded single-segment handle data (see encodeHandleValue); "" when the
+   *  Static handler pushed no handles. */
+  handles: string;
 }
 
 export interface StaticStore {
@@ -174,7 +176,7 @@ export function createStaticStore(): StaticStore | null {
           const val = mod.default;
           // Normalize: string-only (no handles) or { encoded, handles }
           if (typeof val === "string") {
-            return { encoded: val, handles: {} } as StaticEntry;
+            return { encoded: val, handles: "" } as StaticEntry;
           }
           return val as StaticEntry;
         })

package/src/router/lazy-includes.ts

@@ -119,7 +119,7 @@ export function evaluateLazyEntry<TEnv = any>(
   const lazyContext = entry.lazyContext;
 
   // Create a new context for evaluating the lazy patterns.
-  // KNOWN REDUNDANCY (LP3, docs/internal/matching-stability-review.md): this
+  // KNOWN REDUNDANCY (LP3, docs/internal/matching-and-lazy-discovery.md): this
   // runs lazyPatterns.handler() purely to extract `patterns` (route name ->
   // pattern) for matching, and DISCARDS the EntryData `manifest` it builds.
   // loadManifest() then runs the SAME handler again on the first request to