@rangojs/router 0.9.0 → 0.10.1

package/src/vite/discovery/state.ts

@@ -45,6 +45,12 @@ export interface PluginOptions {
    * capture endpoint with the app's configured head-script strategy.
    */
   headScripts?: import("../plugin-types.js").HeadScriptsOption;
+  /**
+   * rango({ progressiveChunkSize }) — threaded alongside headScripts so the
+   * temp server's virtual SSR entry bakes the app's configured Fizz outlining
+   * budget into its capture/render handlers.
+   */
+  progressiveChunkSize?: number;
 }
 
 export interface PrecomputedEntry {

package/src/vite/plugin-types.ts

@@ -159,6 +159,34 @@ interface RangoBaseOptions {
    */
   headScripts?: HeadScriptsOption;
 
+  /**
+   * React Fizz `progressiveChunkSize`, forwarded to the document renders the
+   * generated SSR entry performs: renderToReadableStream (live SSR) and
+   * prerender (PPR shell capture); resume() inherits the capture value from
+   * the stored postponed state.
+   *
+   * Controls COMPLETED-boundary outlining. Once the shell exceeds this budget
+   * (React's default is 12800 bytes — any real document), Fizz moves every
+   * completed Suspense boundary over ~500 bytes out of its document position
+   * to an end-of-stream `<div hidden>` + `$RC()` script reveal. Raise it (e.g.
+   * `Number.MAX_SAFE_INTEGER`) to keep completed content inline: in-place for
+   * non-executing HTML consumers, no reveal step. Boundaries with suspensey
+   * content (hoisted stylesheets) still outline — their reveal must wait for
+   * the CSS. Trade-off: inline content delays later shell bytes behind it,
+   * which is why React outlines by default.
+   *
+   * When UNSET, document renders whose matched chain has a
+   * `loader(Def, { ssr: false })` entry auto-raise to MAX_SAFE_INTEGER — the
+   * loader was awaited before first flush precisely so its content ships
+   * in-place, and outlining the boundary it feeds would defeat that. Setting
+   * an explicit value disables the auto-raise. The auto-raise is live-SSR
+   * only; captured shells use the explicit value or React's default.
+   *
+   * Apps with a custom SSR entry set this per-handler via
+   * `SSRDependencies.progressiveChunkSize`.
+   */
+  progressiveChunkSize?: number;
+
   /**
    * Filter which files route discovery scans, by glob. Paths are matched
    * root-relative (e.g. `src/routes/**`). `include` restricts discovery to

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

@@ -48,6 +48,18 @@ async function initializeApp() {
 initializeApp().catch(console.error);
 `.trim();
 
+function emitProgressiveChunkSize(value: number): string {
+  if (value === Number.POSITIVE_INFINITY) {
+    return "Number.POSITIVE_INFINITY";
+  }
+  if (!Number.isFinite(value)) {
+    throw new Error(
+      `rango({ progressiveChunkSize }) must be a finite number or Infinity, received ${String(value)}`,
+    );
+  }
+  return JSON.stringify(value);
+}
+
 /**
  * Generate the virtual SSR entry. `headScripts` mirrors the rango() plugin
  * option: "preinit" (default) installs the client-reference preinit hook and
@@ -56,6 +68,7 @@ initializeApp().catch(console.error);
  */
 export function getVirtualEntrySSR(
   headScripts: HeadScriptsOption = "preinit",
+  progressiveChunkSize?: number,
 ): string {
   const preinit = headScripts !== "preload";
   // The preload variant drops exactly three preinit-only lines, all built
@@ -73,6 +86,16 @@ installClientReferencePreinit(setOnClientReference);
 `
     : "";
   const hs = JSON.stringify(headScripts);
+  // Emitted into all three handlers: live SSR and shell capture consume it
+  // directly; the resume handler receives it for dep-shape uniformity (resume()
+  // itself inherits the capture value from the postponed state). Finite numbers
+  // stringify exactly (incl. MAX_SAFE_INTEGER). Infinity is emitted as
+  // Number.POSITIVE_INFINITY — JSON.stringify(Infinity) is null, which React
+  // would treat as "no budget" rather than "never outline".
+  const pcs =
+    progressiveChunkSize !== undefined
+      ? `\n  progressiveChunkSize: ${emitProgressiveChunkSize(progressiveChunkSize)},`
+      : "";
   return `
 import {
   ${depsImportNames}
@@ -90,7 +113,7 @@ export const renderHTML = createSSRHandler({
   createFromReadableStream,
   renderToReadableStream,
   injectRSCPayload,
-  headScripts: ${hs},
+  headScripts: ${hs},${pcs}
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
@@ -101,7 +124,7 @@ export const captureShellHTML = createShellCaptureHandler({
   injectRSCPayload,
   prerender,
   resume,
-  headScripts: ${hs},
+  headScripts: ${hs},${pcs}
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
@@ -112,7 +135,7 @@ export const resumeShellHTML = createShellResumeHandler({
   injectRSCPayload,
   prerender,
   resume,
-  headScripts: ${hs},
+  headScripts: ${hs},${pcs}
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });

package/src/vite/rango.ts

@@ -269,6 +269,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     plugins.push(
       createVirtualEntriesPlugin(finalEntries, undefined, {
         headScripts: resolvedOptions.headScripts,
+        progressiveChunkSize: resolvedOptions.progressiveChunkSize,
       }),
     );
     plugins.push(performanceTracksPlugin());
@@ -519,6 +520,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     plugins.push(
       createVirtualEntriesPlugin(finalEntries, routerRef, {
         headScripts: resolvedOptions.headScripts,
+        progressiveChunkSize: resolvedOptions.progressiveChunkSize,
       }),
     );
     plugins.push(performanceTracksPlugin());
@@ -585,6 +587,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
       discovery: options?.discovery,
       clientChunkCtx,
       headScripts: resolvedOptions.headScripts,
+      progressiveChunkSize: resolvedOptions.progressiveChunkSize,
     }),
   );
 

package/src/vite/router-discovery.ts

@@ -265,7 +265,10 @@ async function createTempRscServer(
               },
               load(id: string) {
                 return id === "\0rango-temp-real-ssr-entry"
-                  ? getVirtualEntrySSR(state.opts?.headScripts)
+                  ? getVirtualEntrySSR(
+                      state.opts?.headScripts,
+                      state.opts?.progressiveChunkSize,
+                    )
                   : null;
               },
             } satisfies import("vite").Plugin,
@@ -1707,6 +1710,8 @@ export function createRouterDiscoveryPlugin(
           if (expectedEpoch === undefined) return;
           void (async () => {
             const deadline = Date.now() + 15_000;
+            let reloadBackoffMs = 100;
+            let nextReloadAt = Date.now() + reloadBackoffMs;
             do {
               if (devServerClosed || expectedEpoch !== s.devDiscoveryEpoch) {
                 return;
@@ -1732,10 +1737,18 @@ export function createRouterDiscoveryPlugin(
                   publishDevDiscoveryReady(expectedEpoch);
                   return;
                 }
+                await response.body?.cancel().catch(() => {});
                 // A response without the expected epoch proves an older worker
                 // evaluation won the race after the initial invalidation. Clear
-                // that completed evaluation and retry the reload.
-                reloadWorkerd();
+                // that completed evaluation and retry the reload. Back off the
+                // retries: reloading faster than workerd can evaluate prevents
+                // convergence and retains overlapping module generations.
+                const now = Date.now();
+                if (now >= nextReloadAt) {
+                  reloadWorkerd();
+                  reloadBackoffMs = Math.min(reloadBackoffMs * 2, 1_000);
+                  nextReloadAt = now + reloadBackoffMs;
+                }
               } catch {}
             } while (Date.now() < deadline);
 
@@ -1949,26 +1962,25 @@ export function createRouterDiscoveryPlugin(
             // the entry + router sources so the import re-creates the routers
             // against the refreshed projection (installed by the pre-entry
             // refresh in discover-routers.ts).
-            if (isUseClient && hasClientUrls) {
-              const rscGraph = (server.environments as any)?.rsc?.moduleGraph;
+            const mainRscEnv = (server.environments as any)?.rsc;
+            if (isUseClient && hasClientUrls && mainRscEnv?.runner) {
+              const rscGraph = mainRscEnv.moduleGraph;
               if (rscGraph?.getModulesByFile) {
                 // Importers must be invalidated too: the virtual RSC entry
                 // holds a live `import { router }` binding, and re-evaluating
                 // router.tsx alone leaves that binding on the OLD instance —
                 // the request pipeline would keep serving the stale mount.
-                // Same blast radius as a server urls edit (Vite's own
-                // file-change invalidation propagates upward identically).
-                const invalidateWithImporters = (
-                  mod: any,
-                  seen: Set<any>,
-                ): void => {
-                  if (!mod || seen.has(mod)) return;
-                  seen.add(mod);
-                  rscGraph.invalidateModule(mod);
-                  for (const importer of mod.importers ?? []) {
-                    invalidateWithImporters(importer, seen);
-                  }
-                };
+                // Vite's invalidateModule already walks importers. Share its
+                // seen set across roots instead of recursively starting a new
+                // traversal at every importer (quadratic on a large graph).
+                // Vite's walk skips HMR-accepting importers and soft-invalidates
+                // static ones (vs the old unconditional hard walk) — safe here:
+                // the entry and every router source are invalidated directly as
+                // roots, and ancestors get the exact treatment Vite's own
+                // file-change propagation applies on a server urls edit.
+                // Cloudflare has no local runner and skips this block: its temp
+                // discovery graph and workerd graph are invalidated wholesale
+                // by refreshRuntimeDiscovery() after this watcher event.
                 const routerSourceFiles = new Set<string>();
                 if (s.resolvedEntryPath) {
                   routerSourceFiles.add(resolve(s.resolvedEntryPath));
@@ -1991,7 +2003,7 @@ export function createRouterDiscoveryPlugin(
                     continue;
                   }
                   for (const mod of mods) {
-                    invalidateWithImporters(mod, seen);
+                    rscGraph.invalidateModule(mod, seen);
                   }
                 }
                 debugDiscovery?.(

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

@@ -110,7 +110,10 @@ export function normalizeHostRouterEntry(
 export function createVirtualEntriesPlugin(
   entries: { client: string; ssr: string; rsc?: string },
   routerPathRef?: { path?: string; kind?: "router" | "host" },
-  options?: { headScripts?: HeadScriptsOption },
+  options?: {
+    headScripts?: HeadScriptsOption;
+    progressiveChunkSize?: number;
+  },
 ): Plugin {
   // Build virtual modules map based on which entries use virtual IDs
   const virtualModules: Record<string, string> = {};
@@ -119,7 +122,10 @@ export function createVirtualEntriesPlugin(
     virtualModules[VIRTUAL_IDS.browser] = VIRTUAL_ENTRY_BROWSER;
   }
   if (entries.ssr === VIRTUAL_IDS.ssr) {
-    virtualModules[VIRTUAL_IDS.ssr] = getVirtualEntrySSR(options?.headScripts);
+    virtualModules[VIRTUAL_IDS.ssr] = getVirtualEntrySSR(
+      options?.headScripts,
+      options?.progressiveChunkSize,
+    );
   }
 
   // RSC entry is resolved lazily in load() because routerPath may be