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

package/src/server/action-client.ts

@@ -161,7 +161,8 @@ export interface ActionBuilderWithSchema<TCtx, TInput> {
 /**
  * The final action function. Callable three ways:
  * - Direct: action(input) → Promise<ActionResult<TData>>
- * - React useActionState: action(prevState, formData) → Promise<ActionResult<TData>>
+ * - React useActionState: action(prevState, payload) → Promise<ActionResult<TData>>,
+ *   where payload is the submitted FormData or the value dispatch was called with
  * - React <form action={fn}>: action(formData) → void  (return value ignored by React)
  *
  * The third overload exists purely for type compatibility with React's
@@ -193,8 +194,11 @@ export type ActionFn<TData = unknown, TInput = unknown> = {
   (
     ...args: undefined extends TInput ? [input?: TInput] : [input: TInput]
   ): Promise<ActionResult<TData>>;
-  /** React useActionState: action(prevState, formData) */
-  (prevState: ActionResult<TData> | null, formData: FormData): Promise<ActionResult<TData>>;
+  /**
+   * React useActionState: action(prevState, payload). The payload is the
+   * submitted FormData, or whatever the hook's dispatch was called with.
+   */
+  (prevState: ActionResult<TData> | null, payload: TInput | FormData): Promise<ActionResult<TData>>;
 };
 
 // ─── Implementation ──────────────────────────────────────────────────────
@@ -281,8 +285,8 @@ function extractStandardSchemaErrors(issues: ReadonlyArray<StandardSchemaIssue>)
  * Wrap unexpected errors into a safe server error result.
  * ActionError → typed result. Other errors → INTERNAL_ERROR (no leak).
  *
- * Exported for use by action-handler.ts to catch errors from raw 'use server'
- * functions that don't use createActionClient.
+ * `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> {
   if (error instanceof ActionError) {
@@ -339,21 +343,15 @@ export function createActionClient<TCtx = Record<string, never>>(
         // Run middleware
         const ctx = await runActionMiddleware(config.middleware);
 
-        // Determine input — either FormData (from useActionState) or direct arg
-        let rawInput: unknown;
-        if (args.length === 2 && args[1] instanceof FormData) {
-          // Called as (prevState, formData) by React useActionState (with-JS path)
-          rawInput = schema ? parseFormData(args[1]) : args[1];
-        } else if (args.length === 1 && args[0] instanceof FormData) {
-          // No-JS path: React's decodeAction binds FormData as the sole argument.
-          // The form POSTs without JavaScript, decodeAction resolves the server
-          // reference and binds the FormData, then executeAction calls fn() with
-          // no additional args — so the bound FormData arrives as args[0].
-          rawInput = schema ? parseFormData(args[0]) : args[0];
-        } else {
-          // Direct call: action(input)
-          rawInput = args[0];
-        }
+        // 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

package/src/server/action-handler.ts

@@ -8,7 +8,8 @@
  * 1. Detect action request (POST with `x-rsc-action` header or form action fields)
  * 2. CSRF validation
  * 3. Load and execute the server action
- * 4. Return RSC stream (with-JS) or 302 redirect (no-JS)
+ * 4. Return RSC stream (with-JS), or on the no-JS path a redirect, a page
+ *    rerender carrying React's form state, or the error page
  *
  * See design/08-forms-and-actions.md
  */
@@ -17,6 +18,7 @@ import {
   loadServerAction,
   decodeReply,
   decodeAction,
+  decodeFormState,
   renderToReadableStream,
 } from '../rsc-runtime/rsc.ts';
 
@@ -26,16 +28,19 @@ import { executeAction, type RevalidateRenderer } from './actions.ts';
 import { runWithRequestContext, setMutableCookieContext } from './request-context.ts';
 import { runOutsideReactCacheScope, runWithReactCacheScope } from './react-cache-scope.ts';
 import { getSetCookieHeaders, getCookiesForSsr } from './cookie-context.ts';
-import { ActionError, handleActionError } from './action-client.ts';
+import { ActionError } from './action-client.ts';
 import { enforceBodyLimits, enforceFieldLimit, type BodyLimitsConfig } from './body-limits.ts';
-import { parseFormData } from './form-data.ts';
 import {
   stripSensitiveFields,
   resolveSensitivePredicate,
   getGlobalSensitiveFieldsConfig,
+  type ResolvedSensitivePredicate,
   type SensitiveFieldsOption,
 } from './sensitive-fields.ts';
-import type { FormFlashData } from './form-flash.ts';
+import { randomUUID } from 'node:crypto';
+import type { ReactFormState } from 'react-dom/client';
+import { encodeErrorDigest } from '../shared/error-digest.ts';
+import { clientErrorMessage } from './client-error-message.ts';
 import { checkVersionSkew, applyReloadHeaders } from './version-skew.ts';
 import { logActionError, swallow } from './logger.ts';
 import { fireOnRequestError } from './pipeline-helpers.ts';
@@ -95,7 +100,18 @@ export function isActionRequest(req: Request): boolean {
 // ─── Handler ──────────────────────────────────────────────────────────────
 
 /**
- * Signal from handleFormAction to re-render the page with flash data instead of redirecting.
+ * How a no-JS action that did not redirect is answered. The dispatcher
+ * (`rsc-entry/action-dispatcher.ts`) turns it into the response:
+ *
+ *   - `rerender`: the action returned. The page is rendered again as a GET,
+ *     with `formState` — React's `decodeFormState` of the result, present
+ *     only when the submitted form used `useActionState` — handed to SSR
+ *     and hydration, where React gives it to the hook that submitted.
+ *   - `error`: the action threw. The page is rendered again with the error
+ *     in place of the page component, so the route's nearest error page
+ *     answers, with the
+ *     status the pipeline gives any unhandled error. The JS path rejects
+ *     the action for the same throw, so both reach an error boundary.
  *
  * Carries two cookie-related snapshots taken before the action's ALS scope
  * exits, so the rerender pipeline (which establishes its own fresh cookie
@@ -115,22 +131,36 @@ export function isActionRequest(req: Request): boolean {
  *     previous `cookieHeader: string` shape carried — see
  *     ONGOING_SECURITY.md H-3 (TIM-868) and TIM-837.
  */
-export interface FormRerender {
-  rerender: FormFlashData;
-  setCookieHeaders: string[];
-  cookies: Map<string, string>;
-}
+export type FormActionOutcome =
+  | {
+      kind: 'rerender';
+      formState: ReactFormState | undefined;
+      setCookieHeaders: string[];
+      cookies: Map<string, string>;
+    }
+  | {
+      kind: 'error';
+      error: unknown;
+      errorId: string;
+      setCookieHeaders: string[];
+      cookies: Map<string, string>;
+    };
+
+/** What `handleFormAction` settles with, before the cookie snapshot. */
+type FormActionSettled =
+  | { kind: 'rerender'; formState: ReactFormState | undefined }
+  | { kind: 'error'; error: unknown; errorId: string };
 
 /**
  * Handle a server action request.
  *
- * Returns a Response, a FormRerender signal (for no-JS validation failure re-render),
+ * Returns a Response, a FormActionOutcome (no-JS action that did not redirect),
  * or null if this isn't actually an action request (e.g., a regular form POST to an API route).
  */
 export async function handleActionRequest(
   req: Request,
   config: ActionDispatchConfig
-): Promise<Response | FormRerender | null> {
+): Promise<Response | FormActionOutcome | null> {
   // Version skew detection — reject actions from stale clients (TIM-446).
   // On mismatch, return a structured RSC error response that the client
   // handles by showing a brief "App updated" message and reloading.
@@ -183,38 +213,35 @@ export async function handleActionRequest(
       setMutableCookieContext(true);
       const actionId = req.headers.get('x-rsc-action');
 
-      let result: Response | FormRerender | null;
-      if (actionId) {
-        // With-JS path: client sent action ID in header, args in body
-        result = await handleRscAction(req, actionId, config);
-      } else {
-        // No-JS path: form POST with React's hidden action fields
-        result = await handleFormAction(req, config);
-      }
+      // With-JS path: client sent action ID in header, args in body.
+      // No-JS path: form POST with React's hidden action fields.
+      const result = actionId
+        ? await handleRscAction(req, actionId, config)
+        : await handleFormAction(req, config);
 
       // Apply cookie jar to action responses.
       //
-      // For Response results we append Set-Cookie directly. For FormRerender
-      // signals we snapshot the headers here, before this ALS scope exits, so
-      // the caller can apply them to the rerender pipeline's response (which
+      // For a Response we append Set-Cookie directly. For a no-JS outcome we
+      // snapshot the headers here, before this ALS scope exits, so the
+      // dispatcher can apply them to the response it builds (the rerender
       // runs in its own request-context scope with a fresh cookie jar).
       // See LOCAL-740 — without this snapshot, cookies set inside a no-JS
-      // form action that returns validation errors are silently dropped.
+      // form action are silently dropped.
+      if (result === null) return null;
       if (result instanceof Response) {
         for (const value of getSetCookieHeaders()) {
           result.headers.append('Set-Cookie', value);
         }
-      } else if (result && 'rerender' in result) {
-        result.setCookieHeaders = getSetCookieHeaders();
-        // Snapshot the post-action RYW cookie state as a Map so the rerender
-        // dispatcher can hand it to the rerender request context directly,
-        // with no string round-trip. See TIM-837
-        // and ONGOING_SECURITY.md H-3 (TIM-868). `getCookiesForSsr` already
-        // returns a defensive copy, so the rerender scope cannot mutate the
-        // snapshot through this reference.
-        result.cookies = getCookiesForSsr();
+        return result;
       }
-      return result;
+      const setCookieHeaders = getSetCookieHeaders();
+      // Snapshot the post-action RYW cookie state as a Map so the rerender
+      // dispatcher can hand it to the rerender request context directly,
+      // with no string round-trip. See TIM-837
+      // and ONGOING_SECURITY.md H-3 (TIM-868). `getCookiesForSsr` already
+      // returns a defensive copy, so the rerender scope cannot mutate the
+      // snapshot through this reference.
+      return { ...result, setCookieHeaders, cookies: getCookiesForSsr() };
     })
   );
 }
@@ -226,8 +253,8 @@ export async function handleActionRequest(
  * `'action'`. An `ActionError` is not reported: it is an outcome the
  * action chose to return, not an unhandled error.
  */
-async function reportActionError(req: Request, error: unknown): Promise<void> {
-  logActionError({ method: req.method, path: new URL(req.url).pathname, error });
+async function reportActionError(req: Request, error: unknown, errorId?: string): Promise<void> {
+  logActionError({ method: req.method, path: new URL(req.url).pathname, error, errorId });
   if (error instanceof ActionError) return;
   await fireOnRequestError(error, req, 'action');
 }
@@ -275,17 +302,32 @@ async function rejectActionRequest(
 }
 
 /**
- * The no-JS answer to an action error: re-render the page with the error as
- * flash data. `handleActionError` produces `{ serverError }` for an
- * ActionError and `{ serverError: { code: 'INTERNAL_ERROR' } }` otherwise.
+ * The with-JS answer to an action that threw: the action rejects on the
+ * client and the nearest error boundary renders, as React does for any
+ * server function that throws. The no-JS path answers the same throw with
+ * the error page, so both reach an error boundary and neither turns the
+ * throw into state the action never returned. `createActionClient`
+ * actions never get here: they catch into a `serverError` result.
+ *
+ * The error crosses as a rejected Flight root carrying the digest a render
+ * error carries (shared/error-digest.ts): its message in dev, a fixed one in
+ * production (design/13-security.md §"Errors don't leak"), and the
+ * correlation ID the server logged it with.
  */
-function errorRerender(error: unknown, submittedValues: Record<string, unknown>): FormRerender {
-  return {
-    rerender: { ...handleActionError(error), submittedValues },
-    // Filled in by handleActionRequest before the ALS scope exits.
-    setCookieHeaders: [],
-    cookies: new Map(),
-  };
+async function rejectedActionResponse(req: Request, error: unknown): Promise<Response> {
+  const errorId = randomUUID();
+  await reportActionError(req, error, errorId);
+  const rejection = Promise.reject(error);
+  // Flight subscribes when it renders the root, after this tick; the no-op
+  // handler keeps the rejection from being reported as unhandled first.
+  rejection.catch(() => {});
+  const rscStream = renderToReadableStream(rejection, {
+    onError: () => encodeErrorDigest({ message: clientErrorMessage(error), errorId }),
+  });
+  return new Response(rscStream, {
+    status: 500,
+    headers: { 'Content-Type': RSC_CONTENT_TYPE },
+  });
 }
 
 /**
@@ -355,10 +397,8 @@ async function handleRscAction(
   const call = await decodeRscActionCall(req, actionId, config);
   if (call instanceof Response) return call;
 
-  // Execute the action with revalidation tracking.
-  // Errors are caught here so raw 'use server' functions (not using
-  // createActionClient) still return structured error responses instead
-  // of leaking stack traces as 500s.
+  // Execute the action with revalidation tracking. A throw is answered
+  // with a rejected action (below), never a stack trace.
   let result;
   try {
     const requestUrl = new URL(req.url);
@@ -371,16 +411,7 @@ async function handleRscAction(
       requestSearch: requestUrl.search,
     });
   } catch (error) {
-    await reportActionError(req, error);
-
-    // Return structured error response — ActionError gets its code/data,
-    // unexpected errors get sanitized { code: 'INTERNAL_ERROR' }
-    const errorResult = handleActionError(error);
-    const rscStream = renderToReadableStream(errorResult);
-    return new Response(rscStream, {
-      status: 200,
-      headers: { 'Content-Type': RSC_CONTENT_TYPE },
-    });
+    return rejectedActionResponse(req, error);
   }
   // Outside the try: the action succeeded, and a failure to report its
   // revalidation must not turn it into an action error.
@@ -571,13 +602,14 @@ function concatUint8Arrays(chunks: Uint8Array[]): Uint8Array {
  * Handle a no-JS form action (progressive enhancement fallback).
  *
  * React embeds `$ACTION_REF` / `$ACTION_KEY` hidden fields in the form.
- * We use `decodeAction` to resolve the action function from the form data,
- * execute it, then redirect back to the form's page.
+ * We use `decodeAction` to resolve the action function from the form data
+ * and execute it. A redirect is answered here; anything else settles as a
+ * `FormActionSettled` for the dispatcher to render.
  */
 async function handleFormAction(
   req: Request,
   config: ActionDispatchConfig
-): Promise<Response | FormRerender | null> {
+): Promise<Response | FormActionSettled | null> {
   // Clone before consuming — if this turns out not to be a server action form,
   // we return null and the original request body must remain readable for
   // downstream route handlers. Clone is cheap (shares the body buffer until read).
@@ -595,16 +627,6 @@ async function handleFormAction(
     return new Response(null, { status: fieldResult.status });
   }
 
-  // Capture submitted values for re-render on validation failure.
-  // Parse before decodeAction consumes the FormData, then strip sensitive
-  // fields (passwords, tokens, CVV, etc.) so they are never rendered back
-  // into the HTML as `defaultValue` attributes. See TIM-816.
-  const sensitivePredicate = resolveSensitivePredicate(
-    config.sensitiveFields,
-    getGlobalSensitiveFieldsConfig()
-  );
-  const submittedValues = stripSensitiveFields(parseFormData(formData), sensitivePredicate);
-
   // decodeAction resolves the action function from the form data's hidden fields.
   // Returns null when no $ACTION_REF_/$ACTION_ID_ fields are present — meaning
   // this is a regular form POST, not a React server action.
@@ -632,8 +654,9 @@ async function handleFormAction(
       renderer: config.revalidateRenderer,
     });
   } catch (error) {
-    await reportActionError(req, error);
-    return errorRerender(error, submittedValues);
+    const errorId = randomUUID();
+    await reportActionError(req, error, errorId);
+    return { kind: 'error', error, errorId };
   }
   // Outside the try: the action succeeded, and a failure to report its
   // revalidation must not turn it into an action error.
@@ -647,25 +670,40 @@ async function handleFormAction(
     });
   }
 
-  // Re-render the page with the action result as flash data.
-  // The server component reads the flash via getFormFlash() and passes it
-  // to the client form component as the initial useActionState value.
-  // This handles both success ({ data }) and validation failure
-  // ({ validationErrors, submittedValues }) — the form is the single source of truth.
-  const actionResult = result.actionResult as FormFlashData;
-
-  // Defense-in-depth: strip sensitive fields from `actionResult.submittedValues`
-  // even if the action already built it. `createActionClient` strips internally,
-  // but raw `'use server'` functions that manually return `{ submittedValues }`
-  // are not covered by the inner strip. See TIM-816.
-  if (actionResult && actionResult.submittedValues) {
-    actionResult.submittedValues = stripSensitiveFields(
-      actionResult.submittedValues,
-      sensitivePredicate
-    );
-  }
+  // Defense-in-depth: strip sensitive fields from `submittedValues` before
+  // the result is rendered into the page. `createActionClient` strips
+  // internally, but a raw `'use server'` function that returns
+  // `{ submittedValues }` itself is not covered by that. See TIM-816.
+  const actionResult = stripResultSubmittedValues(
+    result.actionResult,
+    resolveSensitivePredicate(config.sensitiveFields, getGlobalSensitiveFieldsConfig())
+  );
 
-  // setCookieHeaders + cookies are filled in by handleActionRequest before
-  // the ALS scope exits.
-  return { rerender: actionResult, setCookieHeaders: [], cookies: new Map() };
+  // React keys the result to the hook that submitted: `$ACTION_KEY` names
+  // the useActionState instance, and Fizz hands the result to it as its
+  // initial state only when that key and the action match. A form with no
+  // useActionState has no key, so this is undefined and the page renders
+  // with no result, as the JS path discards the return value of a plain
+  // `<form action>`. Such forms should `redirect()` (post-redirect-get).
+  const formState = (await decodeFormState(actionResult, formData)) ?? undefined;
+  return { kind: 'rerender', formState };
+}
+
+/**
+ * `result` with sensitive fields removed from its `submittedValues`, when it
+ * has any. A copy: the action's own object is not written to.
+ */
+function stripResultSubmittedValues(
+  result: unknown,
+  isSensitive: ResolvedSensitivePredicate
+): unknown {
+  if (typeof result !== 'object' || result === null || !('submittedValues' in result)) {
+    return result;
+  }
+  const { submittedValues } = result;
+  if (typeof submittedValues !== 'object' || submittedValues === null) return result;
+  return {
+    ...result,
+    submittedValues: stripSensitiveFields(submittedValues, isSensitive),
+  };
 }

package/src/server/als-registry.ts

@@ -35,6 +35,7 @@ import '#server-only-guard';
 import type { CoercedParams } from '../shared/param-value.ts';
 import type { SlotParamsRecord } from '../shared/slot-params.ts';
 import { AsyncLocalStorage } from 'node:async_hooks';
+import type { ReactFormState } from 'react-dom/client';
 /**
  * Return a process-wide singleton `AsyncLocalStorage` keyed by `symbol`.
  *
@@ -65,6 +66,12 @@ export const requestContextAls = getOrCreateAls<RequestContextStore>(
   Symbol.for('timber:request-context-als')
 );
 
+/** A no-JS action's thrown error, and the correlation ID it was logged with. */
+export interface ActionErrorForRender {
+  error: unknown;
+  errorId: string;
+}
+
 export interface RequestContextStore {
   /**
    * The request this context was opened for, or `null` in the build-time
@@ -134,6 +141,22 @@ export interface RequestContextStore {
   flushed: boolean;
   /** Whether the current context allows cookie mutation. */
   mutableContext: boolean;
+  /**
+   * The form state a no-JS action produced (`decodeFormState`), set only on
+   * the page render that answers it. Read once, by the SSR renderer, which
+   * hands it to Fizz and embeds it for `hydrateRoot`; no user-facing API
+   * reads it, because a server component cannot see an action's result on
+   * the JS path either (design/08 §"No-JS Result Round-Trip").
+   */
+  formState?: ReactFormState;
+  /**
+   * The error a no-JS action threw, set only on the page render that answers
+   * it. The route renders it where its page would be, so the nearest error
+   * page answers, as the nearest error boundary does with JS. Read by the
+   * route element builder and the Flight `onError`; no user-facing API reads
+   * it (design/08 §"The Basic Wire-Up").
+   */
+  actionError?: ActionErrorForRender;
   /**
    * Set by AccessGate or PageDenyBoundary when a DenySignal is caught
    * server-side (inside the React tree, before React Flight sees it).
@@ -236,15 +259,6 @@ export const revalidationAls = getOrCreateAls<RevalidationState>(
   Symbol.for('timber:revalidation-als')
 );
 
-// ─── Form Flash ───────────────────────────────────────────────────────────
-// Used by: form-flash.ts (getFormFlash())
-// Design doc: design/08-forms-and-actions.md §"No-JS Result Round-Trip"
-
-/** @internal — import via form-flash.ts public API */
-export const formFlashAls = getOrCreateAls<import('./form-flash.ts').FormFlashData>(
-  Symbol.for('timber:form-flash-als')
-);
-
 // ─── Early Hints Sender ──────────────────────────────────────────────────
 // Used by: early-hints-sender.ts (sendEarlyHints103())
 // Design doc: design/02-rendering-pipeline.md §"Early Hints (103)"

package/src/server/client-error-message.ts

@@ -0,0 +1,18 @@
+/**
+ * The message an unexpected server error shows the client: its own message
+ * in dev, a fixed one in production (design/13-security.md §"Errors don't
+ * leak"). One definition for every place an error crosses to the client —
+ * a Flight error row's digest, a rejected action, an error page's error.
+ *
+ * Uses isDevMode(), not isDebug(): the text reaches the browser, and
+ * TIMBER_DEBUG must never make it leak.
+ */
+
+import { isDevMode } from './debug.ts';
+
+export const PRODUCTION_ERROR_MESSAGE = 'An unexpected error occurred.';
+
+export function clientErrorMessage(error: unknown): string {
+  if (!isDevMode()) return PRODUCTION_ERROR_MESSAGE;
+  return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,63 @@
+/**
+ * The no-JS action form state a page render hands React (TIM-1570).
+ *
+ * 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. The browser's copy is embedded as JSON, as Next.js embeds it
+ * (`self.__timber_form_state`, read by client/browser-entry/hydrate.ts).
+ *
+ * Both renders must get the same value, or the hook's state changes during
+ * hydration. JSON is lossy (a `Date` becomes a string, a `Map` `{}`, an
+ * `undefined` field — `{ data: undefined }` from every void action — is
+ * dropped), so Fizz gets the JSON round-trip of the state, not the original:
+ * exactly what the browser decodes. On the no-JS path a result is what JSON
+ * carries. A state JSON cannot encode at all (a `BigInt`, a cycle) 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`.
+ *
+ * With client JS disabled nothing is embedded and nothing hydrates, so Fizz
+ * gets the original.
+ *
+ * See design/08-forms-and-actions.md §"No-JS Result Round-Trip".
+ */
+
+import type { ReactFormState } from 'react-dom/client';
+import { htmlEscapeJsonString } from './flight-scripts.ts';
+import { swallow } from './logger.ts';
+import { nonceAttr } from './render-utils.ts';
+
+export interface FormStateForRender {
+  /** For Fizz — the same value the embedded script hands `hydrateRoot`. */
+  formState: ReactFormState | undefined;
+  /** The `<script>` that embeds it for hydration, or `''`. */
+  script: string;
+}
+
+export function formStateForRender(
+  formState: ReactFormState | null,
+  clientJsDisabled: boolean,
+  nonce: string | undefined
+): FormStateForRender {
+  if (!formState) return { formState: undefined, script: '' };
+  // No client: nothing hydrates, so nothing is embedded.
+  if (clientJsDisabled) return { formState, script: '' };
+  let json: string;
+  try {
+    json = JSON.stringify(formState);
+  } catch (error) {
+    swallow(
+      error,
+      "a no-JS action's result could not be encoded as JSON for hydration, so the page " +
+        'renders without it; return plain data (no BigInt or cycles) from actions',
+      { level: 'warn' }
+    );
+    return { formState: undefined, script: '' };
+  }
+  return {
+    // `JSON.parse` returns the decoded tuple untyped; it is the same
+    // opaque `ReactFormState` React built, as the browser will decode it.
+    formState: JSON.parse(json),
+    script: `<script${nonceAttr(nonce)}>self.__timber_form_state=${htmlEscapeJsonString(json)}</script>`,
+  };
+}

package/src/server/index.ts

@@ -49,10 +49,6 @@ export type {
 // FormData Preprocessing
 export { coerce, parseFormData } from './form-data.ts';
 
-// Form Flash (no-JS error round-trip)
-export { getFormFlash } from './form-flash.ts';
-export type { FormFlashData } from './form-flash.ts';
-
 // Revalidation — user-facing revalidation APIs
 export { revalidatePath, revalidateTag } from './actions.ts';
 

package/src/server/logger.ts

@@ -168,7 +168,12 @@ export function logProxyError(data: { error: unknown }): void {
 }
 
 /** Log unhandled error in server action. Level: error. */
-export function logActionError(data: { method: string; path: string; error: unknown }): void {
+export function logActionError(data: {
+  method: string;
+  path: string;
+  error: unknown;
+  errorId?: string;
+}): void {
   if (isControlFlowSignal(data.error)) return;
   _logger.error('unhandled server action error', withTraceContext(data));
 }