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

package/src/server/request-context.ts

@@ -15,7 +15,11 @@
  */
 
 import type { CoercedParams } from '../shared/param-value.ts';
-import { requestContextAls, type RequestContextStore } from './als-registry.ts';
+import {
+  requestContextAls,
+  type ActionErrorForRender,
+  type RequestContextStore,
+} from './als-registry.ts';
 import { _setGetSearchParamsFn, _setGetSegmentParamsFn } from '../shared/als-slots.ts';
 import { appVisibleSearch } from '../shared/rsc-cache-key.ts';
 import {
@@ -25,6 +29,7 @@ import {
 } from '../shared/slot-params.ts';
 import { isDebug } from './debug.ts';
 import { runWithReactCacheScope, type ReactCacheScope } from './react-cache-scope.ts';
+import type { ReactFormState } from 'react-dom/client';
 
 // Re-export the ALS for framework-internal consumers that need direct access.
 export { requestContextAls };
@@ -321,6 +326,16 @@ export interface RequestContextOptions {
    * (TIM-868).
    */
   cookies?: Map<string, string>;
+  /**
+   * The form state of the no-JS action this render answers. Only the
+   * action dispatcher's re-entry passes it; see `RequestContextStore.formState`.
+   */
+  formState?: ReactFormState;
+  /**
+   * The error of the no-JS action this render answers. Only the action
+   * dispatcher's re-entry passes it; see `RequestContextStore.actionError`.
+   */
+  actionError?: ActionErrorForRender;
 }
 
 /**
@@ -342,7 +357,7 @@ export interface RequestContextOptions {
 export function runWithRequestContext<T>(
   req: Request,
   fn: () => T,
-  { reactCacheScope, cookies }: RequestContextOptions = {}
+  { reactCacheScope, cookies, formState, actionError }: RequestContextOptions = {}
 ): T {
   const originalCopy = new Headers(req.headers);
   const appVisible = appVisibleSearch(new URL(req.url));
@@ -366,6 +381,8 @@ export function runWithRequestContext<T>(
     cookieJar: new Map(),
     flushed: false,
     mutableContext: false,
+    formState,
+    actionError,
   };
   return requestContextAls.run(store, () => runWithReactCacheScope(fn, reactCacheScope));
 }
@@ -463,3 +480,23 @@ function freezeHeaders(source: Headers): Headers {
     },
   });
 }
+
+/**
+ * The form state of the no-JS action this render answers, or `null`. Read by
+ * the SSR renderer only (`rsc-entry/ssr-renderer.ts`), which passes it to
+ * Fizz and embeds it for `hydrateRoot`. Framework-internal: not exported
+ * from `@timber-js/app/server`.
+ */
+export function getFormStateForSsr(): ReactFormState | null {
+  return requestContextAls.getStore()?.formState ?? null;
+}
+
+/**
+ * The error of the no-JS action this render answers, or `null`. Read by the
+ * route element builder, which renders it in place of the page, and by the
+ * Flight `onError`, which gives it the ID the action logged it with.
+ * Framework-internal: not exported from `@timber-js/app/server`.
+ */
+export function getActionErrorForRender(): ActionErrorForRender | null {
+  return requestContextAls.getStore()?.actionError ?? null;
+}

package/src/server/route-element-builder.ts

@@ -50,6 +50,7 @@ import { setFirstDeniedSegmentIndex } from './deny-boundary.ts';
 import { loadModule, type ManifestLoader } from './safe-load.ts';
 import { loadFallbackModule } from './pipeline-helpers.ts';
 import { replaceOutermostSegmentOutlet } from './route-element-helpers.ts';
+import { getActionErrorForRender } from './request-context.ts';
 
 /**
  * The `segments` array handed to a layout's `SegmentProvider` — the value
@@ -264,8 +265,18 @@ export async function buildRouteElement(
   // so they go through createElement normally — no wrapper needed.
   const leafIndex = segments.length - 1;
   const leafDenyPages = denyPageChains.get(leafIndex);
+  // A no-JS action that threw is answered by this route with the error in
+  // place of its page (design/08 §"The Basic Wire-Up"). The layouts and
+  // access gates above still render, so the nearest error page answers and
+  // a denied segment's layout never wraps it — the render-error path.
+  const actionError = getActionErrorForRender();
   let element: React.ReactElement;
-  if (isClientReference(PageComponent)) {
+  if (actionError) {
+    const ActionError = (): never => {
+      throw actionError.error;
+    };
+    element = h(ActionError, {});
+  } else if (isClientReference(PageComponent)) {
     element = h(PageComponent, {});
   } else if (leafDenyPages && leafDenyPages.length > 0) {
     element = h(PageDenyBoundary, {

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

@@ -8,7 +8,8 @@
  * `createPipeline` calls it after proxy.ts runs (TIM-1213), so proxy.ts
  * sees action POSTs — "proxy.ts runs on every request, no exclusions." It
  * encapsulates action detection, the route-type check, action handler
- * dispatch, and the no-JS validation rerender path.
+ * dispatch, and the answer to a no-JS action that did not redirect: the
+ * page rerendered with React's form state, or the error page.
  *
  * The CSRF gate is not here: it runs in `createPipeline` before proxy.ts
  * (`csrfGate` in pipeline-helpers.ts). The action handler repeats the
@@ -19,12 +20,10 @@
  * auth/validation belongs in `createActionClient({ middleware })`.
  */
 
-import type { FormRerender } from '../action-handler.ts';
 import { handleActionRequest, isActionRequest } from '../action-handler.ts';
 import type { BodyLimitsConfig } from '../body-limits.ts';
 import type { CsrfConfig } from '../csrf.ts';
-import { runWithFormFlash } from '../form-flash.ts';
-import type { RouteMatcher } from '../pipeline.ts';
+import type { PipelineReentry, RouteMatcher } from '../pipeline.ts';
 import { isApiRouteChain } from '../route-matcher.ts';
 import type { SensitiveFieldsOption } from '../sensitive-fields.ts';
 import type { RevalidateRenderer } from '../actions.ts';
@@ -69,8 +68,8 @@ export interface ActionDispatcherDeps {
  *
  * Called after proxy.ts runs (inside the pipeline) for every request.
  * Checks if the request is a server action POST, handles the route-type
- * check (TIM-870), dispatches to the action handler, and handles the
- * no-JS validation rerender path.
+ * check (TIM-870), dispatches to the action handler, and answers a no-JS
+ * action that did not redirect.
  *
  * Returns `Response` if the request was handled as an action, `null` to
  * fall through to normal routing.
@@ -80,12 +79,12 @@ export function buildActionDispatcher(
 ): (
   req: Request,
   canonicalPath: string,
-  reenter: (req: Request, cookies: Map<string, string>) => Promise<Response>
+  reenter: (req: Request, reentry: PipelineReentry) => Promise<Response>
 ) => Promise<Response | null> {
   return async (
     req: Request,
     canonicalPath: string,
-    reenter: (req: Request, cookies: Map<string, string>) => Promise<Response>
+    reenter: (req: Request, reentry: PipelineReentry) => Promise<Response>
   ): Promise<Response | null> => {
     if (!isActionRequest(req)) return null;
 
@@ -109,34 +108,38 @@ export function buildActionDispatcher(
       revalidateRenderer: deps.buildRevalidateRenderer(req),
     });
 
-    if (actionResponse) {
-      // No-JS validation rerender
-      if ('rerender' in actionResponse) {
-        const formRerender = actionResponse as FormRerender;
-        // Build a synthetic GET request for the rerender pipeline:
-        //   - Same URL (so route matching lands on the same page)
-        //   - Cookie header DROPPED entirely. The post-action RYW state
-        //     is handed to `reenter` as a parsed `Map<string, string>`,
-        //     which becomes the rerender request context's cookies.
-        //   - Method GET because the rerender is conceptually a page render.
-        const rerenderHeaders = new Headers(req.headers);
-        rerenderHeaders.delete('cookie');
-        const rerenderReq = new Request(req.url, {
-          method: 'GET',
-          headers: rerenderHeaders,
-        });
-        const response = await runWithFormFlash(formRerender.rerender, () =>
-          reenter(rerenderReq, formRerender.cookies)
-        );
-        // Apply Set-Cookie headers snapshotted from the action's ALS scope.
-        for (const value of formRerender.setCookieHeaders) {
-          response.headers.append('Set-Cookie', value);
-        }
-        return response;
-      }
+    if (actionResponse === null || actionResponse instanceof Response) {
       return actionResponse;
     }
 
-    return null;
+    // Both answers re-enter the pipeline for a page render of the same URL,
+    // as a GET — the rerender with the action's form state, the throw with
+    // its error, which the route renders in place of its page so the
+    // nearest error page answers (SSR has no error boundaries, so that page
+    // comes from the shell-failure path):
+    //   - Same URL (so route matching lands on the same page)
+    //   - Cookie header DROPPED entirely. The post-action RYW state is
+    //     handed over as a parsed `Map<string, string>` and becomes the
+    //     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.
+    const rerenderHeaders = new Headers(req.headers);
+    rerenderHeaders.delete('cookie');
+    const rerenderReq = new Request(req.url, {
+      method: 'GET',
+      headers: rerenderHeaders,
+    });
+    const { cookies } = actionResponse;
+    const response = await reenter(
+      rerenderReq,
+      actionResponse.kind === 'error'
+        ? { cookies, actionError: { error: actionResponse.error, errorId: actionResponse.errorId } }
+        : { cookies, formState: actionResponse.formState }
+    );
+    // Apply Set-Cookie headers snapshotted from the action's ALS scope.
+    for (const value of actionResponse.setCookieHeaders) {
+      response.headers.append('Set-Cookie', value);
+    }
+    return response;
   };
 }

package/src/server/rsc-entry/error-renderer.ts

@@ -29,6 +29,7 @@ import { getCookiesForSsr } from '../cookie-context.ts';
 import { callSsr } from './ssr-bridge.ts';
 import { teeWithErrorPropagation } from '../stream-utils.ts';
 import { isDevMode } from '../debug.ts';
+import { clientErrorMessage } from '../client-error-message.ts';
 import { ErrorReconstituter } from '../../client/error-reconstituter.tsx';
 import type { SerializableError } from '../../client/error-reconstituter.tsx';
 import type { ManifestLoader } from '../safe-load.ts';
@@ -148,7 +149,7 @@ function toSerializableError(error: unknown): SerializableError {
   const err = error instanceof Error ? error : new Error(String(error));
   const devMode = isDevMode();
   return {
-    message: devMode ? err.message : 'An unexpected error occurred.',
+    message: clientErrorMessage(err),
     name: devMode ? err.name : 'Error',
     ...(devMode && err.stack ? { stack: err.stack } : {}),
   };

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

@@ -18,13 +18,14 @@ import { randomUUID } from 'node:crypto';
 
 import { matchDenyEntries, type DenyPageEntry } from '../deny-boundary.ts';
 import { reportRenderError } from '../pipeline-helpers.ts';
+import { getActionErrorForRender } from '../request-context.ts';
+import { clientErrorMessage } from '../client-error-message.ts';
 import { isDenySignal, isRedirectSignal } from '../signal-identity.ts';
 import { checkAndWarnRscPropError } from '../rsc-prop-warnings.ts';
 
 import { isAbortError } from './helpers.ts';
 import { createSignalRecorder, type RenderSignals } from './render-signals.ts';
 import { isDebug } from '../debug.ts';
-import { isDevMode } from '../debug.ts';
 
 export interface RscStreamResult {
   rscStream: ReadableStream<Uint8Array>;
@@ -135,16 +136,17 @@ export function renderRscStream(
         // whether a Suspense boundary contains it or it crashes the shell
         // and the renderer answers with the error page (design/49
         // §"Deferred: render-error handoff").
-        const errorId = randomUUID();
-        reportRenderError(error, req, { errorId });
-        return encodeErrorDigest({
-          message: isDevMode()
-            ? error instanceof Error
-              ? error.message
-              : String(error)
-            : 'An unexpected error occurred.',
-          errorId,
-        });
+        //
+        // The one exception is a no-JS action's error, rendered in place of
+        // the page (route-element-builder.ts): the action already logged and
+        // reported it, so it keeps that log line's ID and is not reported
+        // twice.
+        const actionError = getActionErrorForRender();
+        const errorId =
+          actionError && actionError.error === error
+            ? actionError.errorId
+            : reportedErrorId(error, req);
+        return encodeErrorDigest({ message: clientErrorMessage(error), errorId });
       },
     },
     {
@@ -159,3 +161,10 @@ export function renderRscStream(
 
   return { rscStream, signals: recorder.signals };
 }
+
+/** Log and report an unhandled render error; the ID it was logged with. */
+function reportedErrorId(error: unknown, req: Request): string {
+  const errorId = randomUUID();
+  reportRenderError(error, req, { errorId });
+  return errorId;
+}

package/src/server/rsc-entry/ssr-renderer.ts

@@ -28,6 +28,8 @@ import type { NavContext, SsrRenderResult } from '../ssr-bridge-types.ts';
 import { htmlEscapeJsonString } from '../flight-scripts.ts';
 import { buildSegmentInfo, isAbortError } from './helpers.ts';
 import { getCookiesForSsr } from '../cookie-context.ts';
+import { getFormStateForSsr } from '../request-context.ts';
+import { formStateForRender } from '../form-state-embed.ts';
 import { getDenyStatus, getFirstDeniedSegmentIndex } from '../deny-boundary.ts';
 import { renderErrorPage, type GlobalErrorFile } from './error-renderer.ts';
 import { callSsr } from './ssr-bridge.ts';
@@ -170,6 +172,15 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
   // that is the value every inline script must wear.
   const nonce = getCspNonce();
 
+  // Only a page answering a no-JS action has one (design/08 §"No-JS Result
+  // Round-Trip"). Fizz gives it to the hook that submitted; the browser
+  // needs the same value for hydrateRoot, or hydration resets that hook.
+  const { formState, script: formStateScript } = formStateForRender(
+    getFormStateForSsr(),
+    clientJsDisabled,
+    nonce
+  );
+
   const reqUrl = new URL(req.url);
   const navContext: NavContext = {
     pathname: reqUrl.pathname,
@@ -181,7 +192,8 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
       clientBootstrap.preloadLinks +
       // Initialize __timber_f in <head> so it exists before any streaming
       // chunk scripts arrive in <body>. See flight-scripts.ts, LOCAL-415.
-      (clientJsDisabled ? '' : flightInitScript(nonce)),
+      (clientJsDisabled ? '' : flightInitScript(nonce)) +
+      formStateScript,
     getHeadSegmentScript: clientJsDisabled
       ? undefined
       : () =>
@@ -193,6 +205,7 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
     deferSuspenseFor: deferSuspenseFor > 0 ? deferSuspenseFor : undefined,
     signal: req.signal,
     cookies: getCookiesForSsr(),
+    formState,
     // Stops the Flight injector writing <script> tags once an unhandled RSC
     // error is captured. Without this, React's Flight encoder may write model
     // data for a chunk that already received an error row, causing the

package/src/server/ssr-bridge-types.ts

@@ -50,6 +50,8 @@
  * and `CLAUDE.md` §"RSC and SSR Are Separate Vite Environments".
  */
 
+import type { ReactFormState } from 'react-dom/client';
+
 /**
  * Navigation context passed from the RSC environment to SSR.
  *
@@ -103,6 +105,13 @@ export interface NavContext {
   /** Request cookies as name→value pairs. Used by useCookie() during SSR
    *  to return correct cookie values before hydration. */
   cookies?: Map<string, string>;
+  /**
+   * The form state of the no-JS action this page answers (React's
+   * `decodeFormState`), passed to Fizz so the `useActionState` hook that
+   * submitted renders with the action's result. Absent on every other
+   * render. See design/08-forms-and-actions.md §"No-JS Result Round-Trip".
+   */
+  formState?: ReactFormState;
   /**
    * Lazy thunk that produces the `<script>self.__timber_segments=…</script>`
    * tag. Invoked by the SSR entry AFTER `renderSsrNodeStream` /

package/src/server/ssr-entry.ts

@@ -198,6 +198,7 @@ export async function handleSsr(
       const renderOptions: SsrStreamOptions = {
         bootstrapScriptContent: navContext.bootstrapScriptContent || undefined,
         nonce,
+        formState: navContext.formState,
         deferSuspenseFor: navContext.deferSuspenseFor,
         signal: navContext.signal,
         renderTimeoutMs,

package/src/server/ssr-render.ts

@@ -22,6 +22,7 @@
 
 import type { ReactNode } from 'react';
 import { renderToReadableStream } from 'react-dom/server';
+import type { ReactFormState } from 'react-dom/client';
 
 import { createRenderTimeout, RenderTimeoutError } from './render-timeout.ts';
 import { logRenderError, logStreamingError } from './logger.ts';
@@ -123,6 +124,8 @@ export interface SsrStreamOptions {
   bootstrapScriptContent?: string;
   /** Request CSP nonce — stamped by Fizz on the bootstrap and runtime scripts. */
   nonce?: string;
+  /** A no-JS action's form state, for the `useActionState` hook that submitted. */
+  formState?: ReactFormState;
   deferSuspenseFor?: number;
   signal?: AbortSignal;
   renderTimeoutMs?: number;
@@ -202,6 +205,7 @@ export async function renderSsrNodeStream(
     const { pipe, abort } = _renderToPipeableStream!(element, {
       bootstrapScriptContent: options?.bootstrapScriptContent || undefined,
       nonce: options?.nonce,
+      formState: options?.formState,
 
       onShellReady() {
         if (deferMs && deferMs > 0) {
@@ -321,6 +325,7 @@ async function renderViaReadableStream(
     stream = await renderToReadableStream(element, {
       bootstrapScriptContent: options?.bootstrapScriptContent || undefined,
       nonce: options?.nonce,
+      formState: options?.formState,
       signal: effectiveSignal,
       onError(error: unknown) {
         if (isAbortError(error) || effectiveSignal?.aborted) return;