@rangojs/router 0.0.0-experimental.150 → 0.0.0-experimental.151

package/dist/vite/index.js

@@ -2520,7 +2520,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.150",
+  version: "0.0.0-experimental.151",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -2768,7 +2768,7 @@ var package_default = {
     }
   },
   engines: {
-    node: "^20.19.0 || >=22.12.0"
+    node: ">=24.0.0"
   }
 };
 
@@ -5140,10 +5140,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];
@@ -5153,7 +5152,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 } : {},
@@ -5186,8 +5184,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 = {};
@@ -5199,7 +5196,6 @@ function buildPerRouterTrie(manifest) {
   }
   return buildRouteTrie(
     manifest.routeManifest,
-    ancestry,
     routeToStaticPrefix,
     manifest.routeTrailingSlash,
     manifest.prerenderRoutes ? new Set(manifest.prerenderRoutes) : void 0,
@@ -6114,7 +6110,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 = [];
@@ -6177,9 +6172,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);
     }
@@ -6214,49 +6206,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?.(
@@ -6702,7 +6691,9 @@ function supplementGenFilesWithRuntimeRoutes(state) {
 }
 
 // src/vite/discovery/virtual-module-codegen.ts
+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) {
@@ -6791,6 +6782,14 @@ 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 trie = state.perRouterTrieMap.get(routerId);
@@ -6817,20 +6816,49 @@ function generatePerRouterModule(state, routerId) {
       lines.push(`export const manifest = ${jsonParseExpression(manifest)};`);
     }
   }
-  if (trie) {
+  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 (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 resolve10 } from "node:path";
-import { readFileSync as readFileSync6, writeFileSync as writeFileSync5, existsSync as existsSync8 } from "node:fs";
+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;
@@ -6866,7 +6894,7 @@ function postprocessBundle(state) {
           target.brand
         );
         if (result) {
-          writeFileSync5(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}`
@@ -6905,11 +6933,11 @@ function postprocessBundle(state) {
           state.projectRoot,
           "dist/rsc/__prerender-manifest.js"
         );
-        writeFileSync5(manifestPath, manifestCode);
+        writeFileSync6(manifestPath, manifestCode);
         totalBytes += Buffer.byteLength(manifestCode);
         const injection = `globalThis.__loadPrerenderManifestModule = () => import("./__prerender-manifest.js");
 `;
-        writeFileSync5(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)`
@@ -6943,11 +6971,11 @@ function postprocessBundle(state) {
           state.projectRoot,
           "dist/rsc/__static-manifest.js"
         );
-        writeFileSync5(manifestPath, manifestCode);
+        writeFileSync6(manifestPath, manifestCode);
         totalBytes += Buffer.byteLength(manifestCode);
         const injection = `import "./__static-manifest.js";
 `;
-        writeFileSync5(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)`
@@ -7106,6 +7134,7 @@ function ensureCloudflareProtocolLoaderRegistered() {
     );
   }
 }
+var injectedShellNotReadyPaths = /* @__PURE__ */ new Set();
 async function createTempRscServer(state, options = {}) {
   ensureCloudflareProtocolLoaderRegistered();
   const { default: rsc } = await import("@vitejs/plugin-rsc");
@@ -7338,14 +7367,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",
@@ -7370,6 +7399,7 @@ 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",
@@ -7381,12 +7411,13 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
           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
@@ -7397,7 +7428,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
         });
         prerenderTempServer = null;
         prerenderNodeRegistry = null;
-        return null;
+        return { env: null, error: createError };
       }
       async function clearTempRegistries(tempRscEnv) {
         try {
@@ -7421,7 +7452,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;
@@ -7436,7 +7467,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
             prerenderTempServer = null;
             prerenderNodeRegistry = null;
           }
-          return await getOrCreateTempServer();
+          return (await getOrCreateTempServer()).env;
         }
         debugDiscovery?.(
           "refreshTempRscEnv: invalidating module graph (%s)",
@@ -7474,11 +7505,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(
@@ -7623,7 +7654,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
           registry = mainRegistry;
         }
         if (!registry) {
-          const tempRscEnv = await getOrCreateTempServer();
+          const tempRscEnv = (await getOrCreateTempServer()).env;
           if (tempRscEnv) {
             try {
               await importEntryAndRegistry(tempRscEnv);
@@ -7720,6 +7751,32 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
           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);
@@ -7734,47 +7791,52 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
         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) {
-            res.statusCode = 500;
-            res.end(`Shell capture module refresh failed: ${err.message}`);
+            handleShellImportError(err);
             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) {
+          const tempResult = await getOrCreateTempServer();
+          if (tempResult.env) {
             try {
-              await importEntryAndRegistry(tempRscEnv);
+              await importEntryAndRegistry(tempResult.env);
             } catch (err) {
-              res.statusCode = 500;
-              res.end(`Shell capture module refresh failed: ${err.message}`);
+              handleShellImportError(err);
               return;
             }
+          } else {
+            tempServerError = tempResult.error;
           }
-          rscRealm = tempRscEnv;
+          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 {
+        } 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;
@@ -7853,6 +7915,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
             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}`
             );
@@ -8388,6 +8451,7 @@ ${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" };
@@ -8635,6 +8699,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: [
@@ -8654,6 +8721,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: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.150",
+  "version": "0.0.0-experimental.151",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -248,6 +248,6 @@
     }
   },
   "engines": {
-    "node": "^20.19.0 || >=22.12.0"
+    "node": ">=24.0.0"
   }
 }

package/skills/debug-manifest/SKILL.md

@@ -8,18 +8,10 @@ argument-hint:
 
 Inspect the route manifest to verify parent relationships, shortCodes, and route structure.
 
-## Quick Access
-
-In development, visit:
-
-```
-http://localhost:PORT/?__debug_manifest
-```
-
-Returns formatted JSON. The HTTP endpoint shape is `{ routerId, routeManifest, routeAncestry, routeTrie, precomputedEntries }` (see below for the programmatic API shape).
-
 ## Programmatic Access
 
+Call `router.debugManifest()` — an `async` method on the router instance:
+
 ```typescript
 import { router } from "./router.js";
 

package/skills/middleware/SKILL.md

@@ -197,6 +197,7 @@ export const myMiddleware: Middleware = async (ctx, next) => {
   ctx.request; // Request object
   ctx.url; // Parsed URL
   ctx.params; // Route parameters
+  ctx.build; // in middleware: true only during Prerender + ppr build-shell capture (plain Prerender does not run middleware)
 
   // Access platform bindings (plain bindings from createRouter<TEnv>())
   ctx.env.DB; // D1Database
@@ -205,6 +206,9 @@ export const myMiddleware: Middleware = async (ctx, next) => {
   // Set variables for downstream handlers (typed via Rango.Vars)
   ctx.set("user", { id: "123", name: "John" });
 
+  // Opt the current request out of PPR shell lookup/capture.
+  ctx.dynamic();
+
   // Continue to next middleware/handler
   await next();
 
@@ -246,6 +250,35 @@ This works alongside `ctx.get("key")` / `ctx.set("key", value)` (global typing
 via Rango.Vars augmentation). Use `createVar` for route-local or feature-scoped
 data; use Rango.Vars for app-wide middleware state.
 
+## Build-Time PPR Middleware
+
+Normal `Prerender` Flight payload collection does not run middleware: there is
+no request to wrap. The exception is `Prerender` + `ppr` build-shell capture.
+After the Flight payload exists, the shell producer replays global and route
+middleware for each generated URL before it captures HTML.
+
+In that build-shell pass:
+
+- `ctx.build === true`;
+- `ctx.waitUntil()` is inert;
+- `ctx.dynamic()` skips the baked shell for that URL;
+- context variables set by middleware are visible to the shell render.
+
+Use this to keep side effects predictable:
+
+```typescript
+export const commerceMiddleware: Middleware = async (ctx, next) => {
+  if (ctx.build) {
+    ctx.dynamic(); // leave this shell to runtime PPR
+    return next();
+  }
+
+  const session = await commerce.auth(ctx.request);
+  ctx.set("session", session);
+  return next();
+};
+```
+
 ## Redirect with State in Middleware
 
 ```typescript

package/skills/ppr/SKILL.md

@@ -21,11 +21,12 @@ shell is shared per host+URL, the holes are per request.
 
 - You want the WHOLE response frozen, loader output included — see
   `/document-cache`.
-- You want routes rendered at build time with `Static()`/`Prerender()` — the
-  `ppr` path option captures at runtime; see `/prerender`.
+- You want build-time Flight segment payloads from `Static()`/`Prerender()` —
+  see `/prerender`. A `Prerender` page may also declare `ppr`; then producer B
+  can bake the HTML shell at build time while loaders stay live.
 - You are unsure which cache layer you need — start at `/cache-guide`.
 
-## Setup: one path option, no middleware
+## Setup: one path option, no PPR middleware to mount
 
 PPR is a DOCUMENT-level property declared on the page route via the `ppr` path
 option. Serving is **integral to the router** — there is nothing to mount. The
@@ -169,6 +170,20 @@ On a document GET to a ppr route the router runs:
 point is after the chain, an unauthorized request NEVER sees shell bytes — put
 auth middleware anywhere (global or route DSL) and it guards PPR for free.
 
+### Opting out per request with `ctx.dynamic()`
+
+Middleware and handlers can call `ctx.dynamic()` to force this request back to
+axis 1. In middleware it runs before the PPR commit point, so the router skips
+shell lookup, HIT serving, and MISS capture for that request. In handlers it is
+too late to prevent a MISS render from already happening, but it still prevents
+the follow-up shell capture.
+
+During `Prerender` + `ppr` build-shell capture, middleware is replayed with
+`ctx.build === true`, `ctx.waitUntil()` inert, and the same `ctx.dynamic()`
+opt-out. Use that for routes where the shell depends on runtime-only auth,
+cookies, or side-effectful SDK calls. A skipped build shell can still be owned
+later by runtime capture when runtime middleware does not call `ctx.dynamic()`.
+
 ## Verifying it works
 
 The header exists on DOCUMENT responses only. A bare `curl` gets the HTML