@timber-js/app 0.2.0-alpha.212 → 0.2.0-alpha.214

package/src/client/browser-entry/hydrate.ts

@@ -76,6 +76,13 @@ interface HydrateOptions {
   reactRoot: ReactRootHost;
   /** Makes the page current and builds its tree — see `RouterInitResult.hydrate`. */
   hydrate: RouterInitResult['hydrate'];
+  /**
+   * The decoded form state of the no-JS action this page answers, or `null`
+   * (./form-state.ts). `hydrateRoot` needs the value Fizz rendered with, or
+   * the `useActionState` hook that submitted hydrates back to its initial
+   * state. See design/08-forms-and-actions.md §"No-JS Result Round-Trip".
+   */
+  formState: ReactFormState | null;
 }
 
 /**
@@ -90,22 +97,6 @@ function takeEmbeddedSegmentInfo(): SegmentInfo[] | null {
   return Array.isArray(embedded) ? embedded : null;
 }
 
-/**
- * Take the form state the server embedded (`self.__timber_form_state`) when
- * this page answers a no-JS action, and remove it. `hydrateRoot` needs the
- * value Fizz rendered with, or the `useActionState` hook that submitted
- * hydrates back to its initial state. See design/08-forms-and-actions.md
- * §"No-JS Result Round-Trip".
- */
-function takeEmbeddedFormState(): ReactFormState | null {
-  const embedded: unknown = Reflect.get(self, '__timber_form_state');
-  Reflect.deleteProperty(self, '__timber_form_state');
-  // `ReactFormState` is an opaque type: React builds it (`decodeFormState`
-  // on the server) and only React reads it, so there is no shape to check
-  // beyond the tuple. It is our own server's JSON of that value.
-  return Array.isArray(embedded) ? (embedded as unknown as ReactFormState) : null;
-}
-
 /**
  * Make the server-rendered page current, and hydrate the React tree with it
  * when an RSC payload is available.
@@ -122,7 +113,7 @@ function takeEmbeddedFormState(): ReactFormState | null {
  * first navigation or revalidation, creates it with the tree it renders
  * (`createReactRoot`, TIM-600 / TIM-580).
  */
-export function hydrateApp({ rscResult, reactRoot, hydrate }: HydrateOptions): void {
+export function hydrateApp({ rscResult, reactRoot, hydrate, formState }: HydrateOptions): void {
   // The chain is the router's own `renderTree`, not a copy: an element type
   // that is present here and absent on the first navigation (or the
   // reverse) changes the type at that position, and React remounts
@@ -143,7 +134,7 @@ export function hydrateApp({ rscResult, reactRoot, hydrate }: HydrateOptions): v
   // construction when the tree it builds renders.
   hydrate(page, (element) =>
     reactRoot.hydrate(element, {
-      formState: takeEmbeddedFormState(),
+      formState,
       // Suppress recoverable hydration errors from deny/error signals
       // inside Suspense boundaries. The server already handled these
       // (wrapStreamWithErrorHandling closes the stream cleanly after

package/src/client/browser-entry/index.ts

@@ -15,6 +15,8 @@
  * Bootstrap call order contract:
  *
  *   1. setupServerActions()      — register callServer (independent)
+ *      takeEmbeddedFormState()   — only on a page answering a no-JS action:
+ *                                   decode its form state, and run 2–7 after
  *   2. createRscPayloadStream()  — decode inlined RSC payload
  *   3. createReactRoot() +       — the root host the router renders through,
  *      createTimberRouter()        then the router + Navigation API
@@ -41,9 +43,11 @@ import { initStaleClient } from '../stale-client.ts';
 
 import { setupServerActions } from './action-dispatch.ts';
 import { createRscPayloadStream } from './rsc-stream.ts';
+import { takeEmbeddedFormState } from './form-state.ts';
 import { createTimberRouter } from './router-init.ts';
 import { createReactRoot } from '../react-root.ts';
 import type { TopLoaderConfig } from '../top-loader.tsx';
+import type { ReactFormState } from 'react-dom/client';
 import { hydrateApp } from './hydrate.ts';
 import { setupPostHydration } from './post-hydration.ts';
 import { setupHmr } from './hmr.ts';
@@ -54,7 +58,7 @@ setupServerActions();
 
 // ─── 2–6. Bootstrap ─────────────────────────────────────────────
 
-function bootstrap(runtimeConfig: typeof config): void {
+function bootstrap(runtimeConfig: typeof config, formState: ReactFormState | null): void {
   // Initialize deployment ID for version skew detection (TIM-446).
   // In dev mode this is null — skew checks are skipped.
   const deploymentId = (runtimeConfig as Record<string, unknown>).deploymentId as string | null;
@@ -95,7 +99,7 @@ function bootstrap(runtimeConfig: typeof config): void {
   });
 
   // Step 4: Make the page current and hydrate (no root without a payload)
-  hydrateApp({ rscResult, reactRoot, hydrate });
+  hydrateApp({ rscResult, reactRoot, hydrate, formState });
 
   // Step 5: Post-hydration wiring
   setupPostHydration({ router, navApiController });
@@ -104,8 +108,6 @@ function bootstrap(runtimeConfig: typeof config): void {
   setupHmr(router);
 }
 
-bootstrap(config);
-
 // ─── 7. Ready Signal ────────────────────────────────────────────
 
 // Signal that the client runtime has been initialized.
@@ -115,6 +117,22 @@ bootstrap(config);
 // via hydrateRoot(document, ...), mutating <html> attributes causes
 // hydration mismatch warnings. Dynamically-added <meta> tags don't
 // conflict because React doesn't reconcile them.
-const readyMeta = document.createElement('meta');
-readyMeta.name = 'timber-ready';
-document.head.appendChild(readyMeta);
+function signalReady(): void {
+  const readyMeta = document.createElement('meta');
+  readyMeta.name = 'timber-ready';
+  document.head.appendChild(readyMeta);
+}
+
+// A page answering a no-JS action must hydrate with the form state Fizz
+// rendered, which is decoded first (design/08 §"No-JS Result Round-Trip").
+// Every other page bootstraps synchronously, as it always has.
+const embeddedFormState = takeEmbeddedFormState();
+if (embeddedFormState) {
+  void embeddedFormState.then((formState) => {
+    bootstrap(config, formState);
+    signalReady();
+  });
+} else {
+  bootstrap(config, null);
+  signalReady();
+}

package/src/client/browser-entry/router-init.ts

@@ -297,7 +297,7 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
     //
     // `_url` names the pending URL the router already published to its own
     // pending store before calling here; the transition has no use for it.
-    navigateTransition: (_url: string, owner: RenderOwner, types, perform, onCommit) => {
+    navigateTransition: (_url: string, owner: RenderOwner, types, perform, onCommit, onHandOff) => {
       return navigateTransition(
         owner,
         async () => {
@@ -334,7 +334,8 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
         },
         render,
         types,
-        onCommit
+        onCommit,
+        onHandOff
       );
     },
 

package/src/client/index.ts

@@ -76,6 +76,7 @@ export {
 
 // Forms
 export { parseFormErrors, useFormAction } from './form.tsx';
+export { useFormField } from './use-form-field.ts';
 export type { FormErrorsResult } from './form.tsx';
 
 // Params. Called with no argument this returns the untyped accumulated params;

package/src/client/navigation-transition.ts

@@ -47,7 +47,9 @@
  *
  * Nothing here may reopen an action scope: no `startTransition` callback in
  * this path may return a thenable, and no caller may invoke this from inside
- * a React action scope. That is a rule about `startTransition`, not about
+ * a React action scope — except one that settles that action at `onHandOff`,
+ * which commits the action and the tree together on purpose (a server action
+ * redirect, TIM-1573). That is a rule about `startTransition`, not about
  * `perform` — `perform` is async by contract and is awaited OUTSIDE any
  * transition scope, which is exactly why it is safe.
  *
@@ -233,6 +235,13 @@ export function createRenderOwner(kind: 'navigation' | 'revalidation'): RenderOw
  * detected via `owner.outcome` (sync) and `owner.displaced` (async).
  * No module-level state; no globalThis singleton.
  *
+ * `onHandOff` runs synchronously right after `render` has scheduled the
+ * tree, before React can commit it. A caller inside a React action scope may
+ * settle that action here (and only here): the render is already entangled
+ * with the scope, so settling commits the action and this tree together,
+ * where settling earlier commits the action alone and settling on the commit
+ * deadlocks. The server action redirect is that caller (TIM-1573).
+ *
  * Used for: navigate(), refresh(), popstate with fetch.
  */
 export function navigateTransition(
@@ -240,7 +249,8 @@ export function navigateTransition(
   perform: () => Promise<TransitionResult>,
   render: NavigationRender,
   types: readonly string[],
-  onCommit?: (outcome: CommitOutcome) => void
+  onCommit?: (outcome: CommitOutcome) => void,
+  onHandOff?: () => void
 ): Promise<void> {
   const superseded = () => new DOMException('Navigation superseded', 'AbortError');
 
@@ -284,6 +294,7 @@ export function navigateTransition(
         },
         types
       );
+      onHandOff?.();
       // React may commit the tree before this settles — that is the point:
       // the destination reveals as React is able to render it
       // rather than waiting for the whole Flight stream. The await is here so

package/src/client/router-effects.ts

@@ -10,7 +10,7 @@
  */
 
 import { setHardNavigating } from './navigation-root.tsx';
-import type { RenderOwner } from './navigation-transition.ts';
+import type { CommitOutcome, RenderOwner } from './navigation-transition.ts';
 import { RedirectError, ServerErrorResponse, NonRscResponse } from './rsc-fetch.ts';
 import { recordSkew } from './router-skew.ts';
 
@@ -147,12 +147,96 @@ export interface NavigationRecoveryDeps {
   currentOwner: () => RenderOwner | null;
   leaveSpaIfOwned: SpaExits['leaveSpaIfOwned'];
   /**
-   * Replace the current entry with `url` — the router's own `navigate()`,
-   * rendering with `types`: the view transition types of the render the
-   * redirect interrupted, so a redirected Back still animates as Back and a
-   * link's own `transitionTypes` survive the hop (TIM-1471).
+   * Follow a redirect to `url` — the router's own `navigate()`, carrying
+   * the interrupted navigation's {@link RedirectHop}.
    */
-  navigate: (url: string, types: readonly string[]) => Promise<void>;
+  navigate: (url: string, hop: RedirectHop) => Promise<void>;
+}
+
+/**
+ * What a redirect hop inherits from the navigation the redirect interrupted.
+ */
+export interface RedirectHop {
+  /**
+   * The view transition types of the interrupted render, so a redirected Back
+   * still animates as Back and a link's own `transitionTypes` survive the
+   * hop (TIM-1471).
+   */
+  types: readonly string[];
+  /**
+   * The interrupted navigation's history mode. A push stays a push: the
+   * address bar moves only when a destination commits, so the interrupted
+   * navigation wrote no entry, and replacing would overwrite the page being
+   * left — Back would skip it (TIM-1571). A refresh or a traversal replaces:
+   * the browser is already on the entry being redirected.
+   */
+  replace: boolean;
+  /**
+   * The interrupted navigation's scroll mode. `<Link scroll={false}>` to a
+   * URL that redirects — a non-canonical `/x/` among them — still keeps the
+   * scroll position; the hop would otherwise default to scrolling to the top.
+   */
+  scroll: boolean;
+  /**
+   * The interrupted navigation's `onCommit`, as {@link HeldCommit.settle}.
+   * A followed redirect is one logical navigation: the hop's commit is the
+   * one the caller is waiting for. `<Link>` holds `isPending` until it, and
+   * a `'failed'` from the interrupted render would release it on the hop's
+   * decode, ahead of a commit React is still holding (TIM-1571). Recovery
+   * delivers it itself on every path that does not follow the redirect.
+   */
+  onCommit?: (outcome: CommitOutcome) => void;
+  /**
+   * The interrupted navigation's `onHandOff`: a server action redirect
+   * waits for the tree that is finally handed to React, which is the
+   * redirected one (TIM-1573).
+   */
+  onHandOff?: () => void;
+}
+
+/**
+ * A navigation's `onCommit`, split around its failure.
+ *
+ * `navigateTransition` settles `onCommit` `'failed'` as soon as `perform`
+ * throws — before the router has seen the error, so before it knows the
+ * failure is a redirect it will follow. `transition` is what the render
+ * gets: every outcome but `'failed'` reaches the caller at once, and
+ * `'failed'` is left to recovery, which either hands `settle` to the
+ * redirect hop or delivers it. `settle` runs the caller's callback at most
+ * once, so a commit or supersession already delivered wins over a later
+ * `'failed'`.
+ */
+export interface HeldCommit {
+  transition: ((outcome: CommitOutcome) => void) | undefined;
+  settle: ((outcome: CommitOutcome) => void) | undefined;
+}
+
+export function holdCommit(onCommit?: (outcome: CommitOutcome) => void): HeldCommit {
+  if (!onCommit) return { transition: undefined, settle: undefined };
+  let settled = false;
+  const settle = (outcome: CommitOutcome): void => {
+    if (settled) return;
+    settled = true;
+    onCommit(outcome);
+  };
+  return {
+    transition: (outcome) => {
+      if (outcome !== 'failed') settle(outcome);
+    },
+    settle,
+  };
+}
+
+/**
+ * The URL a redirect hop navigates to. A redirect target without a fragment
+ * keeps the one the navigation asked for, as a browser does for a 3xx
+ * (RFC 9110 §10.2.2): the server never sees the fragment, so a soft redirect
+ * — `<Link href="/docs/#install">` answered with `/docs` — cannot carry it.
+ */
+export function redirectHopUrl(redirectUrl: string, requestedUrl: string): string {
+  if (redirectUrl.includes('#')) return redirectUrl;
+  const hashIndex = requestedUrl.indexOf('#');
+  return hashIndex === -1 ? redirectUrl : redirectUrl + requestedUrl.slice(hashIndex);
 }
 
 /**
@@ -187,16 +271,21 @@ export function createNavigationRecovery({
     owner: RenderOwner,
     url: string,
     fromUrl: string,
-    /** The view transition types of the render that failed. */
-    types: readonly string[]
+    /** What a redirect hop inherits from the navigation that failed. */
+    hop: RedirectHop
   ): Promise<boolean> {
     if (error instanceof RedirectError) {
       // Same ownership rule as leaving the SPA: a superseded navigation must
       // not steer the document to the destination it was abandoned for.
-      if (currentOwner() !== owner) return true;
-      await navigate(error.redirectUrl, types);
+      if (currentOwner() !== owner) {
+        hop.onCommit?.('superseded');
+        return true;
+      }
+      await navigate(redirectHopUrl(error.redirectUrl, url), hop);
       return true;
     }
+    // Anything else ends this navigation here: its held `'failed'`.
+    hop.onCommit?.('failed');
     // A server error, a non-RSC response and a version skew all end the same
     // way: hand `url` back to the server as a document load, so it can render
     // the outcome as HTML (design/10-error-handling.md §"Error Page Rendering

package/src/client/router-pipeline.ts

@@ -84,7 +84,9 @@ export interface NavigationPipeline {
     types: readonly string[],
     perform: () => Promise<NavigationPayload>,
     /** See `NavigationOptions.onCommit`. */
-    onCommit?: (outcome: CommitOutcome) => void
+    onCommit?: (outcome: CommitOutcome) => void,
+    /** See `NavigationOptions.onHandOff`. */
+    onHandOff?: () => void
   ) => Promise<void>;
 }
 
@@ -186,7 +188,8 @@ export function createNavigationPipeline({
     owner: RenderOwner,
     types: readonly string[],
     perform: () => Promise<NavigationPayload>,
-    onCommit?: (outcome: CommitOutcome) => void
+    onCommit?: (outcome: CommitOutcome) => void,
+    onHandOff?: () => void
   ): Promise<void> {
     // Record that THIS navigation's payload has reached React, at the moment
     // the tree is built and handed back for `navigateTransition` to give to
@@ -260,7 +263,8 @@ export function createNavigationPipeline({
           commit: commitAndForget(result.commit),
         };
       },
-      onCommit
+      onCommit,
+      onHandOff
     );
   }
 

package/src/client/router-types.ts

@@ -89,6 +89,15 @@ export interface NavigationOptions {
    * which of the three it was.
    */
   onCommit?: (outcome: CommitOutcome) => void;
+  /**
+   * @internal Runs once, synchronously after this navigation's tree is handed
+   * to React (its transition scheduled) and before React can commit it. Not
+   * at all if the navigation is superseded or fails first; the returned
+   * promise settles then. A server action that redirects settles its
+   * `useActionState` here, so React commits the action's result and the
+   * destination together (TIM-1573).
+   */
+  onHandOff?: () => void;
 }
 
 /**
@@ -155,7 +164,9 @@ export interface RouterDeps {
       ) => unknown
     ) => Promise<TransitionResult<unknown>>,
     /** See `NavigationOptions.onCommit`; forwarded to `navigateTransition`. */
-    onCommit?: (outcome: CommitOutcome) => void
+    onCommit?: (outcome: CommitOutcome) => void,
+    /** See `NavigationOptions.onHandOff`; forwarded to `navigateTransition`. */
+    onHandOff?: () => void
   ) => Promise<void>;
 
   /**

package/src/client/router.ts

@@ -18,7 +18,12 @@ import { createNavigationCommitter } from './navigation-commit.ts';
 import { fetchRscPayload, NonRscResponse } from './rsc-fetch.ts';
 import { readPayloadTree, readPublishedParams } from '../shared/payload-root.ts';
 import { isClientStale } from './stale-client.ts';
-import { createScrollEffects, createSpaExits, createNavigationRecovery } from './router-effects.ts';
+import {
+  createScrollEffects,
+  createSpaExits,
+  createNavigationRecovery,
+  holdCommit,
+} from './router-effects.ts';
 import { createNavigationLifecycle } from './router-lifecycle.ts';
 import { createNavigationPipeline, prefetchKeyFor } from './router-pipeline.ts';
 import { recordSkew } from './router-skew.ts';
@@ -102,7 +107,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     currentOwner,
     leaveSpaIfOwned,
     // Hoisted — `navigate` is a function declaration below.
-    navigate: (url, types) => navigate(url, { replace: true, _renderTypes: types }),
+    navigate: (url, { types, replace, scroll, onCommit, onHandOff }) =>
+      navigate(url, { replace, scroll, _renderTypes: types, onCommit, onHandOff }),
   });
 
   async function navigate(url: string, options: NavigationOptions = {}): Promise<void> {
@@ -151,6 +157,9 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       await leaveSpaSuperseding(url, departingUrl);
     }
 
+    // A redirect this navigation follows inherits its onCommit (RedirectHop).
+    const heldCommit = holdCommit(options.onCommit);
+
     await runNavigation(url, async (owner) => {
       try {
         await renderViaTransition(
@@ -164,7 +173,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
               signal: owner.fetchAbort.signal,
               departingUrl,
             }),
-          options.onCommit
+          heldCommit.transition,
+          options.onHandOff
         );
 
         // Scroll-to-top on forward navigation, scroll to the #fragment target
@@ -180,7 +190,17 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         // load of the destination, fragment included (TIM-1234). Reloading
         // instead would rebuild the page they were *leaving* and discard
         // the click (TIM-1275).
-        if (await recoverFromNavigationError(error, owner, url, departingUrl, types)) return;
+        if (
+          await recoverFromNavigationError(error, owner, url, departingUrl, {
+            types,
+            replace,
+            scroll,
+            onCommit: heldCommit.settle,
+            onHandOff: options.onHandOff,
+          })
+        ) {
+          return;
+        }
         throw error;
       }
     });
@@ -209,6 +229,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       onCommit?: (outcome: CommitOutcome) => void;
     } = {}
   ): Promise<void> {
+    const heldCommit = holdCommit(opts.onCommit);
     await runNavigation(
       url,
       async (owner) => {
@@ -234,7 +255,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
               });
               return { ...result, params, navState, commit };
             },
-            opts.onCommit
+            heldCommit.transition
           );
         } catch (error) {
           // Neither path is a navigate(), and neither has a caller that
@@ -248,7 +269,15 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           // browser has already traversed, and `refresh()` is by definition
           // where it already is. So `hardNavigate()` takes its same-document
           // branch and reloads rather than pushing an entry.
-          if (await recoverFromNavigationError(error, owner, url, url, [type])) return;
+          if (
+            await recoverFromNavigationError(error, owner, url, url, {
+              types: [type],
+              replace: true,
+              scroll: true,
+              onCommit: heldCommit.settle,
+            })
+          )
+            return;
           throw error;
         }
 

package/src/client/use-form-field.ts

@@ -0,0 +1,132 @@
+/**
+ * useFormField — state for a form field that needs JavaScript (a combobox, a
+ * chip list, a row list), made to behave like a native uncontrolled input.
+ *
+ * React resets a form after its action settles, so a native field with a
+ * `defaultValue` lands on whatever default the page now renders: the action's
+ * `submittedValues`, or fresh page data after a redirect. State held in
+ * `useState` misses that reset and keeps showing the pre-submit edit. This
+ * hook shows `defaultValue` until the user edits, and drops the edit when the
+ * form resets, so it lands where the native fields do.
+ *
+ * See design/08-forms-and-actions.md §"The Form Model".
+ */
+
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type Dispatch,
+  type RefCallback,
+  type SetStateAction,
+} from 'react';
+
+/**
+ * State for a field that follows its form's reset.
+ *
+ * Returns `[value, setValue, ref]`. Attach `ref` to any element inside the
+ * `<form>`, and render the value into the form data yourself (usually a
+ * hidden input). `value` is `defaultValue` until `setValue` is called, and is
+ * `defaultValue` again after the form resets, unless the form cancels its
+ * `reset` event. An edit dispatches a bubbling `change` event from the `ref`
+ * element after it commits, so a native `change` listener on the form sees it
+ * as it sees a native input's (React's synthetic `onChange` reports only
+ * inputs, selects and textareas). A reset and a new default fire none, as
+ * they fire none for a native input.
+ *
+ * @example
+ * ```tsx
+ * // draft: the form's defaults, read from result?.submittedValues ?? pageData
+ * const [tags, setTags, ref] = useFormField(draft.tags);
+ * <div ref={ref}>
+ *   <input type="hidden" name="tags" value={tags.join(',')} />
+ *   <TagPicker value={tags} onChange={setTags} />
+ * </div>
+ * ```
+ */
+export function useFormField<T>(
+  defaultValue: T
+): [value: T, setValue: Dispatch<SetStateAction<T>>, ref: RefCallback<HTMLElement>] {
+  // `null` means "not edited": the field shows its default. A box, so an edit
+  // back to a value equal to the default still counts as an edit.
+  const [edit, setEdit] = useState<{ value: T } | null>(null);
+  const value = edit ? edit.value : defaultValue;
+
+  // The latest default, for an updater called from an old closure. Written
+  // after commit, never during render.
+  const defaultRef = useRef(defaultValue);
+  useLayoutEffect(() => {
+    defaultRef.current = defaultValue;
+  });
+
+  // Resets the form has fired whose outcome this field has not applied yet.
+  // A reset's outcome is known only once its dispatch is over: our listener
+  // runs on the form before React's delegated `onReset`, which may cancel
+  // it. `takeResets` applies every reset whose dispatch has ended, in order:
+  // if any of them was not cancelled, the field was reset. Both the deferred
+  // clear and `setValue` call it, so writes follow a native input's order:
+  // - after `form.reset()` returns, the reset has happened and a write lands
+  //   on top of it (the write takes the reset, and the clear finds nothing);
+  // - during the reset's dispatch (an `onReset` handler), the reset is still
+  //   pending: the write applies to the current value, and the clear then
+  //   erases it unless the reset is cancelled, as a reset overwrites a
+  //   native input written in its handler.
+  // A list, not one slot: `reset(); reset()` where only the second is
+  // cancelled still resets, as it does the native fields.
+  const pendingResets = useRef<Event[]>([]);
+  const takeResets = useCallback((): boolean => {
+    // eventPhase is NONE once dispatch is over.
+    const over = pendingResets.current.filter((e) => e.eventPhase === Event.NONE);
+    if (over.length === 0) return false;
+    pendingResets.current = pendingResets.current.filter((e) => !over.includes(e));
+    return over.some((e) => !e.defaultPrevented);
+  }, []);
+
+  const setValue = useCallback<Dispatch<SetStateAction<T>>>(
+    (next) => {
+      const wasReset = takeResets();
+      setEdit((latest) => {
+        const current = wasReset ? null : latest;
+        const base = current ? current.value : defaultRef.current;
+        const value = next instanceof Function ? next(base) : next;
+        // Unchanged: keep the box, so nothing re-renders and no `change`
+        // fires, as a native input fires none for a value it already has.
+        return Object.is(value, base) ? current : { value };
+      });
+    },
+    [takeResets]
+  );
+
+  const element = useRef<HTMLElement | null>(null);
+  const ref = useCallback<RefCallback<HTMLElement>>(
+    (el) => {
+      element.current = el;
+      const form = el?.closest('form');
+      if (!form) return;
+      const onReset = (event: Event) => {
+        pendingResets.current.push(event);
+        // Dispatch is over by the time a microtask runs.
+        queueMicrotask(() => {
+          if (takeResets()) setEdit(null);
+        });
+      };
+      form.addEventListener('reset', onReset);
+      return () => {
+        element.current = null;
+        pendingResets.current = [];
+        form.removeEventListener('reset', onReset);
+      };
+    },
+    [takeResets]
+  );
+
+  // Every `setValue` stores a new box, and nothing else does except a reset
+  // (which stores null), so a new non-null box is exactly "the user edited".
+  useEffect(() => {
+    if (edit) element.current?.dispatchEvent(new Event('change', { bubbles: true }));
+  }, [edit]);
+
+  return [value, setValue, ref];
+}

package/src/config-types.ts

@@ -56,7 +56,8 @@ export interface TimberUserConfig {
   forms?: {
     /**
      * Strip sensitive fields (passwords, tokens, CVV, SSN, etc.) from the
-     * `submittedValues` echoed back on validation failure.
+     * `submittedValues` echoed back when an action fails (a validation
+     * failure, or a `serverError` from a form submission).
      *
      * Applied to both the with-JS (`createActionClient`) and no-JS (form POST
      * re-render) paths. Safe-by-default: the built-in deny-list is active