@rangojs/router 0.0.0-experimental.ea6d5eec → 0.0.0-experimental.ea9f40f2

package/src/rsc/shell-serve.ts

@@ -0,0 +1,181 @@
+/**
+ * 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`;
+}
+
+/**
+ * Version gates for a stored shell: reactVersion AND buildVersion must both
+ * match the running server. The postponed blob encodes hole positions against
+ * one exact tree, so resuming it under a different React OR a different app
+ * build tree-mismatches inside resume() — after the 200 + prelude committed,
+ * with no recovery. Either mismatch is a miss: the recapture overwrites the
+ * same key (self-healing) and the entry otherwise ages out via TTL. An entry
+ * with no buildVersion (stored before the field existed) is a miss for the
+ * same reason — its build is unknown, so it cannot be proven resumable.
+ */
+export function isValidShellHit(
+  entry: ShellCacheEntry,
+  buildVersion: string,
+): boolean {
+  return (
+    entry.reactVersion === React.version && entry.buildVersion === buildVersion
+  );
+}
+
+/**
+ * Payload integrity gate, run BEFORE the HIT response commits: a stored entry
+ * whose prelude is not decodable base64 or whose postponed blob is not
+ * parseable JSON would otherwise throw AFTER the 200 + full static prelude
+ * flushed (`serveShellHit` decodes at stream construction, `resumeShellHTML`
+ * parses in the tail) — the client gets a visually complete page that never
+ * hydrates, re-served on every request until the entry ages out (no eviction
+ * path exists; failure schedules no recapture by itself). Checking here turns
+ * a corrupt entry (store-layer fault) into a plain MISS the recapture
+ * overwrites. Cost: one duplicate decode/parse per HIT, sub-ms against a
+ * prelude flush that dominates the path.
+ */
+export function hasIntactShellPayload(entry: ShellCacheEntry): boolean {
+  try {
+    base64ToBytes(entry.prelude);
+    if (entry.postponed !== null) JSON.parse(entry.postponed);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 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 }).",
+  );
+}
+
+/** Keys already warned about an active per-request nonce (once per key). */
+const warnedNonceActive = new Set<string>();
+
+/**
+ * Warn once per key that a route declared `ppr` but a per-request CSP nonce is
+ * active for the request, so the route stays on axis 1 (a shared shell would
+ * freeze one request's nonce for every visitor — useNonce() renders it into every
+ * nonced script/style/meta and the browser's CSP would then reject the frozen
+ * nonce for all but the capture request). The nonce blocks capture whether it came
+ * from the `createRouter({ nonce })` provider or from a direct `ctx.set(nonce, …)`
+ * token write in middleware. Same declared-intent-cannot-be-honored doctrine as
+ * the missing-store warning above (an undeclared route stays silent).
+ */
+export function warnPprNonceActiveOnce(key: string): void {
+  if (warnedNonceActive.has(key)) return;
+  warnedNonceActive.add(key);
+  console.warn(
+    `[rango] Route for "${key}" declares the ppr path option, but a per-request ` +
+      "CSP nonce is active for this request (from createRouter({ nonce }) or a " +
+      "ctx.set(nonce, …) token write in middleware), so the route is served on " +
+      "axis 1 without a shell. A shell is shared per host+URL; baking one " +
+      "request's nonce into it would break CSP for every other visitor. Drop the " +
+      "ppr option on this route, or stop setting a per-request nonce for it.",
+  );
+}

package/src/rsc/ssr-setup.ts

@@ -77,7 +77,7 @@ export function getSSRSetup<TEnv>(
   url: URL,
   metricsStore: MetricsStore | undefined,
 ): Promise<SSRSetup> {
-  const early = _getRequestContext()?.var?.[SSR_SETUP_VAR] as
+  const early = _getRequestContext()?._variables?.[SSR_SETUP_VAR] as
     | Promise<SSRSetup>
     | undefined;
   if (early) return early;
@@ -98,7 +98,7 @@ export function getSSRSetup<TEnv>(
  * the isRscRequest decision in rsc-rendering.ts.
  *
  * Note: response/mime routes are excluded by the caller — this function
- * runs after previewMatch() classifies the route type.
+ * runs after classifyRequest() determines the request mode.
  */
 export function mayNeedSSR(request: Request, url: URL): boolean {
   if (
@@ -126,3 +126,19 @@ export function mayNeedSSR(request: Request, url: URL): boolean {
 
   return true;
 }
+
+// Final render-time decision: is the response an RSC stream (vs HTML)? Distinct
+// from mayNeedSSR, which is a conservative pre-classifier (it treats a missing
+// Accept header as needing SSR; this treats it as RSC).
+export function isRscRequest(
+  request: Request,
+  url: URL,
+  isPartial: boolean,
+): boolean {
+  return (
+    isPartial ||
+    (!request.headers.get("accept")?.includes("text/html") &&
+      !url.searchParams.has("__html")) ||
+    url.searchParams.has("__rsc")
+  );
+}

package/src/rsc/transition-gate.ts

@@ -0,0 +1,89 @@
+import type { MatchResult } from "../types.js";
+import type { TransitionWhenContext } from "../types/segments.js";
+import type { getRequestContext } from "../server/request-context.js";
+import { invokeOnError } from "../router/error-handling.js";
+import type { OnErrorCallback } from "../types/error-types.js";
+
+/**
+ * Apply transition({ when }) gates to a payload's segments.
+ *
+ * The predicates were collected during resolution (keyed by segment id) and
+ * stripped from the serialized config; here — after handlers ran and outside any
+ * cache scope — we evaluate each and drop the segment's transition when the
+ * predicate does not hold, so the navigation streams its loading fallback
+ * instead of holding the previous content. A predicate that throws is reported
+ * to the router's onError (phase "rendering") and then treated as "do not hold"
+ * (conservative), so a buggy predicate degrades to no transition rather than
+ * failing the response.
+ *
+ * Mutating the segments here is safe: the segment cache stores a serialized copy
+ * (segment-codec), written during match() BEFORE this gate runs, so dropping a
+ * transition never corrupts a cache entry. The flip side is that a cache hit
+ * skips resolution, collects no predicate, and replays the cached transition
+ * as-is (it was serialized before the gate) — combining transition({ when })
+ * with cache() on the same segment freezes the gate to its cached state, so
+ * avoid caching a route whose transition decision is request-dependent.
+ *
+ * Returns the same array (mutated) for inline use at the payload's `segments`
+ * field.
+ */
+export function gateTransitions(
+  segments: MatchResult["segments"],
+  ctx: ReturnType<typeof getRequestContext>,
+  onError?: OnErrorCallback,
+): MatchResult["segments"] {
+  const predicates = ctx._transitionWhen;
+  if (predicates && predicates.length) {
+    for (const { id, when } of predicates) {
+      let drop: boolean;
+      try {
+        // Assemble the ShouldRevalidateFn-shaped predicate context from the
+        // request context. Source fields (currentUrl/currentParams/fromRouteName)
+        // were stashed at match time from the navigation snapshot; action fields
+        // at the action-bearing gate call sites. nextUrl/nextParams/toRouteName/
+        // method/get/env come straight off ctx (setRequestContextParams ran
+        // before the gate). Source/action fields are undefined when absent —
+        // never fabricated (see TransitionWhenContext).
+        const whenCtx: TransitionWhenContext = {
+          currentUrl: ctx._gateCurrentUrl,
+          currentParams: ctx._gateCurrentParams,
+          fromRouteName:
+            ctx._prevRouteKey as TransitionWhenContext["fromRouteName"],
+          nextUrl: ctx.url,
+          nextParams: ctx.params,
+          toRouteName: ctx.routeName,
+          actionId: ctx._gateActionId,
+          actionUrl: ctx._gateActionUrl,
+          actionResult: ctx._gateActionResult,
+          formData: ctx._gateFormData,
+          method: ctx.request.method,
+          get: ctx.get,
+          env: ctx.env,
+        };
+        drop = when(whenCtx) === false;
+      } catch (error) {
+        // A throwing predicate must not fail the response: report it and treat
+        // the transition as gated off (do not hold). invokeOnError no-ops when
+        // onError is undefined.
+        drop = true;
+        invokeOnError(
+          onError,
+          error,
+          "rendering",
+          {
+            request: ctx.request,
+            url: ctx.url,
+            params: ctx.params,
+            segmentId: id,
+          },
+          "RSC",
+        );
+      }
+      if (drop) {
+        const seg = segments.find((s) => s.id === id);
+        if (seg) seg.transition = undefined;
+      }
+    }
+  }
+  return segments;
+}

package/src/rsc/types.ts

@@ -7,7 +7,7 @@
 
 import type { ResolvedSegment, SlotState } from "../types.js";
 import type { HandleData } from "../server/handle-store.js";
-import type { RSCRouterInternal } from "../router/router-interfaces.js";
+import type { RangoInternal } from "../router/router-interfaces.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 
 /**
@@ -19,10 +19,19 @@ export interface RscPayload {
   metadata?: {
     pathname: string;
     segments: ResolvedSegment[];
+    /** Router instance ID. When this changes between navigations, the client
+     *  discards cached segments and does a full tree replacement (app switch). */
+    routerId?: string;
     isPartial?: boolean;
     isError?: boolean;
     matched?: string[];
     diff?: string[];
+    /**
+     * All segment ids re-resolved on the server, including null-component
+     * ones excluded from `segments`/`diff`. Drives client-side handle-bucket
+     * cleanup. Superset of `diff`. See MatchResult.resolvedIds.
+     */
+    resolvedIds?: string[];
     /** Merged route params from the matched route */
     params?: Record<string, string>;
     slots?: Record<string, SlotState>;
@@ -34,19 +43,37 @@ export interface RscPayload {
     version?: string;
     /** TTL in milliseconds for the client-side in-memory prefetch cache */
     prefetchCacheTTL?: number;
+    /** Max entries in the client-side in-memory prefetch cache (FIFO eviction) */
+    prefetchCacheSize?: number;
+    /** Max concurrent speculative prefetch requests on the client */
+    prefetchConcurrency?: number;
+    /** Server-resolved rango state cookie name; the client reads it verbatim. */
+    stateCookieName?: string;
     /** Theme configuration for FOUC prevention */
     themeConfig?: ResolvedThemeConfig | null;
     /** Initial theme from cookie (for SSR hydration) */
     initialTheme?: Theme;
+    /** URL prefix for all routes (from createRouter({ basename })). */
+    basename?: string;
     /** Whether connection warmup is enabled */
     warmupEnabled?: boolean;
-    /** Server-side redirect with optional state (for partial requests) */
-    redirect?: { url: string };
+    /**
+     * Whether the client should hydrate inside React.StrictMode. Carried on
+     * the initial full-render payload only; the browser entry reads it once at
+     * hydration. Absent on partial (navigation) payloads. Defaults to true on
+     * the client when omitted.
+     */
+    strictMode?: boolean;
+    /**
+     * Server-side redirect with optional state (for partial requests).
+     * `external: true` (from redirect(url, { external: true })) tells the client
+     * to hard-navigate to an off-host target instead of validating same-origin.
+     */
+    redirect?: { url: string; external?: boolean };
     /** Server-set location state to include in history.pushState */
     locationState?: Record<string, unknown>;
   };
   returnValue?: { ok: boolean; data: unknown };
-  formState?: unknown;
 }
 
 /**
@@ -63,7 +90,10 @@ export interface RSCDependencies {
    */
   renderToReadableStream: <T>(
     payload: T,
-    options?: { temporaryReferences?: unknown },
+    options?: {
+      temporaryReferences?: unknown;
+      onError?: (error: unknown) => string | void;
+    },
   ) => ReadableStream<Uint8Array>;
 
   /**
@@ -134,6 +164,32 @@ export interface SSRModule {
     rscStream: ReadableStream<Uint8Array>,
     options?: SSRRenderOptions,
   ) => Promise<ReadableStream<Uint8Array>>;
+
+  /**
+   * PPR shell CAPTURE strategy (Axis 2). Prerenders the loader-masked shell over
+   * the Flight stream, aborts once quiescent, and returns the prelude bytes plus
+   * the postponed resume state — or null when the prelude degraded and must not
+   * be stored. Present only when the SSR virtual entry wires
+   * createShellCaptureHandler; the render layer feature-detects it. See
+   * docs/design/ppr-shell-resume.md.
+   */
+  captureShellHTML?: (
+    rscStream: ReadableStream<Uint8Array>,
+    options: { quiesce: Promise<void>; maxWaitMs?: number },
+  ) => Promise<{ prelude: Uint8Array; postponed: string | null } | null>;
+
+  /**
+   * PPR shell RESUME strategy (Axis 2). Produces the per-request live portion of
+   * the document: resumes fizz over a fresh SsrRoot to emit only the postponed
+   * holes (or, for the DATA variant with postponed === null, just the fresh Flight
+   * payload scripts). The caller prepends the stored prelude bytes to form the
+   * composite response. Present only when the SSR virtual entry wires
+   * createShellResumeHandler; the render layer feature-detects it.
+   */
+  resumeShellHTML?: (
+    rscStream: ReadableStream<Uint8Array>,
+    options: { postponed: string | null; nonce?: string },
+  ) => Promise<ReadableStream<Uint8Array>>;
 }
 
 /**
@@ -171,7 +227,7 @@ export interface CreateRSCHandlerOptions<
   /**
    * The RSC router instance
    */
-  router: RSCRouterInternal<TEnv, TRoutes>;
+  router: RangoInternal<TEnv, TRoutes>;
 
   /**
    * RSC dependencies from @vitejs/plugin-rsc/rsc.

package/src/runtime-env.ts

@@ -0,0 +1,18 @@
+// Runtime-safe detection of a test runner (Vitest), used to decide whether a
+// create*() call with no plugin-injected $$id may fall back to a synthetic id (a
+// bare test) or must fail loud (dev / a real build).
+//
+// `process` is absent in some target runtimes (the browser, certain edge/worker
+// RSC environments), so probe it through `globalThis` with optional chaining —
+// NEVER a bare `process.env.VITEST`, which would ReferenceError before the
+// intended error is thrown. Unlike `process.env.NODE_ENV` (folded by the app's
+// build `define`), `VITEST` is not folded, so this stays a small runtime check;
+// it lives only on the create*() error path (id missing), which never runs in a
+// correct production build.
+//
+// Vitest sets `VITEST` in every test process — the node project and the
+// react-server forks alike (the RSC project forces NODE_ENV=production, so NODE_ENV
+// cannot distinguish it from a real build; `VITEST` can). A real build never sets it.
+export function isUnderTestRunner(): boolean {
+  return !!globalThis.process?.env?.VITEST;
+}

package/src/search-params.ts

@@ -7,9 +7,16 @@
  * URLSearchParams instance.
  */
 
-// ============================================================================
-// Schema Types
-// ============================================================================
+import { encodeKV } from "./encode-kv.js";
+
+/**
+ * Decimal-number grammar for `"number"` search params: optional sign, digits
+ * with optional fraction, optional exponent. Deliberately excludes hex (`0x`),
+ * `Infinity`, and empty/whitespace so `Number()`'s lenient coercions
+ * (`Number("")===0`, `Number("0x10")===16`, `Number("Infinity")===Infinity`)
+ * do not slip non-decimal values into typed search.
+ */
+const DECIMAL_NUMBER_RE = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
 
 /** Supported scalar types for search params (append ? for optional). */
 export type SearchSchemaValue =
@@ -23,10 +30,6 @@ export type SearchSchemaValue =
 /** A search schema maps param names to their type descriptors. */
 export type SearchSchema = Record<string, SearchSchemaValue>;
 
-// ============================================================================
-// Type-Level Schema Resolution
-// ============================================================================
-
 /** Strip trailing `?` from a schema value to get the base type. */
 type BaseType<T extends string> = T extends `${infer B}?` ? B : T;
 
@@ -81,11 +84,11 @@ export type ResolveSearchSchema<T extends SearchSchema> = Simplify<
 // ============================================================================
 
 /** Resolve the global route map from RegisteredRoutes or GeneratedRouteMap. */
-type GlobalRouteMap = keyof RSCRouter.RegisteredRoutes extends never
-  ? keyof RSCRouter.GeneratedRouteMap extends never
+type GlobalRouteMap = keyof Rango.RegisteredRoutes extends never
+  ? keyof Rango.GeneratedRouteMap extends never
     ? Record<string, string>
-    : RSCRouter.GeneratedRouteMap
-  : RSCRouter.RegisteredRoutes;
+    : Rango.GeneratedRouteMap
+  : Rango.RegisteredRoutes;
 
 /**
  * Extract the resolved search params type for a named route.
@@ -163,15 +166,15 @@ type ExtractParamsFromPattern<T extends string> =
             : { [K in Param]: string }
       : {};
 
-// ============================================================================
-// Runtime Parser
-// ============================================================================
-
 /**
  * Parse URLSearchParams into a typed object using the given schema.
  *
  * - `"string"` / `"string?"` - kept as-is
- * - `"number"` / `"number?"` - coerced via `Number()`; NaN treated as missing
+ * - `"number"` / `"number?"` - parsed as a finite decimal number. Accepts an
+ *   optional sign, digits with optional fraction, and optional exponent
+ *   (e.g. `42`, `-3.5`, `1e3`). Empty/whitespace-only, non-decimal forms
+ *   (`0x10`), and non-finite (`Infinity`) are treated as missing (omitted),
+ *   NOT coerced to `0`/`16`/`Infinity`.
  * - `"boolean"` / `"boolean?"` - `"true"` / `"1"` -> true, `"false"` / `"0"` / `""` -> false
  *
  * Missing params (both required and optional) are omitted from the result
@@ -197,11 +200,17 @@ export function parseSearchParams<T extends SearchSchema>(
     if (baseType === "string") {
       result[key] = raw;
     } else if (baseType === "number") {
-      const num = Number(raw);
-      if (!Number.isNaN(num)) {
-        result[key] = num;
+      // Trim, then require a valid decimal numeral and a finite result.
+      // Empty/whitespace, hex (0x10), and Infinity are treated as missing
+      // (omitted) — not coerced to 0/16/Infinity by Number()'s lenient rules.
+      const trimmed = raw.trim();
+      if (trimmed !== "" && DECIMAL_NUMBER_RE.test(trimmed)) {
+        const num = Number(trimmed);
+        if (Number.isFinite(num)) {
+          result[key] = num;
+        }
       }
-      // NaN treated as missing (undefined)
+      // Anything else treated as missing (undefined)
     } else if (baseType === "boolean") {
       result[key] = raw === "true" || raw === "1";
     }
@@ -210,21 +219,17 @@ export function parseSearchParams<T extends SearchSchema>(
   return result as ResolveSearchSchema<T>;
 }
 
-// ============================================================================
-// Runtime Serializer
-// ============================================================================
-
 /**
  * Serialize a typed search params object to a query string (without leading `?`).
- * Skips `undefined` and `null` values.
+ * Skips `undefined` and `null` values. Preserves insertion order (no sort).
  */
 export function serializeSearchParams(params: Record<string, unknown>): string {
-  const parts: string[] = [];
+  // Pre-filter null/undefined and coerce values to strings here so encodeKV
+  // (which never inspects values) reproduces this call site's exact output.
+  const pairs: [string, string][] = [];
   for (const [key, value] of Object.entries(params)) {
     if (value === undefined || value === null) continue;
-    parts.push(
-      `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`,
-    );
+    pairs.push([key, String(value)]);
   }
-  return parts.join("&");
+  return encodeKV(pairs);
 }

package/src/segment-content-promise.ts

@@ -0,0 +1,67 @@
+import type { ReactNode } from "react";
+
+/**
+ * Stable Promise wrappers keyed on the component itself. Objects (React
+ * elements, functions, lazy payloads) land in a WeakMap so entries GC when
+ * the underlying component is released; primitives (string, number, boolean,
+ * null) land in a Map so memoization still applies to text-/null-backed
+ * segments like those in partial-update flows. Keeping this cache outside
+ * the segment eliminates preservation fields on ResolvedSegment — it survives
+ * reconciliation naturally because the component ref is what's stable.
+ *
+ * Browser-only. On the server each SSR render needs a fresh pending promise
+ * so Suspense can emit the loading fallback HTML before content streams. A
+ * shared already-resolved promise has `.status === "fulfilled"` attached by
+ * React on its first observation — subsequent `use()` calls return
+ * synchronously without suspending, so the Suspense fallback never makes it
+ * into the initial HTML. Route-definition components share refs across
+ * requests, so a global cache would leak tracked state between renders.
+ */
+const IS_BROWSER = typeof window !== "undefined";
+const objectContentCache = IS_BROWSER
+  ? new WeakMap<object, Promise<ReactNode>>()
+  : null;
+const primitiveContentCache = IS_BROWSER
+  ? new Map<unknown, Promise<ReactNode>>()
+  : null;
+
+/**
+ * Return a stable Promise wrapping `component`, memoized on the component ref.
+ *
+ * A fresh `Promise.resolve(component)` each render would suspend for one
+ * microtask and briefly commit the loading fallback inside Suspender — the
+ * intercept / parallel-slot flicker this indirection prevents. Reusing the
+ * same Promise ref keeps React's `use()` in "known fulfilled" state after
+ * the first observation.
+ *
+ * @internal
+ */
+export function getMemoizedContentPromise(
+  component: ReactNode,
+): Promise<ReactNode> {
+  if (component instanceof Promise) {
+    return component as Promise<ReactNode>;
+  }
+
+  if (!objectContentCache || !primitiveContentCache) {
+    return Promise.resolve(component);
+  }
+
+  if (component !== null && typeof component === "object") {
+    const cached = objectContentCache.get(component);
+    if (cached) {
+      return cached;
+    }
+    const promise = Promise.resolve(component);
+    objectContentCache.set(component, promise);
+    return promise;
+  }
+
+  const cached = primitiveContentCache.get(component);
+  if (cached) {
+    return cached;
+  }
+  const promise = Promise.resolve(component);
+  primitiveContentCache.set(component, promise);
+  return promise;
+}