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

package/src/client/router-pipeline.ts

@@ -6,7 +6,7 @@
  * that makes the page current, and hand the result over inside a transition.
  *
  * `router.ts` keeps the *operations* — `navigate`, `refresh`, `handlePopState`,
- * `prefetch`, `applyRevalidation` — and each of them is a call into here. The
+ * `prefetch`, `applyActionResult` — and each of them is a call into here. The
  * split is the same one `router-effects.ts` and `router-lifecycle.ts` made
  * (design/18-build-system.md §"No file >500 lines").
  *
@@ -22,6 +22,7 @@ import type { StateTree } from '../shared/segment-info.ts';
 import type { NavigationState } from './navigation-context.ts';
 import { isPartialNavigation, type NavigationCommitter } from './navigation-commit.ts';
 import type { RouterDeps } from './router-types.ts';
+import type { CommitOutcome, RenderOwner } from './navigation-transition.ts';
 import { recordSkew } from './router-skew.ts';
 import { SingleflightTimeoutError } from '../cache/singleflight.ts';
 
@@ -64,9 +65,9 @@ export interface NavigationPipelineDeps extends Pick<
   deps: RouterDeps;
   prefetchCache: PrefetchCache;
   /** Record that this navigation's tree reached React (router-lifecycle.ts). */
-  markHandedOff: (owner: AbortController) => void;
+  markHandedOff: (owner: RenderOwner) => void;
   /** React committed this navigation's tree (router-lifecycle.ts). */
-  forgetOlderHandoffs: (owner: AbortController) => void;
+  forgetOlderHandoffs: (owner: RenderOwner) => void;
 }
 
 export interface NavigationPipeline {
@@ -78,8 +79,10 @@ export interface NavigationPipeline {
   /** Hand a payload to React inside a transition, or render it directly in tests. */
   renderViaTransition: (
     url: string,
-    owner: AbortController,
-    perform: () => Promise<NavigationPayload>
+    owner: RenderOwner,
+    perform: () => Promise<NavigationPayload>,
+    /** See `NavigationOptions.onCommit`. */
+    onCommit?: (outcome: CommitOutcome) => void
   ) => Promise<void>;
   /** Render a decoded payload into the DOM if a renderer is available. */
   renderPayload: (
@@ -222,79 +225,96 @@ export function createNavigationPipeline({
    */
   async function renderViaTransition(
     url: string,
-    owner: AbortController,
-    perform: () => Promise<NavigationPayload>
+    owner: RenderOwner,
+    perform: () => Promise<NavigationPayload>,
+    onCommit?: (outcome: CommitOutcome) => 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
     // React — NOT on commit, which is a whole commit phase too late. See
-    // `handedOffNavAborts` in router-lifecycle.ts.
+    // `RenderOwner.handedOff` in router-lifecycle.ts.
     const handOff = (): void => markHandedOff(owner);
 
-    // Drop the earlier handoffs once React has committed this tree — the
-    // trees they were feeding are gone. Wrapped around the commit thunk so it
-    // runs on React's commit and not at handover; see `forgetOlderHandoffs`.
+    // Settle the owner as committed once React has committed this tree.
+    // Wrapped around the commit thunk so it runs on React's commit and not
+    // at handover; see `forgetOlderHandoffs`.
     const commitAndForget = (commit: () => void) => (): void => {
       forgetOlderHandoffs(owner);
       commit();
     };
 
     if (deps.navigateTransition) {
-      await deps.navigateTransition(url, async (wrapPayload) => {
-        const result = await perform();
-        // Await the payload's *root row* — the same thing React would suspend
-        // on to render the tree, and the first thing Flight emits. The
-        // previous UI stays on screen while this resolves: nothing has been
-        // handed to React yet, and when it is, NavigationRoot hands it over
-        // inside a transition so a tree that is still streaming does not
-        // displace the departing page (TIM-1306).
-        //
-        // Reading them here rather than with `use()` above the tree is what
-        // keeps a decode failure contained: `result.params` never rejects, so
-        // the rejection reaches React only through the tree, inside whatever
-        // error boundary the app put around it (TIM-1297).
-        const params = await result.params;
+      await deps.navigateTransition(
+        url,
+        owner,
+        async (wrapPayload) => {
+          const result = await perform();
+          // Await the payload's *root row* — the same thing React would suspend
+          // on to render the tree, and the first thing Flight emits. The
+          // previous UI stays on screen while this resolves: nothing has been
+          // handed to React yet, and when it is, NavigationRoot hands it over
+          // inside a transition so a tree that is still streaming does not
+          // displace the departing page (TIM-1306).
+          //
+          // Reading them here rather than with `use()` above the tree is what
+          // keeps a decode failure contained: `result.params` never rejects, so
+          // the rejection reaches React only through the tree, inside whatever
+          // error boundary the app put around it (TIM-1297).
+          const params = await result.params;
 
-        if (isPartialNavigation(result.skippedSegments)) {
-          const segmentUpdates = buildSegmentUpdates(result);
+          if (isPartialNavigation(result.skippedSegments)) {
+            const segmentUpdates = buildSegmentUpdates(result);
 
-          // Re-wrap the CURRENT element with new context values.
-          // SegmentOutlets read updates from SegmentUpdateContext;
-          // NavigationProvider gets the new pathname; the params published
-          // above the retained tree are the *incoming* route's.
-          const element = wrapPayload(
-            deps._getCurrentPayload?.() ?? result.payload,
-            result.navState,
-            params,
-            segmentUpdates
-          );
+            // Re-wrap the CURRENT element with new context values.
+            // SegmentOutlets read updates from SegmentUpdateContext;
+            // NavigationProvider gets the new pathname; the params published
+            // above the retained tree are the *incoming* route's.
+            const element = wrapPayload(
+              deps._getCurrentPayload?.() ?? result.payload,
+              result.navState,
+              params,
+              segmentUpdates
+            );
+            handOff();
+            return {
+              element,
+              decodePromise: observeSkew(result.decodePromise),
+              commit: commitAndForget(result.commit),
+            };
+          }
+
+          // Full navigation — empty updates, render the new tree.
+          const element = wrapPayload(result.payload, result.navState, params);
           handOff();
           return {
             element,
             decodePromise: observeSkew(result.decodePromise),
             commit: commitAndForget(result.commit),
           };
-        }
-
-        // Full navigation — empty updates, render the new tree.
-        const element = wrapPayload(result.payload, result.navState, params);
-        handOff();
-        return {
-          element,
-          decodePromise: observeSkew(result.decodePromise),
-          commit: commitAndForget(result.commit),
-        };
-      });
+        },
+        onCommit
+      );
       return;
     }
-    // Fallback: no transition (tests, no React tree)
-    const result = await perform();
-    handOff();
-    const commit = commitAndForget(result.commit);
-    if (isPartialNavigation(result.skippedSegments)) {
-      commit();
-    } else {
-      renderPayload(result.payload, result.navState, await result.params, commit);
+    // Fallback: no transition (tests, no React tree). The commit is
+    // synchronous here, so the outcome is always 'committed' or 'failed' —
+    // no transition counter to supersede. The hook fires on the way out,
+    // on failure too, so it still fires exactly once.
+    let fallbackOutcome: CommitOutcome = 'committed';
+    try {
+      const result = await perform();
+      handOff();
+      const commit = commitAndForget(result.commit);
+      if (isPartialNavigation(result.skippedSegments)) {
+        commit();
+      } else {
+        renderPayload(result.payload, result.navState, await result.params, commit);
+      }
+    } catch (error) {
+      fallbackOutcome = 'failed';
+      throw error;
+    } finally {
+      onCommit?.(fallbackOutcome);
     }
   }
 
@@ -346,9 +366,6 @@ export function createNavigationPipeline({
           decodePromise: prefetched.decodePromise ?? null,
           segmentInfo: prefetched.segmentInfo ?? null,
           skippedSegments: prefetched.skippedSegments ?? null,
-          // Entries written before this field carried it are treated as
-          // cacheable, which is what they were before a deny could be one.
-          status: prefetched.status ?? 200,
         }
       : undefined;
 
@@ -361,21 +378,28 @@ export function createNavigationPipeline({
     if (result === undefined) {
       const inflight = prefetchCache.joinInflight(cacheKey);
       if (inflight) {
+        // Capture the eviction generation before awaiting the flight.
+        // If an action evicts caches while we wait, the result predates
+        // the mutation and must be discarded (TIM-1476, codex on #1131).
+        const genBefore = prefetchCache.getEvictionGen();
         try {
           const outcome = await raceAbort(inflight, options.signal);
-          if (outcome.kind === 'non-route') {
+          if (prefetchCache.getEvictionGen() !== genBefore) {
+            // Eviction happened while we waited — discard stale result,
+            // fall through to a fresh fetch below.
+          } else if (outcome.kind === 'non-route') {
             throw new NonRscResponse(url);
+          } else {
+            // Consume the ready entry so a second click re-fetches
+            prefetchCache.consume(cacheKey);
+            result = {
+              payload: outcome.result.payload,
+              params: outcome.result.params ?? readPublishedParams(undefined),
+              decodePromise: outcome.result.decodePromise ?? null,
+              segmentInfo: outcome.result.segmentInfo ?? null,
+              skippedSegments: outcome.result.skippedSegments ?? null,
+            };
           }
-          // Consume the ready entry so a second click re-fetches
-          prefetchCache.consume(cacheKey);
-          result = {
-            payload: outcome.result.payload,
-            params: outcome.result.params ?? readPublishedParams(undefined),
-            decodePromise: outcome.result.decodePromise ?? null,
-            segmentInfo: outcome.result.segmentInfo ?? null,
-            skippedSegments: outcome.result.skippedSegments ?? null,
-            status: outcome.result.status ?? 200,
-          };
         } catch (error) {
           // Supersession aborts propagate — don't retry a cancelled navigation
           if (error instanceof DOMException && error.name === 'AbortError') throw error;
@@ -440,7 +464,6 @@ export function createNavigationPipeline({
       payload,
       params,
       segmentInfo: result.segmentInfo,
-      status: result.status,
       skippedSegments: result.skippedSegments,
     });
 

package/src/client/router-types.ts

@@ -14,13 +14,23 @@ import type { ParamsSource } from '../shared/payload-root.ts';
 import type { SegmentInfo } from '../shared/segment-info.ts';
 import type { SegmentCache, PrefetchCache } from './segment-cache.ts';
 import type { HistoryStack } from './history.ts';
-import type { TransitionResult } from './navigation-transition.ts';
+import type { TransitionResult, CommitOutcome, RenderOwner } from './navigation-transition.ts';
+import type { NavigationEpoch } from './router-lifecycle.ts';
 
 export interface NavigationOptions {
   /** Set to false to prevent scroll-to-top on forward navigation */
   scroll?: boolean;
   /** Use replaceState instead of pushState (replaces current history entry) */
   replace?: boolean;
+  /**
+   * Runs exactly once, when React commits this navigation's tree — or when
+   * the navigation is abandoned (superseded or failed) and no such commit
+   * will come. The returned promise resolves on decode, which can be before
+   * OR after the commit; this is the hook for the other event. `<Link>`
+   * holds `isPending` until both have happened (TIM-1418). The outcome says
+   * 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
@@ -111,6 +121,7 @@ export interface RouterDeps {
    */
   navigateTransition?: (
     pendingUrl: string,
+    owner: RenderOwner,
     perform: (
       wrapPayload: (
         payload: unknown,
@@ -125,7 +136,9 @@ export interface RouterDeps {
         params: ParamsSource,
         segmentUpdates?: Map<string, unknown>
       ) => unknown
-    ) => Promise<TransitionResult<unknown>>
+    ) => Promise<TransitionResult<unknown>>,
+    /** See `NavigationOptions.onCommit`; forwarded to `navigateTransition`. */
+    onCommit?: (outcome: CommitOutcome) => void
   ) => Promise<void>;
 
   /**
@@ -196,7 +209,7 @@ export interface RouterInstance {
   /** Navigate to a new URL (forward navigation) */
   navigate(url: string, options?: NavigationOptions): Promise<void>;
   /** Full re-render of the current URL — no state tree sent */
-  refresh(): Promise<void>;
+  refresh(options?: { onCommit?: (outcome: CommitOutcome) => void }): Promise<void>;
   /** Handle a popstate event (back/forward button). scrollY is read from history.state. */
   handlePopState(url: string, scrollY?: number, externalSignal?: AbortSignal): Promise<void>;
   /** Whether a navigation is currently in flight */
@@ -208,12 +221,53 @@ export interface RouterInstance {
   /** Prefetch an RSC payload for a URL (used by Link hover) */
   prefetch(url: string): void;
   /**
-   * Apply a piggybacked revalidation payload from a server action response.
-   * Takes the decoded payload *root* — tree plus the params it published —
-   * and renders it without a server fetch.
+   * Snapshot the router's navigation state before dispatching a server action.
+   * Hand the epoch back to `applyActionResult` with the response (TIM-1474).
+   */
+  epoch(): NavigationEpoch;
+  /**
+   * Reconcile the page after a server action. `tree` is the piggybacked
+   * revalidation payload root, or `undefined` when the server sent none.
+   *
+   * Returns `true` when the result was applied, `false` when stale (a
+   * navigation happened since `epoch` was taken or the router was busy at
+   * dispatch). Async because the no-tree path awaits `refresh()` — the next
+   * queued action must not capture its epoch while the refresh is in-flight.
+   *
+   * Does NOT call `runWhenIdle` — that is the action queue's responsibility
+   * (gated on "queue empty", not just "router idle").
+   *
    * See design/08-forms-and-actions.md §"Single-Roundtrip Revalidation".
    */
-  applyRevalidation(payloadRoot: unknown): void;
+  applyActionResult(epoch: NavigationEpoch, tree?: unknown): Promise<boolean>;
+  /**
+   * Run `task` now if the router is idle (not pending, no uncommitted tree),
+   * otherwise once when it next becomes idle. Single slot — the action queue
+   * uses this to flush one deferred refresh when both queue-empty and
+   * router-idle are true (TIM-1474).
+   */
+  runWhenIdle(task: () => void): void;
+  /**
+   * Settle any handed-off-but-uncommitted owners as superseded, then flush
+   * idle tasks. Called by `syncShallowSearch` when a shallow URL update
+   * displaces a suspended transition (TIM-1480).
+   */
+  settleHandoffs(): void;
+  /**
+   * Invalidate client caches for a path so the next navigation fetches
+   * fresh data. Called when `revalidatePath` targeted a non-current path.
+   */
+  invalidatePath(path: string): void;
+  /**
+   * Evict all prefetch cache entries and history stack payloads (TIM-1476).
+   * Called after a server action that revalidated data — the mutation may
+   * affect any route's data, not just the paths the server named, so every
+   * cached payload is stale. In-flight prefetch singleflights are fenced
+   * by the eviction generation — their results are discarded if they
+   * complete after eviction. The current URL's history entry is preserved
+   * so `applyActionResult` can read its segment metadata.
+   */
+  evictStaleCaches(): void;
   /**
    * Populate the segment cache from server-provided segment metadata.
    * Called on initial hydration with segment info embedded in the HTML.