@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/src/client/router-effects.ts

@@ -0,0 +1,228 @@
+/**
+ * Router Effects — full-page navigation and post-paint scroll.
+ *
+ * The two things the router does *to the document* rather than to its own
+ * state: leaving the SPA entirely, and moving the scroll position once React
+ * has committed. Extracted from `router.ts` to keep that file focused on
+ * navigation state (see design/18-build-system.md §"No file >500 lines").
+ *
+ * See design/19-client-navigation.md §"Scroll Restoration"
+ */
+
+import { setHardNavigating } from './navigation-root.tsx';
+import type { RenderOwner } from './navigation-transition.ts';
+import { RedirectError, ServerErrorResponse, NonRscResponse } from './rsc-fetch.ts';
+import { recordSkew } from './router-skew.ts';
+
+/** The subset of `RouterDeps` the post-paint scroll effects need. */
+export interface ScrollEffectDeps {
+  scrollTo: (x: number, y: number) => void;
+  afterPaint?: (callback: () => void) => void;
+  scrollToHash?: (hash: string) => boolean;
+}
+
+export interface ScrollEffects {
+  /**
+   * Schedule scroll restoration after the next paint and fire the
+   * scroll-restored event. Used by navigate, popstate, and refresh.
+   */
+  restoreScrollAfterPaint: (scrollY: number) => void;
+  /**
+   * Scroll to the element matching the URL #fragment after paint, falling
+   * back to scroll-to-top when no element matches (matching full-page-load
+   * behavior for an unknown fragment). Used by forward navigation to a
+   * hash-bearing URL (TIM-1035).
+   */
+  scrollToHashAfterPaint: (hash: string) => void;
+}
+
+export function createScrollEffects(deps: ScrollEffectDeps): ScrollEffects {
+  /** Run a callback after the next paint (after React commit). */
+  function afterPaint(callback: () => void): void {
+    if (deps.afterPaint) {
+      deps.afterPaint(callback);
+    } else {
+      callback();
+    }
+  }
+
+  function restoreScrollAfterPaint(scrollY: number): void {
+    afterPaint(() => {
+      deps.scrollTo(0, scrollY);
+      window.dispatchEvent(new Event('timber:scroll-restored'));
+    });
+  }
+
+  function scrollToHashAfterPaint(hash: string): void {
+    afterPaint(() => {
+      if (deps.scrollToHash?.(hash) !== true) {
+        deps.scrollTo(0, 0);
+      }
+      window.dispatchEvent(new Event('timber:scroll-restored'));
+    });
+  }
+
+  return { restoreScrollAfterPaint, scrollToHashAfterPaint };
+}
+
+/**
+ * Leave the SPA and never come back.
+ *
+ * Every router path that gives up on client-side navigation does the same
+ * three things: flag the hard navigation so the Navigation API and React stop
+ * acting on a dying document, perform the document load, then block forever so
+ * the caller cannot carry on rendering into it. The returned promise is
+ * deliberately unresolvable — `location` assignment does not stop this turn of
+ * the event loop.
+ *
+ * Callers: server error, non-RSC response, and every version skew path
+ * ([33-version-skew.md](../../../../design/33-version-skew.md)).
+ */
+export function leaveSpa(url: string, fromUrl: string): Promise<never> {
+  setHardNavigating(true);
+  hardNavigate(url, fromUrl);
+  return new Promise<never>(() => {});
+}
+
+export interface SpaExitDeps {
+  /** The owner that holds the router right now, or null when idle. */
+  currentOwner: () => RenderOwner | null;
+  /** Supersede whatever is in flight and take ownership. */
+  supersede: () => void;
+}
+
+export interface SpaExits {
+  /**
+   * Leave the SPA — but only if `owner` still owns the router. Every
+   * failure a navigation can end on (a server error, a non-RSC response, a
+   * version skew) can surface long after the user has clicked something else:
+   * a fetch that was never cancellable, a Flight thenable that rejects late.
+   * Hard navigating to the abandoned URL would undo that click, so a
+   * navigation that no longer owns the router does nothing and lets the one
+   * that does drive. Never resolves when it does navigate.
+   *
+   * Must be called from inside the `runNavigation()` callback. That function's
+   * `finally` clears the current controller, so an ownership check downstream
+   * of it compares against `null` and never leaves at all.
+   */
+  leaveSpaIfOwned: (owner: RenderOwner, url: string, fromUrl: string) => Promise<void>;
+
+  /**
+   * Leave the SPA from a path that never entered `runNavigation()` — the
+   * stale-client short circuits, which decide before any fetch is attempted.
+   *
+   * Supersedes first. Nothing else on those paths takes ownership, so without
+   * it an in-flight navigation keeps the router: when its fetch or decode
+   * fails a moment later it still passes its own ownership check and hard
+   * navigates to *its* URL, overwriting the document load started here.
+   */
+  leaveSpaSuperseding: (url: string, fromUrl: string) => Promise<never>;
+}
+
+/**
+ * The two ownership-aware ways out of the SPA.
+ *
+ * Both wrap {@link leaveSpa} with the question "is this navigation still the
+ * one the user is waiting for?" — asked before leaving on a failure, answered
+ * by force on a path that decided before any navigation began. They live
+ * together because every caller of `leaveSpa()` needs one or the other, and
+ * an unguarded call is the bug (TIM-1275, TIM-1276).
+ */
+export function createSpaExits({ currentOwner, supersede }: SpaExitDeps): SpaExits {
+  async function leaveSpaIfOwned(owner: RenderOwner, url: string, fromUrl: string): Promise<void> {
+    if (currentOwner() !== owner) return;
+    await leaveSpa(url, fromUrl);
+  }
+
+  function leaveSpaSuperseding(url: string, fromUrl: string): Promise<never> {
+    supersede();
+    return leaveSpa(url, fromUrl);
+  }
+
+  return { leaveSpaIfOwned, leaveSpaSuperseding };
+}
+
+export interface NavigationRecoveryDeps {
+  /** The owner that holds the router right now, or null when idle. */
+  currentOwner: () => RenderOwner | null;
+  leaveSpaIfOwned: SpaExits['leaveSpaIfOwned'];
+  /** Replace the current entry with `url` — the router's own `navigate()`. */
+  navigate: (url: string) => Promise<void>;
+}
+
+/**
+ * Answer the failures an RSC fetch can end on, or report that this one is not
+ * ours to answer.
+ *
+ * Returns `true` when the error was handled; the caller rethrows on `false`.
+ * Handling a failure by leaving the SPA never resolves at all — the document
+ * is going away and the caller must not carry on rendering into it.
+ *
+ * There is exactly one family of these and one response to it, so it lives in
+ * one function rather than once per fetch path. `navigate()`, `refresh()` and
+ * an uncached traversal all reach it: the latter two used to rethrow instead,
+ * and since nobody awaits a traversal that meant pressing Back on a 500 left
+ * the user on the old document with an unhandled rejection (TIM-1277).
+ *
+ * Order matters in exactly one way: `recordSkew()` ends in error-*text*
+ * matching, so it goes last and can never pre-empt a framework control-flow
+ * signal whose message happens to read like a stale bundle. The class checks
+ * above it are mutually exclusive, so their order is free.
+ *
+ * Must be called from inside the `runNavigation()` callback — see
+ * {@link SpaExits.leaveSpaIfOwned}.
+ */
+export function createNavigationRecovery({
+  currentOwner,
+  leaveSpaIfOwned,
+  navigate,
+}: NavigationRecoveryDeps) {
+  return async function recoverFromNavigationError(
+    error: unknown,
+    owner: RenderOwner,
+    url: string,
+    fromUrl: string
+  ): Promise<boolean> {
+    if (error instanceof RedirectError) {
+      // Same ownership rule as leaving the SPA: a superseded navigation must
+      // not steer the document to the destination it was abandoned for.
+      if (currentOwner() !== owner) return true;
+      await navigate(error.redirectUrl);
+      return true;
+    }
+    // A server error, a non-RSC response and a version skew all end the same
+    // way: hand `url` back to the server as a document load, so it can render
+    // the outcome as HTML (design/10-error-handling.md §"Error Page Rendering
+    // for Client Navigation").
+    if (
+      error instanceof ServerErrorResponse ||
+      error instanceof NonRscResponse ||
+      recordSkew(error)
+    ) {
+      await leaveSpaIfOwned(owner, url, fromUrl);
+      return true;
+    }
+    return false;
+  };
+}
+
+/**
+ * Perform the full document load.
+ *
+ * `fromUrl` is the URL the navigation departed from, passed explicitly
+ * because the address bar may have already been updated.
+ *
+ * When the target differs from the departure point only by #fragment,
+ * assigning `href` is a hash change, not a load — so assign first (to update
+ * the address bar) and then reload (TIM-1235).
+ */
+export function hardNavigate(url: string, fromUrl: string): void {
+  const current = new URL(fromUrl, window.location.origin);
+  const target = new URL(url, window.location.origin);
+  if (target.pathname === current.pathname && target.search === current.search) {
+    window.location.href = url;
+    window.location.reload();
+  } else {
+    window.location.href = url;
+  }
+}

package/src/client/router-lifecycle.ts

@@ -0,0 +1,354 @@
+/**
+ * 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
+ * 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.
+ *
+ * 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 { 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 {
+  /**
+   * 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.
+   */
+  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: (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: RenderOwner) => void;
+  /** React has committed `owner`'s tree — every earlier handoff is off screen. */
+  forgetOlderHandoffs: (owner: RenderOwner) => void;
+
+  /** Whether a navigation is currently in flight. */
+  isPending: () => boolean;
+  /** The URL currently being navigated to, or null if idle. */
+  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;
+}
+
+/**
+ * Check if an error is an abort error (connection closed / fetch aborted).
+ * Browsers throw DOMException with name 'AbortError' when a fetch is aborted.
+ */
+function isAbortError(error: unknown): boolean {
+  if (error instanceof DOMException && error.name === 'AbortError') return true;
+  if (error instanceof Error && error.name === 'AbortError') return true;
+  return false;
+}
+
+export function createNavigationLifecycle(deps: NavigationLifecycleDeps): NavigationLifecycle {
+  // 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;
+
+  /**
+   * Whether a handed-off tree has not yet committed. Derived from the slot:
+   * true when `current` is handed off but not yet settled.
+   */
+  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. A new abort path is a call to
+   * this, not a copy of `controller.abort()`.
+   *
+   * See design/19-client-navigation.md §"A navigation that reached React
+   * keeps its stream".
+   */
+  function abortUnlessHandedOff(owner: RenderOwner): void {
+    if (owner.handedOff) return;
+    owner.fetchAbort.abort();
+  }
+
+  /**
+   * 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 `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',
+    externalSignal?: AbortSignal
+  ): RenderOwner {
+    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.
+    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.
+    //
+    // This is a second, independent way a navigation dies, and it fires for
+    // the same reason as the branch above: the browser aborts a
+    // NavigateEvent's signal when that navigation is superseded. So it needs
+    // the same guard — without it, an intercepted push/replace or traversal
+    // whose tree is already on screen still loses its stream, and the guard
+    // above only appears to work because plain `router.navigate()` carries no
+    // external signal (codex on #1004).
+    if (externalSignal) {
+      if (externalSignal.aborted) {
+        abortUnlessHandedOff(owner);
+      } else {
+        externalSignal.addEventListener('abort', () => abortUnlessHandedOff(owner), { once: true });
+      }
+    }
+
+    return owner;
+  }
+
+  function setPending(value: boolean, url?: string): void {
+    const next: RouterPhase =
+      value && url ? { phase: 'navigating', targetUrl: url } : { phase: 'idle' };
+    // Skip no-op updates
+    if (
+      routerPhase.phase === next.phase &&
+      (routerPhase.phase === 'idle' ||
+        (routerPhase.phase === 'navigating' &&
+          next.phase === 'navigating' &&
+          routerPhase.targetUrl === next.targetUrl))
+    ) {
+      return;
+    }
+    routerPhase = next;
+    // Notify subscribers. This is the ONLY pending representation — React and
+    // non-React consumers alike read it, React ones through
+    // `usePendingNavigation()`'s `useSyncExternalStore` (TIM-1307).
+    for (const listener of pendingListeners) {
+      listener(value);
+    }
+  }
+
+  /**
+   * Wrap a navigation in the standard abort/pending/cleanup lifecycle.
+   * 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: (owner: RenderOwner) => Promise<void>,
+    externalSignal?: AbortSignal
+  ): Promise<void> {
+    const owner = createNavOwner('navigation', externalSignal);
+    setPending(true, url);
+    try {
+      await fn(owner);
+    } catch (error) {
+      if (isAbortError(error)) return;
+      throw error;
+    } finally {
+      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 {
+    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 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: 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. 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',
+    getPendingUrl: () => (routerPhase.phase === 'navigating' ? routerPhase.targetUrl : null),
+    onPendingChange(listener) {
+      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();
+    },
+  };
+}