@rangojs/router 0.0.0-experimental.tapabs2 → 0.1.0

package/dist/vite/index.js

@@ -1,6 +1,201 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/vite/debug.ts
+import debugFactory from "debug";
+function createRangoDebugger(namespace) {
+  const primary = debugFactory(namespace);
+  const shadow = debugFactory(`vite:${namespace}`);
+  if (primary.enabled) return primary;
+  if (shadow.enabled) return shadow;
+  return void 0;
+}
+async function timed(debug12, label, fn) {
+  if (!debug12) return await fn();
+  const start = performance.now();
+  try {
+    return await fn();
+  } finally {
+    debug12("%s (%sms)", label, (performance.now() - start).toFixed(1));
+  }
+}
+function timedSync(debug12, label, fn) {
+  if (!debug12) return fn();
+  const start = performance.now();
+  try {
+    return fn();
+  } finally {
+    debug12("%s (%sms)", label, (performance.now() - start).toFixed(1));
+  }
+}
+function createCounter(debug12, label) {
+  if (!debug12) return void 0;
+  let n = 0;
+  let totalMs = 0;
+  let slowestMs = 0;
+  let slowestFile = "";
+  const record = (file, ms) => {
+    n++;
+    totalMs += ms;
+    if (ms > slowestMs) {
+      slowestMs = ms;
+      slowestFile = file;
+    }
+  };
+  return {
+    record,
+    time(file, fn) {
+      const start = performance.now();
+      let out;
+      try {
+        out = fn();
+      } catch (err) {
+        record(file, performance.now() - start);
+        throw err;
+      }
+      if (out && typeof out.then === "function") {
+        return out.finally(
+          () => record(file, performance.now() - start)
+        );
+      }
+      record(file, performance.now() - start);
+      return out;
+    },
+    flush() {
+      if (n === 0) return;
+      debug12(
+        "%s: %d files, %sms total, slowest %sms %s",
+        label,
+        n,
+        totalMs.toFixed(1),
+        slowestMs.toFixed(1),
+        slowestFile
+      );
+      n = 0;
+      totalMs = 0;
+      slowestMs = 0;
+      slowestFile = "";
+    }
+  };
+}
+var NS;
+var init_debug = __esm({
+  "src/vite/debug.ts"() {
+    "use strict";
+    NS = {
+      config: "rango:config",
+      discovery: "rango:discovery",
+      routes: "rango:routes",
+      prerender: "rango:prerender",
+      build: "rango:build",
+      dev: "rango:dev",
+      transform: "rango:transform",
+      chunks: "rango:chunks"
+    };
+    if (process.env.INTERNAL_RANGO_DEBUG) {
+      const existing = debugFactory.disable();
+      debugFactory.enable(existing ? `${existing},rango:*` : "rango:*");
+    }
+  }
+});
+
+// src/vite/plugins/client-ref-hashing.ts
+var client_ref_hashing_exports = {};
+__export(client_ref_hashing_exports, {
+  computeProductionHash: () => computeProductionHash,
+  hashClientRefs: () => hashClientRefs,
+  hashRefKey: () => hashRefKey,
+  transformClientRefs: () => transformClientRefs
+});
+import { relative as relative2 } from "node:path";
+import { createHash as createHash2 } from "node:crypto";
+function hashRefKey(relativeId) {
+  return createHash2("sha256").update(relativeId).digest("hex").slice(0, 12);
+}
+function computeProductionHash(projectRoot, refKey) {
+  let toHash;
+  if (refKey.startsWith(CLIENT_PKG_PROXY_PREFIX)) {
+    toHash = refKey.slice(CLIENT_PKG_PROXY_PREFIX.length);
+  } else if (refKey.startsWith(CLIENT_IN_SERVER_PKG_PROXY_PREFIX)) {
+    const absPath = decodeURIComponent(
+      refKey.slice(CLIENT_IN_SERVER_PKG_PROXY_PREFIX.length)
+    );
+    toHash = relative2(projectRoot, absPath).replaceAll("\\", "/");
+  } else if (refKey.startsWith(FS_PREFIX)) {
+    const absPath = refKey.slice(FS_PREFIX.length - 1);
+    toHash = relative2(projectRoot, absPath).replaceAll("\\", "/");
+  } else if (refKey.startsWith("/")) {
+    toHash = refKey.slice(1);
+  } else {
+    return refKey;
+  }
+  return hashRefKey(toHash);
+}
+function transformClientRefs(code, projectRoot) {
+  if (!code.includes("registerClientReference")) return null;
+  let hasReplacement = false;
+  const result = code.replace(
+    REGISTER_CLIENT_REF_RE,
+    (match, refKey) => {
+      const hash = computeProductionHash(projectRoot, refKey);
+      if (hash === refKey) return match;
+      hasReplacement = true;
+      return match.replace(`"${refKey}"`, `"${hash}"`);
+    }
+  );
+  return hasReplacement ? result : null;
+}
+function hashClientRefs(projectRoot) {
+  const counter = createCounter(debug7, "hash-client-refs");
+  return {
+    name: "@rangojs/router:hash-client-refs",
+    enforce: "post",
+    applyToEnvironment(env) {
+      return env.name === "rsc";
+    },
+    buildEnd() {
+      counter?.flush();
+    },
+    transform(code, id) {
+      const start = counter ? performance.now() : 0;
+      try {
+        const result = transformClientRefs(code, projectRoot);
+        if (result === null) return;
+        return { code: result, map: null };
+      } finally {
+        counter?.record(id, performance.now() - start);
+      }
+    }
+  };
+}
+var debug7, CLIENT_PKG_PROXY_PREFIX, CLIENT_IN_SERVER_PKG_PROXY_PREFIX, FS_PREFIX, REGISTER_CLIENT_REF_RE;
+var init_client_ref_hashing = __esm({
+  "src/vite/plugins/client-ref-hashing.ts"() {
+    "use strict";
+    init_debug();
+    debug7 = createRangoDebugger(NS.transform);
+    CLIENT_PKG_PROXY_PREFIX = "/@id/__x00__virtual:vite-rsc/client-package-proxy/";
+    CLIENT_IN_SERVER_PKG_PROXY_PREFIX = "/@id/__x00__virtual:vite-rsc/client-in-server-package-proxy/";
+    FS_PREFIX = "/@fs/";
+    REGISTER_CLIENT_REF_RE = /registerClientReference\(\s*(?:(?:\([^)]*\))|(?:\(\)[\s\S]*?\}))\s*,\s*"([^"]+)"\s*,\s*"[^"]+"\s*\)/g;
+  }
+});
+
 // src/vite/rango.ts
-import { readFileSync as readFileSync7, existsSync as existsSync8 } from "node:fs";
-import { resolve as resolve11 } from "node:path";
+import { readFileSync as readFileSync8, existsSync as existsSync9 } from "node:fs";
+import { resolve as resolve12 } from "node:path";
 
 // src/vite/plugins/expose-action-id.ts
 import MagicString from "magic-string";
@@ -251,99 +446,8 @@ function findCallParenAfterGenerics(code, afterCalleeIndex) {
   return -1;
 }
 
-// src/vite/debug.ts
-import debugFactory from "debug";
-var NS = {
-  config: "rango:config",
-  discovery: "rango:discovery",
-  routes: "rango:routes",
-  prerender: "rango:prerender",
-  build: "rango:build",
-  dev: "rango:dev",
-  transform: "rango:transform",
-  chunks: "rango:chunks"
-};
-if (process.env.INTERNAL_RANGO_DEBUG) {
-  const existing = debugFactory.disable();
-  debugFactory.enable(existing ? `${existing},rango:*` : "rango:*");
-}
-function createRangoDebugger(namespace) {
-  const primary = debugFactory(namespace);
-  const shadow = debugFactory(`vite:${namespace}`);
-  if (primary.enabled) return primary;
-  if (shadow.enabled) return shadow;
-  return void 0;
-}
-async function timed(debug11, label, fn) {
-  if (!debug11) return await fn();
-  const start = performance.now();
-  try {
-    return await fn();
-  } finally {
-    debug11("%s (%sms)", label, (performance.now() - start).toFixed(1));
-  }
-}
-function timedSync(debug11, label, fn) {
-  if (!debug11) return fn();
-  const start = performance.now();
-  try {
-    return fn();
-  } finally {
-    debug11("%s (%sms)", label, (performance.now() - start).toFixed(1));
-  }
-}
-function createCounter(debug11, label) {
-  if (!debug11) return void 0;
-  let n = 0;
-  let totalMs = 0;
-  let slowestMs = 0;
-  let slowestFile = "";
-  const record = (file, ms) => {
-    n++;
-    totalMs += ms;
-    if (ms > slowestMs) {
-      slowestMs = ms;
-      slowestFile = file;
-    }
-  };
-  return {
-    record,
-    time(file, fn) {
-      const start = performance.now();
-      let out;
-      try {
-        out = fn();
-      } catch (err) {
-        record(file, performance.now() - start);
-        throw err;
-      }
-      if (out && typeof out.then === "function") {
-        return out.finally(
-          () => record(file, performance.now() - start)
-        );
-      }
-      record(file, performance.now() - start);
-      return out;
-    },
-    flush() {
-      if (n === 0) return;
-      debug11(
-        "%s: %d files, %sms total, slowest %sms %s",
-        label,
-        n,
-        totalMs.toFixed(1),
-        slowestMs.toFixed(1),
-        slowestFile
-      );
-      n = 0;
-      totalMs = 0;
-      slowestMs = 0;
-      slowestFile = "";
-    }
-  };
-}
-
 // src/vite/plugins/expose-action-id.ts
+init_debug();
 var debug = createRangoDebugger(NS.transform);
 function getRscPluginApi(config) {
   let plugin = config.plugins.find((p) => p.name === "rsc:minimal");
@@ -1299,10 +1403,14 @@ ${binding.localName}.$$id = "${handlerId}";`;
   return hasChanges;
 }
 
+// src/vite/plugins/expose-internal-ids.ts
+init_debug();
+
 // src/vite/plugins/expose-ids/router-transform.ts
 import MagicString2 from "magic-string";
 import path3 from "node:path";
 import { createHash } from "node:crypto";
+init_debug();
 var debug2 = createRangoDebugger(NS.transform);
 function skipLeadingTrivia(code, start, end) {
   let i = start;
@@ -1922,6 +2030,7 @@ ${lazyImports.join(",\n")}
 // src/vite/plugins/use-cache-transform.ts
 import path5 from "node:path";
 import MagicString4 from "magic-string";
+init_debug();
 var debug4 = createRangoDebugger(NS.transform);
 var CACHE_RUNTIME_IMPORT = "@rangojs/router/cache-runtime";
 var LAYOUT_TEMPLATE_PATTERN = /\/(layout|template)\.(tsx?|jsx?)$/;
@@ -2115,6 +2224,7 @@ function warnOnNearMissDirectives(ast, fileId, warn) {
 }
 
 // src/vite/plugins/client-ref-dedup.ts
+init_debug();
 var debug5 = createRangoDebugger(NS.transform);
 var CLIENT_IN_SERVER_PROXY_PREFIX = "virtual:vite-rsc/client-in-server-package-proxy/";
 function extractPackageName(absolutePath) {
@@ -2210,21 +2320,35 @@ async function initializeApp() {
 
 initializeApp().catch(console.error);
 `.trim();
-var VIRTUAL_ENTRY_SSR = `
-import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
+function getVirtualEntrySSR(headScripts = "preinit") {
+  const preinit = headScripts !== "preload";
+  const depsImportNames = preinit ? "createFromReadableStream,\n  setOnClientReference," : "createFromReadableStream,";
+  const ssrImportNames = preinit ? "\n  installClientReferencePreinit," : "";
+  const install = preinit ? `
+// Upgrade client-reference modulepreload hints to executing module scripts in
+// the document head, for every render pass (live SSR, shell capture, resume).
+// See src/ssr/preinit-client-references.ts for the full rationale.
+installClientReferencePreinit(setOnClientReference);
+` : "";
+  const hs = JSON.stringify(headScripts);
+  return `
+import {
+  ${depsImportNames}
+} from "@rangojs/router/internal/deps/ssr";
 import { renderToReadableStream, resume } from "react-dom/server.edge";
 import { prerender } from "react-dom/static.edge";
 import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
 import {
   createSSRHandler,
   createShellCaptureHandler,
-  createShellResumeHandler,
+  createShellResumeHandler,${ssrImportNames}
 } from "@rangojs/router/ssr";
-
+${install}
 export const renderHTML = createSSRHandler({
   createFromReadableStream,
   renderToReadableStream,
   injectRSCPayload,
+  headScripts: ${hs},
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
@@ -2235,6 +2359,7 @@ export const captureShellHTML = createShellCaptureHandler({
   injectRSCPayload,
   prerender,
   resume,
+  headScripts: ${hs},
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
@@ -2245,10 +2370,12 @@ export const resumeShellHTML = createShellResumeHandler({
   injectRSCPayload,
   prerender,
   resume,
+  headScripts: ${hs},
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
 `.trim();
+}
 var RSC_ENTRY_BOOTSTRAP_IMPORTS = [
   "virtual:rsc-router/routes-manifest",
   "virtual:rsc-router/loader-manifest"
@@ -2393,7 +2520,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.tapabs2",
+  version: "0.1.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -2430,144 +2557,150 @@ var package_default = {
   type: "module",
   exports: {
     ".": {
-      types: "./src/index.rsc.ts",
+      types: "./dist/types/index.rsc.d.ts",
       "react-server": "./src/index.rsc.ts",
       default: "./src/index.ts"
     },
     "./server": {
-      types: "./src/server.ts",
+      types: "./dist/types/server.d.ts",
       import: "./src/server.ts"
     },
     "./client": {
-      types: "./src/client.tsx",
+      types: "./dist/types/client.d.ts",
       "react-server": "./src/client.rsc.tsx",
       default: "./src/client.tsx"
     },
     "./browser": {
-      types: "./src/browser/index.ts",
+      types: "./dist/types/browser/index.d.ts",
       default: "./src/browser/index.ts"
     },
     "./ssr": {
-      types: "./src/ssr/index.tsx",
+      types: "./dist/types/ssr/index.d.ts",
       default: "./src/ssr/index.tsx"
     },
     "./rsc": {
-      types: "./src/rsc/index.ts",
+      types: "./dist/types/rsc/index.d.ts",
       "react-server": "./src/rsc/index.ts",
       default: "./src/rsc/index.ts"
     },
     "./vite": {
-      types: "./src/vite/index.ts",
+      types: "./dist/types/vite/index.d.ts",
       import: "./dist/vite/index.js"
     },
     "./types": {
       types: "./src/vite/plugins/version.d.ts"
     },
     "./__internal": {
-      types: "./src/__internal.ts",
+      types: "./dist/types/__internal.d.ts",
       default: "./src/__internal.ts"
     },
     "./internal/deps/browser": {
-      types: "./src/deps/browser.ts",
+      types: "./dist/types/deps/browser.d.ts",
       default: "./src/deps/browser.ts"
     },
     "./internal/deps/ssr": {
-      types: "./src/deps/ssr.ts",
+      types: "./dist/types/deps/ssr.d.ts",
       default: "./src/deps/ssr.ts"
     },
     "./internal/deps/rsc": {
-      types: "./src/deps/rsc.ts",
+      types: "./dist/types/deps/rsc.d.ts",
       "react-server": "./src/deps/rsc.ts",
       default: "./src/deps/rsc.ts"
     },
     "./internal/deps/html-stream-client": {
-      types: "./src/deps/html-stream-client.ts",
+      types: "./dist/types/deps/html-stream-client.d.ts",
       default: "./src/deps/html-stream-client.ts"
     },
     "./internal/deps/html-stream-server": {
-      types: "./src/deps/html-stream-server.ts",
+      types: "./dist/types/deps/html-stream-server.d.ts",
       default: "./src/deps/html-stream-server.ts"
     },
     "./internal/rsc-handler": {
-      types: "./src/rsc/handler.ts",
+      types: "./dist/types/rsc/handler.d.ts",
       "react-server": "./src/rsc/handler.ts",
       default: "./src/rsc/handler.ts"
     },
     "./cache": {
-      types: "./src/cache/index.ts",
+      types: "./dist/types/cache/index.d.ts",
       "react-server": "./src/cache/index.ts",
       default: "./src/cache/index.ts"
     },
     "./cache-runtime": {
-      types: "./src/cache/cache-runtime.ts",
+      types: "./dist/types/cache/cache-runtime.d.ts",
       "react-server": "./src/cache/cache-runtime.ts",
       default: "./src/cache/cache-runtime.ts"
     },
     "./cloudflare": {
-      types: "./src/cloudflare/index.ts",
+      types: "./dist/types/cloudflare/index.d.ts",
       "react-server": "./src/cloudflare/index.ts",
       default: "./src/cloudflare/index.ts"
     },
     "./vercel": {
-      types: "./src/vercel/index.ts",
+      types: "./dist/types/vercel/index.d.ts",
       "react-server": "./src/vercel/index.ts",
       default: "./src/vercel/index.ts"
     },
     "./theme": {
-      types: "./src/theme/index.ts",
+      types: "./dist/types/theme/index.d.ts",
       default: "./src/theme/index.ts"
     },
     "./build": {
-      types: "./src/build/index.ts",
+      types: "./dist/types/build/index.d.ts",
       import: "./src/build/index.ts"
     },
+    "./build/shell-capture": {
+      types: "./dist/types/prerender/build-shell-capture.d.ts",
+      "react-server": "./src/prerender/build-shell-capture.ts",
+      import: "./src/prerender/build-shell-capture.ts"
+    },
     "./host": {
-      types: "./src/host/index.ts",
+      types: "./dist/types/host/index.d.ts",
       "react-server": "./src/host/index.ts",
       default: "./src/host/index.ts"
     },
     "./host/testing": {
-      types: "./src/host/testing.ts",
+      types: "./dist/types/host/testing.d.ts",
       default: "./src/host/testing.ts"
     },
     "./testing": {
-      types: "./src/testing/index.ts",
+      types: "./dist/types/testing/index.d.ts",
       default: "./src/testing/index.ts"
     },
     "./testing/vitest": {
-      types: "./src/testing/vitest.ts",
+      types: "./dist/types/testing/vitest.d.ts",
       default: "./dist/testing/vitest.js"
     },
     "./testing/dom": {
-      types: "./src/testing/dom.entry.ts",
+      types: "./dist/types/testing/dom.entry.d.ts",
       default: "./src/testing/dom.entry.ts"
     },
     "./testing/e2e": {
-      types: "./src/testing/e2e/index.ts",
+      types: "./dist/types/testing/e2e/index.d.ts",
       default: "./src/testing/e2e/index.ts"
     },
     "./testing/flight": {
-      types: "./src/testing/flight.entry.ts",
+      types: "./dist/types/testing/flight.entry.d.ts",
       "react-server": "./src/testing/flight.entry.ts",
       default: "./src/testing/flight.entry.ts"
     },
     "./testing/flight-matchers": {
-      types: "./src/testing/flight-matchers.ts",
+      types: "./dist/types/testing/flight-matchers.d.ts",
       default: "./src/testing/flight-matchers.ts"
     }
   },
   publishConfig: {
     access: "public",
-    tag: "experimental"
+    tag: "latest"
   },
   scripts: {
-    build: "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: "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:ui": "playwright test --ui",
     "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
-    "test:unit": "vitest run",
+    "test:unit": "pnpm run build:types && vitest run",
     "test:unit:watch": "vitest",
     "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
   },
@@ -2636,7 +2769,7 @@ var package_default = {
     }
   },
   engines: {
-    node: "^20.19.0 || >=22.12.0"
+    node: ">=24.0.0"
   }
 };
 
@@ -2684,6 +2817,7 @@ function getPackageAliases() {
 }
 function getVendorAliases() {
   const specs = [
+    "@vitejs/plugin-rsc/vendor/react-server-dom/client.browser",
     "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
     "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge"
   ];
@@ -3832,6 +3966,13 @@ function createVersionPlugin() {
   return {
     name: "@rangojs/router:version",
     enforce: "pre",
+    // The build-time shell capture phase (producer B, #699) stamps entries
+    // with THIS instance's version — the value folded into the shipped worker
+    // — never the discovery temp server's own version-plugin value (a
+    // different Date.now() stamp that would fail the serve-side gate).
+    api: {
+      getBuildVersion: () => currentVersion
+    },
     configResolved(config) {
       isDev = config.command === "serve";
       resolvedCacheDir = config.cacheDir ? String(config.cacheDir).replace(/\\/g, "/") : void 0;
@@ -3922,6 +4063,7 @@ import * as Vite from "vite";
 import { isAbsolute, resolve as resolve4 } from "node:path";
 
 // src/vite/plugins/performance-tracks.ts
+init_debug();
 import { readFile } from "node:fs/promises";
 var debug6 = createRangoDebugger(NS.transform);
 var RSDW_PATCH_RE = /((?:var|let|const)\s+\w+\s*=\s*root\._children\s*,\s*(\w+)\s*=\s*root\._debugInfo\s*[;,])/;
@@ -4017,13 +4159,13 @@ function normalizeHostRouterEntry(rawInput, root, exists) {
   }
   return exists(resolve4(root, raw)) ? "./" + raw : raw;
 }
-function createVirtualEntriesPlugin(entries, routerPathRef) {
+function createVirtualEntriesPlugin(entries, routerPathRef, options) {
   const virtualModules = {};
   if (entries.client === VIRTUAL_IDS.browser) {
     virtualModules[VIRTUAL_IDS.browser] = VIRTUAL_ENTRY_BROWSER;
   }
   if (entries.ssr === VIRTUAL_IDS.ssr) {
-    virtualModules[VIRTUAL_IDS.ssr] = VIRTUAL_ENTRY_SSR;
+    virtualModules[VIRTUAL_IDS.ssr] = getVirtualEntrySSR(options?.headScripts);
   }
   const knownIds = new Set(Object.keys(virtualModules));
   if (entries.rsc === VIRTUAL_IDS.rsc) {
@@ -4104,83 +4246,17 @@ function getManualChunks(id) {
   return void 0;
 }
 
-// src/vite/plugins/client-ref-hashing.ts
-import { relative as relative2 } from "node:path";
-import { createHash as createHash2 } from "node:crypto";
-var debug7 = createRangoDebugger(NS.transform);
-var CLIENT_PKG_PROXY_PREFIX = "/@id/__x00__virtual:vite-rsc/client-package-proxy/";
-var CLIENT_IN_SERVER_PKG_PROXY_PREFIX = "/@id/__x00__virtual:vite-rsc/client-in-server-package-proxy/";
-var FS_PREFIX = "/@fs/";
-function hashRefKey(relativeId) {
-  return createHash2("sha256").update(relativeId).digest("hex").slice(0, 12);
+// src/vite/utils/client-chunks.ts
+init_debug();
+init_client_ref_hashing();
+var debugChunks = createRangoDebugger(NS.chunks);
+function isSharedRuntime(meta) {
+  return [meta.id, meta.normalizedId].some(
+    (path6) => path6.includes("/node_modules/") || /\/@rangojs\/router\//.test(path6) || /\/packages\/(rangojs-router|rsc-router)\/(src|dist)\//.test(path6)
+  );
 }
-function computeProductionHash(projectRoot, refKey) {
-  let toHash;
-  if (refKey.startsWith(CLIENT_PKG_PROXY_PREFIX)) {
-    toHash = refKey.slice(CLIENT_PKG_PROXY_PREFIX.length);
-  } else if (refKey.startsWith(CLIENT_IN_SERVER_PKG_PROXY_PREFIX)) {
-    const absPath = decodeURIComponent(
-      refKey.slice(CLIENT_IN_SERVER_PKG_PROXY_PREFIX.length)
-    );
-    toHash = relative2(projectRoot, absPath).replaceAll("\\", "/");
-  } else if (refKey.startsWith(FS_PREFIX)) {
-    const absPath = refKey.slice(FS_PREFIX.length - 1);
-    toHash = relative2(projectRoot, absPath).replaceAll("\\", "/");
-  } else if (refKey.startsWith("/")) {
-    toHash = refKey.slice(1);
-  } else {
-    return refKey;
-  }
-  return hashRefKey(toHash);
-}
-var REGISTER_CLIENT_REF_RE = /registerClientReference\(\s*(?:(?:\([^)]*\))|(?:\(\)[\s\S]*?\}))\s*,\s*"([^"]+)"\s*,\s*"[^"]+"\s*\)/g;
-function transformClientRefs(code, projectRoot) {
-  if (!code.includes("registerClientReference")) return null;
-  let hasReplacement = false;
-  const result = code.replace(
-    REGISTER_CLIENT_REF_RE,
-    (match, refKey) => {
-      const hash = computeProductionHash(projectRoot, refKey);
-      if (hash === refKey) return match;
-      hasReplacement = true;
-      return match.replace(`"${refKey}"`, `"${hash}"`);
-    }
-  );
-  return hasReplacement ? result : null;
-}
-function hashClientRefs(projectRoot) {
-  const counter = createCounter(debug7, "hash-client-refs");
-  return {
-    name: "@rangojs/router:hash-client-refs",
-    enforce: "post",
-    applyToEnvironment(env) {
-      return env.name === "rsc";
-    },
-    buildEnd() {
-      counter?.flush();
-    },
-    transform(code, id) {
-      const start = counter ? performance.now() : 0;
-      try {
-        const result = transformClientRefs(code, projectRoot);
-        if (result === null) return;
-        return { code: result, map: null };
-      } finally {
-        counter?.record(id, performance.now() - start);
-      }
-    }
-  };
-}
-
-// src/vite/utils/client-chunks.ts
-var debugChunks = createRangoDebugger(NS.chunks);
-function isSharedRuntime(meta) {
-  return [meta.id, meta.normalizedId].some(
-    (path6) => path6.includes("/node_modules/") || /\/@rangojs\/router\//.test(path6) || /\/packages\/(rangojs-router|rsc-router)\/(src|dist)\//.test(path6)
-  );
-}
-function sanitizeGroup(name) {
-  return name.replace(/[^a-zA-Z0-9_-]+/g, "_").replace(/^_+|_+$/g, "") || "app";
+function sanitizeGroup(name) {
+  return name.replace(/[^a-zA-Z0-9_-]+/g, "_").replace(/^_+|_+$/g, "") || "app";
 }
 var ROUTE_ROOT_DIRS = /* @__PURE__ */ new Set([
   "routes",
@@ -4528,6 +4604,7 @@ function createVersionInjectorPlugin(rscEntryPath) {
 }
 
 // src/vite/plugins/cjs-to-esm.ts
+init_debug();
 var debug8 = createRangoDebugger(NS.transform);
 function createCjsToEsmPlugin() {
   let isProduction = false;
@@ -4591,11 +4668,33 @@ function createCjsToEsmPlugin() {
 
 // src/vite/router-discovery.ts
 import { createServer as createViteServer } from "vite";
-import { resolve as resolve10 } from "node:path";
-import { readFileSync as readFileSync6 } from "node:fs";
+import { resolve as resolve11 } from "node:path";
+import { readFileSync as readFileSync7 } from "node:fs";
 import { createRequire as createRequire3, register } from "node:module";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
 
+// src/rsc/shell-serve.ts
+import React from "react";
+
+// src/server/context.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+var RSC_CONTEXT_KEY = /* @__PURE__ */ Symbol.for("rangojs-router:rsc-context");
+var RangoContext = globalThis[RSC_CONTEXT_KEY] ??= new AsyncLocalStorage();
+var LOADER_SCOPE_KEY = /* @__PURE__ */ Symbol.for("rangojs-router:loader-scope");
+var loaderScopeALS = globalThis[LOADER_SCOPE_KEY] ??= new AsyncLocalStorage();
+var LOADER_BODY_SCOPE_KEY = /* @__PURE__ */ Symbol.for("rangojs-router:loader-body-scope");
+var loaderBodyScopeALS = globalThis[LOADER_BODY_SCOPE_KEY] ??= new AsyncLocalStorage();
+var PUSH_CALLBACK_SCOPE_KEY = /* @__PURE__ */ Symbol.for(
+  "rangojs-router:push-callback-scope"
+);
+var pushCallbackScopeALS = globalThis[PUSH_CALLBACK_SCOPE_KEY] ??= new AsyncLocalStorage();
+
+// src/rsc/shell-serve.ts
+var DEV_SHELL_PROBE_TIMEOUT_MS = 1e4;
+function normalizeCaptureTimeout(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 1 ? value : void 0;
+}
+
 // src/vite/inject-client-debug.ts
 function isRouterInternalDebugId(id) {
   if (!id.includes("internal-debug")) return false;
@@ -4756,6 +4855,9 @@ function walk(node, visit) {
   }
 }
 
+// src/vite/router-discovery.ts
+init_client_ref_hashing();
+
 // src/vite/utils/bundle-analysis.ts
 function findMatchingParenInBundle(code, openParenPos) {
   let depth = 1;
@@ -4860,6 +4962,9 @@ function createDiscoveryState(entryPath, opts) {
     perRouterManifestDataMap: /* @__PURE__ */ new Map(),
     prerenderManifestEntries: null,
     staticManifestEntries: null,
+    shellCandidates: null,
+    prerenderPayloadValues: null,
+    shellPhaseTempServer: null,
     handlerChunkInfoMap: /* @__PURE__ */ new Map(),
     staticHandlerChunkInfoMap: /* @__PURE__ */ new Map(),
     rscEntryFileName: null,
@@ -4909,13 +5014,13 @@ function checkSelfGenWrite(state, filePath, consume) {
 }
 
 // src/router/logging.ts
-import { AsyncLocalStorage } from "node:async_hooks";
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
 
 // src/internal-debug.ts
 var INTERNAL_RANGO_DEBUG = typeof process !== "undefined" && Boolean(process.env?.INTERNAL_RANGO_DEBUG);
 
 // src/router/logging.ts
-var routerLogContext = new AsyncLocalStorage();
+var routerLogContext = new AsyncLocalStorage2();
 
 // src/router/url-params.ts
 var PATH_SAFE_ESCAPES = {
@@ -5037,10 +5142,9 @@ function buildRouteToStaticPrefix(prefixTree, result) {
 }
 
 // src/build/route-trie.ts
-function buildRouteTrie(routeManifest, routeAncestry, routeToStaticPrefix, routeTrailingSlash, prerenderRouteNames, passthroughRouteNames, responseTypeRoutes) {
+function buildRouteTrie(routeManifest, routeToStaticPrefix, routeTrailingSlash, prerenderRouteNames, passthroughRouteNames, responseTypeRoutes) {
   const root = {};
   for (const [routeName, pattern] of Object.entries(routeManifest)) {
-    const ancestry = routeAncestry[routeName] || [];
     const staticPrefix = routeToStaticPrefix[routeName] || "";
     const trailingSlash = routeTrailingSlash?.[routeName];
     const responseType = responseTypeRoutes?.[routeName];
@@ -5050,7 +5154,6 @@ function buildRouteTrie(routeManifest, routeAncestry, routeToStaticPrefix, route
     insertRoute(root, segments, 0, {
       n: routeName,
       sp: staticPrefix,
-      a: ancestry,
       ...trailingSlash ? { ts: trailingSlash } : {},
       ...prerenderRouteNames?.has(routeName) ? { pr: true } : {},
       ...passthroughRouteNames?.has(routeName) ? { pt: true } : {},
@@ -5083,8 +5186,7 @@ function sortSuffixParams(node) {
   }
 }
 function buildPerRouterTrie(manifest) {
-  const ancestry = manifest._routeAncestry;
-  if (!ancestry || Object.keys(ancestry).length === 0) {
+  if (Object.keys(manifest.routeManifest).length === 0) {
     return null;
   }
   const routeToStaticPrefix = {};
@@ -5096,7 +5198,6 @@ function buildPerRouterTrie(manifest) {
   }
   return buildRouteTrie(
     manifest.routeManifest,
-    ancestry,
     routeToStaticPrefix,
     manifest.routeTrailingSlash,
     manifest.prerenderRoutes ? new Set(manifest.prerenderRoutes) : void 0,
@@ -5442,18 +5543,24 @@ function getStagedAssetDir(projectRoot) {
 function resetStagedBuildAssets(projectRoot) {
   rmSync(getStagedAssetDir(projectRoot), { recursive: true, force: true });
 }
-function stageBuildAssetModule(projectRoot, prefix, exportValue) {
-  const stagedDir = getStagedAssetDir(projectRoot);
-  mkdirSync(stagedDir, { recursive: true });
+function writeBuildAssetModule(dir, prefix, exportValue) {
+  mkdirSync(dir, { recursive: true });
   const contentHash = createHash4("sha256").update(exportValue).digest("hex").slice(0, 8);
   const fileName = `${prefix}-${contentHash}.js`;
-  const filePath = resolve7(stagedDir, fileName);
+  const filePath = resolve7(dir, fileName);
   if (!existsSync5(filePath)) {
     writeFileSync2(filePath, `export default ${exportValue};
 `);
   }
   return fileName;
 }
+function stageBuildAssetModule(projectRoot, prefix, exportValue) {
+  return writeBuildAssetModule(
+    getStagedAssetDir(projectRoot),
+    prefix,
+    exportValue
+  );
+}
 function copyStagedBuildAssets(projectRoot, fileNames) {
   const stagedDir = getStagedAssetDir(projectRoot);
   const distAssetsDir = resolve7(projectRoot, "dist/rsc/assets");
@@ -5469,6 +5576,7 @@ function copyStagedBuildAssets(projectRoot, fileNames) {
 }
 
 // src/vite/discovery/prerender-collection.ts
+init_debug();
 var debug9 = createRangoDebugger(NS.prerender);
 async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
   if (!state.opts?.enableBuildPrerender || !state.isBuildMode) return;
@@ -5676,6 +5784,18 @@ async function expandPrerenderRoutes(state, rscEnv, registry, allManifests) {
               "__pr",
               mainValue
             );
+            if (result.ppr !== void 0 && result.ppr !== false) {
+              (state.shellCandidates ??= []).push({
+                urlPath: entry.urlPath,
+                routeName: result.routeName,
+                paramHash,
+                ppr: result.ppr === true ? true : result.ppr
+              });
+              (state.prerenderPayloadValues ??= /* @__PURE__ */ new Map()).set(
+                mainKey,
+                mainValue
+              );
+            }
             if (result.interceptSegments?.length) {
               const interceptKey = `${result.routeName}/${paramHash}/i`;
               const interceptValue = JSON.stringify({
@@ -5926,6 +6046,8 @@ function describeDiscoveryFailure(err, opts = {}) {
 }
 
 // src/vite/discovery/discover-routers.ts
+init_debug();
+init_client_ref_hashing();
 var debug10 = createRangoDebugger(NS.discovery);
 async function discoverRouters(state, rscEnv) {
   if (!state.resolvedEntryPath) return;
@@ -5990,7 +6112,6 @@ async function discoverRouters(state, rscEnv) {
   const newPerRouterManifestDataMap = /* @__PURE__ */ new Map();
   const newPerRouterPrecomputedMap = /* @__PURE__ */ new Map();
   const newPerRouterTrieMap = /* @__PURE__ */ new Map();
-  let mergedRouteAncestry = {};
   let mergedRouteTrailingSlash = {};
   let routerMountIndex = 0;
   const allManifests = [];
@@ -6053,9 +6174,6 @@ async function discoverRouters(state, rscEnv) {
       sourceFile: router.__sourceFile,
       factoryOnlyPrefixes
     });
-    if (manifest._routeAncestry) {
-      Object.assign(mergedRouteAncestry, manifest._routeAncestry);
-    }
     if (manifest.routeTrailingSlash) {
       Object.assign(mergedRouteTrailingSlash, manifest.routeTrailingSlash);
     }
@@ -6090,49 +6208,46 @@ async function discoverRouters(state, rscEnv) {
   let newMergedRouteTrie = null;
   const trieStart = debug10 ? performance.now() : 0;
   if (Object.keys(newMergedRouteManifest).length > 0) {
-    if (mergedRouteAncestry) {
-      const routeToStaticPrefix = {};
-      for (const { manifest } of allManifests) {
-        for (const name of Object.keys(manifest.routeManifest)) {
-          if (!(name in routeToStaticPrefix)) {
-            routeToStaticPrefix[name] = "";
-          }
-        }
-        buildRouteToStaticPrefix(manifest.prefixTree, routeToStaticPrefix);
-      }
-      const prerenderRouteNames = /* @__PURE__ */ new Set();
-      const passthroughRouteNames = /* @__PURE__ */ new Set();
-      const mergedResponseTypeRoutes = {};
-      for (const { manifest } of allManifests) {
-        if (manifest.prerenderRoutes) {
-          for (const name of manifest.prerenderRoutes) {
-            prerenderRouteNames.add(name);
-          }
-        }
-        if (manifest.passthroughRoutes) {
-          for (const name of manifest.passthroughRoutes) {
-            passthroughRouteNames.add(name);
-          }
+    const routeToStaticPrefix = {};
+    for (const { manifest } of allManifests) {
+      for (const name of Object.keys(manifest.routeManifest)) {
+        if (!(name in routeToStaticPrefix)) {
+          routeToStaticPrefix[name] = "";
         }
-        if (manifest.responseTypeRoutes) {
-          Object.assign(mergedResponseTypeRoutes, manifest.responseTypeRoutes);
+      }
+      buildRouteToStaticPrefix(manifest.prefixTree, routeToStaticPrefix);
+    }
+    const prerenderRouteNames = /* @__PURE__ */ new Set();
+    const passthroughRouteNames = /* @__PURE__ */ new Set();
+    const mergedResponseTypeRoutes = {};
+    for (const { manifest } of allManifests) {
+      if (manifest.prerenderRoutes) {
+        for (const name of manifest.prerenderRoutes) {
+          prerenderRouteNames.add(name);
         }
       }
-      newMergedRouteTrie = buildRouteTrie(
-        newMergedRouteManifest,
-        mergedRouteAncestry,
-        routeToStaticPrefix,
-        mergedRouteTrailingSlash,
-        prerenderRouteNames,
-        passthroughRouteNames,
-        mergedResponseTypeRoutes
-      );
-      for (const { id, manifest } of allManifests) {
-        const perRouterTrie = buildPerRouterTrie(manifest);
-        if (perRouterTrie) {
-          newPerRouterTrieMap.set(id, perRouterTrie);
+      if (manifest.passthroughRoutes) {
+        for (const name of manifest.passthroughRoutes) {
+          passthroughRouteNames.add(name);
         }
       }
+      if (manifest.responseTypeRoutes) {
+        Object.assign(mergedResponseTypeRoutes, manifest.responseTypeRoutes);
+      }
+    }
+    newMergedRouteTrie = buildRouteTrie(
+      newMergedRouteManifest,
+      routeToStaticPrefix,
+      mergedRouteTrailingSlash,
+      prerenderRouteNames,
+      passthroughRouteNames,
+      mergedResponseTypeRoutes
+    );
+    for (const { id, manifest } of allManifests) {
+      const perRouterTrie = buildPerRouterTrie(manifest);
+      if (perRouterTrie) {
+        newPerRouterTrieMap.set(id, perRouterTrie);
+      }
     }
   }
   debug10?.(
@@ -6146,11 +6261,286 @@ async function discoverRouters(state, rscEnv) {
   state.perRouterPrecomputedMap = newPerRouterPrecomputedMap;
   state.perRouterTrieMap = newPerRouterTrieMap;
   state.mergedRouteTrie = newMergedRouteTrie;
+  if (serverMod.setRouteTrie && newMergedRouteTrie) {
+    serverMod.setRouteTrie(newMergedRouteTrie);
+  }
+  const perRouterSetters = [
+    [newPerRouterManifestDataMap, "setRouterManifest"],
+    [newPerRouterTrieMap, "setRouterTrie"],
+    [newPerRouterPrecomputedMap, "setRouterPrecomputedEntries"]
+  ];
+  for (const [map, fn] of perRouterSetters) {
+    const setter = serverMod[fn];
+    if (typeof setter !== "function") continue;
+    for (const [routerId, value] of map) setter(routerId, value);
+  }
   await expandPrerenderRoutes(state, rscEnv, registry, allManifests);
   await renderStaticHandlers(state, rscEnv, registry);
   return serverMod;
 }
 
+// src/vite/discovery/shell-prerender-phase.ts
+import { existsSync as existsSync6, readdirSync as readdirSync2, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "node:fs";
+import { join as join4, resolve as resolve8 } from "node:path";
+
+// src/prerender/shell-manifest-key.ts
+function buildShellManifestKey(pathname) {
+  return pathname;
+}
+
+// src/vite/discovery/shell-prerender-phase.ts
+init_debug();
+var debug11 = createRangoDebugger(NS.prerender);
+async function runShellPrerenderPhase(s, builder) {
+  const tempServer = s.shellPhaseTempServer;
+  if (!s.isBuildMode || !s.shellCandidates?.length || !tempServer) return;
+  const candidates = s.shellCandidates;
+  const startTotal = performance.now();
+  console.log(`[rango] Shell-prerendering ${candidates.length} URL(s)...`);
+  let restoreClientRequire;
+  try {
+    const rscEnv = tempServer.environments?.rsc;
+    const ssrEnv = tempServer.environments?.ssr;
+    if (!rscEnv?.runner || !ssrEnv?.runner) {
+      console.warn(
+        `[rango] shell prerender: temp server runners unavailable (rsc=${String(!!rscEnv?.runner)}, ssr=${String(!!ssrEnv?.runner)}); skipping \u2014 routes keep runtime shell capture.`
+      );
+      return;
+    }
+    const versionPlugin = (builder?.config?.plugins ?? []).find(
+      (p) => p?.name === "@rangojs/router:version"
+    );
+    const buildVersion = versionPlugin?.api?.getBuildVersion?.();
+    if (!buildVersion) {
+      console.warn(
+        "[rango] shell prerender: main build version unavailable; skipping \u2014 routes keep runtime shell capture."
+      );
+      return;
+    }
+    const payloads = s.prerenderPayloadValues ?? /* @__PURE__ */ new Map();
+    const fetchedKeys = /* @__PURE__ */ new Set();
+    globalThis.__loadPrerenderManifestModule = async () => ({
+      default: Object.fromEntries([...payloads.keys()].map((k) => [k, k])),
+      loadPrerenderAsset: async (spec) => {
+        fetchedKeys.add(spec);
+        return { default: JSON.parse(payloads.get(spec)) };
+      }
+    });
+    const ssrRunner = ssrEnv.runner;
+    const ssrPkg = await ssrRunner.import("@rangojs/router/ssr");
+    const ssrDeps = await ssrRunner.import("@rangojs/router/internal/deps/ssr");
+    const reactDomServer = await ssrRunner.import("react-dom/server.edge");
+    const reactDomStatic = await ssrRunner.import("react-dom/static.edge");
+    const htmlStream = await ssrRunner.import(
+      "@rangojs/router/internal/deps/html-stream-server"
+    );
+    const clientOutDir = builder?.environments?.client?.config?.build?.outDir ?? resolve8(s.projectRoot, "dist/client");
+    const clientAssetsDir = join4(clientOutDir, "assets");
+    const entryFile = existsSync6(clientAssetsDir) ? readdirSync2(clientAssetsDir).find((f) => /^index-.*\.js$/.test(f)) : void 0;
+    if (!entryFile) {
+      console.warn(
+        `[rango] shell prerender: built client entry not found under ${clientAssetsDir}; skipping \u2014 routes keep runtime shell capture.`
+      );
+      return;
+    }
+    const base = builder?.config?.base ?? "/";
+    const normalizedBase = base.endsWith("/") ? base : `${base}/`;
+    const bootstrapContent = `import("${normalizedBase}assets/${entryFile}")`;
+    debug11?.("shell prerender bootstrap: %s", bootstrapContent);
+    const minimalPlugin = (tempServer.config?.plugins ?? []).find(
+      (p) => p?.name === "rsc:minimal"
+    );
+    const rscManager = minimalPlugin?.api?.manager;
+    const { computeProductionHash: computeProductionHash2 } = await Promise.resolve().then(() => (init_client_ref_hashing(), client_ref_hashing_exports));
+    let hashToDevKey = /* @__PURE__ */ new Map();
+    const rebuildHashMap = () => {
+      hashToDevKey = /* @__PURE__ */ new Map();
+      const metaMap = rscManager?.clientReferenceMetaMap ?? {};
+      for (const meta of Object.values(metaMap)) {
+        hashToDevKey.set(
+          computeProductionHash2(s.projectRoot, meta.referenceKey),
+          meta.referenceKey
+        );
+      }
+    };
+    const origClientRequire = globalThis.__vite_rsc_client_require__;
+    if (typeof origClientRequire === "function") {
+      restoreClientRequire = () => {
+        globalThis.__vite_rsc_client_require__ = origClientRequire;
+      };
+      globalThis.__vite_rsc_client_require__ = (id) => {
+        const base2 = id.split("$$cache=")[0];
+        let mapped = hashToDevKey.get(base2);
+        if (mapped === void 0) {
+          rebuildHashMap();
+          mapped = hashToDevKey.get(base2);
+        }
+        return origClientRequire(mapped ?? id);
+      };
+    }
+    const captureShellHTML = ssrPkg.createShellCaptureHandler({
+      createFromReadableStream: ssrDeps.createFromReadableStream,
+      renderToReadableStream: reactDomServer.renderToReadableStream ?? reactDomServer.default?.renderToReadableStream,
+      resume: reactDomServer.resume ?? reactDomServer.default?.resume,
+      prerender: reactDomStatic.prerender ?? reactDomStatic.default?.prerender,
+      injectRSCPayload: htmlStream.injectRSCPayload,
+      headScripts: "preinit",
+      loadBootstrapScriptContent: async () => bootstrapContent
+    });
+    const rscRunner = rscEnv.runner;
+    const captureMod = await rscRunner.import(
+      "@rangojs/router/build/shell-capture"
+    );
+    const serverMod = await rscRunner.import("@rangojs/router/server");
+    const registry = serverMod.RouterRegistry;
+    const staged = [];
+    let skipCount = 0;
+    const pathCounts = /* @__PURE__ */ new Map();
+    for (const cand of candidates) {
+      pathCounts.set(cand.urlPath, (pathCounts.get(cand.urlPath) ?? 0) + 1);
+    }
+    for (const cand of candidates) {
+      if ((pathCounts.get(cand.urlPath) ?? 0) > 1) {
+        console.warn(
+          `[rango]   SHELL SKIP ${cand.urlPath.padEnd(34)} - pathname claimed by multiple prerender routes; routes keep runtime capture`
+        );
+        skipCount++;
+        continue;
+      }
+      const startUrl = performance.now();
+      const policy = captureMod.resolveBuildPprConfig(cand.ppr);
+      const mainKey = `${cand.routeName}/${cand.paramHash}`;
+      let handled = false;
+      const mismatches = [];
+      for (const [, routerInstance] of registry) {
+        if (typeof routerInstance.match !== "function") continue;
+        try {
+          const res = await captureMod.captureShellForBuild({
+            router: routerInstance,
+            urlPath: cand.urlPath,
+            routeName: cand.routeName,
+            key: `${cand.urlPath}:shell`,
+            ttl: policy.ttl,
+            swr: policy.swr,
+            tags: policy.tags,
+            maxSnapshotBytes: policy.maxSnapshotBytes,
+            captureTimeout: policy.captureTimeout,
+            buildEnv: s.resolvedBuildEnv,
+            buildVersion,
+            captureShellHTML,
+            debug: !!debug11
+          });
+          if (res.outcome === "route-mismatch") {
+            mismatches.push(res.matchedRouteName ?? "(no match)");
+            continue;
+          }
+          handled = true;
+          const elapsed = (performance.now() - startUrl).toFixed(0);
+          if (res.outcome !== "stored" || !res.entry) {
+            console.warn(
+              `[rango]   SHELL SKIP ${cand.urlPath.padEnd(34)} (${elapsed}ms) - capture ${res.outcome}; route keeps runtime capture`
+            );
+            skipCount++;
+            break;
+          }
+          if (!fetchedKeys.has(mainKey)) {
+            console.warn(
+              `[rango]   SHELL SKIP ${cand.urlPath.padEnd(34)} (${elapsed}ms) - capture did not replay the prerender store; route keeps runtime capture`
+            );
+            skipCount++;
+            break;
+          }
+          const value = {
+            entry: res.entry,
+            ttl: policy.ttl,
+            swr: policy.swr,
+            tags: res.tags,
+            routeName: cand.routeName
+          };
+          staged.push({
+            key: buildShellManifestKey(cand.urlPath),
+            value: JSON.stringify(value)
+          });
+          console.log(
+            `[rango]   SHELL OK   ${cand.urlPath.padEnd(34)} (${elapsed}ms)`
+          );
+          break;
+        } catch (err) {
+          handled = true;
+          const elapsed = (performance.now() - startUrl).toFixed(0);
+          console.warn(
+            `[rango]   SHELL SKIP ${cand.urlPath.padEnd(34)} (${elapsed}ms) - ${err?.message ?? err}; route keeps runtime capture`
+          );
+          skipCount++;
+          break;
+        }
+      }
+      if (!handled) {
+        console.warn(
+          `[rango]   SHELL SKIP ${cand.urlPath.padEnd(34)} - no router matched "${cand.routeName}"` + (mismatches.length > 0 ? ` (matched: ${mismatches.join(", ")})` : "") + "; route keeps runtime capture"
+        );
+        skipCount++;
+      }
+    }
+    if (staged.length > 0) {
+      const rscOutDir = builder?.environments?.rsc?.config?.build?.outDir ?? resolve8(s.projectRoot, "dist/rsc");
+      writeShellManifest(s, rscOutDir, staged);
+    }
+    const totalElapsed = (performance.now() - startTotal).toFixed(0);
+    const parts = [`${staged.length} done`];
+    if (skipCount > 0) parts.push(`${skipCount} skipped`);
+    console.log(
+      `[rango] Shell prerender complete: ${parts.join(", ")} (${totalElapsed}ms total)`
+    );
+  } catch (err) {
+    console.warn(
+      `[rango] shell prerender phase failed: ${err?.message ?? err}; routes keep runtime shell capture.`
+    );
+  } finally {
+    delete globalThis.__loadPrerenderManifestModule;
+    restoreClientRequire?.();
+  }
+}
+function writeShellManifest(s, rscOutDir, staged) {
+  const rscEntryPath = resolve8(rscOutDir, s.rscEntryFileName ?? "index.js");
+  if (!existsSync6(rscEntryPath)) {
+    console.warn(
+      `[rango] shell prerender: RSC entry not found at ${rscEntryPath}; entries not persisted \u2014 routes keep runtime capture.`
+    );
+    return;
+  }
+  const assetsDir = resolve8(rscOutDir, "assets");
+  let totalBytes = 0;
+  const manifestMap = {};
+  const countedFiles = /* @__PURE__ */ new Set();
+  for (const { key, value } of staged) {
+    const fileName = writeBuildAssetModule(assetsDir, "__ps", value);
+    if (!countedFiles.has(fileName)) {
+      countedFiles.add(fileName);
+      totalBytes += Buffer.byteLength(value) + "export default ;\n".length;
+    }
+    manifestMap[key] = `./assets/${fileName}`;
+  }
+  const manifestCode = [
+    `const m=${jsonParseExpression(manifestMap)};`,
+    `export function loadShellAsset(s){return import(s)}`,
+    `export default m;`,
+    ""
+  ].join("\n");
+  writeFileSync3(resolve8(rscOutDir, "__shell-manifest.js"), manifestCode);
+  totalBytes += Buffer.byteLength(manifestCode);
+  const rscCode = readFileSync4(rscEntryPath, "utf-8");
+  if (!rscCode.includes("__shell-manifest.js")) {
+    const injection = `globalThis.__loadShellManifestModule = () => import("./__shell-manifest.js");
+`;
+    writeFileSync3(rscEntryPath, injection + rscCode);
+  }
+  const totalKB = (totalBytes / 1024).toFixed(1);
+  console.log(
+    `[rango] Wrote shell assets (${totalKB} KB total, ${staged.length} entries)`
+  );
+}
+
 // src/vite/discovery/dev-prerender-cache.ts
 function payloadBodiesFromResult(result) {
   const main = JSON.stringify({
@@ -6189,8 +6579,8 @@ function createDevPrerenderCache(maxEntriesPerRouter = MAX_ENTRIES_PER_ROUTER) {
 }
 
 // src/vite/discovery/route-types-writer.ts
-import { dirname as dirname3, join as join4, resolve as resolve8 } from "node:path";
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, existsSync as existsSync6, unlinkSync as unlinkSync2 } from "node:fs";
+import { dirname as dirname3, join as join5, resolve as resolve9 } from "node:path";
+import { readFileSync as readFileSync5, writeFileSync as writeFileSync4, existsSync as existsSync7, unlinkSync as unlinkSync2 } from "node:fs";
 function filterUserNamedRoutes(manifest) {
   const filtered = {};
   for (const [name, pattern] of Object.entries(manifest)) {
@@ -6201,10 +6591,10 @@ function filterUserNamedRoutes(manifest) {
   return filtered;
 }
 function writeGenFileIfChanged(state, outPath, source, opts) {
-  const existing = existsSync6(outPath) ? readFileSync4(outPath, "utf-8") : null;
+  const existing = existsSync7(outPath) ? readFileSync5(outPath, "utf-8") : null;
   if (existing === source) return;
   markSelfGenWrite(state, outPath, source);
-  writeFileSync3(outPath, source);
+  writeFileSync4(outPath, source);
   if (opts?.log) console.log(`[rango] Generated route types -> ${outPath}`);
 }
 function writeCombinedRouteTypesWithTracking(state, opts) {
@@ -6219,10 +6609,10 @@ function writeRouteTypesFiles(state) {
   if (state.perRouterManifests.length === 0) return;
   try {
     const entryDir = dirname3(
-      resolve8(state.projectRoot, state.resolvedEntryPath)
+      resolve9(state.projectRoot, state.resolvedEntryPath)
     );
-    const oldCombinedPath = join4(entryDir, "named-routes.gen.ts");
-    if (existsSync6(oldCombinedPath)) {
+    const oldCombinedPath = join5(entryDir, "named-routes.gen.ts");
+    if (existsSync7(oldCombinedPath)) {
       unlinkSync2(oldCombinedPath);
       console.log(
         `[rango] Removed stale combined route types: ${oldCombinedPath}`
@@ -6303,7 +6693,9 @@ function supplementGenFilesWithRuntimeRoutes(state) {
 }
 
 // src/vite/discovery/virtual-module-codegen.ts
-import { dirname as dirname4, basename, join as join5 } from "node:path";
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync5 } from "node:fs";
+import { dirname as dirname4, basename, join as join6 } from "node:path";
+var MANIFEST_EXTERNALIZE_THRESHOLD = 512 * 1024;
 function generateRoutesManifestModule(state) {
   const hasManifest = state.mergedRouteManifest && Object.keys(state.mergedRouteManifest).length > 0;
   if (hasManifest) {
@@ -6318,7 +6710,7 @@ function generateRoutesManifestModule(state) {
           /\.(tsx?|jsx?)$/,
           ""
         );
-        const genPath = join5(
+        const genPath = join6(
           routerDir,
           `${routerBasename}.named-routes.gen.js`
         ).replaceAll("\\", "/");
@@ -6392,51 +6784,78 @@ function generateRoutesManifestModule(state) {
   }
   return `// Route manifest will be populated at runtime`;
 }
+function shortHash(input) {
+  let h = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(36);
+}
 function generatePerRouterModule(state, routerId) {
-  const routerEntry = state.perRouterManifests.find((e) => e.id === routerId);
+  const sourceFile = state.perRouterManifests.find(
+    (e) => e.id === routerId
+  )?.sourceFile;
   const trie = state.perRouterTrieMap.get(routerId);
   const entries = state.perRouterPrecomputedMap.get(routerId);
   const lines = [];
-  if (routerEntry?.sourceFile) {
-    const routerDir = dirname4(routerEntry.sourceFile);
-    const routerBasename = basename(routerEntry.sourceFile).replace(
-      /\.(tsx?|jsx?)$/,
-      ""
-    );
-    const genPath = join5(
+  if (sourceFile) {
+    const routerDir = dirname4(sourceFile);
+    const routerBasename = basename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
+    const genPath = join6(
       routerDir,
       `${routerBasename}.named-routes.gen.js`
     ).replaceAll("\\", "/");
-    lines.push(`import { NamedRoutes as _r } from ${JSON.stringify(genPath)};`);
-    lines.push(
-      `function __flat(r) { const o = {}; for (const [k, v] of Object.entries(r)) o[k] = typeof v === "string" ? v : v.path; return o; }`
-    );
-    lines.push(`export const manifest = __flat(_r);`);
-  } else {
-    const manifest = state.perRouterManifestDataMap.get(routerId);
-    if (manifest) {
-      lines.push(`export const manifest = ${jsonParseExpression(manifest)};`);
-    }
+    lines.push(`import ${JSON.stringify(genPath)};`);
+  }
+  const hasTrie = !!trie;
+  const hasEntries = !!entries && entries.length > 0;
+  const preset = state.opts?.preset ?? "node";
+  const override = process.env.RANGO_MANIFEST_TEXT;
+  const payload = manifestPayload(trie, hasTrie, entries, hasEntries);
+  const payloadJson = hasTrie || hasEntries ? JSON.stringify(payload) : "";
+  const useTextModule = state.isBuildMode && preset === "cloudflare" && override !== "0" && (hasTrie || hasEntries) && (override === "1" || payloadJson.length >= MANIFEST_EXTERNALIZE_THRESHOLD);
+  if (useTextModule) {
+    const dir = join6(state.projectRoot, "node_modules", ".rango");
+    mkdirSync2(dir, { recursive: true });
+    const safeId = `${routerId.replace(/[^a-zA-Z0-9_-]/g, "_")}-${shortHash(routerId)}`;
+    const filePath = join6(dir, `manifest-${safeId}.txt`).replaceAll("\\", "/");
+    writeFileSync5(filePath, payloadJson);
+    lines.push(`import __manifestJson from ${JSON.stringify(filePath)};`);
+    lines.push(`const __manifestData = JSON.parse(__manifestJson);`);
+    emitManifestExports(lines, hasTrie, hasEntries);
+    return lines.join("\n");
   }
-  if (trie) {
+  if (hasTrie) {
     lines.push(`export const trie = ${jsonParseExpression(trie)};`);
   }
-  if (entries && entries.length > 0) {
+  if (hasEntries) {
     lines.push(
       `export const precomputedEntries = ${jsonParseExpression(entries)};`
     );
   }
   return lines.join("\n") || "";
 }
+function manifestPayload(trie, hasTrie, entries, hasEntries) {
+  const payload = {};
+  if (hasTrie) payload.t = trie;
+  if (hasEntries) payload.p = entries;
+  return payload;
+}
+function emitManifestExports(lines, hasTrie, hasEntries) {
+  if (hasTrie) lines.push(`export const trie = __manifestData.t;`);
+  if (hasEntries)
+    lines.push(`export const precomputedEntries = __manifestData.p;`);
+}
 
 // src/vite/discovery/bundle-postprocess.ts
-import { resolve as resolve9 } from "node:path";
-import { readFileSync as readFileSync5, writeFileSync as writeFileSync4, existsSync as existsSync7 } from "node:fs";
+import { resolve as resolve10 } from "node:path";
+import { readFileSync as readFileSync6, writeFileSync as writeFileSync6, existsSync as existsSync8 } from "node:fs";
 function postprocessBundle(state) {
   const hasPrerenderData = state.prerenderManifestEntries && Object.keys(state.prerenderManifestEntries).length > 0;
   const hasStaticData = state.staticManifestEntries && Object.keys(state.staticManifestEntries).length > 0;
   if (!hasPrerenderData && !hasStaticData) return;
-  const rscEntryPath = resolve9(
+  const rscEntryPath = resolve10(
     state.projectRoot,
     "dist/rsc",
     state.rscEntryFileName ?? "index.js"
@@ -6457,9 +6876,9 @@ function postprocessBundle(state) {
   ];
   for (const target of evictionTargets) {
     for (const info of target.infos) {
-      const chunkPath = resolve9(state.projectRoot, "dist/rsc", info.fileName);
+      const chunkPath = resolve10(state.projectRoot, "dist/rsc", info.fileName);
       try {
-        const code = readFileSync5(chunkPath, "utf-8");
+        const code = readFileSync6(chunkPath, "utf-8");
         const result = evictHandlerCode(
           code,
           info.exports,
@@ -6467,7 +6886,7 @@ function postprocessBundle(state) {
           target.brand
         );
         if (result) {
-          writeFileSync4(chunkPath, result.code);
+          writeFileSync6(chunkPath, result.code);
           const savedKB = (result.savedBytes / 1024).toFixed(1);
           console.log(
             `[rango] Evicted ${target.label} (${savedKB} KB saved): ${info.fileName}`
@@ -6482,8 +6901,8 @@ function postprocessBundle(state) {
   }
   state.handlerChunkInfoMap.clear();
   state.staticHandlerChunkInfoMap.clear();
-  if (hasPrerenderData && existsSync7(rscEntryPath)) {
-    const rscCode = readFileSync5(rscEntryPath, "utf-8");
+  if (hasPrerenderData && existsSync8(rscEntryPath)) {
+    const rscCode = readFileSync6(rscEntryPath, "utf-8");
     if (!rscCode.includes("__prerender-manifest.js")) {
       try {
         let totalBytes = copyStagedBuildAssets(
@@ -6502,15 +6921,15 @@ function postprocessBundle(state) {
           `export default m;`,
           ""
         ].join("\n");
-        const manifestPath = resolve9(
+        const manifestPath = resolve10(
           state.projectRoot,
           "dist/rsc/__prerender-manifest.js"
         );
-        writeFileSync4(manifestPath, manifestCode);
+        writeFileSync6(manifestPath, manifestCode);
         totalBytes += Buffer.byteLength(manifestCode);
         const injection = `globalThis.__loadPrerenderManifestModule = () => import("./__prerender-manifest.js");
 `;
-        writeFileSync4(rscEntryPath, injection + rscCode);
+        writeFileSync6(rscEntryPath, injection + rscCode);
         const totalKB = (totalBytes / 1024).toFixed(1);
         console.log(
           `[rango] Wrote prerender assets (${totalKB} KB total, ${Object.keys(state.prerenderManifestEntries).length} entries)`
@@ -6522,8 +6941,8 @@ function postprocessBundle(state) {
       }
     }
   }
-  if (hasStaticData && existsSync7(rscEntryPath)) {
-    const rscCode = readFileSync5(rscEntryPath, "utf-8");
+  if (hasStaticData && existsSync8(rscEntryPath)) {
+    const rscCode = readFileSync6(rscEntryPath, "utf-8");
     if (!rscCode.includes("__static-manifest.js")) {
       try {
         const manifestEntries = [];
@@ -6540,15 +6959,15 @@ function postprocessBundle(state) {
         }
         const manifestCode = `const m={${manifestEntries.join(",")}};globalThis.__STATIC_MANIFEST=m;export default m;
 `;
-        const manifestPath = resolve9(
+        const manifestPath = resolve10(
           state.projectRoot,
           "dist/rsc/__static-manifest.js"
         );
-        writeFileSync4(manifestPath, manifestCode);
+        writeFileSync6(manifestPath, manifestCode);
         totalBytes += Buffer.byteLength(manifestCode);
         const injection = `import "./__static-manifest.js";
 `;
-        writeFileSync4(rscEntryPath, injection + rscCode);
+        writeFileSync6(rscEntryPath, injection + rscCode);
         const totalKB = (totalBytes / 1024).toFixed(1);
         console.log(
           `[rango] Wrote static assets (${totalKB} KB total, ${Object.keys(state.staticManifestEntries).length} entries)`
@@ -6563,7 +6982,7 @@ function postprocessBundle(state) {
 }
 
 // src/vite/discovery/gate-state.ts
-function createDiscoveryGate(s, debug11) {
+function createDiscoveryGate(s, debug12) {
   let gatePending = false;
   let gateResolver = () => {
   };
@@ -6572,15 +6991,15 @@ function createDiscoveryGate(s, debug11) {
   let pendingEvents = false;
   const beginGate = () => {
     if (gatePending) return;
-    s.discoveryDone = new Promise((resolve12) => {
-      gateResolver = resolve12;
+    s.discoveryDone = new Promise((resolve13) => {
+      gateResolver = resolve13;
     });
     gatePending = true;
   };
   const resolveGate = () => {
     if (!gatePending) return;
     if (inProgress || queued || pendingEvents) {
-      debug11?.(
+      debug12?.(
         "hmr: resolveGate deferred \u2014 work in flight (inProgress=%s queued=%s pendingEvents=%s)",
         inProgress,
         queued,
@@ -6589,7 +7008,7 @@ function createDiscoveryGate(s, debug11) {
       return;
     }
     gatePending = false;
-    debug11?.("hmr: discoveryDone resolved");
+    debug12?.("hmr: discoveryDone resolved");
     gateResolver();
   };
   const noteRouteEvent = () => {
@@ -6599,7 +7018,7 @@ function createDiscoveryGate(s, debug11) {
   const runRefreshCycle = async (work) => {
     if (inProgress) {
       queued = true;
-      debug11?.("hmr: rediscovery in flight \u2014 queued for a follow-up cycle");
+      debug12?.("hmr: rediscovery in flight \u2014 queued for a follow-up cycle");
       return;
     }
     pendingEvents = false;
@@ -6610,16 +7029,16 @@ function createDiscoveryGate(s, debug11) {
       inProgress = false;
       if (queued) {
         queued = false;
-        debug11?.("hmr: consuming queued rediscovery");
+        debug12?.("hmr: consuming queued rediscovery");
         runRefreshCycle(work).catch((err) => {
-          debug11?.(
+          debug12?.(
             "hmr: queued cycle rejected \u2014 releasing gate (%s)",
             err instanceof Error ? err.message : String(err)
           );
           resolveGate();
         });
       } else if (pendingEvents) {
-        debug11?.(
+        debug12?.(
           "hmr: holding gate for pending events (debounce not yet fired)"
         );
       } else {
@@ -6665,15 +7084,15 @@ function selectForwardableResolvePlugins(plugins) {
 }
 function pickForwardedRunnerConfig(config) {
   const r = config.resolve ?? {};
-  const resolve12 = {};
-  if (r.alias !== void 0) resolve12.alias = r.alias;
-  if (r.dedupe !== void 0) resolve12.dedupe = r.dedupe;
-  if (r.conditions !== void 0) resolve12.conditions = r.conditions;
-  if (r.mainFields !== void 0) resolve12.mainFields = r.mainFields;
-  if (r.extensions !== void 0) resolve12.extensions = r.extensions;
+  const resolve13 = {};
+  if (r.alias !== void 0) resolve13.alias = r.alias;
+  if (r.dedupe !== void 0) resolve13.dedupe = r.dedupe;
+  if (r.conditions !== void 0) resolve13.conditions = r.conditions;
+  if (r.mainFields !== void 0) resolve13.mainFields = r.mainFields;
+  if (r.extensions !== void 0) resolve13.extensions = r.extensions;
   if (r.preserveSymlinks !== void 0)
-    resolve12.preserveSymlinks = r.preserveSymlinks;
-  if (r.tsconfigPaths !== void 0) resolve12.tsconfigPaths = r.tsconfigPaths;
+    resolve13.preserveSymlinks = r.preserveSymlinks;
+  if (r.tsconfigPaths !== void 0) resolve13.tsconfigPaths = r.tsconfigPaths;
   const userOxc = config.oxc;
   const userJsx = userOxc && typeof userOxc === "object" && typeof userOxc.jsx === "object" && userOxc.jsx !== null ? userOxc.jsx : {};
   const oxc = userOxc && typeof userOxc === "object" ? {
@@ -6681,13 +7100,14 @@ function pickForwardedRunnerConfig(config) {
     jsx: { ...userJsx, runtime: "automatic", importSource: "react" }
   } : { jsx: { runtime: "automatic", importSource: "react" } };
   return {
-    resolve: resolve12,
+    resolve: resolve13,
     define: config.define,
     oxc
   };
 }
 
 // src/vite/router-discovery.ts
+init_debug();
 var debugDiscovery = createRangoDebugger(NS.discovery);
 var debugRoutes = createRangoDebugger(NS.routes);
 var debugBuild = createRangoDebugger(NS.build);
@@ -6706,6 +7126,7 @@ function ensureCloudflareProtocolLoaderRegistered() {
     );
   }
 }
+var injectedShellNotReadyPaths = /* @__PURE__ */ new Set();
 async function createTempRscServer(state, options = {}) {
   ensureCloudflareProtocolLoaderRegistered();
   const { default: rsc } = await import("@vitejs/plugin-rsc");
@@ -6737,6 +7158,20 @@ async function createTempRscServer(state, options = {}) {
       // hashClientRefs only in build mode — production bundles need hashed refs
       ...options.forceBuild ? [hashClientRefs(state.projectRoot)] : [],
       createVersionPlugin(),
+      // Before the stub plugin, so "virtual:entry-ssr" resolves to the real
+      // SSR entry when the shell endpoint needs it (see the option doc).
+      ...options.realSsrEntry ? [
+        {
+          name: "@rangojs/router:temp-real-ssr-entry",
+          enforce: "pre",
+          resolveId(id) {
+            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;
+          }
+        }
+      ] : [],
       createVirtualStubPlugin(),
       createCloudflareProtocolStubPlugin(),
       // Dev prerender must use dev-mode IDs (path-based) to match the workerd
@@ -6760,7 +7195,7 @@ async function resolveBuildEnv(option, factoryCtx) {
     }
     try {
       const userRequire = createRequire3(
-        resolve10(factoryCtx.root, "package.json")
+        resolve11(factoryCtx.root, "package.json")
       );
       const wranglerPath = userRequire.resolve("wrangler");
       const { getPlatformProxy } = await import(pathToFileURL2(wranglerPath).href);
@@ -6797,6 +7232,12 @@ async function acquireBuildEnv(s, command, mode) {
   globalThis[BUILD_ENV_GLOBAL_KEY] = result.env;
   return true;
 }
+function resetPrerenderCollection(s) {
+  s.prerenderManifestEntries = null;
+  s.staticManifestEntries = null;
+  s.shellCandidates = null;
+  s.prerenderPayloadValues = null;
+}
 async function releaseBuildEnv(s) {
   if (s.buildEnvDispose) {
     try {
@@ -6861,8 +7302,8 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
       s.devServer = server;
       server.middlewares.use(internalDebugNoCacheMiddleware());
       let resolveDiscovery;
-      const discoveryPromise = new Promise((resolve12) => {
-        resolveDiscovery = resolve12;
+      const discoveryPromise = new Promise((resolve13) => {
+        resolveDiscovery = resolve13;
       });
       const gate = createDiscoveryGate(s, debugDiscovery);
       const beginDiscoveryGate = gate.beginGate;
@@ -6918,14 +7359,14 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
               debugDiscovery?.(
                 "getOrCreateTempServer: cached temp runner reused"
               );
-              return existingEnv;
+              return { env: existingEnv, error: null };
             }
             debugDiscovery?.(
               "getOrCreateTempServer: server alive but registry missing \u2014 re-importing"
             );
             try {
               await importEntryAndRegistry(existingEnv);
-              return existingEnv;
+              return { env: existingEnv, error: null };
             } catch (err) {
               debugDiscovery?.(
                 "getOrCreateTempServer: reuse import failed (%s) \u2014 closing orphan and creating fresh",
@@ -6950,19 +7391,25 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
           "getOrCreateTempServer: creating new temp server, entry=%s",
           s.resolvedEntryPath ?? "(unset)"
         );
+        let createError = null;
         try {
           prerenderTempServer = await createTempRscServer(s, {
-            cacheDir: "node_modules/.vite_prerender"
+            cacheDir: "node_modules/.vite_prerender",
+            // The dev /__rsc_shell endpoint drives captureShellHTML in this
+            // server's SSR realm; the entry is only imported when a shell
+            // capture runs, so discovery cost is unchanged.
+            realSsrEntry: true
           });
           const tempRscEnv = prerenderTempServer.environments?.rsc;
           if (tempRscEnv?.runner) {
             await importEntryAndRegistry(tempRscEnv);
-            return tempRscEnv;
+            return { env: tempRscEnv, error: null };
           }
           debugDiscovery?.(
             "getOrCreateTempServer: tempRscEnv.runner unavailable"
           );
         } catch (err) {
+          createError = err;
           debugDiscovery?.(
             "getOrCreateTempServer: FAILED message=%s",
             err.message
@@ -6973,7 +7420,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
         });
         prerenderTempServer = null;
         prerenderNodeRegistry = null;
-        return null;
+        return { env: null, error: createError };
       }
       async function clearTempRegistries(tempRscEnv) {
         try {
@@ -6997,7 +7444,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
         }
       }
       async function refreshTempRscEnv() {
-        let tempRscEnv = await getOrCreateTempServer();
+        const tempRscEnv = (await getOrCreateTempServer()).env;
         if (!tempRscEnv) return null;
         const envGraph = tempRscEnv.moduleGraph;
         const serverGraph = prerenderTempServer?.moduleGraph;
@@ -7012,7 +7459,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
             prerenderTempServer = null;
             prerenderNodeRegistry = null;
           }
-          return await getOrCreateTempServer();
+          return (await getOrCreateTempServer()).env;
         }
         debugDiscovery?.(
           "refreshTempRscEnv: invalidating module graph (%s)",
@@ -7050,11 +7497,11 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
               "acquireBuildEnv",
               () => acquireBuildEnv(s, viteCommand, viteMode)
             );
-            tempRscEnv = await timed(
+            tempRscEnv = (await timed(
               debugDiscovery,
               "getOrCreateTempServer",
               () => getOrCreateTempServer()
-            );
+            )).env;
             if (tempRscEnv) {
               optimizerHashBefore2 = tempRscEnv.depsOptimizer?.metadata?.browserHash;
               await timed(
@@ -7199,7 +7646,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
           registry = mainRegistry;
         }
         if (!registry) {
-          const tempRscEnv = await getOrCreateTempServer();
+          const tempRscEnv = (await getOrCreateTempServer()).env;
           if (tempRscEnv) {
             try {
               await importEntryAndRegistry(tempRscEnv);
@@ -7284,6 +7731,194 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
         res.end("No prerender match");
         logResult(404, "no match");
       });
+      server.middlewares.use("/__rsc_shell", async (req, res) => {
+        await s.discoveryDone;
+        const url = new URL(req.url ?? "", "http://localhost");
+        const pathname = url.searchParams.get("pathname");
+        const routeName = url.searchParams.get("routeName");
+        const version = url.searchParams.get("version");
+        const ttlRaw = url.searchParams.get("ttl");
+        if (!pathname || !routeName || !version || !ttlRaw) {
+          res.statusCode = 400;
+          res.end("Missing pathname/routeName/version/ttl");
+          return;
+        }
+        const sendNotReady = (detail) => {
+          res.statusCode = 503;
+          res.setHeader("x-rango-shell-dev", "NOT-READY");
+          res.end(detail);
+        };
+        const isReoptimizing = (err) => err?.code === "ERR_OUTDATED_OPTIMIZED_DEP" || /Outdated Optimize Dep|optimized dependency|new dependencies optimized/i.test(
+          String(err?.message ?? "")
+        );
+        const handledAsReoptimizing = (err) => {
+          if (!isReoptimizing(err)) return false;
+          sendNotReady(`Shell capture re-optimizing: ${err.message}`);
+          return true;
+        };
+        const handleShellImportError = (err) => {
+          if (handledAsReoptimizing(err)) return;
+          res.statusCode = 500;
+          res.end(`Shell capture module refresh failed: ${err.message}`);
+        };
+        if (process.env.RANGO_E2E_INJECT_SHELL_NOTREADY === "1" && !injectedShellNotReadyPaths.has(pathname)) {
+          injectedShellNotReadyPaths.add(pathname);
+          const injected = Object.assign(
+            new Error("Outdated Optimize Dep (injected boot-race)"),
+            { code: "ERR_OUTDATED_OPTIMIZED_DEP" }
+          );
+          if (handledAsReoptimizing(injected)) return;
+        }
+        const ttl = Number(ttlRaw);
+        const swrRaw = url.searchParams.get("swr");
+        const swr = swrRaw === null ? void 0 : Number(swrRaw);
+        const tagsRaw = url.searchParams.get("tags");
+        const tags = tagsRaw ? tagsRaw.split(",") : void 0;
+        const maxSnapshotBytesRaw = url.searchParams.get("maxSnapshotBytes");
+        const maxSnapshotBytes = maxSnapshotBytesRaw === null ? void 0 : Number(maxSnapshotBytesRaw);
+        const captureTimeout = normalizeCaptureTimeout(
+          Number(url.searchParams.get("captureTimeout"))
+        );
+        const rscEnvMain = server.environments?.rsc;
+        let rscRealm = null;
+        let ssrRealm = null;
+        let ssrEntryId;
+        let tempServerError = null;
+        if (rscEnvMain?.runner && s.resolvedEntryPath) {
+          try {
+            await rscEnvMain.runner.import(s.resolvedEntryPath);
+          } catch (err) {
+            handleShellImportError(err);
+            return;
+          }
+          rscRealm = rscEnvMain;
+          ssrRealm = server.environments?.ssr;
+          ssrEntryId = server.environments?.ssr?.config?.build?.rollupOptions?.input?.index ?? VIRTUAL_IDS.ssr;
+        } else {
+          const tempResult = await getOrCreateTempServer();
+          if (tempResult.env) {
+            try {
+              await importEntryAndRegistry(tempResult.env);
+            } catch (err) {
+              handleShellImportError(err);
+              return;
+            }
+          } else {
+            tempServerError = tempResult.error;
+          }
+          rscRealm = tempResult.env;
+          ssrRealm = prerenderTempServer?.environments?.ssr;
+          ssrEntryId = "virtual:entry-ssr";
+        }
+        if (!rscRealm?.runner || !ssrRealm?.runner) {
+          if (tempServerError && handledAsReoptimizing(tempServerError)) return;
+          res.statusCode = 503;
+          res.end("Shell capture runners not available");
+          return;
+        }
+        let registry = null;
+        let registryError = null;
+        try {
+          const serverMod = await rscRealm.runner.import(
+            "@rangojs/router/server"
+          );
+          registry = serverMod.RouterRegistry ?? null;
+        } catch (err) {
+          registryError = err;
+          registry = null;
+        }
+        if (!registry || registry.size === 0) {
+          if (registryError && handledAsReoptimizing(registryError)) return;
+          res.statusCode = 503;
+          res.end("Shell capture registry not available");
+          return;
+        }
+        const cacheKey = `shell|${pathname}|r=${routeName}|t=${ttl}|s=${swr ?? ""}|g=${(tags ?? []).join("+")}|c=${captureTimeout ?? ""}|v=${version}`;
+        for (const [, routerInstance] of registry) {
+          if (typeof routerInstance.match !== "function") continue;
+          const cached = devPrerenderCache.get(routerInstance, cacheKey);
+          if (cached !== void 0) {
+            res.setHeader("content-type", "application/json");
+            res.setHeader("x-rango-shell-dev", "HIT");
+            res.end(cached);
+            return;
+          }
+        }
+        if (s.devServerOrigin) {
+          try {
+            const probe = await fetch(
+              `${s.devServerOrigin}/__rsc_prerender?pathname=${encodeURIComponent(pathname)}&routeName=${encodeURIComponent(routeName)}`,
+              { signal: AbortSignal.timeout(DEV_SHELL_PROBE_TIMEOUT_MS) }
+            );
+            if (!probe.ok) {
+              res.statusCode = 404;
+              res.end("Route is not prerenderable");
+              return;
+            }
+          } catch {
+            res.statusCode = 404;
+            res.end("Prerender pre-flight failed");
+            return;
+          }
+        }
+        for (const [, routerInstance] of registry) {
+          if (typeof routerInstance.match !== "function") continue;
+          try {
+            const ssrModule = await ssrRealm.runner.import(ssrEntryId);
+            if (typeof ssrModule?.captureShellHTML !== "function") {
+              res.statusCode = 404;
+              res.end("SSR entry has no captureShellHTML");
+              return;
+            }
+            const captureMod = await rscRealm.runner.import(
+              "@rangojs/router/build/shell-capture"
+            );
+            const result = await captureMod.captureShellForBuild({
+              router: routerInstance,
+              urlPath: pathname,
+              routeName,
+              key: `${pathname}:shell`,
+              ttl,
+              swr,
+              tags,
+              maxSnapshotBytes,
+              captureTimeout,
+              buildEnv: s.resolvedBuildEnv,
+              buildVersion: version,
+              captureShellHTML: ssrModule.captureShellHTML,
+              debug: !!debugDiscovery
+            });
+            if (result.outcome === "route-mismatch") continue;
+            if (result.outcome !== "stored" || !result.entry) {
+              res.statusCode = 404;
+              res.end(`Shell capture ${result.outcome}`);
+              return;
+            }
+            const body = JSON.stringify({
+              entry: result.entry,
+              ttl,
+              swr,
+              tags: result.tags,
+              routeName
+            });
+            devPrerenderCache.set(routerInstance, cacheKey, body);
+            res.setHeader("content-type", "application/json");
+            res.setHeader("x-rango-shell-dev", "MISS");
+            res.end(body);
+            return;
+          } catch (err) {
+            if (handledAsReoptimizing(err)) return;
+            console.warn(
+              `[rango] Dev shell capture error for ${pathname} (route keeps runtime capture): ${err.message}`
+            );
+            res.statusCode = 404;
+            res.end(`Shell capture error: ${err.message}`);
+            return;
+          }
+        }
+        res.statusCode = 404;
+        res.end("No router matched");
+      });
       if (opts?.staticRouteTypesGeneration !== false) {
         const isGeneratedRouteFile = (filePath) => filePath.endsWith(".gen.ts") && (filePath.includes("named-routes.gen.ts") || filePath.includes("urls.gen.ts"));
         const regenerateGeneratedRouteFiles = () => {
@@ -7453,7 +8088,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
           }
           const inRecoveryMode = !!s.lastDiscoveryError;
           try {
-            const source = readFileSync6(filePath, "utf-8");
+            const source = readFileSync7(filePath, "utf-8");
             const trimmed = source.trimStart();
             const isUseClient = trimmed.startsWith('"use client"') || trimmed.startsWith("'use client'");
             if (!inRecoveryMode && isUseClient) return;
@@ -7484,7 +8119,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
             if (hasCreateRouter) {
               const nestedRouterConflict = findNestedRouterConflict([
                 ...s.cachedRouterFiles ?? [],
-                resolve10(filePath)
+                resolve11(filePath)
               ]);
               if (nestedRouterConflict) {
                 server.config.logger.error(
@@ -7534,8 +8169,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
       const buildStartTime = performance.now();
       debugDiscovery?.("build: start (env=%s)", this.environment?.name ?? "?");
       resetStagedBuildAssets(s.projectRoot);
-      s.prerenderManifestEntries = null;
-      s.staticManifestEntries = null;
+      resetPrerenderCollection(s);
       await timed(
         debugDiscovery,
         "build acquireBuildEnv",
@@ -7590,20 +8224,59 @@ ${details}`,
         );
       } finally {
         delete globalThis.__rscRouterDiscoveryActive;
-        if (tempServer) {
-          await timed(
-            debugDiscovery,
-            "build tempServer.close",
-            () => tempServer.close()
-          );
+        if (tempServer && s.shellCandidates?.length) {
+          s.shellPhaseTempServer = tempServer;
+        } else {
+          if (tempServer) {
+            await timed(
+              debugDiscovery,
+              "build tempServer.close",
+              () => tempServer.close()
+            );
+          }
+          await releaseBuildEnv(s);
         }
-        await releaseBuildEnv(s);
         debugDiscovery?.(
           "build discovery done (%sms)",
           (performance.now() - buildStartTime).toFixed(1)
         );
       }
     },
+    // Post-build PPR shell capture (producer B, #699): runs after EVERY
+    // environment bundle is written — the shell prelude embeds built client
+    // asset URLs (bootstrap entry), which do not exist at buildStart. The
+    // kept temp server and the buildEnv were deferred AS A PAIR in
+    // buildStart's finally; this finally is the pair's success-path owner
+    // (buildEnd below owns the aborted-build path) — the phase itself is a
+    // pure producer and tears down only the globals it installs.
+    buildApp: {
+      order: "post",
+      async handler(builder) {
+        try {
+          await runShellPrerenderPhase(s, builder);
+        } finally {
+          if (s.isBuildMode) {
+            const tempServer = s.shellPhaseTempServer;
+            s.shellPhaseTempServer = null;
+            if (tempServer) await tempServer.close();
+            await releaseBuildEnv(s);
+          }
+        }
+      }
+    },
+    // An environment build failure aborts the builder before the buildApp
+    // post hook — never leak the kept temp server (open handles hang the CLI)
+    // or the deferred buildEnv (a live miniflare proxy).
+    async buildEnd(error) {
+      if (!error || !s.shellPhaseTempServer) return;
+      const tempServer = s.shellPhaseTempServer;
+      s.shellPhaseTempServer = null;
+      try {
+        await tempServer.close();
+      } finally {
+        await releaseBuildEnv(s);
+      }
+    },
     // Suppress vite's HMR cascade for our own gen-file writes.
     //
     // After every cf HMR cycle, refreshTempRscEnv → writeRouteTypesFiles
@@ -7768,7 +8441,9 @@ ${details}`,
 }
 
 // src/vite/rango.ts
+init_debug();
 var debugConfig = createRangoDebugger(NS.config);
+var SERVER_BUILD_TARGET = "esnext";
 async function rango(options) {
   const rangoStart = performance.now();
   const resolvedOptions = options ?? { preset: "node" };
@@ -7893,7 +8568,11 @@ async function rango(options) {
         }
       }
     });
-    plugins.push(createVirtualEntriesPlugin(finalEntries));
+    plugins.push(
+      createVirtualEntriesPlugin(finalEntries, void 0, {
+        headScripts: resolvedOptions.headScripts
+      })
+    );
     plugins.push(performanceTracksPlugin());
     plugins.push(
       rsc({
@@ -7908,14 +8587,14 @@ async function rango(options) {
       name: "@rangojs/router:auto-discover",
       config(userConfig) {
         if (routerRef.path) return;
-        const root = userConfig.root ? resolve11(process.cwd(), userConfig.root) : process.cwd();
+        const root = userConfig.root ? resolve12(process.cwd(), userConfig.root) : process.cwd();
         const toRootRelative = (abs) => (abs.startsWith(root) ? "./" + abs.slice(root.length + 1) : abs).replaceAll("\\", "/");
         const bulletList = (files) => files.map((f) => "  - " + toRootRelative(f)).join("\n");
         if (explicitHostRouter) {
           routerRef.path = normalizeHostRouterEntry(
             explicitHostRouter,
             root,
-            existsSync8
+            existsSync9
           );
           routerRef.kind = "host";
           return;
@@ -8012,6 +8691,9 @@ If this is a multi-app host router, export a createHostRouter() instance and set
             },
             ssr: {
               ...vercelServerEnv ?? {},
+              build: {
+                target: SERVER_BUILD_TARGET
+              },
               optimizeDeps: {
                 entries: [VIRTUAL_IDS.ssr],
                 include: [
@@ -8031,6 +8713,9 @@ If this is a multi-app host router, export a createHostRouter() instance and set
             },
             rsc: {
               ...vercelServerEnv ?? {},
+              build: {
+                target: SERVER_BUILD_TARGET
+              },
               optimizeDeps: {
                 entries: [VIRTUAL_IDS.rsc],
                 include: [
@@ -8073,7 +8758,11 @@ If this is a multi-app host router, export a createHostRouter() instance and set
         }
       }
     });
-    plugins.push(createVirtualEntriesPlugin(finalEntries, routerRef));
+    plugins.push(
+      createVirtualEntriesPlugin(finalEntries, routerRef, {
+        headScripts: resolvedOptions.headScripts
+      })
+    );
     plugins.push(performanceTracksPlugin());
     plugins.push(
       rsc({
@@ -8092,7 +8781,7 @@ If this is a multi-app host router, export a createHostRouter() instance and set
       if (!file.endsWith(".tsx") && !file.endsWith(".ts") && !file.endsWith(".jsx") && !file.endsWith(".js"))
         return;
       try {
-        const source = readFileSync7(file, "utf-8");
+        const source = readFileSync8(file, "utf-8");
         if (hasUseClientDirective(source)) {
           return [];
         }
@@ -8119,7 +8808,8 @@ If this is a multi-app host router, export a createHostRouter() instance and set
       preset,
       prerenderOnError: options?.prerender?.onError,
       discovery: options?.discovery,
-      clientChunkCtx
+      clientChunkCtx,
+      headScripts: resolvedOptions.headScripts
     })
   );
   if (preset === "vercel") {
@@ -8143,7 +8833,7 @@ function poke() {
     apply: "serve",
     configureServer(server) {
       const stdin = process.stdin;
-      const debug11 = process.env.RANGO_POKE_DEBUG === "1";
+      const debug12 = process.env.RANGO_POKE_DEBUG === "1";
       const triggerReload = (source) => {
         server.hot.send({ type: "full-reload", path: "*" });
         server.config.logger.info(`  browser reload (${source})`, {
@@ -8176,7 +8866,7 @@ function poke() {
         lines.pop();
         return lines;
       };
-      if (debug11) {
+      if (debug12) {
         server.config.logger.info(
           `  poke debug enabled (isTTY=${stdin.isTTY ? "yes" : "no"}, isRaw=${stdin.isTTY ? stdin.isRaw ? "yes" : "no" : "n/a"})`,
           { timestamp: true }
@@ -8189,7 +8879,7 @@ function poke() {
         );
       }
       const onData = (data) => {
-        if (debug11) {
+        if (debug12) {
           server.config.logger.info(`  poke stdin ${formatChunk(data)}`, {
             timestamp: true
           });