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

package/dist/server/ssr-form-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr-form-state.d.ts","sourceRoot":"","sources":["../../src/server/ssr-form-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAmB,KAAK,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAI9F,MAAM,WAAW,YAAY;IAC3B,qCAAqC;IACrC,SAAS,EAAE,cAAc,GAAG,SAAS,CAAC;IACtC,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,wBAAsB,eAAe,CACnC,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,OAAO,EAAE;IACP;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,sBAAsB,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB,GACA,OAAO,CAAC,YAAY,CAAC,CAmBvB"}

package/dist/shared/form-state-flight.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The no-JS action form state on its way to the two renders that need it
+ * (TIM-1572, design/08-forms-and-actions.md §"No-JS Result Round-Trip").
+ *
+ * The RSC environment serializes the form state with Flight
+ * (server/form-state-flight.ts). SSR decodes those bytes for Fizz, and the
+ * browser decodes the same bytes, embedded in the page, for `hydrateRoot`.
+ * Both sides call `decodeFormState` below with their own environment's
+ * Flight client, so the two renders get the same value, and the value a
+ * `useActionState` result has with JS (Flight, through the action response):
+ * a `Date` stays a `Date`, a `Map` a `Map`, and an `undefined` field is
+ * absent on both, because the Flight client drops it.
+ *
+ * The page carries the bytes as base64: Flight may write binary rows (a typed
+ * array in a result), which a text chunk would corrupt, and base64 has no
+ * character that can end a `<script>` element.
+ */
+import type { ReactFormState } from 'react-dom/client';
+/**
+ * A Flight client's `createFromReadableStream`, SSR's or the browser's, typed
+ * to the form state tuple it decodes. React builds `ReactFormState`
+ * (`decodeFormState` on the server) and only React reads it; the Flight
+ * client's type parameter is the only place that type is asserted.
+ */
+export type FormStateFlightDecoder = (stream: ReadableStream<Uint8Array>) => PromiseLike<ReactFormState>;
+/**
+ * Decode the form state's Flight bytes. Rejects if they do not decode within
+ * `timeoutMs`. Every byte is in hand, so only a Flight client bug could
+ * stall it, and the caller falls back to rendering without form state.
+ */
+export declare function decodeFormState(bytes: Uint8Array, decode: FormStateFlightDecoder, timeoutMs: number): Promise<ReactFormState>;
+/** The form state's Flight bytes as the base64 the page embeds. */
+export declare function formStateToBase64(bytes: Uint8Array): string;
+/** The embedded base64 back to the Flight bytes. */
+export declare function formStateFromBase64(text: string): Uint8Array;
+//# sourceMappingURL=form-state-flight.d.ts.map

package/dist/shared/form-state-flight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-state-flight.d.ts","sourceRoot":"","sources":["../../src/shared/form-state-flight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,CACnC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,KAC/B,WAAW,CAAC,cAAc,CAAC,CAAC;AAEjC;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,sBAAsB,EAC9B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,cAAc,CAAC,CAmBzB;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAI3D;AAED,oDAAoD;AACpD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAK5D"}

package/docs/api/31-api-client.mdx

@@ -143,6 +143,28 @@ errors.serverError; // { code, data? } | null
 errors.getFieldError('title'); // string | null
 ```
 
+### `useFormField(defaultValue)`
+
+State for a form field that needs JavaScript, such as a combobox or a chip list, that follows the form's reset like a native input with a `defaultValue`. React resets a form after every action, so use this instead of `useState` for any field inside a form. See [Keeping What the User Typed](/docs/forms-and-actions#keeping-what-the-user-typed).
+
+```tsx
+import { useFormField } from '@timber-js/app/client';
+
+// draft = toDraft(result?.submittedValues ?? post): the form's defaults
+const [tags, setTags, ref] = useFormField(draft.tags);
+
+<div ref={ref}>
+  <input type="hidden" name="tags" value={tags.join(',')} />
+  <TagPicker value={tags} onChange={setTags} />
+</div>
+```
+
+- `value`: `defaultValue` until `setValue` is called, then the edit. An unedited field follows a new `defaultValue`.
+- `setValue`: like a `useState` setter; accepts a value or an updater.
+- `ref`: attach to any element inside the `<form>`. When the form resets, the edit is dropped and `value` is `defaultValue` again, unless the form cancels the `reset` event.
+
+An edit dispatches a bubbling `change` event from the `ref` element, so a native `change` listener on the form sees it. React's `onChange` prop does not: it only reports inputs, selects and textareas. Render the value into the form data yourself, usually with a hidden input.
+
 ### `useFormAction(action)`
 
 Bind a server action to a form with pending state.

package/docs/api/34-api-config.mdx

@@ -153,7 +153,7 @@ limits: {
 - **Type:** `boolean | string[]`
 - **Default:** `true`
 
-Strip sensitive fields (passwords, tokens, CVV, SSN, etc.) from the `submittedValues` echoed back on validation failure. `true` uses the built-in deny-list; an array adds extra field names to the built-in list; `false` disables stripping (never do this in production). See [Forms & Server Actions](/docs/forms-and-actions) for the full pattern list.
+Strip sensitive fields (passwords, tokens, CVV, SSN, etc.) from the `submittedValues` echoed back when an action fails. `true` uses the built-in deny-list; an array adds extra field names to the built-in list; `false` disables stripping (never do this in production). See [Forms & Server Actions](/docs/forms-and-actions) for the full pattern list.
 
 ### `pageExtensions`
 

package/docs/learn/08-forms-and-actions.mdx

@@ -95,45 +95,132 @@ errors.hasErrors;                // boolean
 errors.getFieldError('title');   // string | null (first error for field)
 ```
 
-## After Mutation
+## Keeping What the User Typed
 
-| Pattern                   | When to use                                      |
-| ------------------------- | ------------------------------------------------ |
-| `redirect('/path')`       | User should land somewhere new                   |
-| `revalidatePath('/path')` | Current page needs fresh data                    |
-| `useOptimistic`           | Instant UI update, action confirms in background |
+React resets a form after every action: each field goes back to its `defaultValue`. Build forms on that reset, and they keep the user's input after a failure and show the saved values after a save, with or without JavaScript:
 
-## Forms Without JavaScript
+1. Leave fields **uncontrolled**: a `name` and a `defaultValue`, not `value` + `onChange`.
+2. Take defaults from the result, then from the page: `result?.submittedValues ?? pageData`.
+3. On success, `redirect()` (or `revalidatePath()`), so the page renders the saved data.
 
-The same form works with JavaScript disabled, with no extra code. When a no-JS submission's action returns instead of redirecting, timber renders the page again and React hands the result to the `useActionState` hook that submitted it. `state` holds the result on both paths, so errors and repopulated fields render the same way:
+```ts title="app/events/[id]/actions.ts"
+'use server';
 
-```tsx title="app/todos/todo-form.tsx"
+import { z } from 'zod/v4';
+import { coerce, redirect } from '@timber-js/app/server';
+import { action } from '@/lib/action';
+
+declare const db: { events: { update(data: unknown): Promise<void> } };
+
+export const saveEvent = action
+  .schema(
+    z.object({
+      id: z.string(),
+      title: z.string().min(1, 'Title is required'),
+      category: z.string(),
+      ticketed: z.preprocess(coerce.checkbox, z.boolean()),
+      // sets.0.name, sets.1.name… arrive as an array
+      sets: z.array(z.object({ name: z.string().min(1) })).default([]), // no rows: no key
+    })
+  )
+  .action(async ({ input }) => {
+    await db.events.update(input);
+    redirect(`/events/${input.id}`);
+  });
+```
+
+`submittedValues` is the raw form: strings, lists as arrays, an unchecked box absent. Page data is typed. One small, lenient function reads either into what the fields render:
+
+```ts title="app/events/[id]/draft.ts"
+export function toDraft(values: Record<string, unknown>) {
+  const sets: { name?: unknown }[] = Array.isArray(values.sets) ? values.sets : [];
+  return {
+    title: String(values.title ?? ''),
+    category: String(values.category ?? ''),
+    // Submitted: "on", or absent when unchecked. Saved: a boolean.
+    ticketed: values.ticketed === true || values.ticketed === 'on',
+    sets: sets.map((set) => ({ name: String(set?.name ?? '') })),
+  };
+}
+```
+
+```tsx title="app/events/[id]/event-form.tsx"
 'use client';
 
 import { useActionState } from 'react';
 import { parseFormErrors } from '@timber-js/app/client';
-import { createTodo } from './actions';
+import { saveEvent } from './actions';
+import { toDraft } from './draft';
 
-export function TodoForm() {
-  const [state, action, pending] = useActionState(createTodo, null);
-  const errors = parseFormErrors(state);
+type Event = { id: string; title: string; category: string; ticketed: boolean; sets: { name: string }[] };
+
+export function EventForm({ event }: { event: Event }) {
+  const [result, action, pending] = useActionState(saveEvent, null);
+  const errors = parseFormErrors(result);
+  // After a failure: what the user submitted. Otherwise: the saved event.
+  const d = toDraft(result?.submittedValues ?? event);
 
   return (
     <form action={action}>
-      <input name="title" defaultValue={(state?.submittedValues?.title as string) ?? ''} />
-      {errors.getFieldError('title') && (
-        <p className="text-red-600">{errors.getFieldError('title')}</p>
-      )}
-      <button type="submit" disabled={pending}>
-        {pending ? 'Adding...' : 'Add Todo'}
-      </button>
+      <input type="hidden" name="id" value={event.id} />
+      <input name="title" defaultValue={d.title} />
+      {errors.getFieldError('title')}
+
+      {/* React applies a select's defaultValue only on mount: key it on the default */}
+      <select key={d.category} name="category" defaultValue={d.category}>
+        <option value="meetup">Meetup</option>
+        <option value="social">Social</option>
+      </select>
+
+      <input type="checkbox" name="ticketed" defaultChecked={d.ticketed} />
+
+      {d.sets.map((set, i) => (
+        <input key={i} name={`sets.${i}.name`} defaultValue={set.name} />
+      ))}
+
+      {errors.serverError && <p>Could not save. Please try again.</p>}
+      <button disabled={pending}>Save</button>
     </form>
   );
 }
 ```
 
-The result goes only to the hook that submitted, so two forms on one page never see each other's results. Sensitive fields (password, apiKey, cvv, etc.) are automatically stripped from `submittedValues`.
+When a form submission fails — a validation error, an `ActionError`, or an unexpected error — the result carries `submittedValues`, so the user's input survives any of them.
+
+Three things break the model:
+
+- **Controlled fields.** A field whose value lives in state keeps showing that state after the reset has put the DOM back to its default, and the next submit sends what the DOM holds, not what the user sees. If a form must be controlled, cancel the reset: `<form action={action} onReset={(e) => e.preventDefault()}>`.
+- **An unkeyed `<select>`.** React ignores a changed `defaultValue` on a mounted `<select>`. Key it on its default, as above. Inputs, checkboxes and textareas don't need this.
+- **`useState` for a field that needs JavaScript.** A combobox or a chip list can't be a native input. Hold its state in `useFormField` instead, which follows the reset like a native input:
+
+```tsx
+import { useFormField } from '@timber-js/app/client';
+
+function TagsField({ defaultValue }: { defaultValue: string[] }) {
+  const [tags, setTags, ref] = useFormField(defaultValue);
+  return (
+    <div ref={ref}>
+      <input type="hidden" name="tags" value={tags.join(',')} />
+      <TagPicker value={tags} onChange={setTags} />
+    </div>
+  );
+}
+```
+
+## After Mutation
+
+| Pattern                   | When to use                                      |
+| ------------------------- | ------------------------------------------------ |
+| `redirect('/path')`       | User should land somewhere new                   |
+| `revalidatePath('/path')` | Current page needs fresh data                    |
+| `useOptimistic`           | Instant UI update, action confirms in background |
+
+## Forms Without JavaScript
+
+The same form works with JavaScript disabled, with no extra code. When a no-JS submission's action returns instead of redirecting, timber renders the page again and React hands the result to the `useActionState` hook that submitted it. `result` holds the result on both paths, so errors and the fields' defaults render the same way, and the server writes the user's input back into the HTML.
+
+The result goes only to the hook that submitted, so two forms on one page never see each other's results. It has the same types on both paths: a `Date` your action returns is a `Date` in `state` whether or not JavaScript ran. Sensitive fields (password, apiKey, cvv, etc.) are automatically stripped from `submittedValues`.
 
 A form that doesn't use `useActionState` gets no result back, just as with JavaScript, where React discards a plain `<form action>`'s return value. Such an action should `redirect()` to a page that shows the new state (post-redirect-get). An action that throws renders the nearest `error.tsx`: with JavaScript the action rejects to the nearest error boundary, and without it the page answers from the same `error.tsx` with a 500; return errors from `createActionClient` actions instead.
 
-For advanced topics — coercion helpers, `parseFormData`, sensitive field stripping configuration, and the full end-to-end example — see [Advanced Forms](/docs/advanced-forms).
+For advanced topics — coercion helpers, `parseFormData`, indexed lists, and sensitive field stripping configuration — see [Advanced Forms](/docs/advanced-forms).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.212",
+  "version": "0.2.0-alpha.213",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/client/browser-entry/action-dispatch.ts

@@ -23,7 +23,7 @@ import { getClientDeploymentId, DEPLOYMENT_ID_HEADER, RELOAD_HEADER } from '../r
 import { markClientStale } from '../stale-client.ts';
 import { RSC_CONTENT_TYPE } from '../../shared/rsc-media-type.ts';
 import { CSRF_REJECT_HEADER, CSRF_REJECT_VALUE } from '../../shared/csrf-reject.ts';
-import { createActionQueue } from './action-queue.ts';
+import { createActionQueue, DEFAULT_HOLD_TIMEOUT_MS } from './action-queue.ts';
 
 export function setupServerActions(): void {
   const queue = createActionQueue({
@@ -46,10 +46,10 @@ export function setupServerActions(): void {
     },
   });
 
-  // An action that redirects settles — ending `useActionState`'s pending
-  // state — a full round trip before the destination is on screen, and the
-  // page that submitted stays mounted until then with its button enabled
-  // again. A second submit would run the mutation again (TIM-1568). So the
+  // The page that submitted a redirecting action stays mounted until the
+  // destination commits. Its own useActionState stays pending until the
+  // hand-off (below), but other forms and effects on it can still dispatch,
+  // and a second submit would run the mutation again (TIM-1568). So the
   // departing page may not dispatch: `departing` is set from the redirect
   // response until the router is next idle, and a call made
   // meanwhile is never sent. It resolves at once with `undefined` — what the
@@ -163,10 +163,26 @@ export function setupServerActions(): void {
       }
 
       // Redirects apply unconditionally — the server mutated and told
-      // the client where to go. Return undefined to React NOW so the
-      // action scope settles — awaiting the commit inline would deadlock:
-      // React entangles the commit lane with the action scope, so the
-      // commit waits on the action while the action waits on the commit.
+      // the client where to go. The action settles (returning undefined)
+      // once the destination's tree has been handed to React, not before
+      // and not after:
+      //
+      // - Not after its commit: React entangles the commit with the action
+      //   scope, so the commit would wait on the action while the action
+      //   waited on the commit.
+      // - Not before the hand-off: React would commit the action alone —
+      //   useActionState's result, and React's reset of the submitting form
+      //   onto the defaults the *departing* page renders — and the form
+      //   would show the pre-save values until the destination committed
+      //   (TIM-1573).
+      //
+      // At the hand-off the destination's render is already entangled with
+      // the action, so settling commits both together: the form resets onto
+      // the destination's defaults. The wait always ends: the navigation
+      // hands off, or fails, or a navigation the user starts supersedes it
+      // (its promise settles either way), or DEFAULT_HOLD_TIMEOUT_MS
+      // passes. Every transition waits while an action is pending, so this
+      // must not hang on a stalled fetch.
       //
       // Set before returning, so React never sees the action settle while
       // the departing page can still dispatch (see `departing`).
@@ -190,7 +206,9 @@ export function setupServerActions(): void {
           // still suspended — can commit afterwards, and must not release
           // the latch: it is the departing page again (codex on #1211).
           const redirectSeq = r.epoch().seq + 1;
-          void r.navigate(wrapper._redirect);
+          let handOff!: () => void;
+          const handedOff = new Promise<void>((resolve) => (handOff = resolve));
+          r.navigate(wrapper._redirect, { onHandOff: handOff }).then(handOff, handOff);
           // Released once the departing page can no longer be on screen:
           // when any navigation's tree commits (a streamed destination
           // commits its shell before its stream finishes, and is live from
@@ -213,6 +231,12 @@ export function setupServerActions(): void {
           // A navigation that failed before taking the router never makes
           // it busy, so no idle transition would come.
           if (r.epoch().idle) arrive();
+          let timer: ReturnType<typeof setTimeout> | undefined;
+          await Promise.race([
+            handedOff,
+            new Promise<void>((resolve) => (timer = setTimeout(resolve, DEFAULT_HOLD_TIMEOUT_MS))),
+          ]);
+          clearTimeout(timer);
         } catch (e) {
           console.debug(
             '[timber] action redirect: router not ready, using full navigation',

package/src/client/browser-entry/action-queue.ts

@@ -31,7 +31,7 @@ export interface ActionQueueDeps {
   holdTimeoutMs?: number;
 }
 
-const DEFAULT_HOLD_TIMEOUT_MS = 30_000;
+export const DEFAULT_HOLD_TIMEOUT_MS = 30_000;
 
 const noop = (): void => {};
 

package/src/client/browser-entry/form-state.ts

@@ -0,0 +1,48 @@
+/**
+ * The form state a page answering a no-JS action embeds for hydration
+ * (`self.__timber_form_state`, server/form-state-flight.ts).
+ *
+ * `hydrateRoot` needs the value Fizz rendered with, or the `useActionState`
+ * hook that submitted hydrates back to its initial state. The embed is the
+ * form state's Flight bytes, the same bytes SSR decoded for Fizz, so the
+ * browser decodes them with its own Flight client before it hydrates. Only
+ * this page waits for that; a page without the embed hydrates at once
+ * (TIM-1297: hydration does not wait for the payload root).
+ *
+ * See design/08-forms-and-actions.md §"No-JS Result Round-Trip".
+ */
+
+import type { ReactFormState } from 'react-dom/client';
+import { createFromReadableStream } from '../../rsc-runtime/browser.ts';
+import { decodeFormState, formStateFromBase64 } from '../../shared/form-state-flight.ts';
+
+/**
+ * Every byte is already in the document, so decoding takes microtasks. The
+ * bound only keeps a Flight client bug from holding hydration forever.
+ */
+const DECODE_TIMEOUT_MS = 5_000;
+
+/**
+ * Take the embedded form state, and remove it. `null` when the page has
+ * none, which is every page but one answering a no-JS action. Otherwise a
+ * promise of the decoded state, or of `null` if it could not be decoded: the
+ * page then hydrates as though it had none, which resets that one hook.
+ */
+export function takeEmbeddedFormState(): Promise<ReactFormState | null> | null {
+  const embedded: unknown = Reflect.get(self, '__timber_form_state');
+  Reflect.deleteProperty(self, '__timber_form_state');
+  if (typeof embedded !== 'string') return null;
+  // Inside the chain, so malformed base64 falls back like a failed decode.
+  return Promise.resolve(embedded)
+    .then((text) =>
+      decodeFormState(
+        formStateFromBase64(text),
+        (stream) => createFromReadableStream(stream),
+        DECODE_TIMEOUT_MS
+      )
+    )
+    .catch((error: unknown) => {
+      console.warn('[timber] the form state of a no-JS action did not decode:', error);
+      return null;
+    });
+}

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

@@ -150,9 +150,11 @@ export interface NavigationRecoveryDeps {
    * 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).
+   * link's own `transitionTypes` survive the hop (TIM-1471). `onHandOff`
+   * survives it too: a server action redirect waits for the tree that is
+   * finally handed to React, which is the redirected one (TIM-1573).
    */
-  navigate: (url: string, types: readonly string[]) => Promise<void>;
+  navigate: (url: string, types: readonly string[], onHandOff?: () => void) => Promise<void>;
 }
 
 /**
@@ -188,13 +190,15 @@ export function createNavigationRecovery({
     url: string,
     fromUrl: string,
     /** The view transition types of the render that failed. */
-    types: readonly string[]
+    types: readonly string[],
+    /** The failed navigation's `NavigationOptions.onHandOff`, for the hop. */
+    onHandOff?: () => void
   ): 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);
+      await navigate(error.redirectUrl, types, onHandOff);
       return true;
     }
     // A server error, a non-RSC response and a version skew all end the same