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

package/src/client/router-lifecycle.ts

@@ -2,23 +2,39 @@
  * Navigation Lifecycle — who owns the router, and when a fetch may be cut.
  *
  * One navigation at a time owns the router. This module holds that ownership
- * (`currentNavAbort`), the rule for taking it (`createNavAbort` supersedes),
- * the wrapper every navigation runs inside (`runNavigation`), the set of
- * navigations whose trees are on screen and therefore unabortable
- * (`handedOffNavAborts`), and the pending store that `TopLoader` and
- * `usePendingNavigation()` subscribe to.
+ * as a single `RenderOwner` slot, the rule for taking it (`createNavOwner`
+ * supersedes), the wrapper every navigation runs inside (`runNavigation`),
+ * and the pending store that `TopLoader` and `usePendingNavigation()`
+ * subscribe to.
  *
- * These belong together because every one of them is a read or a write of
- * "which navigation is the user waiting for?" — the question `router.ts` used
- * to answer in four places. Split out of `router.ts` for the same reason
- * `router-effects.ts` was (design/18-build-system.md §"No file >500 lines").
+ * TIM-1481: replaced the transition counter, the `handedOffNavAborts` set,
+ * and the `AbortController`-as-owner pattern with `RenderOwner`. Supersession
+ * is "take the slot": settle the previous owner and abort its fetch unless
+ * handed off.
  *
  * See design/19-client-navigation.md §"How Pending State Works".
  */
 
-import { supersedeNavigationTransitions } from './navigation-transition.ts';
+import { createRenderOwner, type RenderOwner } from './navigation-transition.ts';
 import type { RouterPhase } from './router-types.ts';
 
+/**
+ * A snapshot of "which page, and was a navigation in flight" at one instant.
+ * Captured before an action's POST and compared at response time so the
+ * router can tell whether the response still describes the page on screen.
+ *
+ * `seq` is a monotonic counter bumped on every `createNavOwner` — covering
+ * every path through `runNavigation`. `idle` is false when the router is
+ * mid-navigation OR a handed-off tree has not yet committed (the
+ * handover-to-commit window on the History API fallback).
+ *
+ * See design/19-client-navigation.md §State Update Invariants (TIM-1474).
+ */
+export interface NavigationEpoch {
+  readonly seq: number;
+  readonly idle: boolean;
+}
+
 /** The subset of `RouterDeps` the navigation lifecycle needs. */
 export interface NavigationLifecycleDeps {
   /**
@@ -30,29 +46,33 @@ export interface NavigationLifecycleDeps {
 }
 
 export interface NavigationLifecycle {
-  /** The controller that owns the router right now, or null when idle. */
-  currentNavAbort: () => AbortController | null;
+  /** The owner that holds the router right now, or null when idle. */
+  currentOwner: () => RenderOwner | null;
   /**
-   * Take ownership of the router, superseding whatever held it. See the
-   * implementation for the three parts of superseding.
+   * 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.
    */
-  createNavAbort: (externalSignal?: AbortSignal) => AbortController;
+  createNavOwner: (
+    kind: 'navigation' | 'revalidation',
+    externalSignal?: AbortSignal
+  ) => RenderOwner;
   /**
    * Run `fn` inside the abort/pending/cleanup lifecycle. AbortErrors are
    * swallowed (not application errors); all other errors propagate.
    */
   runNavigation: (
     url: string,
-    fn: (navAbort: AbortController) => Promise<void>,
+    fn: (owner: RenderOwner) => Promise<void>,
     externalSignal?: AbortSignal
   ) => Promise<void>;
   /**
    * Record that `owner`'s payload has reached React, so its stream is no
    * longer cuttable. No-op when `owner` no longer owns the router.
    */
-  markHandedOff: (owner: AbortController) => void;
+  markHandedOff: (owner: RenderOwner) => void;
   /** React has committed `owner`'s tree — every earlier handoff is off screen. */
-  forgetOlderHandoffs: (owner: AbortController) => void;
+  forgetOlderHandoffs: (owner: RenderOwner) => void;
 
   /** Whether a navigation is currently in flight. */
   isPending: () => boolean;
@@ -60,6 +80,33 @@ export interface NavigationLifecycle {
   getPendingUrl: () => string | null;
   /** Subscribe to pending state changes. */
   onPendingChange: (listener: (pending: boolean) => void) => () => void;
+
+  /**
+   * Place a revalidation owner in the slot without bumping the navigation
+   * sequence. Unlike `createNavOwner`, this does not supersede what's in the
+   * slot — the caller (applyActionResult) has already verified the slot is
+   * idle via the epoch check. A concurrent navigation will supersede this
+   * owner through the normal `createNavOwner` path.
+   */
+  placeRevalidationOwner: (owner: RenderOwner) => void;
+  /** Snapshot the router's navigation state (TIM-1474). */
+  epoch: () => NavigationEpoch;
+  /** True iff no navigation has started or is in flight since `e` was taken. */
+  isEpochCurrent: (e: NavigationEpoch) => boolean;
+  /**
+   * Run `task` now if the router is idle, otherwise once when it next becomes
+   * idle (pending false AND commit done). Single slot — a later request
+   * replaces an earlier one (TIM-1474).
+   */
+  runWhenIdle: (task: () => 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`
+   * when a shallow URL update displaces a suspended transition — without
+   * it, `hasUncommittedNav` stays true indefinitely and `runWhenIdle`
+   * tasks never fire (TIM-1480).
+   */
+  settleHandoffs: () => void;
 }
 
 /**
@@ -73,102 +120,83 @@ function isAbortError(error: unknown): boolean {
 }
 
 export function createNavigationLifecycle(deps: NavigationLifecycleDeps): NavigationLifecycle {
-  // AbortController for the current in-flight navigation.
-  // When a new navigation starts, the previous controller is aborted,
-  // cancelling any in-progress RSC fetch. This provides automatic
-  // cancellation of stale fetches regardless of Navigation API support.
-  let currentNavAbort: AbortController | null = null;
+  // The single ownership slot. One navigation at a time.
+  let current: RenderOwner | null = null;
+
+  // A handed-off-but-uncommitted owner that `runNavigation`'s finally has
+  // already cleared from `current`. Tracked separately so `createNavOwner`
+  // can settle it as superseded if a new navigation starts before the
+  // commit (P1 from codex on #1127). Cleared by `forgetOlderHandoffs`
+  // (commit) or by `createNavOwner` (supersession).
+  let pendingCommit: RenderOwner | null = null;
 
   let routerPhase: RouterPhase = { phase: 'idle' };
   const pendingListeners = new Set<(pending: boolean) => void>();
 
+  let navigationSeq = 0;
+  let idleTask: (() => void) | null = null;
+
   /**
-   * The controllers of navigations whose trees have been HANDED TO REACT.
-   *
-   * Its response may still be streaming: a destination reveals as soon as
-   * React can render it, so the tree on screen routinely has Suspense
-   * boundaries still waiting on later Flight rows. Aborting that response
-   * rejects those rows, and the rejection surfaces through the tree into
-   * whatever error boundary the app has — replacing the page the user is
-   * looking at with an error state, while the successor navigation is still
-   * in flight (codex on #1004).
-   *
-   * So such a navigation's stream is allowed to finish. It is finite and
-   * already in flight; the alternative is a visible error on the page being
-   * departed from. Cancelling is still correct for a navigation whose payload
-   * never reached React at all, which is the case the abort was written for.
-   *
-   * **Handed over, not committed.** This is set when the tree is given to
-   * React, not when React commits it. Marking on commit is a whole React
-   * commit phase too late: the notification would be `NavigationRoot`'s
-   * layout effect, and React runs *descendant* layout effects first — so a
-   * destination that navigates from its own mount layout effect (a redirect
-   * guard) runs before the mark and its just-committed stream gets torn out
-   * from under it. `tests/navigation-supersede.test.ts` already pins that
-   * ordering, and there is no earlier hook short of an extra sibling fiber,
-   * which would shift every `useId` in the payload (see `server/ssr-wrappers`).
-   *
-   * Handing over is the right moment on its own terms, not merely a safe
-   * over-approximation: from the instant React holds the tree it may commit
-   * it without asking, so there is no later point at which "not on screen"
-   * is still knowable from out here. The residue is that a navigation
-   * superseded in the window between handover and commit keeps streaming a
-   * payload nobody sees — bandwidth on a finite response, against a visible
-   * error page the other way (codex on #1004, second round).
-   *
-   * A SET, not a single slot. Between a successor's handover and its commit
-   * React is still showing the previous tree — that is what the transition
-   * buys — so the previous navigation's stream is still feeding the screen and
-   * must stay unabortable. Entries are dropped when a later tree actually
-   * commits (`forgetOlderHandoffs`), which is the moment the trees they fed
-   * are gone. A single slot made a legitimate handover steal protection from
-   * a stream still on screen, and let a superseded navigation overwrite the
-   * winner's entry outright.
+   * Whether a handed-off tree has not yet committed. Derived from the slot:
+   * true when `current` is handed off but not yet settled.
    */
-  const handedOffNavAborts = new Set<AbortController>();
+  function hasUncommittedNav(): boolean {
+    return (
+      pendingCommit !== null || (current !== null && current.handedOff && current.outcome === null)
+    );
+  }
 
   /**
    * Cancel a navigation's RSC fetch — unless its tree is the one on screen.
    *
    * THE only place a navigation controller is aborted. Every path that gives
    * up on a navigation calls this, so the "is this tree displayed?" question
-   * is asked once rather than at each site (the same reason `createSpaExits`
-   * exists for the SPA exits). A new abort path is a call to this, not a copy
-   * of `controller.abort()`.
+   * is asked once rather than at each site. A new abort path is a call to
+   * this, not a copy of `controller.abort()`.
    *
-   * See `handedOffNavAborts` for why such a navigation keeps its stream.
+   * See design/19-client-navigation.md §"A navigation that reached React
+   * keeps its stream".
    */
-  function abortUnlessHandedOff(controller: AbortController): void {
-    if (handedOffNavAborts.has(controller)) return;
-    controller.abort();
+  function abortUnlessHandedOff(owner: RenderOwner): void {
+    if (owner.handedOff) return;
+    owner.fetchAbort.abort();
   }
 
   /**
-   * Create a new AbortController for a navigation, superseding any
-   * previous in-flight navigation. Optionally links to an external
-   * signal (e.g., from the Navigation API's NavigateEvent.signal).
+   * Create a new RenderOwner for a navigation, superseding any previous
+   * 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:
    * 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 `handedOffNavAborts`.
-   * 2. Invalidate its render transition so a response that already
-   *    arrived can't commit a stale tree (NavigationRoot's transId guard).
-   *    This happens either way, so skipping the abort cannot let a stale tree
-   *    displace the successor.
+   *    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 createNavAbort(externalSignal?: AbortSignal): AbortController {
-    if (currentNavAbort) {
-      abortUnlessHandedOff(currentNavAbort);
-      supersedeNavigationTransitions();
+  function createNavOwner(
+    kind: 'navigation' | 'revalidation',
+    externalSignal?: AbortSignal
+  ): RenderOwner {
+    if (current) {
+      abortUnlessHandedOff(current);
+      current.settle('superseded');
       deps.completeRouterNavigation?.();
     }
-    const controller = new AbortController();
-    currentNavAbort = controller;
+    // A handed-off owner whose runNavigation has already finished but whose
+    // tree hasn't committed yet. Settle it so its onCommit fires.
+    if (pendingCommit) {
+      pendingCommit.settle('superseded');
+      pendingCommit = null;
+    }
+    navigationSeq += 1;
+    const owner = createRenderOwner(kind);
+    current = owner;
 
     // If an external signal is provided (e.g., Navigation API),
     // forward its abort to our controller.
@@ -182,15 +210,13 @@ export function createNavigationLifecycle(deps: NavigationLifecycleDeps): Naviga
     // external signal (codex on #1004).
     if (externalSignal) {
       if (externalSignal.aborted) {
-        abortUnlessHandedOff(controller);
+        abortUnlessHandedOff(owner);
       } else {
-        externalSignal.addEventListener('abort', () => abortUnlessHandedOff(controller), {
-          once: true,
-        });
+        externalSignal.addEventListener('abort', () => abortUnlessHandedOff(owner), { once: true });
       }
     }
 
-    return controller;
+    return owner;
   }
 
   function setPending(value: boolean, url?: string): void {
@@ -217,65 +243,75 @@ export function createNavigationLifecycle(deps: NavigationLifecycleDeps): Naviga
 
   /**
    * Wrap a navigation in the standard abort/pending/cleanup lifecycle.
-   * Consolidates the createNavAbort + setPending + staleness-guarded
+   * Consolidates the createNavOwner + setPending + staleness-guarded
    * finally that was duplicated across navigate, refresh, and both
    * handlePopState paths. AbortErrors are swallowed (not application
    * errors); all other errors propagate to the caller.
    */
   async function runNavigation(
     url: string,
-    fn: (navAbort: AbortController) => Promise<void>,
+    fn: (owner: RenderOwner) => Promise<void>,
     externalSignal?: AbortSignal
   ): Promise<void> {
-    const navAbort = createNavAbort(externalSignal);
+    const owner = createNavOwner('navigation', externalSignal);
     setPending(true, url);
     try {
-      await fn(navAbort);
+      await fn(owner);
     } catch (error) {
       if (isAbortError(error)) return;
       throw error;
     } finally {
-      if (currentNavAbort === navAbort) {
-        currentNavAbort = null;
+      if (current === owner) {
+        current = null;
         setPending(false);
         deps.completeRouterNavigation?.();
+        flushIdleTask();
       }
     }
   }
 
+  function flushIdleTask(): void {
+    if (routerPhase.phase !== 'idle' || hasUncommittedNav() || !idleTask) return;
+    const task = idleTask;
+    idleTask = null;
+    task();
+  }
+
   return {
-    currentNavAbort: () => currentNavAbort,
-    createNavAbort,
+    currentOwner: () => current,
+    createNavOwner,
     runNavigation,
 
     // Guarded on still owning the router. A superseded navigation can still
     // reach here: a prefetch hit answers from `prefetchCache`, whose payload
     // was fetched under the PREFETCH's controller, so aborting this
     // navigation's controller does not stop it and `perform()` runs to
-    // completion. `navigateTransition`'s stale-transition check happens after
+    // completion. `navigateTransition`'s stale check happens after
     // `perform()` returns, so without this the loser would claim ownership
     // moments before being discarded — and the next navigation would then
     // abort the winner's still-streaming response, erroring the visible tree
     // (codex on #1004).
-    markHandedOff(owner: AbortController): void {
-      if (currentNavAbort !== owner) return;
-      handedOffNavAborts.add(owner);
+    markHandedOff(owner: RenderOwner): void {
+      if (current !== owner) return;
+      owner.handedOff = true;
+      pendingCommit = owner;
     },
 
     // React has committed THIS tree, so every earlier one is unmounted and
-    // their streams no longer feed anything on screen. Forget them — they are
-    // left to finish on their own rather than aborted, since by here they are
-    // nearly done anyway and the point of the set is never to cut a stream
-    // that might still be feeding the screen.
-    //
-    // Pruning on commit rather than at handover is deliberate: between a
-    // successor's handover and its commit, React is still showing the
-    // PREVIOUS tree (that is what the transition buys), so the previous
-    // navigation's stream is still live on screen and must stay unabortable.
-    forgetOlderHandoffs(owner: AbortController): void {
-      for (const controller of handedOffNavAborts) {
-        if (controller !== owner) handedOffNavAborts.delete(controller);
+    // their streams no longer feed anything on screen. The owner's `handedOff`
+    // boolean already captured the individual state; settling clears the
+    // "uncommitted" window. Unlike the old `handedOffNavAborts` set, there is
+    // no set to prune — the single slot means at most one owner is current.
+    forgetOlderHandoffs(owner: RenderOwner): void {
+      owner.settle('committed');
+      if (pendingCommit === owner) {
+        pendingCommit = null;
       }
+      flushIdleTask();
+    },
+
+    placeRevalidationOwner(owner: RenderOwner): void {
+      current = owner;
     },
 
     isPending: () => routerPhase.phase === 'navigating',
@@ -284,5 +320,35 @@ export function createNavigationLifecycle(deps: NavigationLifecycleDeps): Naviga
       pendingListeners.add(listener);
       return () => pendingListeners.delete(listener);
     },
+
+    epoch(): NavigationEpoch {
+      return {
+        seq: navigationSeq,
+        idle: routerPhase.phase === 'idle' && !hasUncommittedNav(),
+      };
+    },
+    isEpochCurrent(e: NavigationEpoch): boolean {
+      return (
+        e.idle && routerPhase.phase === 'idle' && !hasUncommittedNav() && navigationSeq === e.seq
+      );
+    },
+    runWhenIdle(task: () => void): void {
+      if (routerPhase.phase === 'idle' && !hasUncommittedNav()) {
+        task();
+        return;
+      }
+      idleTask = task;
+    },
+
+    settleHandoffs(): void {
+      if (pendingCommit) {
+        pendingCommit.settle('superseded');
+        pendingCommit = null;
+      }
+      if (current !== null && current.handedOff && current.outcome === null) {
+        current.settle('superseded');
+      }
+      flushIdleTask();
+    },
   };
 }