@timber-js/app 0.2.0-alpha.198 → 0.2.0-alpha.199

package/src/client/browser-entry/action-dispatch.ts

@@ -6,10 +6,12 @@
  * The RSC plugin delegates to `globalThis.__viteRscCallServer` which is
  * set by `setServerCallback`.
  *
- * The callback:
- * 1. Serializes args via `encodeReply` (RSC wire format)
- * 2. POSTs to the current URL with `Accept: text/x-component`
- * 3. Decodes the RSC response stream
+ * Actions are dispatched sequentially through a client-wide queue
+ * (TIM-1475): each action's POST starts only after the previous one has
+ * settled and its result has been applied. Navigations do not enter the
+ * queue — they preempt via the NavigationEpoch, marking any running
+ * action as discarded (TIM-1474). Queries (TIM-1415) will bypass the
+ * queue entirely.
  *
  * See design/08-forms-and-actions.md §"Client-Side Form Mechanics"
  */
@@ -20,111 +22,176 @@ import { setHardNavigating } from '../navigation-root.tsx';
 import { getClientDeploymentId, DEPLOYMENT_ID_HEADER, RELOAD_HEADER } from '../rsc-fetch.ts';
 import { markClientStale } from '../stale-client.ts';
 import { RSC_CONTENT_TYPE } from '../../shared/rsc-media-type.ts';
+import { createActionQueue } from './action-queue.ts';
+
+/**
+ * Wait for a navigation or refresh to both settle (promise resolved) AND
+ * commit (pushState / renderPayload's commit thunk ran). The queue must
+ * not release the next action until the URL is correct in the address bar
+ * — same rule `<Link>` uses for `isPending` (design/19 §Per-Link Pending
+ * State). `onCommit` fires exactly once: on commit, supersession, or
+ * failure, so nothing awaiting this can hang (codex on #1125).
+ */
+function settledAndCommitted(start: (onCommit: () => void) => Promise<void>): Promise<void> {
+  let commitResolve!: () => void;
+  const committed = new Promise<void>((r) => (commitResolve = r));
+  return Promise.all([start(commitResolve).catch(() => {}), committed]).then(() => {});
+}
+
 export function setupServerActions(): void {
-  setServerCallback(async (id: string, args: unknown[]) => {
-    const body = await encodeReply(args);
-
-    // Track the X-Timber-Revalidation header from the response.
-    // We intercept the fetch promise to read headers before createFromFetch
-    // consumes the body stream.
-    let hasRevalidation = false;
-    let hasRedirect = false;
-
-    // Build action request headers. Include deployment ID for version
-    // skew detection (TIM-446) — the server rejects stale actions gracefully.
-    const actionHeaders: Record<string, string> = {
-      'Accept': RSC_CONTENT_TYPE,
-      'x-rsc-action': id,
-    };
-    const actionDeploymentId = getClientDeploymentId();
-    if (actionDeploymentId) {
-      actionHeaders[DEPLOYMENT_ID_HEADER] = actionDeploymentId;
-    }
-
-    const response = fetch(window.location.href, {
-      method: 'POST',
-      headers: actionHeaders,
-      body,
-    }).then((res) => {
-      // Version skew detection (TIM-446): the server has signalled that this
-      // client is stale.
-      if (res.headers.get(RELOAD_HEADER) === '1') {
-        // Record it and fail the action. No page load: the action cannot
-        // succeed either way (its ID does not exist in the new build), and
-        // tearing the document down here would destroy whatever the user had
-        // typed into the form. Their next navigation recovers (TIM-1275).
-        markClientStale();
-        throw new Error('Version skew detected — this client is out of date');
+  const queue = createActionQueue({
+    refreshWhenIdle(): void {
+      const router = getRouterOrNull();
+      if (!router) return;
+      router.runWhenIdle(() => void router.refresh());
+    },
+  });
+
+  setServerCallback((id: string, args: unknown[]) => {
+    return queue.run(async ({ hold }) => {
+      // encodeReply inside the queue — preserves call order when two
+      // calls' args serialize in different numbers of microtasks.
+      const body = await encodeReply(args);
+
+      // Capture the epoch AFTER the previous action has settled and
+      // applied, so it reflects the router's real state — not stale
+      // from a predecessor's refresh bumping the seq (TIM-1474).
+      const router = getRouterOrNull();
+      const epoch = router?.epoch();
+
+      let hasRevalidation = false;
+      let hasRedirect = false;
+      const reval: { paths: string | null } = { paths: null };
+
+      const actionHeaders: Record<string, string> = {
+        'Accept': RSC_CONTENT_TYPE,
+        'x-rsc-action': id,
+      };
+      const actionDeploymentId = getClientDeploymentId();
+      if (actionDeploymentId) {
+        actionHeaders[DEPLOYMENT_ID_HEADER] = actionDeploymentId;
       }
-      hasRevalidation = res.headers.get('X-Timber-Revalidation') === '1';
-      hasRedirect = res.headers.get('X-Timber-Redirect') != null;
-      return res;
-    });
 
-    const decoded = await createFromFetch(response);
-
-    // Handle redirect — server encoded the redirect location in the RSC stream
-    // instead of returning HTTP 302. Perform a client-side SPA navigation.
-    if (hasRedirect) {
-      const wrapper = decoded as { _redirect: string; _status: number };
-
-      // External redirects (e.g., OAuth flows via redirectExternal()) must
-      // use a full page navigation — the RSC router can only fetch same-origin
-      // payloads. On browsers with the Navigation API, navigation.navigate()
-      // happens to perform a real cross-origin navigation, but browsers
-      // without it (iPad Safari) would attempt an RSC fetch that fails on CORS.
-      const isExternal =
-        wrapper._redirect.startsWith('https://') || wrapper._redirect.startsWith('http://');
-      if (isExternal) {
-        setHardNavigating(true);
-        window.location.href = wrapper._redirect;
-        return undefined;
+      const response = fetch(window.location.href, {
+        method: 'POST',
+        headers: actionHeaders,
+        body,
+      }).then((res) => {
+        if (res.headers.get(RELOAD_HEADER) === '1') {
+          markClientStale();
+          throw new Error('Version skew detected — this client is out of date');
+        }
+        hasRevalidation = res.headers.get('X-Timber-Revalidation') === '1';
+        hasRedirect = res.headers.get('X-Timber-Redirect') != null;
+        reval.paths = res.headers.get('X-Timber-Revalidation-Path');
+        return res;
+      });
+
+      const decoded = await createFromFetch(response);
+
+      // TIM-1454: Invalidate non-matching paths unconditionally — the
+      // mutation happened server-side regardless of navigation state.
+      if (reval.paths) {
+        if (router) {
+          for (const p of reval.paths.split(' ')) {
+            router.invalidatePath(p);
+          }
+        }
       }
 
-      try {
-        const router = getRouter();
-        void router.navigate(wrapper._redirect);
-      } catch (e) {
-        // Router not yet initialized — fall back to full navigation.
-        // Set hard-navigating flag to prevent Navigation API interception
-        // and React from rendering during page teardown. See TIM-626.
-        console.debug(
-          '[timber] action redirect: router not ready, using full navigation',
-          e instanceof Error ? e.message : e
-        );
-        setHardNavigating(true);
-        window.location.href = wrapper._redirect;
+      // TIM-1476: When the server reports any revalidation, evict all
+      // prefetch cache entries and history stack payloads — the mutation
+      // may affect data any route reads, not just the paths the server
+      // named. Placed before the redirect branch so an internal redirect
+      // via router.navigate() cannot consume a stale prefetch (codex on
+      // #1131). In-flight prefetch singleflights are fenced by the
+      // eviction generation and will not repopulate the cache.
+      if (router && (hasRevalidation || reval.paths)) {
+        router.evictStaleCaches();
       }
-      return undefined;
-    }
 
-    if (hasRevalidation) {
-      // Piggybacked response: wrapper object { _action, _tree }
-      // Apply the revalidated tree directly — no separate router.refresh() needed.
-      const wrapper = decoded as { _action: unknown; _tree: unknown };
-      const router = getRouterOrNull();
-      if (router) {
+      // Redirects apply unconditionally — the server mutated and told
+      // the client where to go. Return undefined to React NOW so the
+      // action scope settles — awaiting the commit inline would deadlock:
+      // React entangles the commit lane with the action scope, so the
+      // commit waits on the action while the action waits on the commit.
+      // The navigate is fire-and-forget: unlike revalidation (where the
+      // next action must capture the refreshed epoch), a redirect leaves
+      // the page entirely — no subsequent action runs on this URL.
+      if (hasRedirect) {
+        const wrapper = decoded as { _redirect: string; _status: number };
+        const isExternal =
+          wrapper._redirect.startsWith('https://') || wrapper._redirect.startsWith('http://');
+        if (isExternal) {
+          setHardNavigating(true);
+          window.location.href = wrapper._redirect;
+          // Never settle — the document is going away and queued actions
+          // must not resume during page teardown (codex on #1125).
+          return new Promise<undefined>(() => {});
+        }
         try {
-          router.applyRevalidation(wrapper._tree);
+          const r = getRouter();
+          void r.navigate(wrapper._redirect);
         } catch (e) {
-          console.error('[timber] applyRevalidation failed after server action', e);
+          console.debug(
+            '[timber] action redirect: router not ready, using full navigation',
+            e instanceof Error ? e.message : e
+          );
+          setHardNavigating(true);
+          window.location.href = wrapper._redirect;
+        }
+        return undefined;
+      }
+
+      if (hasRevalidation) {
+        const wrapper = decoded as { _action: unknown; _tree: unknown };
+        // Return the action result to React NOW — it may be validation errors
+        // the form needs immediately — and hold the queue until the piggybacked
+        // tree commits. Awaiting applyActionResult inline would deadlock: the
+        // action promise settles only after the commit, but React entangles the
+        // commit lane with the action scope, so the commit waits on the action.
+        // Same pattern as the no-tree branch below (codex on #1126).
+        if (router && epoch) {
+          hold(
+            Promise.resolve()
+              .then(() => router.applyActionResult(epoch, wrapper._tree))
+              .then(
+                (applied) => {
+                  if (!applied) queue.markNeedsRefresh();
+                },
+                (e: unknown) => {
+                  console.error('[timber] applyActionResult failed after server action', e);
+                }
+              )
+          );
         }
+        return wrapper._action;
+      }
+
+      // revalidatePath was called but only for non-current paths —
+      // caches were already invalidated above, no refresh needed.
+      if (reval.paths) {
+        return decoded;
+      }
+
+      // No piggybacked revalidation — return the result to React NOW
+      // (it may be validation errors the form needs immediately) and hold
+      // the queue until the refresh commits so the next action captures a
+      // current epoch (codex on #1125).
+      if (router && epoch) {
+        hold(
+          router.applyActionResult(epoch).then(
+            (applied) => {
+              if (!applied) queue.markNeedsRefresh();
+            },
+            (e: unknown) => {
+              console.debug('[timber] action refresh failed', e instanceof Error ? e.message : e);
+            }
+          )
+        );
       }
-      return wrapper._action;
-    }
-
-    // No piggybacked revalidation — refresh to pick up any mutations.
-    // This covers actions that don't call revalidatePath().
-    try {
-      const router = getRouter();
-      void router.refresh();
-    } catch (e) {
-      console.debug(
-        '[timber] action refresh: router not ready',
-        e instanceof Error ? e.message : e
-      );
-    }
-
-    return decoded;
+
+      return decoded;
+    });
   });
 }

package/src/client/browser-entry/action-queue.ts

@@ -0,0 +1,90 @@
+/**
+ * Sequential Action Queue — serialises server action dispatch.
+ *
+ * One action at a time. The next action's POST starts only after the
+ * previous one has settled AND its result has been applied (revalidation
+ * rendered or refresh awaited). Navigations do not enter the queue —
+ * they preempt via the NavigationEpoch. Queries (TIM-1415) bypass it
+ * entirely.
+ *
+ * See design/08-forms-and-actions.md §"Client-Side Form Mechanics"
+ * and design/19-client-navigation.md §State Update Invariants (TIM-1475).
+ */
+
+export interface ActionQueueDeps {
+  refreshWhenIdle: () => void;
+}
+
+const noop = (): void => {};
+
+/**
+ * Passed into `work` so it can return a result to React immediately
+ * while keeping the queue blocked on a side effect (e.g. a refresh
+ * that must commit before the next action captures its epoch).
+ */
+export interface ActionQueueRun {
+  hold: (p: Promise<unknown>) => void;
+}
+
+export interface ActionQueue {
+  /**
+   * Enqueue `work` to run after all preceding actions have settled.
+   * Returns `work`'s own promise so the caller (React) gets the action
+   * result or rejection. If the preceding action rejected, `work` still
+   * runs — errors do not break the chain.
+   *
+   * `work` receives a `hold` handle: calling `hold(promise)` keeps the
+   * queue blocked until that promise settles, independent of `work`'s
+   * return value. Use it for "return the result NOW, await the refresh
+   * commit for sequencing."
+   */
+  run: <T>(work: (q: ActionQueueRun) => Promise<T>) => Promise<T>;
+  /**
+   * Mark that a discarded action would have revalidated. When the queue
+   * drains, one refresh fires via `deps.refreshWhenIdle`.
+   */
+  markNeedsRefresh: () => void;
+}
+
+export function createActionQueue(deps: ActionQueueDeps): ActionQueue {
+  let tail: Promise<void> = Promise.resolve();
+  let needsRefresh = false;
+
+  function drain(): void {
+    if (!needsRefresh) return;
+    needsRefresh = false;
+    deps.refreshWhenIdle();
+  }
+
+  function run<T>(work: (q: ActionQueueRun) => Promise<T>): Promise<T> {
+    const holds: Promise<unknown>[] = [];
+    const hold = (p: Promise<unknown>): void => {
+      holds.push(p.then(noop, noop));
+    };
+    // `p` is the caller-visible promise — it resolves/rejects with work's
+    // result (React sees this). `settled` is the chain link: work settled
+    // AND every held promise settled. It never rejects, so the chain never
+    // breaks and the next action always runs.
+    const p = tail.then(
+      () => work({ hold }),
+      () => work({ hold })
+    );
+    const settled = p
+      .then(noop, noop)
+      .then(() => Promise.all(holds))
+      .then(noop);
+    tail = settled;
+    // Drain when the queue empties: tail identity means nobody enqueued
+    // behind this action between its start and its settlement.
+    void settled.then(() => {
+      if (tail === settled) drain();
+    });
+    return p;
+  }
+
+  function markNeedsRefresh(): void {
+    needsRefresh = true;
+  }
+
+  return { run, markNeedsRefresh };
+}

package/src/client/browser-entry/router-init.ts

@@ -20,7 +20,7 @@ import {
   getNavigationState,
   setNavigationState,
 } from '../navigation-context.ts';
-import { navigateTransition } from '../navigation-transition.ts';
+import { navigateTransition, type RenderOwner } from '../navigation-transition.ts';
 import type { NavigationRender } from '../navigation-root.tsx';
 import { SegmentUpdateContext, EMPTY_SEGMENT_UPDATES } from '../segment-update-context.ts';
 import { SlotContentCacheContext, type SlotContentCache } from '../slot-content-cache-context.ts';
@@ -156,6 +156,11 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
     currentParams = params;
   }
 
+  // Late-bound: syncShallowSearch is defined before createRouter, but only
+  // called after the router exists (from patched pushState/replaceState or
+  // the Navigation API handler, both of which fire from user code).
+  let router: RouterInstance | null = null;
+
   // ─── History API Patch ──────────────────────────────────────────
   // Patch pushState/replaceState to detect external URL changes (nuqs
   // shallow updates, replaceUrl, third-party libraries). When the router
@@ -203,6 +208,21 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
     };
     setNavigationState(newNavState);
 
+    // A shallow search update displaces whatever React is rendering. If a
+    // handed-off tree is still suspended (e.g. a cached popstate replay whose
+    // client component is lazy-loading), this render replaces it and React
+    // will never commit it — so forgetOlderHandoffs never fires and
+    // hasUncommittedNav stays true forever, blocking runWhenIdle tasks.
+    //
+    // Deferred to a microtask so that when a child layout effect fires a
+    // pushState during the same commit (e.g. nuqs syncing on mount),
+    // forgetOlderHandoffs — which runs in the parent layout effect, i.e.
+    // synchronously before the microtask — clears pendingCommit first,
+    // and this settle is a no-op. A genuinely displaced suspended tree
+    // never fires forgetOlderHandoffs, so the microtask settles it
+    // (TIM-1480).
+    queueMicrotask(() => router?.settleHandoffs());
+
     publishTree(currentPayload, currentParams);
     render(renderTree(currentPayload, newNavState, currentParams), null);
   }
@@ -268,7 +288,7 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
     },
 
     // Render a decoded RSC tree through the router's React root. Used for
-    // non-navigation renders (popstate cached replay, applyRevalidation).
+    // non-navigation renders (popstate cached replay, applyActionResult).
     // Wraps with NavigationProvider + TimberNuqsAdapter.
     //
     // For navigation renders (navigate, refresh, popstate-with-fetch),
@@ -307,38 +327,43 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
     //
     // `_url` names the pending URL the router already published to its own
     // pending store before calling here; the transition has no use for it.
-    navigateTransition: (_url: string, perform) => {
-      return navigateTransition(async () => {
-        // What wrapPayload built, held until the transition wins. The client's
-        // record of the displayed tree is navigation state like any other, so
-        // it rides the same commit as the segment cache rather than being
-        // written as a side effect of building the element (TIM-1301).
-        let displayed: { tree: unknown; params: ParamsSource } | null = null;
-        const { element, decodePromise, commit } = await perform(
-          (
-            rawPayload: unknown,
-            navState: NavigationState,
-            params: ParamsSource,
-            segmentUpdates?: Map<string, unknown>
-          ) => {
-            displayed = { tree: rawPayload, params };
-            return renderTree(
-              rawPayload,
-              navState,
-              params,
-              segmentUpdates as Map<string, React.ReactNode> | undefined
-            );
-          }
-        );
-        return {
-          element: element as React.ReactNode,
-          decodePromise,
-          commit: () => {
-            if (displayed) publishTree(displayed.tree, displayed.params);
-            commit();
-          },
-        };
-      }, render);
+    navigateTransition: (_url: string, owner: RenderOwner, perform, onCommit) => {
+      return navigateTransition(
+        owner,
+        async () => {
+          // What wrapPayload built, held until the transition wins. The client's
+          // record of the displayed tree is navigation state like any other, so
+          // it rides the same commit as the segment cache rather than being
+          // written as a side effect of building the element (TIM-1301).
+          let displayed: { tree: unknown; params: ParamsSource } | null = null;
+          const { element, decodePromise, commit } = await perform(
+            (
+              rawPayload: unknown,
+              navState: NavigationState,
+              params: ParamsSource,
+              segmentUpdates?: Map<string, unknown>
+            ) => {
+              displayed = { tree: rawPayload, params };
+              return renderTree(
+                rawPayload,
+                navState,
+                params,
+                segmentUpdates as Map<string, React.ReactNode> | undefined
+              );
+            }
+          );
+          return {
+            element: element as React.ReactNode,
+            decodePromise,
+            commit: () => {
+              if (displayed) publishTree(displayed.tree, displayed.params);
+              commit();
+            },
+          };
+        },
+        render,
+        onCommit
+      );
     },
 
     _getCurrentPayload: () => currentPayload,
@@ -353,7 +378,7 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
     },
   };
 
-  const router = createRouter(deps);
+  router = createRouter(deps);
   setGlobalRouter(router);
 
   // Set up Navigation API integration after router is created.

package/src/client/deny-last-resort.tsx

@@ -0,0 +1,54 @@
+'use client';
+
+import { statusReasonPhrase } from '../shared/status-reason-phrase.ts';
+
+/**
+ * The deny chain's terminal, in client form.
+ *
+ * design/10-error-handling.md §"Fallback Chain" ends every chain in the
+ * framework default page. On a document load that page is the HTML string in
+ * `server/default-status-page.ts`. This is the same terminal for a deny that
+ * streamed to the client as an error row and reached the root boundary with
+ * nothing in between able to render it — which happens in exactly one shape:
+ * a server component rendered by a layout's own chrome denied, and no status
+ * file exists at or above that layout. Files *below* the denying layout are
+ * not candidates: rendering any of them means executing that layout again,
+ * which denies again. So there is no user file to show, and this renders the
+ * default one. See TIM-1450, design/04-authorization.md §"Where a Deny Page
+ * Renders".
+ *
+ * A plain reload button, not an automatic navigation: the status and phrase
+ * are already on screen and tell the reader what happened; the button hands
+ * them the one recovery the framework can offer (a document request, which
+ * takes the re-render fallback) without doing it behind their back. An
+ * effect-driven reload could not be told apart from a loop.
+ *
+ * Same content rules as the HTML page: the status code is the only thing
+ * interpolated, and it is clamped by `statusReasonPhrase`. No URL, no error
+ * message, no stack. See design/13-security.md principle 4.
+ */
+export function DenyLastResort({ status }: { status: number }) {
+  const phrase = statusReasonPhrase(status);
+  return (
+    <main
+      data-timber-deny-terminal=""
+      style={{
+        fontFamily: 'system-ui, -apple-system, "Segoe UI", sans-serif',
+        textAlign: 'center',
+        padding: '2rem',
+      }}
+    >
+      <h1 style={{ fontSize: '3rem', fontWeight: 600, margin: 0, letterSpacing: '-0.02em' }}>
+        {status}
+      </h1>
+      <p style={{ margin: '0.5rem 0 0', opacity: 0.7 }}>{phrase}</p>
+      <button
+        type="button"
+        onClick={() => window.location.reload()}
+        style={{ marginTop: '1.5rem', padding: '0.5rem 1rem', font: 'inherit', cursor: 'pointer' }}
+      >
+        Reload
+      </button>
+    </main>
+  );
+}