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

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

@@ -51,11 +51,13 @@ The `.schema()` method accepts any Standard Schema-compatible validator — Zod,
 ```tsx title="app/todos/todo-form.tsx"
 'use client';
 
-import { useActionState } from '@timber-js/app/client';
+import { useActionState } from 'react';
+import { parseFormErrors } from '@timber-js/app/client';
 import { createTodo } from './actions';
 
 export default function TodoForm() {
-  const [state, action, pending, errors] = useActionState(createTodo, null);
+  const [state, action, pending] = useActionState(createTodo, null);
+  const errors = parseFormErrors(state);
 
   return (
     <form action={action}>
@@ -76,14 +78,15 @@ export default function TodoForm() {
 }
 ```
 
-Without JS, this submits as a standard form POST. With JS, `useActionState` handles pending state and error display.
+`useActionState` is React's own hook. An action built with `createActionClient` passes to it directly, and `state` is typed from the action's result. Without JS, this submits as a standard form POST. With JS, `useActionState` handles pending state and error display.
 
 ### Form Errors
 
-`useActionState` from `@timber-js/app/client` returns a 4-tuple where the 4th element is auto-derived form errors:
+`parseFormErrors` from `@timber-js/app/client` reads the errors out of the result:
 
 ```tsx
-const [state, action, pending, errors] = useActionState(myAction, null);
+const [state, action, pending] = useActionState(myAction, null);
+const errors = parseFormErrors(state);
 
 errors.fieldErrors;              // Record<string, string[]>
 errors.formErrors;               // string[] (form-level errors)
@@ -92,55 +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.
+
+```ts title="app/events/[id]/actions.ts"
+'use server';
 
-When JavaScript is disabled and a server action returns validation errors, timber re-renders the page instead of redirecting. The errors and submitted values are available via `getFormFlash()`:
+import { z } from 'zod/v4';
+import { coerce, redirect } from '@timber-js/app/server';
+import { action } from '@/lib/action';
 
-```tsx title="app/todos/page.tsx"
-import { getFormFlash } from '@timber-js/app/server';
-import { TodoForm } from './todo-form';
+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}`);
+  });
+```
 
-export default async function TodosPage() {
-  const flash = getFormFlash();
-  return <TodoForm flash={flash} />;
+`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/todos/todo-form.tsx"
+```tsx title="app/events/[id]/event-form.tsx"
 'use client';
 
-import { useActionState } from '@timber-js/app/client';
-import { createTodo } from './actions';
-import type { FormFlashData } from '@timber-js/app/server';
+import { useActionState } from 'react';
+import { parseFormErrors } from '@timber-js/app/client';
+import { saveEvent } from './actions';
+import { toDraft } from './draft';
 
-export function TodoForm({ flash }: { flash?: FormFlashData | null }) {
-  const [state, action, pending, errors] = useActionState(createTodo, null);
+type Event = { id: string; title: string; category: string; ticketed: boolean; sets: { name: string }[] };
 
-  const fieldError = (field: string) =>
-    errors.getFieldError(field) ?? flash?.validationErrors?.[field]?.[0];
-  const defaultValue = (field: string) =>
-    (flash?.submittedValues?.[field] as 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={defaultValue('title')} />
-      {fieldError('title') && <p className="text-red-600">{fieldError('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>
   );
 }
 ```
 
-Flash data is server-side only — stored in AsyncLocalStorage for the duration of the re-render. 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.211",
+  "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,21 +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';
-
-/**
- * Wait for a navigation or refresh to both settle (promise resolved) AND
- * commit (pushState / the navigation's commit thunk ran). The queue must
- * not release the next action until the URL is correct in the address bar
- * — same rule `<Link>` uses for `isPending` (design/19 §Per-Link Pending
- * State). `onCommit` fires exactly once: on commit, supersession, or
- * failure, so nothing awaiting this can hang (codex on #1125).
- */
-function settledAndCommitted(start: (onCommit: () => void) => Promise<void>): Promise<void> {
-  let commitResolve!: () => void;
-  const committed = new Promise<void>((r) => (commitResolve = r));
-  return Promise.all([start(commitResolve).catch(() => {}), committed]).then(() => {});
-}
+import { createActionQueue, DEFAULT_HOLD_TIMEOUT_MS } from './action-queue.ts';
 
 export function setupServerActions(): void {
   const queue = createActionQueue({
@@ -60,8 +46,30 @@ export function setupServerActions(): void {
     },
   });
 
+  // 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
+  // redirecting action itself returned. It must settle: React entangles every
+  // transition started while an action is pending, so one left pending would
+  // hold the redirect's own commit forever. `pageGen` names
+  // the page a call was made on, so one queued behind the redirecting
+  // action is dropped too. The check is here rather than in the DOM
+  // (`inert`) because it covers every way a call is made: a click inside a
+  // modal dialog or a shadow root, `requestSubmit()` from a keyboard
+  // shortcut, an effect.
+  let departing = false;
+  let pageGen = 0;
+
   setServerCallback((id: string, args: unknown[]) => {
+    if (departing) return Promise.resolve(undefined);
+    const calledOn = pageGen;
     return queue.run(async ({ hold }) => {
+      if (calledOn !== pageGen) return undefined;
+
       // encodeReply inside the queue — preserves call order when two
       // calls' args serialize in different numbers of microtasks.
       const body = await encodeReply(args);
@@ -75,6 +83,9 @@ export function setupServerActions(): void {
       let hasRevalidation = false;
       let hasRedirect = false;
       let invalidated = false;
+      // Set once the server answered the action itself — past the version
+      // skew and CSRF rejections, which run nothing.
+      let answered = false;
 
       const actionHeaders: Record<string, string> = {
         'Accept': RSC_CONTENT_TYPE,
@@ -104,10 +115,26 @@ export function setupServerActions(): void {
         hasRevalidation = res.headers.get('X-Timber-Revalidation') === '1';
         hasRedirect = res.headers.get('X-Timber-Redirect') != null;
         invalidated = res.headers.get('X-Timber-Invalidated') === '1';
+        answered = true;
         return res;
       });
 
-      const decoded = await createFromFetch(response);
+      let decoded: unknown;
+      try {
+        decoded = await createFromFetch(response);
+      } catch (error) {
+        // A raw server function that throws arrives as a rejected root
+        // (TIM-1570). It may have mutated before it threw, so no payload
+        // cached before it may be reused, nor the mounted shared layouts on
+        // the next navigation. No refresh: the rejection renders the nearest
+        // error boundary, and a refresh would hand that boundary new
+        // children, which resets it and hides the error (error-boundary.tsx).
+        if (answered && router) {
+          router.suppressSegmentReuse();
+          router.evictStaleCaches();
+        }
+        throw error;
+      }
 
       // The mutation happened server-side, and the next thing on screen is
       // not a full render of the current page: revalidatePath named only
@@ -136,14 +163,32 @@ 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 navigate is fire-and-forget: unlike revalidation (where the
-      // next action must capture the refreshed epoch), a redirect leaves
-      // the page entirely — no subsequent action runs on this URL.
+      // 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`).
       if (hasRedirect) {
+        departing = true;
+        pageGen += 1;
         const wrapper = decoded as { _redirect: string; _status: number };
         const isExternal =
           wrapper._redirect.startsWith('https://') || wrapper._redirect.startsWith('http://');
@@ -156,7 +201,42 @@ export function setupServerActions(): void {
         }
         try {
           const r = getRouter();
-          void r.navigate(wrapper._redirect);
+          // The redirect's own navigation takes the next sequence number.
+          // A tree handed to React before it — a refresh of this very page
+          // 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;
+          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
+          // then), or when the router is idle with nothing committed (every
+          // navigation was abandoned; the user stays and may act again).
+          // Not on the redirect navigation's own outcome: a navigation the
+          // user starts meanwhile supersedes it at once, but the departing
+          // page stays until that successor commits (codex on #1211).
+          const stops: (() => void)[] = [];
+          const arrive = (): void => {
+            departing = false;
+            for (const stop of stops) stop();
+          };
+          stops.push(
+            r.onTreeCommit((seq) => {
+              if (seq >= redirectSeq) arrive();
+            }),
+            r.onIdle(arrive)
+          );
+          // 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

@@ -22,6 +22,7 @@
  * See design/19-client-navigation.md §"NavigationContext"
  */
 
+import type { ReactFormState } from 'react-dom/client';
 import { isPageUnloading } from '../unload-guard.ts';
 import type { ReactRootHost } from '../react-root.ts';
 import { readPublishedParams } from '../../shared/payload-root.ts';
@@ -75,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;
 }
 
 /**
@@ -105,7 +113,7 @@ function takeEmbeddedSegmentInfo(): SegmentInfo[] | 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
@@ -126,6 +134,7 @@ export function hydrateApp({ rscResult, reactRoot, hydrate }: HydrateOptions): v
   // construction when the tree it builds renders.
   hydrate(page, (element) =>
     reactRoot.hydrate(element, {
+      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

@@ -159,9 +159,8 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
   // itself calls pushState/replaceState, it sets a flag so the patch
   // skips the sync — the router already updates NavigationContext.
   //
-  // On Navigation API browsers, the navigate event catches most URL
-  // changes. The patch is defense-in-depth and the primary mechanism
-  // for History API-only browsers (older Safari/Firefox).
+  // This is the mechanism with or without the Navigation API: its navigate
+  // listener leaves same-document pushState/replaceState alone.
   const ROUTER_HISTORY_FLAG = Symbol.for('__timber_router_history_update');
   const gFlags = globalThis as Record<symbol, boolean>;
 
@@ -258,7 +257,6 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
       window.history.replaceState(data, unused, url);
       gFlags[ROUTER_HISTORY_FLAG] = false;
     },
-    navigationApiActive: useNavApi,
     scrollTo: (x, y) => {
       // Scroll the document viewport.
       window.scrollTo(x, y);
@@ -299,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 () => {
@@ -336,7 +334,8 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
         },
         render,
         types,
-        onCommit
+        onCommit,
+        onHandOff
       );
     },
 
@@ -361,15 +360,7 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
   let navApiController: NavigationApiController | null = null;
   if (useNavApi) {
     navApiController = setupNavigationApi({
-      onExternalNavigate: async (url, { replace, signal, scroll, departingUrl }) => {
-        await router.navigate(url, {
-          replace,
-          scroll,
-          _signal: signal,
-          _skipHistory: true,
-          _departingUrl: departingUrl,
-        });
-      },
+      onExternalNavigate: (url, { replace }) => router.navigate(url, { replace }),
       onTraverse: async (url, scrollY, signal, direction) => {
         // Back/forward — delegate to the router's popstate handler.
         await router.handlePopState(url, scrollY, signal, direction);
@@ -380,12 +371,8 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
       },
     });
 
-    // Wire the router-navigating flag into RouterDeps.
-    // This must be done after setupNavigationApi returns the controller.
-    deps.setRouterNavigating = (v) => navApiController!.setRouterNavigating(v);
+    // Wired after setupNavigationApi returns the controller.
     deps.saveNavigationEntryScroll = (y) => navApiController!.saveScrollPosition(y);
-    deps.completeRouterNavigation = () => navApiController!.completeRouterNavigation();
-    deps.navigationNavigate = (url, replace) => navApiController!.navigate(url, replace);
   }
 
   /**