@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

package/src/ssr/inject-rsc-eager.ts

@@ -0,0 +1,167 @@
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
+
+/**
+ * Eager Flight-payload injector for the PPR resume path.
+ *
+ * rsc-html-stream's injectRSCPayload starts forwarding Flight chunks only from
+ * inside its first transform() callback — i.e. AFTER the first HTML chunk flows.
+ * That policy exists for the normal document path (a <script> must not precede
+ * the doctype). On a PPR shell HIT it parks the ENTIRE hydration payload: the
+ * resumed fizz render emits its first chunk only when the first hole's data
+ * resolves (live loaders — measured ~1.5s on SFCC-backed pages), while the
+ * Flight root row is ready within ~30ms of the tail render starting. The client
+ * cannot call hydrateRoot until that root row arrives, so the lazy start held
+ * hydration hostage to the slowest loader for no structural reason: the stored
+ * prelude (a complete document through </body></html>) is already on the wire
+ * before the tail, so every tail byte is foster-parented and a Flight <script>
+ * is valid as the FIRST tail byte.
+ *
+ * This injector starts pumping Flight chunks immediately in start(). Ordering
+ * safety is kept by serializing ALL writes through one promise chain: fizz
+ * chunks buffered within a tick flush as one atomic task (same batching idea as
+ * the stock injector — never inject between two partial HTML chunks), and each
+ * Flight script is its own task, so scripts land only between batches. The
+ * trailer is stripped from passing HTML and re-appended once, after both
+ * streams complete — identical to the stock contract.
+ *
+ * RESUME/DATA-VARIANT ONLY. The normal document path must keep the stock
+ * injector: there the first bytes are the document head, and an eager script
+ * would precede the doctype.
+ */
+
+const encoder = new TextEncoder();
+const TRAILER = "</body></html>";
+
+// Escape closing script tags and HTML comments in JS content (ported from
+// rsc-html-stream/server; escapes the "s" instead of the slash so a regexp
+// literal like `0</script/` stays valid JS).
+function escapeScript(script: string): string {
+  return script.replace(/<!--/g, "<\\!--").replace(/<\/(script)/gi, "</\\$1");
+}
+
+function writeScript(
+  controller: TransformStreamDefaultController<Uint8Array>,
+  jsExpr: string,
+  nonce: string | undefined,
+): void {
+  controller.enqueue(
+    encoder.encode(
+      `<script${nonce ? ` nonce="${nonce}"` : ""}>${escapeScript(
+        `(self.__FLIGHT_DATA||=[]).push(${jsExpr})`,
+      )}</script>`,
+    ),
+  );
+}
+
+export function injectRSCPayloadEager(
+  rscStream: ReadableStream<Uint8Array>,
+  options?: { nonce?: string },
+): TransformStream<Uint8Array, Uint8Array> {
+  const nonce = options?.nonce;
+  const htmlDecoder = new TextDecoder();
+  const t0 = INTERNAL_RANGO_DEBUG ? performance.now() : 0;
+  let loggedFirstFlight = false;
+  let loggedFirstHtml = false;
+
+  // All output goes through this chain: one task per Flight script, one task
+  // per buffered-HTML batch. A script can therefore never split a batch.
+  let queue: Promise<void> = Promise.resolve();
+  const enqueueTask = (fn: () => void): Promise<void> => {
+    queue = queue.then(fn);
+    return queue;
+  };
+
+  let buffered: Uint8Array[] = [];
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+  let rscDone: Promise<void> = Promise.resolve();
+
+  function flushBufferedHTML(
+    controller: TransformStreamDefaultController<Uint8Array>,
+  ): void {
+    if (INTERNAL_RANGO_DEBUG && !loggedFirstHtml && buffered.length > 0) {
+      loggedFirstHtml = true;
+      console.log(
+        `[Server][ppr] eager-inject: first resumed HTML batch +${Math.round(performance.now() - t0)}ms`,
+      );
+    }
+    for (const chunk of buffered) {
+      let buf = htmlDecoder.decode(chunk, { stream: true });
+      if (buf.endsWith(TRAILER)) buf = buf.slice(0, -TRAILER.length);
+      controller.enqueue(encoder.encode(buf));
+    }
+    const remaining = htmlDecoder.decode();
+    if (remaining.length) {
+      const out = remaining.endsWith(TRAILER)
+        ? remaining.slice(0, -TRAILER.length)
+        : remaining;
+      controller.enqueue(encoder.encode(out));
+    }
+    buffered.length = 0;
+    timeout = null;
+  }
+
+  async function pumpRSC(
+    controller: TransformStreamDefaultController<Uint8Array>,
+  ): Promise<void> {
+    const rscDecoder = new TextDecoder("utf-8", { fatal: true });
+    const reader = rscStream.getReader();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      // String when the chunk is valid unicode, base64 round-trip otherwise —
+      // same fallback the stock injector uses.
+      let jsExpr: string;
+      try {
+        jsExpr = JSON.stringify(rscDecoder.decode(value, { stream: true }));
+      } catch {
+        const base64 = JSON.stringify(
+          btoa(String.fromCodePoint(...(value as Uint8Array))),
+        );
+        jsExpr = `Uint8Array.from(atob(${base64}), m => m.codePointAt(0))`;
+      }
+      await enqueueTask(() => {
+        if (INTERNAL_RANGO_DEBUG && !loggedFirstFlight) {
+          loggedFirstFlight = true;
+          console.log(
+            `[Server][ppr] eager-inject: first flight script +${Math.round(performance.now() - t0)}ms`,
+          );
+        }
+        writeScript(controller, jsExpr, nonce);
+      });
+    }
+    const remaining = rscDecoder.decode();
+    if (remaining.length) {
+      await enqueueTask(() =>
+        writeScript(controller, JSON.stringify(remaining), nonce),
+      );
+    }
+  }
+
+  return new TransformStream<Uint8Array, Uint8Array>({
+    start(controller) {
+      // The eager part: pump Flight immediately, before any HTML arrives.
+      rscDone = pumpRSC(controller).catch((err) => {
+        try {
+          controller.error(err);
+        } catch {
+          // Stream already errored/closed; nothing to signal.
+        }
+      });
+    },
+    transform(chunk, controller) {
+      buffered.push(chunk);
+      if (timeout) return;
+      // Batch same-tick fizz chunks so a Flight script cannot land between two
+      // partial HTML chunks of one logical write (stock injector's invariant).
+      timeout = setTimeout(() => {
+        void enqueueTask(() => flushBufferedHTML(controller));
+      }, 0);
+    },
+    async flush(controller) {
+      await rscDone;
+      if (timeout) clearTimeout(timeout);
+      await enqueueTask(() => flushBufferedHTML(controller));
+      controller.enqueue(encoder.encode(TRAILER));
+    },
+  });
+}

package/src/ssr/ssr-root.tsx

@@ -0,0 +1,228 @@
+import React from "react";
+import { renderSegments } from "../segment-system.js";
+import {
+  filterSegmentOrder,
+  filterRouteSegmentIds,
+} from "../browser/react/filter-segment-order.js";
+import { ThemeProvider } from "../theme/ThemeProvider.js";
+import { NonceContext } from "../browser/react/nonce-context.js";
+import { NavigationStoreContext } from "../browser/react/context.js";
+import type { NavigationStoreContextValue } from "../browser/react/context.js";
+import type { HandleData } from "../browser/types.js";
+import type { ResolvedSegment } from "../types.js";
+import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
+import type {
+  EventController,
+  DerivedNavigationState,
+} from "../browser/event-controller.js";
+
+/**
+ * createFromReadableStream from @rangojs/router/internal/deps/ssr.
+ * Deserializes the Flight branch used to build the SSR VDOM.
+ */
+export type CreateFromReadableStream = <T>(
+  stream: ReadableStream<Uint8Array>,
+) => Promise<T>;
+
+/**
+ * RSC payload type (minimal interface for SSR)
+ */
+export interface RscPayload {
+  metadata?: {
+    segments?: ResolvedSegment[];
+    rootLayout?: React.ComponentType<{ children: React.ReactNode }>;
+    handles?: AsyncGenerator<HandleData, void, unknown>;
+    matched?: string[];
+    pathname?: string;
+    params?: Record<string, string>;
+    basename?: string;
+    themeConfig?: ResolvedThemeConfig | null;
+    initialTheme?: Theme;
+    version?: string;
+  };
+}
+
+/**
+ * Consume an async generator and return a Promise that resolves with the final value.
+ * Used for SSR where we need to await all handle data before rendering.
+ */
+async function consumeAsyncGenerator(
+  generator: AsyncGenerator<HandleData, void, unknown>,
+): Promise<HandleData> {
+  let lastData: HandleData = {};
+  for await (const data of generator) {
+    lastData = data;
+  }
+  return lastData;
+}
+
+/**
+ * Create a minimal event controller for SSR.
+ * This provides the correct pathname so useNavigation returns the right value during SSR.
+ */
+function createSsrEventController(opts: {
+  pathname: string;
+  params?: Record<string, string>;
+  handleData?: HandleData;
+  matched?: string[];
+}): EventController {
+  const location = new URL(opts.pathname, "http://localhost");
+  let params = opts.params ?? {};
+  const rawMatched = opts.matched ?? [];
+  const handleState = {
+    data: opts.handleData ?? {},
+    segmentOrder: filterSegmentOrder(rawMatched),
+    routeSegmentIds: filterRouteSegmentIds(rawMatched),
+  };
+  const state: DerivedNavigationState = {
+    state: "idle",
+    isStreaming: false,
+    isNavigating: false,
+    location,
+    pendingUrl: null,
+    inflightActions: [],
+  };
+
+  return {
+    getState: () => state,
+    getLocation: () => location,
+    subscribe: () => () => {},
+    getActionState: () => ({
+      state: "idle",
+      actionId: null,
+      payload: null,
+      error: null,
+      result: null,
+    }),
+    subscribeToAction: () => () => {},
+    subscribeToHandles: () => () => {},
+    setHandleData: () => {},
+    getHandleState: () => handleState,
+    setRouteSegmentIds: () => {},
+    setParams: (nextParams) => {
+      params = nextParams;
+    },
+    getParams: () => params,
+    setLocation: () => {},
+    startNavigation: () => {
+      throw new Error("Navigation not supported during SSR");
+    },
+    abortNavigation: () => {},
+    startAction: () => {
+      throw new Error("Actions not supported during SSR");
+    },
+    abortAllActions: () => {},
+    getCurrentNavigation: () => null,
+    getInflightActions: () => new Map(),
+    hadAnyConcurrentActions: () => false,
+  };
+}
+
+/**
+ * Options for {@link createSsrRootComponent}.
+ */
+export interface SsrRootOptions {
+  /** createFromReadableStream for the SSR branch of the Flight stream. */
+  createFromReadableStream: CreateFromReadableStream;
+  /** The Flight stream branch to deserialize into the SSR VDOM. */
+  rscStream: ReadableStream<Uint8Array>;
+  /** Nonce for CSP; propagated to NonceContext. */
+  nonce?: string;
+}
+
+/**
+ * Build the closure component that deserializes the Flight payload, consumes
+ * handles to completion, builds the segment tree, and wraps it in the
+ * NavigationStore / Nonce / Theme providers.
+ *
+ * The full-fizz path (renderHTML), the shell prerender pass (capture), and the
+ * shell resume pass all render this identical tree. `resume` requires the tree
+ * above the postponed holes to match the prerendered tree; rendering the same
+ * builder over the same replayed segments is what makes that hold. A fresh
+ * component instance per pass is fine — replay matches structure, not function
+ * identity.
+ *
+ * The memo slots (payload/handles/context/root) are closure-scoped to the
+ * returned instance, so each render pass memoizes independently. renderSegments
+ * is async: React.use() on a fresh promise would suspend and replay SsrRoot,
+ * re-running the whole segment-tree build unless the promise is memoized.
+ */
+export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
+  const { createFromReadableStream, rscStream, nonce } = opts;
+
+  let payload: Promise<RscPayload> | undefined;
+  let handlesPromise: Promise<HandleData> | undefined;
+  let ssrContextValue: NavigationStoreContextValue | undefined;
+  let rootPromise: Promise<React.ReactNode> | undefined;
+
+  return function SsrRoot() {
+    payload ??= createFromReadableStream<RscPayload>(rscStream);
+    const resolved = React.use(payload);
+
+    const themeConfig = resolved.metadata?.themeConfig ?? null;
+    const pathname = resolved.metadata?.pathname ?? "/";
+
+    // Await handles before creating SSR event controller so hooks can
+    // read request-local handle data via NavigationStoreContext.
+    // The handles property is an async generator that yields on each push
+    // Memoize the promise since async generators can only be iterated once
+    let handleData: HandleData = {};
+    if (resolved.metadata?.handles) {
+      handlesPromise ??= consumeAsyncGenerator(resolved.metadata.handles);
+      handleData = React.use(handlesPromise);
+    }
+
+    // Create SSR context with request-local pathname/params/handles.
+    ssrContextValue ??= {
+      store: null as any,
+      eventController: createSsrEventController({
+        pathname,
+        params: resolved.metadata?.params,
+        handleData,
+        matched: resolved.metadata?.matched,
+      }),
+      navigate: async () => {},
+      refresh: async () => {},
+      version: resolved.metadata?.version,
+      basename: resolved.metadata?.basename,
+    };
+
+    // Build content tree from segments.
+    // Order must match NavigationProvider: NavigationStoreContext > NonceContext > ThemeProvider > content
+    // Memoize like payload/handles above: renderSegments is async, so
+    // React.use() on a fresh promise suspends and replays SsrRoot, which
+    // would re-run the entire segment-tree build on every initial render.
+    rootPromise ??= Promise.resolve(
+      renderSegments(resolved.metadata?.segments ?? [], {
+        rootLayout: resolved.metadata?.rootLayout,
+      }),
+    );
+    let content: React.ReactNode = React.use(rootPromise);
+
+    // Wrap content with ThemeProvider if theme is enabled
+    if (themeConfig) {
+      content = (
+        <ThemeProvider
+          config={themeConfig}
+          initialTheme={resolved.metadata?.initialTheme}
+        >
+          {content}
+        </ThemeProvider>
+      );
+    }
+
+    // Wrap with NonceContext so client components (e.g. MetaTags) can
+    // apply CSP nonces to inline scripts during SSR. Always present to
+    // match the browser-side NavigationProvider tree shape for hydration.
+    content = (
+      <NonceContext.Provider value={nonce}>{content}</NonceContext.Provider>
+    );
+
+    // Wrap with NavigationStoreContext for useNavigation hook
+    return (
+      <NavigationStoreContext.Provider value={ssrContextValue!}>
+        {content}
+      </NavigationStoreContext.Provider>
+    );
+  };
+}

package/src/static-handler.ts

@@ -35,8 +35,7 @@ import type { Handler } from "./types.js";
 import type { StaticBuildContext } from "./prerender.js";
 import type { UseItems, HandlerUseItem } from "./route-types.js";
 import { isCachedFunction } from "./cache/taint.js";
-
-// -- Types ------------------------------------------------------------------
+import { isUnderTestRunner } from "./runtime-env.js";
 
 export interface StaticHandlerOptions {
   /**
@@ -61,7 +60,9 @@ export interface StaticHandlerDefinition<
   use?: () => UseItems<HandlerUseItem>;
 }
 
-// -- Function ---------------------------------------------------------------
+// Process-stable fallback id counter (mirrors createHandle/createLoader/Prerender).
+// Only assigned in bare unit tests where the Vite plugin did not inject an id.
+let runtimeStaticIdCounter = 0;
 
 export function Static<TParams extends Record<string, any> = {}>(
   handler: (ctx: StaticBuildContext) => ReactNode | Promise<ReactNode>,
@@ -69,8 +70,6 @@ export function Static<TParams extends Record<string, any> = {}>(
   __injectedId?: string,
 ): StaticHandlerDefinition<TParams>;
 
-// -- Implementation ---------------------------------------------------------
-
 export function Static<TParams extends Record<string, any>>(
   handler: Function,
   optionsOrId?: StaticHandlerOptions | string,
@@ -94,12 +93,15 @@ export function Static<TParams extends Record<string, any>>(
     id = maybeId ?? "";
   }
 
-  if (!id) {
+  if (!id && !isUnderTestRunner()) {
     throw new Error(
-      "[rango] Static: missing $$id. " +
-        "Ensure the exposeInternalIds Vite plugin is configured.",
+      "[rango] Static: missing $$id. Use `export const X = Static(...)` and " +
+        "ensure the exposeInternalIds Vite plugin is configured.",
     );
   }
+  if (!id) {
+    id = `__rango_runtime_static_${runtimeStaticIdCounter++}`;
+  }
 
   return {
     __brand: "staticHandler" as const,
@@ -109,11 +111,6 @@ export function Static<TParams extends Record<string, any>>(
   };
 }
 
-// -- Type guard -------------------------------------------------------------
-
-/**
- * Type guard to check if a value is a StaticHandlerDefinition.
- */
 export function isStaticHandler(
   value: unknown,
 ): value is StaticHandlerDefinition {

package/src/testing/cache-status.ts

@@ -12,7 +12,14 @@
  * 2. Telemetry path — `createCacheSink` returns a `{ sink, events }` pair the
  *    consumer wires via `createRouter({ telemetry: sink })`. This has ZERO
  *    production surface: no header, just structured `cache.decision` events
- *    (which carry the same coarse `segments` cache signal).
+ *    (which carry the same coarse `segments` cache signal). Assert with
+ *    `assertCacheDecision(events, routeKey, expected)` (the one-call counterpart
+ *    of `assertCacheStatus`) or filter raw via `filterCacheDecisions`.
+ *
+ * Both paths report the SAME coarse route-level signal — pick by TRANSPORT, not
+ * by meaning: the header is the only signal a black-box Playwright `Response`
+ * carries (needs the debug gate ON); the sink is the only zero-production-surface
+ * option and the only one exposing per-segment `shouldRevalidate`.
  *
  * v1 cache status is COARSE (route-level): the router reports a single entry
  * keyed by the route key (the route NAME), not per individual segment.
@@ -37,18 +44,6 @@ export type ExpectedCacheStatus = CacheSegmentStatus;
 /** A target carrying response headers (a Response or a `{ headers }` object). */
 export type CacheStatusTarget = Response | { headers: Headers };
 
-/**
- * Parse an `X-Rango-Cache` header value into a `{ routeKey: status }` map.
- *
- * Header format: `<routeKey>=<status>, <routeKey2>=<status2>`. The key is the
- * route NAME (ctx.routeKey, e.g. `product.detail`), NOT the URL pattern —
- * see assertCacheStatus. Whitespace around entries and the `=` is tolerated.
- * Entries without a status are ignored.
- *
- * @example
- * parseCacheHeader("product.detail=hit, shop.layout=stale")
- * // => { "product.detail": "hit", "shop.layout": "stale" }
- */
 export function parseCacheHeader(
   headerValue: string | null | undefined,
 ): Record<string, string> {
@@ -71,25 +66,6 @@ function getHeaders(target: CacheStatusTarget): Headers {
   return target.headers;
 }
 
-/**
- * Assert that the `X-Rango-Cache` header reports `expected` status for the
- * given route. Throws a descriptive error when the header is missing (gate
- * off), the route is absent, or the status differs.
- *
- * `routeKey` is the route NAME (e.g. `product.detail`), the same id the header
- * carries — NOT the URL pattern (`/products/:id`). The signal is built from
- * ctx.routeKey (telemetry.ts), so a pattern-shaped key never matches.
- *
- * The header is produced by the RSC render pipeline, so get the Response from
- * the router's real fetch path (`router.fetch(...)`), with the debug cache
- * signal gate enabled (`debugCacheSignal: true` or `RANGO_TEST_SIGNALS=1`).
- * NOTE: `dispatch()` is the non-RSC primitive and never emits this header.
- *
- * @example
- * // debugCacheSignal must be enabled on the router under test.
- * const res = await router.fetch(new Request("https://app/products/42"));
- * assertCacheStatus(res, "product.detail", "hit");
- */
 export function assertCacheStatus(
   target: CacheStatusTarget,
   segment: string,
@@ -131,19 +107,6 @@ export interface CacheSink {
   events: TelemetryEvent[];
 }
 
-/**
- * Create a capturing telemetry sink for asserting on `cache.decision` events.
- *
- * This is the ZERO-production-surface path: no response header is emitted, the
- * consumer just inspects the captured events.
- *
- * @example
- * const { sink, events } = createCacheSink();
- * const router = createRouter({ telemetry: sink, ... });
- * // ...send a request through the router's RSC fetch path...
- * const decisions = filterCacheDecisions(events);
- * expect(decisions[0].segments?.[0].cacheStatus).toBe("hit");
- */
 export function createCacheSink(): CacheSink {
   const events: TelemetryEvent[] = [];
   const sink: TelemetrySink = {
@@ -154,9 +117,6 @@ export function createCacheSink(): CacheSink {
   return { sink, events };
 }
 
-/**
- * Filter captured telemetry events down to `cache.decision` events.
- */
 export function filterCacheDecisions(
   events: readonly TelemetryEvent[],
 ): CacheDecisionEvent[] {
@@ -164,3 +124,39 @@ export function filterCacheDecisions(
     (e): e is CacheDecisionEvent => e.type === "cache.decision",
   );
 }
+
+/**
+ * Telemetry-path counterpart of {@link assertCacheStatus}: assert a captured
+ * `cache.decision` event reported `expected` for the segment keyed by `routeKey`
+ * (the route NAME, the same coarse key the header path uses). Throws an
+ * actionable error when no matching segment was captured, or on a mismatch.
+ *
+ * Pairs with {@link createCacheSink}: wire `createRouter({ telemetry: sink })`,
+ * drive an RSC request, then assert against the recorded `events`. This is the
+ * zero-production-surface path (no header to enable). NOTE: `events` accumulates
+ * across requests, so the FIRST matching segment wins — slice or recreate the
+ * sink between requests for the same `routeKey`.
+ */
+export function assertCacheDecision(
+  events: readonly TelemetryEvent[],
+  routeKey: string,
+  expected: ExpectedCacheStatus,
+): void {
+  const segments = filterCacheDecisions(events).flatMap(
+    (d) => d.segments ?? [],
+  );
+  const seg = segments.find((s) => s.id === routeKey);
+  if (seg === undefined) {
+    const known = segments.map((s) => s.id);
+    throw new Error(
+      `assertCacheDecision: no cache.decision segment for routeKey "${routeKey}". ` +
+        `Seen: ${known.length > 0 ? known.join(", ") : "(none)"}. Wire ` +
+        `createRouter({ telemetry: createCacheSink().sink }) and drive an RSC request.`,
+    );
+  }
+  if (seg.cacheStatus !== expected) {
+    throw new Error(
+      `assertCacheDecision: routeKey "${routeKey}" expected "${expected}" but got "${seg.cacheStatus}".`,
+    );
+  }
+}

package/src/testing/collect-handle.ts

@@ -12,32 +12,13 @@
  * 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";
 
-/**
- * Run a handle's collect function on per-segment pushed values.
- *
- * @param handle - The handle whose collect to run.
- * @param segments - Per-segment pushed values: each entry is the array of values
- *   one route segment pushed for this handle, in parent -> child order. Empty
- *   per-segment arrays are dropped before the collect runs, matching production
- *   collectHandleData (a segment that pushed nothing is not passed through).
- * @returns The accumulated value the handle's collect produces.
- *
- * @example
- * ```ts
- * // Default flatten
- * collectHandle(Breadcrumbs, [[{ label: "Home", href: "/" }], [{ label: "P", href: "/p" }]]);
- * // -> [{ label: "Home", href: "/" }, { label: "P", href: "/p" }]
- *
- * // Custom "last wins"
- * const PageTitle = createHandle<string, string>((s) => s.flat().at(-1) ?? "");
- * collectHandle(PageTitle, [["Home"], ["Product"]]); // -> "Product"
- * ```
- */
 export function collectHandle<TData, TAccumulated>(
   handle: Handle<TData, TAccumulated>,
   segments: ReadonlyArray<ReadonlyArray<TData>>,
@@ -46,18 +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;
   }
-
-  // Match production collectHandleData (handle.ts): segments that pushed
-  // nothing (empty arrays) are dropped before the collect runs, so a collect
-  // that inspects segment count or indices sees the same input as at runtime.
-  const nonEmpty = segments.filter((seg) => seg.length > 0) as TData[][];
   return collectFn(nonEmpty);
 }