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

package/src/client/form.tsx

@@ -1,93 +1,21 @@
 /**
  * Client-side form utilities for server actions.
  *
- * Exports a typed `useActionState` that understands the action builder's result shape.
- * Result is typed to:
- *   { data: T } | { validationErrors: Record<string, string[]> } | { serverError: { code, data? } } | null
- *
- * The action builder emits a function that satisfies both the direct call signature
- * and React's `(prevState, formData) => Promise<State>` contract.
+ * Forms use React's own `useActionState`: an action built with
+ * `createActionClient` already has the `(prevState, payload)` signature it
+ * calls, and the result is typed from it. `parseFormErrors` reads the errors
+ * out of that result.
  *
  * See design/08-forms-and-actions.md §"Client-Side Form Mechanics"
  */
 
-import { useActionState as reactUseActionState, useTransition } from 'react';
+import { useTransition } from 'react';
 import type {
   ActionFn,
   ActionResult,
   InputHint,
   ValidationErrors,
 } from '../server/action-client.ts';
-import type { FormFlashData } from '../server/form-flash.ts';
-
-// ─── Types ───────────────────────────────────────────────────────────────
-
-/**
- * The action function type accepted by useActionState.
- * Must satisfy React's (prevState, formData) => Promise<State> contract.
- */
-export type UseActionStateFn<TData> = (
-  prevState: ActionResult<TData> | null,
-  formData: FormData
-) => Promise<ActionResult<TData>>;
-
-/**
- * Return type of useActionState.
- * [result, formAction, isPending, errors]
- * The 4th element is auto-derived from result via useFormErrors logic.
- */
-export type UseActionStateReturn<TData> = [
-  result: ActionResult<TData> | null,
-  formAction: (formData: FormData) => void,
-  isPending: boolean,
-  errors: FormErrorsResult,
-];
-
-// ─── useActionState ──────────────────────────────────────────────────────
-
-/**
- * Typed wrapper around React 19's `useActionState` that understands
- * the timber action builder's result shape.
- *
- * @param action - A server action created with createActionClient or a raw 'use server' function.
- * @param initialState - Initial state, typically `null`. Pass `getFormFlash()` for no-JS
- *   progressive enhancement — the flash seeds the initial state so the form has a
- *   single source of truth for both with-JS and no-JS paths.
- * @param permalink - Optional permalink for progressive enhancement (no-JS fallback URL).
- *
- * @example
- * ```tsx
- * 'use client'
- * import { useActionState } from '@timber-js/app/client'
- * import { createTodo } from './actions'
- *
- * export function NewTodoForm({ flash }) {
- *   const [result, action, isPending] = useActionState(createTodo, flash)
- *   return (
- *     <form action={action}>
- *       <input name="title" />
- *       {result?.validationErrors?.title && <p>{result.validationErrors.title}</p>}
- *       <button disabled={isPending}>Add</button>
- *     </form>
- *   )
- * }
- * ```
- */
-export function useActionState<TData>(
-  action: UseActionStateFn<TData>,
-  initialState: ActionResult<TData> | FormFlashData | null,
-  permalink?: string
-): UseActionStateReturn<TData> {
-  // FormFlashData is structurally compatible with ActionResult at runtime —
-  // the cast satisfies React's generic inference which would otherwise widen TData.
-  const [result, formAction, isPending] = reactUseActionState(
-    action,
-    initialState as ActionResult<TData> | null,
-    permalink
-  );
-  const errors = deriveFormErrors(result);
-  return [result, formAction, isPending, errors];
-}
 
 // ─── useFormAction ───────────────────────────────────────────────────────
 
@@ -114,12 +42,20 @@ export function useFormAction<TData = unknown, TInput = unknown>(
   const [isPending, startTransition] = useTransition();
 
   const execute = (input?: InputHint<TInput>): Promise<ActionResult<TData>> => {
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
       startTransition(async () => {
-        const result = await (action as (input: InputHint<TInput>) => Promise<ActionResult<TData>>)(
-          input as InputHint<TInput>
-        );
-        resolve(result);
+        // A raw server function that throws rejects (TIM-1570). The caller
+        // awaiting `execute` gets that rejection; without the catch the
+        // promise would never settle.
+        try {
+          resolve(
+            await (action as (input: InputHint<TInput>) => Promise<ActionResult<TData>>)(
+              input as InputHint<TInput>
+            )
+          );
+        } catch (error) {
+          reject(error);
+        }
       });
     });
   };
@@ -129,7 +65,7 @@ export function useFormAction<TData = unknown, TInput = unknown>(
 
 // ─── Form error extraction ────────────────────────────────────────────────
 
-/** Return type of the errors element in useActionState. */
+/** What `parseFormErrors` reads out of an action result. */
 export interface FormErrorsResult {
   /** Per-field validation errors keyed by field name. */
   fieldErrors: Record<string, string[]>;
@@ -144,18 +80,19 @@ export interface FormErrorsResult {
 }
 
 /**
- * Derive FormErrorsResult from an action result.
- * Used internally by useActionState 4th tuple element.
- * @internal — exported for test access only.
+ * Read the errors out of an action result — the state `useActionState`
+ * returns. `_root` validation errors are form-level; every other key is a
+ * field.
+ *
+ * @example
+ * ```tsx
+ * const [result, action, isPending] = useActionState(createTodo, null)
+ * const errors = parseFormErrors(result)
+ * errors.getFieldError('title') // first message for the field, or null
+ * ```
  */
-export function deriveFormErrors<TData>(
-  result:
-    | ActionResult<TData>
-    | {
-        validationErrors?: ValidationErrors;
-        serverError?: { code: string; data?: Record<string, unknown> };
-      }
-    | null
+export function parseFormErrors<TData>(
+  result: ActionResult<TData> | null | undefined
 ): FormErrorsResult {
   const empty: FormErrorsResult = {
     fieldErrors: {},
@@ -167,10 +104,8 @@ export function deriveFormErrors<TData>(
 
   if (!result) return empty;
 
-  const validationErrors = result.validationErrors as ValidationErrors | undefined;
-  const serverError = result.serverError as
-    | { code: string; data?: Record<string, unknown> }
-    | undefined;
+  const validationErrors: ValidationErrors | undefined = result.validationErrors;
+  const serverError = result.serverError;
 
   if (!validationErrors && !serverError) return empty;
 

package/src/client/index.ts

@@ -75,8 +75,9 @@ export {
 } from './use-selected-layout-segment.ts';
 
 // Forms
-export { useActionState, useFormAction } from './form.tsx';
-export type { UseActionStateFn, UseActionStateReturn, FormErrorsResult } from './form.tsx';
+export { parseFormErrors, useFormAction } from './form.tsx';
+export { useFormField } from './use-form-field.ts';
+export type { FormErrorsResult } from './form.tsx';
 
 // Params. Called with no argument this returns the untyped accumulated params;
 // pass the route's SEGMENT_PATH (from its generated `./$segment` module) to get

package/src/client/navigation-api.ts

@@ -1,15 +1,14 @@
 /**
  * Navigation API integration — progressive enhancement for client navigation.
  *
- * When the Navigation API (`window.navigation`) is available, this module
- * provides an intercept-based navigation model that replaces the separate
- * popstate + click handler approach with a single navigate event listener.
- *
- * Key benefits:
- * - Intercepts ALL navigations (link clicks, form submissions, back/forward)
- * - Built-in AbortSignal per navigation (auto-aborts in-flight fetches)
- * - Per-entry state via NavigationHistoryEntry.getState()
- * - navigation.transition for progress tracking
+ * When the Navigation API (`window.navigation`) is available, a single
+ * navigate event listener replaces the popstate handler and routes plain
+ * `<a>` clicks through the router:
+ * - Traversals are intercepted, with the event's AbortSignal linked to the
+ *   router's fetch
+ * - Cross-document push/replace navigations are cancelled and re-run through
+ *   the router, so the URL commits with the tree (never at intercept time)
+ * - Per-entry scroll state via NavigationHistoryEntry.getState()
  *
  * When unavailable, all functions are no-ops and the History API fallback
  * in browser-entry.ts handles navigation.
@@ -67,20 +66,18 @@ export function traverseDirection(
 /**
  * Callbacks for the Navigation API event handler.
  *
- * When the Navigation API intercepts a navigation, it delegates to these
- * callbacks which run the RSC fetch + render pipeline.
+ * Push/replace navigations are handed to the router, which commits the URL
+ * with the tree. Traversals are intercepted and replayed or fetched.
  */
 export interface NavigationApiCallbacks {
   /**
-   * Handle a push/replace navigation intercepted by the Navigation API.
-   * This covers both Link <a> clicks (user-initiated) and external
-   * navigations (plain <a> tags, programmatic).
-   * The Navigation API handles the URL update via event.intercept().
+   * Handle a cross-document push/replace navigation the router did not start
+   * itself: a plain `<a>`, `navigation.navigate()`, or `location.assign()`.
+   * The handler has already cancelled the browser's navigation, so the
+   * address bar has not moved; the router moves it when the destination
+   * commits, as it does for its own navigations.
    */
-  onExternalNavigate: (
-    url: string,
-    options: { replace: boolean; signal: AbortSignal; scroll?: boolean; departingUrl?: string }
-  ) => Promise<void>;
+  onExternalNavigate: (url: string, options: { replace: boolean }) => Promise<void>;
 
   /**
    * Handle a traversal (back/forward button). The Navigation API intercepts
@@ -104,58 +101,15 @@ export interface NavigationApiCallbacks {
 }
 
 /**
- * Controller returned by setupNavigationApi. Provides methods to
- * coordinate between the router and the navigate event listener.
+ * Controller returned by setupNavigationApi.
  */
 export interface NavigationApiController {
-  /**
-   * Set the router-navigating flag. When `true`, the next navigate event
-   * (from pushState/replaceState) is recognized as router-initiated. The
-   * handler still intercepts it — but ties the browser's native loading
-   * state to a deferred promise instead of running the RSC pipeline again.
-   *
-   * This means `navigation.transition` is active for the full duration of
-   * every router-initiated navigation, giving the browser a native loading
-   * indicator (tab spinner, address bar) aligned with the TopLoader.
-   *
-   * Must be called synchronously around pushState/replaceState:
-   *   controller.setRouterNavigating(true);
-   *   history.pushState(...);        // navigate event fires, intercepted
-   *   controller.setRouterNavigating(false);  // flag off, deferred stays open
-   */
-  setRouterNavigating: (value: boolean) => void;
-
-  /**
-   * Resolve the deferred promise created by setRouterNavigating(true),
-   * clearing the browser's native loading state. Call this when the
-   * navigation fully completes — the same finally block in router.navigate
-   * that clears the router's pending store.
-   */
-  completeRouterNavigation: () => void;
-
-  /**
-   * Initiate a navigation via the Navigation API (`navigation.navigate()`).
-   * Unlike `history.pushState()`, this fires the navigate event BEFORE
-   * committing the URL — allowing Chrome to show its native loading
-   * indicator while the intercept handler runs.
-   *
-   * Must be called with setRouterNavigating(true) active so the handler
-   * recognizes it as router-initiated and uses the deferred promise.
-   */
-  navigate: (url: string, replace: boolean) => void;
-
   /**
    * Save scroll position into the current navigation entry's state.
    * Uses navigation.updateCurrentEntry() for per-entry scroll storage.
    */
   saveScrollPosition: (scrollY: number) => void;
 
-  /**
-   * Check if the Navigation API has an active transition.
-   * Returns the transition object if available, null otherwise.
-   */
-  hasActiveTransition: () => boolean;
-
   /** Remove the navigate event listener. */
   cleanup: () => void;
 }
@@ -163,24 +117,19 @@ export interface NavigationApiController {
 /**
  * Set up the Navigation API navigate event listener.
  *
- * Intercepts same-origin navigations and delegates to the provided callbacks.
- * Router-initiated navigations (pushState from router.navigate) are detected
- * via a synchronous flag and NOT intercepted — the router already handles them.
- *
- * Returns a controller for coordinating with the router.
+ * The address bar moves only when the destination's tree commits
+ * (design/19-client-navigation.md §"prepareNavigation"). `event.intercept()`
+ * would commit the URL as soon as it is called, a full round trip before the
+ * page that belongs to it, so push/replace navigations are never
+ * intercepted: the router's own navigations never reach here as
+ * cross-document events (Link cancels the click and the router commits with
+ * `pushState`), and the rest are cancelled and re-run through the router.
+ * Only traversals — which the browser has already moved the URL for in every
+ * browser — and shallow updates are intercepted.
  */
 export function setupNavigationApi(callbacks: NavigationApiCallbacks): NavigationApiController {
   const nav = getNavigationApi()!;
 
-  let routerNavigating = false;
-
-  // Deferred promise for router-initiated navigations. Created when
-  // setRouterNavigating(true) is called, resolved by completeRouterNavigation().
-  // The navigate event handler intercepts with this promise so the browser's
-  // native loading state (tab spinner) stays active until the navigation
-  // completes — the same lifecycle the TopLoader is driven by.
-  let routerNavDeferred: { promise: Promise<void>; resolve: () => void } | null = null;
-
   function handleNavigate(event: NavigateEvent): void {
     // Skip non-interceptable navigations (cross-origin, etc.)
     if (!event.canIntercept) return;
@@ -234,20 +183,6 @@ export function setupNavigationApi(callbacks: NavigationApiCallbacks): Navigatio
     const destUrl = new URL(event.destination.url);
     if (destUrl.origin !== location.origin) return;
 
-    // Router-initiated navigation (Link click → router.navigate → pushState).
-    // The router is already running the RSC pipeline — don't run it again.
-    // Instead, intercept with the deferred promise so the browser's native
-    // loading state tracks the navigation's full lifecycle. This aligns the
-    // tab spinner / address bar indicator with the TopLoader.
-    if (routerNavigating && routerNavDeferred) {
-      event.intercept({
-        scroll: 'manual',
-        focusReset: 'manual',
-        handler: () => routerNavDeferred!.promise,
-      });
-      return;
-    }
-
     // Skip reload navigations — let the browser handle full page reload
     if (event.navigationType === 'reload') return;
 
@@ -274,90 +209,33 @@ export function setupNavigationApi(callbacks: NavigationApiCallbacks): Navigatio
           await callbacks.onTraverse(url, scrollY, event.signal, direction);
         },
       });
-    } else if (event.navigationType === 'push' || event.navigationType === 'replace') {
-      // Push/replace — a Link <a> click or an external navigation
-      // (plain <a> tag, programmatic).
-
-      // Save the departing page's scroll position BEFORE event.intercept()
-      // commits the URL change. Once intercept() is called, currentEntry
-      // switches to the new (destination) entry — any updateCurrentEntry()
-      // call after that would save to the wrong entry.
-      // See: router.navigate() also calls saveNavigationEntryScroll(), but
-      // for Navigation API <a> click navigations (where Link does NOT call
-      // router.navigate directly), the router's save runs inside the
-      // intercept handler — too late, currentEntry has already switched.
-      try {
-        const currentState = (nav.currentEntry?.getState() ?? {}) as Record<string, unknown>;
-        nav.updateCurrentEntry({
-          state: { ...currentState, timber: true, scrollY: window.scrollY },
-        });
-      } catch {
-        // Ignore — entry may be disposed
-      }
-
-      // Capture the departing URL BEFORE event.intercept() commits the
-      // destination. Once intercept() is called, currentEntry switches and
-      // getCurrentUrl() returns the destination (TIM-1232).
-      const departingUrl = nav.currentEntry?.url
-        ? new URL(nav.currentEntry.url).pathname +
-          stripRscCacheKey(new URL(nav.currentEntry.url).search)
-        : undefined;
-
-      event.intercept({
-        scroll: 'manual',
-        focusReset: 'manual',
-        async handler() {
-          await callbacks.onExternalNavigate(url + destUrl.hash, {
-            replace: event.navigationType === 'replace',
-            signal: event.signal,
-            scroll: undefined,
-            departingUrl,
-          });
-        },
-      });
+      return;
     }
+
+    // A same-document push/replace is `history.pushState()` /
+    // `replaceState()`: the router's own commit, or app code (nuqs,
+    // replaceUrl, a third-party library). The URL is already the
+    // destination and the History API patch in router-init syncs the search
+    // params, exactly as in browsers without the Navigation API.
+    if (event.destination.sameDocument) return;
+
+    // A cross-document push/replace the router did not start: a plain
+    // `<a>`, `navigation.navigate()`, `location.assign()`. Cancel it and
+    // re-run it through the router, which commits the URL with the tree.
+    // A navigation the browser will not let us cancel stays a document load.
+    // Cancelling rejects a `navigation.navigate()` caller's `committed` and
+    // `finished` with AbortError and drops its `state`; the router's own API
+    // is `useRouter()` (design/19 §"The address bar moves on commit").
+    if (!event.cancelable) return;
+    event.preventDefault();
+    void callbacks.onExternalNavigate(url + destUrl.hash, {
+      replace: event.navigationType === 'replace',
+    });
   }
 
   nav.addEventListener('navigate', handleNavigate);
 
   return {
-    setRouterNavigating(value: boolean): void {
-      routerNavigating = value;
-      if (value) {
-        // Create a new deferred promise. The navigate event handler will
-        // intercept and tie the browser's loading state to this promise.
-        let resolve!: () => void;
-        const promise = new Promise<void>((r) => {
-          resolve = r;
-        });
-        routerNavDeferred = { promise, resolve };
-      } else {
-        // Flag off — but DON'T resolve the deferred here. The navigation
-        // is still in flight (RSC fetch + render). completeRouterNavigation()
-        // resolves it when the navigation fully completes.
-        routerNavigating = false;
-      }
-    },
-
-    completeRouterNavigation(): void {
-      if (routerNavDeferred) {
-        routerNavDeferred.resolve();
-        routerNavDeferred = null;
-      }
-    },
-
-    navigate(url: string, replace: boolean): void {
-      // Use navigation.navigate() instead of history.pushState().
-      // This fires the navigate event BEFORE committing the URL,
-      // which lets Chrome show its native loading indicator while
-      // the intercept handler (deferred promise) is pending.
-      // history.pushState() commits the URL synchronously, so Chrome
-      // sees the navigation as already complete and skips the indicator.
-      nav.navigate(url, {
-        history: replace ? 'replace' : 'push',
-      });
-    },
-
     saveScrollPosition(scrollY: number): void {
       try {
         const currentState = (nav.currentEntry?.getState() ?? {}) as Record<string, unknown>;
@@ -369,10 +247,6 @@ export function setupNavigationApi(callbacks: NavigationApiCallbacks): Navigatio
       }
     },
 
-    hasActiveTransition(): boolean {
-      return nav.transition != null;
-    },
-
     cleanup(): void {
       nav.removeEventListener('navigate', handleNavigate);
     },

package/src/client/navigation-transition.ts

@@ -47,7 +47,9 @@
  *
  * Nothing here may reopen an action scope: no `startTransition` callback in
  * this path may return a thenable, and no caller may invoke this from inside
- * a React action scope. That is a rule about `startTransition`, not about
+ * a React action scope — except one that settles that action at `onHandOff`,
+ * which commits the action and the tree together on purpose (a server action
+ * redirect, TIM-1573). That is a rule about `startTransition`, not about
  * `perform` — `perform` is async by contract and is awaited OUTSIDE any
  * transition scope, which is exactly why it is safe.
  *
@@ -233,6 +235,13 @@ export function createRenderOwner(kind: 'navigation' | 'revalidation'): RenderOw
  * detected via `owner.outcome` (sync) and `owner.displaced` (async).
  * No module-level state; no globalThis singleton.
  *
+ * `onHandOff` runs synchronously right after `render` has scheduled the
+ * tree, before React can commit it. A caller inside a React action scope may
+ * settle that action here (and only here): the render is already entangled
+ * with the scope, so settling commits the action and this tree together,
+ * where settling earlier commits the action alone and settling on the commit
+ * deadlocks. The server action redirect is that caller (TIM-1573).
+ *
  * Used for: navigate(), refresh(), popstate with fetch.
  */
 export function navigateTransition(
@@ -240,7 +249,8 @@ export function navigateTransition(
   perform: () => Promise<TransitionResult>,
   render: NavigationRender,
   types: readonly string[],
-  onCommit?: (outcome: CommitOutcome) => void
+  onCommit?: (outcome: CommitOutcome) => void,
+  onHandOff?: () => void
 ): Promise<void> {
   const superseded = () => new DOMException('Navigation superseded', 'AbortError');
 
@@ -284,12 +294,13 @@ export function navigateTransition(
         },
         types
       );
+      onHandOff?.();
       // React may commit the tree before this settles — that is the point:
       // the destination reveals as React is able to render it
       // rather than waiting for the whole Flight stream. The await is here so
       // the promise this function hands back still means "the payload is
-      // decoded", which is what the router's scroll restoration, the
-      // Navigation API deferred and `<Link>`'s `isPending` are timed against.
+      // decoded", which is what the router's scroll restoration and
+      // `<Link>`'s `isPending` are timed against.
       //
       // ...unless this navigation loses first, in which case it stops waiting
       // on a stream that is no longer its business.

package/src/client/router-effects.ts

@@ -150,9 +150,11 @@ export interface NavigationRecoveryDeps {
    * Replace the current entry with `url` — the router's own `navigate()`,
    * rendering with `types`: the view transition types of the render the
    * redirect interrupted, so a redirected Back still animates as Back and a
-   * link's own `transitionTypes` survive the hop (TIM-1471).
+   * link's own `transitionTypes` survive the hop (TIM-1471). `onHandOff`
+   * survives it too: a server action redirect waits for the tree that is
+   * finally handed to React, which is the redirected one (TIM-1573).
    */
-  navigate: (url: string, types: readonly string[]) => Promise<void>;
+  navigate: (url: string, types: readonly string[], onHandOff?: () => void) => Promise<void>;
 }
 
 /**
@@ -188,13 +190,15 @@ export function createNavigationRecovery({
     url: string,
     fromUrl: string,
     /** The view transition types of the render that failed. */
-    types: readonly string[]
+    types: readonly string[],
+    /** The failed navigation's `NavigationOptions.onHandOff`, for the hop. */
+    onHandOff?: () => void
   ): Promise<boolean> {
     if (error instanceof RedirectError) {
       // Same ownership rule as leaving the SPA: a superseded navigation must
       // not steer the document to the destination it was abandoned for.
       if (currentOwner() !== owner) return true;
-      await navigate(error.redirectUrl, types);
+      await navigate(error.redirectUrl, types, onHandOff);
       return true;
     }
     // A server error, a non-RSC response and a version skew all end the same