@bractjs/bractjs 0.1.27 → 0.1.29

package/src/client/components/Link.tsx

@@ -1,11 +1,28 @@
-import { useContext, type AnchorHTMLAttributes, type ReactNode } from "react";
+import {
+  useContext, useEffect, useRef, useCallback,
+  type AnchorHTMLAttributes, type ReactNode,
+} from "react";
 import { NavigationContext, RouterContext } from "../router.tsx";
-import { prefetchRoute } from "../prefetch.ts";
+import { prefetchRoute, observeOnce } from "../prefetch.ts";
 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 ──────────────────────────────────────────────────────────────────
 
+/**
+ * When to prefetch the target route's chunk + loader data:
+ * - `"none"` (default) — never.
+ * - `"intent"` — on hover/focus, after a short delay (canceled if the pointer
+ *   leaves). The best default for most links.
+ * - `"hover"` — immediately on mouseenter (legacy alias of intent without the
+ *   delay; kept for back-compat).
+ * - `"viewport"` — when the link scrolls into view (shared
+ *   IntersectionObserver). Good for lists.
+ * - `"render"` — as soon as the link mounts.
+ */
+type PrefetchMode = "none" | "intent" | "hover" | "viewport" | "render";
+
 // `to` accepts any registered route literal (autocomplete + typed `params`) but
 // also any string via `(string & {})`, so existing call sites that build the URL
 // themselves — `to={`/posts/${slug}`}`, `to={item.href}` — keep compiling. Run
@@ -18,9 +35,13 @@ type LinkProps<TTo extends RegisteredRoutes = RegisteredRoutes> = Omit<
   to: TTo | (string & {});
   /** Path params for a dynamic `to` (e.g. `params={{ id }}` for `/blog/:id`). */
   params?: ParamsFor<TTo>;
-  prefetch?: "hover" | "none";
+  /** Search params for the target, typed by its `searchSchema` (replaces any query in `to`). */
+  search?: Partial<SearchOutputFor<TTo>>;
+  prefetch?: PrefetchMode;
   /** Opt in to View Transitions API for this navigation (E1). */
   viewTransition?: boolean;
+  /** Replace the current history entry instead of pushing. */
+  replace?: boolean;
   children: ReactNode;
 };
 
@@ -31,11 +52,16 @@ const supportsViewTransitions =
   typeof document !== "undefined" &&
   typeof (document as Document & { startViewTransition?: unknown }).startViewTransition === "function";
 
+/** Hover-intent delay before prefetching — cancels on a fly-by pointer. */
+const INTENT_DELAY_MS = 100;
+
 export function Link<TTo extends RegisteredRoutes = RegisteredRoutes>({
   to,
   params,
+  search,
   prefetch = "none",
   viewTransition = false,
+  replace,
   children,
   ...rest
 }: LinkProps<TTo>) {
@@ -44,8 +70,32 @@ export function Link<TTo extends RegisteredRoutes = RegisteredRoutes>({
   const isLoading = navCtx?.state === "loading";
 
   // Resolve the final href once: substitute params into a dynamic pattern, or
-  // pass an already-built string straight through.
-  const href = params ? buildPath(to as string, params as Record<string, string>) : (to as string);
+  // pass an already-built string straight through; then apply `search`.
+  const base = params ? buildPath(to as string, params as Record<string, string>) : (to as string);
+  const href = withSearch(base, search as Record<string, unknown> | undefined);
+
+  const anchorRef = useRef<HTMLAnchorElement>(null);
+  const intentTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const triggerPrefetch = useCallback(() => {
+    if (routerCtx) void prefetchRoute(href, routerCtx.manifest);
+  }, [href, routerCtx]);
+
+  // viewport / render modes register in an effect — SSR renders a plain <a>.
+  useEffect(() => {
+    if (prefetch === "render") {
+      triggerPrefetch();
+      return;
+    }
+    if (prefetch === "viewport" && anchorRef.current) {
+      return observeOnce(anchorRef.current, triggerPrefetch);
+    }
+  }, [prefetch, triggerPrefetch]);
+
+  // Cancel a pending intent timer on unmount.
+  useEffect(() => () => {
+    if (intentTimer.current) clearTimeout(intentTimer.current);
+  }, []);
 
   function handleClick(e: React.MouseEvent<HTMLAnchorElement>) {
     if (!navCtx) return; // SSR: let browser handle naturally
@@ -54,22 +104,43 @@ export function Link<TTo extends RegisteredRoutes = RegisteredRoutes>({
 
     if (viewTransition && supportsViewTransitions) {
       (document as Document & { startViewTransition(cb: () => void): void }).startViewTransition(
-        () => { void navCtx.navigate(href); },
+        () => { void navCtx.navigate(href, { replace }); },
       );
     } else {
-      void navCtx.navigate(href);
+      void navCtx.navigate(href, { replace });
+    }
+  }
+
+  function startIntent() {
+    if (prefetch !== "intent" || intentTimer.current) return;
+    intentTimer.current = setTimeout(() => {
+      intentTimer.current = null;
+      triggerPrefetch();
+    }, INTENT_DELAY_MS);
+  }
+
+  function cancelIntent() {
+    if (intentTimer.current) {
+      clearTimeout(intentTimer.current);
+      intentTimer.current = null;
     }
   }
 
   function handleMouseEnter() {
-    if (prefetch === "hover" && routerCtx) prefetchRoute(href, routerCtx.manifest);
+    if (prefetch === "hover") triggerPrefetch();
+    else startIntent();
   }
 
   return (
     <a
       href={href}
+      ref={anchorRef}
       onClick={handleClick}
       onMouseEnter={handleMouseEnter}
+      onMouseLeave={cancelIntent}
+      onFocus={startIntent}
+      onBlur={cancelIntent}
+      onTouchStart={prefetch === "intent" || prefetch === "hover" ? triggerPrefetch : undefined}
       aria-disabled={isLoading || undefined}
       {...rest}
     >

package/src/client/components/Outlet.tsx

@@ -41,8 +41,14 @@ export function Outlet(): ReactElement | null {
   // Server-side (SSR): fall back to BractJSContext which carries RouteComponent
   const bractCtx = useContext(BractJSContext);
 
-  const RouteComponent: ComponentType | undefined =
-    routerCtx?.currentModule?.default ?? bractCtx?.RouteComponent;
+  // While selective-SSR hydration is pending, render exactly what the server
+  // sent: the route's Fallback ("client-only"/"data-only" documents) or
+  // nothing (the "spa" shell knows no route at build time). Rendering the real
+  // component here would mismatch the server HTML.
+  const pending = routerCtx?.hydrationPending;
+  const RouteComponent: ComponentType | undefined = pending
+    ? (pending === "spa" ? undefined : routerCtx?.currentModule?.Fallback)
+    : routerCtx?.currentModule?.default ?? bractCtx?.RouteComponent;
   const ErrorFallback: ComponentType<{ error: Error }> =
     routerCtx?.currentModule?.ErrorBoundary ?? DefaultErrorFallback;
 

package/src/client/components/ScrollRestoration.tsx

@@ -0,0 +1,125 @@
+import { useEffect, useLayoutEffect, useRef } from "react";
+import { useLocation } from "../hooks/useLocation.ts";
+import type { RouterLocation } from "../../shared/route-types.ts";
+import {
+  SCROLL_STORAGE_KEY,
+  savePosition,
+  serializePositions,
+  deserializePositions,
+} from "../scroll-restoration.ts";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface ScrollRestorationProps {
+  /**
+   * Derive the storage key for a location. Defaults to `location.key` (one
+   * position per history entry). Return e.g. `location.pathname` to share one
+   * position across every visit to the same path.
+   */
+  getKey?: (location: RouterLocation) => string;
+  /** sessionStorage key holding the persisted positions. */
+  storageKey?: string;
+}
+
+// ── Component ──────────────────────────────────────────────────────────────
+
+// useLayoutEffect warns during SSR; the component renders nothing and the
+// effect only matters in the browser, so alias it away on the server.
+const useBrowserLayoutEffect = typeof document !== "undefined" ? useLayoutEffect : useEffect;
+
+/**
+ * Emulates the browser's scroll restoration on soft navigations. Render it
+ * once in `app/root.tsx` (next to `<Scripts />`).
+ *
+ * Behavior: returning to a history entry (back/forward, reload) restores its
+ * saved scroll position; navigating to a new entry scrolls to the top, or to
+ * the `#fragment` element when the target has one. Positions are tracked from
+ * scroll events (so the leaving page's offset is never lost to layout
+ * clamping) and persisted to sessionStorage across reloads.
+ */
+export function ScrollRestoration({ getKey, storageKey = SCROLL_STORAGE_KEY }: ScrollRestorationProps): null {
+  const location = useLocation();
+
+  const getKeyRef = useRef(getKey);
+  useEffect(() => { getKeyRef.current = getKey; });
+
+  // Lazily hydrated from sessionStorage on first access — the restore layout
+  // effect runs before mount effects, so eager hydration would come too late.
+  const positionsRef = useRef<Map<string, number> | null>(null);
+  const getPositions = (): Map<string, number> => {
+    if (positionsRef.current === null) {
+      positionsRef.current = deserializePositions(sessionStorage.getItem(storageKey));
+    }
+    return positionsRef.current;
+  };
+
+  /** Storage key of the entry currently on screen (what scroll events record). */
+  const activeKeyRef = useRef<string | null>(null);
+
+  // Take manual control + persist across reloads/full navigations.
+  useEffect(() => {
+    if ("scrollRestoration" in history) history.scrollRestoration = "manual";
+    const persist = () => {
+      if (positionsRef.current !== null) {
+        try {
+          sessionStorage.setItem(storageKey, serializePositions(positionsRef.current));
+        } catch {
+          // Storage full/blocked — restoration degrades to in-memory only.
+        }
+      }
+    };
+    window.addEventListener("pagehide", persist);
+    return () => {
+      window.removeEventListener("pagehide", persist);
+      persist();
+    };
+  }, [storageKey]);
+
+  // Continuously record the active entry's position (rAF-throttled). Recording
+  // from scroll events — rather than snapshotting at navigation time — means
+  // the position is already saved before the new page's (possibly shorter)
+  // content clamps window.scrollY.
+  useEffect(() => {
+    let frame = 0;
+    const onScroll = () => {
+      if (frame) return;
+      frame = requestAnimationFrame(() => {
+        frame = 0;
+        if (activeKeyRef.current !== null) {
+          savePosition(getPositions(), activeKeyRef.current, window.scrollY);
+        }
+      });
+    };
+    window.addEventListener("scroll", onScroll, { passive: true });
+    return () => {
+      window.removeEventListener("scroll", onScroll);
+      if (frame) cancelAnimationFrame(frame);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Apply scroll on every committed location change (and on first mount, which
+  // restores the position after a reload).
+  useBrowserLayoutEffect(() => {
+    const key = getKeyRef.current ? getKeyRef.current(location) : location.key;
+    if (activeKeyRef.current === key) return;
+    activeKeyRef.current = key;
+
+    const saved = getPositions().get(key);
+    if (typeof saved === "number") {
+      window.scrollTo(0, saved);
+      return;
+    }
+    if (location.hash) {
+      const el = document.getElementById(location.hash.slice(1));
+      if (el) {
+        el.scrollIntoView();
+        return;
+      }
+    }
+    window.scrollTo(0, 0);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [location]);
+
+  return null;
+}

package/src/client/entry.tsx

@@ -20,6 +20,25 @@ function FallbackApp(): ReactElement {
 (async () => {
   const data: BractJSClientData = window.__BRACTJS_DATA__;
 
+  // Dev-only: surface a loader error captured during SSR in the error overlay.
+  // safeRun serializes failures as `{ __error: { message, stack, routeFile } }`
+  // into each loader slot; this is the overlay's producer (the overlay script
+  // installs a __BRACTJS_ERROR__ setter but nothing assigned it before).
+  if ((window as unknown as { __BRACT_DEV__?: boolean }).__BRACT_DEV__) {
+    const slots = [data.loaderData?.root, data.loaderData?.route, ...((data.loaderData?.layouts as unknown[]) ?? [])];
+    for (const slot of slots) {
+      const e = (slot as { __error?: { message?: string; stack?: string; routeFile?: string } } | null)?.__error;
+      if (e) {
+        const where = e.routeFile ? ` in ${e.routeFile}` : "";
+        (window as unknown as { __BRACTJS_ERROR__?: unknown }).__BRACTJS_ERROR__ = {
+          message: `Loader error${where}: ${e.message ?? "unknown error"}`,
+          stack: e.stack,
+        };
+        break;
+      }
+    }
+  }
+
   // 1. Import the root component (app/root.tsx) so the client tree matches
   //    the server-rendered shell (html, head, body, header, nav, etc.).
   let RootComponent: ComponentType = FallbackApp;
@@ -28,9 +47,13 @@ function FallbackApp(): ReactElement {
     if (rootMod.default) RootComponent = rootMod.default;
   }
 
+  // The SPA shell is built once for "/" and served for every document path —
+  // the browser URL, not the payload, says where we actually are.
+  const initialPathname = data.ssrMode === "spa" ? window.location.pathname : data.pathname;
+
   // 2. Pre-load the current route module so <Outlet> sees it during hydration.
   let initialModule: RouteModuleClient | null = null;
-  const pattern = matchPatternForPath(data.pathname, data.manifest);
+  const pattern = matchPatternForPath(initialPathname, data.manifest);
   const chunkUrl = pattern !== null ? data.manifest.routes[pattern]?.chunk : undefined;
 
   if (chunkUrl) {
@@ -40,9 +63,23 @@ function FallbackApp(): ReactElement {
     initialModule = (await import(url)) as RouteModuleClient;
   }
 
+  // Initial location: pathname comes from the server payload; search is
+  // identical to the request's by construction. The hash never reaches the
+  // server, so it is only known here.
+  const initialLocation = {
+    pathname: initialPathname,
+    search: window.location.search,
+    hash: window.location.hash,
+    state: null,
+    key: "default",
+  };
+
   hydrateRoot(
     document,
-    <ClientRouter initialData={data} initialModule={initialModule}>
+    <ClientRouter
+      initialData={{ ...data, location: initialLocation, search: data.search ?? {} }}
+      initialModule={initialModule}
+    >
       <RootComponent />
     </ClientRouter>,
   );

package/src/client/fetcher-store.ts

@@ -0,0 +1,61 @@
+// Module-level fetcher state, shaped for React's useSyncExternalStore. Giving
+// fetchers identity outside component state is what makes optimistic UI work:
+// a keyed fetcher survives remounts, and `useFetchers()` lets any component
+// observe every in-flight mutation (e.g. dim a list row while its delete
+// fetcher is submitting elsewhere in the tree).
+
+export type FetcherState = "idle" | "loading" | "submitting";
+
+export interface FetcherEntry {
+  key: string;
+  state: FetcherState;
+  data: unknown;
+  /** The submitted form data, available from the moment submit() is called — read this for optimistic UI. */
+  formData?: FormData;
+  /** Uppercase HTTP method of the in-flight/last submission. */
+  formMethod?: string;
+}
+
+type Listener = () => void;
+
+const IDLE_ENTRY: Omit<FetcherEntry, "key"> = { state: "idle", data: undefined };
+
+class FetcherStore {
+  private entries = new Map<string, FetcherEntry>();
+  private listeners = new Set<Listener>();
+  // Snapshots must be referentially stable between emits or
+  // useSyncExternalStore loops. Rebuilt only inside emit().
+  private snapshot: FetcherEntry[] = [];
+
+  get(key: string): FetcherEntry | undefined {
+    return this.entries.get(key);
+  }
+
+  update(key: string, partial: Partial<Omit<FetcherEntry, "key">>): void {
+    const prev = this.entries.get(key) ?? { key, ...IDLE_ENTRY };
+    this.entries.set(key, { ...prev, ...partial });
+    this.emit();
+  }
+
+  remove(key: string): void {
+    if (this.entries.delete(key)) this.emit();
+  }
+
+  subscribe = (listener: Listener): (() => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  /** All current entries (stable reference between updates). */
+  getSnapshot = (): FetcherEntry[] => this.snapshot;
+
+  private emit(): void {
+    this.snapshot = Array.from(this.entries.values());
+    for (const listener of this.listeners) listener();
+  }
+}
+
+export const fetcherStore = new FetcherStore();
+
+/** Stable server snapshot — SSR renders with no active fetchers. */
+export const EMPTY_FETCHERS: FetcherEntry[] = [];

package/src/client/form-utils.ts

@@ -1,5 +1,8 @@
 /**
  * Fetches fresh loader data for a pathname and updates the router context.
+ *
+ * @deprecated `<Form>` now revalidates through the router (see
+ * `useRevalidator`); kept only for callers that imported this directly.
  */
 export async function reloadLoaders(
   pathname: string,

package/src/client/hooks/useActionData.ts

@@ -1,14 +1,18 @@
 import { useContext } from "react";
 import { RouterContext } from "../router.tsx";
 import { BractJSContext } from "../../shared/context.ts";
+import type { ActionData } from "../../shared/route-types.ts";
 
 /**
- * Returns the current route's action data, typed as T | null.
+ * Returns the current route's action data, or null until an action has run.
  * Works in both SSR and client contexts.
+ *
+ * Prefer passing the action function type — `useActionData<typeof action>()` —
+ * so the type is inferred from the action's return. An explicit type still works.
  */
-export function useActionData<T = unknown>(): T | null {
+export function useActionData<T = unknown>(): ActionData<T> | null {
   const router = useContext(RouterContext);
   const bract = useContext(BractJSContext);
   const actionData = router?.actionData ?? bract?.actionData ?? null;
-  return actionData as T | null;
+  return actionData as ActionData<T> | null;
 }

package/src/client/hooks/useFetcher.ts

@@ -1,27 +1,57 @@
-import { useState } from "react";
+import {
+  createElement, useCallback, useEffect, useId, useMemo, useSyncExternalStore,
+  type FormEvent, type FormHTMLAttributes, type FunctionComponent, type ReactNode,
+} from "react";
 import { toSamePath } from "../nav-utils.ts";
+import { fetcherStore, type FetcherState } from "../fetcher-store.ts";
+import { triggerRevalidation } from "../revalidation.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
-type FetcherState = "idle" | "loading" | "submitting";
-
 interface SubmitOptions {
   method: string;
   body: FormData | Record<string, string>;
 }
 
-interface FetcherResult {
+export interface FetcherFormProps extends Omit<FormHTMLAttributes<HTMLFormElement>, "method" | "onSubmit"> {
+  method?: "post" | "put" | "delete";
+  action?: string;
+  /** Renders a hidden `intent` input (pairs with `defineActions()`). */
+  intent?: string;
+  children: ReactNode;
+}
+
+export interface FetcherResult {
   data: unknown;
   state: FetcherState;
+  /** The submitted FormData while a submission is in flight — the optimistic-UI source. */
+  formData?: FormData;
+  /** Uppercase method of the in-flight/last submission. */
+  formMethod?: string;
+  /** This fetcher's identity (explicit `key` option, or component-bound). */
+  key: string;
   load(path: string): Promise<void>;
   submit(path: string, opts: SubmitOptions): Promise<void>;
+  /** A `<fetcher.Form>` that submits through this fetcher (no navigation, no history). */
+  Form: FunctionComponent<FetcherFormProps>;
 }
 
 interface StreamFetcherResult<T = unknown> {
+  /** @deprecated Never emitted — call `connect(actionId)` instead. Removed in 0.2. */
   events: AsyncGenerator<T>;
   connect(actionId: string): AsyncGenerator<T>;
 }
 
+export interface UseFetcherOptions {
+  /**
+   * Give the fetcher a stable identity. Keyed fetchers persist across
+   * unmounts and are shared by every component using the same key; unkeyed
+   * fetchers are removed from `useFetchers()` when their component unmounts.
+   */
+  key?: string;
+  stream?: boolean;
+}
+
 // ── SSE async generator ────────────────────────────────────────────────────
 
 async function* sseStream<T>(actionId: string): AsyncGenerator<T> {
@@ -66,46 +96,60 @@ async function* sseStream<T>(actionId: string): AsyncGenerator<T> {
 
 // ── Hook ───────────────────────────────────────────────────────────────────
 
-export function useFetcher(): FetcherResult;
+const EMPTY_ENTRY = undefined;
+
+export function useFetcher(opts?: { key?: string }): FetcherResult;
 export function useFetcher<T>(opts: { stream: true }): StreamFetcherResult<T>;
-export function useFetcher<T>(opts?: { stream?: boolean }): FetcherResult | StreamFetcherResult<T> {
-  if (opts?.stream) {
-    return {
-      events: (null as unknown) as AsyncGenerator<T>,
-      connect(actionId: string): AsyncGenerator<T> {
-        return sseStream<T>(actionId);
-      },
-    } satisfies StreamFetcherResult<T>;
-  }
+export function useFetcher<T = unknown>(opts?: UseFetcherOptions): FetcherResult | StreamFetcherResult<T> {
+  // All hooks run unconditionally — branching on opts.stream happens only in
+  // the returned value, so the rules of hooks hold for every variant.
+  const autoKey = useId();
+  const key = opts?.key ?? `__fetcher${autoKey}`;
+
+  const entry = useSyncExternalStore(
+    fetcherStore.subscribe,
+    () => fetcherStore.get(key),
+    () => EMPTY_ENTRY,
+  );
 
-  // eslint-disable-next-line react-hooks/rules-of-hooks
-  const [data, setData] = useState<unknown>(undefined);
-  // eslint-disable-next-line react-hooks/rules-of-hooks
-  const [state, setState] = useState<FetcherState>("idle");
+  // Unkeyed fetchers disappear from useFetchers() with their component; keyed
+  // ones persist so optimistic state survives remounts.
+  const isKeyed = opts?.key !== undefined;
+  useEffect(() => {
+    if (isKeyed) return;
+    return () => fetcherStore.remove(key);
+  }, [key, isKeyed]);
 
-  async function load(path: string): Promise<void> {
-    setState("loading");
+  const load = useCallback(async (path: string): Promise<void> => {
+    fetcherStore.update(key, { state: "loading" });
     try {
       const res = await fetch(`/_data?path=${encodeURIComponent(path)}`);
       const json = (await res.json()) as { route?: unknown };
-      setData(json.route);
+      fetcherStore.update(key, { data: json.route });
     } finally {
-      setState("idle");
+      fetcherStore.update(key, { state: "idle" });
     }
-  }
+  }, [key]);
 
-  async function submit(path: string, submitOpts: SubmitOptions): Promise<void> {
-    setState("submitting");
+  const submit = useCallback(async (path: string, submitOpts: SubmitOptions): Promise<void> => {
+    const body =
+      submitOpts.body instanceof FormData
+        ? submitOpts.body
+        : new URLSearchParams(submitOpts.body as Record<string, string>);
+    const formMethod = submitOpts.method.toUpperCase();
+    // Expose the submission BEFORE the fetch — this is what optimistic UI
+    // renders while the mutation is in flight.
+    fetcherStore.update(key, {
+      state: "submitting",
+      formData: submitOpts.body instanceof FormData ? submitOpts.body : undefined,
+      formMethod,
+    });
     try {
-      const body =
-        submitOpts.body instanceof FormData
-          ? submitOpts.body
-          : new URLSearchParams(submitOpts.body as Record<string, string>);
       // Send the custom header so the server's CSRF gate accepts this
       // same-origin mutation (browsers block it cross-origin without a CORS
       // preflight). Without it every fetcher submit 403s.
       const res = await fetch(path, {
-        method: submitOpts.method,
+        method: formMethod,
         body,
         headers: { "X-BractJS-Action": "1" },
       });
@@ -117,11 +161,50 @@ export function useFetcher<T>(opts?: { stream?: boolean }): FetcherResult | Stre
         window.location.assign(to ?? res.url);
         return;
       }
-      setData(await res.json());
+      fetcherStore.update(key, { data: await res.json() });
+      // Mutations invalidate loader data — re-run the active route's loaders
+      // (gated by its shouldRevalidate) so the page reflects the change.
+      fetcherStore.update(key, { state: "loading" });
+      await triggerRevalidation({ formMethod, actionStatus: res.status });
     } finally {
-      setState("idle");
+      fetcherStore.update(key, { state: "idle", formData: undefined });
     }
+  }, [key]);
+
+  // Stable component identity across renders (remounting a form on every
+  // render would drop focus/IME state).
+  const FetcherForm = useMemo<FunctionComponent<FetcherFormProps>>(() => {
+    return function FetcherFormImpl({ method = "post", action, intent, children, ...rest }: FetcherFormProps) {
+      function handleSubmit(e: FormEvent<HTMLFormElement>) {
+        e.preventDefault();
+        const target = e.currentTarget;
+        const url = action ?? window.location.pathname + window.location.search;
+        void submit(url, { method, body: new FormData(target) });
+      }
+      const intentInput = intent !== undefined
+        ? createElement("input", { key: "__bract_intent", type: "hidden", name: "intent", value: intent })
+        : null;
+      return createElement("form", { method, onSubmit: handleSubmit, ...rest }, intentInput, children);
+    };
+  }, [submit]);
+
+  if (opts?.stream) {
+    return {
+      events: (null as unknown) as AsyncGenerator<T>,
+      connect(actionId: string): AsyncGenerator<T> {
+        return sseStream<T>(actionId);
+      },
+    } satisfies StreamFetcherResult<T>;
   }
 
-  return { data, state, load, submit };
+  return {
+    data: entry?.data,
+    state: entry?.state ?? "idle",
+    formData: entry?.formData,
+    formMethod: entry?.formMethod,
+    key,
+    load,
+    submit,
+    Form: FetcherForm,
+  };
 }

package/src/client/hooks/useFetchers.ts

@@ -0,0 +1,23 @@
+import { useSyncExternalStore } from "react";
+import { fetcherStore, EMPTY_FETCHERS, type FetcherEntry } from "../fetcher-store.ts";
+
+/**
+ * Every active fetcher (keyed and mounted-unkeyed alike) — the cross-component
+ * view for optimistic UI. Example: a table dims each row whose keyed delete
+ * fetcher (`useFetcher({ key: "delete-" + id })`) is currently submitting:
+ *
+ *   const deleting = new Set(
+ *     useFetchers()
+ *       .filter((f) => f.state === "submitting" && f.key.startsWith("delete-"))
+ *       .map((f) => f.key.slice("delete-".length)),
+ *   );
+ *
+ * SSR-safe: renders an empty list on the server.
+ */
+export function useFetchers(): FetcherEntry[] {
+  return useSyncExternalStore(
+    fetcherStore.subscribe,
+    fetcherStore.getSnapshot,
+    () => EMPTY_FETCHERS,
+  );
+}