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

package/src/rsc/shell-serve.ts

@@ -0,0 +1,124 @@
+/**
+ * Integrated PPR shell serving (Axis 2, see docs/design/ppr-shell-resume.md).
+ *
+ * PPR is opt-in per PAGE ROUTE via the `ppr` path option
+ * (`path(pattern, Handler, { name, ppr: true | PartialPrerenderProps })`) and the
+ * serving logic is INTEGRAL to the render pipeline — there is no middleware to
+ * mount. This module owns the config/key/store plumbing the render layer
+ * (rsc-rendering.ts) uses at its COMMIT POINT, which sits after the WHOLE
+ * middleware chain (global `router.use()` chain AND route DSL `middleware()`,
+ * both of which wrap the render pass): any middleware rejection/redirect wins
+ * before a single shell byte is written.
+ *
+ * The shell store is the app-level `createRouter({ cache })` store
+ * (`requestCtx._cacheStore`). A store without the `getShell`/`putShell` family
+ * degrades a ppr route to axis 1 with a once-per-key warning (the declared
+ * intent cannot be honored — unlike an undeclared route, which is silent).
+ */
+
+import React from "react";
+import type { EntryData } from "../server/context.js";
+import { sortedSearchString } from "../cache/cache-key-utils.js";
+import type { ShellCacheEntry, SegmentCacheStore } from "../cache/types.js";
+
+/** Debug/status header the browser (and e2e assertions) can read: HIT | MISS. */
+export const SHELL_STATUS_HEADER = "x-rango-shell";
+
+/**
+ * Default shell ttl (seconds) for `ppr: true` and for a PartialPrerenderProps
+ * that omits `ttl`.
+ */
+export const DEFAULT_PPR_TTL_SECONDS = 300;
+
+/** The route's ppr option normalized to a concrete policy. */
+export interface ResolvedPprConfig {
+  ttl: number;
+  swr?: number;
+  tags?: string[];
+}
+
+/**
+ * Normalize the matched page route's `ppr` path option. Returns null when the
+ * route does not declare `ppr` (or declares `ppr: false`) — the caller then does
+ * NOTHING: no store read, no capture, no logs. Pure axis 1, zero cost.
+ *
+ * PPR is a DOCUMENT-level property of the page route; there is no subtree
+ * inheritance (declaring it on a layout is not supported — a follow-up).
+ */
+export function resolvePprConfig(
+  entry: EntryData | undefined | null,
+): ResolvedPprConfig | null {
+  if (!entry || entry.type !== "route") return null;
+  const ppr = entry.ppr;
+  if (ppr === undefined || ppr === false) return null;
+  if (ppr === true) return { ttl: DEFAULT_PPR_TTL_SECONDS };
+  return {
+    ttl: ppr.ttl ?? DEFAULT_PPR_TTL_SECONDS,
+    swr: ppr.swr,
+    tags: ppr.tags,
+  };
+}
+
+/**
+ * Shell cache key: host + pathname + sorted search + a `:shell` namespace suffix
+ * (so it can never collide with a document-cache key; the store further isolates
+ * the shell family internally).
+ *
+ * The 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.
+ */
+export function buildShellKey(url: URL): string {
+  const sorted = sortedSearchString(url.searchParams);
+  const searchSuffix = sorted ? `?${sorted}` : "";
+  return `${url.host}${url.pathname}${searchSuffix}:shell`;
+}
+
+/**
+ * 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 — the recapture
+ * overwrites the same key and the entry otherwise ages out via TTL.
+ */
+export function isValidShellHit(entry: ShellCacheEntry): boolean {
+  return entry.reactVersion === React.version;
+}
+
+/** Decode a base64 prelude back into bytes for stream composition. */
+export 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;
+}
+
+/** True when the store implements the shell entry family. */
+export function hasShellFamily(
+  store: SegmentCacheStore | undefined,
+): store is SegmentCacheStore & {
+  getShell: NonNullable<SegmentCacheStore["getShell"]>;
+  putShell: NonNullable<SegmentCacheStore["putShell"]>;
+} {
+  return !!store?.getShell && !!store?.putShell;
+}
+
+/** Keys already warned about a missing shell store family (once per key). */
+const warnedMissingStore = new Set<string>();
+
+/**
+ * Warn once per key that a route declared `ppr` but the app-level cache store
+ * does not implement the shell family (getShell/putShell), so the route stays on
+ * axis 1. Unlike an undeclared route (silent), a declared route that cannot be
+ * honored deserves a diagnostic.
+ */
+export function warnShellStoreMissingOnce(key: string): void {
+  if (warnedMissingStore.has(key)) return;
+  warnedMissingStore.add(key);
+  console.warn(
+    `[rango] Route for "${key}" declares the ppr path option, but the app-level ` +
+      "cache store does not implement the shell family (getShell/putShell), so " +
+      "the route is served on axis 1 without a shell. Use MemorySegmentCacheStore, " +
+      "CFCacheStore, or VercelCacheStore (or add the family to your custom store) " +
+      "via createRouter({ cache }).",
+  );
+}

package/src/server/context.ts

@@ -233,6 +233,13 @@ export type EntryData =
       staticHandlerId?: string;
       /** Response type for non-RSC routes (json, text, image, any) */
       responseType?: string;
+      /**
+       * PPR (partial pre-rendering) opt-in from the path() `ppr` option. A
+       * document-level property of the page route: `true` uses the default
+       * shell policy, an object carries ttl/swr/tags. Read by the integrated
+       * PPR serve path (rsc/shell-serve.ts resolvePprConfig).
+       */
+      ppr?: boolean | import("../urls/pattern-types.js").PartialPrerenderProps;
     } & EntryPropCommon &
       EntryPropDatas &
       EntryPropSegments &

package/src/server/request-context.ts

@@ -50,7 +50,6 @@ import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
 import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
 import type { TransitionWhenFn } from "../types/segments.js";
 import type { ResolvedTracing } from "../router/tracing.js";
-import { fireAndForgetWaitUntil } from "../types/request-scope.js";
 import {
   THEME_COOKIE,
   isValidTheme,
@@ -174,49 +173,17 @@ export interface RequestContext<
   /** @internal Cache store for segment caching (optional, used by CacheScope) */
   _cacheStore?: SegmentCacheStore;
 
-  /**
-   * @internal PPR shell-resume signal. Set by the shell-cache middleware on a
-   * validated shell HIT before it awaits next(); read in the render orchestration
-   * (rsc-rendering) to call the resume strategy instead of a full fizz render. The
-   * middleware sets it optimistically — the render layer is the final authority
-   * (nonce/formState/allReady bypass) and marks the response only when it actually
-   * resumed. Single-request; the middleware clears it in a finally.
-   */
-  _shellResume?: { postponed: string | null };
-
-  /**
-   * @internal PPR shell-capture DESCRIPTOR ("a capture of this document is
-   * wanted"). Set by the shell-cache middleware BEFORE its single foreground
-   * next() on a MISS or SWR stale hit, and read by the render orchestration
-   * (rsc-rendering) AFTER the response is built to schedule a background capture
-   * task. Its mere presence must NOT change the foreground render — loader
-   * masking and the cookie/header capture guard key off `_shellCaptureRun`, not
-   * this descriptor. `store` carries the SAME store the middleware resolved for
-   * its getShell read (options.store ?? _cacheStore), so a store-attached
-   * middleware writes captures where it reads them; without it an explicit
-   * options.store distinct from the app-level _cacheStore would read one store
-   * and write another and the shell would never HIT. `tags` is left unset here —
-   * the background capture collects the shell's own (non-loader) request tags
-   * from its derived render. Single-request; the middleware clears it in a
-   * finally after next() settles.
-   */
-  _shellCapture?: {
-    key: string;
-    ttl?: number;
-    swr?: number;
-    tags?: string[];
-    store?: SegmentCacheStore<any>;
-  };
-
   /**
    * @internal PPR shell-capture ACTIVE marker. True ONLY inside the background
    * capture task's derived request context (built by shell-capture.ts). This is
    * the switch every capture-specific behavior reads: loader masking
    * (loader-mask.ts isShellCaptureActive / fresh.ts emitStreaming) and the
    * cookies()/headers() capture guard (cookie-store.ts
-   * assertNotInsideShellCapture). The foreground render never sets it — even when
-   * `_shellCapture` (the "capture wanted" descriptor) is present — so the served
-   * response is byte-identical to axis 1.
+   * assertNotInsideShellCapture). The foreground render never sets it, so the
+   * served response is byte-identical to axis 1. The capture descriptor itself
+   * (key/ttl/swr/tags/store) is NOT threaded through the request context — the
+   * integrated PPR serve path (rsc/shell-serve.ts + rsc-rendering.ts) builds it
+   * locally and passes it to scheduleShellCapture directly.
    */
   _shellCaptureRun?: boolean;
 
@@ -267,6 +234,19 @@ export interface RequestContext<
   /** @internal Registered onResponse callbacks */
   _onResponseCallbacks: Array<(response: Response) => Response>;
 
+  /**
+   * @internal Promises of the background tasks scheduled via this context's
+   * waitUntil (deferred cache writes, revalidations, consumer tasks). The PPR
+   * shell capture drains this list BEFORE its match/render as an ORDERING EDGE:
+   * every foreground deferred cache write is scheduled here before the capture
+   * task is, so settling the list first guarantees the capture's cache reads
+   * observe the foreground's generation instead of racing it (see
+   * shell-capture.ts). Tasks whose scheduling fn carries
+   * UNTRACKED_BACKGROUND_TASK are not tracked (the capture task itself —
+   * tracking it would make that drain await its own promise).
+   */
+  _pendingBackgroundTasks?: Array<Promise<unknown>>;
+
   /**
    * Current theme setting (only available when theme is enabled in router config)
    *
@@ -495,8 +475,6 @@ export type PublicRequestContext<
   | "_handleStore"
   | "_transitionWhen"
   | "_cacheStore"
-  | "_shellResume"
-  | "_shellCapture"
   | "_shellCaptureRun"
   | "_explicitTaggedStores"
   | "_requestTags"
@@ -535,6 +513,17 @@ export type PublicRequestContext<
   | "res"
 >;
 
+/**
+ * Marker for a waitUntil-scheduled fn whose task promise must NOT enter
+ * _pendingBackgroundTasks. Used by the PPR shell capture for its own task:
+ * the capture's pre-render write barrier settles that list, so tracking the
+ * capture itself would make the drain wait on its own (still-running) promise.
+ * @internal
+ */
+export const UNTRACKED_BACKGROUND_TASK: unique symbol = Symbol.for(
+  "rango.untrackedBackgroundTask",
+);
+
 // AsyncLocalStorage instance for request context
 const requestContextStorage = new AsyncLocalStorage<RequestContext<any>>();
 
@@ -946,20 +935,37 @@ export function createRequestContext<TEnv>(
     _cacheProfiles: cacheProfiles,
 
     waitUntil(fn: () => Promise<void>): void {
+      // Wrap in Promise.resolve().then(fn) so a SYNCHRONOUS throw in a
+      // non-async callback becomes a rejected promise handed to the host's
+      // waitUntil (logged as a background failure), instead of escaping into
+      // the request flow. Mirrors fireAndForgetWaitUntil's deferral.
+      const task = Promise.resolve().then(fn);
+      // Track the task promise so the PPR shell capture can settle the
+      // foreground's deferred cache writes before its own match/render (the
+      // ordering edge; see _pendingBackgroundTasks). The capture task itself
+      // opts out via the marker — the drain must never await its own promise.
+      if (
+        !(fn as { [UNTRACKED_BACKGROUND_TASK]?: boolean })[
+          UNTRACKED_BACKGROUND_TASK
+        ]
+      ) {
+        ctx._pendingBackgroundTasks?.push(task);
+      }
       if (executionContext?.waitUntil) {
-        // Wrap in Promise.resolve().then(fn) so a SYNCHRONOUS throw in a
-        // non-async callback becomes a rejected promise handed to the host's
-        // waitUntil (logged as a background failure), instead of escaping into
-        // the request flow. Mirrors fireAndForgetWaitUntil's deferral.
-        executionContext.waitUntil(Promise.resolve().then(fn));
+        executionContext.waitUntil(task);
       } else {
-        fireAndForgetWaitUntil(fn);
+        // Node/dev fallback: fire-and-forget with error logging (the same
+        // policy fireAndForgetWaitUntil applies).
+        task.catch((err) =>
+          console.error("[waitUntil] Background task failed:", err),
+        );
       }
     },
 
     executionContext,
 
     _onResponseCallbacks: [],
+    _pendingBackgroundTasks: [],
 
     onResponse(callback: (response: Response) => Response): void {
       assertNotInsideCacheExec(ctx, "onResponse");

package/src/ssr/index.tsx

@@ -173,13 +173,25 @@ export interface SSRDependencies<TEnv = unknown> {
 const DEFAULT_SHELL_CAPTURE_MAX_WAIT_MS = 5000;
 
 /**
- * Fixed number of macrotask hops between `quiesce` resolving and the abort. By
- * the time `quiesce` resolves the Flight input is byte-quiet and frozen, so
- * these hops are deterministic: they only give React's fizz worker turns to
- * flush the settled shell and mark still-pending boundaries as POSTPONED (rather
- * than errored) before controller.abort() lands. Not a wall-clock wait.
+ * 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.
+ *
+ * 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. Under
+ * replay, Flight-quiet fires BEFORE the fizz side has consumed the instant payload
+ * and rendered the shell to `<body>`, so the fizz needs a real buffer of turns after
+ * quiesce — otherwise the abort lands on an unrendered tree (empty prelude, root
+ * postpone) and the sanity gate refuses. Still task-based (masked loaders never
+ * emit, so more hops never lets a hole settle); a cold worker whose first
+ * attempt still under-renders heals on the in-place retry. Bounded by maxWaitMs.
  */
-const POST_QUIESCE_TASK_HOPS = 2;
+const POST_QUIESCE_TASK_HOPS = 16;
 
 /**
  * Route an SSR error through the deps.onError notification callback with the
@@ -398,6 +410,7 @@ export function createShellCaptureHandler<TEnv = unknown>(
 ) {
   const { createFromReadableStream, loadBootstrapScriptContent, prerender } =
     deps;
+  const onError = deps.onError;
 
   if (!prerender) {
     throw new Error(
@@ -437,6 +450,25 @@ export function createShellCaptureHandler<TEnv = unknown>(
     const prerenderPromise = prerender(<SsrRoot />, {
       signal: controller.signal,
       bootstrapScriptContent,
+      // Abort is how capture WORKS: once the shell is quiet we abort() to freeze
+      // the prelude and let the still-pending holes postpone. React reports the
+      // abort reason for each pending boundary through onError. Without an onError
+      // here React falls back to console.error, so every capture that still has a
+      // live hole at abort time (the normal case, and every cold-module capture
+      // where the shell is not yet done) dumps a DOMException [AbortError] stack —
+      // once per pending boundary. That is EXPECTED degradation, not a failure, so
+      // swallow the abort here. Genuine shell render errors (a component throwing)
+      // are NOT the abort and still surface through the deps.onError channel, the
+      // same one renderHTML uses. See docs/design/ppr-shell-resume.md.
+      onError: (error: unknown) => {
+        if (
+          controller.signal.aborted &&
+          (error as { name?: string } | null)?.name === "AbortError"
+        ) {
+          return;
+        }
+        reportRenderError(onError, error);
+      },
     });
 
     // Wait for the caller's quiesce signal. By the time it resolves the Flight

package/src/theme/ThemeProvider.tsx

@@ -109,27 +109,6 @@ function applyThemeToDocument(theme: Theme, config: ResolvedThemeConfig): void {
   }
 }
 
-function getStoredTheme(config: ResolvedThemeConfig): Theme {
-  const { storageKey, themes, defaultTheme, enableSystem } = config;
-
-  let stored = readThemeFromCookie(storageKey);
-
-  if (!stored) {
-    stored = readThemeFromStorage(storageKey);
-  }
-
-  if (stored) {
-    if (stored === "system" && enableSystem) {
-      return "system";
-    }
-    if (themes.includes(stored)) {
-      return stored as Theme;
-    }
-  }
-
-  return defaultTheme;
-}
-
 export function ThemeProvider({
   config,
   initialTheme,
@@ -137,17 +116,48 @@ export function ThemeProvider({
 }: ThemeProviderProps): React.ReactNode {
   const [mounted, setMounted] = useState(false);
 
-  const [theme, setThemeState] = useState<Theme>(() => {
-    if (initialTheme) return initialTheme;
-    if (typeof window === "undefined") return config.defaultTheme;
-    return getStoredTheme(config);
-  });
+  // HYDRATION PARITY: this initializer is the server (SSR/resume) render AND
+  // the client's hydration render — both must produce the same value. It must
+  // NEVER read cookie/localStorage: whenever the payload's initialTheme
+  // differs from the visitor's stored theme (a PPR shell HIT deliberately
+  // replays the CAPTURE's initialTheme), a storage-reading initializer makes
+  // the client's first render diverge from the server tree. Any raw-theme text
+  // (a toggle label) then fails hydration, React regenerates the tree, and the
+  // FOUC-applied class is wiped from <html>. The visitor's stored theme is
+  // applied by the post-mount re-sync effect below instead.
+  const [theme, setThemeState] = useState<Theme>(
+    () => initialTheme ?? config.defaultTheme,
+  );
 
   const [systemTheme, setSystemTheme] = useState<ResolvedTheme>("light");
 
   useEffect(() => {
     setMounted(true);
     setSystemTheme(getSystemTheme());
+    // Re-sync state from an EXPLICITLY stored theme after mount. initialTheme
+    // comes from the payload and can legitimately differ from the visitor's
+    // stored theme — on a PPR shell HIT it is deliberately the CAPTURE's theme
+    // (the resume tree must match the frozen prelude; see
+    // ShellCacheEntry.initialTheme). The FOUC script already applied the stored
+    // theme to the document pre-paint; this brings the provider state (toggles,
+    // useTheme readers) in line with it, and is the ONLY place the provider
+    // reads storage (the initializer must not — see the parity note above).
+    // Only an explicit cookie/localStorage value re-syncs — a defaultTheme
+    // fallback must not override a server-provided initialTheme when the
+    // visitor never chose a theme.
+    // First VALID candidate wins — an empty/garbage cookie value (e.g. a
+    // deleted cookie leaving "theme=") must not shadow a valid localStorage
+    // value behind a bare null-coalesce.
+    const explicit =
+      [
+        readThemeFromCookie(config.storageKey),
+        readThemeFromStorage(config.storageKey),
+      ].find((v) => v !== null && isValidTheme(v, config)) ?? null;
+    if (explicit !== null && explicit !== theme) {
+      setThemeState(explicit as Theme);
+      applyThemeToDocument(explicit as Theme, config);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
   const setTheme = useCallback(

package/src/urls/index.ts

@@ -11,6 +11,7 @@ export type {
   UnnamedRoute,
   LocalOnlyInclude,
   PathOptions,
+  PartialPrerenderProps,
   UrlPatterns,
   IncludeOptions,
 } from "./pattern-types.js";

package/src/urls/path-helper.ts

@@ -175,6 +175,11 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       ...(resolveResponseType(options)
         ? { responseType: resolveResponseType(options) }
         : {}),
+      // PPR shell-caching opt-in (document-level). Stored raw; the integrated
+      // serve path normalizes it via resolvePprConfig (rsc/shell-serve.ts).
+      ...(options?.ppr !== undefined && options.ppr !== false
+        ? { ppr: options.ppr }
+        : {}),
     };
 
     if (isStaticHandler(handler) && handler.$$id && ctx.namePrefix) {

package/src/urls/pattern-types.ts

@@ -35,12 +35,48 @@ export type LocalOnlyInclude = string & { [LOCAL_ONLY_BRAND]: void };
 /**
  * Options for path() function
  */
+/**
+ * Options for the `ppr` path option (PPR shell caching — Axis 2, see
+ * docs/design/ppr-shell-resume.md and the /ppr skill). Declaring
+ * `ppr: true | PartialPrerenderProps` on a page route opts that DOCUMENT into
+ * shell capture: the rendered HTML shell (everything that is not a live hole) is
+ * cached and, on a later GET, flushed immediately while fizz resumes only the
+ * holes. Serving is integral to the router — there is no middleware to mount;
+ * the shell store is the app-level `createRouter({ cache })` store (which must
+ * implement the `getShell`/`putShell` family).
+ */
+export interface PartialPrerenderProps {
+  /**
+   * Shell time-to-live in seconds. Defaults to 300 (`ppr: true` uses the same
+   * default).
+   */
+  ttl?: number;
+  /**
+   * Stale-while-revalidate window in seconds: a stale shell is still served
+   * while a background recapture refreshes it.
+   */
+  swr?: number;
+  /**
+   * Operational tags attached to the captured shell entry for
+   * `updateTag()`/`revalidateTag()`-driven eviction. UNIONED with the tags the
+   * capture render auto-collects (the shell's own non-loader request tags).
+   */
+  tags?: string[];
+}
+
 export interface PathOptions<
   TName extends string = string,
   TSearch extends SearchSchema = {},
 > {
   /** Route name for href() lookups */
   name?: TName;
+  /**
+   * PPR shell caching opt-in for this page route (document-level). `true` uses
+   * the default policy (ttl 300); an object sets ttl/swr/tags. See
+   * {@link PartialPrerenderProps}. Routes without this option are pure axis 1 —
+   * no capture, no store reads, no logs.
+   */
+  ppr?: boolean | PartialPrerenderProps;
   /** Search param schema for typed query parameters */
   search?: TSearch;
   /** Trailing slash behavior: "never" (redirect /path/ to /path), "always" (redirect /path to /path/), "ignore" (match both) */