@rangojs/router 0.0.0-experimental.146 → 0.0.0-experimental.148

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) {
@@ -2410,7 +2520,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.146",
+  version: "0.0.0-experimental.148",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -2538,6 +2648,11 @@ var package_default = {
       types: "./src/build/index.ts",
       import: "./src/build/index.ts"
     },
+    "./build/shell-capture": {
+      types: "./src/prerender/build-shell-capture.ts",
+      "react-server": "./src/prerender/build-shell-capture.ts",
+      import: "./src/prerender/build-shell-capture.ts"
+    },
     "./host": {
       types: "./src/host/index.ts",
       "react-server": "./src/host/index.ts",
@@ -3849,6 +3964,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;
@@ -3939,6 +4061,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*[;,])/;
@@ -4121,75 +4244,9 @@ 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);
-}
-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
+init_debug();
+init_client_ref_hashing();
 var debugChunks = createRangoDebugger(NS.chunks);
 function isSharedRuntime(meta) {
   return [meta.id, meta.normalizedId].some(
@@ -4545,6 +4602,7 @@ function createVersionInjectorPlugin(rscEntryPath) {
 }
 
 // src/vite/plugins/cjs-to-esm.ts
+init_debug();
 var debug8 = createRangoDebugger(NS.transform);
 function createCjsToEsmPlugin() {
   let isProduction = false;
@@ -4608,11 +4666,18 @@ 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";
+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;
@@ -4773,6 +4838,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;
@@ -4877,6 +4945,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,
@@ -5459,18 +5530,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");
@@ -5486,6 +5563,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;
@@ -5693,6 +5771,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({
@@ -5943,6 +6033,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;
@@ -6163,11 +6255,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({
@@ -6206,8 +6573,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)) {
@@ -6218,10 +6585,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) {
@@ -6236,10 +6603,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}`
@@ -6320,7 +6687,7 @@ function supplementGenFilesWithRuntimeRoutes(state) {
 }
 
 // src/vite/discovery/virtual-module-codegen.ts
-import { dirname as dirname4, basename, join as join5 } from "node:path";
+import { dirname as dirname4, basename, join as join6 } from "node:path";
 function generateRoutesManifestModule(state) {
   const hasManifest = state.mergedRouteManifest && Object.keys(state.mergedRouteManifest).length > 0;
   if (hasManifest) {
@@ -6335,7 +6702,7 @@ function generateRoutesManifestModule(state) {
           /\.(tsx?|jsx?)$/,
           ""
         );
-        const genPath = join5(
+        const genPath = join6(
           routerDir,
           `${routerBasename}.named-routes.gen.js`
         ).replaceAll("\\", "/");
@@ -6420,7 +6787,7 @@ function generatePerRouterModule(state, routerId) {
       /\.(tsx?|jsx?)$/,
       ""
     );
-    const genPath = join5(
+    const genPath = join6(
       routerDir,
       `${routerBasename}.named-routes.gen.js`
     ).replaceAll("\\", "/");
@@ -6447,13 +6814,13 @@ function generatePerRouterModule(state, routerId) {
 }
 
 // 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 writeFileSync5, 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"
@@ -6474,9 +6841,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,
@@ -6484,7 +6851,7 @@ function postprocessBundle(state) {
           target.brand
         );
         if (result) {
-          writeFileSync4(chunkPath, result.code);
+          writeFileSync5(chunkPath, result.code);
           const savedKB = (result.savedBytes / 1024).toFixed(1);
           console.log(
             `[rango] Evicted ${target.label} (${savedKB} KB saved): ${info.fileName}`
@@ -6499,8 +6866,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(
@@ -6519,15 +6886,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);
+        writeFileSync5(manifestPath, manifestCode);
         totalBytes += Buffer.byteLength(manifestCode);
         const injection = `globalThis.__loadPrerenderManifestModule = () => import("./__prerender-manifest.js");
 `;
-        writeFileSync4(rscEntryPath, injection + rscCode);
+        writeFileSync5(rscEntryPath, injection + rscCode);
         const totalKB = (totalBytes / 1024).toFixed(1);
         console.log(
           `[rango] Wrote prerender assets (${totalKB} KB total, ${Object.keys(state.prerenderManifestEntries).length} entries)`
@@ -6539,8 +6906,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 = [];
@@ -6557,15 +6924,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);
+        writeFileSync5(manifestPath, manifestCode);
         totalBytes += Buffer.byteLength(manifestCode);
         const injection = `import "./__static-manifest.js";
 `;
-        writeFileSync4(rscEntryPath, injection + rscCode);
+        writeFileSync5(rscEntryPath, injection + rscCode);
         const totalKB = (totalBytes / 1024).toFixed(1);
         console.log(
           `[rango] Wrote static assets (${totalKB} KB total, ${Object.keys(state.staticManifestEntries).length} entries)`
@@ -6580,7 +6947,7 @@ function postprocessBundle(state) {
 }
 
 // src/vite/discovery/gate-state.ts
-function createDiscoveryGate(s, debug11) {
+function createDiscoveryGate(s, debug12) {
   let gatePending = false;
   let gateResolver = () => {
   };
@@ -6589,15 +6956,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,
@@ -6606,7 +6973,7 @@ function createDiscoveryGate(s, debug11) {
       return;
     }
     gatePending = false;
-    debug11?.("hmr: discoveryDone resolved");
+    debug12?.("hmr: discoveryDone resolved");
     gateResolver();
   };
   const noteRouteEvent = () => {
@@ -6616,7 +6983,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;
@@ -6627,16 +6994,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 {
@@ -6682,15 +7049,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" ? {
@@ -6698,13 +7065,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);
@@ -6754,6 +7122,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
@@ -6777,7 +7159,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);
@@ -6814,6 +7196,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 {
@@ -6878,8 +7266,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;
@@ -6969,7 +7357,11 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
         );
         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) {
@@ -7301,6 +7693,162 @@ 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 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;
+        if (rscEnvMain?.runner && s.resolvedEntryPath) {
+          try {
+            await rscEnvMain.runner.import(s.resolvedEntryPath);
+          } catch (err) {
+            res.statusCode = 500;
+            res.end(`Shell capture module refresh failed: ${err.message}`);
+            return;
+          }
+          rscRealm = rscEnvMain;
+          ssrRealm = server.environments?.ssr;
+          ssrEntryId = server.environments?.ssr?.config?.build?.rollupOptions?.input?.index ?? VIRTUAL_IDS.ssr;
+        } else {
+          const tempRscEnv = await getOrCreateTempServer();
+          if (tempRscEnv) {
+            try {
+              await importEntryAndRegistry(tempRscEnv);
+            } catch (err) {
+              res.statusCode = 500;
+              res.end(`Shell capture module refresh failed: ${err.message}`);
+              return;
+            }
+          }
+          rscRealm = tempRscEnv;
+          ssrRealm = prerenderTempServer?.environments?.ssr;
+          ssrEntryId = "virtual:entry-ssr";
+        }
+        if (!rscRealm?.runner || !ssrRealm?.runner) {
+          res.statusCode = 503;
+          res.end("Shell capture runners not available");
+          return;
+        }
+        let registry = null;
+        try {
+          const serverMod = await rscRealm.runner.import(
+            "@rangojs/router/server"
+          );
+          registry = serverMod.RouterRegistry ?? null;
+        } catch {
+          registry = null;
+        }
+        if (!registry || registry.size === 0) {
+          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) {
+            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 = () => {
@@ -7470,7 +8018,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;
@@ -7501,7 +8049,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
             if (hasCreateRouter) {
               const nestedRouterConflict = findNestedRouterConflict([
                 ...s.cachedRouterFiles ?? [],
-                resolve10(filePath)
+                resolve11(filePath)
               ]);
               if (nestedRouterConflict) {
                 server.config.logger.error(
@@ -7551,8 +8099,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",
@@ -7607,20 +8154,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
@@ -7785,6 +8371,7 @@ ${details}`,
 }
 
 // src/vite/rango.ts
+init_debug();
 var debugConfig = createRangoDebugger(NS.config);
 async function rango(options) {
   const rangoStart = performance.now();
@@ -7929,14 +8516,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;
@@ -8117,7 +8704,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 [];
         }
@@ -8144,7 +8731,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") {
@@ -8168,7 +8756,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})`, {
@@ -8201,7 +8789,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 }
@@ -8214,7 +8802,7 @@ function poke() {
         );
       }
       const onData = (data) => {
-        if (debug11) {
+        if (debug12) {
           server.config.logger.info(`  poke stdin ${formatChunk(data)}`, {
             timestamp: true
           });