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

package/src/client/router-lifecycle.ts

@@ -35,23 +35,13 @@ export interface NavigationEpoch {
   readonly idle: boolean;
 }
 
-/** The subset of `RouterDeps` the navigation lifecycle needs. */
-export interface NavigationLifecycleDeps {
-  /**
-   * Signal that a router-initiated navigation has completed. Resolves the
-   * deferred promise that ties the browser's native loading state to the
-   * navigation lifecycle.
-   */
-  completeRouterNavigation?: () => void;
-}
-
 export interface NavigationLifecycle {
   /** The owner that holds the router right now, or null when idle. */
   currentOwner: () => RenderOwner | null;
   /**
    * Take ownership of the router, superseding whatever held it. Returns
    * a fresh `RenderOwner` for the new navigation. See the implementation
-   * for the three parts of superseding.
+   * for the two parts of superseding.
    */
   createNavOwner: (
     kind: 'navigation' | 'revalidation',
@@ -99,6 +89,21 @@ export interface NavigationLifecycle {
    * replaces an earlier one (TIM-1474).
    */
   runWhenIdle: (task: () => void) => void;
+  /**
+   * Subscribe to the router becoming idle (pending false AND commit done):
+   * `listener` runs on every such transition until unsubscribed. Unlike
+   * `runWhenIdle`, any number of listeners may wait.
+   */
+  onIdle: (listener: () => void) => () => void;
+  /**
+   * Subscribe to React committing a navigation's tree — the tree on screen
+   * has changed, whether or not its stream has finished decoding (so the
+   * router may still be pending). Runs on every commit until unsubscribed,
+   * with the committing navigation's `epoch().seq`: a tree handed to React
+   * before a later navigation started can still commit after it, and the
+   * sequence says which one it was.
+   */
+  onTreeCommit: (listener: (seq: number) => void) => () => void;
   /**
    * Settle any handed-off-but-uncommitted owners as superseded, then flush
    * the idle task if the router is now idle. Called by `syncShallowSearch`
@@ -119,7 +124,7 @@ function isAbortError(error: unknown): boolean {
   return false;
 }
 
-export function createNavigationLifecycle(deps: NavigationLifecycleDeps): NavigationLifecycle {
+export function createNavigationLifecycle(): NavigationLifecycle {
   // The single ownership slot. One navigation at a time.
   let current: RenderOwner | null = null;
 
@@ -135,6 +140,10 @@ export function createNavigationLifecycle(deps: NavigationLifecycleDeps): Naviga
 
   let navigationSeq = 0;
   let idleTask: (() => void) | null = null;
+  const idleListeners = new Set<() => void>();
+  const treeCommitListeners = new Set<(seq: number) => void>();
+  // The navigationSeq each owner ran under, for tree-commit listeners.
+  const ownerSeq = new WeakMap<RenderOwner, number>();
 
   /**
    * Whether a handed-off tree has not yet committed. Derived from the slot:
@@ -167,17 +176,13 @@ export function createNavigationLifecycle(deps: NavigationLifecycleDeps): Naviga
    * in-flight navigation. Optionally links to an external signal (e.g.,
    * from the Navigation API's NavigateEvent.signal).
    *
-   * Superseding is one operation with three parts:
+   * Superseding is one operation with two parts:
    * 1. Abort the previous navigation's fetch — UNLESS its tree is the one on
    *    screen, in which case tearing the stream down would error the page the
    *    user is currently looking at. See `RenderOwner.handedOff`.
    * 2. Settle the previous owner as 'superseded' so its transition detects
    *    it lost and never hands a stale tree to React. This replaces both
    *    `supersedeNavigationTransitions()` and the transition counter bump.
-   * 3. Resolve its Navigation API deferred — the superseded navigation's
-   *    finally block is staleness-guarded (see TIM-1034) and no longer
-   *    cleans up after itself, so the browser's native loading state for
-   *    the dead navigation is cleared here.
    */
   function createNavOwner(
     kind: 'navigation' | 'revalidation',
@@ -186,7 +191,6 @@ export function createNavigationLifecycle(deps: NavigationLifecycleDeps): Naviga
     if (current) {
       abortUnlessHandedOff(current);
       current.settle('superseded');
-      deps.completeRouterNavigation?.();
     }
     // A handed-off owner whose runNavigation has already finished but whose
     // tree hasn't committed yet. Settle it so its onCommit fires.
@@ -196,6 +200,7 @@ export function createNavigationLifecycle(deps: NavigationLifecycleDeps): Naviga
     }
     navigationSeq += 1;
     const owner = createRenderOwner(kind);
+    ownerSeq.set(owner, navigationSeq);
     current = owner;
 
     // If an external signal is provided (e.g., Navigation API),
@@ -264,14 +269,16 @@ export function createNavigationLifecycle(deps: NavigationLifecycleDeps): Naviga
       if (current === owner) {
         current = null;
         setPending(false);
-        deps.completeRouterNavigation?.();
         flushIdleTask();
       }
     }
   }
 
+  // Every place the router may have just become idle calls this.
   function flushIdleTask(): void {
-    if (routerPhase.phase !== 'idle' || hasUncommittedNav() || !idleTask) return;
+    if (routerPhase.phase !== 'idle' || hasUncommittedNav()) return;
+    for (const listener of [...idleListeners]) listener();
+    if (!idleTask) return;
     const task = idleTask;
     idleTask = null;
     task();
@@ -307,10 +314,13 @@ export function createNavigationLifecycle(deps: NavigationLifecycleDeps): Naviga
       if (pendingCommit === owner) {
         pendingCommit = null;
       }
+      const seq = ownerSeq.get(owner) ?? navigationSeq;
+      for (const listener of [...treeCommitListeners]) listener(seq);
       flushIdleTask();
     },
 
     placeRevalidationOwner(owner: RenderOwner): void {
+      ownerSeq.set(owner, navigationSeq);
       current = owner;
     },
 
@@ -340,6 +350,16 @@ export function createNavigationLifecycle(deps: NavigationLifecycleDeps): Naviga
       idleTask = task;
     },
 
+    onIdle(listener) {
+      idleListeners.add(listener);
+      return () => idleListeners.delete(listener);
+    },
+
+    onTreeCommit(listener) {
+      treeCommitListeners.add(listener);
+      return () => treeCommitListeners.delete(listener);
+    },
+
     settleHandoffs(): void {
       if (pendingCommit) {
         pendingCommit.settle('superseded');

package/src/client/router-pipeline.ts

@@ -55,7 +55,6 @@ export interface NavigationFetchOptions {
   replace: boolean;
   commitUrl?: string;
   signal?: AbortSignal;
-  skipHistory?: boolean;
   departingUrl?: string;
 }
 
@@ -85,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>;
 }
 
@@ -187,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
@@ -261,7 +263,8 @@ export function createNavigationPipeline({
           commit: commitAndForget(result.commit),
         };
       },
-      onCommit
+      onCommit,
+      onHandOff
     );
   }
 
@@ -388,9 +391,9 @@ export function createNavigationPipeline({
       result = await fetchRscPayload(url, deps, freshStateTree, currentUrl, options.signal);
     }
 
-    // Update the browser history — skip when the Navigation API has already
-    // updated the URL via event.intercept() (external navigations).
-    // The committed URL keeps the #fragment (commitUrl) even though the
+    // Update the browser history. This is the only place a push/replace
+    // navigation moves the address bar, with or without the Navigation API
+    // (its listener leaves same-document pushState alone). The committed URL keeps the #fragment (commitUrl) even though the
     // fetch/history-stack URL is hash-less (TIM-1035).
     //
     // Deferred with the rest of the commit: the address bar is navigation
@@ -400,17 +403,12 @@ export function createNavigationPipeline({
     // response that won the race anyway re-pushed the abandoned URL
     // (TIM-1022's failure mode, made unconditional by TIM-1301).
     const commitHistoryUrl = (): void => {
-      if (options.skipHistory) return;
       const commitUrl = options.commitUrl ?? url;
-      // Set the router-navigating flag so the Navigation API's navigate
-      // listener doesn't double-intercept this pushState/replaceState.
-      deps.setRouterNavigating?.(true);
       if (options.replace) {
         deps.replaceState({ timber: true, scrollY: 0 }, '', commitUrl);
       } else {
         deps.pushState({ timber: true, scrollY: 0 }, '', commitUrl);
       }
-      deps.setRouterNavigating?.(false);
     };
 
     const params = await result.params;

package/src/client/router-types.ts

@@ -90,24 +90,14 @@ export interface NavigationOptions {
    */
   onCommit?: (outcome: CommitOutcome) => void;
   /**
-   * @internal AbortSignal from the Navigation API's NavigateEvent.
-   * When provided, the signal is linked to the router's per-navigation
-   * AbortController so in-flight RSC fetches are cancelled when a new
-   * navigation starts.
+   * @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).
    */
-  _signal?: AbortSignal;
-  /**
-   * @internal Skip pushState/replaceState — the Navigation API has already
-   * updated the URL via event.intercept(). Used for external navigations
-   * intercepted by the navigate event handler.
-   */
-  _skipHistory?: boolean;
-  /**
-   * @internal The URL the user is navigating FROM, captured before the
-   * Navigation API commits the destination. Sent as X-Timber-URL for
-   * slot skip comparison on the server (TIM-1232).
-   */
-  _departingUrl?: string;
+  onHandOff?: () => void;
 }
 
 /**
@@ -174,37 +164,17 @@ 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>;
 
-  /**
-   * Whether the Navigation API is active and handling traversals.
-   * When true, the popstate handler is a no-op — the Navigation API's
-   * navigate event covers back/forward button presses.
-   */
-  navigationApiActive?: boolean;
-
-  /**
-   * Called around pushState/replaceState to set a flag that prevents
-   * the Navigation API's navigate listener from double-handling
-   * router-initiated navigations.
-   */
-  setRouterNavigating?: (value: boolean) => void;
-
   /**
    * Save scroll position via the Navigation API's per-entry state.
    * When provided, used instead of history.replaceState for scroll storage.
    */
   saveNavigationEntryScroll?: (scrollY: number) => void;
 
-  /**
-   * Signal that a router-initiated navigation has completed. Resolves the
-   * deferred promise that ties the browser's native loading state to the
-   * navigation lifecycle. Called in the finally block of navigate/refresh,
-   * the same place `setPending(false)` clears the TopLoader.
-   */
-  completeRouterNavigation?: () => void;
-
   /**
    * Get the current unwrapped RSC payload element. Used for partial
    * navigation: the router re-wraps the same element with new
@@ -212,14 +182,6 @@ export interface RouterDeps {
    */
   _getCurrentPayload?: () => unknown;
 
-  /**
-   * Initiate a navigation via the Navigation API (`navigation.navigate()`).
-   * Fires the navigate event BEFORE committing the URL, allowing Chrome
-   * to show its native loading indicator. Falls back to pushState when
-   * unavailable.
-   */
-  navigationNavigate?: (url: string, replace: boolean) => void;
-
   /**
    * Scroll the element matching a URL #fragment into view. Returns true
    * when a matching element was found and scrolled. When absent or false,
@@ -301,6 +263,20 @@ export interface RouterInstance {
    * router-idle are true (TIM-1474).
    */
   runWhenIdle(task: () => void): void;
+  /**
+   * Subscribe to the router becoming idle — no navigation pending and no
+   * handed-off tree waiting to commit. Runs on every such transition until
+   * the returned function unsubscribes; any number of listeners may wait.
+   */
+  onIdle(listener: () => void): () => void;
+  /**
+   * Subscribe to React committing a navigation's tree: the page on screen
+   * has changed, even if its stream is still decoding and the router is
+   * still pending. Runs on every commit until unsubscribed, with the
+   * committing navigation's `epoch().seq` — a tree handed to React before a
+   * later navigation started can still commit after it.
+   */
+  onTreeCommit(listener: (seq: number) => void): () => void;
   /**
    * Settle any handed-off-but-uncommitted owners as superseded, then flush
    * idle tasks. Called by `syncShallowSearch` when a shallow URL update

package/src/client/router.ts

@@ -59,7 +59,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
   // Ownership of the router: who is navigating, whose fetch may be cut, and
   // the pending store TopLoader subscribes to. See router-lifecycle.ts.
-  const lifecycle = createNavigationLifecycle(deps);
+  const lifecycle = createNavigationLifecycle();
   const {
     currentOwner,
     createNavOwner,
@@ -102,14 +102,13 @@ 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> {
     const scroll = options.scroll !== false;
     const replace = options.replace === true;
-    const externalSignal = options._signal as AbortSignal | undefined;
-    const skipHistory = options._skipHistory === true;
     // A push, a replace, and a server action redirect all move the user
     // forward; the caller's own types ride beside it. A redirect this router
     // follows keeps the types of the render it interrupted instead.
@@ -127,11 +126,9 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     const hash = hashIndex === -1 ? '' : url.slice(hashIndex);
     const fetchUrl = hashIndex === -1 ? url : url.slice(0, hashIndex);
 
-    // Use the pre-intercept departing URL when the Navigation API has already
-    // committed the destination (_departingUrl from navigation-api.ts). Otherwise
-    // capture it now — getCurrentUrl() is still the departing URL at this point
-    // for non-Navigation-API navigations (TIM-1232).
-    const departingUrl = options._departingUrl ?? deps.getCurrentUrl();
+    // The address bar moves only when the destination commits, so it still
+    // names the page being left (TIM-1232).
+    const departingUrl = deps.getCurrentUrl();
 
     // Capture the departing page's scroll position for scroll={false} preservation.
     const currentScrollY = deps.getScrollY();
@@ -155,57 +152,51 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       await leaveSpaSuperseding(url, departingUrl);
     }
 
-    let effectiveSkipHistory = skipHistory;
-
-    await runNavigation(
-      url,
-      async (owner) => {
-        // When Navigation API is active, initiate the navigation via
-        // navigation.navigate() BEFORE the fetch. Must happen after
-        // createNavOwner supersedes the previous navigation (done by
-        // runNavigation) so the old deferred is resolved first.
-        if (!effectiveSkipHistory && deps.navigationNavigate) {
-          deps.setRouterNavigating?.(true);
-          deps.navigationNavigate(url, replace);
-          deps.setRouterNavigating?.(false);
-          effectiveSkipHistory = true;
+    await runNavigation(url, async (owner) => {
+      try {
+        await renderViaTransition(
+          fetchUrl,
+          owner,
+          types,
+          () =>
+            performNavigationFetch(fetchUrl, {
+              replace,
+              commitUrl: url,
+              signal: owner.fetchAbort.signal,
+              departingUrl,
+            }),
+          options.onCommit,
+          options.onHandOff
+        );
+
+        // Scroll-to-top on forward navigation, scroll to the #fragment target
+        // when the URL has one, or restore captured position for scroll={false}.
+        if (scroll && hash) {
+          scrollToHashAfterPaint(hash);
+        } else {
+          restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
         }
-
-        try {
-          await renderViaTransition(
-            fetchUrl,
+      } catch (error) {
+        // `url` is where the user asked to go and `departingUrl` is where
+        // they were: a failure here finishes the click as a full document
+        // 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,
-            () =>
-              performNavigationFetch(fetchUrl, {
-                replace,
-                commitUrl: url,
-                signal: owner.fetchAbort.signal,
-                skipHistory: effectiveSkipHistory,
-                departingUrl,
-              }),
-            options.onCommit
-          );
-
-          // Scroll-to-top on forward navigation, scroll to the #fragment target
-          // when the URL has one, or restore captured position for scroll={false}.
-          if (scroll && hash) {
-            scrollToHashAfterPaint(hash);
-          } else {
-            restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
-          }
-        } catch (error) {
-          // `url` is where the user asked to go and `departingUrl` is where
-          // they were: a failure here finishes the click as a full document
-          // 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;
-          throw error;
+            options.onHandOff
+          )
+        ) {
+          return;
         }
-      },
-      externalSignal
-    );
+        throw error;
+      }
+    });
   }
 
   /**
@@ -523,6 +514,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       return outcome === 'committed';
     },
     runWhenIdle: (task: () => void) => lifecycle.runWhenIdle(task),
+    onIdle: (listener) => lifecycle.onIdle(listener),
+    onTreeCommit: (listener) => lifecycle.onTreeCommit(listener),
     settleHandoffs: () => lifecycle.settleHandoffs(),
     suppressSegmentReuse(): void {
       // TIM-1466: uses invalidateReuse() instead of clear() to preserve

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/plugins/shims.ts

@@ -103,8 +103,6 @@ export const SERVER_STUB_EXPORTS: readonly string[] = [
   // form-data
   'coerce',
   'parseFormData',
-  // form-flash
-  'getFormFlash',
   // revalidation
   'revalidatePath',
   'revalidateTag',

package/src/rsc-runtime/rsc.ts

@@ -16,6 +16,9 @@ export {
   loadServerAction,
   decodeReply,
   decodeAction,
+  // No-JS action result → the `useActionState` hook that submitted it
+  // (server/action-handler.ts), as Next.js does in its action handler.
+  decodeFormState,
   encryptActionBoundArgs,
   decryptActionBoundArgs,
   // Flight client running INSIDE the RSC environment — decodes a cached

package/src/rsc-runtime/vendor-types.d.ts

@@ -25,3 +25,17 @@ declare module '@vitejs/plugin-rsc/vendor/react-server-dom/server.edge' {
     options?: { temporaryReferences?: unknown; arraySizeLimit?: number }
   ): Promise<unknown[]>;
 }
+
+// src decodes through plugin-rsc's wrappers; tests decode a Flight response
+// with the vendored client directly, as the browser's createFromFetch does.
+declare module '@vitejs/plugin-rsc/vendor/react-server-dom/client.edge' {
+  export function createFromReadableStream(
+    stream: ReadableStream<Uint8Array>,
+    options: {
+      serverConsumerManifest: unknown;
+      nonce?: string;
+      temporaryReferences?: unknown;
+      encodeFormAction?: unknown;
+    }
+  ): PromiseLike<unknown>;
+}