@rangojs/router 0.19.0 → 0.20.0

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,
+        );
+      }
+    },
+  };
+}