@rangojs/router 0.15.1 → 0.17.0

package/src/cache/taint.ts

@@ -1,7 +1,7 @@
 /**
  * Taint symbol for request-scoped objects.
  *
- * Objects branded with NOCACHE_SYMBOL (ctx, env, req) are excluded from
+ * Objects branded with NOCACHE_SYMBOL (ctx objects) are excluded from
  * "use cache" cache keys and trigger handle capture mode so that side
  * effects (breadcrumbs, metadata) are recorded and replayed on cache hit.
  */

package/src/cache/types.ts

@@ -424,9 +424,8 @@ export type DocumentShellCacheEntry = ShellCacheEntry & {
 /**
  * The families a shell snapshot pins. The item/segment/response families are
  * cache-store reads/writes (recorded by RecordingShellStore); the loader family
- * pins the settled CONTAINER of a bake-lane loader (a loader on an entry with
- * no renderable loading(), executed during capture — see
- * docs/design/loader-container-bake.md). Excludes the shell family itself
+ * pins the settled CONTAINER of a bake-lane loader (lane rule: see
+ * resolveLoaderData, loader-cache.ts). Excludes the shell family itself
  * (getShell/putShell) — the snapshot rides INSIDE a shell entry, so recording
  * it would be self-referential.
  */
@@ -542,6 +541,11 @@ export interface CachedEntryData {
    *  (see handle-snapshot.ts encodeHandles) so Promise/ReactNode handle values
    *  round-trip through JSON-serializing stores instead of being flattened. */
   handles: string;
+  /**
+   * Owning loader ids index-aligned with the decoded `handles` values
+   * (HandleOwners). Absent: every value restores as a plain replay.
+   */
+  handleOwners?: HandleOwners;
   /** Expiration timestamp (ms since epoch) */
   expiresAt: number;
   /** Cache tags for invalidation */
@@ -583,3 +587,12 @@ export interface CacheDefaults {
  * Structure: { handleName: [values...] }
  */
 export type SegmentHandleData = Record<string, unknown[]>;
+
+/**
+ * segmentId -> handleName -> the owning loader id of each recorded value, by
+ * index (null: not owned). Only a PPR shell capture writes owners: the
+ * settled pushes of an `ssr: false` loader's own body, which the record keeps
+ * because the prelude rendered them. restoreHandles replays an owned value
+ * through HandleStore.pushReplayed, so that loader's live re-run replaces it.
+ */
+export type HandleOwners = Record<string, Record<string, (string | null)[]>>;

package/src/client.rsc.tsx

@@ -1,7 +1,7 @@
 /**
  * RSC-environment version of client exports
  *
- * This file is used when importing "rsc-router/client" from RSC (server components).
+ * This file is used when importing "@rangojs/router/client" from RSC (server components).
  * It re-exports the server's createLoader so that loader definitions work in both
  * environments with the same import.
  *
@@ -9,6 +9,10 @@
  * in RSC context, while the regular client.tsx is used in client components.
  */
 
+// From html.ts directly, never via ./client.js: every export of that
+// "use client" module is an opaque client reference here.
+import * as Html from "./html.js";
+
 // Re-export everything from client.tsx (Outlet, useLoader, etc.)
 // These are safe to use in RSC context
 export {
@@ -64,7 +68,10 @@ export {
   useLinkStatus,
   type LinkStatus,
 } from "./browser/react/use-link-status.js";
-export { useScrollRestoration } from "./browser/react/ScrollRestoration.js";
+export {
+  useScrollRestoration,
+  type ScrollRestorationProps,
+} from "./browser/react/ScrollRestoration.js";
 
 export {
   Link,
@@ -72,11 +79,6 @@ export {
   type PrefetchStrategy,
 } from "./browser/react/Link.js";
 
-export {
-  ScrollRestoration,
-  type ScrollRestorationProps,
-} from "./browser/react/ScrollRestoration.js";
-
 export {
   NavigationProvider,
   type NavigationProviderProps,
@@ -91,14 +93,13 @@ export { MountContext } from "./browser/react/mount-context.js";
 export { createHandle, isHandle, type Handle } from "./handle.js";
 
 export { Meta } from "./handles/meta.js";
-export { MetaTags } from "./handles/MetaTags.js";
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
 export {
   Script,
   type ScriptConfig,
   type ScriptAttributes,
 } from "./handles/script.js";
-export { Scripts } from "./handles/Scripts.js";
+export { Html };
 export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
 
 export {

package/src/client.tsx

@@ -8,6 +8,9 @@ import {
   Suspense,
   type ReactNode,
 } from "react";
+// Not `export * as Html`: plugin-rsc's "use client" proxy transform only
+// expands bare `export *` and throws on a named one.
+import * as Html from "./html.js";
 import { OutletContext, type OutletContextValue } from "./outlet-context.js";
 import {
   type ClientErrorBoundaryFallbackProps,
@@ -300,7 +303,7 @@ interface ErrorBoundaryState {
  * @example
  * ```tsx
  * "use client";
- * import { ErrorBoundary } from "rsc-router/client";
+ * import { ErrorBoundary } from "@rangojs/router/client";
  *
  * function MyComponent() {
  *   return (
@@ -427,7 +430,6 @@ export {
 } from "./browser/react/use-link-status.js";
 
 export {
-  ScrollRestoration,
   useScrollRestoration,
   type ScrollRestorationProps,
 } from "./browser/react/ScrollRestoration.js";
@@ -436,14 +438,13 @@ export { type Handle } from "./handle.js";
 export { useHandle } from "./browser/react/use-handle.js";
 
 export { Meta } from "./handles/meta.js";
-export { MetaTags } from "./handles/MetaTags.js";
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
 export {
   Script,
   type ScriptConfig,
   type ScriptAttributes,
 } from "./handles/script.js";
-export { Scripts } from "./handles/Scripts.js";
+export { Html };
 export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
 
 export {

package/src/components/DefaultDocument.tsx

@@ -3,12 +3,16 @@
 import type { ReactNode, ReactElement } from "react";
 import { MetaTags } from "../handles/MetaTags.js";
 import { Scripts } from "../handles/Scripts.js";
+import { ScrollRestoration } from "../browser/react/ScrollRestoration.js";
 
 /**
  * Default document component that provides a basic HTML structure.
  * Used when no custom document is provided to createRouter.
- * Includes MetaTags for automatic charset, viewport, and route meta support,
- * and Scripts (head + body sites) so the Script handle works out of the box.
+ * Renders every Html member: Html.Meta (charset, viewport, route meta), head +
+ * body Html.Scripts sites for the Script handle, and Html.ScrollRestoration.
+ * An app that wants a custom getKey or no scroll restoration passes its own
+ * document; rendering a second Html.ScrollRestoration under this one only
+ * warns ("[Scroll] Already initialized").
  *
  * Uses suppressHydrationWarning on <html> because the theme script
  * may modify class/style attributes before React hydrates.
@@ -27,6 +31,7 @@ export function DefaultDocument({
       <body>
         <Scripts position="body" />
         {children}
+        <ScrollRestoration />
       </body>
     </html>
   );

package/src/context-var.ts

@@ -12,7 +12,7 @@
  * interface PaginationData { current: number; total: number }
  * export const Pagination = createVar<PaginationData>();
  *
- * // Non-cacheable var — ctx.get(User) throws inside a cache() boundary
+ * // Non-cacheable var — ctx.get(User) throws inside cache() or "use cache"
  * export const User = createVar<UserData>({ cache: false });
  *
  * // handler
@@ -26,7 +26,7 @@
 export interface ContextVar<T> {
   readonly __brand: "context-var";
   readonly key: symbol;
-  /** When false, ctx.get(var) throws inside a cache() boundary. */
+  /** When false, ctx.get(var) throws inside cache() or "use cache". */
   readonly cache: boolean;
   /** Phantom field to carry the type parameter. Never set at runtime. */
   readonly __type?: T;
@@ -35,9 +35,10 @@ export interface ContextVar<T> {
 export interface ContextVarOptions {
   /**
    * When false, marks this variable as non-cacheable.
-   * Reading this var with ctx.get() inside a cache() boundary throws. Use for
-   * inherently request-specific data (user sessions, auth tokens, etc.) that
-   * must never be baked into cached segments.
+   * Reading this var with ctx.get() inside a cache() boundary or a "use cache"
+   * function throws. Use for inherently request-specific data (user sessions,
+   * auth tokens, etc.) that must never be baked into cached segments or
+   * entries; pass the value into a "use cache" function as an argument.
    *
    * @default true
    */

package/src/escape-script.ts

@@ -45,7 +45,7 @@ export function escapeJsonForScript(json: string): string {
  * source; for untrusted dynamic data, JSON-encode it and read it back, rather than
  * inlining it as code.
  *
- * Used by the Script handle's <Scripts> renderer for inline `children`.
+ * Used by the Script handle's <Html.Scripts> renderer for inline `children`.
  */
 export function escapeScriptBody(js: string): string {
   return js.replace(/<!--/g, "<\\u0021--").replace(/<\/(script)/gi, "<\\/$1");

package/src/handles/MetaTags.tsx

@@ -2,17 +2,18 @@
 
 /**
  * Component to render collected meta descriptors in the document head.
+ * Public as `Html.Meta` (`@rangojs/router/client`).
  *
- * Deferred (Promise) meta descriptors are resolved before MetaTags renders
+ * Deferred (Promise) meta descriptors are resolved before `<Html.Meta />` renders
  * (server-side on the full render, client-side before apply on navigation), so
  * it only ever receives resolved descriptors and never suspends.
  *
- * When theme is enabled in the router config, MetaTags also renders
+ * When theme is enabled in the router config, `<Html.Meta />` also renders
  * the theme initialization script to prevent FOUC (flash of unstyled content).
- * This makes MetaTags the sole FOUC-script injector for apps that render it;
- * the standalone `<ThemeScript />` is only needed when MetaTags is not used.
- * Rendering both is safe (the inline script guards listener registration) but
- * redundant.
+ * This makes `<Html.Meta />` the sole FOUC-script injector for apps that render
+ * it; the standalone `<ThemeScript />` is only needed when `<Html.Meta />` is not
+ * used. Rendering both is safe (the inline script guards listener registration)
+ * but redundant.
  *
  * @example
  * ```tsx
@@ -20,7 +21,7 @@
  *   return (
  *     <html lang="en" suppressHydrationWarning>
  *       <head>
- *         <MetaTags />
+ *         <Html.Meta />
  *       </head>
  *       <body>...</body>
  *     </html>
@@ -179,17 +180,18 @@ export function renderMetaDescriptor(
 }
 
 /**
- * Renders all collected meta descriptors from route handlers.
+ * Renders all collected meta descriptors from route handlers. Public as
+ * `Html.Meta` (`@rangojs/router/client`).
  *
- * Place this component inside the `<head>` element of your document.
+ * Place `<Html.Meta />` inside the `<head>` element of your document.
  * It will automatically update when meta descriptors change during navigation.
  *
  * When theme is enabled in router config, also renders the theme initialization
  * script to prevent FOUC (flash of unstyled content).
  *
- * Deferred (Promise) meta descriptors are resolved BEFORE MetaTags renders —
+ * Deferred (Promise) meta descriptors are resolved BEFORE this renders —
  * server-side on the full/SSR render, client-side before apply on navigation
- * (resolve-by-default) — so MetaTags only ever receives resolved descriptors and
+ * (resolve-by-default) — so it only ever receives resolved descriptors and
  * never suspends.
  */
 export function MetaTags(): React.ReactNode {

package/src/handles/Scripts.tsx

@@ -1,11 +1,12 @@
 "use client";
 
 /**
- * Renders the scripts collected by the Script handle into the document.
+ * Renders the scripts collected by the Script handle into the document. Public
+ * as `Html.Scripts` (`@rangojs/router/client`).
  *
- * Place `<Scripts />` inside `<head>` (default) and, if you push body scripts,
- * `<Scripts position="body" />` at the top of `<body>`. Each site renders the
- * configs whose `position` matches; the request CSP nonce is applied
+ * Place `<Html.Scripts />` inside `<head>` (default) and, if you push body
+ * scripts, `<Html.Scripts position="body" />` at the top of `<body>`. Each site
+ * renders the configs whose `position` matches; the request CSP nonce is applied
  * automatically to every DOCUMENT-RENDERED <script> (consumers never pass it). An
  * async script first encountered on a soft navigation is injected client-side
  * where the nonce is unavailable, so it carries no nonce and relies on
@@ -24,11 +25,11 @@
  * ```tsx
  * <html>
  *   <head>
- *     <MetaTags />
- *     <Scripts />
+ *     <Html.Meta />
+ *     <Html.Scripts />
  *   </head>
  *   <body>
- *     <Scripts position="body" />
+ *     <Html.Scripts position="body" />
  *     {children}
  *   </body>
  * </html>
@@ -80,10 +81,10 @@ function passthroughAttributes(
       if (dev) {
         console.warn(
           isHandler
-            ? `[Scripts] event handler "${key}" in a script's attributes is ` +
+            ? `[Html.Scripts] event handler "${key}" in a script's attributes is ` +
                 `dropped; callbacks cannot cross the server -> client handle ` +
                 `boundary. Use a "use client" component for load/error handling.`
-            : `[Scripts] managed field "${key}" in a script's attributes is ` +
+            : `[Html.Scripts] managed field "${key}" in a script's attributes is ` +
                 `dropped; set it via the ScriptConfig fields (the request nonce ` +
                 `is applied automatically).`,
         );
@@ -129,7 +130,7 @@ function renderScript(
     async
   ) {
     console.warn(
-      `[Scripts] An async external script (src="${src}") is hoisted into ` +
+      `[Html.Scripts] An async external script (src="${src}") is hoisted into ` +
         `<head> by React; position: "body" is ignored for it.`,
     );
   }

package/src/handles/meta.ts

@@ -19,7 +19,7 @@
  *   return (
  *     <html>
  *       <head>
- *         <MetaTags />
+ *         <Html.Meta />
  *       </head>
  *       ...
  *     </html>
@@ -225,7 +225,7 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
  * Built-in handle for managing document metadata.
  *
  * Use `ctx.use(Meta)` in route handlers to push meta descriptors.
- * Use `<MetaTags />` component to render them in the document head.
+ * Use the `<Html.Meta />` component to render them in the document head.
  *
  * Deferred (Promise) descriptors are resolved before collectMeta runs
  * (resolve-by-default), so they participate in deduplication and `%s`

package/src/handles/script.ts

@@ -3,22 +3,23 @@
  * route/layout handlers.
  *
  * Push from a SERVER handler with `ctx.use(Script)(config)`; render with the
- * `<Scripts />` component (from `@rangojs/router/client`) placed in the Document
- * `<head>` (and optionally a second `<Scripts position="body" />` at the top of
- * `<body>`). This mirrors the Meta / <MetaTags> pair.
+ * `<Html.Scripts />` component (from `@rangojs/router/client`) placed in the
+ * Document `<head>` (and optionally a second `<Html.Scripts position="body" />`
+ * at the top of `<body>`). This mirrors the Meta / <Html.Meta> pair.
  *
- * The request CSP nonce is applied AUTOMATICALLY by <Scripts> to document-rendered
- * scripts; consumers never pass a nonce. (An async script first loaded on a soft
- * navigation is injected client-side without a nonce — it relies on
- * 'strict-dynamic' or a host allowance; see the EXECUTION CONTRACT below and the
- * /scripts skill.) A ScriptConfig is fully serializable (it crosses the
- * server -> client handle-collection boundary), so callbacks like onLoad are NOT
- * supported — a consumer needing them renders their own "use client" script.
+ * The request CSP nonce is applied AUTOMATICALLY by <Html.Scripts> to
+ * document-rendered scripts; consumers never pass a nonce. (An async script
+ * first loaded on a soft navigation is injected client-side without a nonce —
+ * it relies on 'strict-dynamic' or a host allowance; see the EXECUTION CONTRACT
+ * below and the /scripts skill.) A ScriptConfig is fully serializable (it
+ * crosses the server -> client handle-collection boundary), so callbacks like
+ * onLoad are NOT supported — a consumer needing them renders their own
+ * "use client" script.
  *
  * EXECUTION CONTRACT (see the /scripts skill for the full story):
  * - Inline (`children`) and ordered external (`src`, optional `defer`) scripts
  *   are DOCUMENT-LOAD scripts: they execute only when present in the initial HTML
- *   response. <Scripts> freezes them after hydration, so a later client (soft)
+ *   response. <Html.Scripts> freezes them after hydration, so a later client (soft)
  *   navigation never inserts an inert copy — React creates client-mounted
  *   <script> elements via innerHTML, which the HTML spec makes non-executing.
  * - Async external scripts (`src` + `async: true`) are React RESOURCES: they load
@@ -78,9 +79,9 @@ export type ScriptAttributes = Omit<
 /** Fields shared by every script shape. */
 interface ScriptConfigBase {
   /**
-   * Where <Scripts> renders this script.
-   * - "head" (default): the `<head>` <Scripts> site.
-   * - "body": the `<Scripts position="body" />` site at the top of <body>.
+   * Where <Html.Scripts> renders this script.
+   * - "head" (default): the `<head>` <Html.Scripts> site.
+   * - "body": the `<Html.Scripts position="body" />` site at the top of <body>.
    * Note: an external `async` script is hoisted into <head> by React regardless.
    */
   position?: "head" | "body";
@@ -96,7 +97,7 @@ interface ScriptConfigBase {
 /**
  * Inline script: a raw JS body rendered in place, escaped against `</script>`
  * breakout. DOCUMENT-LOAD only (executes when present in the initial HTML;
- * <Scripts> freezes it after hydration so navigation never inserts an inert
+ * <Html.Scripts> freezes it after hydration so navigation never inserts an inert
  * copy). `id` is REQUIRED — inline scripts are never deduped by React, so a
  * layout and a child pushing the same bootstrap would inject it twice. It is also
  * rendered as the script's DOM `id`. Forbids `src`/`async`/`defer`. For analytics
@@ -146,7 +147,7 @@ export interface OrderedScriptConfig extends ScriptConfigBase {
  * inline (`id` + `children`), external async (`src` + `async: true`), or external
  * ordered (`src`, optional `defer`). Invalid combinations (both `src`+`children`,
  * `async`+`defer`, inline without `id`) are compile errors. The CSP nonce is
- * applied by <Scripts>, never here.
+ * applied by <Html.Scripts>, never here.
  */
 export type ScriptConfig =
   | InlineScriptConfig

package/src/href-client.ts

@@ -6,7 +6,7 @@
  *
  * @example
  * ```typescript
- * import { href } from "rsc-router/client";
+ * import { href } from "@rangojs/router/client";
  *
  * href("/blog/my-post");           // ✓ matches /blog/:slug
  * href("/shop/product/widget");    // ✓ matches /shop/product/:slug

package/src/html.ts

@@ -0,0 +1,12 @@
+/**
+ * Members of the `Html` namespace; client.tsx and client.rsc.tsx expose this
+ * module as `import * as Html`. A module namespace, not an object literal, so
+ * bundlers drop members an app never renders (a literal kept opt-in
+ * ScrollRestoration in every app: +313 B gzip, over the router-chunk ratchet).
+ * No "use client": each member stays its own module's client reference, so a
+ * server component can dot into `Html`. Pinned by __tests__/html.test.ts and
+ * testing/__tests__/html-namespace.rsc-test.tsx.
+ */
+export { MetaTags as Meta } from "./handles/MetaTags.js";
+export { Scripts } from "./handles/Scripts.js";
+export { ScrollRestoration } from "./browser/react/ScrollRestoration.js";

package/src/index.rsc.ts

@@ -51,6 +51,7 @@ export type {
   LoaderDefinition,
   LoaderFn,
   LoaderContext,
+  LoaderOptions,
   FetchableLoaderOptions,
   LoadOptions,
   // Error boundary types
@@ -188,6 +189,9 @@ export {
   type RouterRequestInput,
 } from "./router.js";
 
+// Route manifest snapshot returned by router.debugManifest()
+export type { SerializedManifest } from "./debug.js";
+
 // RSC handler types (server-side)
 export type { HandlerCacheConfig } from "./rsc/types.js";
 export {
@@ -254,6 +258,7 @@ export type {
 export type {
   ScopedReverseFunction,
   ReverseFunction,
+  GlobalReverseFunction,
   ExtractLocalRoutes,
   ParamsFor,
 } from "./reverse.js";

package/src/index.ts

@@ -334,6 +334,7 @@ export type { BreadcrumbItem } from "./handles/breadcrumbs.js";
 export type {
   ScopedReverseFunction,
   ReverseFunction,
+  GlobalReverseFunction,
   ExtractLocalRoutes,
   ParamsFor,
 } from "./reverse.js";

package/src/loader-store.ts

@@ -34,6 +34,15 @@
  * the store — the hook falls back to `OutletContext.loaderData`.
  */
 
+import { unwrapsSynchronously } from "./thenable-status.js";
+
+/** The loader-segment shape announcePendingStreams reads (ResolvedSegment). */
+export interface PendingStreamSource {
+  type: string;
+  loaderId?: string;
+  loaderData?: unknown;
+}
+
 export interface LoaderEntry<T = unknown> {
   readonly value: T | undefined;
   /**
@@ -87,6 +96,14 @@ export interface SubscribeOptions {
    * Refreshes this bucket in place (no params/body) and rejects on failure.
    */
   refetch?: () => Promise<void>;
+  /**
+   * Called by `announcePendingStreams` (inside a transition commit) when a
+   * navigation stream for this bucket's loader is still pending. The hook pins
+   * `isLoading: true` with a useOptimistic update; React reverts it when that
+   * transition commits. Route-context readers only — an ephemeral reader owns
+   * its own lifecycle.
+   */
+  onStreamPending?: () => void;
 }
 
 interface InternalEntry {
@@ -118,6 +135,8 @@ interface InternalEntry {
   groups: Map<string, number>;
   /** Plain-GET refresh thunk for `refreshGroups`, set while in any group. */
   refetch: (() => Promise<void>) | undefined;
+  /** Subscribers' `onStreamPending` callbacks (see SubscribeOptions). */
+  streamPendingListeners: Set<() => void>;
 }
 
 /**
@@ -137,6 +156,21 @@ export class LoaderStore {
   private readonly families = new Map<string, Set<string>>();
   /** refresh group name -> set of bucket keys, for refreshGroups(). */
   private readonly groups = new Map<string, Set<string>>();
+  /**
+   * loader.$$id -> per-loader streams a committed navigation is still
+   * receiving. Registered and announced by announcePendingStreams(), which
+   * browser/partial-update.ts calls INSIDE every transition commit, so a
+   * reader whose content is held on screen by that transition pins
+   * `isLoading: true` for the data it is still showing until the transition
+   * lands (use-loader.tsx). Family-keyed on purpose: a persisting layout
+   * reader of the same createLoader the child is re-running is pinned too
+   * (the loader is in flight; not "this segment's copy is being replaced" —
+   * issue #862, working as designed). The new tree's own read of the loader
+   * suspends at the read site and never observes the flag. A Set, not a
+   * flag: overlapping navigations (second click before the first stream
+   * lands) keep the family pending until the LAST stream settles.
+   */
+  private readonly pendingStreams = new Map<string, Set<Promise<unknown>>>();
 
   private getOrCreate(bucketKey: string): InternalEntry {
     let e = this.entries.get(bucketKey);
@@ -151,6 +185,7 @@ export class LoaderStore {
         clearWhenSettled: false,
         groups: new Map(),
         refetch: undefined,
+        streamPendingListeners: new Set(),
       };
       this.entries.set(bucketKey, e);
     }
@@ -195,8 +230,11 @@ export class LoaderStore {
     e.pendingClear = false;
     e.clearWhenSettled = false;
     e.listeners.add(cb);
+    const onStreamPending = options?.onStreamPending;
+    if (onStreamPending) e.streamPendingListeners.add(onStreamPending);
     return () => {
       e.listeners.delete(cb);
+      if (onStreamPending) e.streamPendingListeners.delete(onStreamPending);
       // Group membership is refcounted per subscriber so refreshGroups() never
       // fetches for an unmounted reader, and a bucket shared by subscribers in
       // different groups stays in each group until ALL of that group's
@@ -479,6 +517,73 @@ export class LoaderStore {
     for (const cb of e.listeners) cb();
   }
 
+  /**
+   * Register a still-streaming per-loader result for `loaderId`. No-op for a
+   * settled Flight chunk (unwrapsSynchronously / "rejected"): the forceAwait
+   * and action lanes commit settled chunks, and a { ssr: false } loader is
+   * awaited before flush. Released as the stream settles, either way.
+   */
+  trackPendingStream(loaderId: string, stream: Promise<unknown>): void {
+    if (
+      unwrapsSynchronously(stream) ||
+      (stream as { status?: string }).status === "rejected"
+    ) {
+      return;
+    }
+    let set = this.pendingStreams.get(loaderId);
+    if (set?.has(stream)) return;
+    if (!set) {
+      set = new Set();
+      this.pendingStreams.set(loaderId, set);
+    }
+    set.add(stream);
+    const release = () => {
+      const current = this.pendingStreams.get(loaderId);
+      if (!current || !current.delete(stream)) return;
+      if (current.size === 0) this.pendingStreams.delete(loaderId);
+    };
+    stream.then(release, release);
+  }
+
+  /** True while any navigation stream for `loaderId` is still pending. */
+  isStreamPending(loaderId: string): boolean {
+    return this.pendingStreams.has(loaderId);
+  }
+
+  /**
+   * Register the loader segments of a tree being committed whose data is
+   * still a pending promise, then fire `onStreamPending` on every subscriber
+   * of every family with a pending stream. MUST run inside the startTransition
+   * that commits the tree: the hook answers with a useOptimistic update, which
+   * React reverts exactly when that transition commits — so the held reader
+   * reports isLoading:true for as long as its data stays on screen and not a
+   * frame longer. Outside a transition React reverts an optimistic update on
+   * the next render, pinning nothing useful. Registering here rather than in
+   * the tree build keeps register + announce in one call; settled chunks
+   * (cached/reused segments, forceAwait lanes) are skipped by
+   * trackPendingStream.
+   */
+  announcePendingStreams(segments: readonly PendingStreamSource[]): void {
+    for (const segment of segments) {
+      if (
+        segment.type === "loader" &&
+        segment.loaderId &&
+        segment.loaderData instanceof Promise
+      ) {
+        this.trackPendingStream(segment.loaderId, segment.loaderData);
+      }
+    }
+    for (const loaderId of this.pendingStreams.keys()) {
+      const fam = this.families.get(loaderId);
+      if (!fam) continue;
+      for (const bucketKey of fam) {
+        const e = this.entries.get(bucketKey);
+        if (!e) continue;
+        for (const cb of e.streamPendingListeners) cb();
+      }
+    }
+  }
+
   /**
    * Test-only escape hatch. Drops every entry. Production code should never
    * call this; the store is process-scoped and lives for the tab's lifetime.
@@ -488,6 +593,7 @@ export class LoaderStore {
     this.entries.clear();
     this.families.clear();
     this.groups.clear();
+    this.pendingStreams.clear();
   }
 }