@rangojs/router 0.0.0-experimental.113 → 0.0.0-experimental.115

package/src/vite/plugins/expose-internal-ids.ts

@@ -28,6 +28,7 @@ import {
   getImportedFnNames,
   collectCreateExportBindings,
   buildUnsupportedShapeWarning,
+  findUnsupportedCreateCallSites,
   isExportOnlyFile,
 } from "./expose-ids/export-analysis.js";
 import {
@@ -370,14 +371,21 @@ ${lazyImports.join(",\n")}
           if (!hasCode) continue;
 
           const fnNames = getFnNames(cfg.fnName);
-          const totalCalls = countCreateCallsForNames(code, fnNames);
-          const supportedBindings = getBindings(code, fnNames).length;
-          if (totalCalls <= supportedBindings) continue;
+          // Locate the real (comment/string-free) create* calls not covered by
+          // a supported, id-injectable export shape. Empty means every call is
+          // fine — in particular, a create*() token in a comment or string no
+          // longer trips a spurious warning.
+          const sites = findUnsupportedCreateCallSites(
+            code,
+            fnNames,
+            getBindings(code, fnNames),
+          );
+          if (sites.length === 0) continue;
 
           const warnKey = `${id}::${cfg.fnName}`;
           if (unsupportedShapeWarnings.has(warnKey)) continue;
           unsupportedShapeWarnings.add(warnKey);
-          this.warn(buildUnsupportedShapeWarning(filePath, cfg.fnName));
+          this.warn(buildUnsupportedShapeWarning(filePath, cfg.fnName, sites));
         }
 
         // --- Loader: track for manifest (RSC env only) ---

package/src/vite/rango.ts

@@ -23,6 +23,7 @@ import {
   onwarn,
   getManualChunks,
 } from "./utils/shared-utils.js";
+import { resolveClientChunks } from "./utils/client-chunks.js";
 import type { RangoOptions } from "./plugin-types.js";
 import { printBanner, rangoVersion } from "./utils/banner.js";
 import { createVersionInjectorPlugin } from "./plugins/version-injector.js";
@@ -62,6 +63,15 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
   const resolvedOptions: RangoOptions = options ?? { preset: "node" };
   const preset = resolvedOptions.preset ?? "node";
   const showBanner = resolvedOptions.banner ?? true;
+  // Client-chunking strategy (per-route/per-feature splitting of the browser
+  // bundle). Defaults to the built-in directory strategy (`true`) pre-1.0; pass
+  // `clientChunks: false` to opt out. Resolved once and forwarded to
+  // @vitejs/plugin-rsc in both presets. The built-in strategy only splits where it
+  // recognizes a route structure, so this default is a no-op for flat / host-split
+  // apps and never duplicates the shared runtime.
+  const clientChunks = resolveClientChunks(
+    resolvedOptions.clientChunks ?? true,
+  );
   debugConfig?.("rango(%s) setup start", preset);
 
   const plugins: PluginOption[] = [];
@@ -231,6 +241,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
       rsc({
         entries: finalEntries,
         serverHandler: false,
+        clientChunks,
       }) as PluginOption,
     );
 
@@ -394,6 +405,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     plugins.push(
       rsc({
         entries: finalEntries,
+        clientChunks,
       }) as PluginOption,
     );
 

package/src/vite/router-discovery.ts

@@ -17,6 +17,7 @@ import {
   findNestedRouterConflict,
   findRouterFiles,
 } from "../build/generate-route-types.js";
+import { firstCodeMatchIndex } from "../build/route-types/source-scan.js";
 import { createVersionPlugin } from "./plugins/version-plugin.js";
 import { createVirtualStubPlugin } from "./plugins/virtual-stub-plugin.js";
 import {
@@ -1184,8 +1185,19 @@ export function createRouterDiscoveryPlugin(
               trimmed.startsWith('"use client"') ||
               trimmed.startsWith("'use client'");
             if (!inRecoveryMode && isUseClient) return;
-            const hasUrls = source.includes("urls(");
-            const hasCreateRouter = /\bcreateRouter\s*[<(]/.test(source);
+            // Cheap raw pre-check first; only when a candidate token is present
+            // do we confirm it occurs in real code (not a comment/string) via a
+            // single allocation-free code-region scan. Most saved files contain
+            // neither token and skip the scan entirely. This avoids a comment or
+            // string mention spuriously marking a file relevant and triggering an
+            // unnecessary re-discovery on save.
+            let hasUrls = source.includes("urls(");
+            let hasCreateRouter = /\bcreateRouter\s*[<(]/.test(source);
+            if (hasUrls) hasUrls = firstCodeMatchIndex(source, /urls\(/g) >= 0;
+            if (hasCreateRouter) {
+              hasCreateRouter =
+                firstCodeMatchIndex(source, /\bcreateRouter\s*[<(]/g) >= 0;
+            }
             if (!inRecoveryMode && !hasUrls && !hasCreateRouter) return;
             if (inRecoveryMode) {
               debugDiscovery?.(

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

@@ -0,0 +1,156 @@
+// Resolution of the public `clientChunks` option into the callback shape that
+// @vitejs/plugin-rsc expects. See plugin-types.ts (ClientChunks) and
+// docs/client-chunking.md for the contract. The mechanism: a distinct returned
+// name yields a distinct, dynamically-imported client chunk, independent of how
+// the RSC/server build chunked the importing modules.
+
+import type { ClientChunkMeta, ClientChunks } from "../plugin-types.js";
+import { createRangoDebugger, NS } from "../debug.js";
+
+/** The callback shape @vitejs/plugin-rsc's `clientChunks` option accepts. */
+export type RscClientChunksFn = (meta: ClientChunkMeta) => string | undefined;
+
+/**
+ * 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. If the path passes through a {@link ROUTE_ROOT_DIRS} marker that has a
+ *    directory after it, key on that next segment (the route id) — robust to any
+ *    nesting depth below it (`routes/foo/components/ui/X.tsx` -> `app-foo`).
+ * 2. Otherwise return `undefined` (inherit the default `serverChunk` grouping).
+ */
+export function directoryClientChunks(
+  meta: ClientChunkMeta,
+): string | undefined {
+  if (isSharedRuntime(meta)) {
+    // React / router runtime / node_modules: always shared, expected, uninteresting.
+    return undefined;
+  }
+  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.
+ * - function             -> the user's function, used verbatim.
+ */
+export function resolveClientChunks(
+  option: ClientChunks | undefined,
+): RscClientChunksFn | undefined {
+  if (!option) return undefined;
+  if (option === true) return directoryClientChunks;
+  return option;
+}

package/src/vite/utils/shared-utils.ts

@@ -173,12 +173,19 @@ export function getManualChunks(id: string): string | undefined {
     return "react";
   }
   // Use dynamic package name from package.json
-  // Check both npm install path and workspace symlink resolved path
+  // Check both npm install path and workspace symlink resolved path.
+  //
+  // The workspace patterns are anchored to the package's own `src`/`dist` so
+  // they match the router runtime but NOT consumer apps that merely live under a
+  // `packages/rangojs-router/` ancestor (the in-repo e2e apps at
+  // `packages/rangojs-router/e2e/<app>/src/...`). Without the anchor those apps'
+  // own client components were force-merged into the shared "router" chunk,
+  // which both misrepresented real-consumer bundles and blocked `clientChunks`
+  // splitting from relocating them.
   const packageName = getPublishedPackageName();
   if (
     normalized.includes(`node_modules/${packageName}/`) ||
-    normalized.includes("packages/rsc-router/") ||
-    normalized.includes("packages/rangojs-router/")
+    /\/packages\/(rsc-router|rangojs-router)\/(src|dist)\//.test(normalized)
   ) {
     return "router";
   }