@rangojs/router 0.0.0-experimental.140 → 0.0.0-experimental.142

package/src/vite/discovery/dev-prerender-cache.ts

@@ -0,0 +1,117 @@
+/**
+ * Dev prerender result cache — memoizes /__rsc_prerender responses between
+ * HMR edits (issue #654).
+ *
+ * Freshness invariant (why identity keying is correct): the endpoint
+ * re-imports the user's entry module through a Vite module runner on every
+ * request. When ANY module in the entry → router → urls → handler chain was
+ * invalidated (file edit propagates up the importer graph), that import
+ * re-executes the entry, `createRouter()` re-runs, and `RouterRegistry.set`
+ * (router.ts) replaces the router instance with a NEW object. When nothing
+ * was invalidated, the import is a module-cache hit and the instance is the
+ * SAME object. Router-instance identity therefore IS the HMR generation:
+ * keying the cache on it gives "serve cached until an edit invalidates the
+ * chain" without any watcher bookkeeping, and the WeakMap lets every stale
+ * generation's bucket be garbage-collected the moment the registry drops
+ * the old instance.
+ *
+ * Staleness envelope: a cached body can only go stale through NON-module
+ * inputs (a getParams() reading a database, fs content outside the module
+ * graph). Production freezes those at build time, so serving them frozen
+ * between edits makes dev MORE faithful to production, not less — the
+ * pre-#654 behavior of re-rendering per request was the anomaly.
+ */
+
+import type { SerializedSegmentData } from "../../cache/types.js";
+
+/** Structural slice of `matchForPrerender`'s result the payload derivation needs. */
+export interface DevPrerenderMatchPayloadSource {
+  segments: SerializedSegmentData[];
+  handles: string;
+  interceptSegments?: SerializedSegmentData[];
+  interceptHandles?: string;
+}
+
+/** Serialized response bodies for the two endpoint variants of one render. */
+export interface DevPrerenderPayloadBodies {
+  /** `intercept != 1` response: the route's own segments + handles. */
+  main: string;
+  /**
+   * `intercept=1` response: main + intercept segments with the MERGED handle
+   * string. Falls back to `main` byte-for-byte when the route has no
+   * intercept segments — mirroring the endpoint's historical behavior.
+   */
+  intercept: string;
+}
+
+export interface DevPrerenderCache {
+  get(router: object, key: string): string | undefined;
+  set(router: object, key: string, body: string): void;
+}
+
+/**
+ * Derive both variant bodies from one matchForPrerender result, so a single
+ * render warms the main AND intercept cache keys (matchForPrerender computes
+ * intercept segments unconditionally either way — see prerender-match.ts
+ * step 14).
+ */
+export function payloadBodiesFromResult(
+  result: DevPrerenderMatchPayloadSource,
+): DevPrerenderPayloadBodies {
+  const main = JSON.stringify({
+    segments: result.segments,
+    handles: result.handles,
+  });
+  const intercept = result.interceptSegments?.length
+    ? JSON.stringify({
+        segments: [...result.segments, ...result.interceptSegments],
+        handles: result.interceptHandles ?? "",
+      })
+    : main;
+  return { main, intercept };
+}
+
+/**
+ * Cache key for one endpoint request shape. `pathname` and `routeName` come
+ * straight from the query; `passthrough` selects the getParams-checked match
+ * path; `intercept` selects which variant body is served. All four dimensions
+ * change the response, so all four are in the key.
+ */
+export function devPrerenderCacheKey(
+  pathname: string,
+  opts: { intercept: boolean; passthrough: boolean; routeName: string | null },
+): string {
+  return `${pathname}|i=${opts.intercept ? 1 : 0}|p=${opts.passthrough ? 1 : 0}|r=${opts.routeName ?? ""}`;
+}
+
+/**
+ * Per-router FIFO cap: a dev session that visits an unbounded set of
+ * prerendered pathnames (e.g. crawling param routes) must not grow one
+ * bucket without limit. 500 rendered payloads is far beyond any interactive
+ * session; eviction order does not matter for correctness (a miss just
+ * re-renders).
+ */
+const MAX_ENTRIES_PER_ROUTER = 500;
+
+export function createDevPrerenderCache(
+  maxEntriesPerRouter: number = MAX_ENTRIES_PER_ROUTER,
+): DevPrerenderCache {
+  const buckets = new WeakMap<object, Map<string, string>>();
+  return {
+    get(router: object, key: string): string | undefined {
+      return buckets.get(router)?.get(key);
+    },
+    set(router: object, key: string, body: string): void {
+      let bucket = buckets.get(router);
+      if (!bucket) {
+        bucket = new Map();
+        buckets.set(router, bucket);
+      }
+      if (!bucket.has(key) && bucket.size >= maxEntriesPerRouter) {
+        const oldest = bucket.keys().next().value;
+        if (oldest !== undefined) bucket.delete(oldest);
+      }
+      bucket.set(key, body);
+    },
+  };
+}

package/src/vite/router-discovery.ts

@@ -44,6 +44,11 @@ import {
 } from "./discovery/self-gen-tracking.js";
 import { discoverRouters } from "./discovery/discover-routers.js";
 import { describeDiscoveryFailure } from "./discovery/discovery-errors.js";
+import {
+  createDevPrerenderCache,
+  devPrerenderCacheKey,
+  payloadBodiesFromResult,
+} from "./discovery/dev-prerender-cache.js";
 import {
   writeCombinedRouteTypesWithTracking,
   writeRouteTypesFiles,
@@ -828,6 +833,15 @@ export function createRouterDiscoveryPlugin(
       // Registry from the main server's RSC environment (populated by discoverRouters)
       let mainRegistry: Map<string, any> | null = null;
 
+      // Memoized /__rsc_prerender render results, keyed by router-instance
+      // identity (#654). The per-request entry re-import below is what makes
+      // identity a valid freshness key: an HMR-invalidated chain re-runs
+      // createRouter() and replaces the registry instance, so cached bodies
+      // for the old instance become unreachable; an untouched chain returns
+      // the same instance and the cached body is byte-identical to a fresh
+      // render. See dev-prerender-cache.ts for the full invariant.
+      const devPrerenderCache = createDevPrerenderCache();
+
       // Push discovery state (manifest, trie, precomputed entries) to the
       // server module so runtime request handling uses the current routes.
       // Shared by initial discovery and HMR-triggered re-discovery.
@@ -918,9 +932,28 @@ export function createRouterDiscoveryPlugin(
 
         if (!registry) {
           // No main registry: the RSC env has no module runner (Cloudflare dev).
-          // Lazily create a Node.js temp server for prerender evaluation.
-          if (!prerenderNodeRegistry) {
-            await getOrCreateTempServer();
+          // Lazily create a Node.js temp server for prerender evaluation, and
+          // re-import the entry through it on EVERY request — the temp server
+          // has its own file watcher, so a handler-only edit (a file without
+          // urls()/createRouter() that the main watcher's route-file sniff
+          // ignores) invalidates its module graph; the re-import re-evaluates
+          // exactly the dirty subgraph and re-registers fresh router
+          // instances. Before #654 the cached registry was only refreshed on
+          // route-file edits, so handler-only edits served stale prerender
+          // content on this path. Warm-cache re-imports are module-cache hits.
+          const tempRscEnv = await getOrCreateTempServer();
+          if (tempRscEnv) {
+            try {
+              await importEntryAndRegistry(tempRscEnv);
+            } catch (err: any) {
+              console.warn(
+                `[rango] Dev prerender module refresh failed: ${err.message}`,
+              );
+              res.statusCode = 500;
+              res.end(`Prerender handler error: ${err.message}`);
+              logResult(500, "temp module refresh failed");
+              return;
+            }
           }
           registry = prerenderNodeRegistry;
         }
@@ -936,8 +969,38 @@ export function createRouterDiscoveryPlugin(
         const wantRouteName = url.searchParams.get("routeName");
         const wantPassthrough = url.searchParams.get("passthrough") === "1";
 
+        // One render warms BOTH variant keys (matchForPrerender computes the
+        // intercept segments unconditionally), so a route's main and modal
+        // variants cost a single render per HMR generation.
+        const variantDims = {
+          passthrough: wantPassthrough,
+          routeName: wantRouteName,
+        };
+        const keyMain = devPrerenderCacheKey(pathname, {
+          intercept: false,
+          ...variantDims,
+        });
+        const keyIntercept = devPrerenderCacheKey(pathname, {
+          intercept: true,
+          ...variantDims,
+        });
+        const requestedKey = wantIntercept ? keyIntercept : keyMain;
+
         for (const [, routerInstance] of registry) {
           if (!routerInstance.matchForPrerender) continue;
+          // Cache is consulted per router IN LOOP ORDER so multi-router
+          // fall-through semantics are identical to the uncached path: a
+          // router that never produced a payload for this key still runs
+          // its matchForPrerender (cheap trie miss / intentionally-uncached
+          // error retry) before the next router is considered.
+          const cached = devPrerenderCache.get(routerInstance, requestedKey);
+          if (cached !== undefined) {
+            res.setHeader("content-type", "application/json");
+            res.setHeader("x-rango-prerender-cache", "HIT");
+            res.end(cached);
+            logResult(200, "cache hit");
+            return;
+          }
           try {
             const result = await routerInstance.matchForPrerender(
               pathname,
@@ -953,19 +1016,19 @@ export function createRouterDiscoveryPlugin(
             // This prevents returning the wrong entry when multiple routers
             // have prerenderable routes sharing the same pathname.
             if (wantRouteName && result.routeName !== wantRouteName) continue;
+            // Pre-encoded MERGED handle string in the intercept body comes
+            // from the producer (handles are Flight-encoded so
+            // Promise/ReactNode values survive the wire).
+            const bodies = payloadBodiesFromResult(result);
+            devPrerenderCache.set(routerInstance, keyMain, bodies.main);
+            devPrerenderCache.set(
+              routerInstance,
+              keyIntercept,
+              bodies.intercept,
+            );
             res.setHeader("content-type", "application/json");
-            let payload: Record<string, unknown>;
-            if (wantIntercept && result.interceptSegments?.length) {
-              payload = {
-                segments: [...result.segments, ...result.interceptSegments],
-                // Pre-encoded MERGED handle string from the producer (handles are
-                // Flight-encoded so Promise/ReactNode values survive the wire).
-                handles: result.interceptHandles ?? "",
-              };
-            } else {
-              payload = { segments: result.segments, handles: result.handles };
-            }
-            res.end(JSON.stringify(payload));
+            res.setHeader("x-rango-prerender-cache", "MISS");
+            res.end(wantIntercept ? bodies.intercept : bodies.main);
             logResult(200, `match ${result.routeName}`);
             return;
           } catch (err: any) {

package/src/cache/shell-cache.ts

@@ -1,386 +0,0 @@
-/**
- * PPR Shell Cache Middleware
- *
- * Axis 2 of the two-axis render model (see docs/design/ppr-shell-resume.md).
- * Opt-in middleware that caches the rendered HTML *shell* (React's `prelude`
- * plus the `postponed` state from a static `prerender` abort) and, on a later
- * request, serves those bytes immediately and resumes fizz for just the live
- * holes. The browser sees one ordinary streamed document.
- *
- * The middleware owns only the cheap URL/method gating and the stream
- * composition. The RENDER layer (rsc-rendering, integrated by a later stage) is
- * the final authority on whether a resume actually happens: it reads
- * requestCtx._shellResume, calls the resume strategy, and marks the response
- * with the internal `x-rango-shell-resumed` header ONLY when it truly resumed.
- * This middleware composes the cached prelude in front of the live response ONLY
- * when that marker is present; everything else (redirects, 404s, error renders,
- * nonce/allReady bypasses) flows through untouched — every non-resumed path
- * fails open to axis 1.
- *
- * Flow (the middleware calls next() EXACTLY ONCE on every path — the executor's
- * per-entry next() is a single-use latch, so a second call throws):
- * 1. Bypass matrix (non-GET, _rsc_* params, RSC request, skipPaths, isEnabled,
- *    store lacks the shell family) → plain next(), axis 1.
- * 2. getShell(key) HIT + reactVersion matches → arm _shellResume, await next()
- *    once. On a stale (SWR) hit, ALSO set the _shellCapture descriptor before
- *    that same next() so the render layer schedules a background recapture.
- *    - marker present → strip it, prepend prelude bytes, x-rango-shell: HIT.
- *    - marker absent → render layer did not resume; return untouched.
- * 3. MISS (or reactVersion mismatch) → set the _shellCapture descriptor before
- *    the single next(), stream the live response to the user with
- *    x-rango-shell: MISS. The render layer reads the descriptor after building the
- *    response and schedules a BACKGROUND capture (via router.match under a derived
- *    context — NOT a second next()); see rsc-rendering.ts + shell-capture.ts.
- * The descriptor is cleared in a finally so it never leaks into a reused ctx.
- */
-
-import React from "react";
-import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
-import {
-  getRequestContext,
-  type RequestContext,
-} from "../server/request-context.js";
-import { mayNeedSSR } from "../rsc/ssr-setup.js";
-import type { SegmentCacheStore } from "./types.js";
-import { sortedSearchString } from "./cache-key-utils.js";
-import { reportCacheError } from "./cache-error.js";
-
-/** Debug/status header the browser (and e2e assertions) can read: HIT | MISS. */
-const SHELL_STATUS_HEADER = "x-rango-shell";
-
-/**
- * Internal marker the render layer sets on the live response when — and only
- * when — it actually resumed a cached shell. The middleware composes the prelude
- * in front of the body iff this header is present, then strips it before the
- * response leaves. It is the whole handshake between the middleware (which arms
- * _shellResume optimistically) and the render layer (the final authority).
- */
-const SHELL_RESUMED_MARKER_HEADER = "x-rango-shell-resumed";
-
-/**
- * React version captured at prerender time is the invalidation gate: a stored
- * shell whose reactVersion differs from the running React cannot be resumed (the
- * postponed blob is build-coupled), so it is treated as a miss. Read once at
- * module load — React.version is stable for the process lifetime.
- */
-const REACT_VERSION = React.version;
-
-/** Decode a base64 prelude back into bytes for stream composition. */
-function base64ToBytes(b64: string): Uint8Array {
-  const binary = atob(b64);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
-  return bytes;
-}
-
-/**
- * Compose the served response: prelude bytes first, then the live (resumed) body.
- * React relies on HTML-parser foster-parenting for content streamed after the
- * prelude's closing `</body></html>`, so plain byte concatenation is the correct
- * composition (POC item 6) — do not try to reopen or splice the document.
- *
- * Status and headers come from the LIVE next() response: Set-Cookie and friends
- * are per-request and belong to the live pass, not the frozen shell. The internal
- * marker is stripped and x-rango-shell: HIT is added.
- */
-function composeShellResponse(
-  response: Response,
-  preludeBase64: string,
-): Response {
-  const preludeBytes = base64ToBytes(preludeBase64);
-  const body = response.body;
-  const composed = new ReadableStream<Uint8Array>({
-    async start(controller) {
-      controller.enqueue(preludeBytes);
-      if (body) {
-        const reader = body.getReader();
-        try {
-          for (;;) {
-            const { done, value } = await reader.read();
-            if (done) break;
-            controller.enqueue(value);
-          }
-        } finally {
-          reader.releaseLock();
-        }
-      }
-      controller.close();
-    },
-    cancel(reason) {
-      // Propagate downstream cancellation to the live body so it does not leak.
-      return body?.cancel(reason);
-    },
-  });
-
-  const headers = new Headers(response.headers);
-  headers.delete(SHELL_RESUMED_MARKER_HEADER);
-  headers.set(SHELL_STATUS_HEADER, "HIT");
-  return new Response(composed, {
-    status: response.status,
-    statusText: response.statusText,
-    headers,
-  });
-}
-
-/** Clone a response with the x-rango-shell status header added. */
-function withShellStatus(response: Response, status: "HIT" | "MISS"): Response {
-  const headers = new Headers(response.headers);
-  headers.set(SHELL_STATUS_HEADER, status);
-  return new Response(response.body, {
-    status: response.status,
-    statusText: response.statusText,
-    headers,
-  });
-}
-
-/**
- * Options for the PPR shell-cache middleware.
- */
-export interface ShellCacheOptions<TEnv = any> {
-  /**
-   * Cache store to use. Defaults to the request context's `_cacheStore`
-   * (the app-level store wired via the router's cache config).
-   */
-  store?: SegmentCacheStore<TEnv>;
-
-  /**
-   * Shell time-to-live in seconds. Defaults to 300.
-   */
-  ttlSeconds?: number;
-
-  /**
-   * Stale-while-revalidate window in seconds. On a stale hit the cached shell is
-   * still served and a background recapture is scheduled.
-   */
-  swrSeconds?: number;
-
-  /**
-   * Custom cache key generator. Receives the cleaned request URL. The middleware
-   * appends its own `:shell` namespace suffix, so the returned key never collides
-   * with a document-cache key.
-   *
-   * A custom generator owns the FULL key identity, including host scoping: the
-   * default key incorporates `url.host` so shells can never leak across tenants
-   * in multi-host deployments — include it in custom keys too unless the store
-   * is provably single-host.
-   */
-  keyGenerator?: (url: URL) => string;
-
-  /**
-   * Callback to decide whether shell caching is enabled for this request.
-   * Return false to fall through to a normal HTML render (axis 1).
-   */
-  isEnabled?: (ctx: MiddlewareContext<TEnv>) => boolean | Promise<boolean>;
-
-  /**
-   * Skip shell caching for specific path prefixes (e.g. admin, API routes).
-   */
-  skipPaths?: string[];
-
-  /**
-   * Enable debug logging for shell cache operations (HIT / MISS / CAPTURED).
-   * Defaults to false.
-   */
-  debug?: boolean;
-}
-
-/**
- * Create the PPR shell-cache middleware.
- *
- * Add it to a router (or a route subtree) to cache the HTML shell and resume
- * fizz for just the live holes on subsequent requests. Personalization must live
- * in loaders/holes — the shell is shared per URL key (the shell-manifest
- * pattern). Actions, progressive enhancement, formState, and per-request nonce
- * always take axis 1.
- *
- * @example
- * ```typescript
- * const router = createRouter<AppEnv>()
- *   .use(createShellCacheMiddleware({ ttlSeconds: 600, swrSeconds: 60 }))
- *   .route("home", (ctx) => <HomePage />);
- * ```
- */
-export function createShellCacheMiddleware<TEnv = any>(
-  options: ShellCacheOptions<TEnv> = {},
-): MiddlewareFn<TEnv> {
-  const {
-    ttlSeconds = 300,
-    swrSeconds,
-    keyGenerator,
-    isEnabled,
-    skipPaths = [],
-    debug = false,
-  } = options;
-
-  const log = debug ? (message: string) => console.log(message) : () => {};
-
-  return async function shellCacheMiddleware(
-    ctx: MiddlewareContext<TEnv>,
-    next: () => Promise<Response>,
-  ): Promise<Response> {
-    const url = ctx.url;
-    // ctx.url is stripped of _rsc_* params by the pipeline (stripInternalParams);
-    // read the raw request URL for internal-param detection, like document-cache.
-    const rawUrl = new URL(ctx.request.url);
-
-    // --- Bypass matrix (each bypass = plain next(), axis 1) ---
-
-    // Mutations are dynamic — never resume/capture a shell for them.
-    if (ctx.request.method !== "GET") return next();
-    // RSC action / loader / partial requests are not HTML document requests.
-    if (rawUrl.searchParams.has("_rsc_action")) return next();
-    if (rawUrl.searchParams.has("_rsc_loader")) return next();
-    if (rawUrl.searchParams.has("_rsc_partial")) return next();
-    // RSC (Flight) request — the Flight path is untouched by PPR.
-    if (!mayNeedSSR(ctx.request, rawUrl)) return next();
-    // Consumer opt-outs.
-    if (skipPaths.some((path) => url.pathname.startsWith(path))) return next();
-    if (isEnabled) {
-      const enabled = await isEnabled(ctx);
-      if (!enabled) return next();
-    }
-
-    const requestCtx = getRequestContext();
-    const store = options.store ?? requestCtx?._cacheStore;
-
-    // Store must implement the shell family — otherwise fail open to axis 1.
-    if (!store?.getShell || !store?.putShell) return next();
-
-    // Track whether next() has been called so the catch block knows whether it is
-    // safe to fall through to the handler (mirrors document-cache). cacheKey is
-    // assigned inside the try (a throwing keyGenerator must degrade, not 500).
-    let handlerCalled = false;
-    let cacheKey = "";
-
-    /**
-     * Build the "capture wanted" descriptor. Set on the request context BEFORE
-     * the single next() so the render layer can read it after building the
-     * response and schedule the background capture (via router.match under a
-     * derived context — NOT a second next()). `store` is the SAME store this
-     * middleware resolved for getShell, so a store-attached middleware writes
-     * captures where it reads them. `tags` is intentionally omitted: the capture
-     * collects the shell's own non-loader tags from its derived render.
-     */
-    const captureDescriptor = (): NonNullable<
-      RequestContext["_shellCapture"]
-    > => ({
-      key: cacheKey,
-      ttl: ttlSeconds,
-      swr: swrSeconds,
-      store,
-    });
-
-    try {
-      // Namespace the key with a `:shell` suffix (mirrors document-cache's
-      // `:html`/`:rsc` suffix) so it can never collide with a document-cache key;
-      // the store further isolates the shell family internally. Built inside the
-      // try so a throwing keyGenerator degrades to a full render, not a 500.
-      //
-      // The default key includes the request HOST: in a multi-tenant host-router
-      // deployment (one worker, one shared KV/runtime-cache store) a host-less
-      // key would serve tenant A's captured shell to tenant B's users. The CF
-      // document family fixed this exact class at the store tier (toDocKVHost);
-      // the shell family fixes it at the key tier so every store is safe.
-      let searchSuffix = "";
-      if (!keyGenerator) {
-        const sorted = sortedSearchString(url.searchParams);
-        if (sorted) searchSuffix = `?${sorted}`;
-      }
-      cacheKey = keyGenerator
-        ? `${keyGenerator(url)}:shell`
-        : `${url.host}${url.pathname}${searchSuffix}:shell`;
-
-      const cached = await store.getShell(cacheKey);
-      const validHit =
-        cached != null && cached.entry.reactVersion === REACT_VERSION;
-
-      if (cached && !validHit) {
-        // reactVersion mismatch: the postponed blob is build-coupled and cannot
-        // be resumed by the running React. There is no deleteShell primitive in
-        // v1, so we simply treat it as a MISS — the recapture below overwrites
-        // the same key, and the entry otherwise ages out via TTL.
-        log(
-          `[ShellCache] MISS ${url.pathname} (reactVersion ${cached.entry.reactVersion} != ${REACT_VERSION})`,
-        );
-      }
-
-      if (validHit) {
-        // Arm the resume optimistically. The render layer is the final authority
-        // (nonce/formState/allReady bypass); it engages resume and marks the
-        // response only when it actually resumed.
-        if (requestCtx) {
-          requestCtx._shellResume = { postponed: cached!.entry.postponed };
-          // SWR: on a stale hit, also request a background recapture by setting
-          // the descriptor before this single next(). Resume (foreground) and
-          // capture-request (background) legitimately coexist now — the render
-          // layer schedules the recapture off the descriptor after building the
-          // resumed response. A fresh hit leaves the descriptor unset.
-          if (cached!.shouldRevalidate) {
-            requestCtx._shellCapture = captureDescriptor();
-          }
-        }
-        handlerCalled = true;
-        let response: Response;
-        try {
-          response = await next();
-        } finally {
-          // Always disarm both single-request flags. A next() throw here (resume
-          // failure) propagates to the outer catch and rethrows; the
-          // version-keyed entry self-heals via axis 1 + recapture on the next
-          // request (v1 has no deleteShell to eagerly remove it).
-          if (requestCtx) {
-            requestCtx._shellResume = undefined;
-            requestCtx._shellCapture = undefined;
-          }
-        }
-
-        if (response.headers.has(SHELL_RESUMED_MARKER_HEADER)) {
-          log(`[ShellCache] HIT ${url.pathname}`);
-          return composeShellResponse(response, cached!.entry.prelude);
-        }
-
-        // Marker absent: the render layer did NOT resume (redirect, 404, error
-        // render, per-request nonce, or allReady buffering). Fail open to axis 1
-        // — return the live response untouched. Note: no manual onResponse-
-        // callback drain is needed here (or on any path in this middleware),
-        // because every path runs a full next() pipeline pass, which already
-        // drains those callbacks — unlike document-cache, which serves a fully
-        // cached response bypassing next() and must drain them itself.
-        log(`[ShellCache] PASS ${url.pathname} (resume not engaged)`);
-        return response;
-      }
-
-      // --- MISS (no entry, or reactVersion mismatch) ---
-      // Set the "capture wanted" descriptor before the single next(). The render
-      // layer reads it after building the response and, if the response is a
-      // servable 200 HTML document, schedules a BACKGROUND capture (router.match
-      // under a derived context — never a second next()). The descriptor's mere
-      // presence does not change the foreground render (loader masking keys off
-      // _shellCaptureRun, which only the background derived context sets).
-      if (requestCtx) requestCtx._shellCapture = captureDescriptor();
-      handlerCalled = true;
-      let response: Response;
-      try {
-        response = await next();
-      } finally {
-        // Clear the descriptor so it never leaks into a reused ctx. The render
-        // layer already read it (synchronously, inside next()) and captured its
-        // own reference for the background task, so clearing here is safe.
-        if (requestCtx) requestCtx._shellCapture = undefined;
-      }
-
-      log(`[ShellCache] MISS ${url.pathname}`);
-      return withShellStatus(response, "MISS");
-    } catch (error) {
-      reportCacheError(error, "cache-read", "[ShellCache] middleware");
-      if (handlerCalled) {
-        // Post-handler failure (resume/render throw, or a stream error): do not
-        // call next() again — that would re-run handler side effects.
-        throw error;
-      }
-      // Pre-handler failure (cache lookup / key generation): degrade to a full
-      // render.
-      return next();
-    }
-  };
-}