@rangojs/router 0.15.1 → 0.17.0

package/dist/types/cache/types.d.ts

@@ -377,9 +377,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.
  */
@@ -481,6 +480,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 */
@@ -520,3 +524,11 @@ 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/dist/types/client.d.ts

@@ -1,4 +1,5 @@
 import { Component, type ReactNode } from "react";
+import * as Html from "./html.js";
 import { type ClientErrorBoundaryFallbackProps } from "./types";
 /**
  * Outlet component - renders child content in layouts
@@ -125,7 +126,7 @@ interface ErrorBoundaryState {
  * @example
  * ```tsx
  * "use client";
- * import { ErrorBoundary } from "rsc-router/client";
+ * import { ErrorBoundary } from "@rangojs/router/client";
  *
  * function MyComponent() {
  *   return (
@@ -172,14 +173,13 @@ export { useSegments, type SegmentsState, } from "./browser/react/use-segments.j
 export { NavigationProvider, type NavigationProviderProps, } from "./browser/react/NavigationProvider.js";
 export { Link, type LinkProps, type PrefetchStrategy, type StateOrGetter, type LinkState, } from "./browser/react/Link.js";
 export { useLinkStatus, type LinkStatus, } from "./browser/react/use-link-status.js";
-export { ScrollRestoration, useScrollRestoration, type ScrollRestorationProps, } from "./browser/react/ScrollRestoration.js";
+export { useScrollRestoration, type ScrollRestorationProps, } from "./browser/react/ScrollRestoration.js";
 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 { createLocationState, useLocationState, type LocationStateDefinition, type LocationStateEntry, type LocationStateOptions, } from "./browser/react/location-state.js";
 export { href, type PatternToPath } from "./href-client.js";

package/dist/types/client.rsc.d.ts

@@ -1,13 +1,14 @@
 /**
  * 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.
  *
  * The bundler uses the "react-server" export condition to select this file
  * in RSC context, while the regular client.tsx is used in client components.
  */
+import * as Html from "./html.js";
 export { Outlet, ParallelOutlet, useOutlet, type OutletState, useLoader, ErrorBoundary, type ErrorBoundaryProps, } from "./client.js";
 export { useFetchLoader, useRefreshLoaders, type LoadFunction, type UseLoaderResult, type UseFetchLoaderResult, type UseLoaderOptions, } from "./use-loader.js";
 export { createLoader } from "./route-definition.js";
@@ -22,18 +23,16 @@ export { useNonce } from "./browser/react/nonce-context.js";
 export { useMount } from "./browser/react/use-mount.js";
 export { useSegments, type SegmentsState, } from "./browser/react/use-segments.js";
 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, type LinkProps, type PrefetchStrategy, } from "./browser/react/Link.js";
-export { ScrollRestoration, type ScrollRestorationProps, } from "./browser/react/ScrollRestoration.js";
 export { NavigationProvider, type NavigationProviderProps, } from "./browser/react/NavigationProvider.js";
 export { href } from "./href-client.js";
 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 { createLocationState, type LocationStateDefinition, type LocationStateEntry, type LocationStateOptions, } from "./browser/react/location-state-shared.js";
 export { useHref } from "./browser/react/use-href.js";

package/dist/types/components/DefaultDocument.d.ts

@@ -2,8 +2,11 @@ import type { ReactNode, ReactElement } from "react";
 /**
  * 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.

package/dist/types/context-var.d.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
@@ -25,7 +25,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;
@@ -33,9 +33,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/dist/types/escape-script.d.ts

@@ -39,6 +39,6 @@ export declare 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 declare function escapeScriptBody(js: string): string;

package/dist/types/handles/MetaTags.d.ts

@@ -1,17 +1,18 @@
 import type { MetaDescriptorBase } from "../router/types.js";
 export declare function renderMetaDescriptor(descriptor: MetaDescriptorBase, index: number): React.ReactNode;
 /**
- * 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 declare function MetaTags(): React.ReactNode;

package/dist/types/handles/Scripts.d.ts

@@ -1,9 +1,10 @@
 /**
- * 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
@@ -22,11 +23,11 @@
  * ```tsx
  * <html>
  *   <head>
- *     <MetaTags />
- *     <Scripts />
+ *     <Html.Meta />
+ *     <Html.Scripts />
  *   </head>
  *   <body>
- *     <Scripts position="body" />
+ *     <Html.Scripts position="body" />
  *     {children}
  *   </body>
  * </html>

package/dist/types/handles/meta.d.ts

@@ -19,7 +19,7 @@
  *   return (
  *     <html>
  *       <head>
- *         <MetaTags />
+ *         <Html.Meta />
  *       </head>
  *       ...
  *     </html>
@@ -33,7 +33,7 @@ import type { MetaDescriptor } from "../router/types.js";
  * 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/dist/types/handles/script.d.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
@@ -64,9 +65,9 @@ export type ScriptAttributes = Omit<ScriptHTMLAttributes<HTMLScriptElement>, "id
 /** 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";
@@ -81,7 +82,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
@@ -128,7 +129,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 | AsyncScriptConfig | OrderedScriptConfig;
 /**

package/dist/types/href-client.d.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/dist/types/html.d.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/dist/types/index.d.ts

@@ -103,7 +103,7 @@ export { Script, type ScriptConfig, type ScriptAttributes, } from "./handles/scr
 export { Breadcrumbs } from "./handles/breadcrumbs.js";
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
 export type { BreadcrumbItem } from "./handles/breadcrumbs.js";
-export type { ScopedReverseFunction, ReverseFunction, ExtractLocalRoutes, ParamsFor, } from "./reverse.js";
+export type { ScopedReverseFunction, ReverseFunction, GlobalReverseFunction, ExtractLocalRoutes, ParamsFor, } from "./reverse.js";
 export { scopedReverse } from "./reverse.js";
 export { createLocationState, type LocationStateDefinition, type LocationStateEntry, type LocationStateOptions, } from "./browser/react/location-state-shared.js";
 export type { OTelTracer, OTelActiveSpanTracer, OTelSpan, OTelTracingOptions, } from "./router/telemetry-otel.js";

package/dist/types/index.rsc.d.ts

@@ -9,7 +9,7 @@
  * in RSC context, while the regular index.ts is used in client components.
  */
 export { RouteNotFoundError, DataNotFoundError, notFound, MiddlewareError, HandlerError, BuildError, DslContextError, InvalidHandlerError, RouterError, Skip, isSkip, } from "./index.js";
-export type { DocumentProps, DefaultEnv, RouteDefinition, RouteConfig, RouteDefinitionOptions, TrailingSlashMode, Handler, HandlerContext, ExtractParams, GenericParams, Middleware, RevalidateParams, Revalidate, ActionRef, IsActionFn, RouteKeys, LoaderDefinition, LoaderFn, LoaderContext, FetchableLoaderOptions, LoadOptions, ErrorInfo, ErrorBoundaryFallbackProps, ErrorBoundaryHandler, ClientErrorBoundaryFallbackProps, NotFoundInfo, NotFoundBoundaryFallbackProps, NotFoundBoundaryHandler, ErrorPhase, OnErrorContext, OnErrorCallback, TransitionConfig, TransitionWhenFn, TransitionWhenContext, ViewTransitionClass, } from "./types.js";
+export type { DocumentProps, DefaultEnv, RouteDefinition, RouteConfig, RouteDefinitionOptions, TrailingSlashMode, Handler, HandlerContext, ExtractParams, GenericParams, Middleware, RevalidateParams, Revalidate, ActionRef, IsActionFn, RouteKeys, LoaderDefinition, LoaderFn, LoaderContext, LoaderOptions, FetchableLoaderOptions, LoadOptions, ErrorInfo, ErrorBoundaryFallbackProps, ErrorBoundaryHandler, ClientErrorBoundaryFallbackProps, NotFoundInfo, NotFoundBoundaryFallbackProps, NotFoundBoundaryHandler, ErrorPhase, OnErrorContext, OnErrorCallback, TransitionConfig, TransitionWhenFn, TransitionWhenContext, ViewTransitionClass, } from "./types.js";
 export type { RangoOptions, SSRStreamMode, SSROptions, ResolveStreamingContext, } from "./router.js";
 export type { OriginCheckConfig, OriginCheckContext, OriginCheckPhase, } from "./rsc/origin-guard.js";
 export type { ShellCaptureDebug, ShellCaptureDebugEvent, } from "./rsc/shell-capture.js";
@@ -23,6 +23,7 @@ export { Prerender, Passthrough, type PrerenderHandlerDefinition, type Passthrou
 export { Static, type StaticHandlerDefinition, type StaticHandlerOptions, } from "./static-handler.js";
 export { urls, type PathHelpers, type PathOptions, type PartialPrerenderProps, type UrlPatterns, type IncludeOptions, type IncludeItem, type RouteResponse, type ProblemDetails, type ResponseHandler, type ResponseHandlerContext, type JsonResponseHandler, type TextResponseHandler, type JsonValue, type ResponsePathFn, type JsonResponsePathFn, type TextResponsePathFn, } from "./urls.js";
 export { createRouter, type Rango, type RootLayoutProps, type RouterRequestInput, } from "./router.js";
+export type { SerializedManifest } from "./debug.js";
 export type { HandlerCacheConfig } from "./rsc/types.js";
 export { TRACKING_SEARCH_PARAMS, type CacheSearchParams, } from "./cache/search-params-filter.js";
 export { Meta } from "./handles/meta.js";
@@ -38,7 +39,7 @@ export { cacheTag } from "./cache/cache-tag.js";
 export { updateTag, revalidateTag } from "./cache/tag-invalidation.js";
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
 export type { MiddlewareContext, CookieOptions, MiddlewareFn, } from "./router/middleware.js";
-export type { ScopedReverseFunction, ReverseFunction, ExtractLocalRoutes, ParamsFor, } from "./reverse.js";
+export type { ScopedReverseFunction, ReverseFunction, GlobalReverseFunction, ExtractLocalRoutes, ParamsFor, } from "./reverse.js";
 export { scopedReverse, createReverse } from "./reverse.js";
 export type { SearchSchema, SearchSchemaValue, ResolveSearchSchema, RouteSearchParams, RouteParams, } from "./search-params.js";
 export { createLocationState, type LocationStateDefinition, type LocationStateEntry, type LocationStateOptions, } from "./browser/react/location-state-shared.js";

package/dist/types/loader-store.d.ts

@@ -33,6 +33,12 @@
  * realm, so there is no cross-request pollution. Server renders never mutate
  * the store — the hook falls back to `OutletContext.loaderData`.
  */
+/** 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;
     /**
@@ -77,6 +83,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;
 }
 export declare class LoaderStore {
     private readonly entries;
@@ -84,6 +98,21 @@ export declare class LoaderStore {
     private readonly families;
     /** refresh group name -> set of bucket keys, for refreshGroups(). */
     private readonly groups;
+    /**
+     * 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;
     private getOrCreate;
     private registerFamily;
     /**
@@ -178,6 +207,29 @@ export declare class LoaderStore {
      */
     clearFamily(loaderId: string): void;
     private notify;
+    /**
+     * 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;
+    /** True while any navigation stream for `loaderId` is still pending. */
+    isStreamPending(loaderId: string): boolean;
+    /**
+     * 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;
     /**
      * 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.

package/dist/types/reverse.d.ts

@@ -119,6 +119,35 @@ export type ScopedReverseFunction<TLocalRoutes, TGlobalRoutes = TLocalRoutes> =
      */
     <TName extends keyof TLocalRoutes & string>(name: `.${TName}`, params: ExtractParams<RoutePatternFor<TLocalRoutes, TName>>, search: ResolveSearchSchema<ExtractSearchSchema<TLocalRoutes, TName>>): string;
 };
+/**
+ * Reverse function that resolves global route names only: no include() scope,
+ * no param auto-fill.
+ *
+ * This is the `ctx.reverse` of middleware (`MiddlewareContext`) and
+ * response-route handlers (`ResponseHandlerContext`). On a live request both
+ * get `createReverseFunction(routeMap)` with no route name or params (the
+ * middleware callers in rsc/handler.ts and rsc/loader-fetch.ts,
+ * handleResponseRoute, router/intercept-resolution.ts; mirrored by
+ * testing/run-middleware.ts and testing/dispatch.ts), so a dot-local `.name`
+ * has no scope to resolve against and throws `Unknown route`. Build-time PPR
+ * shell capture (prerender/build-shell-capture.ts) gives global and route
+ * middleware the same global-only reverse.
+ *
+ * - Route map with a string index signature (no generated map, the permissive
+ *   `Record<string, string>` fallback): any name except a dot-prefixed literal.
+ *   `Exclude` is required because `keyof` collapses to `string` there, so the
+ *   global overloads of `ScopedReverseFunction` would accept `.name` too.
+ * - Concrete route map: the global overloads of `ScopedReverseFunction`, with
+ *   name and param validation. The empty local map (`{}`) leaves no dot-prefixed
+ *   overload that can match.
+ *
+ * @example
+ * ```typescript
+ * reverse("blog.post", { slug: "hello" }) // ok: global route + params
+ * reverse(".post", { slug: "hello" })     // compile error: no include() scope
+ * ```
+ */
+export type GlobalReverseFunction<TGlobalRoutes> = string extends keyof TGlobalRoutes ? <TName extends string>(name: Exclude<TName, `.${string}`>, params?: Record<string, string>, search?: Record<string, unknown>) => string : ScopedReverseFunction<{}, TGlobalRoutes>;
 /**
  * Extract local routes type from UrlPatterns
  * Used with scopedReverse() to get the routes type from patterns
@@ -178,11 +207,14 @@ export type { RouteResponse } from "./urls.js";
  * Get a locally-typed reverse function from ctx.reverse for composable modules.
  *
  * This is a type-only cast - ctx.reverse already resolves names at runtime.
- * Provides type safety: `.name` validates against local routes,
- * `name` validates against global named-routes.
+ * Only the module's LOCAL routes are typed: `.name` and bare `name` both
+ * validate against the local map (the global map parameter defaults to it).
+ * Always dot-prefix local names — a bare name type-checks against the local
+ * map but resolves as a global name at runtime. For global names, call
+ * ctx.reverse directly.
  *
  * @param reverse - The ctx.reverse function from HandlerContext
- * @returns The same reverse function, typed with local + global routes
+ * @returns The same reverse function, typed with the module's local routes
  *
  * @example
  * ```typescript
@@ -193,7 +225,7 @@ export type { RouteResponse } from "./urls.js";
  *
  *     reverse(".index");              // ✓ Local route
  *     reverse(".post", { slug: "x" }); // ✓ Local with params
- *     reverse("shop.cart");           // ✓ Global route
+ *     ctx.reverse("shop.cart");       // Global route: use ctx.reverse
  *
  *     return <BlogIndex />;
  *   }, { name: "index" }),

package/dist/types/route-definition/dsl-helpers.d.ts

@@ -26,7 +26,7 @@ declare const revalidate: RouteHelpers<any, any>["revalidate"];
  * When an error occurs during rendering of this segment or its children,
  * the fallback will be rendered instead. The fallback can be:
  * - A static ReactNode (e.g., <ErrorPage />)
- * - A handler function that receives error info and reset function
+ * - A handler function that receives `{ error }` (server fallbacks get no reset)
  *
  * Error boundaries catch errors from:
  * - Middleware execution
@@ -42,11 +42,11 @@ declare const revalidate: RouteHelpers<any, any>["revalidate"];
  *
  * // Or with handler for dynamic error UI:
  * route("products.detail", ProductDetail, () => [
- *   errorBoundary(({ error, reset }) => (
+ *   errorBoundary(({ error }) => (
  *     <div>
  *       <h2>Product failed to load</h2>
  *       <p>{error.message}</p>
- *       <button onClick={reset}>Retry</button>
+ *       <a href="/products">Back to products</a>
  *     </div>
  *   )),
  * ])