@rangojs/router 0.17.0 → 0.18.0

package/src/rsc/shell-build-manifest.ts

@@ -81,16 +81,16 @@ function loadManifest(): Promise<ShellManifestModule | null> {
 }
 
 /**
- * Per-spec verdict memo for the version + integrity gates. A manifest record
+ * Per-spec verdict memo for the version + structural gates. A manifest record
  * is immutable for the process lifetime (content-hashed asset module), so its
- * gate verdict is constant — without this, EVERY request to a baked ppr route
- * re-decodes the full prelude base64 (hasIntactShellPayload) on the hot path:
- * a fresh build hit never populates the runtime store, so the store MISS +
- * read-through is the steady state, not a warm-up. Only the per-request
- * gates (tag markers, staleness) stay outside the memo. `null` memoizes a
- * failed verdict — deterministically invalid, don't re-pay the decode.
- * Spec-only keying is sound because buildVersion is process-constant on the
- * manifest path (folded into the shipped worker; dev never loads a manifest).
+ * gate verdict is constant: a fresh build hit never populates the runtime
+ * store, so the store MISS + read-through is the steady state, not a warm-up.
+ * Only the per-request gates (tag markers, staleness) stay outside the memo;
+ * the document HIT decodes the prelude once per serve (openShellDocument),
+ * partial replay never does. `null` memoizes a failed verdict —
+ * deterministically invalid. Spec-only keying is sound because buildVersion is
+ * process-constant on the manifest path (folded into the shipped worker; dev
+ * never loads a manifest).
  */
 const validatedSpecs = new Map<string, ValidatedBuildShellEntry | null>();
 
@@ -259,6 +259,24 @@ async function fetchDevShellEntry(
   }
 }
 
+/**
+ * Whether a build-time shell exists for `pathname` (the caller checks the
+ * request is search-less, like the entries lookupBuildShell serves): a
+ * manifest entry for the path in production, a Prerender route in dev. No
+ * asset load and no dev capture: it only decides whether a request that
+ * cannot read the build shell deserves a warning.
+ */
+export async function hasBuildShell(
+  pathname: string,
+  dev?: DevShellLookup,
+): Promise<boolean> {
+  if (globalThis.__loadShellManifestModule === undefined) {
+    return dev?.isPrerenderRoute === true;
+  }
+  const mod = await loadManifest();
+  return mod?.default[buildShellManifestKey(pathname)] !== undefined;
+}
+
 /**
  * Look up the baked shell entry for a request, applying every serve gate:
  * search-less requests only (the build captured the bare pathname; a

package/src/rsc/shell-capture-constants.ts

@@ -14,18 +14,72 @@
  * costs latency-to-HIT only — never a served response — and 5s spuriously
  * refused legitimately-slow deferred shell material (a real storefront's meta
  * chains settle at ~7s). Ceiling math: workerd's waitUntil lifetime is ~30s
- * past response completion, and a guaranteed two-attempt envelope needs
- * 2x budget + the in-place retry delay + store I/O, i.e. budget <= ~14s. The
- * 15s default deliberately sits just past that: attempt 1 always gets its
- * full 15s, but when it consumed the whole budget the in-place RETRY may be
- * truncated by the platform kill on workerd — degrading to the existing
- * best-effort contract (the key stays MISS; a later request re-captures).
+ * past response completion. An attempt that consumed the whole budget is not
+ * retried in place (shell-capture.ts noShellCauses), so the envelope is one
+ * budget plus store I/O; the retry follows only an attempt that ended early
+ * (a cold-module abort). Past the ceiling the platform kill degrades to the
+ * existing best-effort contract (the key stays MISS; a later request
+ * re-captures).
  * Node/dev and build-time captures have no waitUntil ceiling. The per-route
  * `ppr.captureTimeout` knob remains for tightening below the default. See
  * docs/design/ppr-shell-resume.md (Cost model).
  */
 export const SHELL_CAPTURE_MAX_WAIT_MS = 15_000;
 
+/**
+ * The shell key for one request partition (cache-scope.ts
+ * resolveShellPartition): the route cache() `key()` or store keyGenerator
+ * result that partitions the route's record partitions its shell too, so
+ * each partition captures and serves its own. Here, in the leaf module, so
+ * the testing helper `shellCacheKey` (testing/shell-status.ts) calls it
+ * without pulling shell-serve.ts.
+ *
+ * The partition is URI-encoded: it is request-derived, and raw it could end
+ * in a suffix another key is built with (navigationShellKey), so a partition
+ * `gold:navigation` named gold's navigation entry and its document shell
+ * replayed to gold's navigations. Encoded, it holds no `:` or `|`.
+ */
+export function partitionShellKey(key: string, partition: string): string {
+  return `${key}|${encodeURIComponent(partition)}`;
+}
+
+/**
+ * The navigation-only entry beside a document shell key (a cold partial
+ * request's capture, rsc-rendering.ts). A suffix after the (encoded)
+ * partition: partitionShellKey keeps the two unambiguous.
+ */
+export function navigationShellKey(key: string): string {
+  return `${key}:navigation`;
+}
+
+/**
+ * Fixed number of macrotask hops between `quiesce` resolving and the abort. These
+ * give React's fizz worker turns to flush the settled shell into the prelude and
+ * mark still-pending boundaries as POSTPONED (rather than errored) before
+ * controller.abort() lands. Not a wall-clock wait. Taken by captureShellHTML
+ * (ssr/index.tsx) and by the testing SSR stub (testing/serve-shell-request.ts),
+ * so the stub freezes the same Flight the real capture would.
+ *
+ * Why 16 and not the original 2: under the REPLAY-ONLY capture model
+ * (docs/design/ppr-shell-resume.md), the capture Flight render serializes ring-3
+ * cached segments that are ALREADY serialized, so it emits the whole shell payload
+ * in the first tick and the gate declares quiesce almost immediately (~a few ms).
+ * On the old fresh-execution path the Flight dribbled out as handlers ran, so
+ * Flight-quiet effectively meant "the shell has rendered" and 2 hops sufficed.
+ *
+ * Hops alone are NOT render-readiness: fizz cannot emit even <html> until the
+ * payload root settles, nor complete a shell whose client components are
+ * still loading — real module-runner I/O in dev (100ms+ cold), which no fixed
+ * count of near-zero-cost task hops can buy. captureShellHTML therefore
+ * awaits the payload-settled signal (SsrRootOptions.onPayloadSettled) and
+ * then the client-reference loads in flight in the isolate (captureClientLoads),
+ * deadline-bounded, between quiesce and these hops; the hops then only flush
+ * the settled tree and mark pending boundaries POSTPONED. Still task-based
+ * (masked loaders never emit, so more hops never lets a hole settle). Bounded
+ * by maxWaitMs end to end.
+ */
+export const POST_QUIESCE_TASK_HOPS = 16;
+
 /**
  * Hard cap on one capture TASK — runShellCapture end to end (both attempts +
  * the in-place retry delay). SHELL_CAPTURE_MAX_WAIT_MS arms only inside