@rangojs/router 0.19.0 → 0.20.0

package/dist/types/cache/cache-exec-scope.d.ts

@@ -30,6 +30,12 @@
  */
 export interface CacheExecScope {
     readonly parent?: CacheExecScope;
+    /**
+     * Loader values its chain read through an already-started execution, to
+     * their loader ids (cache-tag.ts readStartedLoaderValue), checked again
+     * before its write (#1011).
+     */
+    loaderReads?: Map<object, string>;
 }
 /**
  * Run a callback whose identity reads never reach a shared entry, so

package/dist/types/cache/cache-tag.d.ts

@@ -10,7 +10,8 @@
  * profile/DSL tags before storing.
  */
 import { type RequestContext } from "../server/request-context.js";
-import { type LoaderIdentityRead } from "../server/context.js";
+import { type LoaderIdentityRead, type LoaderRunIdentity } from "../server/context.js";
+import { type CacheExecScope } from "./cache-exec-scope.js";
 import type { ExecutionStart } from "./tag-invalidation.js";
 /**
  * Call `fn` outside any "use cache" tag scope: detached work a cached body
@@ -153,6 +154,28 @@ export declare function markIdentityRead(set: Set<string>, read: LoaderIdentityR
  * recorded, nearest first (breadth-first, so the execution's own read wins).
  */
 export declare function recordedIdentityRead(root: Set<string>): LoaderIdentityRead | undefined;
+/**
+ * `value` is the promise of the execution `run` records, started by the
+ * current execution (if any), which reads it. Both loader runners call it
+ * (loader-resolution.ts createLoaderExecutor, request-context.ts
+ * createUseFunction).
+ */
+export declare function trackLoaderRun(value: object, run: LoaderRunIdentity): void;
+/**
+ * A ctx.use(Loader) or getRequestContext().use(Loader) read that returns an
+ * already-started value (the request memo, a loader cache() binding's value).
+ * The current loader execution, if any, links it (it reads the value).
+ * Inside a "use cache" body the value is refused when its execution read
+ * request identity, as a body entered there would have been
+ * (guardIdentityRead). The check runs once the value settles, so a read the
+ * body makes after an await counts. Each enclosing execution also notes the
+ * value, and checks it again after encoding its result
+ * (assertLoaderReadsClean): a read that settles after the value (a nested
+ * promise in it) then fails the write instead.
+ */
+export declare function readStartedLoaderValue<T>(value: Promise<T>, loaderId: string): Promise<T>;
+/** Throw when a loader value `scope` read carries an identity read. */
+export declare function assertLoaderReadsClean(scope: CacheExecScope): void;
 /** `root`'s tags plus those of every set it links to, transitively. */
 export declare function flattenRecordedTags(root: Set<string>): Set<string>;
 /** Record where the execution recording into `set` started. */

package/dist/types/server/context.d.ts

@@ -539,8 +539,44 @@ export interface LoaderIdentityRead {
  * (cache-tag.ts recordedIdentityRead), so both orders fail the same way.
  * Response directives do not record: a key cannot make a skipped body's side
  * effect reach a HIT.
+ *
+ * The read also lands on the execution's LoaderRunIdentity (#1011), which
+ * every execution has, from either loader runner (runInsideLoaderRun).
  */
 export declare function recordLoaderIdentityRead(surface: string, verb?: LoaderIdentityReadVerb): void;
+/**
+ * One loader execution's request-identity record (#1011): the first identity
+ * read its body made, and the executions whose values it read with
+ * ctx.use(Loader). Every execution has one; the recorded-tag sets that carry
+ * the same reads for a loader cache() fill (cache-tag.ts) exist only in a
+ * request that binds one.
+ *
+ * A "use cache" function that reads a loader's value through the request
+ * memo (a handler, the route's loader() binding or a parent layout's started
+ * it first) does not run the body, so guardIdentityRead never sees the read.
+ * Scar: the entry, keyed without the cookie, stored the first visitor's value
+ * and served it to the next. cache-tag.ts readStartedLoaderValue refuses such
+ * a value through this record.
+ */
+export interface LoaderRunIdentity {
+    readonly loaderId: string;
+    read?: LoaderIdentityRead;
+    reads?: Set<LoaderRunIdentity>;
+}
+/**
+ * Run a loader body with `run` as its identity record: both loader runners
+ * (loader-resolution.ts createLoaderExecutor, request-context.ts
+ * createUseFunction) enter it around the loader function.
+ */
+export declare function runInsideLoaderRun<T>(run: LoaderRunIdentity, fn: () => T): T;
+/** The innermost loader execution's identity record (runInsideLoaderRun). */
+export declare function getLoaderRunIdentity(): LoaderRunIdentity | undefined;
+/**
+ * The error a "use cache" function's read of a loader value fails with when
+ * the loader's execution, or one whose value it read, made `read` (#1011).
+ * Worded like guardIdentityRead's "use cache" refusal, naming the loaders.
+ */
+export declare function useCacheLoaderIdentityError(read: LoaderIdentityRead, loaderId: string): Error;
 /** The error a loader cache() fill with no declared key fails with (#972). */
 export declare function loaderCacheIdentityError(read: LoaderIdentityRead, cachedLoaderId: string): Error;
 /**
@@ -632,7 +668,8 @@ export declare function runInsideLoaderScope<T>(fn: () => T): T;
  * and handler-invoked via ctx.use) so request-scoped reads inside a loader
  * never trip the cache() guard — a route cache() never stores loader values.
  * A "use cache" body the loader was entered in still refuses them
- * (guardIdentityRead).
+ * (guardIdentityRead); one that reads the value later refuses what the run
+ * recorded (runInsideLoaderRun, cache-tag.ts readStartedLoaderValue).
  */
 export declare function runInsideLoaderBodyScope<T>(fn: () => T, loaderId?: string, tags?: Set<string>): T;
 /** The innermost loader body's execution tag set (runInsideLoaderBodyScope). */

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.0",
+  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";
@@ -6957,6 +6987,7 @@ var NON_CACHEABLE_READ = {
     ...requestReadCaptureFix("per-request variables")
   }
 };
+var loaderRunALS = globalThis[/* @__PURE__ */ Symbol.for("rangojs-router:loader-run-identity")] ??= new AsyncLocalStorage2();
 function getLoaderBodyTags() {
   return loaderBodyScopeALS.getStore()?.tags;
 }
@@ -9938,6 +9969,7 @@ globalThis[/* @__PURE__ */ Symbol.for("rangojs-router:identity-read-recorder")]
   if (set === void 0 || identityReads.has(set)) return;
   identityReads.set(set, { surface, verb, bodyId: getCurrentLoaderBodyId() });
 };
+var loaderRuns = globalThis[/* @__PURE__ */ Symbol.for("rangojs-router:loader-runs")] ??= /* @__PURE__ */ new WeakMap();
 
 // src/router/router-context.ts
 import { AsyncLocalStorage as AsyncLocalStorage4 } from "async_hooks";
@@ -13347,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.0",
+  "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/cache-guide/SKILL.md

@@ -560,9 +560,9 @@ Loaders are exempt from the `cache()` guard because they run outside the cache
 scope and resolve fresh every request. A loader with its own `cache()` does not:
 its value is stored, so it falls under the loader `cache()` guard above. Nor
 does a loader awaited inside a `"use cache"` body: its value is part of what the
-function returns, so the same reads throw there when the cached function is
-the first to read it in the request (an already-started loader's value is
-stored unchecked).
+function returns, so the same reads throw there, whether the cached function
+starts the loader or reads a value a handler or a `loader()` binding already
+started.
 
 ## Loaders Are Always Fresh
 

package/skills/caching/SKILL.md

@@ -870,10 +870,10 @@ This is the **consumption-lane rule**, and it holds for every shared
 artifact — `cache()`, `"use cache"`, and the PPR shell (`/ppr`): handler
 consumption = baked copy; client-side `useLoader` = live. The tiers differ on
 identity reads inside a handler-consumed loader: `cache()` permits them (the
-leak above); `"use cache"` throws when the cached function is the first to
-read the loader in the request, because the loader body then runs inside it
-and its value is part of the result (a loader already started elsewhere
-returns its value unchecked, and that value is stored); a PPR shell capture
+leak above); `"use cache"` throws, because the loader's value is part of the
+result: inside the loader body when the cached function starts it, and at
+`ctx.use()` when a handler or a `loader()` binding started it first and its
+run made such a read; a PPR shell capture
 refuses them and the route stays uncached. It is stated once in `/rango` → Invariants.
 
 ```typescript

package/skills/parallel/SKILL.md

@@ -280,7 +280,7 @@ layout(<AccountLayout />, () => [
 
 A slot's `loading()` (whether from `handler.use` or explicit) makes that slot an independent streaming unit, exactly as in the **Streaming Behavior** section above.
 
-Under a shared artifact (`cache()`, `"use cache"`, a PPR shell), the server-side `await ctx.use(CartLoader)` above is the BAKED lane — the capture-time value freezes into the artifact. An identity read (`cookies()`, `headers()`, `ctx.request.headers`) inside the loader bakes too under `cache()`; inside `"use cache"` it throws when the cached function is the first to read the loader in the request (an already-started loader's value is stored unchecked); under a PPR shell it refuses the capture, so the route stays uncached. Consume the loader client-side (`useLoader` in a `"use client"` component, the slot's `loading()` as its boundary) to keep the slot live per request. One rule, stated once: `/rango` → Invariants ("the consumption-lane rule").
+Under a shared artifact (`cache()`, `"use cache"`, a PPR shell), the server-side `await ctx.use(CartLoader)` above is the BAKED lane — the capture-time value freezes into the artifact. An identity read (`cookies()`, `headers()`, `ctx.request.headers`) inside the loader bakes too under `cache()`; inside `"use cache"` it throws, whichever code started the loader first; under a PPR shell it refuses the capture, so the route stays uncached. Consume the loader client-side (`useLoader` in a `"use client"` component, the slot's `loading()` as its boundary) to keep the slot live per request. One rule, stated once: `/rango` → Invariants ("the consumption-lane rule").
 
 The `parallel` mount site has the narrowest allow-list for `handler.use` items — slots cannot bring their own middleware or layout, only `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, and `transition`. See [skills/handler-use](../handler-use/SKILL.md) for the full table and merge rules.
 

package/skills/rango/SKILL.md

@@ -135,8 +135,8 @@ stated, greppable contract.
   `ctx.request.headers`, a `{ cache: false }` variable) inside that loader
   are permitted under a route `cache()` (a documented footgun; see
   `/caching` → "Cache purity & tainted objects"). They throw inside
-  `"use cache"` (when the cached function is the first to read the loader in
-  the request; an already-started loader's value is stored unchecked) and REFUSE a PPR capture: the route serves uncached until
+  `"use cache"` (whichever code started the loader first: a handler, a
+  `loader()` binding, or the cached function itself) and REFUSE a PPR capture: the route serves uncached until
   the read moves to a live loader. Client-side consumption
   (`useLoader` in a `"use client"` component) is the LIVE lane. DSL
   `loader()` segments follow their PPR lane (only `ssr: false` bakes; see

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/skills/use-cache/SKILL.md

@@ -283,11 +283,14 @@ is part of that body: its value is captured into the shared cache entry like
 any other computed data, so a `{ cache: false }` variable read there throws,
 exactly as `cookies()`, `headers()`, `ctx.request.headers` and a theme read do
 (one guard follows the
-cached body's whole async chain, loaders included). The check runs only when
-the loader body starts inside the cached function: a loader something else in
-the request already started (a handler's `ctx.use()`, a route `loader()`)
-returns its memoized value without it, and that value is still stored in the
-entry. Read the value outside and pass it in as an argument. Handler/cached-scope consumption = baked copy,
+cached body's whole async chain, loaders included). The order does not
+matter: a loader something else in the request already started (a handler's
+`ctx.use()`, the route's or a parent layout's `loader()`) returns its memoized
+value, and `ctx.use()` (or `getRequestContext().use()`) inside the cached function rejects with the same error
+when that run, or a loader it read, made such a read. A read the run makes
+after its value settled (a nested promise in the value) fails the entry's
+write instead: the caller gets its own value, nothing is stored, and `onError`
+reports it. Read the value outside and pass it in as an argument. Handler/cached-scope consumption = baked copy,
 client-side `useLoader` = live (the consumption-lane rule, `/rango` →
 Invariants). Under a route `cache()` a loader body's reads stay allowed (the
 route entry never stores a loader's value); during a PPR capture they refuse

package/src/cache/cache-exec-scope.ts

@@ -34,6 +34,12 @@ import { _setCacheExecScopeProbe } from "./taint.js";
  */
 export interface CacheExecScope {
   readonly parent?: CacheExecScope;
+  /**
+   * Loader values its chain read through an already-started execution, to
+   * their loader ids (cache-tag.ts readStartedLoaderValue), checked again
+   * before its write (#1011).
+   */
+  loaderReads?: Map<object, string>;
 }
 
 const cacheExecStorage = new AsyncLocalStorage<CacheExecScope>();

package/src/cache/cache-runtime.ts

@@ -47,6 +47,7 @@ import { encodeKV } from "../encode-kv.js";
 import { runBackground } from "./background-task.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import {
+  assertLoaderReadsClean,
   normalizeTags,
   outsideCacheTagScope,
   recordRequestTags,
@@ -753,6 +754,7 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
                       // An error row would replace the stale entry; the catch
                       // below reports it and the stale entry keeps serving.
                       if (flightErrors.length > 0) throw flightErrors[0];
+                      assertLoaderReadsClean(bgScope);
                       const freshTags = entryTags(scoped.tags);
                       // One of the refreshed value's tags was invalidated after
                       // the refresh started: written now, a value that may
@@ -972,6 +974,9 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         // promise in the result or a handle value, as an error row and
         // completes normally; stored, every hit would serve that error.
         if (flightErrors.length > 0) throw flightErrors[0];
+        // The encode awaited the result's nested promises: an identity read a
+        // loader value made after it settled is recorded now (#1011).
+        assertLoaderReadsClean(execScope);
       } catch (buildError) {
         // Serialize/handle-encode failed: no envelope for followers (they run
         // fresh) and nothing to write.