@rangojs/router 0.0.0-experimental.136 → 0.0.0-experimental.138

package/src/browser/react/NavigationProvider.tsx

@@ -32,56 +32,10 @@ import { createAppShellRef, type AppShellRef } from "../app-shell.js";
 import { startConnectionWarmup } from "../connection-warmup.js";
 import { debugLog } from "../logging.js";
 import { cloneHandleData } from "../navigation-store.js";
-import { collectHandleData } from "../../handle.js";
-import { Meta } from "../../handles/meta.js";
-import type { MetaDescriptor } from "../../router/types.js";
 import {
-  HEAD_RESOLVE_HANDLE_NAMES,
-  hasDeferredHandleValue,
+  deferredHandleNames,
   resolveDeferredHandleValues,
-} from "./deferred-handle-resolution.js";
-
-/** Meta handle-name key. Meta is the only head-placed handle whose consumer
- *  use()s a deferred value above the route <Suspense>, so it must be resolved in
- *  the store before apply; every other handle keeps the promise contract. */
-const META = "__rsc_router_meta__";
-
-/**
- * Carry the previous page's COLLECTED Meta forward so the title is kept (no
- * blank) while a deferred Meta resolves on a soft navigation.
- *
- * Why a carry-forward and not just preserving the previous Meta data: handle
- * collection (useHandle/MetaTags) is driven by the event controller's
- * `segmentOrder`, which becomes the NEW route's order so the synchronous
- * breadcrumbs render immediately. The previous route's title lives under a
- * segment that is NOT in the new order, so it would stop being collected — the
- * title would fall back to the layout default. Re-keying the previous COLLECTED
- * descriptors under a segment that IS in the new order keeps them visible.
- *
- * Title descriptors are wrapped as `{ title: { absolute } }` so re-collection
- * under a (possibly template-bearing) new layout does not re-apply a title
- * template to an already-final title. Promise and default (charSet/viewport)
- * descriptors are dropped: Promise ones would suspend MetaTags, and the defaults
- * are re-added by collectMeta.
- */
-function carriedPreviousMeta(prev: MetaDescriptor[]): MetaDescriptor[] {
-  const out: MetaDescriptor[] = [];
-  for (const d of prev) {
-    if (d && typeof (d as { then?: unknown }).then === "function") continue;
-    const base = d as Exclude<MetaDescriptor, Promise<unknown>>;
-    if ("charSet" in base) continue;
-    if ("name" in base && (base as { name?: unknown }).name === "viewport") {
-      continue;
-    }
-    if ("title" in base) {
-      const t = (base as { title: unknown }).title;
-      out.push({ title: { absolute: typeof t === "string" ? t : String(t) } });
-      continue;
-    }
-    out.push(base);
-  }
-  return out;
-}
+} from "../../handles/deferred-resolution.js";
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -144,131 +98,88 @@ async function processHandles(
 
     yieldCount++;
 
-    // Resolve ONLY Meta in the store before applying. Meta is the sole
-    // head-placed handle whose consumer use()s a deferred value above the route
-    // <Suspense>; an uncontained suspension there would revert the just-committed
-    // route and hide its loading fallback. Every other handle (Breadcrumbs,
-    // custom handles) keeps the DeferredHandleEntry contract: its deferred values
-    // reach the consumer AS A PROMISE and are narrowed via isThenable(). So sync
-    // handles AND non-Meta deferred promises apply/stream through immediately —
-    // only Meta is held back and swapped in once resolved.
-    const metaDeferred = hasDeferredHandleValue(
-      handleData,
-      HEAD_RESOLVE_HANDLE_NAMES,
-    );
+    // Resolve-by-default: hold the previous resolved value until this yield's
+    // deferred (Promise) handle values settle, then apply the fully-resolved
+    // snapshot. The hold needs NO extra state — we simply do not touch the store
+    // until the values resolve, so useHandle keeps reading (and showing) the
+    // previous data. A yield with no deferred value applies synchronously.
+    const hasDeferred = deferredHandleNames(handleData).size > 0;
 
-    // Apply now. The non-deferred-Meta case applies the whole snapshot in one
-    // call (Meta included). When Meta IS deferred, replace the deferred Meta with
-    // the previous page's COLLECTED Meta (stale-while-revalidate — never a blank
-    // title) keyed under one of the NEW route's Meta segments, so it stays
-    // collected under the new segment order while the synchronous and non-Meta
-    // deferred handles update with normal cleanup. The resolved Meta is swapped
-    // in by the partial merge below.
-    if (metaDeferred) {
-      const immediate: HandleData = { ...handleData };
-      const metaSegments = handleData[META] ?? {};
-      // Anchor: the last new Meta segment in matched order (collected after the
-      // shared layout, so its carried title wins). Falls back to any new Meta
-      // segment if matched ordering does not surface one.
-      const metaSegmentIds = Object.keys(metaSegments);
-      const ordered = (matched ?? []).filter((id) =>
-        metaSegmentIds.includes(id),
-      );
-      const anchor = ordered.at(-1) ?? metaSegmentIds.at(-1);
-
-      const prevState = eventController.getHandleState();
-      const prevCollected = collectHandleData(
-        Meta,
-        prevState.data,
-        prevState.segmentOrder,
-      ) as MetaDescriptor[];
-      const carried = carriedPreviousMeta(prevCollected);
-
-      if (anchor && carried.length > 0) {
-        immediate[META] = { [anchor]: carried };
-      } else {
-        // No previous Meta to carry and/or no anchor: leave Meta unset until it
-        // resolves (the documented no-previous-Meta behavior).
-        delete immediate[META];
-      }
-      eventController.setHandleData(immediate, matched, isPartial, resolvedIds);
-    } else {
+    if (!hasDeferred) {
       eventController.setHandleData(
         handleData,
         matched,
         isPartial,
         resolvedIds,
       );
-    }
-
-    // Snapshot of the nav's full applied handle state (sync handles, non-Meta
-    // deferred promises, and — when Meta is deferred — the carried previous Meta).
-    // Captured AFTER applying so it reflects what is actually on screen now.
-    const baseSnapshot = cloneHandleData(eventController.getHandleState().data);
-
-    if (!metaDeferred) {
-      // Non-deferred: the applied snapshot is final. Keep the cache in sync and
-      // fresh. The token guard stops a stale same-URL nav writing a newer entry.
+      // Keep the cache fresh. The token guard stops a stale same-URL nav writing
+      // a newer entry.
       if (store.getCacheEntryInstance(historyKey) === myInstance) {
-        store.updateCacheHandleData(historyKey, baseSnapshot, false);
+        store.updateCacheHandleData(
+          historyKey,
+          eventController.getHandleState().data,
+          false,
+        );
       }
       continue;
     }
 
-    // Meta is deferred-pending. The applied snapshot carries the PREVIOUS page's
-    // Meta (or none), not this route's final title, so the cache entry must NOT
-    // be served as fresh on a popstate return. Mark it STALE and handlesPending
-    // (token-guarded). This is the P1 fix: the deferred Meta is a SERVER-side
-    // promise streamed via Flight, so a navigate-away ABORTS the stream and the
-    // client's deferred-Meta promise never resolves — the .then below never
-    // fires. stale makes a popstate return revalidate; handlesPending makes that
+    // The PREVIOUS (held) snapshot — captured before the await so the cache and
+    // the navigate-away merge below reflect what useHandle is still showing.
+    const previousSnapshot = cloneHandleData(
+      eventController.getHandleState().data,
+    );
+
+    // The route HAS changed even though the handle data is held, so update
+    // `routeSegmentIds` (what useSegments reads) now. This leaves `data` /
+    // `segmentOrder` (what useHandle collects over) untouched, so useHandle keeps
+    // holding its previous value while useSegments reflects the new route.
+    eventController.setRouteSegmentIds(matched ?? []);
+
+    // Deferred-pending: the new values are not applied yet (the previous value is
+    // held), so the cache entry must NOT be served as fresh on a popstate return.
+    // Mark it STALE + handlesPending (token-guarded), storing the PREVIOUS (held)
+    // snapshot. P1 fix: a deferred value is a SERVER-side promise streamed via
+    // Flight, so a navigate-away ABORTS the stream and the resolve below never
+    // settles. stale makes a popstate return revalidate; handlesPending makes that
     // revalidation a FULL re-render (no client segment IDs) so the server
-    // re-streams the handles. A diff-only revalidation would omit the unchanged
-    // segments' handles and the deferred Meta would never land — see the
-    // segmentIds branch in navigation-bridge.ts.
+    // re-streams the handles — a diff-only revalidation would omit the unchanged
+    // segments' handles and the deferred value would never land (see the
+    // segmentIds branch in navigation-bridge.ts).
     if (store.getCacheEntryInstance(historyKey) === myInstance) {
-      store.updateCacheHandleData(historyKey, baseSnapshot, true, true);
+      store.updateCacheHandleData(historyKey, previousSnapshot, true, true);
     }
 
-    // Resolve Meta late, then swap it in. The swap is a PARTIAL merge with
-    // resolvedIds=undefined so the stale-clear loop (which scans all handle
-    // names under resolvedIds) cannot wipe the non-Meta buckets we already
-    // applied. When the deferred Meta DOES resolve while this nav still owns the
-    // entry (no navigate-away abort), write the resolved handle data and clear
-    // stale + handlesPending — the entry is now complete, so a popstate return
-    // serves it without revalidating.
-    //
-    // Order-safety: each stream yield is a full cumulative snapshot and a
-    // segment's handle array is atomic, so concurrent Meta resolutions of
-    // different yields write identical per-segment arrays or touch disjoint
-    // segments — neither can clobber the other.
-    void resolveDeferredHandleValues(
-      handleData,
-      HEAD_RESOLVE_HANDLE_NAMES,
-    ).then((resolved) => {
-      const cacheValue = { ...baseSnapshot, [META]: resolved[META] };
-      if (stillLive()) {
-        // Still on the live page: swap Meta in and refresh the cache as fresh.
-        eventController.setHandleData(
-          { [META]: resolved[META] },
-          matched,
-          true,
-          undefined,
-        );
-        store.updateCacheHandleData(
-          historyKey,
-          eventController.getHandleState().data,
-          false,
-          false,
-        );
-      } else if (store.getCacheEntryInstance(historyKey) === myInstance) {
-        // Navigated away, but THIS nav still owns the target cache entry: write
-        // the resolved data and clear stale + handlesPending so a popstate return
-        // is fresh.
-        store.updateCacheHandleData(historyKey, cacheValue, false, false);
-      }
-      // else: a newer nav to the same URL superseded us — do nothing.
-    });
+    // Resolve every deferred value (allSettled; rejected + nullish dropped, sync
+    // values pass through). Each stream yield is a full cumulative snapshot.
+    const resolved = await resolveDeferredHandleValues(handleData);
+
+    if (!stillLive()) {
+      // Navigated away (or a same-URL nav superseded us) while resolving. We do
+      // NOT write `resolved` into the entry. It is THIS yield's snapshot only (on a
+      // partial nav, just the re-resolved segments' buckets), and a correct write
+      // needs setHandleData's nested per-segment merge + matched/resolvedIds
+      // cleanup: HandleData is handleName -> segmentId -> entries[], so a
+      // handle-name-level spread would drop a shared layout bucket (e.g. a
+      // Breadcrumbs layout crumb under L0 when the route pushed under R0) and would
+      // mark stale previous-route buckets fresh. We cannot run that merge here
+      // without touching the now-different live page. Instead leave the entry as it
+      // was marked before the await — stale + handlesPending — so a popstate return
+      // revalidates with a full re-render and re-streams the handles. A newer nav
+      // owning the entry has already overwritten it; nothing to do either way.
+      continue;
+    }
+
+    // Still live: apply the fully-resolved snapshot and refresh the cache fresh.
+    eventController.setHandleData(resolved, matched, isPartial, resolvedIds);
+    if (store.getCacheEntryInstance(historyKey) === myInstance) {
+      store.updateCacheHandleData(
+        historyKey,
+        eventController.getHandleState().data,
+        false,
+        false,
+      );
+    }
   }
 
   // Check again before final updates

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

@@ -558,18 +558,15 @@ export function createServerActionBridge(
           return undefined;
         }
 
-        // Update UI with error boundary
-        startTransition(() => {
-          onUpdate({ root: errorTree, metadata: metadata! });
-        });
-
         // Update segment tracking to exclude error segment IDs
         const errorSegmentIds = new Set(diff);
         const segmentIdsAfterError = segmentState.currentSegmentIds.filter(
           (id) => !errorSegmentIds.has(id),
         );
 
-        // Update store state
+        // Cache (and bump the nav instance) BEFORE the UI update so a deferred
+        // handle pushed by the error-boundary render still applies — see the
+        // "normal" case below for why caching after onUpdate dropped it.
         store.setSegmentIds(segmentIdsAfterError);
         const currentHandleData = eventController.getHandleState().data;
         store.cacheSegmentsForHistory(
@@ -578,6 +575,11 @@ export function createServerActionBridge(
           currentHandleData,
         );
 
+        // Update UI with error boundary
+        startTransition(() => {
+          onUpdate({ root: errorTree, metadata: metadata! });
+        });
+
         // Throw the error so the action promise rejects
         if (returnValue && !returnValue.ok) {
           throw returnValue.data;
@@ -779,10 +781,16 @@ export function createServerActionBridge(
             break;
           }
 
-          startTransition(() => {
-            onUpdate({ root: newTree, metadata: metadata! });
-          });
-
+          // Cache (and bump the nav instance) BEFORE the UI update, matching the
+          // navigation commit order (navigation-transaction.ts:157). processHandles
+          // is spawned by onUpdate and captures the current nav instance up front;
+          // a deferred handle value resolves asynchronously and is only applied
+          // while stillLive() (its captured instance still owns the page). Caching
+          // AFTER onUpdate bumped the instance out from under that in-flight
+          // resolve, so stillLive() turned false and the resolved handle snapshot
+          // was dropped on the action-revalidation path (sync siblings sharing the
+          // yield are held atomically, so they were dropped too).
+          //
           // Location state already applied above (pre-switch). Update store.
           store.setSegmentIds(matched);
           const currentHandleData = eventController.getHandleState().data;
@@ -791,6 +799,10 @@ export function createServerActionBridge(
             fullSegments,
             currentHandleData,
           );
+
+          startTransition(() => {
+            onUpdate({ root: newTree, metadata: metadata! });
+          });
           // Invalidation deferred to finalizeAction() (runs after this caches
           // the fresh segments), suppressed when the action called
           // keepClientCache().