@bractjs/bractjs 0.1.27 → 0.1.29

package/src/client/hooks/useLoaderData.ts

@@ -1,14 +1,18 @@
 import { useContext } from "react";
 import { RouterContext } from "../router.tsx";
 import { BractJSContext } from "../../shared/context.ts";
+import type { LoaderData } from "../../shared/route-types.ts";
 
 /**
- * Returns the current route's loader data, typed as T.
- * Works in both SSR and client contexts.
+ * Returns the current route's loader data. Works in both SSR and client contexts.
+ *
+ * Prefer passing the loader function type — `useLoaderData<typeof loader>()` —
+ * so the data type is inferred from the loader's return (no hand-written type to
+ * keep in sync). An explicit object type still works: `useLoaderData<HomeData>()`.
  */
-export function useLoaderData<T = unknown>(): T {
+export function useLoaderData<T = unknown>(): LoaderData<T> {
   const router = useContext(RouterContext);
   const bract = useContext(BractJSContext);
   const loaderData = router?.loaderData ?? bract?.loaderData ?? {};
-  return loaderData.route as T;
+  return loaderData.route as LoaderData<T>;
 }

package/src/client/hooks/useLocation.ts

@@ -0,0 +1,27 @@
+import { useContext } from "react";
+import { RouterContext } from "../router.tsx";
+import { BractJSContext } from "../../shared/context.ts";
+import type { RouterLocation } from "../../shared/route-types.ts";
+
+/**
+ * The current location: `{ pathname, search, hash, state, key }`.
+ *
+ * Reactive on the client — re-renders on every navigation (including
+ * back/forward). SSR-safe: during server rendering it reflects the request URL
+ * (`hash` is always `""` there, since fragments never reach the server), so
+ * components rendering `pathname`/`search` hydrate without mismatch. Never
+ * reads `window.location` during render.
+ */
+export function useLocation(): RouterLocation {
+  const routerCtx = useContext(RouterContext);
+  const bractCtx = useContext(BractJSContext);
+  if (routerCtx?.location) return routerCtx.location;
+  if (bractCtx?.location) return bractCtx.location;
+  return {
+    pathname: bractCtx?.pathname ?? "/",
+    search: "",
+    hash: "",
+    state: null,
+    key: "default",
+  };
+}

package/src/client/hooks/useMatches.ts

@@ -0,0 +1,32 @@
+import { useContext } from "react";
+import { RouterContext } from "../router.tsx";
+import { BractJSContext } from "../../shared/context.ts";
+import type { RouteMatch } from "../../shared/route-types.ts";
+
+/**
+ * Returns the matched route chain, outermost → innermost: the root, then each
+ * layout, then the leaf route. Each entry exposes `{ id, pathname, params,
+ * data, handle }`, where `handle` is that module's static `handle` export.
+ *
+ * Use it to build breadcrumbs or conditional chrome from `handle` without
+ * threading props through every layout. Works in both SSR and client contexts;
+ * the chain updates on soft navigation and revalidation.
+ *
+ * ```tsx
+ * // routes/blog/[id].tsx
+ * export const handle = { breadcrumb: "Post" };
+ *
+ * // some layout
+ * const crumbs = useMatches()
+ *   .filter((m) => m.handle?.breadcrumb)
+ *   .map((m) => m.handle!.breadcrumb as string);
+ * ```
+ *
+ * `handle` must be JSON-serializable — it travels in the SSR bootstrap and the
+ * `/_data` soft-nav payload, the same as loader data.
+ */
+export function useMatches(): RouteMatch[] {
+  const router = useContext(RouterContext);
+  const bract = useContext(BractJSContext);
+  return router?.matches ?? bract?.matches ?? [];
+}

package/src/client/hooks/useNavigate.ts

@@ -1,13 +1,20 @@
 import { useContext, useCallback } from "react";
 import { NavigationContext } from "../router.tsx";
 import { buildPath } from "../build-path.ts";
-import type { RegisteredRoutes, ParamsFor } from "../registry.ts";
+import { withSearch } from "../search-serializer.ts";
+import type { RegisteredRoutes, ParamsFor, SearchOutputFor } from "../registry.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
 export interface NavigateOptions<TTo extends RegisteredRoutes = RegisteredRoutes> {
   /** Path params for a dynamic `to` (e.g. `{ params: { id } }` for `/blog/:id`). */
   params?: ParamsFor<TTo>;
+  /** Search params for the target, typed by its `searchSchema` (replaces any query in `to`). */
+  search?: Partial<SearchOutputFor<TTo>>;
+  /** Replace the current history entry instead of pushing a new one. */
+  replace?: boolean;
+  /** Arbitrary history state, readable via `useLocation().state` after navigating. */
+  state?: unknown;
 }
 
 export interface NavigateFn {
@@ -27,19 +34,17 @@ export interface NavigateFn {
  *
  * SSR-safe and safe outside a `ClientRouter`: with no NavigationContext it
  * resolves to a no-op (same guard as `<Link>`), so it never throws during render.
- *
- * Note: navigation always pushes a history entry today; a `replace` option will
- * follow once the underlying navigate contract supports it.
  */
 export function useNavigate(): NavigateFn {
   const navCtx = useContext(NavigationContext);
   return useCallback<NavigateFn>(
     (to, options) => {
-      const href = options?.params
+      const base = options?.params
         ? buildPath(to as string, options.params as Record<string, string>)
         : (to as string);
+      const href = withSearch(base, options?.search as Record<string, unknown> | undefined);
       if (!navCtx) return Promise.resolve();
-      return navCtx.navigate(href);
+      return navCtx.navigate(href, { replace: options?.replace, state: options?.state });
     },
     [navCtx],
   );

package/src/client/hooks/useRevalidator.ts

@@ -0,0 +1,26 @@
+import { useContext } from "react";
+import { RouterContext } from "../router.tsx";
+
+export interface Revalidator {
+  /** Re-run the active route's loaders and commit fresh data. */
+  revalidate(): Promise<void>;
+  state: "idle" | "loading";
+}
+
+const noop = async (): Promise<void> => {};
+
+/**
+ * Manually revalidate the current route's loader data — for "Refresh" buttons,
+ * window-focus refetching, polling, or after out-of-band mutations (e.g. a
+ * WebSocket message). Respects the route's `shouldRevalidate` export.
+ *
+ * `state` tracks only revalidation — it does not flip during navigations
+ * (that's `useNavigation()`).
+ *
+ * SSR-safe: without a ClientRouter it returns an idle no-op.
+ */
+export function useRevalidator(): Revalidator {
+  const routerCtx = useContext(RouterContext);
+  if (!routerCtx) return { revalidate: noop, state: "idle" };
+  return { revalidate: routerCtx.revalidate, state: routerCtx.revalidationState };
+}

package/src/client/hooks/useSearch.ts

@@ -0,0 +1,73 @@
+import { useContext, useCallback } from "react";
+import { RouterContext, NavigationContext } from "../router.tsx";
+import { BractJSContext } from "../../shared/context.ts";
+import { serializeSearch } from "../search-serializer.ts";
+import type { SearchOutputFor } from "../registry.ts";
+
+// ── useSearch ──────────────────────────────────────────────────────────────
+
+/**
+ * The current route's VALIDATED search params — the output of its
+ * `searchSchema` export (numbers/booleans/arrays/defaults already applied),
+ * or the raw string record for routes without a schema.
+ *
+ * Validation happens once, on the server; this hook reads the validated object
+ * that rode in with the page (`__BRACTJS_DATA__`) or the last soft-nav
+ * (`/_data`) — the client never re-runs the schema.
+ *
+ * Type it against your codegen'd routes with a route literal —
+ * `useSearch<"/posts">()` → `{ page: number }` — or pass an explicit shape:
+ * `useSearch<{ page: number }>()`. SSR-safe.
+ */
+// Overload 1: a route literal → schema-output shape from the registry.
+export function useSearch<TTo extends string>(): SearchOutputFor<TTo>;
+// Overload 2: an explicit object shape.
+export function useSearch<T extends Record<string, unknown>>(): T;
+export function useSearch(): Record<string, unknown> {
+  const routerCtx = useContext(RouterContext);
+  const bractCtx = useContext(BractJSContext);
+  return routerCtx?.search ?? bractCtx?.search ?? {};
+}
+
+// ── useSetSearch ───────────────────────────────────────────────────────────
+
+export interface SetSearchOptions {
+  /** Replace the current history entry instead of pushing a new one. */
+  replace?: boolean;
+}
+
+export type SetSearchFn<T extends Record<string, unknown>> = (
+  updater: Partial<T> | ((prev: T) => Partial<T>),
+  options?: SetSearchOptions,
+) => Promise<void>;
+
+/**
+ * Returns a setter that merges a patch into the current search params,
+ * serializes the result back into the URL, and soft-navigates — so loaders
+ * re-run and the route's `searchSchema` re-validates server-side. Set a key
+ * to `undefined` to delete it.
+ *
+ *   const setSearch = useSetSearch<"/posts">();
+ *   setSearch({ page: 2 });                       // patch
+ *   setSearch((prev) => ({ page: prev.page + 1 })); // functional
+ *
+ * SSR-safe: without a ClientRouter it resolves to a no-op.
+ */
+export function useSetSearch<TTo extends string>(): SetSearchFn<SearchOutputFor<TTo>>;
+export function useSetSearch<T extends Record<string, unknown>>(): SetSearchFn<T>;
+export function useSetSearch(): SetSearchFn<Record<string, unknown>> {
+  const routerCtx = useContext(RouterContext);
+  const navCtx = useContext(NavigationContext);
+
+  return useCallback<SetSearchFn<Record<string, unknown>>>(
+    (updater, options) => {
+      if (!routerCtx || !navCtx) return Promise.resolve();
+      const prev = routerCtx.search;
+      const patch = typeof updater === "function" ? updater(prev) : updater;
+      const next = { ...prev, ...patch };
+      const target = routerCtx.location.pathname + serializeSearch(next);
+      return navCtx.navigate(target, { replace: options?.replace });
+    },
+    [routerCtx, navCtx],
+  );
+}

package/src/client/hooks/useSearchParams.ts

@@ -18,8 +18,13 @@ export interface SearchParamsResult<T extends Record<string, string>> {
 // ── Hook ───────────────────────────────────────────────────────────────────
 
 /**
- * Reads and writes URL search params. Triggers a loader re-run (soft-nav fetch)
- * when params change.
+ * Low-level read/write of raw `URLSearchParams` (string values only). Triggers a
+ * loader re-run (soft-nav fetch) when params change.
+ *
+ * Prefer `useSearch()` / `useSetSearch()` when the route has a `searchSchema`:
+ * those return the VALIDATED, coerced object (numbers stay numbers, defaults
+ * applied) and accept typed patches. Reach for `useSearchParams` only when you
+ * want raw string access or the route has no schema.
  *
  * Pass the route pattern as a generic to type the result against your codegen'd
  * routes: `useSearchParams<"/posts">()`. Augment `RouteSearchParamsMap` to give a

package/src/client/nav-utils.ts

@@ -22,6 +22,32 @@ export function toSamePath(loc: string): string | null {
   }
 }
 
+// ── Navigation target parsing ──────────────────────────────────────────────
+
+/**
+ * Split an internal navigation target ("/path", "/path?q", "/path#h",
+ * "/path?q#h") into its parts. Callers must normalize absolute URLs through
+ * `toSamePath()` first — this is a pure string split, not a URL parser.
+ */
+export function parseTo(to: string): { pathname: string; search: string; hash: string } {
+  const hashIdx = to.indexOf("#");
+  const hash = hashIdx === -1 ? "" : to.slice(hashIdx);
+  const beforeHash = hashIdx === -1 ? to : to.slice(0, hashIdx);
+  const searchIdx = beforeHash.indexOf("?");
+  const search = searchIdx === -1 ? "" : beforeHash.slice(searchIdx);
+  const pathname = searchIdx === -1 ? beforeHash : beforeHash.slice(0, searchIdx);
+  return { pathname: pathname || "/", search, hash };
+}
+
+/** Random short key identifying a history entry (scroll restoration identity). */
+export function createLocationKey(): string {
+  try {
+    return crypto.randomUUID().slice(0, 8);
+  } catch {
+    return Math.random().toString(36).slice(2, 10);
+  }
+}
+
 // ── Pattern Matching ───────────────────────────────────────────────────────
 
 /**

package/src/client/prefetch.ts

@@ -1,32 +1,127 @@
 import type { ServerManifest } from "../server/render.ts";
-import { matchPatternForPath } from "./nav-utils.ts";
+import { matchPatternForPath, parseTo } from "./nav-utils.ts";
+import { loaderCache, cacheKey } from "./cache.ts";
 
-// ── Cache ──────────────────────────────────────────────────────────────────
+// ── State ──────────────────────────────────────────────────────────────────
 
-const prefetched = new Set<string>();
+/** In-flight prefetches by path — concurrent callers share one task. */
+const inflight = new Map<string, Promise<void>>();
+
+/** Chunk hrefs already given a <link rel="modulepreload"> tag. */
+const preloadedChunks = new Set<string>();
+
+// Cap concurrent /_data prefetches so viewport-prefetching a long list of
+// links cannot stampede the server. Chunk modulepreload is cheap (served
+// immutable from cache) and stays uncapped.
+const MAX_DATA_PREFETCHES = 6;
+let activeDataPrefetches = 0;
+
+// Prefetched data gets at least this freshness window so a hover→click within
+// it commits straight from cache with zero extra requests (same idea as
+// TanStack Router's preloadStaleTime). Routes with a longer `config.staleTime`
+// keep their own.
+const PREFETCH_STALE_TIME = 30_000;
+const PREFETCH_GC_TIME = 60_000;
 
 // ── Implementation ─────────────────────────────────────────────────────────
 
 /**
- * Prefetches both the route chunk and loader data for the given path.
- * De-duplicates via a module-level Set — safe to call on every hover.
+ * Prefetches the route chunk (via `<link rel="modulepreload">`) and warms the
+ * loader cache for the given path, under the same cache key the router
+ * computes — so the eventual navigation commits instantly. Best-effort and
+ * de-duplicated; safe to call on every hover.
  */
-export function prefetchRoute(path: string, manifest: ServerManifest): void {
-  if (prefetched.has(path)) return;
-  prefetched.add(path);
+export function prefetchRoute(path: string, manifest: ServerManifest): Promise<void> {
+  const existing = inflight.get(path);
+  if (existing) return existing;
+
+  const task = doPrefetch(path, manifest)
+    .catch(() => { /* prefetch is best-effort — never surface errors */ })
+    .finally(() => { inflight.delete(path); });
+  inflight.set(path, task);
+  return task;
+}
 
-  // Prefetch route chunk via <link rel="modulepreload">
-  const pattern = matchPatternForPath(path, manifest);
+async function doPrefetch(path: string, manifest: ServerManifest): Promise<void> {
+  const { pathname, search } = parseTo(path);
+  const pattern = matchPatternForPath(pathname, manifest);
   const chunk = pattern !== null ? manifest.routes[pattern]?.chunk : undefined;
-  if (chunk) {
+
+  // 1. Warm the route chunk.
+  if (chunk && !preloadedChunks.has(chunk)) {
+    preloadedChunks.add(chunk);
     const link = document.createElement("link");
     link.rel = "modulepreload";
     link.href = chunk;
     document.head.appendChild(link);
   }
 
-  // Prefetch loader data at low priority
-  void fetch(`/_data?path=${encodeURIComponent(path)}`, {
-    priority: "low",
-  } as RequestInit);
+  // 2. Warm the loader cache. Importing the (already preloaded) chunk yields
+  //    config/loaderDeps, which the router uses to key the cache — without the
+  //    module we fall back to the path-keyed default, matching loadRoute.
+  const mod = chunk
+    ? (await import(/* @vite-ignore */ chunk).catch(() => null)) as Record<string, unknown> | null
+    : null;
+  const routeConfig = mod?.config as { staleTime?: number; gcTime?: number } | undefined;
+  const loaderDepsFn = mod?.loaderDeps as
+    | ((args: { searchParams: URLSearchParams }) => unknown[])
+    | undefined;
+  const dataPath = pathname + search;
+  const deps = loaderDepsFn ? loaderDepsFn({ searchParams: new URLSearchParams(search) }) : [dataPath];
+  const key = cacheKey(pathname, deps);
+
+  if (loaderCache.get(key)?.fresh) return; // already warm
+  if (activeDataPrefetches >= MAX_DATA_PREFETCHES) return;
+
+  activeDataPrefetches++;
+  try {
+    const res = await fetch(`/_data?path=${encodeURIComponent(dataPath)}`, {
+      priority: "low",
+    } as RequestInit);
+    if (!res.ok) return;
+    const data = (await res.json()) as Record<string, unknown>;
+    loaderCache.set(
+      key,
+      data,
+      Math.max(routeConfig?.staleTime ?? 0, PREFETCH_STALE_TIME),
+      Math.max(routeConfig?.gcTime ?? 0, PREFETCH_GC_TIME),
+    );
+  } finally {
+    activeDataPrefetches--;
+  }
+}
+
+// ── Viewport observation (shared) ──────────────────────────────────────────
+
+const observedCallbacks = new WeakMap<Element, () => void>();
+let observer: IntersectionObserver | null = null;
+
+/**
+ * Fire `callback` once when `el` first enters the viewport, via one shared
+ * IntersectionObserver (per-element observers are a perf trap on long lists).
+ * Returns an unsubscribe function. Environments without IntersectionObserver
+ * fire immediately.
+ */
+export function observeOnce(el: Element, callback: () => void): () => void {
+  if (typeof IntersectionObserver === "undefined") {
+    callback();
+    return () => {};
+  }
+  if (!observer) {
+    observer = new IntersectionObserver((entries) => {
+      for (const entry of entries) {
+        if (!entry.isIntersecting) continue;
+        const fire = observedCallbacks.get(entry.target);
+        observedCallbacks.delete(entry.target);
+        observer!.unobserve(entry.target);
+        if (fire) fire();
+      }
+    });
+  }
+  observedCallbacks.set(el, callback);
+  observer.observe(el);
+  return () => {
+    observedCallbacks.delete(el);
+    observer?.unobserve(el);
+  };
 }

package/src/client/registry.ts

@@ -94,6 +94,15 @@ export type RegisteredParamsMap =
 export type RegisteredSearchMap =
   Register extends { routes: { search: infer S } } ? S : Record<string, Record<string, string>>;
 
+/**
+ * Pattern → VALIDATED search shape (the output of each route's `searchSchema`),
+ * registered by codegen under `Register.routes.searchOutput`. Distinct from
+ * `RegisteredSearchMap`, which stays string-valued for the legacy
+ * `useSearchParams` surface.
+ */
+export type RegisteredSearchOutputMap =
+  Register extends { routes: { searchOutput: infer S } } ? S : Record<string, Record<string, unknown>>;
+
 /** Params object for a specific route literal (`{}` for static routes). */
 export type ParamsFor<TTo> =
   TTo extends keyof RegisteredParamsMap ? RegisteredParamsMap[TTo] : Record<string, string>;
@@ -102,6 +111,21 @@ export type ParamsFor<TTo> =
 export type SearchFor<TTo> =
   TTo extends keyof RegisteredSearchMap ? RegisteredSearchMap[TTo] : Record<string, string>;
 
+/** Validated (schema-output) search object for a specific route literal. */
+export type SearchOutputFor<TTo> =
+  TTo extends keyof RegisteredSearchOutputMap ? RegisteredSearchOutputMap[TTo] : Record<string, unknown>;
+
+/**
+ * Infer the output type of a Zod/Valibot-compatible schema — the duck-typed
+ * counterpart of `z.infer`. Used by the generated route types to derive each
+ * route's search shape from its `searchSchema` export.
+ */
+export type InferSchemaOutput<S> =
+  S extends { parse(input: unknown): infer T } ? T :
+  S extends { safeParse(input: unknown): infer R }
+    ? (Awaited<R> extends { data?: infer T } ? NonNullable<T> : Record<string, unknown>)
+    : Record<string, unknown>;
+
 /** Whether a route literal carries any path params. Reserved for a future strict `<Link>` mode. */
 export type HasParams<TTo> =
   keyof ParamsFor<TTo> extends never ? false : true;

package/src/client/revalidation.ts

@@ -0,0 +1,25 @@
+// Bridge between the router and fetchers. `useFetcher().submit` must trigger a
+// loader revalidation after its mutation, but the hook module cannot import
+// ClientRouter (circular); instead the router registers its revalidate
+// function here on mount.
+
+export interface RevalidationInfo {
+  /** The mutation's HTTP method, when revalidation follows an action. */
+  formMethod?: string;
+  /** The action response status, when mutation-triggered. */
+  actionStatus?: number;
+}
+
+type RevalidateFn = (info?: RevalidationInfo) => Promise<void>;
+
+let currentRevalidator: RevalidateFn | null = null;
+
+/** Called by ClientRouter on mount/unmount. Not part of the public API. */
+export function registerRevalidator(fn: RevalidateFn | null): void {
+  currentRevalidator = fn;
+}
+
+/** Revalidate the active route's loaders, if a router is mounted. */
+export function triggerRevalidation(info?: RevalidationInfo): Promise<void> {
+  return currentRevalidator ? currentRevalidator(info) : Promise.resolve();
+}

package/src/client/router.tsx

@@ -1,26 +1,52 @@
 import { createContext, useContext, type ComponentType } from "react";
 import type { ServerManifest } from "../server/render.ts";
+import type { RouterLocation, RouteMatch } from "../shared/route-types.ts";
 
 // ── Route module shape visible on the client ───────────────────────────────
 
 export interface RouteModuleClient {
   default?: ComponentType;
   ErrorBoundary?: ComponentType<{ error: Error }>;
+  /** SSR'd placeholder for selective-SSR routes (`ssr: false` / `"data-only"`). */
+  Fallback?: ComponentType;
+  /** Browser-side loader (RR7-style). Runs on navigation instead of just fetching /_data. */
+  clientLoader?: import("../shared/route-types.ts").ClientLoaderFunction;
+  /** Browser-side action (RR7-style). Runs on submit instead of POSTing directly. */
+  clientAction?: import("../shared/route-types.ts").ClientActionFunction;
 }
 
+/**
+ * Truthy while the initial client render must keep showing what the server
+ * sent instead of the real route component: the Fallback for selective-SSR
+ * documents, nothing for the SPA shell. Cleared (→ `false`) once loader data
+ * is in place.
+ */
+export type HydrationPending = false | "client-only" | "data-only" | "spa";
+
 // ── Router Context ─────────────────────────────────────────────────────────
 
 export interface RouteState {
   loaderData: Record<string, unknown>;
   actionData: unknown;
   params: Record<string, string>;
+  /** Query-free pathname of the current route (kept alongside `location` for back-compat). */
   pathname: string;
+  location: RouterLocation;
+  /** Validated search params (route `searchSchema` output; raw string record otherwise). */
+  search: Record<string, unknown>;
+  /** The matched route chain (root → layouts → route) for `useMatches()`. */
+  matches: RouteMatch[];
 }
 
 export interface RouterContextValue extends RouteState {
   manifest: ServerManifest;
   currentModule: RouteModuleClient | null;
   setRoute(state: Partial<RouteState>): void;
+  /** Re-run the active route's loaders (gated by `shouldRevalidate`). */
+  revalidate(): Promise<void>;
+  /** "loading" while a revalidation is in flight. Distinct from the navigation state. */
+  revalidationState: "idle" | "loading";
+  hydrationPending: HydrationPending;
 }
 
 export const RouterContext = createContext<RouterContextValue>(null!);
@@ -37,9 +63,16 @@ export function useRouterContext(): RouterContextValue {
 
 export type NavigationState = "idle" | "loading" | "submitting";
 
+export interface NavigateOptions {
+  /** Replace the current history entry instead of pushing a new one. */
+  replace?: boolean;
+  /** Arbitrary history state, readable via `useLocation().state` after the navigation. */
+  state?: unknown;
+}
+
 export interface NavigationContextValue {
   state: NavigationState;
-  navigate(to: string): Promise<void>;
+  navigate(to: string, options?: NavigateOptions): Promise<void>;
   submit(to: string, options: { method: string; body: FormData | Record<string, string> }): Promise<void>;
 }
 

package/src/client/rpc.ts

@@ -49,9 +49,19 @@ export function createClient<
             const httpMethod = method.toUpperCase();
             const url = baseUrl + path;
             const hasBody = httpMethod !== "GET" && httpMethod !== "DELETE" && input !== undefined;
+            // Send the custom CSRF marker on every mutating call. The server's
+            // /api CSRF gate accepts Sec-Fetch-Site / Origin too, but this
+            // header keeps same-origin calls working even behind proxies that
+            // strip those — and it can't be set cross-origin without a CORS
+            // preflight the framework's CORS never grants. Mirrors the
+            // server-action proxy in src/build/directives.ts.
+            const isMutating = httpMethod !== "GET";
+            const headers: Record<string, string> = {};
+            if (hasBody) headers["Content-Type"] = "application/json";
+            if (isMutating) headers["X-BractJS-Action"] = "1";
             const res = await fetch(url, {
               method: httpMethod,
-              headers: hasBody ? { "Content-Type": "application/json" } : undefined,
+              headers: Object.keys(headers).length > 0 ? headers : undefined,
               body: hasBody ? JSON.stringify(input) : undefined,
             });
             if (!res.ok) {

package/src/client/scroll-restoration.ts

@@ -0,0 +1,48 @@
+// Pure helpers for <ScrollRestoration /> — kept DOM-free so they are
+// unit-testable under bun:test without a browser.
+
+export const SCROLL_STORAGE_KEY = "bractjs:scroll";
+
+/** Cap stored entries so sessionStorage doesn't grow unbounded in long sessions. */
+export const MAX_SCROLL_ENTRIES = 50;
+
+/**
+ * Record a scroll position for a history-entry key. Re-inserts the key so the
+ * map keeps insertion order as LRU order, then evicts the oldest entries past
+ * the cap.
+ */
+export function savePosition(
+  positions: Map<string, number>,
+  key: string,
+  y: number,
+  max: number = MAX_SCROLL_ENTRIES,
+): void {
+  positions.delete(key);
+  positions.set(key, y);
+  while (positions.size > max) {
+    const oldest = positions.keys().next().value;
+    if (oldest === undefined) break;
+    positions.delete(oldest);
+  }
+}
+
+export function serializePositions(positions: Map<string, number>): string {
+  return JSON.stringify(Object.fromEntries(positions));
+}
+
+/** Tolerant parse: malformed/foreign payloads yield an empty map, never throw. */
+export function deserializePositions(raw: string | null): Map<string, number> {
+  if (!raw) return new Map();
+  try {
+    const obj = JSON.parse(raw) as Record<string, unknown>;
+    const positions = new Map<string, number>();
+    if (obj && typeof obj === "object" && !Array.isArray(obj)) {
+      for (const [key, value] of Object.entries(obj)) {
+        if (typeof value === "number" && Number.isFinite(value)) positions.set(key, value);
+      }
+    }
+    return positions;
+  } catch {
+    return new Map();
+  }
+}