@rangojs/router 0.16.0 → 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

@@ -104,10 +104,13 @@ export declare class LoaderStore {
      * 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). 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.
+     * 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;

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>
  *   )),
  * ])

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

@@ -102,10 +102,10 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *   intercept("@modal", "card", () => <CardModal />),
      * ])
      *
-     * // With loaders and revalidation
+     * // With loaders and revalidation (revalidate() goes on the loader;
+     * // an intercept-level revalidate() throws)
      * intercept("@modal", "card", () => <CardModal />, () => [
-     *   loader(CardModalLoader),
-     *   revalidate(() => false),
+     *   loader(CardModalLoader, () => [revalidate(() => false)]),
      * ])
      *
      * // Conditional activation via the config object's `when` selector
@@ -127,7 +127,11 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      * @param handler - Component or handler for intercepted render
      * @param config - Optional InterceptConfig (e.g. `{ when }`), or the use
      *   callback directly when there is no config
-     * @param use - Optional callback for loaders, middleware, revalidate, etc.
+     * @param use - Optional callback for loader(), middleware(), loading(),
+     *   transition() and a layout() modal chrome without use() items.
+     *   revalidate() (goes on the loader), errorBoundary()/notFoundBoundary()
+     *   (go on the enclosing layout) and cache() (goes on the target route)
+     *   throw here.
      */
     intercept: {
         <K extends keyof ResolvedRouteMap<T> & string>(slotName: `@${string}`, routeName: `.${K}`, handler: ReactNode | Handler<ExtractRouteParams<T, K>, {}, TEnv>, config?: import("../server/context.js").InterceptConfig<TEnv> | (() => UseItems<InterceptUseItem>), use?: () => UseItems<InterceptUseItem>): InterceptItem;
@@ -183,6 +187,9 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *   ({ defaultShouldRevalidate: true })
      * )
      * ```
+     * Not valid directly inside intercept() use() (throws at definition time):
+     * intercepts only revalidate their loaders, so attach it there with
+     * `loader(Def, () => [revalidate(...)])`.
      * @param fn - Function returning either:
      *   - `boolean` (hard decision — short-circuits the chain),
      *   - `{ defaultShouldRevalidate: boolean }` (soft — updates the suggestion
@@ -245,16 +252,19 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      * ```typescript
      * errorBoundary(<ErrorFallback />)
      *
-     * // With dynamic error handler
-     * errorBoundary(({ error, reset }) => (
+     * // With dynamic error handler (server fallback: receives only { error })
+     * errorBoundary(({ error }) => (
      *   <div>
      *     <h2>Something went wrong</h2>
      *     <p>{error.message}</p>
-     *     <button onClick={reset}>Try again</button>
+     *     <a href="/">Go home</a>
      *   </div>
      * ))
      * ```
-     * @param fallback - Static JSX or handler receiving error info and reset function
+     * Not valid inside intercept() use() (throws at definition time): an
+     * intercept has no boundary of its own, and its loader errors resolve
+     * against the enclosing layout/path boundary.
+     * @param fallback - Static JSX or handler receiving `{ error }`
      */
     errorBoundary: (fallback: ReactNode | ErrorBoundaryHandler) => ErrorBoundaryItem;
     /**
@@ -270,6 +280,9 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *   </div>
      * ))
      * ```
+     * Not valid inside intercept() use() (throws at definition time): an
+     * intercept has no boundary of its own, and notFound() from its loaders
+     * resolves against the enclosing layout/path boundary.
      * @param fallback - Static JSX or handler receiving not-found info
      */
     notFoundBoundary: (fallback: ReactNode | NotFoundBoundaryHandler) => NotFoundBoundaryItem;
@@ -285,6 +298,9 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      * Note: Loaders are NOT cached by default. Use cache() inside loader()
      * to explicitly opt-in to loader caching.
      *
+     * Not valid inside intercept() use() (throws at definition time): an
+     * intercept navigation is cached under the target route's cache() scope.
+     *
      * ```typescript
      * // Using app-level defaults (ttl inherited from store.defaults)
      * cache(() => [
@@ -319,6 +335,12 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *   route("archive/:year"),     // uses KV store
      * ])
      *
+     * // Among a path's children: caches that path (handler, layouts, parallels)
+     * path("/product/:id", ProductPage, { name: "product" }, () => [
+     *   cache({ ttl: 60 }),
+     *   layout(<ProductChrome />),  // cached with the path
+     * ])
+     *
      * // Opt-in loader caching
      * route("product/:id", ProductHandler, () => [
      *   loader(ProductLoader),               // NOT cached (default)
@@ -345,7 +367,9 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *    content while the new loader resolves instead of flashing the route's
      *    loading() skeleton (see segment-system.tsx inTransitionScope). Held
      *    useLoader readers of the re-run loaders report isLoading: true until
-     *    the new data commits (use-loader.tsx). This is also the precondition
+     *    the new data commits (use-loader.tsx). The pin is per loader family
+     *    (`$$id`), not per segment — a layout reader of the same createLoader
+     *    the child is re-running is flagged too. This is also the precondition
      *    for any view-transition animation.
      * 2. <ViewTransition> (experimental React only): the segment content is also
      *    wrapped in React's <ViewTransition>, so the held swap cross-fades/morphs.

package/dist/types/route-definition/resolve-handler-use.d.ts

@@ -6,6 +6,28 @@ import type { AllUseItems } from "../route-types.js";
  * ReactNode handlers return undefined (no .use possible).
  */
 export declare function resolveHandlerUse(handler: unknown): (() => any[]) | undefined;
+/**
+ * Validate every item an intercept's merged use() returned (explicit use()
+ * and handler.use) against MOUNT_SITE_ALLOWED_TYPES.intercept, plus two
+ * structural rules:
+ * - a nested layout() is only the modal chrome (intercept() keeps its
+ *   handler), so it may not carry use() items of its own;
+ * - a cache entry in `capturedLayouts` means cache() ran in the scope even if
+ *   it was not returned; its orphan form re-parents the following siblings
+ *   onto that entry, so it is rejected the same way. Inside a path, cache()
+ *   writes `sinks.cache` instead (dsl-helpers.ts cache()).
+ */
+export declare function validateInterceptUseItems(items: AllUseItems[], capturedLayouts: readonly {
+    type: string;
+}[], slotName: string, routeName: string, sinks: {
+    readonly revalidate: readonly unknown[];
+    readonly errorBoundary: readonly unknown[];
+    readonly notFoundBoundary: readonly unknown[];
+    readonly intercept: readonly unknown[];
+    readonly parallel: Readonly<Record<string, unknown>>;
+    /** Set by cache() when the intercept is declared inside a path. */
+    readonly cache?: unknown;
+}): void;
 /**
  * Validate that items from handler.use() are valid for the given mount site.
  * Throws a descriptive error if any item is not allowed.
@@ -16,4 +38,4 @@ export declare function validateHandlerUseItems(items: AllUseItems[], mountSite:
  * handler.use items come first (defaults), explicit items second (overrides).
  * Returns undefined if both are absent.
  */
-export declare function mergeHandlerUse(handlerUse: (() => any[]) | undefined, explicitUse: (() => any[]) | undefined, mountSite: string): (() => any[]) | undefined;
+export declare function mergeHandlerUse(handlerUse: (() => any[]) | undefined, explicitUse: (() => any[]) | undefined, mountSite: string | null): (() => any[]) | undefined;

package/dist/types/route-types.d.ts

@@ -156,7 +156,7 @@ export type RouteUseItem = LayoutItem | ParallelItem | InterceptItem | Middlewar
 /** Items that can be used inside a response route (path.json(), etc.) */
 export type ResponseRouteUseItem = MiddlewareItem | CacheItem;
 export type ParallelUseItem = RevalidateItem | LoaderItem | LoadingItem | ErrorBoundaryItem | NotFoundBoundaryItem | TransitionItem;
-export type InterceptUseItem = MiddlewareItem | RevalidateItem | LoaderItem | LoadingItem | ErrorBoundaryItem | NotFoundBoundaryItem | LayoutItem | RouteItem | TransitionItem;
+export type InterceptUseItem = MiddlewareItem | LoaderItem | LoadingItem | LayoutItem | RouteItem | TransitionItem;
 export type LoaderUseItem = RevalidateItem | CacheItem;
 /**
  * Allow composition factories in use() callbacks.