@rangojs/router 0.19.1 → 0.20.0

package/dist/types/ssr/entry-preload-priority.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The client entry's head hint at default fetch priority, after the head chunk
+ * scripts (issue #1025).
+ *
+ * For `bootstrapModules`, Fizz writes `<link rel="modulepreload"
+ * fetchPriority="low">` into the head and claims the URL
+ * (`moduleScriptResources[url] = null`, react-dom 19.3.0
+ * `react-dom-server.edge.production.js:546-565`) before the render starts, so
+ * no `preloadModule`/`preinitModule` call can replace it, and the
+ * `bootstrapModules` entry shape has no priority field. Chromium fetches that
+ * hint at Low, and once it boosts in-viewport images to High after first
+ * layout, the entry queues behind them; the executing end-of-shell module
+ * script reuses the in-flight Low fetch through the module map. Hydration
+ * then waits on a few-hundred-byte file while the head chunk scripts it
+ * imports (High) have long arrived: measured +3.8 s on a priority-honouring
+ * HTTP/2 link at Slow 4G.
+ *
+ * The fix serves that one tag without the attribute, so it fetches at
+ * Chromium's modulepreload default (High), and moves it after the head
+ * chunk scripts. Fizz flushes the bootstrap hint before the head chunk scripts; at
+ * High in that position it took one of HTTP/1.1's six connections ahead of
+ * the react chunk and delayed the last head chunk (hydration +91 ms, LCP
+ * +84 ms measured). After the scripts it is the last High request in the
+ * queue, so it never displaces a chunk hydration also needs. The accepted
+ * cost: an HTTP/2 server that sends equal-priority streams first in, first
+ * out delivers it with the last head chunk instead of before it (text-only
+ * pages +12 to +56 ms measured, against -0.15 to -3.3 s hydration on image
+ * pages; CHANGELOG has the matrix). Everything else about the bootstrap pair
+ * stays Fizz's: the nonce, the executing `id="_R_"` tag, the URL claim that
+ * keeps plugin-rsc's and the preinit hook's calls for the entry inert, and the
+ * PPR prelude/resume behaviour.
+ *
+ * The match is the exact tag Fizz writes for a string `bootstrapModules`
+ * entry (`rel`, `fetchPriority`, `nonce`, `href` in that order), not a
+ * pattern, and only before the first `<body`. A Fizz version that writes it
+ * differently leaves the bytes untouched: the output keeps the Low hint.
+ *
+ * Where the tag goes: right after the run of Fizz resource tags that directly
+ * follows the hint, before the first token that is anything else (`</head>`,
+ * the app's own head children, or body content in a head-less document).
+ * Fizz flushes the head chunk scripts and the bulk preloads straight after
+ * the bootstrap hint (react-dom 19.3.0 `flushCompletedQueues`, `:7321-7325`),
+ * as `<script …></script>` with no body and `<link …/>`; the scan accepts
+ * only those two shapes and stops at any other token without reading into it.
+ * It never searches the app's head content for `</head>` or `<body`: React
+ * does not escape either inside `<script>` or `<style>` text, so a head script
+ * holding the string `"<body>"` once received the tag inside its source and
+ * threw. Fizz escapes `>` in attribute values, so the first `>` ends a tag.
+ * Every insertion point is the boundary between two complete tags; a stream
+ * that ends mid-run, or a run tag longer than {@link MAX_HELD_TAG}, gets the
+ * tag before the unfinished one. Only that one tag is held back while the run
+ * streams; each complete run tag is forwarded as soon as it is scanned.
+ */
+/**
+ * Rewrite a complete document prefix (the PPR shell capture's prelude).
+ * Returns `bytes` unchanged when no hint precedes the first `<body`.
+ */
+export declare function rewriteEntryPreloadPriority(bytes: Uint8Array, entryUrl: string, nonce?: string): Uint8Array;
+/**
+ * Streaming form for live SSR: the same rewrite as
+ * {@link rewriteEntryPreloadPriority}, then pass-through. Before the hint is
+ * found, only a chunk tail that may be the start of a split `<body` or hint
+ * tag is held back. After it, complete run tags are forwarded as they are
+ * scanned and only an unfinished one (at most {@link MAX_HELD_TAG} bytes) is
+ * held, so every byte is scanned a bounded number of times. Once the tag is
+ * placed, or once `<body` passes without a hint, chunks are forwarded
+ * untouched and unscanned.
+ */
+export declare function entryPreloadPriorityTransform(entryUrl: string, nonce?: string): TransformStream<Uint8Array, Uint8Array>;

package/dist/types/ssr/index.d.ts

@@ -145,6 +145,7 @@ export interface SSRDependencies<TEnv = unknown> {
      * undefined keeps the inline bootstrap verbatim, so a custom SSR entry that
      * never installed the preinit hook cannot drift into the half-converted
      * state on upgrade (the generated entry always passes an explicit value).
+     * Any other value throws when the handler is created.
      */
     headScripts?: HeadScriptsOption;
     /**

package/dist/types/ssr/preinit-client-references.d.ts

@@ -55,11 +55,23 @@ export declare function runWithPreinitNonce<T>(nonce: string | undefined, fn: ()
  *
  * Known trades (deliberate, measured neutral-to-positive on the e2e apps —
  * PR #694 has the Lighthouse/hydration numbers):
- * - Fetch priority: an executing async module script fetches at Chromium's
- *   async-script priority, below a bare modulepreload hint; preinitModule
- *   forwards no fetchPriority (react-dom's public API drops it — only
- *   `preinit` forwards it). Execution-overlap is bought with hint priority,
- *   the same trade Next.js ships via ReactDOM.preinit.
+ * - Fetch priority: Chromium gives a parser-inserted `async` module script
+ *   initial priority High: below the render-blocking stylesheet (Highest),
+ *   and alongside the LCP image once Chromium boosts the in-viewport image to
+ *   High (#1021). Every head chunk gets the same priority: the shared
+ *   dependency chunks (react, router, entry.rsc and the bundler runtime) and
+ *   every client-component chunk. The entry itself is a Fizz bootstrapModules
+ *   hint, not a preinit (Fizz claims its URL, so this hook's call for it is
+ *   inert); the handlers serve that hint at default priority, High as well,
+ *   after these scripts (entry-preload-priority.ts, #1025).
+ *   Lowering the chunks to `fetchpriority="low"` was measured and rejected
+ *   (#1021; Chromium 153, 20 interleaved runs per variant and cell). On pages
+ *   with images above the fold the Low chunks queue behind the boosted
+ *   images: hydration came 206 to 6407 ms later on HTTP/1.1 and 65 to 642 ms
+ *   later on HTTP/2. The one gain, FCP -136 ms, needed an image-free page
+ *   with 35 KB of render-blocking CSS on HTTP/1.1 Slow 4G, and hydration was
+ *   still 98 ms later there. `headScripts: "preload"` is the way to get Low
+ *   chunk fetches.
  * - Build only: plugin-rsc's dev load path reports `js: []` per reference, so
  *   dev documents have no head chunk scripts — a client module whose module
  *   scope assumes body-parsed DOM can break in production only. The

package/dist/types/vite/plugin-types.d.ts

@@ -68,6 +68,12 @@ export interface ClientChunkMeta {
  *   strategy**. It splits app `"use client"` modules by **route id** — the segment
  *   after a route-root directory (`routes`, `app`, `pages`, `features`, `handlers`,
  *   …) — so `routes/dashboard/**` becomes `app-dashboard` at any nesting depth.
+ *   The first marker in the path wins, except that an `app/` directly followed
+ *   by another marker with a directory after it is treated as a source root:
+ *   `app/routes/product/**` becomes `app-product`, while `app/dashboard/**`
+ *   (Next-style), `app/components/**` and files directly in `app/routes/` stay
+ *   `app-dashboard` / `app-components` / `app-routes`. The same route id under
+ *   different markers is one group.
  *   Where it finds NO route structure (a flat `src/components/`, or host sub-apps
  *   already split by a dynamic `import()`), it inherits the default grouping
  *   unchanged — so the shared `src/components` chunk stays shared and host apps do
@@ -79,10 +85,14 @@ export interface ClientChunkMeta {
  *   back to the default grouping for that one module. Forwarded directly to
  *   `@vitejs/plugin-rsc`'s `clientChunks`.
  *
- * Every module maps to exactly one group, so there is no byte duplication: a
- * component used by two routes lives in one group and is fetched whenever it
- * renders. Put genuinely shared client components OUTSIDE route directories so
- * they land in the shared group rather than one route's chunk.
+ * Every module maps to exactly one group, so there is no byte duplication. A
+ * group is also the loading unit: rendering any one member downloads the whole
+ * group's chunk, every other member included. A component used by two routes
+ * lives in one group, and rendering it on either route fetches that entire
+ * group. Put genuinely shared client components OUTSIDE route directories so
+ * they land in the shared group rather than one route's chunk, and keep an
+ * always-rendered component (a layout header) out of a large group.
+ * `DEBUG=rango:chunks vite build` logs each group's module count and size.
  *
  * @default true
  */
@@ -114,14 +124,18 @@ interface RangoBaseOptions {
      * - `"preinit"` (**default**): client-reference chunks render as EXECUTING
      *   `<script type="module" async>` tags hoisted into `<head>` (upgrading
      *   plugin-rsc's modulepreload hints in place), and the browser entry ships
-     *   as Fizz `bootstrapModules` — a head `modulepreload fetchpriority=low`
-     *   hint plus the executing end-of-shell `id="_R_"` module script. Chunk
+     *   as Fizz `bootstrapModules` — a `modulepreload` hint after the head
+     *   chunk scripts (default priority; Fizz's `fetchpriority=low` is dropped,
+     *   #1025)
+     *   plus the executing end-of-shell `id="_R_"` module script. Chunk
      *   execution overlaps body streaming instead of waiting for the hydration
      *   import walk; under PPR everything lands in the stored shell prelude.
      * - `"preload"`: the previous behavior — `<link rel="modulepreload">` hints
      *   only, entry as an inline `import()` script at end of shell. Chunks
      *   fetch+compile early but execute only when hydration imports them.
      *
+     * Any other value throws when the generated SSR entry is built.
+     *
      * Build-only for the chunk half: plugin-rsc resolves no JS deps per client
      * reference in dev, so dev documents carry no head chunk scripts in either
      * mode (the bootstrap conversion does apply in dev). Trades and upstream

package/dist/types/vite/plugins/virtual-entries.d.ts

@@ -5,7 +5,9 @@ export declare const VIRTUAL_ENTRY_BROWSER: string;
  * option: "preinit" (default) installs the client-reference preinit hook and
  * threads `getClientEntryUrl` so Fizz emits `bootstrapModules`;
  * "preload" omits the hook and uses the deprecated inline
- * `loadBootstrapScriptContent` bootstrap.
+ * `loadBootstrapScriptContent` bootstrap. Any other value throws: an unknown
+ * string such as "prenit" used to run as "preinit" silently
+ * (`headScripts !== "preload"` since #694).
  */
 export declare function getVirtualEntrySSR(headScripts?: HeadScriptsOption, progressiveChunkSize?: number): string;
 /**

package/dist/types/vite/utils/client-chunks.d.ts

@@ -1,4 +1,6 @@
+import type { Plugin } from "vite";
 import type { ClientChunkMeta, ClientChunks } from "../plugin-types.js";
+import { type Debugger } from "../debug.js";
 /** The callback shape @vitejs/plugin-rsc's `clientChunks` option accepts. */
 export type RscClientChunksFn = (meta: ClientChunkMeta) => string | undefined;
 /**
@@ -36,8 +38,11 @@ export interface ClientChunkContext {
  * 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.
+ * 3. The first {@link ROUTE_ROOT_DIRS} marker with a directory after it -> key on
+ *    that next segment (the route id), robust to any nesting depth. A
+ *    {@link SOURCE_ROOT_DIRS} marker (`app`) directly followed by another marker
+ *    with a directory after it defers to that inner marker:
+ *    `app/routes/<id>/…` -> `app-<id>`, while `app/<segment>/…` -> `app-<segment>`.
  * 4. Otherwise `undefined` (inherit the default `serverChunk` grouping).
  */
 export declare function directoryClientChunks(meta: ClientChunkMeta, ctx?: ClientChunkContext): string | undefined;
@@ -53,3 +58,18 @@ export declare function directoryClientChunks(meta: ClientChunkMeta, ctx?: Clien
  *   fallback refinement does not apply — the consumer owns the grouping).
  */
 export declare function resolveClientChunks(option: ClientChunks | undefined, ctx?: ClientChunkContext): RscClientChunksFn | undefined;
+/**
+ * Build-end group report under `DEBUG=rango:chunks`: one line per client
+ * reference group with its client-reference count and the size of the group's
+ * own chunk (code split into shared chunks such as `react`/`router` is not
+ * counted). A group is the loading unit (plugin-rsc imports the group's virtual
+ * module to resolve any one member), so a large group that an always-rendered
+ * component belongs to is downloaded on every route; this line makes that
+ * visible. Covers every group, including ones named by a custom `clientChunks`
+ * function or by plugin-rsc's default `serverChunk` grouping. `undefined` when
+ * the namespace is off, so a normal build does not register it. Group names are
+ * printed with NUL escaped: plugin-rsc's default group is named
+ * `facade:\0virtual:…`, and a raw NUL makes `grep` treat the output as binary
+ * and drop that line, usually the largest group. `log` is injectable for tests.
+ */
+export declare function clientChunksReport(log?: Debugger | undefined): Plugin | undefined;

package/dist/vite/index.js

@@ -4369,7 +4369,12 @@ function emitProgressiveChunkSize(value) {
   return JSON.stringify(value);
 }
 function getVirtualEntrySSR(headScripts = "preinit", progressiveChunkSize) {
-  const preinit = headScripts !== "preload";
+  if (headScripts !== "preinit" && headScripts !== "preload") {
+    throw new Error(
+      `rango({ headScripts }) must be "preinit" or "preload", received ${JSON.stringify(headScripts)}`
+    );
+  }
+  const preinit = headScripts === "preinit";
   const depsImportNames = preinit ? "createFromReadableStream,\n  setOnClientReference,\n  getClientEntryUrl," : "createFromReadableStream,";
   const ssrImportNames = preinit ? "\n  installClientReferencePreinit," : "";
   const install = preinit ? `
@@ -4578,7 +4583,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.19.1",
+  version: "0.20.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -6443,6 +6448,7 @@ function getManualChunks(id) {
 // src/vite/utils/client-chunks.ts
 init_debug();
 init_client_ref_hashing();
+import { gzipSync } from "node:zlib";
 var debugChunks = createRangoDebugger(NS.chunks);
 function isSharedRuntime(meta) {
   return [meta.id, meta.normalizedId].some(
@@ -6468,6 +6474,7 @@ var ROUTE_ROOT_DIRS = /* @__PURE__ */ new Set([
   "screens",
   "sections"
 ]);
+var SOURCE_ROOT_DIRS = /* @__PURE__ */ new Set(["app"]);
 function directoryClientChunks(meta, ctx) {
   if (isSharedRuntime(meta)) {
     return void 0;
@@ -6478,14 +6485,13 @@ function directoryClientChunks(meta, ctx) {
   }
   const segments = meta.normalizedId.split("/").filter(Boolean);
   const dirCount = segments.length - 1;
-  if (dirCount >= 1) {
-    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;
-      }
-    }
+  const isMarkerAt = (i) => i < dirCount - 1 && ROUTE_ROOT_DIRS.has(segments[i].toLowerCase());
+  for (let i = 0; i < dirCount - 1; i++) {
+    if (!isMarkerAt(i)) continue;
+    const marker = SOURCE_ROOT_DIRS.has(segments[i].toLowerCase()) && isMarkerAt(i + 1) ? i + 1 : i;
+    const group = `app-${sanitizeGroup(segments[marker + 1])}`;
+    debugChunks?.("split %s -> %s", meta.normalizedId, group);
+    return group;
   }
   debugChunks?.(
     "shared %s (no route-root marker; inherits default grouping)",
@@ -6498,6 +6504,30 @@ function resolveClientChunks(option, ctx) {
   if (option === true) return (meta) => directoryClientChunks(meta, ctx);
   return option;
 }
+var CLIENT_GROUP_PREFIX = "\0virtual:vite-rsc/client-references/group/";
+function clientChunksReport(log = debugChunks) {
+  if (!log) return void 0;
+  return {
+    name: "@rangojs/router:client-chunks-report",
+    apply: "build",
+    applyToEnvironment: (env) => env.name === "client",
+    generateBundle(_options, bundle) {
+      for (const chunk of Object.values(bundle)) {
+        if (chunk.type !== "chunk") continue;
+        const facade = chunk.facadeModuleId;
+        if (!facade?.startsWith(CLIENT_GROUP_PREFIX)) continue;
+        log(
+          "group %s: %d client reference(s), %d B (%d B gzip) -> %s",
+          facade.slice(CLIENT_GROUP_PREFIX.length).replaceAll("\0", "\\0"),
+          this.getModuleInfo(facade)?.importedIds.length ?? 0,
+          Buffer.byteLength(chunk.code),
+          gzipSync(chunk.code).length,
+          chunk.fileName
+        );
+      }
+    }
+  };
+}
 
 // src/vite/plugins/vercel-output.ts
 import { rm, mkdir, cp, writeFile } from "node:fs/promises";
@@ -13349,6 +13379,7 @@ If this is a multi-app host router, export a createHostRouter() instance and set
     );
     plugins.push(clientRefDedup());
   }
+  plugins.push(clientChunksReport());
   plugins.push({
     name: "@rangojs/router:client-component-hmr",
     hotUpdate(ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/bundle-analysis/SKILL.md

@@ -15,7 +15,7 @@ Your app builds in three Vite environments — `client`, `ssr`, and `rsc` — an
 1. **Server code leaking into the client.** A file that imports `node:fs`, calls a database, or contains action logic ends up in the client bundle because a client component pulled it in transitively. Symptom: your client bundle is much larger than expected, sometimes with imports that fail at runtime.
 2. **Both dev and prod React in the SSR/RSC bundle.** When `process.env.NODE_ENV` isn't folded at build time, React's CJS files ship both `.development.js` _and_ `.production.js` variants — doubling React's footprint. The Cloudflare Vite plugin and rango's `vercel` preset fold NODE_ENV automatically; on the default `node` preset, `vite build` does it for the client but not always for SSR/RSC, so add the `define` from Step 2.
 3. **An oversized routes-manifest in your RSC worker.** The `virtual:rsc-router/routes-manifest/<routerId>` chunk holds your route trie and precomputed entries — large only in proportion to your route count. If it's surprisingly big, you may have unintentionally generated routes (e.g., parametrized fixtures) that bloated the trie.
-4. **Poor client-chunk grouping.** `rango({ clientChunks })` decides how `"use client"` modules are grouped into browser chunks. The default groups them by route directory (`routes/<id>/**` → `app-<id>`), with flat folders like `src/components/` in one shared chunk; `clientChunks: false` ships one client chunk per router. A route that pulls in unrelated routes' client code, or one oversized shared chunk, points at the grouping.
+4. **Poor client-chunk grouping.** `rango({ clientChunks })` decides how `"use client"` modules are grouped into browser chunks. The default groups them by route directory (`routes/<id>/**` → `app-<id>`), with flat folders like `src/components/` in one shared chunk; `clientChunks: false` ships one client chunk per router. A group is the loading unit: rendering any one member downloads the whole group's chunk. A route that pulls in unrelated routes' client code, or one oversized shared chunk, points at the grouping; `DEBUG=rango:chunks vite build` logs each group's size at build end.
 
 Tree-shaking does _not_ catch generated data inlined as string literals, or data-dependent conditionals like React's `NODE_ENV` branches. You need a visualizer.
 

package/skills/router-setup/SKILL.md

@@ -234,8 +234,14 @@ Notes:
 
 - `clientChunks` default groups app client components by the directory after a
   route root (`routes/`, `app/`, `pages/`, `features/`, `handlers/`, ...), so
-  `routes/dashboard/**` becomes chunk `app-dashboard`. Flat folders such as
-  `src/components/` stay in the shared chunk. `false` restores
+  `routes/dashboard/**` becomes chunk `app-dashboard`. An `app/` directly
+  followed by another marker with a directory after it is a source root, so
+  `app/routes/product/**` is `app-product`; `app/<segment>/**`,
+  `app/components/**` and files directly in `app/routes/` keep `app-<segment>`
+  / `app-components` / `app-routes`. Flat folders such as
+  `src/components/` stay in the shared chunk. A group is the loading unit:
+  rendering any member downloads the whole group's chunk;
+  `DEBUG=rango:chunks vite build` logs each group's size. `false` restores
   `@vitejs/plugin-rsc`'s grouping (one client chunk per router). A function
   `(meta) => string | undefined` names the group per module (`undefined` keeps
   the default); `directoryClientChunks(meta)`, the default strategy, is

package/src/ssr/entry-preload-priority.ts

@@ -0,0 +1,308 @@
+/**
+ * The client entry's head hint at default fetch priority, after the head chunk
+ * scripts (issue #1025).
+ *
+ * For `bootstrapModules`, Fizz writes `<link rel="modulepreload"
+ * fetchPriority="low">` into the head and claims the URL
+ * (`moduleScriptResources[url] = null`, react-dom 19.3.0
+ * `react-dom-server.edge.production.js:546-565`) before the render starts, so
+ * no `preloadModule`/`preinitModule` call can replace it, and the
+ * `bootstrapModules` entry shape has no priority field. Chromium fetches that
+ * hint at Low, and once it boosts in-viewport images to High after first
+ * layout, the entry queues behind them; the executing end-of-shell module
+ * script reuses the in-flight Low fetch through the module map. Hydration
+ * then waits on a few-hundred-byte file while the head chunk scripts it
+ * imports (High) have long arrived: measured +3.8 s on a priority-honouring
+ * HTTP/2 link at Slow 4G.
+ *
+ * The fix serves that one tag without the attribute, so it fetches at
+ * Chromium's modulepreload default (High), and moves it after the head
+ * chunk scripts. Fizz flushes the bootstrap hint before the head chunk scripts; at
+ * High in that position it took one of HTTP/1.1's six connections ahead of
+ * the react chunk and delayed the last head chunk (hydration +91 ms, LCP
+ * +84 ms measured). After the scripts it is the last High request in the
+ * queue, so it never displaces a chunk hydration also needs. The accepted
+ * cost: an HTTP/2 server that sends equal-priority streams first in, first
+ * out delivers it with the last head chunk instead of before it (text-only
+ * pages +12 to +56 ms measured, against -0.15 to -3.3 s hydration on image
+ * pages; CHANGELOG has the matrix). Everything else about the bootstrap pair
+ * stays Fizz's: the nonce, the executing `id="_R_"` tag, the URL claim that
+ * keeps plugin-rsc's and the preinit hook's calls for the entry inert, and the
+ * PPR prelude/resume behaviour.
+ *
+ * The match is the exact tag Fizz writes for a string `bootstrapModules`
+ * entry (`rel`, `fetchPriority`, `nonce`, `href` in that order), not a
+ * pattern, and only before the first `<body`. A Fizz version that writes it
+ * differently leaves the bytes untouched: the output keeps the Low hint.
+ *
+ * Where the tag goes: right after the run of Fizz resource tags that directly
+ * follows the hint, before the first token that is anything else (`</head>`,
+ * the app's own head children, or body content in a head-less document).
+ * Fizz flushes the head chunk scripts and the bulk preloads straight after
+ * the bootstrap hint (react-dom 19.3.0 `flushCompletedQueues`, `:7321-7325`),
+ * as `<script …></script>` with no body and `<link …/>`; the scan accepts
+ * only those two shapes and stops at any other token without reading into it.
+ * It never searches the app's head content for `</head>` or `<body`: React
+ * does not escape either inside `<script>` or `<style>` text, so a head script
+ * holding the string `"<body>"` once received the tag inside its source and
+ * threw. Fizz escapes `>` in attribute values, so the first `>` ends a tag.
+ * Every insertion point is the boundary between two complete tags; a stream
+ * that ends mid-run, or a run tag longer than {@link MAX_HELD_TAG}, gets the
+ * tag before the unfinished one. Only that one tag is held back while the run
+ * streams; each complete run tag is forwarded as soon as it is scanned.
+ */
+
+const LOW_PRIORITY_ATTR = ' fetchPriority="low"';
+const encoder = new TextEncoder();
+const BODY_OPEN = encoder.encode("<body");
+const LINK_OPEN = encoder.encode("<link");
+const SCRIPT_OPEN = encoder.encode("<script");
+const SCRIPT_CLOSE = encoder.encode("</script>");
+const GT = 0x3e;
+
+/**
+ * Longest run tag held while its end has not arrived. Fizz's chunk scripts
+ * and preload links are a few hundred bytes; past this the tag goes before
+ * the held one, which keeps the per-chunk work bounded.
+ */
+const MAX_HELD_TAG = 8192;
+
+/** React's escapeTextForBrowser: the attribute escaping Fizz applies. */
+function escapeAttr(value: string): string {
+  return value.replace(/["&'<>]/g, (c) =>
+    c === '"'
+      ? "&quot;"
+      : c === "&"
+        ? "&amp;"
+        : c === "'"
+          ? "&#x27;"
+          : c === "<"
+            ? "&lt;"
+            : "&gt;",
+  );
+}
+
+interface EntryHintBytes {
+  low: Uint8Array;
+  auto: Uint8Array;
+}
+
+function entryHintBytes(
+  entryUrl: string,
+  nonce: string | undefined,
+): EntryHintBytes {
+  const tail =
+    (nonce ? ` nonce="${escapeAttr(nonce)}"` : "") +
+    ` href="${escapeAttr(entryUrl)}"/>`;
+  return {
+    low: encoder.encode(`<link rel="modulepreload"${LOW_PRIORITY_ATTR}${tail}`),
+    auto: encoder.encode(`<link rel="modulepreload"${tail}`),
+  };
+}
+
+function indexOfBytes(
+  haystack: Uint8Array,
+  needle: Uint8Array,
+  from = 0,
+): number {
+  const first = needle[0];
+  const last = haystack.length - needle.length;
+  outer: for (let i = from; i <= last; i++) {
+    if (haystack[i] !== first) continue;
+    for (let j = 1; j < needle.length; j++) {
+      if (haystack[i + j] !== needle[j]) continue outer;
+    }
+    return i;
+  }
+  return -1;
+}
+
+/**
+ * Length of the longest suffix of `buf` that is a proper prefix of `needle`:
+ * the bytes a chunk boundary may have split off a match.
+ */
+function partialSuffixLength(buf: Uint8Array, needle: Uint8Array): number {
+  const max = Math.min(buf.length, needle.length - 1);
+  outer: for (let len = max; len > 0; len--) {
+    const start = buf.length - len;
+    for (let j = 0; j < len; j++) {
+      if (buf[start + j] !== needle[j]) continue outer;
+    }
+    return len;
+  }
+  return 0;
+}
+
+function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}
+
+/** Index of the hint in `buf` when it precedes the first `<body`, else -1. */
+function findHint(buf: Uint8Array, hint: EntryHintBytes): number {
+  const bodyAt = indexOfBytes(buf, BODY_OPEN);
+  return indexOfBytes(bodyAt === -1 ? buf : buf.subarray(0, bodyAt), hint.low);
+}
+
+/**
+ * 1 when `needle` starts at `pos`, 0 when it does not, -1 when `buf` ends
+ * before that can be decided (the available bytes match a prefix).
+ */
+function matchAt(buf: Uint8Array, pos: number, needle: Uint8Array): number {
+  const n = Math.min(needle.length, buf.length - pos);
+  for (let j = 0; j < n; j++) {
+    if (buf[pos + j] !== needle[j]) return 0;
+  }
+  return n === needle.length ? 1 : -1;
+}
+
+/** HTML whitespace, `/` or `>`: the byte that ends a tag name. */
+function endsTagName(byte: number): boolean {
+  return (
+    byte === 0x20 ||
+    byte === 0x09 ||
+    byte === 0x0a ||
+    byte === 0x0c ||
+    byte === 0x0d ||
+    byte === 0x2f ||
+    byte === GT
+  );
+}
+
+interface RunScan {
+  /** The run ended: `at` is the first byte of the token after it. */
+  ended: boolean;
+  /** Insertion point, or the start of the unfinished token when not ended. */
+  at: number;
+}
+
+/**
+ * Skip the run of Fizz resource tags at the start of `buf`: `<link …>` and
+ * `<script …></script>` with nothing between the two tags.
+ */
+function scanRun(buf: Uint8Array): RunScan {
+  let pos = 0;
+  while (pos < buf.length) {
+    const link = matchAt(buf, pos, LINK_OPEN);
+    const script = link === 1 ? 0 : matchAt(buf, pos, SCRIPT_OPEN);
+    if (link !== 1 && script !== 1) {
+      return { ended: link === 0 && script === 0, at: pos };
+    }
+    const nameEnd = pos + (link === 1 ? LINK_OPEN.length : SCRIPT_OPEN.length);
+    if (nameEnd >= buf.length) return { ended: false, at: pos };
+    if (!endsTagName(buf[nameEnd]!)) return { ended: true, at: pos };
+    const gt = buf.indexOf(GT, nameEnd);
+    if (gt === -1) return { ended: false, at: pos };
+    let end = gt + 1;
+    if (script === 1) {
+      const close = matchAt(buf, end, SCRIPT_CLOSE);
+      // An inline script body: the hint goes before the <script, never in it.
+      if (close !== 1) return { ended: close === 0, at: pos };
+      end += SCRIPT_CLOSE.length;
+    }
+    pos = end;
+  }
+  return { ended: false, at: pos };
+}
+
+/** `rest` with `hint` inserted at `at`. */
+function insertAt(rest: Uint8Array, at: number, hint: Uint8Array): Uint8Array {
+  const out = new Uint8Array(rest.length + hint.length);
+  out.set(rest.subarray(0, at), 0);
+  out.set(hint, at);
+  out.set(rest.subarray(at), at + hint.length);
+  return out;
+}
+
+/**
+ * Rewrite a complete document prefix (the PPR shell capture's prelude).
+ * Returns `bytes` unchanged when no hint precedes the first `<body`.
+ */
+export function rewriteEntryPreloadPriority(
+  bytes: Uint8Array,
+  entryUrl: string,
+  nonce?: string,
+): Uint8Array {
+  const hint = entryHintBytes(entryUrl, nonce);
+  const at = findHint(bytes, hint);
+  if (at === -1) return bytes;
+  const rest = bytes.subarray(at + hint.low.length);
+  return concat(
+    bytes.subarray(0, at),
+    insertAt(rest, scanRun(rest).at, hint.auto),
+  );
+}
+
+/**
+ * Streaming form for live SSR: the same rewrite as
+ * {@link rewriteEntryPreloadPriority}, then pass-through. Before the hint is
+ * found, only a chunk tail that may be the start of a split `<body` or hint
+ * tag is held back. After it, complete run tags are forwarded as they are
+ * scanned and only an unfinished one (at most {@link MAX_HELD_TAG} bytes) is
+ * held, so every byte is scanned a bounded number of times. Once the tag is
+ * placed, or once `<body` passes without a hint, chunks are forwarded
+ * untouched and unscanned.
+ */
+export function entryPreloadPriorityTransform(
+  entryUrl: string,
+  nonce?: string,
+): TransformStream<Uint8Array, Uint8Array> {
+  const hint = entryHintBytes(entryUrl, nonce);
+  let carry: Uint8Array | null = null;
+  // The unfinished run tag after the removed hint (possibly empty).
+  let held: Uint8Array | null = null;
+  let done = false;
+  const place = (
+    rest: Uint8Array,
+    controller: TransformStreamDefaultController<Uint8Array>,
+  ): void => {
+    const scan = scanRun(rest);
+    if (scan.ended || rest.length - scan.at > MAX_HELD_TAG) {
+      done = true;
+      held = null;
+      controller.enqueue(insertAt(rest, scan.at, hint.auto));
+      return;
+    }
+    if (scan.at > 0) controller.enqueue(rest.slice(0, scan.at));
+    held = rest.slice(scan.at);
+  };
+  return new TransformStream<Uint8Array, Uint8Array>({
+    transform(chunk, controller) {
+      if (done) {
+        controller.enqueue(chunk);
+        return;
+      }
+      if (held) {
+        place(concat(held, chunk), controller);
+        return;
+      }
+      const buf: Uint8Array = carry ? concat(carry, chunk) : chunk;
+      carry = null;
+      const at = findHint(buf, hint);
+      if (at !== -1) {
+        if (at > 0) controller.enqueue(buf.slice(0, at));
+        place(buf.subarray(at + hint.low.length), controller);
+        return;
+      }
+      if (indexOfBytes(buf, BODY_OPEN) !== -1) {
+        done = true;
+        controller.enqueue(buf);
+        return;
+      }
+      const hold = Math.max(
+        partialSuffixLength(buf, hint.low),
+        partialSuffixLength(buf, BODY_OPEN),
+      );
+      if (hold > 0) carry = buf.slice(buf.length - hold);
+      const out = hold > 0 ? buf.subarray(0, buf.length - hold) : buf;
+      if (out.length > 0) controller.enqueue(out);
+    },
+    flush(controller) {
+      if (carry) controller.enqueue(carry);
+      // The stream ended inside the run: the tag goes before the unfinished one.
+      if (held) controller.enqueue(concat(hint.auto, held));
+    },
+  });
+}

package/src/ssr/index.tsx

@@ -2,6 +2,10 @@ import React from "react";
 import { createSsrRootComponent, deserializeSsrPayload } from "./ssr-root.js";
 import { injectRSCPayloadEager } from "./inject-rsc-eager.js";
 import { runWithPreinitNonce } from "./preinit-client-references.js";
+import {
+  entryPreloadPriorityTransform,
+  rewriteEntryPreloadPriority,
+} from "./entry-preload-priority.js";
 import {
   POST_QUIESCE_TASK_HOPS,
   SHELL_CAPTURE_MAX_WAIT_MS,
@@ -189,6 +193,7 @@ export interface SSRDependencies<TEnv = unknown> {
    * undefined keeps the inline bootstrap verbatim, so a custom SSR entry that
    * never installed the preinit hook cannot drift into the half-converted
    * state on upgrade (the generated entry always passes an explicit value).
+   * Any other value throws when the handler is created.
    */
   headScripts?: HeadScriptsOption;
 
@@ -521,9 +526,23 @@ const MISSING_BOOTSTRAP_MSG =
  * getClientEntryUrl only counts under an explicit `headScripts: "preinit"` —
  * any other headScripts keeps the inline path, so its presence alone is a
  * misconfiguration worth flagging rather than silently ignoring.
+ * An unknown headScripts value throws: a custom SSR entry bypasses the
+ * rango({ headScripts }) check in getVirtualEntrySSR, and a typo such as
+ * "prenit" would otherwise run the inline path as if it were "preload".
+ * undefined stays valid (see {@link resolveBootstrap}).
  */
 function assertBootstrapDeps(deps: SSRDependencies): void {
-  const preinit = deps.headScripts === "preinit";
+  const { headScripts } = deps;
+  if (
+    headScripts !== undefined &&
+    headScripts !== "preinit" &&
+    headScripts !== "preload"
+  ) {
+    throw new Error(
+      `[ssr] headScripts must be "preinit" or "preload", received ${JSON.stringify(headScripts)}`,
+    );
+  }
+  const preinit = headScripts === "preinit";
   if (deps.getClientEntryUrl && !preinit) {
     console.warn(
       '[ssr] getClientEntryUrl is ignored without headScripts: "preinit"; ' +
@@ -550,13 +569,18 @@ type BootstrapOptions = Pick<
  * `headScripts: "preinit"`, getClientEntryUrl() (sync — nothing to race)
  * short-circuits to bootstrapModules, and inline content that is exactly
  * `import("<entry-url>")` converts to the URL. React then emits a
- * `<link rel="modulepreload" fetchpriority="low">` hint in the head plus the
- * executing `<script type="module" src async>` at end of shell — the entry
- * fetch starts with the first flushed bytes instead of when the parser reaches
- * an opaque inline script that only reveals the URL once executed. Fizz stamps
- * the request nonce on both tags, and under PPR both land in the stored
- * prelude; on resume React has already cleared the bootstrap fields from the
- * postponed state, so nothing re-emits. The conversion is an explicit opt-in:
+ * `<link rel="modulepreload">` hint in the head plus the executing
+ * `<script type="module" src async>` at end of shell — the entry fetch starts
+ * with the first flushed bytes instead of when the parser reaches an opaque
+ * inline script that only reveals the URL once executed. Fizz writes that hint
+ * with `fetchPriority="low"` ahead of the head chunk scripts; the handlers
+ * serve it without the attribute after the head chunk scripts
+ * (entry-preload-priority.ts, issue #1025), because at Low the entry queued
+ * behind in-viewport images and gated hydration (+3.8 s measured on a
+ * prioritising HTTP/2 link). Fizz stamps the request nonce on both tags, and
+ * under PPR both land in the stored prelude; on resume React has already
+ * cleared the bootstrap fields from the postponed state, so nothing re-emits.
+ * The conversion is an explicit opt-in:
  * undefined headScripts (a custom SSR entry that predates the option, which
  * also never installed the preinit hook) keeps the inline bootstrap
  * byte-for-byte — converting by default would break CSPs that allowlist the
@@ -746,8 +770,15 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
         await htmlStream.allReady;
       }
 
+      // The entry's Fizz hint at default priority, after the head chunk
+      // scripts (entry-preload-priority.ts).
+      const entryUrl = bootstrap.bootstrapModules?.[0];
+      const html = entryUrl
+        ? htmlStream.pipeThrough(entryPreloadPriorityTransform(entryUrl, nonce))
+        : htmlStream;
+
       // Inject RSC payload into HTML as <script nonce="...">__FLIGHT_DATA__</script>
-      return htmlStream.pipeThrough(injectRSCPayload(rscStream2, { nonce }));
+      return html.pipeThrough(injectRSCPayload(rscStream2, { nonce }));
     } catch (error) {
       reportRenderError(onError, error);
       throw error;
@@ -952,6 +983,12 @@ export function createShellCaptureHandler<TEnv = unknown>(
         const result = await prerenderPromise;
         prelude = await readStreamToUint8Array(result.prelude);
         postponed = result.postponed;
+        // Same hint rewrite as renderHTML, applied to the stored prelude; a
+        // resume never re-emits the bootstrap pair (Fizz clears it).
+        const entryUrl = bootstrap.bootstrapModules?.[0];
+        if (entryUrl) {
+          prelude = rewriteEntryPreloadPriority(prelude, entryUrl);
+        }
       } catch (error) {
         // Identity match: swallow ONLY our own deliberate abort
         // (error === abortReason). Not error.name — capture aborts before this

package/src/ssr/preinit-client-references.ts

@@ -81,11 +81,23 @@ export function runWithPreinitNonce<T>(
  *
  * Known trades (deliberate, measured neutral-to-positive on the e2e apps —
  * PR #694 has the Lighthouse/hydration numbers):
- * - Fetch priority: an executing async module script fetches at Chromium's
- *   async-script priority, below a bare modulepreload hint; preinitModule
- *   forwards no fetchPriority (react-dom's public API drops it — only
- *   `preinit` forwards it). Execution-overlap is bought with hint priority,
- *   the same trade Next.js ships via ReactDOM.preinit.
+ * - Fetch priority: Chromium gives a parser-inserted `async` module script
+ *   initial priority High: below the render-blocking stylesheet (Highest),
+ *   and alongside the LCP image once Chromium boosts the in-viewport image to
+ *   High (#1021). Every head chunk gets the same priority: the shared
+ *   dependency chunks (react, router, entry.rsc and the bundler runtime) and
+ *   every client-component chunk. The entry itself is a Fizz bootstrapModules
+ *   hint, not a preinit (Fizz claims its URL, so this hook's call for it is
+ *   inert); the handlers serve that hint at default priority, High as well,
+ *   after these scripts (entry-preload-priority.ts, #1025).
+ *   Lowering the chunks to `fetchpriority="low"` was measured and rejected
+ *   (#1021; Chromium 153, 20 interleaved runs per variant and cell). On pages
+ *   with images above the fold the Low chunks queue behind the boosted
+ *   images: hydration came 206 to 6407 ms later on HTTP/1.1 and 65 to 642 ms
+ *   later on HTTP/2. The one gain, FCP -136 ms, needed an image-free page
+ *   with 35 KB of render-blocking CSS on HTTP/1.1 Slow 4G, and hydration was
+ *   still 98 ms later there. `headScripts: "preload"` is the way to get Low
+ *   chunk fetches.
  * - Build only: plugin-rsc's dev load path reports `js: []` per reference, so
  *   dev documents have no head chunk scripts — a client module whose module
  *   scope assumes body-parsed DOM can break in production only. The

package/src/vite/plugin-types.ts

@@ -83,6 +83,12 @@ export interface ClientChunkMeta {
  *   strategy**. It splits app `"use client"` modules by **route id** — the segment
  *   after a route-root directory (`routes`, `app`, `pages`, `features`, `handlers`,
  *   …) — so `routes/dashboard/**` becomes `app-dashboard` at any nesting depth.
+ *   The first marker in the path wins, except that an `app/` directly followed
+ *   by another marker with a directory after it is treated as a source root:
+ *   `app/routes/product/**` becomes `app-product`, while `app/dashboard/**`
+ *   (Next-style), `app/components/**` and files directly in `app/routes/` stay
+ *   `app-dashboard` / `app-components` / `app-routes`. The same route id under
+ *   different markers is one group.
  *   Where it finds NO route structure (a flat `src/components/`, or host sub-apps
  *   already split by a dynamic `import()`), it inherits the default grouping
  *   unchanged — so the shared `src/components` chunk stays shared and host apps do
@@ -94,10 +100,14 @@ export interface ClientChunkMeta {
  *   back to the default grouping for that one module. Forwarded directly to
  *   `@vitejs/plugin-rsc`'s `clientChunks`.
  *
- * Every module maps to exactly one group, so there is no byte duplication: a
- * component used by two routes lives in one group and is fetched whenever it
- * renders. Put genuinely shared client components OUTSIDE route directories so
- * they land in the shared group rather than one route's chunk.
+ * Every module maps to exactly one group, so there is no byte duplication. A
+ * group is also the loading unit: rendering any one member downloads the whole
+ * group's chunk, every other member included. A component used by two routes
+ * lives in one group, and rendering it on either route fetches that entire
+ * group. Put genuinely shared client components OUTSIDE route directories so
+ * they land in the shared group rather than one route's chunk, and keep an
+ * always-rendered component (a layout header) out of a large group.
+ * `DEBUG=rango:chunks vite build` logs each group's module count and size.
  *
  * @default true
  */
@@ -137,14 +147,18 @@ interface RangoBaseOptions {
    * - `"preinit"` (**default**): client-reference chunks render as EXECUTING
    *   `<script type="module" async>` tags hoisted into `<head>` (upgrading
    *   plugin-rsc's modulepreload hints in place), and the browser entry ships
-   *   as Fizz `bootstrapModules` — a head `modulepreload fetchpriority=low`
-   *   hint plus the executing end-of-shell `id="_R_"` module script. Chunk
+   *   as Fizz `bootstrapModules` — a `modulepreload` hint after the head
+   *   chunk scripts (default priority; Fizz's `fetchpriority=low` is dropped,
+   *   #1025)
+   *   plus the executing end-of-shell `id="_R_"` module script. Chunk
    *   execution overlaps body streaming instead of waiting for the hydration
    *   import walk; under PPR everything lands in the stored shell prelude.
    * - `"preload"`: the previous behavior — `<link rel="modulepreload">` hints
    *   only, entry as an inline `import()` script at end of shell. Chunks
    *   fetch+compile early but execute only when hydration imports them.
    *
+   * Any other value throws when the generated SSR entry is built.
+   *
    * Build-only for the chunk half: plugin-rsc resolves no JS deps per client
    * reference in dev, so dev documents carry no head chunk scripts in either
    * mode (the bootstrap conversion does apply in dev). Trades and upstream

package/src/vite/plugins/virtual-entries.ts

@@ -65,13 +65,20 @@ function emitProgressiveChunkSize(value: number): string {
  * option: "preinit" (default) installs the client-reference preinit hook and
  * threads `getClientEntryUrl` so Fizz emits `bootstrapModules`;
  * "preload" omits the hook and uses the deprecated inline
- * `loadBootstrapScriptContent` bootstrap.
+ * `loadBootstrapScriptContent` bootstrap. Any other value throws: an unknown
+ * string such as "prenit" used to run as "preinit" silently
+ * (`headScripts !== "preload"` since #694).
  */
 export function getVirtualEntrySSR(
   headScripts: HeadScriptsOption = "preinit",
   progressiveChunkSize?: number,
 ): string {
-  const preinit = headScripts !== "preload";
+  if (headScripts !== "preinit" && headScripts !== "preload") {
+    throw new Error(
+      `rango({ headScripts }) must be "preinit" or "preload", received ${JSON.stringify(headScripts)}`,
+    );
+  }
+  const preinit = headScripts === "preinit";
   // The preload variant drops the preinit-only imports/install and swaps the
   // bootstrap dep, all built here so the template below stays a single
   // unconditional shape.

package/src/vite/rango.ts

@@ -32,6 +32,7 @@ import {
   getManualChunks,
 } from "./utils/shared-utils.js";
 import {
+  clientChunksReport,
   resolveClientChunks,
   type ClientChunkContext,
 } from "./utils/client-chunks.js";
@@ -537,6 +538,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     );
     plugins.push(clientRefDedup());
   }
+  plugins.push(clientChunksReport());
 
   plugins.push({
     name: "@rangojs/router:client-component-hmr",

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

@@ -1,5 +1,7 @@
+import type { Plugin } from "vite";
+import { gzipSync } from "node:zlib";
 import type { ClientChunkMeta, ClientChunks } from "../plugin-types.js";
-import { createRangoDebugger, NS } from "../debug.js";
+import { createRangoDebugger, NS, type Debugger } from "../debug.js";
 import { hashRefKey } from "../plugins/client-ref-hashing.js";
 
 /** The callback shape @vitejs/plugin-rsc's `clientChunks` option accepts. */
@@ -97,6 +99,20 @@ const ROUTE_ROOT_DIRS = new Set([
   "sections",
 ]);
 
+/**
+ * Markers that double as a conventional source root. `app/` is both a Next-style
+ * route root (`app/<segment>/…`) and the source root of many apps
+ * (`app/components`, `app/routes/<id>`). Keying on the segment after it put every
+ * route under `app/routes/` into one `app-routes` group, and a group is the
+ * loading unit, so rendering any one member downloaded every route's client code
+ * (#1022). A source-root marker therefore defers to a marker that IMMEDIATELY
+ * follows it when that inner marker has a route directory after it
+ * (`app/routes/<id>/…` -> `app-<id>`). Anything else after `app/` (including
+ * `app/components/`) is still the Next-style route id. Only these markers defer:
+ * `routes/view/<sub>/…` keeps `view` as the route id.
+ */
+const SOURCE_ROOT_DIRS = new Set(["app"]);
+
 /**
  * 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
@@ -116,8 +132,11 @@ const ROUTE_ROOT_DIRS = new Set([
  * 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.
+ * 3. The first {@link ROUTE_ROOT_DIRS} marker with a directory after it -> key on
+ *    that next segment (the route id), robust to any nesting depth. A
+ *    {@link SOURCE_ROOT_DIRS} marker (`app`) directly followed by another marker
+ *    with a directory after it defers to that inner marker:
+ *    `app/routes/<id>/…` -> `app-<id>`, while `app/<segment>/…` -> `app-<segment>`.
  * 4. Otherwise `undefined` (inherit the default `serverChunk` grouping).
  */
 export function directoryClientChunks(
@@ -140,17 +159,21 @@ export function directoryClientChunks(
   }
   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;
-      }
-    }
+  // 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.
+  const isMarkerAt = (i: number) =>
+    i < dirCount - 1 && ROUTE_ROOT_DIRS.has(segments[i].toLowerCase());
+  for (let i = 0; i < dirCount - 1; i++) {
+    if (!isMarkerAt(i)) continue;
+    // A source root (`app/`) yields to an inner marker right after it.
+    const marker =
+      SOURCE_ROOT_DIRS.has(segments[i].toLowerCase()) && isMarkerAt(i + 1)
+        ? i + 1
+        : i;
+    const group = `app-${sanitizeGroup(segments[marker + 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.
@@ -182,3 +205,46 @@ export function resolveClientChunks(
   if (option === true) return (meta) => directoryClientChunks(meta, ctx);
   return option;
 }
+
+/** Module-id prefix of the per-group virtual module @vitejs/plugin-rsc emits. */
+const CLIENT_GROUP_PREFIX = "\0virtual:vite-rsc/client-references/group/";
+
+/**
+ * Build-end group report under `DEBUG=rango:chunks`: one line per client
+ * reference group with its client-reference count and the size of the group's
+ * own chunk (code split into shared chunks such as `react`/`router` is not
+ * counted). A group is the loading unit (plugin-rsc imports the group's virtual
+ * module to resolve any one member), so a large group that an always-rendered
+ * component belongs to is downloaded on every route; this line makes that
+ * visible. Covers every group, including ones named by a custom `clientChunks`
+ * function or by plugin-rsc's default `serverChunk` grouping. `undefined` when
+ * the namespace is off, so a normal build does not register it. Group names are
+ * printed with NUL escaped: plugin-rsc's default group is named
+ * `facade:\0virtual:…`, and a raw NUL makes `grep` treat the output as binary
+ * and drop that line, usually the largest group. `log` is injectable for tests.
+ */
+export function clientChunksReport(
+  log: Debugger | undefined = debugChunks,
+): Plugin | undefined {
+  if (!log) return undefined;
+  return {
+    name: "@rangojs/router:client-chunks-report",
+    apply: "build",
+    applyToEnvironment: (env) => env.name === "client",
+    generateBundle(_options, bundle) {
+      for (const chunk of Object.values(bundle)) {
+        if (chunk.type !== "chunk") continue;
+        const facade = chunk.facadeModuleId;
+        if (!facade?.startsWith(CLIENT_GROUP_PREFIX)) continue;
+        log(
+          "group %s: %d client reference(s), %d B (%d B gzip) -> %s",
+          facade.slice(CLIENT_GROUP_PREFIX.length).replaceAll("\0", "\\0"),
+          this.getModuleInfo(facade)?.importedIds.length ?? 0,
+          Buffer.byteLength(chunk.code),
+          gzipSync(chunk.code).length,
+          chunk.fileName,
+        );
+      }
+    },
+  };
+}