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

package/src/rsc/progressive-enhancement.ts

@@ -15,6 +15,7 @@ import type { MiddlewareFn } from "../router/middleware.js";
 import { executeMiddleware } from "../router/middleware.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import { gateTransitions } from "./transition-gate.js";
+import { resolvedHandleStream } from "../handles/deferred-resolution.js";
 import type { RscPayload, ReactFormState } from "./types.js";
 import {
   createResponseWithMergedHeaders,
@@ -315,7 +316,8 @@ export async function handleProgressiveEnhancement<TEnv>(
         params: match.params,
         isPartial: false,
         rootLayout: ctx.router.rootLayout,
-        handles: handleStore.stream(),
+        // PE full render: resolve deferred handle values server-side.
+        handles: resolvedHandleStream(handleStore),
         version: ctx.version,
         stateCookieName: ctx.router.resolvedStateCookieName,
         themeConfig: ctx.router.themeConfig,
@@ -462,7 +464,8 @@ async function renderPeErrorBoundary<TEnv>(
       isPartial: false,
       isError: true,
       rootLayout: ctx.router.rootLayout,
-      handles: handleStore.stream(),
+      // PE error-boundary full render: resolve deferred handle values server-side.
+      handles: resolvedHandleStream(handleStore),
       version: ctx.version,
       stateCookieName: ctx.router.resolvedStateCookieName,
       themeConfig: ctx.router.themeConfig,

package/src/rsc/rsc-rendering.ts

@@ -22,6 +22,7 @@ import {
 } from "./helpers.js";
 import type { HandlerContext } from "./handler-context.js";
 import { gateTransitions } from "./transition-gate.js";
+import { resolvedHandleStream } from "../handles/deferred-resolution.js";
 
 export function handleRscRendering<TEnv>(
   ctx: HandlerContext<TEnv>,
@@ -78,7 +79,10 @@ async function handleRscRenderingInner<TEnv>(
       params: m.params,
       isPartial: false,
       rootLayout: ctx.router.rootLayout,
-      handles: handleStore.stream(),
+      // Full render: resolve deferred handle values server-side so SSR markup and
+      // the first sync useHandle read see resolved values. Partial payloads below
+      // keep streaming (handleStore.stream()).
+      handles: resolvedHandleStream(handleStore),
       version: ctx.version,
       prefetchCacheTTL: ctx.router.prefetchCacheTTL,
       prefetchCacheSize: ctx.router.prefetchCacheSize,

package/src/ssr/index.tsx

@@ -195,6 +195,7 @@ function createSsrEventController(opts: {
     subscribeToHandles: () => () => {},
     setHandleData: () => {},
     getHandleState: () => handleState,
+    setRouteSegmentIds: () => {},
     setParams: (nextParams) => {
       params = nextParams;
     },

package/src/testing/collect-handle.ts

@@ -12,7 +12,9 @@
  * It relies on createHandle registering the collect even in a bare test (it
  * assigns a runtime fallback id when the Vite plugin did not inject one). If a
  * handle's module was never imported (so createHandle never ran), the collect is
- * unregistered and this falls back to a flat array with a warning.
+ * unregistered and this falls back to the default identity collect — with a
+ * warning, since a CUSTOM collect that failed to register silently returns the
+ * wrong shape.
  */
 
 import { getCollectFn, type Handle } from "../handle.js";
@@ -25,16 +27,20 @@ export function collectHandle<TData, TAccumulated>(
     | ((segments: TData[][]) => TAccumulated)
     | undefined;
 
+  // Drop empty arrays matching production behavior (segment count/indices).
+  const nonEmpty = segments.filter((seg) => seg.length > 0) as TData[][];
+
+  // No registered collect (the handle's module was not imported): fall back to the
+  // default identity collect — the per-segment arrays as-is, mirroring production
+  // collectHandleData. Warn, because a handle with a CUSTOM collect would silently
+  // get the wrong shape (the runtime can't tell it from an intended default).
   if (!collectFn) {
     console.warn(
-      `[rango] collectHandle: handle "${handle.$$id}" has no registered collect ` +
-        `function. Import the handle's module so createHandle() runs. Falling ` +
-        `back to a flat array.`,
+      `[rango] collectHandle: handle "${handle.$$id}" has no registered collect — ` +
+        `falling back to the identity (per-segment data as-is). Import the handle's ` +
+        `module so createHandle() runs if you expected a custom collect.`,
     );
-    return segments.flat() as unknown as TAccumulated;
+    return nonEmpty as unknown as TAccumulated;
   }
-
-  // Drop empty arrays matching production behavior (segment count/indices).
-  const nonEmpty = segments.filter((seg) => seg.length > 0) as TData[][];
   return collectFn(nonEmpty);
 }

package/src/testing/render-route.tsx

@@ -46,6 +46,7 @@ import {
   generateHistoryKey,
 } from "../browser/navigation-store.js";
 import { createEventController } from "../browser/event-controller.js";
+import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
 import type { NavigationStore, NavigationBridge } from "../browser/types.js";
 import type { EventController } from "../browser/event-controller.js";
 import type { ResolvedSegment, RscMetadata } from "../browser/types.js";
@@ -481,8 +482,12 @@ export async function renderRoute(
 
   const eventController = createEventController({ initialLocation: url });
   eventController.setParams(initialMatch.params);
+  // Resolve-by-default: resolve any deferred (Promise) seeded handle values
+  // before applying, so the seeded handles reach collect/useHandle resolved —
+  // matching what the server/client do in a real app.
+  const resolvedSeed = await resolveDeferredHandleValues(handleSeed);
   eventController.setHandleData(
-    handleSeed,
+    resolvedSeed,
     initialSegments.map((s) => s.id),
   );
 

package/src/browser/react/deferred-handle-resolution.ts

@@ -1,75 +0,0 @@
-import type { HandleData } from "../types.js";
-import { isThenable } from "../../handles/is-thenable.js";
-
-/**
- * The set of handle names whose deferred (Promise) values MUST be resolved in
- * the store BEFORE the snapshot is applied during client navigation.
- *
- * The boundary: a handle belongs here only if its consumer `use()`s a promise in
- * <head>, above the route's <Suspense>. Suspending there would revert the
- * just-committed route and hide its loading fallback. Today that is Meta alone
- * (MetaTags lives in <head> and use()s deferred descriptors). Every OTHER handle
- * keeps the public DeferredHandleEntry contract: its deferred value reaches the
- * consumer AS A PROMISE during soft navigation, narrowed via isThenable().
- *
- * If a future head-placed handle starts use()-ing promises, add its name here.
- */
-export const HEAD_RESOLVE_HANDLE_NAMES: readonly string[] = [
-  "__rsc_router_meta__",
-];
-
-/**
- * True when a handle value in this snapshot is a deferred (Promise) value.
- *
- * When `onlyHandleNames` is given, only those handle buckets are considered;
- * deferred values under any other handle are ignored (they pass through to the
- * consumer as promises, by contract).
- */
-export function hasDeferredHandleValue(
-  data: HandleData,
-  onlyHandleNames?: readonly string[],
-): boolean {
-  const scope = onlyHandleNames ? new Set(onlyHandleNames) : null;
-  for (const [handleName, segments] of Object.entries(data)) {
-    if (scope && !scope.has(handleName)) continue;
-    for (const values of Object.values(segments)) {
-      if (values.some(isThenable)) return true;
-    }
-  }
-  return false;
-}
-
-/**
- * Snapshot with deferred (Promise) values awaited; a rejected deferred is
- * dropped (it contributes nothing), mirroring the render-side REJECTED_META.
- * Promise.allSettled treats non-promise values as already-fulfilled, so plain
- * values pass through unchanged.
- *
- * When `onlyHandleNames` is given, ONLY those handle buckets are resolved; every
- * other bucket is copied through by reference (its deferred values keep their
- * promise identity so the consumer can narrow them).
- */
-export async function resolveDeferredHandleValues(
-  data: HandleData,
-  onlyHandleNames?: readonly string[],
-): Promise<HandleData> {
-  const scope = onlyHandleNames ? new Set(onlyHandleNames) : null;
-  const out: HandleData = {};
-  await Promise.all(
-    Object.entries(data).flatMap(([handleName, segments]) => {
-      // Out-of-scope buckets pass through untouched (promise identity kept).
-      if (scope && !scope.has(handleName)) {
-        out[handleName] = segments;
-        return [];
-      }
-      out[handleName] = {};
-      return Object.entries(segments).map(async ([segmentId, values]) => {
-        const settled = await Promise.allSettled(values);
-        out[handleName][segmentId] = settled
-          .filter((r) => r.status === "fulfilled")
-          .map((r) => (r as PromiseFulfilledResult<unknown>).value);
-      });
-    }),
-  );
-  return out;
-}