@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/src/client/error-boundary.tsx

@@ -18,22 +18,30 @@
  * See design/10-error-handling.md §"Status-Code Files"
  */
 
-import { Component, createElement, type ReactNode } from 'react';
-import { getSsrData } from './ssr-data.js';
-
-// ─── Page Unload Detection ───────────────────────────────────────────────────
-// Track whether the page is being unloaded (user refreshed or navigated away).
-// When this is true, error boundaries suppress activation — the error is from
-// the aborted connection, not an application error.
-let _isUnloading = false;
-if (typeof window !== 'undefined') {
-  window.addEventListener('beforeunload', () => {
-    _isUnloading = true;
-  });
-  window.addEventListener('pagehide', () => {
-    _isUnloading = true;
-  });
-}
+import { Component, createContext, createElement, useContext, type ReactNode } from 'react';
+import { getSsrData } from './ssr-data.ts';
+import { getRouterOrNull } from './router-ref.ts';
+import { markStaleFromError } from './stale-client.ts';
+import { StatusPageMarker } from './status-page-marker.tsx';
+import { leaveSpa } from './router-effects.ts';
+// Page unload detection: when the page is being torn down, error boundaries
+// suppress activation — the error is from the aborted connection, not the
+// application. unload-guard.ts is the single owner of that state; this module
+// used to keep its own copy, which drifted (TIM-1260).
+import { isPageUnloading } from './unload-guard.ts';
+
+// ─── Ancestry Context ────────────────────────────────────────────────────────
+
+/**
+ * Tracks the chain of segment keys from root to the current boundary.
+ * Each keyed `TimberErrorBoundary` appends its `segmentKey`; unkeyed
+ * slot boundaries pass the parent value through. The claim rule uses
+ * this to find the first *reachable* owner from the `owners` list,
+ * eliminating the owner-below-throw-site escape. See TIM-1450.
+ */
+const DenyAncestryContext = createContext<readonly string[]>([]);
+
+export { DenyAncestryContext };
 
 // ─── Digest Types ────────────────────────────────────────────────────────────
 
@@ -42,6 +50,14 @@ interface DenyDigest {
   type: 'deny';
   status: number;
   data: unknown;
+  /**
+   * Ordered candidate owners — segment keys of segments with matching deny
+   * pages, best match first. Present = addressed (a boundary should render
+   * it). In-tree hoists produce a single-element list; late addressing
+   * (TIM-1450) produces the full candidate list so the boundary can find the
+   * first *reachable* owner via its ancestry context.
+   */
+  owners?: string[];
 }
 
 /** Structured digest returned by RSC onError for RenderError. */
@@ -65,19 +81,47 @@ type ParsedDigest = DenyDigest | RenderErrorDigest | RedirectDigest;
 
 export interface TimberErrorBoundaryProps {
   /** The component to render when an error is caught. */
-  fallbackComponent: (...args: unknown[]) => ReactNode;
+  fallbackComponent?: (...args: unknown[]) => ReactNode;
+  /**
+   * Pre-rendered fallback element. Used for MDX status files which are server
+   * components and cannot be passed as function props across the RSC→client
+   * boundary. When set, rendered directly instead of calling fallbackComponent.
+   *
+   * See design/10-error-handling.md §"Status-Code File Variants" — MDX status
+   * files are server components by default (zero client JS).
+   */
+  fallbackElement?: ReactNode;
   /**
    * Status code filter. If set, only catches errors matching this status.
    * 400 = any 4xx, 500 = any 5xx, specific number = exact match.
    */
   status?: number;
   /**
-   * When true, catching a DenySignal sets _denyHandledByBoundary on the
-   * nav context to prevent page-level deny promotion. Only slot catch-all
-   * boundaries should set this — segment boundaries (403.tsx, 4xx.tsx,
-   * error.tsx) must NOT, otherwise normal page denies get swallowed.
+   * When true, this boundary wraps a parallel slot. Slot denials are
+   * graceful degradation — they must NOT change the HTTP status code.
    */
   isSlotBoundary?: boolean;
+  /**
+   * Segment key of the segment that declared this boundary. Only meaningful
+   * against a deny digest carrying `owners`. See the decline rule in
+   * `render()` and TIM-1356.
+   */
+  segmentKey?: string;
+  /**
+   * Catch denies only; re-throw everything else. Set on the copy of a
+   * segment's boundaries placed outside its layout, which gives a deny thrown
+   * from that layout's own chrome a catcher keyed to the segment — without
+   * changing where a 5xx from the same chrome goes. See TIM-1450.
+   */
+  denyOnly?: boolean;
+  /**
+   * The deny chain's terminal: the outermost framework boundary, which claims
+   * any deny that streamed past every segment boundary and renders the
+   * framework default page. Implies `denyOnly`. Only a deny thrown from a
+   * layout's chrome with no status file at or above that layout gets here —
+   * the segment copies (`denyOnly`) claim every other shape. See TIM-1450.
+   */
+  lastResort?: boolean;
   children: ReactNode;
 }
 
@@ -86,6 +130,24 @@ interface TimberErrorBoundaryState {
   error: Error | null;
 }
 
+// Module-level guard: the first boundary to catch a given redirect digest
+// schedules the navigation and marks it handled here. Subsequent renders
+// (React retries the error-boundary render path multiple times in dev, and
+// outer boundaries that also see the error) become no-ops, preventing
+// duplicate router.navigate() calls.
+const _handledRedirects = new WeakSet<object>();
+
+// The same guard for the terminal's exit: React may render the fallback
+// path more than once for one error, and the document load must start once.
+const _handledExits = new WeakSet<object>();
+
+// Companion guard keyed by location: client-render redirect() (the
+// next/navigation shim) throws a FRESH error instance on every render
+// attempt, and React replays the errored render — so the WeakSet alone
+// would schedule the navigation twice. While a navigation to a location
+// is pending, further redirect errors for the same location are no-ops.
+let _pendingRedirectLocation: string | null = null;
+
 // ─── Component ───────────────────────────────────────────────────────────────
 
 export class TimberErrorBoundary extends Component<
@@ -102,13 +164,26 @@ export class TimberErrorBoundary extends Component<
     // The aborted connection causes React's streaming hydration to error,
     // but the page is about to be replaced — showing an error boundary
     // would be a jarring flash for the user.
-    if (_isUnloading) {
+    if (isPageUnloading()) {
       return { hasError: false, error: null };
     }
 
     return { hasError: true, error };
   }
 
+  componentDidCatch(error: Error): void {
+    // A stale bundle most often surfaces here rather than as a rejected
+    // navigation: a client reference missing from this build's manifest, or
+    // a lazily-imported chunk the CDN no longer has, thrown during render.
+    //
+    // Recording it is all that happens — this boundary still renders its
+    // fallback, and the recovery is the user's next navigation, which the
+    // router turns into a full document load. Reloading from here would be a
+    // page load the user did not ask for, on a page that may be mid-rollout
+    // and would come back just as stale (TIM-1275).
+    markStaleFromError(error);
+  }
+
   componentDidUpdate(prevProps: TimberErrorBoundaryProps): void {
     // Reset error state when children change (e.g. client-side navigation).
     // Without this, navigating from one error page to another keeps the
@@ -123,20 +198,141 @@ export class TimberErrorBoundary extends Component<
     this.setState({ hasError: false, error: null });
   };
 
+  static override contextType = DenyAncestryContext;
+  declare context: readonly string[];
+
+  private get childAncestry(): readonly string[] {
+    const parent = this.context ?? [];
+    const key = this.props.segmentKey;
+    // A segment has two keyed boundary sets (outside and inside its layout);
+    // the inner one sees its own key already present and adds nothing.
+    return key && !parent.includes(key) ? [...parent, key] : parent;
+  }
+
   render(): ReactNode {
     if (!this.state.hasError || !this.state.error) {
-      return this.props.children;
+      return createElement(
+        DenyAncestryContext.Provider,
+        { value: this.childAncestry },
+        this.props.children
+      );
     }
 
     const error = this.state.error;
     const parsed = parseDigest(error);
 
-    // RedirectSignal errors must propagate through all error boundaries
-    // so the SSR shell fails and the pipeline catch block can produce a
-    // proper HTTP redirect response. See design/04-authorization.md.
+    // RedirectSignal handling splits by environment:
+    //
+    // - SSR (no window): re-throw so the Fizz shell fails and the server
+    //   pipeline catch block can produce a proper HTTP 3xx response. See
+    //   design/04-authorization.md.
+    //
+    // - Client (window exists): a RedirectSignal that leaked into the RSC
+    //   Flight payload during client navigation would otherwise bubble past
+    //   every error boundary to `window.onerror`, which in dev triggers the
+    //   Vite error overlay (false positive — navigation itself works).
+    //   Instead, ask the router to perform an SPA navigation to the target
+    //   and render nothing while it takes over. The router's own catch path
+    //   handles cross-origin / hard navigations. See TIM-838.
     if (parsed?.type === 'redirect') {
+      if (typeof window === 'undefined') {
+        throw error;
+      }
+      // Dedupe: React may render the error-boundary fallback path more
+      // than once for a single caught error (dev-mode double render, and
+      // additional boundaries above us in the tree). Only schedule the
+      // navigation on the first render that sees this error instance.
+      const alreadyHandled =
+        _handledRedirects.has(error) || _pendingRedirectLocation === parsed.location;
+      if (!alreadyHandled) {
+        _handledRedirects.add(error);
+        const router = getRouterOrNull();
+        if (router) {
+          _pendingRedirectLocation = parsed.location;
+          // Schedule the navigation outside the render phase to avoid
+          // setState-during-render warnings from router state updates.
+          queueMicrotask(() => {
+            router
+              .navigate(parsed.location, { replace: true })
+              .catch(() => {
+                // Fall back to a hard navigation if the soft navigation fails.
+                window.location.href = parsed.location;
+              })
+              .finally(() => {
+                _pendingRedirectLocation = null;
+              });
+          });
+        } else {
+          // No router available (shouldn't happen post-bootstrap) — fall
+          // back to a hard navigation so the user still ends up at the
+          // target.
+          window.location.href = parsed.location;
+        }
+      }
+      // Nothing to show, but still a subtree replaced: a layout that
+      // redirected after I/O never mounted its children, and the commit that
+      // renders this empty spot must not teach the cache otherwise — or the
+      // redirect's own navigation would advertise those layouts as mounted
+      // and the server would skip into an outlet the client does not have.
+      return this.markStatusPage(null);
+    }
+
+    // Owner-addressed denies: the digest carries an ordered `owners` list
+    // of segment keys with matching deny pages. This boundary claims the
+    // deny only when it is the first *reachable* owner — i.e. its
+    // segmentKey appears in `owners` AND in its ancestry (the chain from
+    // root to here). Unreachable owners (below the throw site) are skipped,
+    // and the first ancestor that IS reachable claims. This eliminates the
+    // owner-below-throw-site escape (TIM-1450).
+    //
+    // Unkeyed boundaries (slots, or boundaries without deny chains) never
+    // claim an addressed deny. See TIM-1356.
+    if (parsed?.type === 'deny' && Array.isArray(parsed.owners) && parsed.owners.length > 0) {
+      // Slot boundaries always claim addressed denies — graceful degradation
+      // within the slot is correct regardless of which segment the owner
+      // chain resolved to. Without this, the deny escapes the slot and
+      // becomes a page-level 4xx. See TIM-1450.
+      if (!this.props.lastResort && !this.props.isSlotBoundary) {
+        const reachable = parsed.owners.find((k: string) => this.childAncestry.includes(k));
+        if (!this.props.segmentKey || reachable !== this.props.segmentKey) {
+          throw error;
+        }
+      }
+    }
+    // Deny-only boundaries (the outer segment copies) re-throw everything
+    // else so a crash in a layout's chrome still reaches the documented 5xx
+    // flow instead of a status page for an unrelated error.
+    if (this.props.denyOnly && !this.props.lastResort && parsed?.type !== 'deny') {
       throw error;
     }
+    // The terminal is where that flow ends on the client. A non-deny row
+    // nothing claimed — a RenderError or a plain crash on a route with no
+    // matching `error.tsx` — has no page to render in-SPA; React would
+    // unmount the root. So the terminal does what the router does for an
+    // error envelope (design/10 §"Error Page Rendering for Client
+    // Navigation"): leave the SPA, and let the document request render the
+    // real error page with the real status. On the server it re-throws so
+    // the Fizz shell fails and the pipeline serves that page directly. The
+    // envelope still covers errors that land inside Flight's opening window;
+    // this covers the ones that land after it, which used to be held for
+    // (TIM-1495, TIM-1497).
+    if (this.props.lastResort && parsed?.type !== 'deny') {
+      if (typeof window === 'undefined') {
+        throw error;
+      }
+      if (!_handledExits.has(error)) {
+        _handledExits.add(error);
+        const router = getRouterOrNull();
+        const current = window.location.pathname + window.location.search;
+        // The row arrived for the navigation in flight, whose URL is not on
+        // the address bar yet; fall back to the current document.
+        const target = router?.getPendingUrl() ?? current;
+        queueMicrotask(() => {
+          void leaveSpa(target, current);
+        });
+      }
+      return null;
+    }
 
     // If this boundary has a status filter, check whether the error matches.
     // Non-matching errors re-throw so an outer boundary can catch them.
@@ -148,23 +344,66 @@ export class TimberErrorBoundary extends Component<
       }
     }
 
-    // Report DenySignal handling to prevent page-level promotion — but only
-    // for slot boundaries. Segment boundaries (403.tsx, 4xx.tsx, error.tsx)
-    // must NOT set this flag, otherwise normal page/hold-window denies get
-    // swallowed as 200 with boundary HTML instead of the intended 4xx.
-    // Runs here in render() (not getDerivedStateFromError) so the status
-    // filter has already been applied — non-matching boundaries re-threw above.
-    // See LOCAL-298.
-    if (parsed?.type === 'deny' && this.props.isSlotBoundary) {
-      const ssrData = getSsrData();
-      if (ssrData?._navContext) {
-        ssrData._navContext._denyHandledByBoundary = true;
+    // Report DenySignal handling so the pipeline skips the redundant
+    // renderDenyPage() re-render — but ONLY when this boundary can fully
+    // handle the deny in-tree:
+    //
+    // ✅ TSX boundaries (fallbackComponent) — can receive runtime props
+    //    (status, dangerouslyPassData) dynamically in render()
+    // ❌ MDX boundaries (fallbackElement) — pre-rendered at tree-build time,
+    //    cannot receive runtime deny props. Must fall through to re-render.
+    //
+    // For qualifying segment boundaries: also set the HTTP status code from
+    // the DenySignal so the Response has the correct 4xx status. This runs
+    // synchronously during Fizz rendering, BEFORE onShellReady.
+    //
+    // For slot boundaries: set _denyHandledByBoundary but do NOT change
+    // statusCode — slot denials are graceful degradation.
+    //
+    // See TIM-664, LOCAL-298.
+    if (parsed?.type === 'deny') {
+      const canHandleInTree = this.props.fallbackElement == null;
+
+      if (canHandleInTree || this.props.isSlotBoundary) {
+        const ssrData = getSsrData();
+        if (ssrData?._navContext) {
+          ssrData._navContext._denyHandledByBoundary = true;
+          if (!this.props.isSlotBoundary) {
+            ssrData._navContext.statusCode = parsed.status;
+          }
+        }
       }
     }
 
-    // Render the fallback component with the right props shape.
+    return this.markStatusPage(this.renderFallback(parsed, error));
+  }
+
+  /**
+   * The status page this boundary shows for a row it claimed. Its shape is
+   * the file's documented contract: TSX status files get `{ status,
+   * dangerouslyPassData }`, `error.tsx` gets `{ error, digest, reset }` (plus
+   * the deny extras for dual-shape implementations — without the error prop,
+   * an error.tsx reading error.message crashes on deny fall-through, TIM-1081),
+   * and an MDX status file is the element pre-rendered for it at tree-build
+   * time, since a server component cannot cross the RSC→client boundary as a
+   * function prop.
+   */
+  private renderFallback(parsed: ParsedDigest | null, error: Error): ReactNode {
+    if (this.props.fallbackElement != null) {
+      return this.props.fallbackElement;
+    }
+
     if (parsed?.type === 'deny') {
+      if (this.props.status != null) {
+        return createElement(this.props.fallbackComponent as never, {
+          status: parsed.status,
+          dangerouslyPassData: parsed.data,
+        });
+      }
       return createElement(this.props.fallbackComponent as never, {
+        error: denyError(parsed.status, error),
+        digest: null,
+        reset: this.reset,
         status: parsed.status,
         dangerouslyPassData: parsed.data,
       });
@@ -180,6 +419,19 @@ export class TimberErrorBoundary extends Component<
       reset: this.reset,
     });
   }
+
+  /**
+   * A status page (or, for a redirect row, nothing at all) replaced part of
+   * the main route, and the segment cache must not learn a chain that never
+   * mounted; the marker tells the navigation that commits this tree. A boundary that declined in `render()` re-threw
+   * before getting here, so only the boundary that put a page on screen
+   * speaks. A slot degrading leaves the page and its chain intact, so slot
+   * boundaries stay silent. See `status-page-marker.tsx` (TIM-1495).
+   */
+  private markStatusPage(page: ReactNode): ReactNode {
+    if (this.props.isSlotBoundary) return page;
+    return createElement(StatusPageMarker, null, page);
+  }
 }
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
@@ -196,12 +448,36 @@ function parseDigest(error: Error): ParsedDigest | null {
     if (parsed && typeof parsed === 'object' && typeof parsed.type === 'string') {
       return parsed as ParsedDigest;
     }
-  } catch {
-    // Not JSON — legacy or unknown digest format
+  } catch (e) {
+    console.debug('[timber] error digest is not valid JSON:', e instanceof Error ? e.message : e);
   }
   return null;
 }
 
+/**
+ * The Error an `error.tsx` serving a deny should receive.
+ *
+ * The error that actually arrives here is React's, not the framework's: a
+ * server-thrown error crossing Flight has its message and name replaced with
+ * a generic redacted string in production, by design. An `error.tsx` written
+ * per the docs branches on `error.message` — so handing it the redacted error
+ * gives it nothing to branch on, while the in-tree path hands the same file a
+ * `DenySignal` named error reading `Access denied with status <N>` (see
+ * `renderDenyEntry`). This reconstructs that shape from the digest, which is
+ * where the status already is.
+ *
+ * Derived from the status alone — no stack, no server data — so it is safe on
+ * the client for the same reason the digest is. See design/13-security.md
+ * §"Errors don't leak", TIM-1081.
+ */
+function denyError(status: number, original: Error): Error {
+  // A dev build may have preserved something more useful than the redaction.
+  if (original.name === 'DenySignal') return original;
+  const error = new Error(`Access denied with status ${status}`);
+  error.name = 'DenySignal';
+  return error;
+}
+
 /**
  * Extract the HTTP status code from a parsed digest or error message.
  * Falls back to message pattern matching for errors without a digest.

package/src/client/error-reconstituter.tsx

@@ -0,0 +1,79 @@
+'use client';
+
+/**
+ * Reconstitutes a SerializableError into a real Error instance before
+ * passing to the user's error component.
+ *
+ * TSX error pages are 'use client' components that receive { error: Error, digest, reset }.
+ * Error objects are not RSC-serializable (React Flight throws "Only plain objects
+ * can be passed to Client Components"). This wrapper receives the error as a plain
+ * SerializableError object, reconstitutes a real Error instance, and passes it
+ * to the user's error component — ensuring error instanceof Error works correctly.
+ *
+ * See design/spike-TIM-565-unify-error-pages.md §"Edge Case B"
+ * See design/10-error-handling.md §"RSC → SSR for Error Pages via SerializableError"
+ */
+
+import { createElement, type ReactNode, type ComponentType } from 'react';
+
+/**
+ * Plain-object representation of an Error that can cross the RSC → client boundary.
+ * Stack is only included in dev mode (gated by isDevMode() on the server).
+ */
+export interface SerializableError {
+  message: string;
+  name: string;
+  stack?: string;
+}
+
+/**
+ * Props for the ErrorReconstituter wrapper component.
+ * All props are RSC-serializable:
+ * - error: plain object (SerializableError)
+ * - digest: plain JSON or null
+ * - reset: undefined (only meaningful on client after boundary catch)
+ * - component: client module reference (RSC Flight serializes as opaque ref)
+ * - status / dangerouslyPassData: set only when error.tsx serves a deny()
+ *   as the last entry in the 4xx fallback chain — forwarded so dual-shape
+ *   error.tsx implementations can branch on the deny status (TIM-1081)
+ */
+interface ErrorReconstituterProps {
+  error: SerializableError;
+  digest: { code: string; data: unknown } | null;
+  reset: undefined;
+  component: ComponentType<{
+    error: Error;
+    digest: { code: string; data: unknown } | null;
+    reset: (() => void) | undefined;
+    status?: number;
+    dangerouslyPassData?: unknown;
+  }>;
+  status?: number;
+  dangerouslyPassData?: unknown;
+}
+
+/**
+ * Reconstitute a SerializableError into a real Error instance and render
+ * the user's error component with the proper props.
+ */
+export function ErrorReconstituter({
+  error: serialized,
+  digest,
+  reset,
+  component,
+  status,
+  dangerouslyPassData,
+}: ErrorReconstituterProps): ReactNode {
+  // Reconstitute a real Error so instanceof checks work in user code
+  const error = Object.assign(new Error(serialized.message), {
+    name: serialized.name,
+    ...(serialized.stack != null ? { stack: serialized.stack } : {}),
+  });
+
+  return createElement(component, {
+    error,
+    digest,
+    reset,
+    ...(status != null ? { status, dangerouslyPassData } : {}),
+  });
+}

package/src/client/form.tsx

@@ -12,8 +12,13 @@
  */
 
 import { useActionState as reactUseActionState, useTransition } from 'react';
-import type { ActionResult, ValidationErrors } from '#/server/action-client';
-import type { FormFlashData } from '#/server/form-flash';
+import type {
+  ActionFn,
+  ActionResult,
+  InputHint,
+  ValidationErrors,
+} from '../server/action-client.ts';
+import type { FormFlashData } from '../server/form-flash.ts';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -27,13 +32,15 @@ export type UseActionStateFn<TData> = (
 ) => Promise<ActionResult<TData>>;
 
 /**
- * Return type of useActionState — matches React 19's useActionState return.
- * [result, formAction, isPending]
+ * Return type of useActionState.
+ * [result, formAction, isPending, errors]
+ * The 4th element is auto-derived from result via useFormErrors logic.
  */
 export type UseActionStateReturn<TData> = [
   result: ActionResult<TData> | null,
   formAction: (formData: FormData) => void,
   isPending: boolean,
+  errors: FormErrorsResult,
 ];
 
 // ─── useActionState ──────────────────────────────────────────────────────
@@ -73,7 +80,13 @@ export function useActionState<TData>(
 ): UseActionStateReturn<TData> {
   // FormFlashData is structurally compatible with ActionResult at runtime —
   // the cast satisfies React's generic inference which would otherwise widen TData.
-  return reactUseActionState(action, initialState as ActionResult<TData> | null, permalink);
+  const [result, formAction, isPending] = reactUseActionState(
+    action,
+    initialState as ActionResult<TData> | null,
+    permalink
+  );
+  const errors = deriveFormErrors(result);
+  return [result, formAction, isPending, errors];
 }
 
 // ─── useFormAction ───────────────────────────────────────────────────────
@@ -90,15 +103,22 @@ export function useActionState<TData>(
  * </button>
  * ```
  */
-export function useFormAction<TData>(
-  action: (input: unknown) => Promise<ActionResult<TData>>
-): [(input?: unknown) => Promise<ActionResult<TData>>, boolean] {
+export function useFormAction<TData = unknown, TInput = unknown>(
+  action: ActionFn<TData, TInput> | ((input: TInput) => Promise<ActionResult<TData>>)
+): [
+  (
+    ...args: undefined extends TInput ? [input?: InputHint<TInput>] : [input: InputHint<TInput>]
+  ) => Promise<ActionResult<TData>>,
+  boolean,
+] {
   const [isPending, startTransition] = useTransition();
 
-  const execute = (input?: unknown): Promise<ActionResult<TData>> => {
+  const execute = (input?: InputHint<TInput>): Promise<ActionResult<TData>> => {
     return new Promise((resolve) => {
       startTransition(async () => {
-        const result = await action(input);
+        const result = await (action as (input: InputHint<TInput>) => Promise<ActionResult<TData>>)(
+          input as InputHint<TInput>
+        );
         resolve(result);
       });
     });
@@ -107,9 +127,9 @@ export function useFormAction<TData>(
   return [execute, isPending];
 }
 
-// ─── useFormErrors ──────────────────────────────────────────────────────
+// ─── Form error extraction ────────────────────────────────────────────────
 
-/** Return type of useFormErrors(). */
+/** Return type of the errors element in useActionState. */
 export interface FormErrorsResult {
   /** Per-field validation errors keyed by field name. */
   fieldErrors: Record<string, string[]>;
@@ -124,27 +144,11 @@ export interface FormErrorsResult {
 }
 
 /**
- * Extract per-field and form-level errors from an ActionResult.
- *
- * Pure function (no internal hooks) — follows React naming convention
- * since it's used in render. Accepts the result from `useActionState`
- * or flash data from `getFormFlash()`.
- *
- * @example
- * ```tsx
- * const [result, action, isPending] = useActionState(createTodo, null)
- * const errors = useFormErrors(result)
- *
- * return (
- *   <form action={action}>
- *     <input name="title" />
- *     {errors.getFieldError('title') && <p>{errors.getFieldError('title')}</p>}
- *     {errors.formErrors.map(e => <p key={e}>{e}</p>)}
- *   </form>
- * )
- * ```
+ * Derive FormErrorsResult from an action result.
+ * Used internally by useActionState 4th tuple element.
+ * @internal — exported for test access only.
  */
-export function useFormErrors<TData>(
+export function deriveFormErrors<TData>(
   result:
     | ActionResult<TData>
     | {