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

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;
 }
 
@@ -388,9 +387,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 +399,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

@@ -89,25 +89,6 @@ export interface NavigationOptions {
    * which of the three it was.
    */
   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.
-   */
-  _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;
 }
 
 /**
@@ -177,34 +158,12 @@ export interface RouterDeps {
     onCommit?: (outcome: CommitOutcome) => 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 +171,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 +252,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,
@@ -108,8 +108,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   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 +125,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 +151,39 @@ 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;
-        }
-
-        try {
-          await renderViaTransition(
-            fetchUrl,
-            owner,
-            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;
+    await runNavigation(url, async (owner) => {
+      try {
+        await renderViaTransition(
+          fetchUrl,
+          owner,
+          types,
+          () =>
+            performNavigationFetch(fetchUrl, {
+              replace,
+              commitUrl: url,
+              signal: owner.fetchAbort.signal,
+              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);
         }
-      },
-      externalSignal
-    );
+      } 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;
+      }
+    });
   }
 
   /**
@@ -523,6 +501,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/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>;
+}

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