@rangojs/router 0.9.0 → 0.10.1

package/AGENTS.md

@@ -10,4 +10,4 @@ Start with the mental model at `node_modules/@rangojs/router/skills/rango/SKILL.
 
 ## Contributing
 
-This package is developed in the monorepo at https://github.com/ivogt/vite-rsc. If you are contributing there rather than consuming the published package, read the root `AGENTS.md` in that repo for the pre-push gate and e2e rules — they apply to the monorepo, not to consumer apps.
+This package is developed in the monorepo at https://github.com/rangojs/rango. If you are contributing there rather than consuming the published package, read the root `AGENTS.md` in that repo for the pre-push gate and e2e rules — they apply to the monorepo, not to consumer apps.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Ivo Todorov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,13 +4,14 @@ A code-first, type-safe React Server Components router. Django-inspired:
 routes are expressed in one visible tree, URLs are built from names, and
 everything past the core is opt-in.
 
-> **Experimental:** This package is under active development. APIs may change
-> between releases. Install with `@experimental` tag.
+> **Pre-1.0:** Rango follows semver 0.x — breaking changes land in minor
+> releases and are noted in the changelog. npm `latest` is the current 0.x
+> release; the `experimental` tag tracks `main` between tagged releases.
 
 This page is a tour: it builds one small shop and meets the entire core API
 along the way — about six primitives. Everything else is opt-in and linked at
 the end. For the design rationale behind these APIs, read
-[Why Rango](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/why-rango.md); this page shows how it feels, that page
+[Why Rango](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/why-rango.md); this page shows how it feels, that page
 argues why it's right.
 
 ## Start a new app
@@ -24,7 +25,8 @@ pnpm create rango my-app
 
 Select a deployment target with `--template basic`, `--template cloudflare`, or
 `--template vercel`. The templates include streaming RSC, typed routes, Server
-Actions, Tailwind CSS, and production deployment configuration. For a plain
+Actions, Tailwind CSS, and production deployment configuration; the scaffolder
+installs the latest `@rangojs/router` release. For a plain
 JavaScript Node app, add `--template basic --js`. With npm, run
 `npm create rango@latest my-app`. The scaffolder currently requires Node.js 24
 or newer.
@@ -34,7 +36,7 @@ or newer.
 If you are adding Rango to an existing Vite RSC project:
 
 ```bash
-npm install @rangojs/router@experimental react @vitejs/plugin-rsc
+npm install @rangojs/router@latest react @vitejs/plugin-rsc
 ```
 
 ```ts
@@ -170,7 +172,7 @@ per group — while matching stays an `O(path length)` prefix trie, identical
 in dev and production. None of this is assumed: the trie is benchmarked
 in-repo against multi-thousand-route manifests, and the lazy guarantees are
 pinned by run-count tests (see
-[matching & lazy discovery](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/internal/matching-and-lazy-discovery.md)).
+[matching & lazy discovery](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/internal/matching-and-lazy-discovery.md)).
 Grow the tree without watching the boot time.
 
 That's a working site. Everything below adds to this app.
@@ -466,19 +468,19 @@ npx rango generate src/             # recursive scan
 
 ### Examples
 
-- [`e2e/mini`](https://github.com/ivogt/vite-rsc/tree/main/packages/rangojs-router/e2e/mini) — single-file demo app
-- [`cloudflare-basic`](https://github.com/ivogt/vite-rsc/tree/main/tests/cloudflare-basic) — Cloudflare Workers with caching, loaders, theme, and pre-rendering
-- [`cloudflare-multi-router`](https://github.com/ivogt/vite-rsc/tree/main/examples/cloudflare-multi-router) — multi-app host routing
-- [`vercel-basic`](https://github.com/ivogt/vite-rsc/tree/main/examples/vercel-basic) — Vercel deployment with `preset: "vercel"`, `VercelCacheStore`, and OTel tracing
-- [`vercel-multi-router`](https://github.com/ivogt/vite-rsc/tree/main/examples/vercel-multi-router) — multi-app host routing on Vercel (single function, routed by Host header)
+- [`e2e/mini`](https://github.com/rangojs/rango/tree/main/packages/rangojs-router/e2e/mini) — single-file demo app
+- [`cloudflare-basic`](https://github.com/rangojs/rango/tree/main/tests/cloudflare-basic) — Cloudflare Workers with caching, loaders, theme, and pre-rendering
+- [`cloudflare-multi-router`](https://github.com/rangojs/rango/tree/main/examples/cloudflare-multi-router) — multi-app host routing
+- [`vercel-basic`](https://github.com/rangojs/rango/tree/main/examples/vercel-basic) — Vercel deployment with `preset: "vercel"`, `VercelCacheStore`, and OTel tracing
+- [`vercel-multi-router`](https://github.com/rangojs/rango/tree/main/examples/vercel-multi-router) — multi-app host routing on Vercel (single function, routed by Host header)
 
 ### Going deeper
 
-- [Why Rango](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/why-rango.md) — the design rationale, claim by claim
+- [Why Rango](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/why-rango.md) — the design rationale, claim by claim
 - [Framework comparison](./skills/comparison/references/framework-comparison.md) — Rango vs Next.js App Router, TanStack Start, and Waku, capability by capability
-- [Docs index](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/README.md) — architecture, caching, prerender, testing
-- [Execution model](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/internal/execution-model.md) — the runtime contract
+- [Docs index](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/README.md) — architecture, caching, prerender, testing
+- [Execution model](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/internal/execution-model.md) — the runtime contract
 
 ## License
 
-MIT
+[MIT](./LICENSE)

package/dist/types/cache/cf/cf-cache-constants.d.ts

@@ -66,7 +66,7 @@ export declare const MAX_REVALIDATION_INTERVAL = 30;
  * This is the default; override per store via
  * `CFCacheStoreOptions.edgeLookupTimeoutMs` (<= 0 disables the budget).
  *
- * 25ms, raised from 10: production Workers logs (autobarn pilot) showed the
+ * 25ms, raised from 10: Workers logs (production pilot) showed the
  * 10ms budget firing frequently on cold colos where the first Cache API touch
  * is slow but healthy — each false positive downgrades a warm L1 HIT to an
  * L2/render round trip that costs far more than the 15ms of extra patience.

package/dist/types/cache/cf/cf-cache-store.d.ts

@@ -322,7 +322,7 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * this, kv.put/get reject with `414 ... exceeds key length limit of 512`
      * and the entry silently never reaches L2 (observed in production for
      * "use cache" items whose serialized args — e.g. a CMS query object — blow
-     * the cap; autobarn pilot). Keys are opaque storage identifiers, so
+     * the cap; production pilot). Keys are opaque storage identifiers, so
      * normalization is semantics-preserving as long as distinct logical keys
      * stay distinct: colliding requires an identical 400-byte prefix AND a
      * 128-bit SHA-256 collision. Deterministic, so every family's read, write,

package/dist/types/outlet-context.d.ts

@@ -17,6 +17,15 @@ export interface OutletContextValue {
      * the resolved `loaderData` record.
      */
     loaderStreams?: Record<string, unknown>;
+    /**
+     * Loader $$ids on this segment that the render awaited before first flush
+     * (loader(Def, { ssr: false })). Dev-diagnostic input only: useLoader uses
+     * it to warn when a read still suspends during SSR on a render that awaited
+     * flagged loaders (ssr-suspension-warning.ts). Present only on streaming
+     * lanes with flagged loaders (document and shell-capture renders); absent
+     * on forceAwait/action lanes.
+     */
+    awaitedLoaderIds?: readonly string[];
     parent?: OutletContextValue | null;
     /** Loading component for Suspense fallback (from segment's loading() definition) */
     loading?: ReactNode;

package/dist/types/outlet-provider.d.ts

@@ -3,12 +3,13 @@ import type { ResolvedSegment } from "./types.js";
 /**
  * Outlet content provider — stores parent context for useLoader chain walking.
  */
-export declare function OutletProvider({ content, parallel, segment, loaderData, loaderStreams, pending, children, }: {
+export declare function OutletProvider({ content, parallel, segment, loaderData, loaderStreams, awaitedLoaderIds, pending, children, }: {
     content: ReactNode;
     parallel?: ResolvedSegment[];
     segment?: ResolvedSegment;
     loaderData?: Record<string, any>;
     loaderStreams?: Record<string, unknown>;
+    awaitedLoaderIds?: readonly string[];
     pending?: boolean;
     children: ReactNode;
 }): ReactNode;

package/dist/types/route-content-wrapper.d.ts

@@ -71,6 +71,9 @@ export interface LoaderBoundaryProps {
      * the children; useLoader suspends per loader at the read site.
      */
     loaderStreams?: Record<string, unknown>;
+    /** Dev-diagnostic input for the SSR suspension warning — see
+     *  OutletContextValue.awaitedLoaderIds. Rides the streams lane only. */
+    awaitedLoaderIds?: readonly string[];
     fallback?: ReactNode;
     outletKey: string;
     outletContent: ReactNode;
@@ -78,4 +81,4 @@ export interface LoaderBoundaryProps {
     parallel?: ResolvedSegment[];
     children: ReactNode;
 }
-export declare function LoaderBoundary({ loaderDataPromise, loaderIds, loaderStreams, fallback, outletKey, outletContent, segment, parallel, children, }: LoaderBoundaryProps): ReactNode;
+export declare function LoaderBoundary({ loaderDataPromise, loaderIds, loaderStreams, awaitedLoaderIds, fallback, outletKey, outletContent, segment, parallel, children, }: LoaderBoundaryProps): ReactNode;

package/dist/types/rsc/nonce.d.ts

@@ -21,6 +21,16 @@ import type { ContextVar } from "../context-var.js";
  * scripts — useNonce() stays undefined for that request.
  */
 export declare const nonce: ContextVar<string>;
+/**
+ * Normalize a NonceProvider return value to the nonce the request runs with.
+ * `true` auto-generates; `false` and the empty string are the per-request
+ * opt-out and normalize to undefined — without this, a falsy string would be
+ * threaded as-is into the render: never written to the token (`if (nonce)`)
+ * yet still `!== undefined` for the ppr shell gate (rsc-rendering.ts
+ * activeNonce), pinning a ppr route to axis 1 with no way to opt a request
+ * out while keeping the provider for the rest of the app.
+ */
+export declare function resolveProviderNonce(result: string | boolean): string | undefined;
 /**
  * Generate a cryptographic nonce for CSP.
  * Returns a 16-byte random value encoded as base64.

package/dist/types/rsc/shell-capture-constants.d.ts

@@ -29,7 +29,7 @@ export declare const SHELL_CAPTURE_MAX_WAIT_MS = 15000;
  * Hard cap on one capture TASK — runShellCapture end to end (both attempts +
  * the in-place retry delay). SHELL_CAPTURE_MAX_WAIT_MS arms only inside
  * captureShellHTML, AFTER the capture's router.match(); a handler wedged on a
- * never-settling upstream await (autobarn pilot: a 30s+ tarpitting fetch)
+ * never-settling upstream await (production pilot: a 30s+ tarpitting fetch)
  * wedges the task with no deadline in force. The task's settle path releases
  * the per-key stampede guard and the serialized capture-queue slot, so an
  * unbounded task strands BOTH for the isolate's lifetime.

package/dist/types/rsc/types.d.ts

@@ -252,9 +252,13 @@ export interface HandlerCacheConfig {
 }
 /**
  * Nonce provider function type.
- * Can return a nonce string, or true to auto-generate one.
+ * Return a nonce string to use verbatim, `true` to auto-generate one, or
+ * `false` (or an empty string) to serve THIS request without a nonce — the
+ * per-request opt-out for apps that nonce globally but declare `ppr` on some
+ * routes: a shell is shared per host+URL and can never bake a per-request
+ * nonce, so a ppr route only captures when its requests opt out here.
  */
-export type NonceProvider<TEnv = unknown> = (request: Request, env: TEnv) => string | true | Promise<string | true>;
+export type NonceProvider<TEnv = unknown> = (request: Request, env: TEnv) => string | boolean | Promise<string | boolean>;
 /**
  * Options for creating an RSC handler
  */

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

@@ -19,6 +19,7 @@ interface RenderToReadableStreamOptions {
     bootstrapModules?: string[];
     nonce?: string;
     formState?: unknown;
+    progressiveChunkSize?: number;
 }
 /**
  * ReadableStream with the allReady promise added by react-dom/server.edge.
@@ -34,6 +35,7 @@ interface PrerenderOptions {
     bootstrapScriptContent?: string;
     bootstrapModules?: string[];
     onError?: (error: unknown) => void;
+    progressiveChunkSize?: number;
 }
 /**
  * Result of prerender from react-dom/static.edge. `postponed` is React's
@@ -129,6 +131,22 @@ export interface SSRDependencies<TEnv = unknown> {
      * state on upgrade (the generated entry always passes an explicit value).
      */
     headScripts?: HeadScriptsOption;
+    /**
+     * Fizz `progressiveChunkSize`, forwarded verbatim to renderToReadableStream
+     * (live SSR) and prerender (shell capture); resume() inherits the capture
+     * value from the postponed state. The generated virtual SSR entry threads
+     * the `rango({ progressiveChunkSize })` plugin option here (canonical docs
+     * on `RangoBaseOptions.progressiveChunkSize` in vite/plugin-types.ts).
+     *
+     * When UNSET, createSSRHandler auto-raises to Number.MAX_SAFE_INTEGER for
+     * document renders whose matched chain has a `loader(Def, { ssr: false })`
+     * entry (payload segments carry `awaitBeforeFlush`): the loader was awaited
+     * before first flush precisely so its content ships in-place, and React
+     * 19.2's Fizz would otherwise move any completed boundary over ~500 bytes
+     * to an end-of-stream `<div hidden>` + $RC reveal once the shell saturates
+     * the default 12800 budget. An explicit value disables the auto-raise.
+     */
+    progressiveChunkSize?: number;
     /**
      * prerender from react-dom/static.edge. Optional; required only by
      * {@link createShellCaptureHandler} for PPR shell capture.

package/dist/types/ssr/ssr-root.d.ts

@@ -26,6 +26,15 @@ export interface RscPayload {
         version?: string;
     };
 }
+/**
+ * Deserialize the Flight stream branch into the payload SsrRoot renders,
+ * fragment expansion included. Factored out of SsrRoot so createSSRHandler can
+ * create the promise BEFORE fizz starts and read metadata that must influence
+ * the fizz call itself (the ssr:false progressiveChunkSize auto-raise) —
+ * awaiting it there is latency-neutral because fizz cannot emit even <html>
+ * until this same promise settles.
+ */
+export declare function deserializeSsrPayload(createFromReadableStream: CreateFromReadableStream, rscStream: ReadableStream<Uint8Array>): Promise<RscPayload>;
 /**
  * Options for {@link createSsrRootComponent}.
  */
@@ -34,6 +43,13 @@ export interface SsrRootOptions {
     createFromReadableStream: CreateFromReadableStream;
     /** The Flight stream branch to deserialize into the SSR VDOM. */
     rscStream: ReadableStream<Uint8Array>;
+    /**
+     * Pre-created payload promise (deserializeSsrPayload over the SAME
+     * rscStream). When present SsrRoot adopts it instead of deserializing
+     * lazily on first render — the stream can only be consumed once, so the
+     * caller that already started deserialization MUST pass the promise in.
+     */
+    payload?: Promise<RscPayload>;
     /** Nonce for CSP; propagated to NonceContext. */
     nonce?: string;
     /**

package/dist/types/ssr-suspension-warning.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Dev-only diagnostic for the { ssr: false } SSR-completeness opt-in.
+ *
+ * A document render that awaits flagged loaders before first flush is usually
+ * expected to produce an SSR-complete boundary — but the await is scoped per
+ * LOADER (see LoaderOptions in types/loader-types.ts), so one unflagged read
+ * under the same Suspense boundary still suspends it and the boundary streams
+ * as its fallback, invisible without JS. That failure mode looks exactly like
+ * the flag not working; a consumer app burned hours on byte-level archaeology
+ * before the unflagged sibling read was identified. This warning names the
+ * culprit at the suspension site instead.
+ *
+ * Fires at most once per loader id per process, only during the SSR pass
+ * (`window` undefined), only in dev, and only when the render actually awaited
+ * flagged loaders (`awaitedLoaderIds`, stamped by segment resolution on
+ * document AND shell-capture renders — capture awaits the same flagged lane;
+ * its masked live-lane reads suspend by design and dedupe against the live
+ * render's warnings through the once-per-id set).
+ */
+export declare function warnAwaitedSsrSuspension(loaderId: string, awaitedLoaderIds: readonly string[] | undefined, stream: Promise<unknown>, isServer?: boolean): void;

package/dist/types/types/loader-types.d.ts

@@ -170,7 +170,11 @@ export type LoaderFn<T, TParams = Record<string, string | undefined>, TEnv = Def
  *
  * Scoped per LOADER, not per segment: an `ssr: false` loader alongside a
  * deliberately streaming sibling awaits only itself, and the sibling keeps
- * streaming behind its `loading()`/Suspense boundary.
+ * streaming behind its `loading()`/Suspense boundary. Watch the scoping when
+ * the boundary must be SSR-complete: ONE unflagged read under it still
+ * suspends the whole boundary, which then streams as its fallback — looking
+ * exactly like the flag not working. In dev the router warns at the read
+ * site naming the unflagged loader (ssr-suspension-warning.ts).
  */
 export type LoaderOptions = {
     ssr?: boolean;

package/dist/types/types/segments.d.ts

@@ -140,9 +140,26 @@ export interface ResolvedSegment {
     loaderId?: string;
     _inherited?: boolean;
     loaderData?: any;
+    /**
+     * True when this loader was awaited before first flush
+     * (loader(Def, { ssr: false })). Stamped by resolveLoaders (fresh.ts) on
+     * document AND shell-capture renders — capture bakes flagged loaders and
+     * awaits the same lane. Feeds segment-system's settled-value delivery and
+     * the dev SSR suspension warning (ssr-suspension-warning.ts).
+     */
+    awaitBeforeFlush?: true;
     parallelLoading?: ReactNode;
     loaderDataPromise?: Promise<any[]> | any[];
     loaderIds?: string[];
+    /**
+     * Per-loader UNDECODED results for a layout/route stream map.
+     * Flagged (ssr:false) entries are settled values; unflagged siblings
+     * stay promises. Parallel slots do not use this channel — they pin
+     * loading() / live-lane holes via use(loaderDataPromise).
+     */
+    loaderStreams?: Record<string, unknown>;
+    /** $$ids of loaders this segment awaited before flush. Dev diagnostic. */
+    awaitedLoaderIds?: string[];
     error?: ErrorInfo;
     notFoundInfo?: NotFoundInfo;
     mountPath?: string;

package/dist/types/vite/discovery/state.d.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 {
     staticPrefix: string;

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

@@ -135,6 +135,33 @@ interface RangoBaseOptions {
      * @default "preinit"
      */
     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/dist/types/vite/plugins/virtual-entries.d.ts

@@ -6,7 +6,7 @@ export declare const VIRTUAL_ENTRY_BROWSER: string;
  * lets the SSR handlers convert the bootstrap to `bootstrapModules`;
  * "preload" omits the hook and pins the handlers to the hint-only strategy.
  */
-export declare function getVirtualEntrySSR(headScripts?: HeadScriptsOption): string;
+export declare function getVirtualEntrySSR(headScripts?: HeadScriptsOption, progressiveChunkSize?: number): string;
 /**
  * Virtual modules an RSC entry must import at startup to register the data the
  * request handler needs before the first request arrives:

package/dist/types/vite/utils/shared-utils.d.ts

@@ -45,6 +45,7 @@ export declare function createVirtualEntriesPlugin(entries: {
     kind?: "router" | "host";
 }, options?: {
     headScripts?: HeadScriptsOption;
+    progressiveChunkSize?: number;
 }): Plugin;
 /**
  * Suppress known harmless warnings: "use client" directives, sourcemap errors,

package/dist/vite/index.js

@@ -3476,7 +3476,18 @@ async function initializeApp() {
 
 initializeApp().catch(console.error);
 `.trim();
-function getVirtualEntrySSR(headScripts = "preinit") {
+function emitProgressiveChunkSize(value) {
+  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);
+}
+function getVirtualEntrySSR(headScripts = "preinit", progressiveChunkSize) {
   const preinit = headScripts !== "preload";
   const depsImportNames = preinit ? "createFromReadableStream,\n  setOnClientReference," : "createFromReadableStream,";
   const ssrImportNames = preinit ? "\n  installClientReferencePreinit," : "";
@@ -3487,6 +3498,8 @@ function getVirtualEntrySSR(headScripts = "preinit") {
 installClientReferencePreinit(setOnClientReference);
 ` : "";
   const hs = JSON.stringify(headScripts);
+  const pcs = progressiveChunkSize !== void 0 ? `
+  progressiveChunkSize: ${emitProgressiveChunkSize(progressiveChunkSize)},` : "";
   return `
 import {
   ${depsImportNames}
@@ -3504,7 +3517,7 @@ export const renderHTML = createSSRHandler({
   createFromReadableStream,
   renderToReadableStream,
   injectRSCPayload,
-  headScripts: ${hs},
+  headScripts: ${hs},${pcs}
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
@@ -3515,7 +3528,7 @@ export const captureShellHTML = createShellCaptureHandler({
   injectRSCPayload,
   prerender,
   resume,
-  headScripts: ${hs},
+  headScripts: ${hs},${pcs}
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
@@ -3526,7 +3539,7 @@ export const resumeShellHTML = createShellResumeHandler({
   injectRSCPayload,
   prerender,
   resume,
-  headScripts: ${hs},
+  headScripts: ${hs},${pcs}
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
@@ -3685,7 +3698,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.9.0",
+  version: "0.10.1",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -3694,15 +3707,15 @@ var package_default = {
     "rsc",
     "vite"
   ],
-  homepage: "https://github.com/ivogt/vite-rsc#readme",
+  homepage: "https://github.com/rangojs/rango#readme",
   bugs: {
-    url: "https://github.com/ivogt/vite-rsc/issues"
+    url: "https://github.com/rangojs/rango/issues"
   },
   license: "MIT",
   author: "Ivo Todorov",
   repository: {
     type: "git",
-    url: "git+https://github.com/ivogt/vite-rsc.git",
+    url: "git+https://github.com/rangojs/rango.git",
     directory: "packages/rangojs-router"
   },
   bin: {
@@ -3717,7 +3730,8 @@ var package_default = {
     "dist",
     "skills",
     "AGENTS.md",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   type: "module",
   exports: {
@@ -5466,7 +5480,10 @@ function createVirtualEntriesPlugin(entries, routerPathRef, options) {
     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
+    );
   }
   const knownIds = new Set(Object.keys(virtualModules));
   if (entries.rsc === VIRTUAL_IDS.rsc) {
@@ -9540,6 +9557,11 @@ async function runShellPrerenderPhase(s, builder) {
       prerender: reactDomStatic.prerender ?? reactDomStatic.default?.prerender,
       injectRSCPayload: htmlStream.injectRSCPayload,
       headScripts: "preinit",
+      // Build-captured shells must honor the explicit outlining budget: the
+      // capture value rides the postponed state into every runtime resume().
+      ...s.opts?.progressiveChunkSize !== void 0 && {
+        progressiveChunkSize: s.opts.progressiveChunkSize
+      },
       loadBootstrapScriptContent: async () => bootstrapContent
     });
     const rscRunner = rscEnv.runner;
@@ -10366,7 +10388,10 @@ async function createTempRscServer(state, options = {}) {
             return id === "virtual:entry-ssr" ? "\0rango-temp-real-ssr-entry" : null;
           },
           load(id) {
-            return id === "\0rango-temp-real-ssr-entry" ? getVirtualEntrySSR(state.opts?.headScripts) : null;
+            return id === "\0rango-temp-real-ssr-entry" ? getVirtualEntrySSR(
+              state.opts?.headScripts,
+              state.opts?.progressiveChunkSize
+            ) : null;
           }
         }
       ] : [],
@@ -11305,6 +11330,8 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
           if (expectedEpoch === void 0) return;
           void (async () => {
             const deadline = Date.now() + 15e3;
+            let reloadBackoffMs = 100;
+            let nextReloadAt = Date.now() + reloadBackoffMs;
             do {
               if (devServerClosed || expectedEpoch !== s.devDiscoveryEpoch) {
                 return;
@@ -11325,7 +11352,14 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
                   publishDevDiscoveryReady(expectedEpoch);
                   return;
                 }
-                reloadWorkerd();
+                await response.body?.cancel().catch(() => {
+                });
+                const now = Date.now();
+                if (now >= nextReloadAt) {
+                  reloadWorkerd();
+                  reloadBackoffMs = Math.min(reloadBackoffMs * 2, 1e3);
+                  nextReloadAt = now + reloadBackoffMs;
+                }
               } catch {
               }
             } while (Date.now() < deadline);
@@ -11456,17 +11490,10 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
                 hasClientUrls
               );
             }
-            if (isUseClient && hasClientUrls) {
-              const rscGraph = server.environments?.rsc?.moduleGraph;
+            const mainRscEnv = server.environments?.rsc;
+            if (isUseClient && hasClientUrls && mainRscEnv?.runner) {
+              const rscGraph = mainRscEnv.moduleGraph;
               if (rscGraph?.getModulesByFile) {
-                const invalidateWithImporters = (mod, seen2) => {
-                  if (!mod || seen2.has(mod)) return;
-                  seen2.add(mod);
-                  rscGraph.invalidateModule(mod);
-                  for (const importer of mod.importers ?? []) {
-                    invalidateWithImporters(importer, seen2);
-                  }
-                };
                 const routerSourceFiles = /* @__PURE__ */ new Set();
                 if (s.resolvedEntryPath) {
                   routerSourceFiles.add(resolve12(s.resolvedEntryPath));
@@ -11489,7 +11516,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
                     continue;
                   }
                   for (const mod of mods) {
-                    invalidateWithImporters(mod, seen);
+                    rscGraph.invalidateModule(mod, seen);
                   }
                 }
                 debugDiscovery?.(
@@ -11953,7 +11980,8 @@ async function rango(options) {
     });
     plugins.push(
       createVirtualEntriesPlugin(finalEntries, void 0, {
-        headScripts: resolvedOptions.headScripts
+        headScripts: resolvedOptions.headScripts,
+        progressiveChunkSize: resolvedOptions.progressiveChunkSize
       })
     );
     plugins.push(performanceTracksPlugin());
@@ -12146,7 +12174,8 @@ If this is a multi-app host router, export a createHostRouter() instance and set
     });
     plugins.push(
       createVirtualEntriesPlugin(finalEntries, routerRef, {
-        headScripts: resolvedOptions.headScripts
+        headScripts: resolvedOptions.headScripts,
+        progressiveChunkSize: resolvedOptions.progressiveChunkSize
       })
     );
     plugins.push(performanceTracksPlugin());
@@ -12199,7 +12228,8 @@ If this is a multi-app host router, export a createHostRouter() instance and set
       prerenderOnError: options?.prerender?.onError,
       discovery: options?.discovery,
       clientChunkCtx,
-      headScripts: resolvedOptions.headScripts
+      headScripts: resolvedOptions.headScripts,
+      progressiveChunkSize: resolvedOptions.progressiveChunkSize
     })
   );
   if (preset === "vercel") {