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

package/src/build/route-types/include-resolution.ts

@@ -97,6 +97,147 @@ function extractNamePrefixFromInclude(node: ts.CallExpression): string | null {
   return null;
 }
 
+/**
+ * True when the thunk transforms its dynamic import via a `.then(cb)` whose
+ * callback selects a NAMED export other than `default` (e.g.
+ * `import("./x").then((m) => m.routes)`). The static resolver walks the module's
+ * `export default`, so such a selector would resolve the WRONG export — the
+ * caller must treat it as unresolvable instead of silently mis-resolving. Returns
+ * false for the supported shapes (no `.then`, `.then((m) => m)`,
+ * `.then((m) => m.default)`) and for any shape it cannot positively identify as a
+ * non-default member selection (those keep the existing resolve-via-default path).
+ */
+function thenSelectsNonDefaultMember(expr: ts.Expression): boolean {
+  const findThenCall = (e: ts.Expression): ts.CallExpression | null => {
+    if (
+      ts.isCallExpression(e) &&
+      ts.isPropertyAccessExpression(e.expression) &&
+      e.expression.name.text === "then"
+    ) {
+      return e;
+    }
+    if (ts.isCallExpression(e) && ts.isPropertyAccessExpression(e.expression)) {
+      return findThenCall(e.expression.expression);
+    }
+    if (ts.isPropertyAccessExpression(e)) return findThenCall(e.expression);
+    if (ts.isParenthesizedExpression(e)) return findThenCall(e.expression);
+    if (ts.isAwaitExpression(e)) return findThenCall(e.expression);
+    return null;
+  };
+
+  const thenCall = findThenCall(expr);
+  if (!thenCall || thenCall.arguments.length === 0) return false;
+  const cb = thenCall.arguments[0];
+  if (!ts.isArrowFunction(cb) && !ts.isFunctionExpression(cb)) return false;
+
+  let ret: ts.Expression | undefined;
+  if (ts.isBlock(cb.body)) {
+    for (const stmt of cb.body.statements) {
+      if (ts.isReturnStatement(stmt) && stmt.expression) {
+        ret = stmt.expression;
+        break;
+      }
+    }
+  } else {
+    ret = cb.body;
+  }
+  if (!ret) return false;
+
+  if (ts.isPropertyAccessExpression(ret)) {
+    return ret.name.text !== "default";
+  }
+  return false;
+}
+
+/**
+ * Extract the module specifier from an async include thunk
+ * (`() => import("./mod")`). Handles arrow and function-expression thunks,
+ * concise or block bodies, and `import("./mod").then(...)` chains. Returns the
+ * specifier string, or null when the second arg is not a dynamic-import thunk
+ * (so the caller can fall through to identifier / factory-call / dynamic-expr
+ * classification).
+ */
+function extractDynamicImportSpecifier(node: ts.Expression): string | null {
+  let body: ts.ConciseBody | undefined;
+  if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+    body = node.body;
+  }
+  if (!body) return null;
+
+  // Concise body is the expression itself; block body: first `return <expr>`.
+  let expr: ts.Expression | undefined;
+  if (ts.isBlock(body)) {
+    for (const stmt of body.statements) {
+      if (ts.isReturnStatement(stmt) && stmt.expression) {
+        expr = stmt.expression;
+        break;
+      }
+    }
+  } else {
+    expr = body;
+  }
+  if (!expr) return null;
+
+  // Descend `import("./mod").then(...)` / parenthesized / await wrappers down to
+  // the `import(...)` call itself.
+  const findImportCall = (e: ts.Expression): ts.CallExpression | null => {
+    if (
+      ts.isCallExpression(e) &&
+      e.expression.kind === ts.SyntaxKind.ImportKeyword
+    ) {
+      return e;
+    }
+    if (ts.isCallExpression(e) && ts.isPropertyAccessExpression(e.expression)) {
+      return findImportCall(e.expression.expression);
+    }
+    if (ts.isPropertyAccessExpression(e)) return findImportCall(e.expression);
+    if (ts.isParenthesizedExpression(e)) return findImportCall(e.expression);
+    if (ts.isAwaitExpression(e)) return findImportCall(e.expression);
+    return null;
+  };
+
+  const importCall = findImportCall(expr);
+  if (!importCall || importCall.arguments.length === 0) return null;
+  // A `.then()` selecting a non-default named export can't be statically
+  // resolved to `export default`; return null so the caller emits a diagnostic
+  // rather than silently generating types for the wrong export.
+  if (thenSelectsNonDefaultMember(expr)) return null;
+  return getStringValue(importCall.arguments[0]);
+}
+
+/**
+ * Resolve a module's `export default` to either a same-file `urls()` variable
+ * name (`export default shopPatterns`) or the inline call block
+ * (`export default urls(...)`). Used to walk async include modules
+ * (`() => import("./mod")`), whose convention is `export default urls(...)`.
+ */
+function resolveDefaultExportTarget(
+  code: string,
+  sourceFile: ts.SourceFile,
+): { variableName?: string; inlineBlock?: string } | null {
+  let result: { variableName?: string; inlineBlock?: string } | null = null;
+
+  function visit(node: ts.Node) {
+    if (result) return;
+    if (ts.isExportAssignment(node) && !node.isExportEquals) {
+      const expr = node.expression;
+      if (ts.isIdentifier(expr)) {
+        result = { variableName: expr.text };
+      } else if (ts.isCallExpression(expr)) {
+        const callee = expr.expression;
+        if (ts.isIdentifier(callee) && callee.text === "urls") {
+          result = { inlineBlock: expr.getText(sourceFile) };
+        }
+      }
+      return;
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return result;
+}
+
 /**
  * Extract include() calls with diagnostics for unresolvable ones.
  * Returns both resolved includes (identifier second args) and unresolvable
@@ -108,7 +249,12 @@ export function extractIncludesWithDiagnostics(
 ): {
   resolved: Array<{
     pathPrefix: string;
-    variableName: string;
+    // Exactly one of variableName / moduleSpecifier is set. variableName is the
+    // classic `include("/api", apiUrls)` identifier form; moduleSpecifier is the
+    // async `include("/api", () => import("./api"))` form, carrying the imported
+    // module path so resolution can walk its `export default`.
+    variableName?: string;
+    moduleSpecifier?: string;
     namePrefix: string | null;
   }>;
   unresolvable: Array<{
@@ -130,7 +276,8 @@ export function extractIncludesWithDiagnostics(
     );
   const resolved: Array<{
     pathPrefix: string;
-    variableName: string;
+    variableName?: string;
+    moduleSpecifier?: string;
     namePrefix: string | null;
   }> = [];
   const unresolvable: Array<{
@@ -158,12 +305,22 @@ export function extractIncludesWithDiagnostics(
         const secondArg = node.arguments[1];
         const namePrefix = extractNamePrefixFromInclude(node);
 
+        const dynamicImportSpec = extractDynamicImportSpecifier(secondArg);
+
         if (ts.isIdentifier(secondArg)) {
           resolved.push({
             pathPrefix,
             variableName: secondArg.text,
             namePrefix,
           });
+        } else if (dynamicImportSpec !== null) {
+          // Async include: `include("/api", () => import("./api"))`. Resolvable
+          // statically by walking the imported module's `export default`.
+          resolved.push({
+            pathPrefix,
+            moduleSpecifier: dynamicImportSpec,
+            namePrefix,
+          });
         } else if (ts.isCallExpression(secondArg)) {
           const callText = secondArg.expression.getText(sourceFile);
           unresolvable.push({
@@ -348,65 +505,120 @@ function buildRouteMapFromBlock(
     }
   }
 
-  for (const { pathPrefix, variableName, namePrefix } of includes) {
+  for (const inc of includes) {
+    const { pathPrefix, namePrefix } = inc;
     let childResult: {
       routes: Record<string, string>;
       searchSchemas: Record<string, Record<string, string>>;
     };
 
-    // Try import resolution first
-    const imported = resolveImportedVariable(fullSource, variableName);
-    if (imported) {
-      const targetFile = resolveImportPath(imported.specifier, filePath);
+    if (inc.moduleSpecifier) {
+      // Async include `() => import("./mod")`: resolve the imported module's
+      // `export default` (convention: `export default urls(...)`), then recurse
+      // into it exactly like an identifier include. Nested include()s inside the
+      // async module — eager or async — resolve through the same recursion.
+      const targetFile = resolveImportPath(inc.moduleSpecifier, filePath);
       if (!targetFile) {
-        if (diagnosticsOut) {
-          diagnosticsOut.push({
-            pathPrefix,
-            namePrefix,
-            reason: "file-not-found",
-            sourceFile: filePath,
-            detail: `import "${imported.specifier}" resolved to no file`,
-          });
-        }
+        diagnosticsOut?.push({
+          pathPrefix,
+          namePrefix,
+          reason: "file-not-found",
+          sourceFile: filePath,
+          detail: `import("${inc.moduleSpecifier}") resolved to no file`,
+        });
         continue;
       }
-      childResult = buildCombinedRouteMapWithSearch(
-        targetFile,
-        imported.exportedName,
-        visited,
-        diagnosticsOut,
-        undefined,
-        memo,
-      );
-    } else {
-      // Check if variable exists as a same-file urls() definition. Share the
-      // full-source SourceFile parse via the memo (block === fullSource hits the
-      // same cache entry already used above).
-      const sameFileBlock = extractUrlsBlockForVariable(
-        fullSource,
-        variableName,
-        parseBlock(memo, fullSource),
+      let targetSource: string;
+      try {
+        targetSource = readSourceMemoized(memo, resolve(targetFile));
+      } catch (err) {
+        // Every other failure path in this function emits a diagnostic; a bare
+        // `continue` here would drop the group from generated types with no
+        // signal at all. Emit one like the siblings do.
+        diagnosticsOut?.push({
+          pathPrefix,
+          namePrefix,
+          reason: "file-not-found",
+          sourceFile: filePath,
+          detail: `import("${inc.moduleSpecifier}") resolved to "${targetFile}" but reading it failed: ${(err as Error)?.message ?? String(err)}`,
+        });
+        continue;
+      }
+      const def = resolveDefaultExportTarget(
+        targetSource,
+        parseBlock(memo, targetSource),
       );
-      if (!sameFileBlock) {
-        if (diagnosticsOut) {
-          diagnosticsOut.push({
-            pathPrefix,
-            namePrefix,
-            reason: "unresolvable-import",
-            sourceFile: filePath,
-            detail: `variable "${variableName}" not found in imports or same-file scope`,
-          });
-        }
+      if (!def) {
+        diagnosticsOut?.push({
+          pathPrefix,
+          namePrefix,
+          reason: "unresolvable-import",
+          sourceFile: filePath,
+          detail: `import("${inc.moduleSpecifier}") has no resolvable \`export default urls(...)\``,
+        });
         continue;
       }
-      childResult = buildCombinedRouteMapWithSearch(
-        filePath,
+      if (def.inlineBlock) {
+        // `export default urls(...)` — recurse into the inline call block.
+        childResult = buildCombinedRouteMapWithSearch(
+          targetFile,
+          undefined,
+          visited,
+          diagnosticsOut,
+          def.inlineBlock,
+          memo,
+        );
+      } else {
+        // `export default <name>`. That name may be a same-file
+        // `const name = urls(...)` OR itself re-exported from an import
+        // (`import { name } from "./x"; export default name`). The shared helper
+        // resolves the import chain first, then falls back to same-file
+        // extraction — without this a re-exported default silently yields empty
+        // routes. Resolution scope is the imported module (targetFile); the
+        // diagnostic is still attributed to the file with the async include.
+        const variableName = def.variableName!;
+        const resolved = resolveIncludedVariable({
+          variableName,
+          resolutionFile: targetFile,
+          resolutionSource: targetSource,
+          reportFile: filePath,
+          memo,
+          visited,
+          diagnosticsOut,
+          pathPrefix,
+          namePrefix,
+          fileNotFoundDetail: (specifier) =>
+            `import("${inc.moduleSpecifier}") default re-exports "${variableName}" from "${specifier}", which resolved to no file`,
+          notFoundDetail: () =>
+            `import("${inc.moduleSpecifier}") default "${variableName}" not found in its imports or same-file scope`,
+        });
+        if (!resolved) continue;
+        childResult = resolved;
+      }
+    } else if (inc.variableName) {
+      // Identifier include `include(prefix, patterns)`: resolve `patterns`
+      // (imported or same-file) through the same shared helper as the async
+      // `export default <name>` form above.
+      const variableName = inc.variableName;
+      const resolved = resolveIncludedVariable({
         variableName,
+        resolutionFile: filePath,
+        resolutionSource: fullSource,
+        reportFile: filePath,
+        memo,
         visited,
         diagnosticsOut,
-        undefined,
-        memo,
-      );
+        pathPrefix,
+        namePrefix,
+        fileNotFoundDetail: (specifier) =>
+          `import "${specifier}" resolved to no file`,
+        notFoundDetail: () =>
+          `variable "${variableName}" not found in imports or same-file scope`,
+      });
+      if (!resolved) continue;
+      childResult = resolved;
+    } else {
+      continue;
     }
 
     // Includes without a name keep their child names private to the mounted
@@ -438,6 +650,94 @@ function buildRouteMapFromBlock(
   return routeMap;
 }
 
+/**
+ * Resolve an include's target VARIABLE to its child route map. The variable may
+ * be imported (`import { name } from "./x"`) or defined in the same file
+ * (`const name = urls(...)`). Shared by the identifier include branch and the
+ * async-include `export default <name>` branch so a future import-resolution fix
+ * cannot silently miss one form. Returns null (with a diagnostic pushed) when
+ * the variable is unresolvable — the caller should skip the include.
+ *
+ * `resolutionFile`/`resolutionSource` is the module whose import + same-file
+ * scope is searched; `reportFile` is the file the diagnostic is attributed to
+ * (the one containing the include() call), which differs for async includes.
+ */
+function resolveIncludedVariable(opts: {
+  variableName: string;
+  resolutionFile: string;
+  resolutionSource: string;
+  reportFile: string;
+  memo: ScanMemo | undefined;
+  visited: Set<string> | undefined;
+  diagnosticsOut: UnresolvableInclude[] | undefined;
+  pathPrefix: string;
+  namePrefix: string | null;
+  fileNotFoundDetail: (specifier: string) => string;
+  notFoundDetail: () => string;
+}): {
+  routes: Record<string, string>;
+  searchSchemas: Record<string, Record<string, string>>;
+} | null {
+  const {
+    variableName,
+    resolutionFile,
+    resolutionSource,
+    reportFile,
+    memo,
+    visited,
+    diagnosticsOut,
+    pathPrefix,
+    namePrefix,
+  } = opts;
+  const imported = resolveImportedVariable(resolutionSource, variableName);
+  if (imported) {
+    const targetFile = resolveImportPath(imported.specifier, resolutionFile);
+    if (!targetFile) {
+      diagnosticsOut?.push({
+        pathPrefix,
+        namePrefix,
+        reason: "file-not-found",
+        sourceFile: reportFile,
+        detail: opts.fileNotFoundDetail(imported.specifier),
+      });
+      return null;
+    }
+    return buildCombinedRouteMapWithSearch(
+      targetFile,
+      imported.exportedName,
+      visited,
+      diagnosticsOut,
+      undefined,
+      memo,
+    );
+  }
+  // Not imported: it must be a same-file `const name = urls(...)`. Confirm it
+  // exists so an undefined name emits a diagnostic instead of empty routes.
+  const sameFileBlock = extractUrlsBlockForVariable(
+    resolutionSource,
+    variableName,
+    parseBlock(memo, resolutionSource),
+  );
+  if (!sameFileBlock) {
+    diagnosticsOut?.push({
+      pathPrefix,
+      namePrefix,
+      reason: "unresolvable-import",
+      sourceFile: reportFile,
+      detail: opts.notFoundDetail(),
+    });
+    return null;
+  }
+  return buildCombinedRouteMapWithSearch(
+    resolutionFile,
+    variableName,
+    visited,
+    diagnosticsOut,
+    undefined,
+    memo,
+  );
+}
+
 /**
  * Build route map and search schemas together.
  * Internal helper used by the include resolution path.

package/src/build/runtime-discovery.ts

@@ -139,7 +139,10 @@ export async function discoverAndWriteRouteTypes(
     for (const [id, router] of registry) {
       if (!router.urlpatterns) continue;
 
-      const manifest = generateManifest(router.urlpatterns, routerMountIndex);
+      const manifest = await generateManifest(
+        router.urlpatterns,
+        routerMountIndex,
+      );
       routerMountIndex++;
 
       // Filter out auto-generated route names that the runtime creates for

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

@@ -2267,6 +2267,28 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv || !this.waitUntil || totalTtl < 60) return;
 
     const kvKey = this.toKVKey(key);
+
+    // Reject an oversized data-segment KV key the same way tag-marker keys are
+    // rejected in invalidateTags(). A key over KV_MAX_KEY_BYTES makes kv.put()
+    // fail, so the segment silently never lands in L2 (KV) and every cold-colo
+    // or TTL-expired read re-renders instead of serving stale. Segment keys can
+    // grow with user-controlled inputs (e.g. a route's search params), so report
+    // a clear, actionable error and skip the doomed write rather than letting it
+    // reject deep inside waitUntil as an opaque cache-write failure.
+    const kvKeyBytes = kvKeyByteLength(kvKey);
+    if (kvKeyBytes > KV_MAX_KEY_BYTES) {
+      reportCacheError(
+        new Error(
+          `cache segment key produces a ${kvKeyBytes}-byte KV key, over the ` +
+            `${KV_MAX_KEY_BYTES}-byte limit; the segment was not persisted to KV (L2). ` +
+            `Reduce the cache-key inputs (e.g. large search params on this route).`,
+        ),
+        "cache-write",
+        "[CFCacheStore] kvSetSegment",
+      );
+      return;
+    }
+
     const expiresAt = staleAt + swrWindow * 1000;
 
     this.waitUntil(() =>

package/src/client.rsc.tsx

@@ -101,8 +101,5 @@ export { useHref } from "./browser/react/use-href.js";
 export { useReverse } from "./browser/react/use-reverse.js";
 
 export { useHandle } from "./browser/react/use-handle.js";
-// Type a deferred-aware consumer narrows: an accumulated entry may be a Promise
-// (a `ctx.use(Handle).defer()` slot) until it resolves.
-export type { DeferredHandleEntry } from "./defer.js";
 
 export { useLocationState } from "./browser/react/location-state.js";

package/src/client.tsx

@@ -389,9 +389,6 @@ export {
 
 export { type Handle } from "./handle.js";
 export { useHandle } from "./browser/react/use-handle.js";
-// Type a deferred-aware consumer narrows: an accumulated entry may be a Promise
-// (a `ctx.use(Handle).defer()` slot) until it resolves.
-export type { DeferredHandleEntry } from "./defer.js";
 
 export { Meta } from "./handles/meta.js";
 export { MetaTags } from "./handles/MetaTags.js";

package/src/defer.ts

@@ -14,14 +14,14 @@
  *   // deep async component, far from ctx:
  *   resolve({ label, href, content });          // identical call, just deferred
  *
- * Under the hood the reserved slot is a Promise the renderer `use()`s; RSC Flight
- * streams it as a late row, so a deferred-aware consumer reading the handle
- * (`useHandle`) sees that entry as a `Promise` until it resolves (see
- * {@link DeferredHandleEntry}). The hazard that guards against bugs: a deferred
- * slot whose resolver is never called would keep the Flight stream — and the HTTP
- * response — open forever. So a deferred auto-resolves to `else` after `timeoutMs`
- * (default {@link DEFAULT_DEFER_TIMEOUT_MS}) if the resolver is never called,
- * degrading gracefully (and warning in dev) instead of hanging the request.
+ * Under the hood the reserved slot is a Promise. Handle values are resolved
+ * before any consumer sees them (resolve-by-default: the full render resolves
+ * server-side, navigation resolves client-side before apply), so `useHandle`
+ * receives the resolved value, never the Promise. The hazard that guards against
+ * bugs: a deferred slot whose resolver is never called would keep the render —
+ * and the HTTP response — waiting forever. So a deferred auto-resolves to `else`
+ * after `timeoutMs` (default {@link DEFAULT_DEFER_TIMEOUT_MS}) if the resolver is
+ * never called, degrading gracefully (and warning in dev) instead of hanging.
  */
 
 /** Default auto-resolve window. Long enough for genuine deep async work, short
@@ -74,24 +74,13 @@ export type HandlePush<TData> = HandlePushFn<TData> & {
    * re-enter the deadlock-guard push-callback scope a direct push thunk gets,
    * because a deferred resolver fires after the handler phase has closed.
    *
-   * The reserved slot appears in the accumulated handle data as a pending
-   * `Promise` until it resolves (see {@link DeferredHandleEntry}); a
-   * deferred-aware consumer narrows thenable entries (`use()`/`await` + null
-   * check) before dereferencing.
+   * The reserved slot is resolved before any consumer reads it
+   * (resolve-by-default), so `useHandle` receives the resolved value (or the
+   * `else` fallback on timeout), never a Promise.
    */
   defer(options?: DeferOptions<TData>): HandlePushFn<TData>;
 };
 
-/**
- * A handle entry a deferred-aware consumer may read from `useHandle`: either a
- * resolved value, or a pending `Promise` that resolves to the value, to `else`,
- * or (when no `else` was given) `undefined` on timeout. Reading code should treat
- * thenable entries as such and narrow before dereferencing.
- */
-export type DeferredHandleEntry<TData> =
-  | TData
-  | Promise<TData | null | undefined>;
-
 // Internal: a timeout-bounded { promise, resolve }. Not part of the public API
 // (the public surface is `ctx.use(Handle).defer()`); exported for `withDefer`
 // and unit tests only. Resolves to `T`, the `else` fallback, or `undefined`.

package/src/handle.ts

@@ -10,8 +10,11 @@ import { isUnderTestRunner } from "./runtime-env.js";
  *
  * @example
  * ```ts
- * // Define a handle (name auto-generated from file + export)
- * export const Breadcrumbs = createHandle<BreadcrumbItem>();
+ * // Define a handle (name auto-generated from file + export).
+ * // Default collect is the identity: one array per segment that pushed.
+ * export const Breadcrumbs = createHandle<BreadcrumbItem, BreadcrumbItem[]>(
+ *   (segments) => segments.flat(), // opt into a single flat list
+ * );
  *
  * // Use in handler
  * const push = ctx.use(Breadcrumbs);
@@ -21,7 +24,7 @@ import { isUnderTestRunner } from "./runtime-env.js";
  * const crumbs = useHandle(Breadcrumbs);
  * ```
  */
-export interface Handle<TData, TAccumulated = TData[]> {
+export interface Handle<TData, TAccumulated = TData[][]> {
   /**
    * Brand to distinguish handles from loaders in ctx.use()
    */
@@ -35,10 +38,13 @@ export interface Handle<TData, TAccumulated = TData[]> {
 }
 
 /**
- * Default collect function that flattens segment arrays into a single array.
+ * Default collect: pass the per-segment data through as-is — one array per segment
+ * that pushed, in segment order. Lossless, so a consumer can tell which/how-many
+ * segments contributed. Callers that want a single flat list opt in with
+ * `createHandle((segments) => segments.flat())`.
  */
-function defaultCollect<T>(segments: T[][]): T[] {
-  return segments.flat();
+function defaultCollect<T>(segments: T[][]): T[][] {
+  return segments;
 }
 
 // Module-level registry mapping $$id to collect functions.
@@ -62,13 +68,22 @@ export function getCollectFn(
  * The $$id is auto-generated by the Vite exposeInternalIds plugin based on
  * file path and export name. No manual naming required.
  *
- * @param collect - Optional collect function (default: flatten into array)
+ * @param collect - Optional collect function. Default: pass the per-segment data
+ *   through as-is (one array per segment that pushed, in segment order). Lossless,
+ *   so a consumer can tell which/how-many segments contributed. Opt into a single
+ *   flat list with `(segments) => segments.flat()`.
  * @param __injectedId - Auto-injected by Vite plugin, do not provide manually
  *
  * @example
  * ```ts
- * // Default: flatten into array
- * export const Breadcrumbs = createHandle<BreadcrumbItem>();
+ * // Default: per-segment grouping, as-is
+ * export const Pushed = createHandle<string>();
+ * // Result type: string[][]  (e.g. [["a"], ["b", "c"]])
+ *
+ * // Opt into a single flat list
+ * export const Breadcrumbs = createHandle<BreadcrumbItem, BreadcrumbItem[]>(
+ *   (segments) => segments.flat()
+ * );
  * // Result type: BreadcrumbItem[]
  *
  * // Custom: last value wins
@@ -83,8 +98,9 @@ export function getCollectFn(
  * );
  * // Result type: MetaTags
  *
- * // Custom: dedupe by href
- * export const Breadcrumbs = createHandle<BreadcrumbItem>(
+ * // Custom: dedupe by href (TAccumulated must be given — a custom collect that
+ * // returns a flat array no longer matches the default TData[][])
+ * export const Breadcrumbs = createHandle<BreadcrumbItem, BreadcrumbItem[]>(
  *   (segments) => {
  *     const all = segments.flat();
  *     return all.filter((item, i) => all.findIndex(x => x.href === item.href) === i);
@@ -92,7 +108,7 @@ export function getCollectFn(
  * );
  * ```
  */
-export function createHandle<TData, TAccumulated = TData[]>(
+export function createHandle<TData, TAccumulated = TData[][]>(
   collect?: (segments: TData[][]) => TAccumulated,
   __injectedId?: string,
 ): Handle<TData, TAccumulated> {
@@ -156,12 +172,18 @@ export function collectHandleData<TData, TAccumulated>(
   data: Record<string, Record<string, unknown[]>>,
   segmentOrder: string[],
 ): TAccumulated {
+  // Fall back to the default (identity, pass-through) collect when none is
+  // registered — e.g. the handle's module was not imported so createHandle() never
+  // ran. This is harmless for a handle that wanted the default, but a handle with a
+  // CUSTOM collect that failed to register silently gets the wrong shape (identity
+  // TData[][]) cast as its declared TAccumulated. The runtime can't tell the two
+  // apart (a Handle only carries $$id), so warn in dev (folded out of production).
   const collectFn = getCollectFn(handle.$$id);
   if (!collectFn && process.env.NODE_ENV !== "production") {
     console.warn(
-      `[rango] Handle "${handle.$$id}" has no registered collect function. ` +
-        `Falling back to flat array. Ensure the handle module is imported so ` +
-        `createHandle() runs and registers the collect function.`,
+      `[rango] Handle "${handle.$$id}" has no registered collect — falling back ` +
+        `to the identity (per-segment data as-is). If this handle declares a ` +
+        `CUSTOM collect, import its module so createHandle() runs where it is read.`,
     );
   }
   const collect = (collectFn ??