@rangojs/router 0.0.0-experimental.145 → 0.0.0-experimental.147

package/src/prerender/build-shell-capture.ts

@@ -0,0 +1,237 @@
+/**
+ * Producer B: build-time PPR shell capture for Prerender+ppr routes (#699).
+ *
+ * Runs in the RSC realm of the build's temp server, AFTER all bundles are
+ * written (the prelude embeds built client asset URLs — bootstrap module,
+ * chunk preloads — that only exist post-client-build). The capture core is
+ * producer A's, verbatim: deriveShellCaptureContext (mask funnel, liveness,
+ * snapshot recording, implicit doc-cache scope) + captureAndStoreShell (gates,
+ * quiesce, tags union, putShell barrier). The differences are only the base
+ * context (a synthetic build request created via createRequestContext over the
+ * build env — no ambient identity, so the identity guard is trivially
+ * satisfied) and the sink (an entry collector instead of a runtime store).
+ *
+ * The capture's match() re-enters withCacheLookup, HITs the in-realm prerender
+ * store seeded from the just-collected Flight payloads, and REPLAYS the
+ * build-time segments — no handler execution, exactly the runtime composition
+ * path (#697). Live-lane loaders mask into holes; bake-lane loaders execute
+ * under the build context and refuse the capture if they reject or read
+ * identity, the same eligibility rules as at runtime.
+ */
+
+import type { ShellCacheEntry } from "../cache/types.js";
+import { MemorySegmentCacheStore } from "../cache/memory-segment-store.js";
+import {
+  createRequestContext,
+  runWithRequestContext,
+  setRequestContextParams,
+} from "../server/request-context.js";
+import {
+  deriveShellCaptureContext,
+  captureAndStoreShell,
+  delay,
+  SHELL_CAPTURE_RETRY_DELAY_MS,
+  type ShellCaptureDescriptor,
+} from "../rsc/shell-capture.js";
+import { buildFullPayload } from "../rsc/full-payload.js";
+import type { RscPayload, SSRModule } from "../rsc/types.js";
+import type { HandlerContext } from "../rsc/handler-context.js";
+import { renderToReadableStream } from "../deps/rsc.js";
+import {
+  resolvePprConfig,
+  type ResolvedPprConfig,
+} from "../rsc/shell-serve.js";
+
+/**
+ * Normalize a collected truthy `ppr` path option into the SAME concrete
+ * policy the runtime serve path derives — through resolvePprConfig itself,
+ * over a synthetic route entry — so the build-stamped ttl default can never
+ * drift from the serve-side one.
+ */
+export function resolveBuildPprConfig(
+  ppr: true | { ttl?: number; swr?: number; tags?: string[] },
+): ResolvedPprConfig {
+  const resolved = resolvePprConfig({ type: "route", ppr } as any);
+  // resolvePprConfig returns null only for undefined/false ppr; the collector
+  // filtered those out. Guard for the type only.
+  if (!resolved) throw new Error("[rango] unreachable: ppr option was falsy");
+  return resolved;
+}
+
+export interface BuildShellCaptureOptions {
+  /** The router instance (from RouterRegistry in the same realm). */
+  router: any;
+  /** Concrete URL path to capture (e.g. "/pp/alpha"). */
+  urlPath: string;
+  /**
+   * The candidate's trie route key. The capture's match() must land on THIS
+   * route: the phase sweeps every registered router, and a router that does
+   * not own the URL matches something else (its catch-all, a 404 shape) —
+   * that capture must not be baked.
+   */
+  routeName: string;
+  /** Shell store key to stamp into the descriptor (host-free at build). */
+  key: string;
+  ttl?: number;
+  swr?: number;
+  /** The route's static ppr.tags (the capture unions render-recorded tags). */
+  tags?: string[];
+  /** Build-time env bindings (rango plugin buildEnv), if configured. */
+  buildEnv?: unknown;
+  /**
+   * The MAIN build's version (the version plugin's value folded into the
+   * shipped worker) — NOT the temp server's own version-plugin value. The
+   * serve-side isValidShellHit gate compares entry.buildVersion against the
+   * running worker's ctx.version; stamping the temp server's would make every
+   * build entry an eternal MISS.
+   */
+  buildVersion: string;
+  /**
+   * The SSR half, composed by the plugin from the temp server's SSR
+   * environment runner (react-dom/static prerender + Flight client), with the
+   * bootstrap script content overridden to the BUILT client entry URL.
+   */
+  captureShellHTML: NonNullable<SSRModule["captureShellHTML"]>;
+  /** Verbose per-attempt breadcrumbs (build log). */
+  debug?: boolean;
+}
+
+export interface BuildShellCaptureResult {
+  outcome:
+    | "stored"
+    | "no-shell"
+    | "redirect"
+    | "refused"
+    /** The router swept does not own this URL — try the next one. */
+    | "route-mismatch";
+  /** Present iff outcome === "stored". */
+  entry?: ShellCacheEntry;
+  /** The putShell-barrier tag union (static ppr.tags + render-recorded). */
+  tags?: string[];
+  /** On route-mismatch: what this router's match actually landed on. */
+  matchedRouteName?: string;
+}
+
+/**
+ * Capture the PPR shell for one prerendered URL at build time. Retries once
+ * in place on `no-shell` (the first attempt warms the temp server's SSR/Flight
+ * transform graph, mirroring producer A's cold-start retry — same delay).
+ */
+export async function captureShellForBuild(
+  opts: BuildShellCaptureOptions,
+): Promise<BuildShellCaptureResult> {
+  const first = await attemptBuildCapture(opts);
+  if (first.outcome !== "no-shell") return first;
+  if (opts.debug) {
+    console.log(
+      `[rango] shell capture attempt 1/2 for ${opts.urlPath} produced no shell (cold graph?) — retrying`,
+    );
+  }
+  await delay(SHELL_CAPTURE_RETRY_DELAY_MS);
+  return attemptBuildCapture(opts);
+}
+
+/** One attempt: fresh base context, fresh derivation, fresh render. */
+async function attemptBuildCapture(
+  opts: BuildShellCaptureOptions,
+): Promise<BuildShellCaptureResult> {
+  const router = opts.router;
+  const url = new URL(opts.urlPath, "http://build.invalid");
+  const request = new Request(url, { method: "GET" });
+
+  // Synthetic build request context: same factory the runtime handler uses,
+  // so the capture's ALS surface (cookie machinery, variables, waitUntil,
+  // theme resolution) is production-shaped. No cookie header → theme resolves
+  // to the app default, exactly like a first anonymous visitor's capture.
+  const baseCtx = createRequestContext({
+    env: (opts.buildEnv ?? {}) as any,
+    request,
+    url,
+    variables: {},
+    // Fresh empty store per attempt: cache()/"use cache" reads MISS, execute,
+    // and are recorded into the snapshot by the derivation's RecordingShell
+    // wrapper — the entry pins its own generation, nothing preexisting leaks.
+    cacheStore: new MemorySegmentCacheStore(),
+    themeConfig: router.themeConfig ?? null,
+    stateCookieName: router.resolvedStateCookieName,
+    version: opts.buildVersion,
+  });
+
+  const { derivedCtx, freshHandleStore } = deriveShellCaptureContext(baseCtx, {
+    ttl: opts.ttl,
+    swr: opts.swr,
+  });
+
+  // Entry collector: captureAndStoreShell's sink. putShell never fails here,
+  // so a "stored" outcome always carries the entry.
+  let collected: { entry: ShellCacheEntry; tags?: string[] } | null = null;
+  const collector = {
+    putShell: async (
+      _key: string,
+      entry: ShellCacheEntry,
+      _ttl?: number,
+      _swr?: number,
+      tags?: string[],
+    ): Promise<void> => {
+      collected = { entry, tags };
+    },
+  };
+
+  const descriptor: ShellCaptureDescriptor = {
+    key: opts.key,
+    buildVersion: opts.buildVersion,
+    ttl: opts.ttl,
+    swr: opts.swr,
+    tags: opts.tags,
+    store: collector as any,
+    debug: opts.debug,
+  };
+
+  let mismatchedRouteName: string | undefined;
+  const outcome = await runWithRequestContext(derivedCtx, async () => {
+    const match = await router.match(request, { env: opts.buildEnv ?? {} });
+    if (match.routeName !== opts.routeName) {
+      mismatchedRouteName = match.routeName;
+      return "route-mismatch" as const;
+    }
+    if (match.redirect) return "redirect" as const;
+
+    setRequestContextParams(match.params, match.routeName);
+
+    const payload = buildFullPayload(
+      match,
+      // buildFullPayload reads only ctx.router.* and ctx.version.
+      { router, version: opts.buildVersion } as unknown as HandlerContext<any>,
+      url,
+      derivedCtx,
+      freshHandleStore,
+    );
+    const rscStream = renderToReadableStream<RscPayload>(payload, {
+      onError: (error: unknown) => {
+        if (opts.debug) {
+          console.warn(
+            `[rango] shell capture render error for ${opts.urlPath}:`,
+            error,
+          );
+        }
+      },
+    });
+
+    return captureAndStoreShell(
+      { captureShellHTML: opts.captureShellHTML } as SSRModule,
+      rscStream,
+      freshHandleStore,
+      derivedCtx,
+      descriptor,
+    );
+  });
+
+  if (outcome === "stored" && collected !== null) {
+    const hit: { entry: ShellCacheEntry; tags?: string[] } = collected;
+    return { outcome, entry: hit.entry, tags: hit.tags };
+  }
+  if (outcome === "route-mismatch") {
+    return { outcome, matchedRouteName: mismatchedRouteName };
+  }
+  return { outcome };
+}

package/src/prerender/shell-manifest-key.ts

@@ -0,0 +1,20 @@
+/**
+ * Build shell manifest key, shared by the producer (the build's shell
+ * prerender phase, vite/discovery/shell-prerender-phase.ts) and the consumer
+ * (the runtime read-through, rsc/shell-build-manifest.ts) so the format
+ * cannot drift. Dependency-free: the producer runs node-side in the plugin,
+ * the consumer in the RSC runtime.
+ *
+ * PATHNAME-ONLY by design. Host-free because the build knows no request
+ * host. Router-free because the router id ($$id) is a hash of
+ * filePath:lineNumber of the TRANSFORMED source, which differs between the
+ * discovery temp server's dev-style transform chain and the main build's —
+ * a temp-realm router id can never be looked up by the shipped worker. The
+ * producer instead detects pathname collisions across routers at build time
+ * and declines both entries (loudly), keeping the key unambiguous. This is
+ * a manifest namespace, never a store keyspace: the runtime shell key
+ * (host + pathname + search + ":shell") stays untouched.
+ */
+export function buildShellManifestKey(pathname: string): string {
+  return pathname;
+}

package/src/prerender/store.ts

@@ -73,7 +73,16 @@ export function createDevPrerenderStore(devUrl: string): PrerenderStore {
       if (isIntercept) url += "&intercept=1";
       if (meta.isPassthroughRoute) url += "&passthrough=1";
       try {
-        const res = await fetch(url);
+        // Bounded: this fetch also runs inside the PPR shell capture (a
+        // workerd waitUntil task), where an unsettled fetch does not reject —
+        // it pends until the task is torn down. Unbounded, one pending fetch
+        // wedged the per-isolate capture queue on GH runners (rotating dev
+        // capture failures; endpoint instrumentation showed 3-4ms memo HITs,
+        // so latency was never the issue — settlement was). On timeout the
+        // catch degrades to a store miss and the pipeline falls through to
+        // the live handler render (the documented dev fall-through), so the
+        // capture still lands with live content.
+        const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
         if (!res.ok) return null;
         return res.json();
       } catch {

package/src/router/loader-resolution.ts

@@ -430,6 +430,22 @@ function createLoaderExecutor<TEnv>(
     // nested deps inherit isDslLoader=false only when the CHAIN started in a
     // handler; a chain started by the segment funnel stays DSL (the loader
     // scope ALS survives the body's awaits).
+    // Shell fast path eligibility: a HANDLER-invoked loader executing during a
+    // capture is handler-layer dynamism — on a handler-free (replayed) HIT it
+    // would never re-run, freezing its consumption-lane value (#672's "fresh
+    // per serve" slot shape). Mark the capture; the entry declines the fast
+    // path and keeps the full tail. DSL loaders re-run on every HIT and never
+    // set this.
+    if (!isDslLoader) {
+      const captureCtx = _getRequestContext();
+      if (
+        captureCtx?._shellCaptureRun &&
+        captureCtx._shellCaptureHandleLiveness
+      ) {
+        captureCtx._shellCaptureHandleLiveness.handlerInvokedLoader = true;
+      }
+    }
+
     const promise = observePhase(PHASES.loader(loader.$$id), () =>
       Promise.resolve(
         runInsideLoaderBodyScope(

package/src/router/match-api.ts

@@ -1,4 +1,8 @@
-import { CacheScope, createCacheScope } from "../cache/cache-scope.js";
+import {
+  CacheScope,
+  createCacheScope,
+  resolveShellImplicitCacheScope,
+} from "../cache/cache-scope.js";
 import { RouteNotFoundError } from "../errors";
 import {
   createErrorInfo,
@@ -180,7 +184,10 @@ export async function createMatchContextForFull<TEnv>(
     },
     isSameRouteNavigation: false,
     interceptResult: null,
-    cacheScope: snapshot.cacheScope,
+    // Shell fast path: a capture or an eligible HIT tail may substitute an
+    // implicit doc-level scope (marker-gated; a route-derived scope wins).
+    // Full matches only — partial navigations never serve a shell.
+    cacheScope: resolveShellImplicitCacheScope(snapshot.cacheScope),
     isIntercept: false,
     actionContext: undefined,
     isAction: false,

package/src/router/match-handlers.ts

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import { sanitizeError } from "../errors";
 import type { ErrorInfo, ErrorPhase, MatchResult } from "../types";
 import type {
@@ -291,7 +292,13 @@ export function createMatchHandlers<TEnv = any>(
           });
           emitter.start();
 
+          const ctxBuildStart = INTERNAL_RANGO_DEBUG ? performance.now() : 0;
           const result = await createMatchContextForFull(request, env);
+          if (INTERNAL_RANGO_DEBUG) {
+            console.log(
+              `[Server][match] context built +${Math.round(performance.now() - ctxBuildStart)}ms (abs ${Math.round(performance.now())})`,
+            );
+          }
 
           if ("type" in result && result.type === "redirect") {
             emitter.end(0, false);
@@ -310,7 +317,13 @@ export function createMatchHandlers<TEnv = any>(
           try {
             const state = createPipelineState();
             const pipeline = createMatchPartialPipeline(ctx, state);
+            const pipeStart = INTERNAL_RANGO_DEBUG ? performance.now() : 0;
             const matchResult = await collectMatchResult(pipeline, ctx, state);
+            if (INTERNAL_RANGO_DEBUG) {
+              console.log(
+                `[Server][match] pipeline collected +${Math.round(performance.now() - pipeStart)}ms (abs ${Math.round(performance.now())})`,
+              );
+            }
             if (hasTelemetry || cacheSignalEnabled) {
               const signalSegments = buildSignal(ctx.routeKey, state);
               recordSignalIfEnabled(signalSegments);

package/src/router/match-middleware/cache-lookup.ts

@@ -112,6 +112,9 @@ let prerenderStoreInstance: PrerenderStore | null | undefined;
 let _deserializeSegments:
   | typeof import("../../cache/segment-codec.js").deserializeSegments
   | undefined;
+let _fragmentSegments:
+  | typeof import("../../cache/segment-codec.js").fragmentSegments
+  | undefined;
 let _restoreHandles:
   | typeof import("../../cache/handle-snapshot.js").restoreHandles
   | undefined;
@@ -135,6 +138,7 @@ async function ensurePrerenderDeps() {
       import("../../prerender/store.js"),
     ]);
     _deserializeSegments = codec.deserializeSegments;
+    _fragmentSegments = codec.fragmentSegments;
     _restoreHandles = snapshot.restoreHandles;
     _decodeHandles = snapshot.decodeHandles;
     _hashParams = paramHash.hashParams;
@@ -237,6 +241,7 @@ async function* yieldFromStore<TEnv>(
 
   if (
     !_deserializeSegments ||
+    !_fragmentSegments ||
     !_restoreHandles ||
     !_decodeHandles ||
     !_hashParams ||
@@ -245,7 +250,13 @@ async function* yieldFromStore<TEnv>(
     throw new Error("yieldFromStore called before ensurePrerenderDeps");
   }
 
-  const segments = await _deserializeSegments(entry.segments);
+  // Shell-HIT tail (issue #700): a Prerender+ppr route's tail serves from THIS
+  // store (the prerender lookup runs before the cache scope), so the fragment
+  // splice must apply here too — otherwise producer B entries re-serialize the
+  // whole tree per request while producer A entries do not.
+  const segments = _getRequestContext()?._shellFragmentPayload
+    ? await _fragmentSegments(entry.segments)
+    : await _deserializeSegments(entry.segments);
 
   // Replay handle data (same as runtime cache hit path). entry.handles is a
   // Flight-encoded string ("" when none) — decode before restore so

package/src/router/prerender-match.ts

@@ -21,6 +21,7 @@ import type { RouterContext } from "./router-context.js";
 import type { ResolveSegmentOptions } from "./segment-resolution.js";
 import { runWithRouterContext } from "./router-context.js";
 import type { EntryData, InterceptEntry } from "../server/context";
+import type { PartialPrerenderProps } from "../urls/pattern-types.js";
 import type {
   HandlerContext,
   InternalHandlerContext,
@@ -74,6 +75,13 @@ export async function matchForPrerender<TEnv = any>(
    *  the sinks store it as-is (no longer merge raw records). */
   interceptHandles?: string;
   passthrough?: true;
+  /**
+   * The matched route entry's `ppr` path option, surfaced so the build
+   * collection can flag Prerender+ppr routes as build-time shell candidates
+   * (issue #699 producer B). Runtime-only today; the build otherwise never
+   * sees the option (it lives on EntryData, not the trie).
+   */
+  ppr?: boolean | PartialPrerenderProps;
 } | null> {
   // 1. Find the matching route entry
   const matched = await deps.findMatch(pathname);
@@ -306,6 +314,18 @@ export async function matchForPrerender<TEnv = any>(
       // 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;
+        }
+      }
+
       // 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
@@ -420,6 +440,7 @@ export async function matchForPrerender<TEnv = any>(
         params: matchedParams,
         interceptSegments,
         interceptHandles,
+        ppr: routePpr,
       };
     });
   });

package/src/router/segment-resolution/mask-nested.ts

@@ -51,11 +51,27 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
  * rule, semantic-matrix PPR3) shares the raw container and must keep real
  * values. Cycles are preserved as cycles in the copy.
  */
+/**
+ * Optional single-walk report for maskNestedContainerThenables: `thenable`
+ * flips true when the walk masked at least one thenable. The shell fast path
+ * reads it at handle-push time — a pushed container with a nested thenable
+ * declares per-request data, and a shell entry whose HANDLER layer made such
+ * a declaration cannot be served handler-free (the hole would never fill).
+ * Same single-pass shape as elideLoaderContainer's `hasHole`.
+ */
+export interface MaskReport {
+  thenable: boolean;
+}
+
 export function maskNestedContainerThenables(
   value: unknown,
   seen: Map<object, unknown> = new Map(),
+  report?: MaskReport,
 ): unknown {
-  if (isThenable(value)) return createMaskedLoaderPromise();
+  if (isThenable(value)) {
+    if (report) report.thenable = true;
+    return createMaskedLoaderPromise();
+  }
 
   if (Array.isArray(value)) {
     const cached = seen.get(value);
@@ -63,7 +79,7 @@ export function maskNestedContainerThenables(
     const out: unknown[] = new Array(value.length);
     seen.set(value, out);
     for (let i = 0; i < value.length; i++) {
-      out[i] = maskNestedContainerThenables(value[i], seen);
+      out[i] = maskNestedContainerThenables(value[i], seen, report);
     }
     return out;
   }
@@ -74,7 +90,7 @@ export function maskNestedContainerThenables(
     const out: Record<string, unknown> = {};
     seen.set(value, out);
     for (const key of Object.keys(value)) {
-      out[key] = maskNestedContainerThenables(value[key], seen);
+      out[key] = maskNestedContainerThenables(value[key], seen, report);
     }
     return out;
   }

package/src/rsc/capture-queue.ts

@@ -0,0 +1,67 @@
+/**
+ * Per-isolate shell-capture serialization.
+ *
+ * Captures are CPU-bound background renders whose quiet detection is
+ * task-quantized (FLIGHT_QUIET_HOPS macrotask hops with zero new bytes). Two
+ * captures running concurrently starve each other: one grinding capture —
+ * e.g. a prerender+ppr route whose capture round-trips the dev
+ * /__rsc_prerender endpoint, whose per-request module re-import can peg a
+ * slow CI runner for seconds — keeps the sibling's render byte-silent past
+ * its abort budget, so the sibling freezes a trivial prelude and stores
+ * nothing. Observed on GH runners as ROTATING eternal-MISS victims (the
+ * warmup on one shard, a composition probe, then /ppr-shell?probe=stream once
+ * the first was quieted) while every local run passed.
+ *
+ * Serializing capture execution removes the cross-talk: each capture's quiet
+ * window observes only its own work. Captures are TTL-scale background work,
+ * so queueing costs latency-to-HIT only — never a served response. On workerd
+ * a queued capture rides the scheduling request's waitUntil, whose lifetime
+ * is bounded; a capture killed mid-queue by that bound simply recaptures on a
+ * later request (the existing best-effort contract).
+ *
+ * The chain link resolves in `finally` and the prior link is awaited with a
+ * swallow, so one rejected capture can never wedge every later one.
+ */
+let captureQueue: Promise<void> = Promise.resolve();
+
+/**
+ * Upper bound on how long one queue link may hold the queue. A capture task
+ * normally settles well inside this (attempt + in-place retry + writes), but
+ * a task wedged on never-settling I/O — a workerd waitUntil fetch that pends
+ * instead of rejecting (seen on GH runners with the dev prerender store
+ * before its fetch was time-bounded) — must not block every later capture in
+ * the isolate. At the cap the QUEUE is released; the wedged task itself stays
+ * detached (its own per-key guards clean up when/if it settles).
+ */
+const QUEUE_LINK_CAP_MS = 60_000;
+
+/**
+ * Run `task` after every previously enqueued capture has settled. Returns a
+ * promise for THIS task's completion (rejections propagate to the caller —
+ * the queue itself is insulated).
+ */
+export function enqueueSerializedCapture(
+  task: () => Promise<void>,
+): Promise<void> {
+  const prior = captureQueue;
+  let releaseQueue!: () => void;
+  captureQueue = new Promise<void>((resolve) => {
+    releaseQueue = resolve;
+  });
+  return (async () => {
+    await prior.catch(() => {});
+    let capTimer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        task(),
+        new Promise<void>((resolve) => {
+          capTimer = setTimeout(resolve, QUEUE_LINK_CAP_MS);
+          (capTimer as { unref?: () => void }).unref?.();
+        }),
+      ]);
+    } finally {
+      if (capTimer) clearTimeout(capTimer);
+      releaseQueue();
+    }
+  })();
+}