@rangojs/router 0.16.0 → 0.17.0

package/src/cache/document-cache.ts

@@ -129,6 +129,19 @@ function shouldCacheResponse(response: Response): CacheDirectives | null {
   return parseCacheControl(cacheControl);
 }
 
+/**
+ * Throw the first error the drained render reported through Flight or Fizz
+ * onError. A component that throws after the 200 committed does not fail the
+ * stream: it completes with an error row or an errored Suspense boundary, and
+ * every hit would serve it (issue #915). The caller's catch reports the skipped
+ * write as cache-write. Read only after the body is fully drained, when both
+ * renders have finished.
+ */
+function throwIfRenderErrored(requestCtx: RequestContext | undefined): void {
+  const errors = requestCtx?._renderErrors;
+  if (errors && errors.length > 0) throw errors[0];
+}
+
 // ============================================================================
 // Response Helpers
 // ============================================================================
@@ -404,6 +417,7 @@ export function createDocumentCacheMiddleware<TEnv = any>(
                   // drain the fresh render fully before snapshotting tags
                   // (same render-complete barrier as the miss path).
                   const body = await new Response(fresh.body).arrayBuffer();
+                  throwIfRenderErrored(requestCtx);
                   await store.putResponse!(
                     cacheKey,
                     new Response(body, fresh),
@@ -468,6 +482,7 @@ export function createDocumentCacheMiddleware<TEnv = any>(
             // unaffected) is the render-complete barrier that keeps the cached
             // body and its tag set consistent.
             const body = await new Response(cacheStream).arrayBuffer();
+            throwIfRenderErrored(requestCtx);
             await store.putResponse!(
               cacheKey,
               new Response(body, originalResponse),

package/src/cache/handle-capture.ts

@@ -6,10 +6,82 @@
  * pulling in @vitejs/plugin-rsc/rsc dependencies.
  */
 
+import { getCurrentLoaderBodyId } from "../server/context.js";
 import type { HandleStore } from "../server/handle-store.js";
 import type { SegmentHandleData } from "./types.js";
 
-export interface HandleCapture {
+/**
+ * Scoping for one capture of a cached unit (a loader's own cache(),
+ * loader-cache.ts; a "use cache" function, cache-runtime.ts) that runs
+ * concurrently with live pushes into the same store.
+ */
+export interface HandleCaptureOptions {
+  /** Push-time predicate; a rejected push is not recorded by this capture. */
+  accept?: () => boolean;
+  /**
+   * Recorded pushes do not reach the store. A stale hit's background
+   * revalidation: the foreground already replayed the entry's pushes, so the
+   * fresh body's pushes belong only to the refreshed entry.
+   */
+  divert?: boolean;
+  /**
+   * Record key for an accepted push, in place of its segment id. A loader's
+   * own cache() (loader-cache.ts recordOwnerKey) and "use cache"
+   * (useCacheRecordKey) group pushes by the loader body that made them.
+   */
+  key?: () => string;
+}
+
+// The loader whose recorded push a "use cache" HIT is replaying
+// (replayLoaderPush), for an enclosing "use cache" MISS's record key.
+let replayingOwner: string | undefined;
+
+/**
+ * HandleStore.pushReplayed, attributed to `loaderId` for the record key of an
+ * enclosing "use cache" MISS: an outer cached function records an inner HIT's
+ * replayed loader pushes under that loader, not as its own.
+ */
+export function replayLoaderPush(
+  handleStore: HandleStore,
+  handleName: string,
+  segmentId: string,
+  value: unknown,
+  loaderId: string,
+): void {
+  const prev = replayingOwner;
+  replayingOwner = loaderId;
+  try {
+    handleStore.pushReplayed(handleName, segmentId, value, loaderId);
+  } finally {
+    replayingOwner = prev;
+  }
+}
+
+/**
+ * Record key for a "use cache" capture: run-length groups `${seq}:${owner}`,
+ * so the HIT (handle-snapshot.ts appendHandles) delivers each loader's pushes
+ * at most once per request. The owner is the loader whose body, entered
+ * inside this execution via ctx.use, made the push; empty for the function's
+ * own pushes and those of cached functions it calls. Groups keep push order
+ * across owners. Create at call time: the caller's loader body is the
+ * function's own scope.
+ */
+export function useCacheRecordKey(): () => string {
+  const callerBody = getCurrentLoaderBodyId();
+  let seq = 0;
+  let last: string | undefined;
+  return () => {
+    const body = replayingOwner ?? getCurrentLoaderBodyId();
+    const owner = body === callerBody ? "" : (body ?? "");
+    if (owner !== last) {
+      last = owner;
+      seq++;
+    }
+    return `${seq}:${owner}`;
+  };
+}
+
+export interface HandleCapture extends HandleCaptureOptions {
   data: Record<string, SegmentHandleData>;
 }
 
@@ -42,33 +114,41 @@ function ensureInterceptorInstalled(handleStore: HandleStore): void {
     segmentId: string,
     value: unknown,
   ) => {
+    let diverted = false;
     for (const capture of captures) {
-      if (!capture.data[segmentId]) {
-        capture.data[segmentId] = {};
+      if (capture.accept && !capture.accept()) continue;
+      if (capture.divert) diverted = true;
+      const key = capture.key ? capture.key() : segmentId;
+      if (!capture.data[key]) {
+        capture.data[key] = {};
       }
-      if (!capture.data[segmentId][handleName]) {
-        capture.data[segmentId][handleName] = [];
+      if (!capture.data[key][handleName]) {
+        capture.data[key][handleName] = [];
       }
-      capture.data[segmentId][handleName].push(value);
+      capture.data[key][handleName].push(value);
     }
-    originalPush(handleName, segmentId, value);
+    if (!diverted) originalPush(handleName, segmentId, value);
   };
 }
 
 /**
- * Start capturing handle pushes for a cached function execution.
+ * Start capturing handle pushes for a cached function or cached loader
+ * execution (`options`: see HandleCaptureOptions).
  *
  * Concurrency-safe: multiple overlapping captures on the same
  * HandleStore are independent. Each capture registers a token in a
  * Set; stopping removes it. No ordering requirement (LIFO not needed).
  */
-export function startHandleCapture(handleStore: HandleStore): {
+export function startHandleCapture(
+  handleStore: HandleStore,
+  options?: HandleCaptureOptions,
+): {
   capture: HandleCapture;
   stop: () => void;
 } {
   ensureInterceptorInstalled(handleStore);
 
-  const capture: HandleCapture = { data: {} };
+  const capture: HandleCapture = { data: {}, ...options };
   const captures = activeCapturesMap.get(handleStore)!;
   captures.add(capture);
 

package/src/cache/handle-snapshot.ts

@@ -6,9 +6,10 @@
  * during segment resolution and stored alongside cached segments.
  */
 
+import { replayLoaderPush } from "./handle-capture.js";
 import type { ResolvedSegment } from "../types.js";
 import type { HandleStore } from "../server/handle-store.js";
-import type { SegmentHandleData } from "./types.js";
+import type { HandleOwners, SegmentHandleData } from "./types.js";
 // segment-codec eagerly pulls @vitejs/plugin-rsc (a virtual: module unresolvable
 // in plain node/vitest). It is imported LAZILY inside the two async encode/decode
 // helpers below so that modules which import handle-snapshot only for the
@@ -47,19 +48,32 @@ function withTimeout<T>(p: Promise<T>, ms: number, onTimeout: T): Promise<T> {
   ]);
 }
 
-export async function encodeHandles(handles: HandleRecord): Promise<string> {
+/**
+ * `onError` reaches the Flight encode (see serializeResult). A cache writer
+ * passes the collector it gives the value's encode, so a handle value that
+ * fails to encode (a rejected pushed promise) refuses the whole entry like a
+ * failed value does; prerender (prerender-match.ts) passes one too and
+ * hands the error to its prerender.onError policy.
+ */
+export async function encodeHandles(
+  handles: HandleRecord,
+  onError?: (error: unknown) => void,
+): Promise<string> {
   if (!hasHandleData(handles)) return "";
-  return encodeHandleValue(handles);
+  return encodeHandleValue(handles, onError);
 }
 
 export function decodeHandles(encoded: string): Promise<HandleRecord | null> {
   return decodeHandleValue<HandleRecord>(encoded);
 }
 
-export async function encodeHandleValue(value: unknown): Promise<string> {
+export async function encodeHandleValue(
+  value: unknown,
+  onError?: (error: unknown) => void,
+): Promise<string> {
   const { serializeResult } = await import("./segment-codec.js");
   const encoded = await withTimeout(
-    serializeResult(value),
+    serializeResult(value, onError),
     HANDLE_ENCODE_TIMEOUT_MS,
     null,
   );
@@ -84,49 +98,139 @@ export async function decodeHandleValue<T>(encoded: string): Promise<T | null> {
  * Capture handle data for a set of segments from the handle store.
  * Used when caching segments to preserve their handle data.
  *
- * `exclude` (shell captures: RequestContext._shellCaptureLoaderHandleValues)
- * drops DSL-loader-scoped push values from the CACHE WRITE only: loaders
- * re-run fresh on every HIT, so replaying their captured values would
- * duplicate the fresh push — and their masked nested promises would stall the
- * Flight handle encode to its timeout. Threaded as an explicit argument so
- * every other getDataForSegment consumer (the render-barrier snapshot,
- * prerender) provably sees every push.
+ * DSL-loader pushes stay out of the CACHE WRITE: a HIT runs loaders exactly
+ * as an uncached render of the same request would (cache-lookup.ts
+ * resolveFreshLoadersAndYield), so replaying a recorded copy would duplicate
+ * the live push. Handler pushes, including
+ * handler-invoked ctx.use(Loader) bodies (skipped with their handler on a
+ * HIT), are kept. The store tags loader pushes by array position at push
+ * time, so primitive values are covered. A PPR shell capture untags the
+ * settled bake-lane pushes its record keeps (shell-capture.ts) and gives
+ * them an owner (captureHandleOwners). Only this call site passes
+ * excludeLoaderPushes; every other getDataForSegment consumer (the
+ * render-barrier snapshot, prerender) sees every push.
  */
 export function captureHandles(
   segments: ResolvedSegment[],
   handleStore: HandleStore,
-  exclude?: WeakSet<object>,
 ): Record<string, SegmentHandleData> {
   const handles: Record<string, SegmentHandleData> = {};
   for (const seg of segments) {
-    const data = handleStore.getDataForSegment(seg.id);
-    if (!exclude) {
-      handles[seg.id] = data;
-      continue;
-    }
-    const filtered: SegmentHandleData = {};
-    for (const [handleName, values] of Object.entries(data)) {
-      const kept = values.filter(
-        (v) => typeof v !== "object" || v === null || !exclude.has(v),
-      );
-      if (kept.length > 0) filtered[handleName] = kept;
-    }
-    handles[seg.id] = filtered;
+    handles[seg.id] = handleStore.getDataForSegment(seg.id, true);
   }
   return handles;
 }
 
+/** The owners of captureHandles' values; undefined when none is owned. */
+export function captureHandleOwners(
+  segments: ResolvedSegment[],
+  handleStore: HandleStore,
+): HandleOwners | undefined {
+  let owners: HandleOwners | undefined;
+  for (const seg of segments) {
+    const segOwners = handleStore.getRecordOwners(seg.id);
+    if (segOwners) (owners ??= {})[seg.id] = segOwners;
+  }
+  return owners;
+}
+
 /**
  * Restore handle data from a cached snapshot into the handle store.
- * Used when serving cached segments to replay their handle data.
+ * Used when serving cached segments to replay their handle data: a route
+ * cache() record owns its segments' arrays, so it REPLACES them.
+ *
+ * A segment with `owners` is replaced with empty arrays and re-pushed in
+ * recorded order, an owned value through pushReplayed: the owning loader
+ * re-runs on the HIT (loaders stay live), and its live pushes replace the
+ * recorded ones in place instead of appending a second copy. `claim`
+ * (setupLoaderAccess _claimLoaderPushes) is asked once per owner, so the
+ * loader's own cache() HIT does not replay its pushes a second time
+ * (loader-cache.ts replayLoaderHandles); an owner it refuses is skipped. A
+ * record without owners restores as a plain replay.
  */
 export function restoreHandles(
   handles: Record<string, SegmentHandleData>,
   handleStore: HandleStore,
+  owners?: HandleOwners,
+  claim?: (loaderId: string) => boolean,
 ): void {
+  let delivers: Map<string, boolean> | undefined;
   for (const [segId, segHandles] of Object.entries(handles)) {
-    if (Object.keys(segHandles).length > 0) {
+    if (Object.keys(segHandles).length === 0) continue;
+    const segOwners = owners?.[segId];
+    if (!segOwners) {
       handleStore.replaySegmentData(segId, segHandles);
+      continue;
+    }
+    const cleared: SegmentHandleData = {};
+    for (const handleName in segHandles) cleared[handleName] = [];
+    handleStore.replaySegmentData(segId, cleared);
+    for (const [handleName, values] of Object.entries(segHandles)) {
+      const valueOwners = segOwners[handleName];
+      for (let i = 0; i < values.length; i++) {
+        const owner = valueOwners?.[i];
+        if (!owner) {
+          handleStore.push(handleName, segId, values[i]);
+          continue;
+        }
+        delivers ??= new Map();
+        let deliver = delivers.get(owner);
+        if (deliver === undefined) {
+          deliver = claim ? claim(owner) : true;
+          delivers.set(owner, deliver);
+        }
+        if (deliver) {
+          handleStore.pushReplayed(handleName, segId, values[i], owner);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Append recorded handle pushes to the store, in recorded order, via push()
+ * so active captures and loader-scope tagging see them like live pushes. For
+ * a cached unit that shares its segments with live pushes ("use cache");
+ * restoreHandles would wipe those. `segmentId` redirects every value to one
+ * segment (the caller's).
+ *
+ * Owner-keyed groups (useCacheRecordKey, `${seq}:${loaderId}`) are a loader's
+ * pushes, which reach the page once per request: `claim` (setupLoaderAccess
+ * _claimLoaderPushes) skips a loader that already ran or was replayed in this
+ * request, and a claimed loader that runs later replaces its replayed values
+ * (HandleStore.pushReplayed). `${seq}:` groups are the function's own pushes.
+ * A key without ":" is a segment id (records written before owner keys) and
+ * replays unchanged. A loader's own cache() replays through loader-cache.ts
+ * replayLoaderHandles.
+ */
+export function appendHandles(
+  handles: Record<string, SegmentHandleData>,
+  handleStore: HandleStore,
+  segmentId?: string,
+  claim?: (loaderId: string) => boolean,
+): void {
+  let claims: Map<string, boolean> | undefined;
+  for (const [key, segHandles] of Object.entries(handles)) {
+    const colon = key.indexOf(":");
+    const owner = colon < 0 ? "" : key.slice(colon + 1);
+    if (owner) {
+      claims ??= new Map();
+      let deliver = claims.get(owner);
+      if (deliver === undefined) {
+        deliver = claim ? claim(owner) : true;
+        claims.set(owner, deliver);
+      }
+      if (!deliver) continue;
+    }
+    const target = segmentId ?? key;
+    for (const [handleName, values] of Object.entries(segHandles)) {
+      for (const value of values) {
+        if (owner) {
+          replayLoaderPush(handleStore, handleName, target, value, owner);
+        } else {
+          handleStore.push(handleName, target, value);
+        }
+      }
     }
   }
 }

package/src/cache/segment-codec.ts

@@ -69,11 +69,15 @@ export function stringToStream(str: string): ReadableStream<Uint8Array> {
  */
 export async function rscSerialize(
   value: unknown,
+  onError?: (error: unknown) => void,
 ): Promise<string | undefined> {
   if (value === undefined || value === null) return undefined;
 
   const temporaryReferences = createTemporaryReferenceSet();
-  const stream = renderToReadableStream(value, { temporaryReferences });
+  const stream = renderToReadableStream(value, {
+    temporaryReferences,
+    onError,
+  });
   return streamToString(stream);
 }
 
@@ -102,10 +106,16 @@ export async function rscDeserialize<T>(
  *
  * Returns null only on serialization failure.
  */
-export async function serializeResult(value: unknown): Promise<string | null> {
+export async function serializeResult(
+  value: unknown,
+  onError?: (error: unknown) => void,
+): Promise<string | null> {
   try {
     const temporaryReferences = createTemporaryReferenceSet();
-    const stream = renderToReadableStream(value, { temporaryReferences });
+    const stream = renderToReadableStream(value, {
+      temporaryReferences,
+      onError,
+    });
     return await streamToString(stream);
   } catch (error) {
     // Returning null silently turns a non-serializable cache value into a
@@ -145,9 +155,17 @@ export const deserializeComponent: (encoded: string) => Promise<unknown> =
  * Serialize segments for storage.
  * Each segment's component, layout, loading, and loaderData are RSC-serialized.
  * Metadata is preserved as-is.
+ *
+ * `onError` goes to every Flight encode. A component that throws while
+ * encoding (e.g. an async server component in the tree) does not reject the
+ * encode: Flight reports it through onError and writes an error row
+ * (`1:E{...}`) that throws when the decoded tree renders. cacheRoute and the
+ * prerender producers (prerender-match.ts) pass it to refuse such an entry;
+ * without it the encode is unchanged.
  */
 export async function serializeSegments(
   segments: ResolvedSegment[],
+  onError?: (error: unknown) => void,
 ): Promise<SerializedSegmentData[]> {
   return Promise.all(
     segments.map(async (segment): Promise<SerializedSegmentData> => {
@@ -162,6 +180,7 @@ export async function serializeSegments(
       // Serialize the component to RSC stream
       const stream = renderToReadableStream(componentResolved, {
         temporaryReferences,
+        onError,
       });
 
       // RSC-serialize loading: "null" string distinguishes explicit null from undefined
@@ -169,7 +188,7 @@ export async function serializeSegments(
         segment.loading !== undefined
           ? segment.loading === null
             ? "null"
-            : await rscSerialize(segment.loading)
+            : await rscSerialize(segment.loading, onError)
           : undefined;
 
       // Await loaderData / loaderDataPromise if they're Promises
@@ -190,9 +209,9 @@ export async function serializeSegments(
         encodedLoaderDataPromise,
       ] = await Promise.all([
         streamToString(stream),
-        segment.layout ? rscSerialize(segment.layout) : undefined,
-        rscSerialize(loaderDataResolved),
-        rscSerialize(loaderDataPromiseResolved),
+        segment.layout ? rscSerialize(segment.layout, onError) : undefined,
+        rscSerialize(loaderDataResolved, onError),
+        rscSerialize(loaderDataPromiseResolved, onError),
       ]);
 
       return {

package/src/cache/tag-invalidation.ts

@@ -68,8 +68,8 @@ function warnNoTagStore(fn: string, tags: string[]): void {
   console.warn(
     `[${fn}] No tag-capable cache store is configured; tags ` +
       `[${tags.join(", ")}] were not invalidated. The configured store must ` +
-      `implement invalidateTags() (the built-in MemorySegmentCacheStore and ` +
-      `CFCacheStore do).`,
+      `implement invalidateTags() (the built-in MemorySegmentCacheStore, ` +
+      `CFCacheStore, and VercelCacheStore do).`,
   );
 }
 
@@ -98,7 +98,8 @@ function warnPartialTagStore(fn: string, incapable: number): void {
   console.warn(
     `[${fn}] ${incapable} configured cache store(s) do not implement ` +
       `invalidateTags(); their tagged entries were NOT invalidated. Use a ` +
-      `tag-capable store (e.g. MemorySegmentCacheStore / CFCacheStore) for any ` +
+      `tag-capable store (MemorySegmentCacheStore / CFCacheStore / ` +
+      `VercelCacheStore) for any ` +
       `cache({ store }) boundary whose entries you invalidate by tag.`,
   );
 }

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>
   );