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

package/src/client/navigation-root.tsx

@@ -1,21 +1,26 @@
 /**
- * NavigationRoot — Wrapper component for transition-based rendering.
- *
- * Solves the "new boundary has no old content" problem for client-side
- * navigation. When React renders a completely new Suspense boundary via
- * root.render(), it shows the fallback immediately — root.render() is
- * always an urgent update regardless of startTransition.
- *
- * NavigationRoot holds the current element in React state. Navigation
- * updates call startTransition(() => setState(newElement)), which IS
- * a transition update. React keeps the old committed tree visible while
- * the new tree resolves, instead of hiding it behind a Suspense fallback.
- *
- * The navigation's async work runs OUTSIDE the transition scope and every
- * state update it schedules gets its own synchronous `startTransition` — a
- * transition scope does not survive an `await`, and an async callback that
- * returns a thenable defers the commit past the promise callers await. See
- * the long comment on `_navigateTransition` (TIM-1306).
+ * NavigationRoot — the component the router renders the page through.
+ *
+ * It is stateless. The router owns the displayed tree and drives React with
+ * `root.render(<NavigationRoot rendered={{ element, publish }} />)` inside a
+ * synchronous `startTransition` (see `client/react-root.ts`). A transition
+ * update keeps the committed tree on screen while the incoming one resolves,
+ * instead of replacing it with a Suspense fallback — the reason this
+ * component exists (TIM-1306).
+ *
+ * It used to hold the tree in `useState` and register `setState` closures
+ * into module globals during render so the router could reach into it, with a
+ * second set of stand-in closures for the window before a root existed
+ * (TIM-600). Inverting that — router calls React, not the reverse — deleted
+ * all of it (TIM-1431). Next.js's `use-action-queue.ts` says it wants this
+ * shape and cannot have it because it must decode Flight during render;
+ * timber decodes in `router-pipeline.ts`, so nothing stands in the way.
+ *
+ * What this component does own is **the commit-time publish**: a navigation's
+ * state (segment cache, address bar, history stack, pathname) is published
+ * from a layout effect keyed on the tree object, so the event that puts a
+ * route on screen is the event that makes it current (TIM-1301). Props work
+ * for that exactly as state did.
  *
  * This component holds no pending state. The `TopLoader` it renders and the
  * public `usePendingNavigation()` both subscribe to the router's external
@@ -35,166 +40,39 @@
  * See design/19-client-navigation.md §"NavigationContext"
  */
 
-import {
-  createElement,
-  Fragment,
-  startTransition,
-  useLayoutEffect,
-  useRef,
-  useState,
-  type ReactNode,
-} from 'react';
+import { createElement, Fragment, useLayoutEffect, useRef, type ReactNode } from 'react';
 import { TopLoader, type TopLoaderConfig } from './top-loader.tsx';
 
-// ─── Transition Result ──────────────────────────────────────────
+// ─── Rendered Tree ──────────────────────────────────────────────
 
 /**
- * What a navigation's `perform()` hands back to the transition.
- *
- * Declared once and shared by every layer that passes it along — the router's
- * `RouterDeps.navigateTransition` imports it too — so a field cannot be added
- * to the producer and dropped by the adapter in between. `E` is the element
- * type: `ReactNode` here, `unknown` in the router, which never touches it.
+ * The tree the router has handed to React, and the state publish that belongs
+ * to it. They travel as one object so React's commit of the tree is the event
+ * that publishes — see the effect in NavigationRoot. Every `render` builds a
+ * fresh one, which is what keys that effect: a tree is published once, however
+ * many times React re-runs the effect for it.
  */
-export interface TransitionResult<E = ReactNode> {
-  /** The wrapped tree to render. */
-  element: E;
-  /** Resolves when the Flight stream finishes decoding, or null. */
-  decodePromise: Promise<void> | null;
+export interface RenderedTree {
+  element: ReactNode;
   /**
    * Publishes the navigation's state — segment cache, pathname, address bar,
    * history stack, and the client's record of the mounted tree — and
-   * announces it to listeners outside React.
-   *
-   * Run when React commits this tree, not when the tree is handed over: a
-   * tree React is still waiting on, or one a later navigation replaces first,
-   * has been given to React without being on screen. A superseded navigation
-   * never runs it and leaves every one of those consumers describing the
-   * route still on screen (TIM-1301).
+   * announces it to listeners outside React. Runs when React commits
+   * `element`, never before (TIM-1301). Null for a render that has nothing to
+   * publish on commit (hydration, the shallow search re-wrap).
    */
-  commit: () => void;
-}
-
-/**
- * The tree NavigationRoot holds in state, and the state publish that belongs
- * to it. They travel as one object so React's commit of the tree is the event
- * that publishes — see the effect in NavigationRoot.
- */
-interface RenderedTree {
-  element: ReactNode;
   publish: (() => void) | null;
 }
 
-// ─── Navigation Transition Counter ──────────────────────────────
-// Monotonically increasing counter that increments each time
-// navigateTransition() is called. Used to detect stale transitions:
-// if a newer transition started while the current one's perform()
-// was in flight, the current transition is stale and should reject.
-//
-// Separate from the link-pending navId (which only increments on
-// link clicks). This counter covers all navigation types: link clicks,
-// programmatic navigate(), refresh(), and handlePopState().
-//
-// Uses globalThis for singleton guarantee across chunks — same pattern
-// as NavigationContext and the link pending store.
-
-const NAV_TRANSITION_KEY = Symbol.for('__timber_nav_transition_counter');
-
 /**
- * `waiters` are woken on every bump so an in-flight navigation can stop
- * waiting on its own payload the moment it is superseded — see
- * `settleOnDecodeOrSupersession`.
- */
-interface TransitionCounter {
-  id: number;
-  waiters: Set<() => void>;
-}
-
-function getTransitionCounter(): TransitionCounter {
-  const g = globalThis as Record<symbol, unknown>;
-  const existing = g[NAV_TRANSITION_KEY] as Partial<TransitionCounter> | undefined;
-  if (!existing) {
-    const created: TransitionCounter = { id: 0, waiters: new Set() };
-    g[NAV_TRANSITION_KEY] = created;
-    return created;
-  }
-  // A duplicated copy of this module may have created the singleton before
-  // `waiters` existed. The object is shared across chunks, so fill it in
-  // rather than replacing it — replacing would strand the other copy's id.
-  existing.waiters ??= new Set();
-  return existing as TransitionCounter;
-}
-
-/** Bump the counter and wake everything waiting on an older transition. */
-function bumpTransitionCounter(): number {
-  const counter = getTransitionCounter();
-  counter.id += 1;
-  for (const wake of [...counter.waiters]) wake();
-  return counter.id;
-}
-
-/**
- * Invalidate all in-flight navigation transitions. Any navigateTransition()
- * call whose perform() has not yet committed will reject with AbortError
- * instead of committing its element.
- *
- * Called by the router when a render supersedes in-flight navigations
- * WITHOUT going through navigateTransition() — the cached popstate replay
- * renders via transitionRender(), which doesn't bump the counter, so a
- * stale forward navigation's setElement would otherwise pass the
- * `counter.id !== transId` guard and commit the forward page over the
- * replayed back page (TIM-1022).
- */
-export function supersedeNavigationTransitions(): void {
-  bumpTransitionCounter();
-}
-
-/**
- * Wait for the payload to finish decoding, OR for this transition to be
- * superseded — whichever happens first.
+ * Hand a tree to React in a transition. `publish` runs when React commits it.
  *
- * A superseded navigation must stop waiting on its own stream. The stream is
- * deliberately NOT aborted once its tree has been handed to React (the tree
- * may be on screen with boundaries still feeding from it — see
- * `handedOffNavAbort` in `client/router.ts`), so there is nothing left to make
- * `decodePromise` settle promptly. Awaiting it bare would keep the loser's
- * `router.navigate()` promise pending for the rest of the stream — and
- * forever if it stalls — which is what `<Link>`'s `isPending` is timed
- * against, so the losing link would sit spinning while the winner loaded
- * (codex on #1004).
- *
- * A decode *failure* still propagates: it is a real error for this
- * navigation, and the caller's recovery is timed against it.
+ * Every path that puts a page on screen goes through one of these — a
+ * navigation, a revalidation, a popstate replay, a shallow search re-wrap —
+ * and it is always a synchronous `startTransition` around `root.render`.
+ * The production one is `createReactRoot().render`.
  */
-function settleOnDecodeOrSupersession(
-  decodePromise: Promise<void>,
-  counter: TransitionCounter,
-  transId: number
-): Promise<void> {
-  if (counter.id !== transId) return Promise.resolve();
-  return new Promise<void>((resolve, reject) => {
-    const stopWaiting = (): void => {
-      counter.waiters.delete(wake);
-    };
-    const wake = (): void => {
-      if (counter.id !== transId) {
-        stopWaiting();
-        resolve();
-      }
-    };
-    counter.waiters.add(wake);
-    decodePromise.then(
-      () => {
-        stopWaiting();
-        resolve();
-      },
-      (error: unknown) => {
-        stopWaiting();
-        reject(error instanceof Error ? error : new Error(String(error)));
-      }
-    );
-  });
-}
+export type NavigationRender = (element: ReactNode, publish: (() => void) | null) => void;
 
 // ─── Hard Navigation Guard ──────────────────────────────────────
 
@@ -255,52 +133,25 @@ export function isHardNavigating(): boolean {
 // eslint-disable-next-line unicorn/no-thenable -- Intentionally a never-resolving thenable
 const unresolvedThenable = { then() {} } as PromiseLike<never>;
 
-// ─── Module-level functions ──────────────────────────────────────
-
-/**
- * Module-level reference to the state setter wrapped in startTransition.
- * Used for non-navigation renders (applyRevalidation, popstate replay).
- */
-let _transitionRender: ((element: ReactNode) => void) | null = null;
-
-/**
- * Module-level reference to the navigation transition function.
- *
- * Runs the fetch OUTSIDE any transition scope and wraps only the state update
- * that hands the resulting tree to React — describing this as "a full
- * navigation in a single startTransition" is the shape TIM-1306 removed.
- */
-let _navigateTransition:
-  | ((url: string, perform: () => Promise<TransitionResult>) => Promise<void>)
-  | null = null;
-
 // ─── Component ───────────────────────────────────────────────────
 
 /**
- * Root wrapper component that enables transition-based rendering.
- *
- * Renders the TopLoader alongside the tree it holds in state. Neither adds a
- * DOM element on the hydration path, so the tree matches the server HTML.
- *
- * Usage in browser-entry.ts:
- *   const rootEl = createElement(NavigationRoot, { initial: wrapped });
- *   reactRoot = hydrateRoot(document, rootEl);
+ * Root component the router renders the page through.
  *
- * Subsequent navigations:
- *   navigateTransition(url, async () => { fetch; return wrappedElement; });
+ * Renders the TopLoader alongside the tree it is given. Neither adds a DOM
+ * element on the hydration path, so the tree matches the server HTML.
  *
- * Non-navigation renders:
- *   transitionRender(newWrappedElement);
+ * Rendered only by `createReactRoot` (client/react-root.ts): hydration passes
+ * `{ element, publish: null }`, and every later render is a synchronous
+ * `startTransition(() => root.render(...))` with a fresh `rendered` object.
  */
 export function NavigationRoot({
-  initial,
+  rendered,
   topLoaderConfig,
 }: {
-  initial: ReactNode;
+  rendered: RenderedTree;
   topLoaderConfig?: TopLoaderConfig;
 }): ReactNode {
-  const [rendered, setRendered] = useState<RenderedTree>({ element: initial, publish: null });
-
   // Publish the navigation's state when React commits its tree — not when the
   // tree is handed over. A tree React is still waiting on, or one a later
   // navigation replaces before React renders it, has been *given* to React
@@ -324,8 +175,8 @@ export function NavigationRoot({
   //
   // Keyed on the tree object rather than on the effect run. A publish moves
   // the address bar, which is not idempotent, so any second invocation for the
-  // same tree — an effect re-run React is entitled to perform — must be a
-  // no-op rather than a second history entry.
+  // same tree — an effect re-run React is entitled to perform, StrictMode's
+  // double-invoke — must be a no-op rather than a second history entry.
   const publishedRef = useRef<RenderedTree | null>(null);
   useLayoutEffect(() => {
     if (publishedRef.current === rendered) return;
@@ -333,141 +184,17 @@ export function NavigationRoot({
     rendered.publish?.();
   }, [rendered]);
 
-  // NOTE: We use standalone `startTransition` (imported from 'react'),
-  // NOT `useTransition`. The `useTransition` hook's `startTransition`
-  // is tied to a single fiber and tracks one async callback at a time.
-  // When two navigations overlap (click slow-page, then click dashboard),
-  // calling useTransition's startTransition twice with concurrent async
-  // callbacks corrupts React's internal hook tracking — causing
-  // "Rendered more hooks than during the previous render."
-  //
-  // Standalone `startTransition` creates independent transition lanes
-  // for each call, so concurrent navigations don't interfere. We don't
-  // need useTransition's `isPending` — pending state lives in the router's
-  // external store, which TopLoader and usePendingNavigation() subscribe to.
-  //
-  // This matches the Next.js pattern (TIM-625): "No useTransition in
-  // the router at all — only standalone startTransition."
-
-  // Non-navigation render (revalidation, popstate cached replay).
-  // Non-navigation render (revalidation, popstate cached replay). Both publish
-  // synchronously in the router before calling this — neither has an in-flight
-  // window in which it could be superseded — so there is nothing to publish
-  // on commit.
-  _transitionRender = (newElement: ReactNode) => {
-    startTransition(() => {
-      setRendered({ element: newElement, publish: null });
-    });
-  };
-
-  // Full navigation transition.
-  //
-  // The async work runs OUTSIDE any transition scope, and each state update is
-  // its own synchronous `startTransition`. Two React behaviours force that
-  // shape; both were measured on React 19.2.7 (tests/navigation-transition-
-  // suspense.test.ts pins the observable half).
-  //
-  // 1. A transition scope does not survive an `await`. `startTransition`
-  //    restores the previous scope in its `finally`, which for an async
-  //    callback runs when that callback RETURNS — i.e. at its first `await`.
-  //    So an update scheduled past an await inside `startTransition(async …)`
-  //    is an ordinary urgent update:
-  //
-  //      startTransition(() => setEl(x))                     -> 'HOME' held
-  //      startTransition(async () => { await p; setEl(x) })  -> fallback shown
-  //
-  //    Left uncorrected, every navigation whose new tree suspends replaces the
-  //    visible page with a Suspense fallback — the exact thing this component
-  //    exists to prevent (TIM-1306). React documents the caveat under
-  //    `startTransition`: updates after an await need their own transition.
-  //
-  // 2. Re-wrapping *inside* the async callback is not enough. Returning a
-  //    thenable from `startTransition` hands it to `ReactSharedInternals.S`,
-  //    which calls react-dom's `entangleAsyncAction`. That opens an action
-  //    scope: `currentEntangledLane` collects EVERY transition update
-  //    scheduled while the scope is open — including one from a nested,
-  //    fully synchronous `startTransition` — and rendering that lane throws
-  //    `currentEntangledActionThenable`, suspending until the action settles.
-  //    Which is after the promise `navigateTransition` hands back, so a caller
-  //    that awaits a navigation and then reads the DOM sees the departing
-  //    page, and the TIM-1301 publish (a layout effect on the commit) is just
-  //    as late. (Not `ReactSharedInternals.asyncTransitions` — that counter is
-  //    write-only in 19.2.7.)
-  //
-  // No async action is created here, so every navigation commits as soon as
-  // React can render its destination — where TIM-1301 put it. That
-  // now holds for ALL of them. It used not to hold for `<Link>`, which wrapped
-  // `router.navigate()` in its own `useTransition`: that action scope
-  // entangled this component's updates just the same, so a Link navigation
-  // committed only once the payload had finished decoding, and with it
-  // `pushState`, the segment cache and `timber:navigation-end`. Link now calls
-  // `router.navigate()` outside any transition and tracks its own `isPending`
-  // with a plain `useState` (TIM-1307).
-  //
-  // Nothing here may reopen an action scope: no `startTransition` callback in
-  // this path may return a thenable, and no caller may invoke this from inside
-  // a React action scope. That is a rule about `startTransition`, not about
-  // `perform` — `perform` is async by contract and is awaited OUTSIDE any
-  // transition scope, which is exactly why it is safe.
-  //
-  // Standalone `startTransition` rather than `useTransition`'s is still
-  // deliberate — see the TIM-625 note above; each navigation needs an
-  // independent lane.
-  //
-  // `url` is unused: it named the pending state this component used to hold,
-  // and the router already publishes the same URL to its own pending store
-  // before calling here. It stays in the signature because the router's
-  // `RouterDeps.navigateTransition` adapter passes it and the argument reads
-  // at the call site.
-  _navigateTransition = (_url: string, perform: () => Promise<TransitionResult>) => {
-    // Increment the transition counter SYNCHRONOUSLY (before any await). Each
-    // call gets a unique transId; the counter is the same globalThis
-    // singleton, so a newer call always has a higher id.
-    const counter = getTransitionCounter();
-    const transId = bumpTransitionCounter();
-
-    const superseded = () => new DOMException('Navigation superseded', 'AbortError');
-
-    return (async () => {
-      const { element, decodePromise, commit } = await perform();
-      if (counter.id !== transId) {
-        decodePromise?.catch(() => {});
-        throw superseded();
-      }
-      // Hand the tree over with its commit attached. The effect above runs
-      // it if and when React commits this tree, so a navigation that is
-      // superseded while its payload streams publishes nothing (TIM-1301).
-      //
-      // This is THE update that must not hide the departing page (TIM-1306).
-      startTransition(() => {
-        setRendered({ element, publish: commit });
-      });
-      // React may commit the tree before this settles — that is the point:
-      // the destination reveals as React is able to render it
-      // rather than waiting for the whole Flight stream. The await is here so
-      // the promise this function hands back still means "the payload is
-      // decoded", which is what the router's scroll restoration, the
-      // Navigation API deferred and `<Link>`'s `isPending` are timed against.
-      //
-      // ...unless this navigation loses first, in which case it stops waiting
-      // on a stream that is no longer its business. See
-      // `settleOnDecodeOrSupersession`.
-      if (decodePromise) await settleOnDecodeOrSupersession(decodePromise, counter, transId);
-      if (counter.id !== transId) throw superseded();
-    })();
-  };
-
   // ─── Hard navigation guard ─────────────────────────────────
   // When a hard navigation is in progress (500 error, version skew),
   // suspend forever to prevent React from rendering children during
   // page teardown. This avoids "Rendered more hooks" crashes in
   // CHILD components whose hook counts may shift during teardown.
   //
-  // CRITICAL: This throw MUST come AFTER all hooks (the useState,
-  // useRef and useLayoutEffect above). React requires the same hooks
-  // to run on every render. If we threw before hooks, React would see
-  // 0 hooks on the re-render vs 3 on the initial render — triggering
-  // the exact "Rendered more hooks" error we're trying to prevent.
+  // CRITICAL: This throw MUST come AFTER all hooks (the useRef and
+  // useLayoutEffect above). React requires the same hooks to run on every
+  // render. If we threw before hooks, React would see 0 hooks on the
+  // re-render vs 2 on the initial render — triggering the exact "Rendered
+  // more hooks" error we're trying to prevent.
   //
   // By placing it after hooks but before the return, all hooks
   // satisfy React's rules, but the thrown thenable prevents any
@@ -495,86 +222,3 @@ export function NavigationRoot({
     rendered.element
   );
 }
-
-// ─── Public API ──────────────────────────────────────────────────
-
-/**
- * Trigger a transition render for non-navigation updates.
- * React keeps the old committed tree visible while any new Suspense
- * boundaries in the update resolve.
- *
- * Used for: applyRevalidation, popstate replay with cached payload.
- */
-export function transitionRender(element: ReactNode): void {
-  if (_transitionRender) {
-    _transitionRender(element);
-  }
-}
-
-/**
- * Run a full navigation, handing its tree to React in a transition.
- *
- * The `perform` callback fetches the RSC payload, updates router state, and
- * returns the wrapped React element. `perform` is async by contract and runs
- * OUTSIDE any transition scope — only the `setRendered` that hands its result
- * over is wrapped, in a synchronous `startTransition`.
- *
- * Do not call this from inside a React action scope, and never let a
- * `startTransition` callback in this path return a thenable: either opens an
- * action scope that entangles the update and defers the commit until the
- * action settles (TIM-1306, TIM-1307).
- *
- * Returns a Promise that resolves when the async work completes — the payload
- * is fetched, decoded, and handed to React. It does **not** wait for React to
- * commit the tree, so the state that publishes on that commit (address bar,
- * segment cache, history entry, pathname) may still be a beat behind when it
- * resolves. Anything that needs the destination to be current should listen
- * for `timber:navigation-end`, which is dispatched by the publish itself.
- *
- * Awaiting the publish here was tried and rejected: it makes the promise
- * depend on a React commit, which never arrives if the root unmounts
- * mid-navigation, and deadlocks any caller that awaits a navigation inside
- * `act()`.
- *
- * Used for: navigate(), refresh(), popstate with fetch.
- */
-export function navigateTransition(
-  url: string,
-  perform: () => Promise<TransitionResult>
-): Promise<void> {
-  if (_navigateTransition) {
-    return _navigateTransition(url, perform);
-  }
-  // Fallback: no NavigationRoot mounted (shouldn't happen in production).
-  // Nothing can supersede a transition that does not exist, so the commit
-  // runs unconditionally.
-  return perform().then((result) => result.commit());
-}
-
-/**
- * Install one-shot deferred callbacks for the no-RSC bootstrap path (TIM-600).
- *
- * When there's no RSC payload, we can't create a React root immediately —
- * `createRoot(document).render(...)` would blank the SSR HTML. Instead,
- * this sets up `_transitionRender` and `_navigateTransition` so that the
- * first client navigation triggers root creation via `createAndMount`.
- *
- * After `createAndMount` runs, NavigationRoot renders and overwrites these
- * callbacks with its real `startTransition`-based implementations.
- */
-export function installDeferredNavigation(createAndMount: (initial: ReactNode) => void): void {
-  let mounted = false;
-  const mountOnce = (element: ReactNode) => {
-    if (mounted) return;
-    mounted = true;
-    createAndMount(element);
-  };
-  _transitionRender = (element: ReactNode) => {
-    mountOnce(element);
-  };
-  _navigateTransition = async (_url: string, perform: () => Promise<TransitionResult>) => {
-    const { element, commit } = await perform();
-    commit();
-    mountOnce(element);
-  };
-}