@rangojs/router 0.20.0 → 0.22.0

package/src/router/prerender-match.ts

@@ -33,11 +33,22 @@ import type {
   SegmentHandleData,
 } from "../cache/types.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
+import type { RouterVersions } from "../router-versions.js";
+import type { OnDemandRouteConfig } from "../prerender/on-demand.js";
+import { isPrerenderPersonalizationError } from "../prerender/producer-guard.js";
+import { isDataNotFoundError } from "../errors.js";
 
 export interface PrerenderMatchDeps<TEnv = any> {
   /** Owning router id; scopes bake-time root-scope/search-schema lookups the
    *  same way reqCtx._routerId does at runtime (issue #762). */
   routerId?: string;
+  /**
+   * The owning router's cache versions. Set on the requestless on-demand
+   * producer's context as `_versions`, so cache stores built inside the render
+   * key under the router's pair like a live request does instead of the
+   * whole-build fallback (server/build-version-table.ts getCacheVersions).
+   */
+  versions?: RouterVersions;
   findMatch: (
     pathname: string,
   ) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
@@ -66,6 +77,14 @@ export async function matchForPrerender<TEnv = any>(
   buildEnv?: TEnv,
   /** Dev-only: check getParams() for passthrough routes to skip unknown params. */
   devMode?: boolean,
+  /**
+   * Requestless on-demand refresh (router.prerender()). Arms the personalization
+   * guard: cookies()/headers()/response mutations throw a
+   * PrerenderPersonalizationError so the caller maps a personalized render to
+   * skipped-personalized instead of baking a shared payload. `buildEnv` here is
+   * the live trigger env, not the shared build env.
+   */
+  onDemand?: boolean,
 ): Promise<{
   segments: SerializedSegmentData[];
   /** RSC-encoded handle map ("" when none) — see handle-snapshot.ts. Encoded in
@@ -79,6 +98,11 @@ export async function matchForPrerender<TEnv = any>(
    *  the sinks store it as-is (no longer merge raw records). */
   interceptHandles?: string;
   passthrough?: true;
+  /** On-demand only: the render hit `notFound()` and nothing else failed. */
+  notFound?: true;
+  /** Route-level onDemand config (ttl/tags) read off the route entry; only set
+   *  when `onDemand` and the route declared an onDemand object literal. */
+  onDemandConfig?: OnDemandRouteConfig;
   /**
    * The matched route entry's `ppr` path option, surfaced so the build
    * collection can flag Prerender+ppr routes as build-time shell candidates
@@ -109,383 +133,467 @@ export async function matchForPrerender<TEnv = any>(
     passthrough: true as const,
   });
 
-  return runWithRouterContext(routerCtx, async () => {
-    // 2. Load the manifest entry tree
-    const manifestEntry = await loadManifest(
-      matched.entry,
-      matched.routeKey,
-      pathname,
-      undefined,
-      false,
-    );
-
-    // 3. Build ancestor chain [root, ..., route]
-    const entries: EntryData[] = [];
-    for (const entry of traverseBack(manifestEntry)) {
-      entries.push(entry);
-    }
-
-    // 3b. Dev-mode passthrough shortcut: if the route is a Passthrough route
-    // and has getParams(), check if the matched params are in the known list.
-    // In production, only known params are pre-rendered; unknown params fall
-    // through to the live handler. Mirror that behavior in dev mode to avoid
-    // rendering unknown params with build: true.
-    // Vars collected from getParams() probe — merged into render context below.
-    let devProbeBuildVars: Record<string, any> | undefined;
-
-    if (devMode && matchedPassthroughRoute) {
-      const routeEntry = entries.find(
-        (
-          e,
-        ): e is EntryData & {
-          type: "route";
-          prerenderDef: { getParams: (ctx: any) => Promise<any[]> | any[] };
-        } =>
-          e.type === "route" &&
-          !!(e as any).isPassthrough &&
-          !!(e as any).prerenderDef?.getParams,
-      );
-      if (routeEntry) {
-        try {
-          const probeBuildVars: Record<string, any> = {};
-          const knownParamsList = await routeEntry.prerenderDef.getParams({
-            build: true as const,
-            dev: true,
-            set: ((keyOrVar: any, value: any) => {
-              contextSet(probeBuildVars, keyOrVar, value);
-            }) as any,
-            reverse: createReverseFunction(deps.mergedRouteMap),
-            get env() {
-              if (buildEnv !== undefined) return buildEnv;
-              throw new Error(
-                "[rango] ctx.env is not available during dev-mode getParams(). " +
-                  "Configure buildEnv in your rango() plugin options to enable build-time env access.",
-              );
-            },
-          });
-          // Compare only the keys returned by getParams — ignore mount params
-          // from include() prefixes that aren't part of the handler's params.
-          const isKnown = knownParamsList.some((known: Record<string, any>) => {
-            const knownKeys = Object.keys(known);
-            return knownKeys.every(
-              (k) => String(known[k]) === String(matchedParams[k]),
-            );
-          });
-          if (!isKnown) {
-            return passthroughResult();
-          }
-          // Preserve vars set by getParams() for the render context
-          if (hasContextVars(probeBuildVars)) {
-            devProbeBuildVars = probeBuildVars;
-          }
-        } catch (err: any) {
-          // Mirror production semantics (prerender-collection.ts):
-          // Skip errors are intentional — treat as passthrough.
-          // All other errors propagate so dev surfaces them.
-          if (err?.name === "Skip") {
-            return passthroughResult();
-          }
-          throw err;
-        }
-      }
-    }
+  // Set inside the render; out here for the notFound() outcome at the end.
+  let onDemandConfig: OnDemandRouteConfig | undefined;
 
-    // 4. Create handle store for collecting handle data
-    const handleStore = createHandleStore();
-
-    // 5. Create a minimal request context with the handle store
-    // Shallow-copy getParams vars so each param set is independent.
-    // In dev mode, merge vars from the getParams() probe if the caller
-    // didn't provide buildVars (production passes them from expandPrerenderRoutes).
-    const effectiveBuildVars = buildVars ?? devProbeBuildVars;
-    const variables: Record<string, any> = effectiveBuildVars
-      ? { ...effectiveBuildVars }
-      : {};
-    const stubRes = new Response(null, { status: 200 });
-    const minimalRequestContext: RequestContext<TEnv> = {
-      env: buildEnv ?? ({} as TEnv),
-      request: new Request("http://prerender" + pathname),
-      url: new URL("http://prerender" + pathname),
-      originalUrl: new URL("http://prerender" + pathname),
-      pathname,
-      searchParams: new URLSearchParams(),
-      _variables: variables,
-      build: true,
-      // Inert here: the prerender-collect / static-render pass has no live
-      // PPR-shell decision to gate; dynamic() reaches the shell axis only on a
-      // live request or a shell capture.
-      dynamic: () => {},
-      get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
-      set: ((keyOrVar: any, value: any) => {
-        contextSet(variables, keyOrVar, value);
-      }) as any,
-      params: matchedParams,
-      res: stubRes,
-      cookie: () => undefined,
-      cookies: () => ({}),
-      _readCookie: () => undefined,
-      _readCookies: () => ({}),
-      setCookie: () => {},
-      deleteCookie: () => {},
-      header: () => {},
-      setStatus: () => {},
-      _setStatus: () => {},
-      _rotateStateCookie: () => {},
-      _setKeepCacheDirective: () => {},
-      _setFreshReadsCookie: () => {},
-      use: (() => {
-        throw new Error("use() not available during pre-rendering");
-      }) as any,
-      method: "GET",
-      _handleStore: handleStore,
-      _requestTags: new Set<string>(),
-      waitUntil: () => {},
-      onResponse: () => {},
-      _onResponseCallbacks: [],
-      // No theme at build time: no request cookie.
-      _readTheme: () => undefined,
-      setLocationState() {},
-      _locationState: undefined,
-      _renderBarrier: Promise.resolve(),
-      _resolveRenderBarrier: () => {},
-      _reportedErrors: new WeakSet<object>(),
-      reverse: createReverseFunction(
-        deps.mergedRouteMap,
+  const rendered = runWithRouterContext(routerCtx, () =>
+    routerCtx.getContext().runIsolated(matched.routeKey, async () => {
+      // 2. Load the manifest entry tree
+      const manifestEntry = await loadManifest(
+        matched.entry,
         matched.routeKey,
-        matchedParams,
-        matched.routeKey
-          ? isRouteRootScoped(matched.routeKey, deps.routerId)
-          : undefined,
-      ),
-      // Scope the bake context's own lookups (createPrerenderContext reads it
-      // through the request ALS) per router as well.
-      _routerId: deps.routerId,
-    };
-
-    return runWithRequestContext(minimalRequestContext, async () => {
-      // 6. Create prerender context with synthetic URL.
-      // Prerender handlers get params, pathname, url, searchParams, search,
-      // reverse, use(handle), and optionally env (when buildEnv is configured).
-      const buildCtx = createPrerenderContext<TEnv>(
-        matchedParams,
         pathname,
-        deps.mergedRouteMap,
-        matched.routeKey,
-        variables,
-        matchedPassthroughRoute,
-        buildEnv,
-        devMode,
+        undefined,
+        false,
       );
 
-      // 7. Wire use() for handles only (loaders throw)
-      setupBuildUse(buildCtx);
+      // 3. Build ancestor chain [root, ..., route]
+      const entries: EntryData[] = [];
+      for (const entry of traverseBack(manifestEntry)) {
+        entries.push(entry);
+      }
 
-      // 8. Resolve all segments with skipLoaders
-      const loaderPromises = new Map<string, Promise<any>>();
-      const allSegments = await deps.resolveAllSegments(
-        entries,
-        matched.routeKey,
-        matchedParams,
-        buildCtx,
-        loaderPromises,
-        // throwOnError: a render failure (or `throw new Skip()`) must reach the
-        // build/dev caller, not be baked into a frozen error page (issue #587).
-        { skipLoaders: true, throwOnError: true },
-      );
+      // On-demand refresh: read the route's onDemand config (ttl/tags) off the
+      // retained route entry. `tags` is a function, so it can't ride the trie; the
+      // trigger resolves it from here. Only an object literal carries config;
+      // `onDemand: true` uses router-level defaults (config stays undefined).
+      if (onDemand) {
+        const routeEntry = entries.find(
+          (e) =>
+            e.type === "route" &&
+            !!(e as { prerenderDef?: unknown }).prerenderDef,
+        ) as
+          | { prerenderDef?: { options?: { onDemand?: unknown } } }
+          | undefined;
+        const od = routeEntry?.prerenderDef?.options?.onDemand;
+        if (od && typeof od === "object") {
+          onDemandConfig = od as OnDemandRouteConfig;
+        }
+      }
 
-      // 9. Detect passthrough sentinel: handler returned ctx.passthrough().
-      // When the route declares loading(), the handler result is deferred so the
-      // component is a thenable resolving to the sentinel — detectPrerenderPassthrough
-      // resolves thenables before testing (a sync check would miss it and bake a
-      // corrupt artifact).
-      if (await detectPrerenderPassthrough(allSegments)) {
-        return passthroughResult();
+      // 3b. Dev-mode passthrough shortcut: if the route is a Passthrough route
+      // and has getParams(), check if the matched params are in the known list.
+      // In production, only known params are pre-rendered; unknown params fall
+      // through to the live handler. Mirror that behavior in dev mode to avoid
+      // rendering unknown params with build: true.
+      // Vars collected from getParams() probe — merged into render context below.
+      let devProbeBuildVars: Record<string, any> | undefined;
+
+      // On-demand refresh renders exactly the requested param set, even one not
+      // returned by getParams() (that is the point of an explicit refresh), so the
+      // dev getParams() passthrough probe is skipped for onDemand.
+      if (devMode && matchedPassthroughRoute && !onDemand) {
+        const routeEntry = entries.find(
+          (
+            e,
+          ): e is EntryData & {
+            type: "route";
+            prerenderDef: { getParams: (ctx: any) => Promise<any[]> | any[] };
+          } =>
+            e.type === "route" &&
+            !!(e as any).isPassthrough &&
+            !!(e as any).prerenderDef?.getParams,
+        );
+        if (routeEntry) {
+          try {
+            const probeBuildVars: Record<string, any> = {};
+            const knownParamsList = await routeEntry.prerenderDef.getParams({
+              build: true as const,
+              dev: true,
+              set: ((keyOrVar: any, value: any) => {
+                contextSet(probeBuildVars, keyOrVar, value);
+              }) as any,
+              reverse: createReverseFunction(deps.mergedRouteMap),
+              get env() {
+                if (buildEnv !== undefined) return buildEnv;
+                throw new Error(
+                  "[rango] ctx.env is not available during dev-mode getParams(). " +
+                    "Configure buildEnv in your rango() plugin options to enable build-time env access.",
+                );
+              },
+            });
+            // Compare only the keys returned by getParams — ignore mount params
+            // from include() prefixes that aren't part of the handler's params.
+            const isKnown = knownParamsList.some(
+              (known: Record<string, any>) => {
+                const knownKeys = Object.keys(known);
+                return knownKeys.every(
+                  (k) => String(known[k]) === String(matchedParams[k]),
+                );
+              },
+            );
+            if (!isKnown) {
+              return passthroughResult();
+            }
+            // Preserve vars set by getParams() for the render context
+            if (hasContextVars(probeBuildVars)) {
+              devProbeBuildVars = probeBuildVars;
+            }
+          } catch (err: any) {
+            // Mirror production semantics (prerender-collection.ts):
+            // Skip errors are intentional — treat as passthrough.
+            // All other errors propagate so dev surfaces them.
+            if (err?.name === "Skip") {
+              return passthroughResult();
+            }
+            throw err;
+          }
+        }
       }
 
-      // 10. Filter out any loader segments (belt-and-suspenders)
-      const nonLoaderSegments = allSegments.filter((s) => s.type !== "loader");
-
-      // 11. Wait for handles to settle
-      handleStore.seal();
-      await handleStore.settled;
-
-      // 12. Serialize segments using the cache serializer
-      const { serializeSegments } = await import("../cache/segment-codec.js");
-      const { encodeHandles } = await import("../cache/handle-snapshot.js");
-      // Flight encodes a component that throws (an async server component in
-      // the tree) as an error row and completes normally. Rethrown below like
-      // a handler throw, so the caller's policy decides instead of baking the
-      // error (#914).
-      const flightErrors: unknown[] = [];
-      const onFlightError = (error: unknown): void => {
-        flightErrors.push(error);
+      // 4. Create handle store for collecting handle data
+      const handleStore = createHandleStore();
+
+      // 5. Create a minimal request context with the handle store
+      // Shallow-copy getParams vars so each param set is independent.
+      // In dev mode, merge vars from the getParams() probe if the caller
+      // didn't provide buildVars (production passes them from expandPrerenderRoutes).
+      const effectiveBuildVars = buildVars ?? devProbeBuildVars;
+      const variables: Record<string, any> = effectiveBuildVars
+        ? { ...effectiveBuildVars }
+        : {};
+      const stubRes = new Response(null, { status: 200 });
+      const minimalRequestContext: RequestContext<TEnv> = {
+        env: buildEnv ?? ({} as TEnv),
+        // Requestless refresh: arm the personalization guard so standalone
+        // cookies()/headers() (and the cache-directive helpers) throw a
+        // PrerenderPersonalizationError, which the producer maps to
+        // skipped-personalized. Build/dev prerender leave this unset.
+        ...(onDemand ? { _onDemandProducer: true as const } : {}),
+        ...(onDemand && deps.versions ? { _versions: deps.versions } : {}),
+        request: new Request("http://prerender" + pathname),
+        url: new URL("http://prerender" + pathname),
+        originalUrl: new URL("http://prerender" + pathname),
+        pathname,
+        searchParams: new URLSearchParams(),
+        _variables: variables,
+        build: true,
+        // Inert here: the prerender-collect / static-render pass has no live
+        // PPR-shell decision to gate; dynamic() reaches the shell axis only on a
+        // live request or a shell capture.
+        dynamic: () => {},
+        get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
+        set: ((keyOrVar: any, value: any) => {
+          contextSet(variables, keyOrVar, value);
+        }) as any,
+        params: matchedParams,
+        res: stubRes,
+        cookie: () => undefined,
+        cookies: () => ({}),
+        _readCookie: () => undefined,
+        _readCookies: () => ({}),
+        setCookie: () => {},
+        deleteCookie: () => {},
+        header: () => {},
+        setStatus: () => {},
+        _setStatus: () => {},
+        _rotateStateCookie: () => {},
+        _setKeepCacheDirective: () => {},
+        _setFreshReadsCookie: () => {},
+        use: (() => {
+          throw new Error("use() not available during pre-rendering");
+        }) as any,
+        method: "GET",
+        _handleStore: handleStore,
+        _requestTags: new Set<string>(),
+        waitUntil: () => {},
+        onResponse: () => {},
+        _onResponseCallbacks: [],
+        // No theme at build time: no request cookie.
+        _readTheme: () => undefined,
+        setLocationState() {},
+        _locationState: undefined,
+        _renderBarrier: Promise.resolve(),
+        _resolveRenderBarrier: () => {},
+        _reportedErrors: new WeakSet<object>(),
+        reverse: createReverseFunction(
+          deps.mergedRouteMap,
+          matched.routeKey,
+          matchedParams,
+          matched.routeKey
+            ? isRouteRootScoped(matched.routeKey, deps.routerId)
+            : undefined,
+        ),
+        // Scope the bake context's own lookups (createPrerenderContext reads it
+        // through the request ALS) per router as well.
+        _routerId: deps.routerId,
       };
-      const serializedSegments = await serializeSegments(
-        nonLoaderSegments,
-        onFlightError,
-      );
 
-      // 13. Collect handle data per segment (skip segments with no handle data).
-      // Encoded through the Flight codec (not stored raw) so Promise/ReactNode
-      // handle values survive the JSON-serialized build artifact / dev wire —
-      // the same fix the runtime cache uses. Encode happens here, in the RSC
-      // environment where the codec resolves; the node-side sinks only persist.
-      const handlesRecord: Record<string, SegmentHandleData> = {};
-      for (const seg of nonLoaderSegments) {
-        const segHandles = handleStore.getDataForSegment(seg.id);
-        if (Object.keys(segHandles).length > 0) {
-          // Resolve deferred values before encoding so the baked artifact holds
-          // resolved data (prerender = build-time cache).
-          handlesRecord[seg.id] = await resolveSegmentHandleValues(segHandles);
+      return runWithRequestContext(minimalRequestContext, async () => {
+        // 6. Create prerender context with synthetic URL.
+        // Prerender handlers get params, pathname, url, searchParams, search,
+        // reverse, use(handle), and optionally env (when buildEnv is configured).
+        const buildCtx = createPrerenderContext<TEnv>(
+          matchedParams,
+          pathname,
+          deps.mergedRouteMap,
+          matched.routeKey,
+          variables,
+          matchedPassthroughRoute,
+          buildEnv,
+          devMode,
+          onDemand,
+        );
+
+        // 7. Wire use() for handles only (loaders throw)
+        setupBuildUse(buildCtx);
+
+        // 8. Resolve all segments with skipLoaders
+        const loaderPromises = new Map<string, Promise<any>>();
+        const allSegments = await deps.resolveAllSegments(
+          entries,
+          matched.routeKey,
+          matchedParams,
+          buildCtx,
+          loaderPromises,
+          // throwOnError: a render failure (or `throw new Skip()`) must reach the
+          // build/dev caller, not be baked into a frozen error page (issue #587).
+          { skipLoaders: true, throwOnError: true },
+        );
+
+        // 9. Detect passthrough sentinel: handler returned ctx.passthrough().
+        // When the route declares loading(), the handler result is deferred so the
+        // component is a thenable resolving to the sentinel — detectPrerenderPassthrough
+        // resolves thenables before testing (a sync check would miss it and bake a
+        // corrupt artifact).
+        if (await detectPrerenderPassthrough(allSegments)) {
+          return { ...passthroughResult(), onDemandConfig };
         }
-      }
-      const handles = await encodeHandles(handlesRecord, onFlightError);
-      // Before intercept resolution, as a handler throw would be.
-      if (flightErrors.length > 0) throw flightErrors[0];
-
-      // Use the trie-level route key (e.g., "docs", "docs.article")
-      const routeName = matched.routeKey;
-
-      // Surface the matched route entry's ppr option for the build collection
-      // (leaf-first: the deepest type:"route" entry in the ancestor chain is
-      // the matched page route; ancestors are layouts/includes).
-      let routePpr: boolean | PartialPrerenderProps | undefined;
-      for (let i = entries.length - 1; i >= 0; i--) {
-        const e = entries[i]!;
-        if (e.type === "route") {
-          routePpr = e.ppr;
-          break;
+
+        // 10. Filter out any loader segments (belt-and-suspenders)
+        const nonLoaderSegments = allSegments.filter(
+          (s) => s.type !== "loader",
+        );
+
+        // 11. Wait for handles to settle
+        handleStore.seal();
+        await handleStore.settled;
+
+        // 12. Serialize segments using the cache serializer.
+        // Flight encodes a component that throws (an async server component in
+        // the tree) as an error row and completes normally. Rethrown below like
+        // a handler throw, so the caller's policy decides instead of baking the
+        // error (#914). On-demand refresh: a deep async child calling
+        // cookies()/headers() throws here, not in resolveAllSegments; a
+        // personalization error is thrown in preference to any other so the
+        // trigger maps it to skipped-personalized and keeps the old entry.
+        const { serializeSegments } = await import("../cache/segment-codec.js");
+        const { encodeHandles } = await import("../cache/handle-snapshot.js");
+        const flightErrors: unknown[] = [];
+        const onFlightError = (error: unknown): void => {
+          flightErrors.push(error);
+        };
+        // The collected error to rethrow. On an on-demand refresh a failure
+        // goes ahead of a notFound(): a render that hit a missing item AND a
+        // failing data source must keep the page (render-failed), not remove
+        // it because the notFound() happened to be reported first.
+        const firstFlightError = (): unknown => {
+          const failure = onDemand
+            ? flightErrors.findIndex((e) => !isDataNotFoundError(e))
+            : -1;
+          return flightErrors[failure === -1 ? 0 : failure];
+        };
+        const serializedSegments = await serializeSegments(
+          nonLoaderSegments,
+          onFlightError,
+        );
+        const personalized = flightErrors.find((e) =>
+          isPrerenderPersonalizationError(e),
+        );
+        if (onDemand && personalized) {
+          throw personalized;
         }
-      }
 
-      // 14. Resolve intercept segments for this route (if any ancestor defines
-      //     an intercept targeting this route). At build time we skip when()
-      //     evaluation -- we pre-render all intercepts unconditionally and let
-      //     runtime matching decide which to serve.
-      let interceptSegments: SerializedSegmentData[] | undefined;
-      let interceptHandles: string | undefined;
-
-      const foundIntercepts: {
-        intercept: InterceptEntry;
-        entry: EntryData;
-      }[] = [];
-      // The entry, then its orphans (nested ones included): the same traversal
-      // findInterceptForRoute uses; the build keeps ALL matches (not just the
-      // innermost) and skips when().
-      const collect = (source: EntryData): undefined => {
-        for (const ic of source.intercept) {
-          if (ic.routeName === matched.routeKey) {
-            foundIntercepts.push({ intercept: ic, entry: source });
+        // 13. Collect handle data per segment (skip segments with no handle data).
+        // Encoded through the Flight codec (not stored raw) so Promise/ReactNode
+        // handle values survive the JSON-serialized build artifact / dev wire —
+        // the same fix the runtime cache uses. Encode happens here, in the RSC
+        // environment where the codec resolves; the node-side sinks only persist.
+        const handlesRecord: Record<string, SegmentHandleData> = {};
+        for (const seg of nonLoaderSegments) {
+          const segHandles = handleStore.getDataForSegment(seg.id);
+          if (Object.keys(segHandles).length > 0) {
+            // Resolve deferred values before encoding so the baked artifact holds
+            // resolved data (prerender = build-time cache).
+            handlesRecord[seg.id] =
+              await resolveSegmentHandleValues(segHandles);
           }
         }
-        return undefined;
-      };
-      let current: EntryData | null = manifestEntry;
-      let prev: EntryData | null = null;
-      while (current) {
-        collect(current);
-        findInOrphans(current, collect, prev);
-        prev = current;
-        current = current.parent;
-      }
-
-      if (foundIntercepts.length > 0) {
-        const interceptResolvedSegments: typeof nonLoaderSegments = [];
-
-        for (const { intercept, entry: parentEntry } of foundIntercepts) {
-          // setupBuildUse keys handle pushes by ctx._currentSegmentId. The main
-          // resolveAllSegments pass left it on the route's segment id, so pin it
-          // to THIS intercept's slot id before resolving the handler/layout --
-          // otherwise the intercept's ctx.use() handle pushes land in the wrong
-          // bucket and getDataForSegment(seg.id) below drops them from the baked
-          // artifact. Re-pinned per iteration so multiple intercepts targeting
-          // the same route each get their own id (mirrors fresh.ts parallel-slot
-          // pinning).
-          const interceptSegmentId = `${parentEntry.shortCode}.${intercept.slotName}`;
-          (buildCtx as InternalHandlerContext<any, TEnv>)._currentSegmentId =
-            interceptSegmentId;
-
-          // Resolve handler
-          const handlerRaw =
-            typeof intercept.handler === "function"
-              ? intercept.handler(buildCtx)
-              : intercept.handler;
-          const handlerResolved =
-            handlerRaw instanceof Promise ? await handlerRaw : handlerRaw;
-          if (handlerResolved instanceof Response) {
-            // Handler returned a redirect/response -- skip this intercept
-            continue;
+        const handles = await encodeHandles(handlesRecord, onFlightError);
+        // Before intercept resolution, as a handler throw would be.
+        if (flightErrors.length > 0) throw firstFlightError();
+
+        // Use the trie-level route key (e.g., "docs", "docs.article")
+        const routeName = matched.routeKey;
+
+        // Surface the matched route entry's ppr option for the build collection
+        // (leaf-first: the deepest type:"route" entry in the ancestor chain is
+        // the matched page route; ancestors are layouts/includes).
+        let routePpr: boolean | PartialPrerenderProps | undefined;
+        for (let i = entries.length - 1; i >= 0; i--) {
+          const e = entries[i]!;
+          if (e.type === "route") {
+            // A durable segment refresh cannot atomically replace the separate
+            // document shell. Keep on-demand routes on axis 1 so a refreshed
+            // payload cannot be paired with a stale shell prelude.
+            routePpr = e.isOnDemand === true ? undefined : e.ppr;
+            break;
           }
-          const component: ReactNode = handlerResolved;
-
-          // Resolve layout (if any)
-          let layoutElement: ReactNode | undefined;
-          if (intercept.layout) {
-            if (typeof intercept.layout === "function") {
-              const layoutResult = await intercept.layout(buildCtx);
-              if (layoutResult instanceof Response) continue;
-              layoutElement = layoutResult;
-            } else {
-              layoutElement = intercept.layout;
+        }
+
+        // 14. Resolve intercept segments for this route (if any ancestor defines
+        //     an intercept targeting this route). At build time we skip when()
+        //     evaluation -- we pre-render all intercepts unconditionally and let
+        //     runtime matching decide which to serve.
+        let interceptSegments: SerializedSegmentData[] | undefined;
+        let interceptHandles: string | undefined;
+
+        const foundIntercepts: {
+          intercept: InterceptEntry;
+          entry: EntryData;
+        }[] = [];
+        // The entry, then its orphans (nested ones included): the same traversal
+        // findInterceptForRoute uses; the build keeps ALL matches (not just the
+        // innermost) and skips when().
+        const collect = (source: EntryData): undefined => {
+          for (const ic of source.intercept) {
+            if (ic.routeName === matched.routeKey) {
+              foundIntercepts.push({ intercept: ic, entry: source });
             }
           }
-
-          interceptResolvedSegments.push({
-            id: interceptSegmentId,
-            namespace: `intercept:${intercept.routeName}`,
-            type: "parallel" as const,
-            index: 0,
-            component,
-            loading: intercept.loading === false ? null : intercept.loading,
-            layout: layoutElement,
-            params: matchedParams,
-            slot: intercept.slotName,
-            belongsToRoute: true,
-            parallelName: `intercept:${intercept.routeName}.${intercept.slotName}`,
-          });
+          return undefined;
+        };
+        let current: EntryData | null = manifestEntry;
+        let prev: EntryData | null = null;
+        while (current) {
+          collect(current);
+          findInOrphans(current, collect, prev);
+          prev = current;
+          current = current.parent;
         }
 
-        if (interceptResolvedSegments.length > 0) {
-          // Wait for handles again (intercept handlers may have called use())
-          await handleStore.settled;
-          interceptSegments = await serializeSegments(
-            interceptResolvedSegments,
-            onFlightError,
-          );
-          const interceptHandlesRecord: Record<string, SegmentHandleData> = {};
-          for (const seg of interceptResolvedSegments) {
-            const segHandles = handleStore.getDataForSegment(seg.id);
-            if (Object.keys(segHandles).length > 0) {
-              interceptHandlesRecord[seg.id] =
-                await resolveSegmentHandleValues(segHandles);
+        // V1 writes only the main variant. Do not execute intercept producers
+        // whose output would be discarded (and whose personalization/errors
+        // must not block an otherwise valid main refresh).
+        if (!onDemand && foundIntercepts.length > 0) {
+          const interceptResolvedSegments: typeof nonLoaderSegments = [];
+
+          for (const { intercept, entry: parentEntry } of foundIntercepts) {
+            // setupBuildUse keys handle pushes by ctx._currentSegmentId. The main
+            // resolveAllSegments pass left it on the route's segment id, so pin it
+            // to THIS intercept's slot id before resolving the handler/layout --
+            // otherwise the intercept's ctx.use() handle pushes land in the wrong
+            // bucket and getDataForSegment(seg.id) below drops them from the baked
+            // artifact. Re-pinned per iteration so multiple intercepts targeting
+            // the same route each get their own id (mirrors fresh.ts parallel-slot
+            // pinning).
+            const interceptSegmentId = `${parentEntry.shortCode}.${intercept.slotName}`;
+            (buildCtx as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+              interceptSegmentId;
+
+            // Resolve handler
+            const handlerRaw =
+              typeof intercept.handler === "function"
+                ? intercept.handler(buildCtx)
+                : intercept.handler;
+            const handlerResolved =
+              handlerRaw instanceof Promise ? await handlerRaw : handlerRaw;
+            if (handlerResolved instanceof Response) {
+              // Handler returned a redirect/response -- skip this intercept
+              continue;
+            }
+            const component: ReactNode = handlerResolved;
+
+            // Resolve layout (if any)
+            let layoutElement: ReactNode | undefined;
+            if (intercept.layout) {
+              if (typeof intercept.layout === "function") {
+                const layoutResult = await intercept.layout(buildCtx);
+                if (layoutResult instanceof Response) continue;
+                layoutElement = layoutResult;
+              } else {
+                layoutElement = intercept.layout;
+              }
             }
+
+            interceptResolvedSegments.push({
+              id: interceptSegmentId,
+              namespace: `intercept:${intercept.routeName}`,
+              type: "parallel" as const,
+              index: 0,
+              component,
+              loading: intercept.loading === false ? null : intercept.loading,
+              layout: layoutElement,
+              params: matchedParams,
+              slot: intercept.slotName,
+              belongsToRoute: true,
+              parallelName: `intercept:${intercept.routeName}.${intercept.slotName}`,
+            });
           }
-          // The intercept artifact serves main + intercept segments together, so
-          // encode the MERGED handle map here (the sinks no longer merge raw
-          // records — they store this pre-encoded string as-is).
-          interceptHandles = await encodeHandles(
-            {
-              ...handlesRecord,
-              ...interceptHandlesRecord,
-            },
-            onFlightError,
-          );
-        }
-      }
 
-      if (flightErrors.length > 0) throw flightErrors[0];
+          if (interceptResolvedSegments.length > 0) {
+            // Wait for handles again (intercept handlers may have called use())
+            await handleStore.settled;
+            interceptSegments = await serializeSegments(
+              interceptResolvedSegments,
+              onFlightError,
+            );
+            const interceptHandlesRecord: Record<string, SegmentHandleData> =
+              {};
+            for (const seg of interceptResolvedSegments) {
+              const segHandles = handleStore.getDataForSegment(seg.id);
+              if (Object.keys(segHandles).length > 0) {
+                interceptHandlesRecord[seg.id] =
+                  await resolveSegmentHandleValues(segHandles);
+              }
+            }
+            // The intercept artifact serves main + intercept segments together, so
+            // encode the MERGED handle map here (the sinks no longer merge raw
+            // records — they store this pre-encoded string as-is).
+            interceptHandles = await encodeHandles(
+              {
+                ...handlesRecord,
+                ...interceptHandlesRecord,
+              },
+              onFlightError,
+            );
+          }
+        }
 
-      return {
-        segments: serializedSegments,
-        handles,
-        routeName,
-        params: matchedParams,
-        interceptSegments,
-        interceptHandles,
-        ppr: routePpr,
-      };
-    });
-  });
+        if (flightErrors.length > 0) throw firstFlightError();
+
+        return {
+          segments: serializedSegments,
+          handles,
+          routeName,
+          params: matchedParams,
+          interceptSegments,
+          interceptHandles,
+          onDemandConfig,
+          ppr: routePpr,
+        };
+      });
+    }),
+  );
+  // A build or dev render keeps the throw (the caller's onError policy).
+  if (!onDemand) return rendered;
+  // An on-demand refresh reports a notFound() anywhere in the render (a
+  // handler's throw, or the only kind of error Flight collected) as an
+  // outcome, with the route's onDemand config: the trigger stores the
+  // "removed" marker stamped like a page (create-prerender-trigger.ts).
+  try {
+    return await rendered;
+  } catch (error) {
+    if (!isDataNotFoundError(error)) throw error;
+    return {
+      segments: [],
+      handles: "",
+      routeName: matched.routeKey,
+      params: matchedParams,
+      notFound: true,
+      onDemandConfig,
+    };
+  }
 }
 
 /**