@rangojs/router 0.9.0 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -9,15 +9,15 @@
     "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": {
@@ -32,7 +32,8 @@
     "dist",
     "skills",
     "AGENTS.md",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "type": "module",
   "exports": {
@@ -176,20 +177,6 @@
     "access": "public",
     "tag": "latest"
   },
-  "scripts": {
-    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
-    "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
-    "prepublishOnly": "pnpm build",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
-    "test": "playwright test",
-    "test:preload": "playwright test --config=playwright.preload.config.ts",
-    "test:ui": "playwright test --ui",
-    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-basename --project=hmr-prerender --no-deps --workers=1 && RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
-    "test:hmr-routes-local": "RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
-    "test:unit": "pnpm run build:types && vitest run",
-    "test:unit:watch": "vitest",
-    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
-  },
   "dependencies": {
     "@types/debug": "^4.1.12",
     "@vitejs/plugin-rsc": "^0.5.31",
@@ -206,18 +193,18 @@
     "@opentelemetry/context-async-hooks": "^2.9.0",
     "@opentelemetry/sdk-trace-base": "^2.9.0",
     "@playwright/test": "^1.49.1",
-    "@shared/e2e": "workspace:*",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^24.10.1",
-    "@types/react": "catalog:",
-    "@types/react-dom": "catalog:",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
     "esbuild": "^0.28.1",
     "happy-dom": "^20.10.1",
     "jiti": "^2.7.0",
-    "react": "catalog:",
-    "react-dom": "catalog:",
-    "vitest": "^4.1.9"
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "vitest": "^4.1.9",
+    "@shared/e2e": "0.0.1"
   },
   "peerDependencies": {
     "@cloudflare/vite-plugin": "^1.42.1",
@@ -256,5 +243,18 @@
   },
   "engines": {
     "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
+    "test": "playwright test",
+    "test:preload": "playwright test --config=playwright.preload.config.ts",
+    "test:ui": "playwright test --ui",
+    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-basename --project=hmr-prerender --no-deps --workers=1 && RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
+    "test:hmr-routes-local": "RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
+    "test:unit": "pnpm run build:types && vitest run",
+    "test:unit:watch": "vitest",
+    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
   }
-}
+}

package/skills/bundle-analysis/SKILL.md

@@ -150,7 +150,7 @@ The treemap shows nested boxes; box area = uncompressed size. Hover for gzip/bro
 
 ## Reporting Rango regressions
 
-If a finding looks like a `@rangojs/router` regression (the framework is shipping more than it should, not your app), open an issue at the [@rangojs/router GitHub](https://github.com/ivogt/vite-rsc/issues) and include:
+If a finding looks like a `@rangojs/router` regression (the framework is shipping more than it should, not your app), open an issue at the [@rangojs/router GitHub](https://github.com/rangojs/rango/issues) and include:
 
 - The output of `client.html` / `rsc.html` (screenshots or the JSON `data = {...}` block from the HTML).
 - The `@rangojs/router` version (`pnpm why @rangojs/router`).

package/skills/loader/SKILL.md

@@ -757,6 +757,18 @@ Response construction (real 404, no warm-up race). Client navigations stream
 exactly as before. Scoped per LOADER: the flagged loader awaits only itself;
 siblings keep streaming.
 
+Delivery is in-place, not merely in-document. React's Fizz outlines any
+COMPLETED Suspense boundary over ~500 bytes to an end-of-stream
+`<div hidden>` + `$RC()` reveal once the shell saturates its 12800-byte
+`progressiveChunkSize` budget — the bytes are in the HTML, but not at their
+document position, and a consumer that doesn't execute scripts never sees
+them revealed. When the matched chain has a flagged loader, the document
+render raises the budget to `MAX_SAFE_INTEGER` automatically, so the awaited
+content renders where it belongs. Pin the budget yourself (in either
+direction) with `rango({ progressiveChunkSize })` in the Vite config — an
+explicit value disables the auto-raise. Boundaries hoisting stylesheets
+still outline; their reveal must wait for the CSS.
+
 The costs and constraints:
 
 - Every document load pays the flagged loader's latency before first byte.
@@ -766,8 +778,11 @@ The costs and constraints:
   document render awaits the loader before the render barrier resolves, so
   that wait is a cycle by construction; it throws a deadlock error naming the
   fix.
-- PPR capture renders mask loaders and skip the await — the flag does not
-  bake anything into a shell (`/ppr`).
+- PPR capture is the BAKE lane for flagged loaders (`/ppr`): the capture
+  render awaits them too, and the settled result — handle pushes included —
+  freezes into the stored shell. Unflagged loaders stay masked as live
+  holes. The `progressiveChunkSize` auto-raise is live-document only;
+  captured shells outline per the explicit option or React's default.
 
 Also available in `clientUrls()` route groups (`/client-urls`), where the
 loader-heavy shape makes it most useful. `LoaderOptions` is exported from the

package/skills/testing/SKILL.md

@@ -32,7 +32,7 @@ index.rsc.ts` alias are all in [`./setup.md`](./setup.md). Read it before writin
 > [`./bindings.md`](./bindings.md).
 
 For the long-form prose guide (setup walkthrough + migration), see
-[`docs/testing.md`](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md)
+[`docs/testing.md`](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md)
 (the `docs/` directory is not shipped in the published package, so this is an
 absolute link).
 

package/skills/testing/bindings.md

@@ -100,4 +100,4 @@ describe("bindings seam", () => {
 
 - (cross-cutting)
 - Siblings: `./loader.md`, `./middleware.md`, `./server-actions.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "What these primitives deliberately don't cover (the platform-bindings paragraph)"
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "What these primitives deliberately don't cover (the platform-bindings paragraph)"

package/skills/testing/cache-prerender.md

@@ -169,4 +169,4 @@ expect(await store.getShell(key)).not.toBeNull();
 
 - `/caching`, `/prerender`, `/use-cache`, `/ppr` — the DSL this tests
 - Siblings: [`./e2e-parity.md`](./e2e-parity.md), [`./response-routes.md`](./response-routes.md)
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Cache, SWR, and prerender"
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "Cache, SWR, and prerender"

package/skills/testing/client-components.md

@@ -128,4 +128,4 @@ it("resolves params + reverse + Outlet through the layout chain", async () => {
 
 - `/hooks` — the DSL this tests
 - Siblings: `./handles.md`, `./reverse-and-types.md`, `./render-handler.md`, `./e2e-parity.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Reverse and components" (and the "Catch: streaming `use(promise)` Suspense content" subsection)
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "Reverse and components" (and the "Catch: streaming `use(promise)` Suspense content" subsection)

package/skills/testing/e2e-parity.md

@@ -122,4 +122,4 @@ A `submit` intent does NOT replay against a snapshot of the server — it submit
 
 - `/hooks`, `/view-transitions` — the DSL this tests
 - Siblings: [`./cache-prerender.md`](./cache-prerender.md), [`./client-components.md`](./client-components.md)
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "E2E with dev/prod and PE parity" (and "Running a subset locally")
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "E2E with dev/prod and PE parity" (and "Running a subset locally")

package/skills/testing/flight.md

@@ -88,4 +88,4 @@ it("snapshots the normalized payload", async () => {
 
 - `/route` — the DSL this tests
 - Siblings: `./setup.md`, `./server-tree.md`, `./render-handler.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "renderToFlightString — real async Server Components"
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "renderToFlightString — real async Server Components"

package/skills/testing/handles.md

@@ -150,4 +150,4 @@ it("renders the seeded trail (seed the INPUT pushes, the collect runs)", async (
 
 - `/handler-use`, `/breadcrumbs` — the DSL this tests
 - Siblings: `./loader.md`, `./client-components.md`, `./render-handler.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Testing a handle's collect/accumulator"
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "Testing a handle's collect/accumulator"

package/skills/testing/loader.md

@@ -127,4 +127,4 @@ it("asserts a loader's set-cookie + redirect (runLoaderResult)", async () => {
 
 - `/loader` — the DSL this tests
 - Siblings: `./handles.md`, `./reverse-and-types.md`, `./bindings.md`, `./server-actions.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Loaders — the raw body or a registered createLoader"
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "Loaders — the raw body or a registered createLoader"

package/skills/testing/middleware.md

@@ -96,4 +96,4 @@ Pass an array to run several in order. Cookies set inside middleware via the sta
 
 - `/middleware` — the DSL this tests
 - Siblings: `./response-routes.md`, `./server-actions.md`, `./loader.md`, `./bindings.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Middleware"
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "Middleware"

package/skills/testing/render-handler.md

@@ -119,4 +119,4 @@ it("asserts the client-cache directives", async () => {
 
 - `/route` — the DSL this tests
 - Siblings: [`./server-tree.md`](./server-tree.md), [`./server-actions.md`](./server-actions.md), [`./setup.md`](./setup.md), [`./loader.md`](./loader.md)
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "renderHandler — run a real route handler and assert its RSC"
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "renderHandler — run a real route handler and assert its RSC"

package/skills/testing/response-routes.md

@@ -92,4 +92,4 @@ describe("api routes via dispatch", () => {
 
 - `/response-routes`, `/mime-routes` — the DSL this tests
 - Siblings: `./middleware.md`, `./setup.md`, `./cache-prerender.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "dispatch — request to Response" (the `rangoTestConfig` preset stubs `@vitejs/plugin-rsc/rsc`, so no per-file `vi.mock` is needed)
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "dispatch — request to Response" (the `rangoTestConfig` preset stubs `@vitejs/plugin-rsc/rsc`, so no per-file `vi.mock` is needed)

package/skills/testing/reverse-and-types.md

@@ -82,4 +82,4 @@ For a large type-only suite, collect recipe-1/2 assertions in `*.test-d.ts` file
 
 - `/typesafety`, `/links` — the DSL this tests
 - Siblings: `./client-components.md`, `./loader.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Type-level tests — make misuse fail to compile"
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "Type-level tests — make misuse fail to compile"

package/skills/testing/server-actions.md

@@ -104,4 +104,4 @@ it("asserts the client-cache directives an action issued", async () => {
 
 - `/server-actions` — the DSL this tests
 - Siblings: `./render-handler.md`, `./middleware.md`, `./loader.md`, `./bindings.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "runInRequestContext — the handler / server-action test primitive"
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "runInRequestContext — the handler / server-action test primitive"

package/skills/testing/server-tree.md

@@ -125,4 +125,4 @@ it("asserts the server-rendered host content", async () => {
 
 - `/route` — the DSL this tests
 - Siblings: `./flight.md`, `./render-handler.md`, `./setup.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "renderServerTree — serialize then deserialize to an inspectable tree" (and the "findElements / textContent" subsection)
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "renderServerTree — serialize then deserialize to an inspectable tree" (and the "findElements / textContent" subsection)

package/skills/testing/setup.md

@@ -120,4 +120,4 @@ Scripts:
 
 - (cross-cutting)
 - Siblings: `./flight.md`, `./server-tree.md`, `./render-handler.md`, `./response-routes.md`
-- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Setup" (and the subsections "Resolving @rangojs/router in a unit test — use the preset" and "Two vitest projects")
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "Setup" (and the subsections "Resolving @rangojs/router in a unit test — use the preset" and "Two vitest projects")

package/src/browser/merge-segment-loaders.ts

@@ -45,6 +45,10 @@ export function mergeSegmentLoaders(
     }),
     // Keep all loader IDs from cache
     loaderIds: fromCache.loaderIds,
+    // The rebuilt aggregate is the source of truth. Cached per-loader
+    // streams would make LoaderResolver ignore loaderDataPromise.
+    loaderStreams: undefined,
+    awaitedLoaderIds: undefined,
   };
 }
 

package/src/cache/cache-runtime.ts

@@ -207,8 +207,8 @@ interface CacheEnvelope {
  * leader (function threw, or the result was not serializable) propagates to
  * current waiters, which then retry fresh.
  *
- * A leader that NEVER settles must not hang followers (scar tissue, autobarn
- * pilot outage): a background shell capture's render became leader, awaited a
+ * A leader that NEVER settles must not hang followers (scar tissue, production
+ * pilot incident): a background shell capture's render became leader, awaited a
  * tarpitting upstream fetch, and workerd killed the capture's waitUntil context
  * — orphaning the leader promise as permanently pending, its map entry never
  * cleared. Every later document render calling the same cached function (an

package/src/cache/cf/cf-cache-constants.ts

@@ -86,7 +86,7 @@ export 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/src/cache/cf/cf-cache-store.ts

@@ -2383,7 +2383,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * 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/src/client.tsx

@@ -49,6 +49,8 @@ function renderSlotContent(segment: ResolvedSegment | null): ReactNode {
     <LoaderBoundary
       loaderDataPromise={segment.loaderDataPromise!}
       loaderIds={segment.loaderIds!}
+      loaderStreams={segment.loaderStreams}
+      awaitedLoaderIds={segment.awaitedLoaderIds}
       fallback={segment.loading}
       outletKey={segment.id + "-loader"}
       outletContent={null}

package/src/outlet-context.ts

@@ -18,6 +18,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/src/outlet-provider.tsx

@@ -13,6 +13,7 @@ export function OutletProvider({
   segment,
   loaderData,
   loaderStreams,
+  awaitedLoaderIds,
   pending = false,
   children,
 }: {
@@ -21,6 +22,7 @@ export function OutletProvider({
   segment?: ResolvedSegment;
   loaderData?: Record<string, any>;
   loaderStreams?: Record<string, unknown>;
+  awaitedLoaderIds?: readonly string[];
   pending?: boolean;
   children: ReactNode;
 }): ReactNode {
@@ -34,6 +36,7 @@ export function OutletProvider({
       segment,
       loaderData,
       loaderStreams,
+      awaitedLoaderIds,
       pending,
       parent: parentContext,
       loading: segment?.loading,
@@ -44,6 +47,7 @@ export function OutletProvider({
       segment,
       loaderData,
       loaderStreams,
+      awaitedLoaderIds,
       pending,
       parentContext,
     ],

package/src/route-content-wrapper.tsx

@@ -129,6 +129,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;
@@ -141,6 +144,7 @@ export function LoaderBoundary({
   loaderDataPromise,
   loaderIds,
   loaderStreams,
+  awaitedLoaderIds,
   fallback,
   outletKey,
   outletContent,
@@ -154,6 +158,7 @@ export function LoaderBoundary({
         loaderDataPromise={loaderDataPromise}
         loaderIds={loaderIds}
         loaderStreams={loaderStreams}
+        awaitedLoaderIds={awaitedLoaderIds}
         outletKey={outletKey}
         outletContent={outletContent}
         segment={segment}
@@ -187,6 +192,7 @@ function LoaderResolver({
   loaderDataPromise,
   loaderIds,
   loaderStreams,
+  awaitedLoaderIds,
   outletKey,
   outletContent,
   segment,
@@ -201,6 +207,7 @@ function LoaderResolver({
         segment={segment}
         parallel={parallel}
         loaderStreams={loaderStreams}
+        awaitedLoaderIds={awaitedLoaderIds}
       >
         {children}
       </OutletProvider>

package/src/router/segment-resolution/fresh.ts

@@ -11,6 +11,7 @@ import {
   getParallelEntries,
   getParallelSlotEntries,
   type EntryData,
+  type LoaderEntry,
 } from "../../server/context";
 import type {
   HandlerContext,
@@ -45,6 +46,37 @@ import {
   latchPprHeaderScopeForEntries,
 } from "../../server/context.js";
 
+/**
+ * Register flagged loader $$ids on the request context and return their
+ * indices. Must run BEFORE kickoff: rendered() checks the set to fail
+ * fast on the barrier cycle (resolution awaits the loader, the barrier
+ * awaits resolution).
+ */
+function registerAwaitBeforeFlushIds(loaderEntries: LoaderEntry[]): number[] {
+  const awaitedIndices: number[] = [];
+  for (let i = 0; i < loaderEntries.length; i++) {
+    if (loaderEntries[i]!.awaitBeforeFlush) awaitedIndices.push(i);
+  }
+  if (awaitedIndices.length > 0) {
+    const reqCtx = _getRequestContext();
+    if (reqCtx) {
+      reqCtx._awaitBeforeFlushLoaderIds ??= new Set();
+      for (const i of awaitedIndices) {
+        reqCtx._awaitBeforeFlushLoaderIds.add(loaderEntries[i]!.loader.$$id);
+      }
+    }
+  }
+  return awaitedIndices;
+}
+
+function stampAwaitBeforeFlush(
+  loaderEntry: LoaderEntry,
+): { awaitBeforeFlush: true } | Record<string, never> {
+  return loaderEntry.awaitBeforeFlush === true
+    ? { awaitBeforeFlush: true as const }
+    : {};
+}
+
 // ---------------------------------------------------------------------------
 // Fresh path (full match, no revalidation)
 // ---------------------------------------------------------------------------
@@ -112,23 +144,12 @@ export async function resolveLoaders<TEnv>(
     // the set to fail fast on the barrier cycle (segment resolution awaits the
     // loader, the barrier awaits segment resolution, rendered() awaits the
     // barrier), and the loader body can call rendered() before the await below
-    // is reached. Skipped during shell capture: LIVE-lane loaders are masked
-    // with never-resolving promises there (loader-mask.ts) and would hang.
-    const awaitedIndices: number[] = [];
-    if (!isShellCaptureActive()) {
-      for (let i = 0; i < loaderEntries.length; i++) {
-        if (loaderEntries[i]!.awaitBeforeFlush) awaitedIndices.push(i);
-      }
-    }
-    if (awaitedIndices.length > 0) {
-      const reqCtx = _getRequestContext();
-      if (reqCtx) {
-        reqCtx._awaitBeforeFlushLoaderIds ??= new Set();
-        for (const i of awaitedIndices) {
-          reqCtx._awaitBeforeFlushLoaderIds.add(loaderEntries[i]!.loader.$$id);
-        }
-      }
-    }
+    // is reached.
+    //
+    // Shell-capture renders await too: flagged loaders BAKE at capture
+    // (loader-mask masks only LIVE-lane loaders). Capture must await them so
+    // bake-lane handle pushes land in the prelude.
+    const awaitedIndices = registerAwaitBeforeFlushIds(loaderEntries);
 
     // Streaming loaders: promises kick off now, settle during RSC serialization.
     const segments = loaderEntries.map((loaderEntry, i) => {
@@ -142,6 +163,10 @@ export async function resolveLoaders<TEnv>(
         component: null,
         params: ctx.params,
         loaderId: loader.$$id,
+        // Stamped on document AND capture renders: segment-system's
+        // value-delivery await and the dev SSR-suspension diagnostic both
+        // key off it.
+        ...stampAwaitBeforeFlush(loaderEntry),
         loaderData: deps.wrapLoaderPromise(
           runInsideLoaderScope(() =>
             resolveLoaderData(
@@ -188,6 +213,11 @@ export async function resolveLoaders<TEnv>(
   // collapsing the whole entry and discarding successful sibling data, and
   // (2) leave the other in-flight raw promises without a .catch, producing
   // unhandled rejections. Mirrors the loading path and intercept-resolution.
+  //
+  // Flagged loaders still get awaitBeforeFlush stamped: auto-raise and
+  // settled-value delivery key off the field, and this path already paid
+  // the pre-flush await.
+  registerAwaitBeforeFlushIds(loaderEntries);
   const pendingLoaderData = loaderEntries.map((loaderEntry, i) => {
     const { loader } = loaderEntry;
     const segmentId = `${shortCode}D${i}.${loader.$$id}`;
@@ -224,6 +254,7 @@ export async function resolveLoaders<TEnv>(
       component: null,
       params: ctx.params,
       loaderId: loader.$$id,
+      ...stampAwaitBeforeFlush(loaderEntry),
       loaderData: pending.wrapped,
       belongsToRoute,
     };

package/src/router.ts

@@ -1167,11 +1167,16 @@ export function createRouter<TEnv = any>(
         | null = null;
 
       return async (request: Request, input: RouterRequestInput<TEnv> = {}) => {
+        const requestedDiscoveryEpoch = request.headers.get(
+          DEV_DISCOVERY_PROBE_HEADER,
+        );
         if (
           devDiscoveryEpoch !== undefined &&
-          request.headers.get(DEV_DISCOVERY_PROBE_HEADER) ===
-            String(devDiscoveryEpoch)
+          requestedDiscoveryEpoch !== null
         ) {
+          // A stale generation must still answer as a probe. Rendering the app
+          // on an epoch mismatch makes the readiness loop overlap full renders
+          // with workerd reloads and can exhaust the dev server heap.
           return new Response(null, {
             headers: {
               [DEV_DISCOVERY_EPOCH_HEADER]: String(devDiscoveryEpoch),

package/src/rsc/handler.ts

@@ -45,7 +45,7 @@ import {
   handleResponseRoute,
   type ResponseRouteMatch,
 } from "./response-route-handler.js";
-import { generateNonce, nonce as nonceToken } from "./nonce.js";
+import { nonce as nonceToken, resolveProviderNonce } from "./nonce.js";
 import { VERSION } from "@rangojs/router:version";
 import type { ErrorPhase } from "../types.js";
 import type { RouterRequestInput } from "../router/router-interfaces.js";
@@ -456,12 +456,12 @@ export function createRSCHandler<
       }
     }
 
-    // Resolve nonce if provider is set
+    // Resolve nonce if provider is set. false/"" normalize to undefined —
+    // the per-request opt-out (resolveProviderNonce).
     const nonceStart = performance.now();
     let nonce: string | undefined;
     if (nonceProvider) {
-      const result = await nonceProvider(request, env);
-      nonce = result === true ? generateNonce() : result;
+      nonce = resolveProviderNonce(await nonceProvider(request, env));
     }
     const nonceDur = performance.now() - nonceStart;
 

package/src/rsc/nonce.ts

@@ -25,6 +25,22 @@ import { createVar } from "../context-var.js";
  */
 export const nonce: ContextVar<string> = createVar<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 function resolveProviderNonce(
+  result: string | boolean,
+): string | undefined {
+  if (result === true) return generateNonce();
+  return result === false || result === "" ? undefined : result;
+}
+
 /**
  * Generate a cryptographic nonce for CSP.
  * Returns a 16-byte random value encoded as base64.

package/src/rsc/shell-capture-constants.ts

@@ -30,7 +30,7 @@ export const SHELL_CAPTURE_MAX_WAIT_MS = 15_000;
  * 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.