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

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

@@ -102,7 +102,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, onHandOff) =>
+      navigate(url, { replace: true, _renderTypes: types, onHandOff }),
   });
 
   async function navigate(url: string, options: NavigationOptions = {}): Promise<void> {
@@ -164,7 +165,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
               signal: owner.fetchAbort.signal,
               departingUrl,
             }),
-          options.onCommit
+          options.onCommit,
+          options.onHandOff
         );
 
         // Scroll-to-top on forward navigation, scroll to the #fragment target
@@ -180,7 +182,18 @@ 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,
+            options.onHandOff
+          )
+        ) {
+          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

package/src/server/action-client.ts

@@ -118,7 +118,11 @@ export type ActionResult<TData = unknown> =
       data?: never;
       validationErrors?: never;
       serverError: { code: string; data?: Record<string, unknown> };
-      submittedValues?: never;
+      /**
+       * The submitted form, when the input was FormData — for repopulating
+       * form fields, which React resets after the action (TIM-1573).
+       */
+      submittedValues?: Record<string, unknown>;
     };
 
 /** Context passed to the action body. */
@@ -288,7 +292,9 @@ function extractStandardSchemaErrors(issues: ReadonlyArray<StandardSchemaIssue>)
  * `createActionClient` actions only. A raw `'use server'` function that
  * throws is rejected on the client instead (action-handler.ts).
  */
-export function handleActionError(error: unknown): ActionResult<never> {
+export function handleActionError(error: unknown): {
+  serverError: { code: string; data?: Record<string, unknown> };
+} {
   if (error instanceof ActionError) {
     return {
       serverError: {
@@ -339,43 +345,49 @@ export function createActionClient<TCtx = Record<string, never>>(
     fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>
   ): ActionFn<TData, TInput> {
     async function actionHandler(...args: unknown[]): Promise<ActionResult<TData>> {
+      // The input is the last argument in every call shape: `(input)`,
+      // `(formData)`, `(prevState, payload)` from useActionState's
+      // dispatch, `(initialState, formData)` on the no-JS path (Fizz binds
+      // the initial state into the form, and decodeAction binds the
+      // FormData after it), and `(...bound, prevState, payload)` for an
+      // action with bound arguments. Nothing before it is input:
+      // `prevState` comes from the client, so it is never read.
+      const last = args.at(-1);
+      const form = last instanceof FormData ? parseFormData(last) : undefined;
+
+      // Resolve the sensitive-field stripping predicate once per invocation.
+      // Precedence: per-action (config.stripSensitiveFields) > global
+      // (forms.stripSensitiveFields from timber.config.ts) > built-in deny-list.
+      // See TIM-816.
+      const sensitivePredicate = resolveSensitivePredicate(
+        config.stripSensitiveFields,
+        getGlobalSensitiveFieldsConfig()
+      );
+
+      // A "safe-to-echo" copy of the input. Files are stripped (can't
+      // serialize, shouldn't echo back) and sensitive fields (passwords,
+      // tokens, CVV, etc.) are removed before they would land in the RSC
+      // payload → client form `defaultValue` → DOM.
+      const echo = (value: unknown): Record<string, unknown> | undefined => {
+        const withoutFiles = stripFiles(value);
+        if (withoutFiles === undefined) return undefined;
+        return stripSensitiveFields(withoutFiles, sensitivePredicate);
+      };
+
       try {
         // Run middleware
         const ctx = await runActionMiddleware(config.middleware);
 
-        // The input is the last argument in every call shape: `(input)`,
-        // `(formData)`, `(prevState, payload)` from useActionState's
-        // dispatch, `(initialState, formData)` on the no-JS path (Fizz binds
-        // the initial state into the form, and decodeAction binds the
-        // FormData after it), and `(...bound, prevState, payload)` for an
-        // action with bound arguments. Nothing before it is input:
-        // `prevState` comes from the client, so it is never read.
-        const last = args.at(-1);
-        const rawInput: unknown = schema && last instanceof FormData ? parseFormData(last) : last;
-
-        // Resolve the sensitive-field stripping predicate once per invocation.
-        // Precedence: per-action (config.stripSensitiveFields) > global
-        // (forms.stripSensitiveFields from timber.config.ts) > built-in deny-list.
-        // See TIM-816.
-        const sensitivePredicate = resolveSensitivePredicate(
-          config.stripSensitiveFields,
-          getGlobalSensitiveFieldsConfig()
-        );
-
-        // Capture a "safe-to-echo" snapshot of the raw input once. Files are
-        // stripped (can't serialize, shouldn't echo back) and sensitive fields
-        // (passwords, tokens, CVV, etc.) are removed before they would land
-        // in the RSC payload → client form `defaultValue` → DOM.
-        const buildSubmittedValues = (): Record<string, unknown> | undefined => {
-          const withoutFiles = stripFiles(rawInput);
-          if (withoutFiles === undefined) return undefined;
-          return stripSensitiveFields(withoutFiles, sensitivePredicate);
-        };
+        // Without a schema the action receives the FormData itself. Checks
+        // and echoes read the parsed form: a FormData has no own entries.
+        const rawInput: unknown = schema && form ? form : last;
+        const submitted: unknown = form ?? rawInput;
+        const buildSubmittedValues = () => echo(submitted);
 
         // Validate file sizes before schema validation.
-        if (config.fileSizeLimit !== undefined && rawInput && typeof rawInput === 'object') {
+        if (config.fileSizeLimit !== undefined && submitted && typeof submitted === 'object') {
           const fileSizeErrors = validateFileSizes(
-            rawInput as Record<string, unknown>,
+            submitted as Record<string, unknown>,
             config.fileSizeLimit
           );
           if (fileSizeErrors) {
@@ -435,7 +447,12 @@ export function createActionClient<TCtx = Record<string, never>>(
         if (isRedirectSignal(error) || isDenySignal(error)) {
           throw error;
         }
-        return handleActionError(error);
+        // A `serverError` echoes the form like a validation failure does.
+        // React resets the form after the action, and a form whose defaults
+        // fell back to page data would lose what the user typed (TIM-1573).
+        const result = handleActionError(error);
+        const submittedValues = form && echo(form);
+        return submittedValues ? { ...result, submittedValues } : result;
       }
     }
 
@@ -508,6 +525,8 @@ function logValidationFailure(errors: ValidationErrors): void {
 /**
  * Validate that all File objects in the input are within the size limit.
  * Returns validation errors keyed by field name, or null if all files are ok.
+ * Keys are dot paths (`rows.0.file`), the form a field name and a Standard
+ * Schema error use, so `getFieldError` finds a file in a list.
  */
 function validateFileSizes(input: Record<string, unknown>, limit: number): ValidationErrors | null {
   const limitKb = Math.round(limit / 1024);
@@ -526,7 +545,7 @@ function validateFileSizes(input: Record<string, unknown>, limit: number): Valid
       } else if (Array.isArray(value)) {
         for (let i = 0; i < value.length; i++) {
           const item = value[i];
-          const itemPath = `${path}[${i}]`;
+          const itemPath = `${path}.${i}`;
           if (item instanceof File && item.size > limit) {
             (errors[itemPath] ??= []).push(
               `File "${item.name}" (${formatSize(item.size)}) exceeds the ${limitLabel} limit`
@@ -546,29 +565,25 @@ function validateFileSizes(input: Record<string, unknown>, limit: number): Valid
 }
 
 /**
- * Strip File objects from a value, returning a plain object safe for
- * serialization. File objects can't be serialized and shouldn't be echoed back.
+ * Strip File objects from a value, returning a copy safe for serialization.
+ * File objects can't be serialized and shouldn't be echoed back.
+ *
+ * Mirrors `parseFormData`'s output: objects and arrays at any depth, arrays
+ * of arrays included. A File in an array becomes `undefined` rather than
+ * being removed, so `rows.2` still names the third element (TIM-1573).
  */
 function stripFiles(value: unknown): Record<string, unknown> | undefined {
-  if (value === null || value === undefined) return undefined;
-  if (typeof value !== 'object') return undefined;
+  if (value === null || typeof value !== 'object' || value instanceof File) return undefined;
+  return stripFilesFrom(value) as Record<string, unknown>;
+}
 
+function stripFilesFrom(value: unknown): unknown {
+  if (value instanceof File) return undefined;
+  if (Array.isArray(value)) return value.map(stripFilesFrom);
+  if (typeof value !== 'object' || value === null) return value;
   const result: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-    if (v instanceof File) continue;
-    if (Array.isArray(v)) {
-      result[k] = v
-        .filter((item) => !(item instanceof File))
-        .map((item) =>
-          typeof item === 'object' && item !== null && !(item instanceof File)
-            ? (stripFiles(item) ?? {})
-            : item
-        );
-    } else if (typeof v === 'object' && v !== null && !(v instanceof File)) {
-      result[k] = stripFiles(v) ?? {};
-    } else {
-      result[k] = v;
-    }
+  for (const [k, v] of Object.entries(value)) {
+    if (!(v instanceof File)) result[k] = stripFilesFrom(v);
   }
   return result;
 }

package/src/server/flight-scripts.ts

@@ -16,6 +16,7 @@
  */
 
 import { nonceAttr } from './render-utils.ts';
+import { formStateToBase64 } from '../shared/form-state-flight.ts';
 
 // ─── JSON Escaping ────────────────────────────────────────────────────────
 
@@ -65,3 +66,15 @@ export function flightChunkScript(data: string, nonce?: string): string {
   const escaped = htmlEscapeJsonString(JSON.stringify([1, data]));
   return `<script${nonceAttr(nonce)}>(${FLIGHT_VAR}=${FLIGHT_VAR}||[]).push(${escaped})</script>`;
 }
+
+/**
+ * Generate the script that embeds a no-JS action's form state for
+ * hydration: its Flight bytes (server/form-state-flight.ts), as base64. Only
+ * a page answering a no-JS action has one. Base64 carries Flight's binary
+ * rows, which a text chunk would corrupt, and has no character that can end
+ * the script element or the string. See design/08-forms-and-actions.md
+ * §"No-JS Result Round-Trip".
+ */
+export function formStateScript(bytes: Uint8Array, nonce?: string): string {
+  return `<script${nonceAttr(nonce)}>self.__timber_form_state="${formStateToBase64(bytes)}"</script>`;
+}

package/src/server/form-data.ts

@@ -18,9 +18,15 @@
  * Handles:
  * - **Duplicate keys → arrays**: `tags=js&tags=ts` → `{ tags: ["js", "ts"] }`
  * - **Nested dot-paths**: `user.name=Alice` → `{ user: { name: "Alice" } }`
- * - **Empty strings → undefined**: Enables `.optional()` semantics in schemas
+ * - **Indexed lists → arrays**: `rows.0.name=A&rows.1.name=B` →
+ *   `{ rows: [{ name: "A" }, { name: "B" }] }`, when the indexes are exactly
+ *   `0..n-1`. A list with a gap stays an object keyed by index.
+ * - **Empty strings stay `""`**: a blank text input is `""`, so
+ *   `z.string().min(1, 'Required')` reports its own message. Use
+ *   `coerce.text` to make a blank optional field `undefined`
  * - **Empty Files → undefined**: File inputs with no selection become `undefined`
  * - **Strips `$ACTION_*` fields**: React's internal hidden fields are excluded
+ * - **Drops `__proto__` paths and names deeper than 32 segments**
  */
 export function parseFormData(formData: FormData): Record<string, unknown> {
   const flat: Record<string, unknown> = {};
@@ -97,6 +103,11 @@ function expandDotPaths(flat: Record<string, unknown>): Record<string, unknown>
     // `result['__proto__']` resolves to the prototype object itself.
     const parts = key.split('.');
     if (parts.some((p) => DANGEROUS_KEYS.has(p))) continue;
+    // Bound the nesting depth. Every walk over the parsed value recurses
+    // once per level (list conversion here, then file and sensitive-field
+    // stripping and schema validation), and a 10 KB key of 5,000 segments
+    // fits well inside the body limits. No form nests this deep.
+    if (parts.length > MAX_PATH_DEPTH) continue;
 
     if (parts.length === 1) {
       result[parts[0]] = value;
@@ -106,12 +117,13 @@ function expandDotPaths(flat: Record<string, unknown>): Record<string, unknown>
     let current: Record<string, unknown> = result;
     for (let i = 0; i < parts.length - 1; i++) {
       const part = parts[i];
-      if (current[part] === undefined || current[part] === null) {
-        current[part] = {};
-      }
-      // If current[part] is not an object (e.g., a string from a non-dotted key),
-      // the dot-path takes precedence
-      if (typeof current[part] !== 'object' || current[part] instanceof File) {
+      // Step only into an object this walk built. Anything else under the
+      // name — a string, a File, or an array from a duplicate key
+      // (`rows=x&rows=y`) — is replaced: the dot-path takes precedence.
+      // Stepping into an array would let `rows.4294967294` set its length
+      // to 2^32 - 1, and every later walk (file and sensitive-field
+      // stripping) maps over that length (TIM-1573).
+      if (!isPlainObject(current[part])) {
         current[part] = {};
       }
       current = current[part] as Record<string, unknown>;
@@ -120,9 +132,39 @@ function expandDotPaths(flat: Record<string, unknown>): Record<string, unknown>
     current[parts[parts.length - 1]] = value;
   }
 
+  // The top level is always an object: it is the form, not a list.
+  for (const [key, value] of Object.entries(result)) {
+    if (isPlainObject(value)) result[key] = indexedListsToArrays(value);
+  }
   return result;
 }
 
+/**
+ * `node`, with every nested object whose keys are exactly `"0".."n-1"`
+ * turned into an array, depth first. Only a dense, canonical index set
+ * converts: `{ "0", "2" }` (a gap), `{ "01" }` and `{ "0", "name" }` stay
+ * objects. So a forged `rows.99999` stays one key instead of allocating a
+ * sparse array, and the array's length is bounded by the field count limit.
+ *
+ * Object.keys lists integer-like keys first, in ascending order, so a dense
+ * set reads as `0, 1, … n-1` and `Object.values` is already in index order.
+ */
+function indexedListsToArrays(node: Record<string, unknown>): Record<string, unknown> | unknown[] {
+  for (const [key, value] of Object.entries(node)) {
+    if (isPlainObject(value)) node[key] = indexedListsToArrays(value);
+  }
+  const keys = Object.keys(node);
+  const dense = keys.length > 0 && keys.every((key, i) => key === String(i));
+  return dense ? Object.values(node) : node;
+}
+
+/** An object the dot-path walk built — not an array, File or other instance. */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === 'object' && value !== null && Object.getPrototypeOf(value) === Object.prototype
+  );
+}
+
 // `__proto__` is the only key in this parser that escapes the dot-path
 // walk's `typeof !== 'object'` reset: accessing `obj['__proto__']` returns
 // `Object.prototype` (itself an object), so the walk steps into the global
@@ -132,13 +174,22 @@ function expandDotPaths(flat: Record<string, unknown>): Record<string, unknown>
 // keys and do not mutate anything global.
 const DANGEROUS_KEYS = new Set(['__proto__']);
 
+/**
+ * The most segments a dot-path field name may have. A deeper name is dropped,
+ * like a `__proto__` path, so no walk over the parsed value can exhaust the
+ * stack (TIM-1573).
+ */
+const MAX_PATH_DEPTH = 32;
+
 // ─── Coercion Helpers ────────────────────────────────────────────────────
 
 /**
  * Schema-agnostic coercion primitives for common FormData patterns.
  *
  * These are plain transform functions — they compose with any schema library's
- * `transform`/`preprocess` pipeline:
+ * `transform`/`preprocess` pipeline. In Zod, use `z.preprocess`: it runs on an
+ * absent key (an unchecked checkbox), where `z.unknown().transform()` fails
+ * with "expected nonoptional" before the transform runs.
  *
  * ```ts
  * // Zod
@@ -153,8 +204,9 @@ export const coerce = {
    * Use with `.optional()` schemas where an empty input means "not provided".
    *
    * ```ts
-   * // Zod
-   * z.unknown().transform(coerce.text).pipe(z.string().optional())
+   * // Zod — preprocess, not `z.unknown().transform(…)`: Zod 4 rejects an
+   * // absent key before a transform runs ("expected nonoptional")
+   * z.preprocess(coerce.text, z.string().optional())
    * // Valibot
    * v.pipe(v.unknown(), v.transform(coerce.text), v.optional(v.string()))
    * ```

package/src/server/form-state-flight.ts

@@ -0,0 +1,67 @@
+/**
+ * The no-JS action form state a page render hands React (TIM-1570), encoded
+ * with Flight (TIM-1572).
+ *
+ * Fizz renders the `useActionState` hook that submitted with the action's
+ * result, and the browser must hydrate with the same value, or the hook
+ * resets. Both get it from the Flight bytes encoded here: SSR decodes them
+ * for Fizz (`NavContext.formState`) and, once they decode, embeds them for
+ * `hydrateRoot` (server/ssr-form-state.ts; decoded by
+ * client/browser-entry/form-state.ts). Flight is what carries a
+ * `useActionState` result with JS, so a result has the same types with and
+ * without JS. See shared/form-state-flight.ts for the decode.
+ *
+ * A state Flight cannot encode must not turn the page into a 500 after the
+ * action's mutation committed, so it is dropped from both renders: the page
+ * renders with no result, as for a form without `useActionState`. That is a
+ * value Flight cannot serialize (a plain function, a class instance), which
+ * fails the action with JS too, or a nested promise that rejects or does not
+ * settle in time, which with JS reaches the hook as that rejected or pending
+ * promise. The no-JS page cannot carry a pending promise, and does not embed
+ * an error row.
+ *
+ * See design/08-forms-and-actions.md §"No-JS Result Round-Trip".
+ */
+
+import type { ReactFormState } from 'react-dom/client';
+import { renderToReadableStream } from '../rsc-runtime/rsc.ts';
+import { swallow } from './logger.ts';
+import { readAllBytesWithDeadline } from './stream-utils.ts';
+
+/**
+ * Serialize the form state with Flight, or return `null` when it cannot be,
+ * with a warning. The whole payload is read under one `timeoutMs` deadline,
+ * and the render stops when `signal` (the request's) aborts.
+ */
+export async function encodeFormState(
+  formState: ReactFormState,
+  timeoutMs: number,
+  signal?: AbortSignal
+): Promise<Uint8Array | null> {
+  let failure: unknown;
+  try {
+    // Flight reports a value it cannot serialize (anywhere in the tree,
+    // including a rejected nested promise) here, and writes an error row in
+    // its place; a result with an error row in it is not the action's result.
+    const flightErrors: unknown[] = [];
+    const stream = renderToReadableStream(formState, {
+      signal,
+      onError(error: unknown) {
+        flightErrors.push(error);
+      },
+    });
+    const bytes = await readAllBytesWithDeadline(stream, timeoutMs, 'no-JS form state encode');
+    if (flightErrors.length === 0) return bytes;
+    failure = flightErrors[0];
+  } catch (error) {
+    // The deadline, reported as itself: cancelling the read after it makes
+    // Flight report an abort to onError too, which says nothing of the cause.
+    failure = error;
+  }
+  swallow(
+    failure,
+    "a no-JS action's result could not be serialized with Flight, so the page renders without it",
+    { level: 'warn' }
+  );
+  return null;
+}

package/src/server/rsc-entry/action-dispatcher.ts

@@ -123,11 +123,14 @@ export function buildActionDispatcher(
     //     render's request-context cookies, so the page reads what the
     //     action wrote, not what the request carried (TIM-868).
     //   - Method GET because it is a page render.
+    //   - The POST's abort signal, so a client that disconnects stops the
+    //     render (and the form state encode) as it would any page's.
     const rerenderHeaders = new Headers(req.headers);
     rerenderHeaders.delete('cookie');
     const rerenderReq = new Request(req.url, {
       method: 'GET',
       headers: rerenderHeaders,
+      signal: req.signal,
     });
     const { cookies } = actionResponse;
     const response = await reenter(

package/src/server/rsc-entry/index.ts

@@ -322,6 +322,7 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
           clientSegmentCache,
           renderDenyFallback,
           buildManifest: typedBuildManifest,
+          renderTimeoutMs: (config as Record<string, unknown>).renderTimeoutMs as number,
           globalError: manifest.globalError,
         },
         interception