@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.131

package/src/vite/{ast-handler-extract.ts → utils/ast-handler-extract.ts}

@@ -1,9 +1,5 @@
 import type MagicString from "magic-string";
-import { hashInlineId, buildExportMap } from "./expose-id-utils.ts";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
+import { hashInlineId, buildExportMap } from "../plugins/expose-id-utils.js";
 
 /** Minimal ESTree Program node — avoids importing from `rollup` (not a direct dep). */
 interface ProgramNode {
@@ -27,14 +23,14 @@ export interface HandlerCallSite {
 export interface VirtualHandlerEntry {
   originalModuleId: string;
   imports: string[];
+  declarations: string[];
   handlerCode: string;
   exportName: string;
 }
 
 function isDirectivePrologueStatement(node: any): boolean {
   return (
-    node?.type === "ExpressionStatement" &&
-    typeof node.directive === "string"
+    node?.type === "ExpressionStatement" && typeof node.directive === "string"
   );
 }
 
@@ -48,7 +44,7 @@ function findImportInsertionPos(
 ): number {
   let program: ProgramNode;
   try {
-    program = parseAst(code, { jsx: true });
+    program = parseAst(code, { lang: "tsx" });
   } catch {
     return 0;
   }
@@ -70,10 +66,6 @@ function findImportInsertionPos(
   return insertionPos;
 }
 
-// ---------------------------------------------------------------------------
-// AST walking helper
-// ---------------------------------------------------------------------------
-
 /**
  * Recursively walk an ESTree AST node, calling `enter` on each node.
  * Parent is passed for context.
@@ -99,7 +91,11 @@ function walkNode(
           walkNode(item, node, ancestors, enter);
         }
       }
-    } else if (child && typeof child === "object" && typeof child.type === "string") {
+    } else if (
+      child &&
+      typeof child === "object" &&
+      typeof child.type === "string"
+    ) {
       walkNode(child, node, ancestors, enter);
     }
   }
@@ -107,10 +103,6 @@ function walkNode(
   ancestors.pop();
 }
 
-// ---------------------------------------------------------------------------
-// AST analysis
-// ---------------------------------------------------------------------------
-
 /**
  * Parse the file with Vite's parseAst and find all calls to `fnName`.
  * Distinguishes between `export const X = fnName(...)` (exportInfo set)
@@ -123,7 +115,7 @@ export function findHandlerCalls(
 ): HandlerCallSite[] {
   let program: ProgramNode;
   try {
-    program = parseAst(code, { jsx: true });
+    program = parseAst(code, { lang: "tsx" });
   } catch {
     return [];
   }
@@ -158,8 +150,10 @@ export function findHandlerCalls(
 
     if (parent?.type === "VariableDeclarator" && parent.init === node) {
       // ancestors: [..., ExportNamedDecl, VarDecl, VarDeclarator, CallExpr]
-      const grandParent = ancestors.length >= 3 ? ancestors[ancestors.length - 3] : null;
-      const greatGrandParent = ancestors.length >= 4 ? ancestors[ancestors.length - 4] : null;
+      const grandParent =
+        ancestors.length >= 3 ? ancestors[ancestors.length - 3] : null;
+      const greatGrandParent =
+        ancestors.length >= 4 ? ancestors[ancestors.length - 4] : null;
 
       if (
         grandParent?.type === "VariableDeclaration" &&
@@ -233,7 +227,7 @@ export function getImportedLocalNames(
   parseAst: (code: string, options?: any) => ProgramNode,
 ): Set<string> {
   try {
-    const program = parseAst(code, { jsx: true });
+    const program = parseAst(code, { lang: "tsx" });
     return getImportedLocalNamesFromProgram(program, importedName);
   } catch {
     return new Set<string>();
@@ -250,7 +244,7 @@ export function extractImportDeclarations(
 ): string[] {
   let program: ProgramNode;
   try {
-    program = parseAst(code, { jsx: true });
+    program = parseAst(code, { lang: "tsx" });
   } catch {
     return [];
   }
@@ -264,9 +258,161 @@ export function extractImportDeclarations(
   return imports;
 }
 
-// ---------------------------------------------------------------------------
-// Transform
-// ---------------------------------------------------------------------------
+/**
+ * Check if an expression AST subtree is "inert" -- safe to evaluate eagerly
+ * without referencing import bindings. Inert expressions contain only literals,
+ * arrays/objects of inert values, template literals with inert expressions,
+ * and unary/binary operators on inert operands.
+ *
+ * Function/arrow expressions are NOT inert (they're lazy -- handled separately).
+ * Identifiers and member expressions are NOT inert (may reference imports).
+ *
+ * This check prevents TDZ errors when declarations are moved to virtual
+ * modules that end up in separate Rollup chunks with circular dependencies.
+ */
+function isInertExpression(node: any): boolean {
+  if (!node) return false;
+  switch (node.type) {
+    case "Literal":
+      return true;
+    case "TemplateLiteral":
+      return (node.expressions ?? []).every((e: any) => isInertExpression(e));
+    case "ArrayExpression":
+      return (node.elements ?? []).every(
+        (e: any) => e === null || isInertExpression(e),
+      );
+    case "ObjectExpression":
+      return (node.properties ?? []).every(
+        (p: any) =>
+          p.type === "Property" &&
+          (!p.computed || isInertExpression(p.key)) &&
+          isInertExpression(p.value),
+      );
+    case "UnaryExpression":
+      return isInertExpression(node.argument);
+    case "BinaryExpression":
+      return isInertExpression(node.left) && isInertExpression(node.right);
+    case "ConditionalExpression":
+      return (
+        isInertExpression(node.test) &&
+        isInertExpression(node.consequent) &&
+        isInertExpression(node.alternate)
+      );
+    case "SpreadElement":
+      return isInertExpression(node.argument);
+    default:
+      return false;
+  }
+}
+
+/**
+ * Check if a variable declarator's init is safe for inclusion in a virtual
+ * module. Safe initializers are:
+ *   1. Function/arrow expressions (body is lazy, no TDZ risk)
+ *   2. Inert expressions (no identifier references, no TDZ risk)
+ *
+ * Declarations that reference identifiers at the top level (e.g.
+ * `const VT = React.Fragment`) are NOT safe -- when the virtual module
+ * is bundled into a separate Rollup chunk, circular chunk dependencies
+ * can cause "Cannot access X before initialization" TDZ errors.
+ */
+function isSafeDeclaratorInit(init: any): boolean {
+  if (!init) return true; // `let x;` with no init is safe
+  if (
+    init.type === "ArrowFunctionExpression" ||
+    init.type === "FunctionExpression"
+  ) {
+    return true;
+  }
+  return isInertExpression(init);
+}
+
+/**
+ * Check if all declarators in a VariableDeclaration have safe initializers
+ * and none is a handler call (Static/Prerender).
+ */
+function isSafeVariableDeclaration(
+  node: any,
+  handlerNames: Set<string>,
+): boolean {
+  if (node.type !== "VariableDeclaration") return false;
+  return node.declarations.every(
+    (d: any) =>
+      isSafeDeclaratorInit(d.init) &&
+      !(
+        d.init?.type === "CallExpression" &&
+        d.init.callee?.type === "Identifier" &&
+        handlerNames.has(d.init.callee.name)
+      ),
+  );
+}
+
+/**
+ * Extract module-level declarations that are safe for inclusion in virtual
+ * modules. "Safe" means the declaration can be eagerly evaluated without
+ * referencing import bindings, preventing TDZ errors in separate chunks.
+ *
+ * Included: function declarations, arrow/function expression inits, and
+ * variable inits that are inert (pure literals, arrays, objects).
+ * Excluded: declarations that reference identifiers at init time (may
+ * reference imports causing TDZ), handler call declarations (circular),
+ * class declarations (field initializers can reference imports).
+ *
+ * Strips export keywords so declarations work as plain locals.
+ * Rollup tree-shakes unused declarations from virtual modules.
+ */
+export function extractModuleLevelDeclarations(
+  code: string,
+  parseAst: (code: string, options?: any) => ProgramNode,
+  handlerNames: Set<string>,
+): string[] {
+  let program: ProgramNode;
+  try {
+    program = parseAst(code, { lang: "tsx" });
+  } catch {
+    return [];
+  }
+
+  const declarations: string[] = [];
+  for (const node of program.body as any[]) {
+    // Skip imports (handled by extractImportDeclarations)
+    if (node.type === "ImportDeclaration") continue;
+
+    // VariableDeclaration -- include only if all declarators are safe
+    if (node.type === "VariableDeclaration") {
+      if (isSafeVariableDeclaration(node, handlerNames)) {
+        declarations.push(code.slice(node.start, node.end));
+      }
+      continue;
+    }
+
+    // FunctionDeclaration -- always safe (body is lazy)
+    if (node.type === "FunctionDeclaration") {
+      declarations.push(code.slice(node.start, node.end));
+      continue;
+    }
+
+    // ExportNamedDeclaration with a declaration inside -- strip the export
+    if (node.type === "ExportNamedDeclaration" && node.declaration) {
+      const decl = node.declaration;
+      if (decl.type === "VariableDeclaration") {
+        if (isSafeVariableDeclaration(decl, handlerNames)) {
+          declarations.push(code.slice(decl.start, decl.end));
+        }
+      } else if (decl.type === "FunctionDeclaration") {
+        declarations.push(code.slice(decl.start, decl.end));
+      }
+      continue;
+    }
+
+    // Skip: ClassDeclaration (field initializers can reference imports),
+    // ExportDefaultDeclaration, ExportAllDeclaration,
+    // ExportNamedDeclaration without declaration (re-exports),
+    // ExpressionStatement (side effects), etc.
+  }
+
+  return declarations;
+}
 
 /**
  * Transform inline handler calls by extracting them into virtual modules.
@@ -295,19 +441,30 @@ export function transformInlineHandlers(
 
   const imports = extractImportDeclarations(code, parseAst);
 
-  // Track line occurrences for same-line collision handling
-  const lineCounts = new Map<number, number>();
+  // Collect local names for both Static and Prerender to exclude their
+  // declarations from virtual modules (avoids circular extraction).
+  const staticNames = getImportedLocalNames(code, "Static", parseAst);
+  const prerenderNames = getImportedLocalNames(code, "Prerender", parseAst);
+  const handlerNames = new Set([...staticNames, ...prerenderNames]);
+  const declarations = extractModuleLevelDeclarations(
+    code,
+    parseAst,
+    handlerNames,
+  );
 
   // Collect all import statements to prepend
   const importStatements: string[] = [];
 
-  for (const site of inlineSites) {
-    const lineCount = lineCounts.get(site.lineNumber) ?? 0;
-    lineCounts.set(site.lineNumber, lineCount + 1);
-
-    const hash = hashInlineId(filePath, site.lineNumber, lineCount);
+  for (const [siteIndex, site] of inlineSites.entries()) {
+    // Key the extracted handler on its source-order index (per fnName), NOT its
+    // line number. The id flows into BOTH the export name and the virtual module
+    // path (which hashId hashes for the runtime $$id), and line numbers shift
+    // between the prerender and production build contexts. The index is invariant
+    // to those shifts, keeping the prerender manifest key == the runtime id.
+    const hash = hashInlineId(filePath, fnName, siteIndex);
     const exportName = `__sh_${hash}`;
-    const virtualId = `\0${virtualPrefix}${filePath}:${site.lineNumber}${lineCount > 0 ? `:${lineCount}` : ""}`;
+    const idSuffix = `${filePath}:${fnName}:${siteIndex}`;
+    const virtualId = `\0${virtualPrefix}${idSuffix}`;
 
     // Extract the full handler call expression text
     const handlerCode = code.slice(site.callStart, site.callEnd);
@@ -316,6 +473,7 @@ export function transformInlineHandlers(
     virtualRegistry.set(virtualId, {
       originalModuleId: moduleId,
       imports,
+      declarations,
       handlerCode,
       exportName,
     });
@@ -324,10 +482,8 @@ export function transformInlineHandlers(
     s.overwrite(site.callStart, site.callEnd, exportName);
 
     // Build the import specifier for this virtual module
-    const importId = `${virtualPrefix}${filePath}:${site.lineNumber}${lineCount > 0 ? `:${lineCount}` : ""}`;
-    importStatements.push(
-      `import { ${exportName} } from "${importId}";`,
-    );
+    const importId = `${virtualPrefix}${idSuffix}`;
+    importStatements.push(`import { ${exportName} } from "${importId}";`);
   }
 
   // Insert imports after directive prologue + existing import block

package/src/vite/utils/banner.ts

@@ -0,0 +1,36 @@
+import packageJson from "../../../package.json";
+
+export const rangoVersion: string = packageJson.version;
+
+let _bannerPrinted = false;
+
+export function printBanner(
+  mode: "dev" | "build" | "preview",
+  preset: string,
+  version: string,
+): void {
+  if (_bannerPrinted) return;
+  _bannerPrinted = true;
+
+  // ANSI codes
+  const dim = "\x1b[2m";
+  const bold = "\x1b[1m";
+  const reset = "\x1b[0m";
+
+  const banner = `
+${dim}  ✦        ✦          ✧.           .          .${reset}
+${dim} ╱${reset}    ${bold}╔═╗${reset}${dim}      *      ╱                   ✦             *${reset}
+${dim}      ${reset}${bold}║ ║${reset} ${bold}╔═╗${reset}${dim}                    *                ✧.   ╱${reset}
+${dim}   ${reset}${bold}╔╗ ║ ║ ║ ║${reset}${dim}                          *               ╱${reset}
+${dim}   ${reset}${bold}║║ ║ ║ ║ ║  ╦═╗╔═╗╔╗╔╔═╗╔═╗${reset}${dim}             ✧              ✦${reset}
+${dim}   ${reset}${bold}║║ ║ ╠═╝ ║  ╠╦╝╠═╣║║║║ ╦║ ║${reset}${dim}        *           ✧${reset}
+${dim}   ${reset}${bold}║╚═╝ ╔═══╝  ╩╚═╩ ╩╝╚╝╚═╝╚═╝${reset}${dim}            ✦          .      *${reset}
+${dim}   ${reset}${bold}╚══╗ ║${reset}${dim} *      RSC Wrangler         ✧                ✦${reset}
+${dim}  *   ${reset}${bold}║ ║${reset}${dim}                          *            ✧.    ╱${reset}
+${dim}   ${reset}${bold}═══╝ ╚════${reset}${dim}                           ✦            *${reset}
+
+   v${version} · ${preset} · ${mode}
+`;
+
+  console.log(banner);
+}

package/src/vite/utils/bundle-analysis.ts

@@ -0,0 +1,132 @@
+import {
+  skipStringOrComment,
+  escapeRegExp,
+} from "../plugins/expose-id-utils.js";
+
+/**
+ * Find matching close paren in bundled code using depth counting.
+ * Uses skipStringOrComment to correctly handle template literals, comments, and nested strings.
+ * @internal Exported for testing only.
+ */
+export function findMatchingParenInBundle(
+  code: string,
+  openParenPos: number,
+): number {
+  let depth = 1;
+  let pos = openParenPos;
+  while (pos < code.length && depth > 0) {
+    const skipped = skipStringOrComment(code, pos);
+    if (skipped > pos) {
+      pos = skipped;
+      continue;
+    }
+    if (code[pos] === "(") depth++;
+    else if (code[pos] === ")") depth--;
+    pos++;
+  }
+  return depth === 0 ? pos : -1;
+}
+
+/**
+ * Scan a bundled chunk for handler exports and extract their names + $$id values.
+ * Optionally detects passthrough flag. @internal Exported for testing only.
+ */
+export function extractHandlerExportsFromChunk(
+  chunkCode: string,
+  handlerModules: Map<string, string[]>,
+  fnName: string,
+  detectPassthrough: boolean,
+): Array<{ name: string; handlerId: string; passthrough: boolean }> {
+  const handlers: Array<{
+    name: string;
+    handlerId: string;
+    passthrough: boolean;
+  }> = [];
+
+  for (const [, handlerNames] of handlerModules) {
+    for (const name of handlerNames) {
+      const eName = escapeRegExp(name);
+      const idPattern = new RegExp(
+        `(?<![a-zA-Z0-9_])${eName}\\.\\$\\$id\\s*=\\s*"([^"]+)"`,
+      );
+      const match = chunkCode.match(idPattern);
+      if (!match) continue;
+
+      let isPassthrough = false;
+      if (detectPassthrough) {
+        const eFnName = escapeRegExp(fnName);
+        const callStartRe = new RegExp(
+          `(?:const|let|var)\\s+${eName}\\s*=\\s*${eFnName}\\s*(?:<[^>]*>)?\\s*\\(`,
+        );
+        const callStart = callStartRe.exec(chunkCode);
+        if (callStart) {
+          const afterOpen = callStart.index + callStart[0].length;
+          const closePos = findMatchingParenInBundle(chunkCode, afterOpen);
+          if (closePos !== -1) {
+            const callBody = chunkCode.slice(callStart.index, closePos);
+            isPassthrough = /passthrough\s*:\s*(!0|true)/.test(callBody); // !0 is minified true
+          }
+        }
+      }
+      handlers.push({ name, handlerId: match[1], passthrough: isPassthrough });
+    }
+  }
+
+  return handlers;
+}
+
+/**
+ * Evict handler code from a bundled chunk, replacing full call expressions with stubs.
+ * Returns the modified code and bytes saved, or null if no changes were made.
+ * @internal Exported for testing only.
+ */
+export function evictHandlerCode(
+  code: string,
+  exports: Array<{ name: string; handlerId: string; passthrough?: boolean }>,
+  fnName: string,
+  brand: string,
+): { code: string; savedBytes: number } | null {
+  const originalSize = Buffer.byteLength(code);
+  let modified = code;
+
+  const eFnName = escapeRegExp(fnName);
+  for (const { name, handlerId, passthrough } of exports) {
+    if (passthrough) continue;
+
+    const eName = escapeRegExp(name);
+    // Match const/let/var: Rolldown (Vite 8) emits top-level bindings in the
+    // non-minified RSC bundle as `var`, whereas Rollup used `const`.
+    const callStartRe = new RegExp(
+      `(?:const|let|var)\\s+${eName}\\s*=\\s*${eFnName}\\s*(?:<[^>]*>)?\\s*\\(`,
+    );
+    const startMatch = callStartRe.exec(modified);
+    if (!startMatch) continue;
+
+    const afterOpen = startMatch.index + startMatch[0].length;
+    const closePos = findMatchingParenInBundle(modified, afterOpen);
+    if (closePos === -1) continue;
+
+    let rangeEnd = closePos;
+    while (rangeEnd < modified.length && /\s/.test(modified[rangeEnd]))
+      rangeEnd++;
+    if (modified[rangeEnd] === ";") rangeEnd++;
+
+    const matched = modified.slice(startMatch.index, rangeEnd);
+    if (!matched.includes(handlerId)) continue;
+
+    const stub = `const ${name} = { __brand: "${brand}", $$id: "${handlerId}" };`;
+    modified =
+      modified.slice(0, startMatch.index) + stub + modified.slice(rangeEnd);
+
+    modified = modified.replace(
+      new RegExp(`\\n${eName}\\.\\$\\$id\\s*=\\s*"[^"]+";`),
+      "",
+    );
+  }
+
+  if (modified === code) return null;
+  return {
+    code: modified,
+    savedBytes: originalSize - Buffer.byteLength(modified),
+  };
+}

package/src/vite/utils/client-chunks.ts

@@ -0,0 +1,184 @@
+import type { ClientChunkMeta, ClientChunks } from "../plugin-types.js";
+import { createRangoDebugger, NS } from "../debug.js";
+import { hashRefKey } from "../plugins/client-ref-hashing.js";
+
+/** The callback shape @vitejs/plugin-rsc's `clientChunks` option accepts. */
+export type RscClientChunksFn = (meta: ClientChunkMeta) => string | undefined;
+
+/**
+ * Build-time context the discovery pass populates and the built-in strategy
+ * reads. It refines how the catch-all (no route-root marker) modules are grouped
+ * without touching marker splits or the shared runtime:
+ *
+ * - `fallbackRefs`: production hashes of the `"use client"` modules a consumer
+ *   registered as `errorBoundary`/`notFoundBoundary` fallbacks. Pulled into a
+ *   dedicated `app-fallback` chunk so the error UI is not co-bundled with the
+ *   very route code it exists to catch failures for (resilience), and so the
+ *   chunk it would otherwise sit in gets named after a real module rather than
+ *   the boundary. Populated by reading each fallback element's client-reference
+ *   `$$id` during discovery (see discover-routers).
+ */
+export interface ClientChunkContext {
+  fallbackRefs: Set<string>;
+}
+
+/**
+ * Opt-in observability for the built-in strategy. The route-root marker list is
+ * intentionally finite (see {@link ROUTE_ROOT_DIRS}); a consumer whose layout
+ * has no recognized marker (e.g. `src/parts/<feature>/…`) silently inherits the
+ * default grouping (no per-route split). That silence is the only real downside
+ * of a convention-based default, so we make the decision observable: run a build
+ * with `DEBUG=rango:chunks` to see, per client module, which route group it was
+ * assigned to or why it fell back to the shared grouping. Zero cost when off
+ * (the debugger is `undefined` unless the namespace is enabled). For full control
+ * over any layout, pass a `clientChunks` function instead of relying on the
+ * convention — that is the supported configurability path, not widening the list.
+ */
+const debugChunks = createRangoDebugger(NS.chunks);
+
+/**
+ * Modules that must stay on the default (shared) grouping regardless of strategy:
+ * React, the router client runtime, and anything in node_modules. Splitting these
+ * out per route would fragment the shared baseline and regress cache reuse — they
+ * are loaded on every route, so they belong in shared chunks.
+ *
+ * The Rango runtime is matched by package root only: `@rangojs/router` (the
+ * installed/aliased name) and the workspace `packages/(rangojs-router|rsc-router)/(src|dist)/`.
+ * The `(src|dist)` anchor matches the package's own source/build output but NOT
+ * consumer apps that merely live under a `packages/rangojs-router/` ancestor (the
+ * in-repo e2e apps), so their app components remain splittable. We deliberately do
+ * NOT match a bare `/src/browser/`: that is a consumer-owned path (a consumer's own
+ * `src/browser/Foo.tsx` must still split).
+ *
+ * We test BOTH `meta.id` (absolute) and `meta.normalizedId`. `normalizedId` is the
+ * project-root-relative form plugin-rsc derives (e.g. `../../src/browser/react/Link.tsx`
+ * for the in-repo runtime), which the package-root patterns miss; the absolute `id`
+ * always contains the package's real location, so it reliably catches the runtime.
+ */
+function isSharedRuntime(meta: ClientChunkMeta): boolean {
+  return [meta.id, meta.normalizedId].some(
+    (path) =>
+      path.includes("/node_modules/") ||
+      /\/@rangojs\/router\//.test(path) ||
+      /\/packages\/(rangojs-router|rsc-router)\/(src|dist)\//.test(path),
+  );
+}
+
+/** Sanitize a raw group name into a filesystem/Rollup-safe chunk name fragment. */
+function sanitizeGroup(name: string): string {
+  return name.replace(/[^a-zA-Z0-9_-]+/g, "_").replace(/^_+|_+$/g, "") || "app";
+}
+
+/**
+ * Directory names that conventionally hold one sub-directory per route/feature.
+ * When a `"use client"` module lives under one of these, the built-in strategy
+ * keys the chunk on the segment IMMEDIATELY AFTER the marker (the route id),
+ * rather than the module's immediate parent directory. This is what keeps
+ * `routes/foo/components/Button.tsx` and `routes/bar/components/Button.tsx` in
+ * `app-foo` / `app-bar` instead of colliding in a single `app-components`.
+ *
+ * Route identity lives in the path PREFIX; the immediate parent (a suffix) is
+ * only a reliable proxy for the un-nested `routes/<route>/Widget.tsx` layout.
+ */
+const ROUTE_ROOT_DIRS = new Set([
+  "routes",
+  "route",
+  "pages",
+  "page",
+  "app",
+  "features",
+  "feature",
+  "views",
+  "view",
+  "handlers",
+  "urls",
+  "modules",
+  "screens",
+  "sections",
+]);
+
+/**
+ * Built-in strategy used when `clientChunks: true` (also the default). Splits app
+ * client components by route/feature identity ONLY where it can recognize a route
+ * structure; everywhere else it inherits the default grouping (returns undefined).
+ * This conservatism is what makes it safe as a default:
+ *
+ * - A recognized route structure (`routes/<id>/…`, `app/<id>/…`, `handlers/<id>/…`
+ *   etc.) splits into a per-route chunk `app-<id>`, at any nesting depth.
+ * - A flat `src/components/Button.tsx`, or host sub-apps already split by a dynamic
+ *   `import()` boundary (each app's `serverChunk` differs), get `undefined` and so
+ *   keep `@vitejs/plugin-rsc`'s default `serverChunk` grouping — i.e. NO change
+ *   versus not enabling the option. Returning a parent-dir name here would instead
+ *   merge unrelated modules (e.g. every host app's `components/Layout.tsx` into one
+ *   `app-components`), re-introducing cross-app leakage.
+ *
+ * Resolution order:
+ * 1. Shared runtime (React / router / node_modules) -> `undefined` (never split).
+ * 2. A registered error/notFound fallback (`ctx.fallbackRefs`) -> `app-fallback`,
+ *    regardless of location, so the error UI is decoupled from the happy path.
+ * 3. A {@link ROUTE_ROOT_DIRS} marker with a directory after it -> key on that
+ *    next segment (the route id), robust to any nesting depth.
+ * 4. Otherwise `undefined` (inherit the default `serverChunk` grouping).
+ */
+export function directoryClientChunks(
+  meta: ClientChunkMeta,
+  ctx?: ClientChunkContext,
+): string | undefined {
+  if (isSharedRuntime(meta)) {
+    // React / router runtime / node_modules: always shared, expected, uninteresting.
+    return undefined;
+  }
+  // Registered error/notFound fallbacks -> a dedicated chunk. The error UI must
+  // not co-bundle with the code it catches failures for, and removing it lets the
+  // chunk it would otherwise anchor be named after a real module, not the boundary.
+  if (
+    ctx?.fallbackRefs.size &&
+    ctx.fallbackRefs.has(hashRefKey(meta.normalizedId))
+  ) {
+    debugChunks?.("fallback %s -> app-fallback", meta.normalizedId);
+    return "app-fallback";
+  }
+  const segments = meta.normalizedId.split("/").filter(Boolean);
+  const dirCount = segments.length - 1; // exclude the filename
+  if (dirCount >= 1) {
+    // Route-root marker -> the segment after it is the route id. First marker
+    // wins, so a top-level route owns its whole subtree. The `< dirCount - 1`
+    // bound guarantees the segment after the marker is a directory, not the file.
+    for (let i = 0; i < dirCount - 1; i++) {
+      if (ROUTE_ROOT_DIRS.has(segments[i].toLowerCase())) {
+        const group = `app-${sanitizeGroup(segments[i + 1])}`;
+        debugChunks?.("split %s -> %s", meta.normalizedId, group);
+        return group;
+      }
+    }
+  }
+  // No recognized route structure -> inherit the default serverChunk grouping.
+  // This is the actionable "silent" case: app code that did NOT split by route.
+  // Surface it (under DEBUG=rango:chunks) so a consumer can see their layout
+  // missed the convention and either colocate under a marker dir or pass a fn.
+  debugChunks?.(
+    "shared %s (no route-root marker; inherits default grouping)",
+    meta.normalizedId,
+  );
+  return undefined;
+}
+
+/**
+ * Resolve a Rango `clientChunks` option into a @vitejs/plugin-rsc `clientChunks`
+ * callback, or `undefined` to leave plugin-rsc on its default (serverChunk)
+ * grouping.
+ *
+ * - `false` / `undefined` -> `undefined` (no override).
+ * - `true`               -> the built-in {@link directoryClientChunks} strategy,
+ *   bound to the discovery-populated {@link ClientChunkContext} (fallback chunk).
+ * - function             -> the user's function, used verbatim (full control; the
+ *   fallback refinement does not apply — the consumer owns the grouping).
+ */
+export function resolveClientChunks(
+  option: ClientChunks | undefined,
+  ctx?: ClientChunkContext,
+): RscClientChunksFn | undefined {
+  if (!option) return undefined;
+  if (option === true) return (meta) => directoryClientChunks(meta, ctx);
+  return option;
+}