@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/src/client/navigation-transition.ts

@@ -0,0 +1,327 @@
+/**
+ * Navigation transition — the router-level hand-off of a navigation's tree to
+ * React, and the supersession that governs it.
+ *
+ * `navigateTransition` runs a navigation's fetch OUTSIDE any transition scope
+ * and hands the resulting tree to React through a `NavigationRender`, which
+ * is a synchronous `startTransition` around `root.render` (client/react-root.ts).
+ * 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(() => render(x))                     -> 'HOME' held
+ *      startTransition(async () => { await p; render(x) })  -> fallback shown
+ *
+ *    Left uncorrected, every navigation whose new tree suspends replaces the
+ *    visible page with a Suspense fallback — the exact thing NavigationRoot
+ *    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 holds for
+ * ALL of them. It used not to hold for `<Link>`, which wrapped
+ * `router.navigate()` in its own `useTransition`: that action scope entangled
+ * the root'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 deliberate:
+ * the hook's is tied to a single fiber and tracks one async callback at a
+ * time, and two overlapping navigations through it corrupted React's hook
+ * tracking ("Rendered more hooks than during the previous render"). Each
+ * navigation needs an independent lane. This matches the Next.js pattern
+ * (TIM-625): "No useTransition in the router at all — only standalone
+ * startTransition."
+ *
+ * See design/19-client-navigation.md §"How Pending State Works"
+ */
+
+import type { ReactNode } from 'react';
+import type { NavigationRender } from './navigation-root.tsx';
+
+// ─── Transition Result ──────────────────────────────────────────
+
+/**
+ * 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.
+ */
+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;
+  /**
+   * 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).
+   */
+  commit: () => void;
+}
+
+/** What happened to this navigation's tree. */
+export type CommitOutcome = 'committed' | 'superseded' | 'failed';
+
+// ─── RenderOwner ────────────────────────────────────────────────
+
+/**
+ * A per-render identity that replaces the transition counter, the
+ * `handedOffNavAborts` set, and the `AbortController`-as-owner pattern.
+ *
+ * The navigation lifecycle holds one slot (`current: RenderOwner | null`).
+ * All supersession is "take the slot":
+ *
+ *   - Navigation takes unconditionally (previous owner gets settled + aborted
+ *     if !handedOff).
+ *   - Revalidation takes only if empty (epoch check).
+ *   - Handover gate before root.render checks `current === owner`.
+ *   - `settle()` is called from NavigationRoot publish (committed), slot
+ *     takeover (superseded), or rejection (failed).
+ *
+ * `settle()` records the outcome and resolves `displaced` for non-committed
+ * outcomes. The `outcome` field is first-wins with one exception:
+ * `settle('superseded')` overrides a prior `'committed'`, because a
+ * committed-but-still-decoding navigation can be displaced by a successor
+ * and the post-decode check must throw rather than letting the old
+ * navigation continue.
+ *
+ * TIM-1481: replaces counter + waiters + bumpTransitionCounter +
+ * supersedeNavigationTransitions + handedOffNavAborts + globalThis singleton.
+ */
+export interface RenderOwner {
+  readonly kind: 'navigation' | 'revalidation';
+  readonly fetchAbort: AbortController;
+  handedOff: boolean;
+  /** Sync read for the post-perform() check. null until settled. */
+  outcome: CommitOutcome | null;
+  /**
+   * Resolves when this owner is displaced — a successor supersedes it or it
+   * fails. Does NOT resolve on commit: a committed navigation still waits
+   * for its decode to finish. Used to stop waiting on a decode that is no
+   * longer this navigation's business.
+   */
+  readonly displaced: Promise<void>;
+  /**
+   * Record this owner's outcome and, for non-committed outcomes, resolve
+   * `displaced`. First-wins with one exception: `settle('superseded')`
+   * overrides a prior `'committed'`.
+   */
+  settle: (outcome: CommitOutcome) => void;
+}
+
+/**
+ * Create a fresh RenderOwner. Exported so tests that call
+ * `navigateTransition` directly can construct one without a router.
+ */
+export function createRenderOwner(kind: 'navigation' | 'revalidation'): RenderOwner {
+  let resolveDisplaced!: () => void;
+  const displaced = new Promise<void>((r) => {
+    resolveDisplaced = r;
+  });
+
+  const owner: RenderOwner = {
+    kind,
+    fetchAbort: new AbortController(),
+    handedOff: false,
+    outcome: null,
+    displaced,
+    settle(outcome: CommitOutcome): void {
+      if (owner.outcome === null) {
+        owner.outcome = outcome;
+      } else if (outcome === 'superseded' && owner.outcome === 'committed') {
+        // A committed-but-still-decoding navigation can be displaced by a
+        // successor. Override so the post-decode check throws AbortError
+        // rather than letting the old navigation continue with scroll
+        // restoration while a newer navigation is active.
+        owner.outcome = 'superseded';
+      }
+      // Resolve `displaced` for any non-committed outcome, even if the
+      // outcome field was already set. A committed-but-still-decoding
+      // navigation must be woken when a successor supersedes it — the old
+      // counter-based waiter did this because the counter bumped regardless
+      // of commit state. A commit does NOT resolve displaced: that would
+      // end the decode wait early, clearing pending state before the Flight
+      // stream finishes.
+      if (outcome !== 'committed') {
+        resolveDisplaced();
+      }
+    },
+  };
+  return owner;
+}
+
+// ─── navigateTransition ─────────────────────────────────────────
+
+/**
+ * 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 `render` that hands its result over
+ * is wrapped, in a synchronous `startTransition` (see the module comment).
+ *
+ * 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()`.
+ *
+ * Rejects with an `AbortError` when a newer transition started while this
+ * one's `perform()` was in flight — the stale tree is never handed to React
+ * and its `commit` never runs (TIM-629, TIM-1301).
+ *
+ * `onCommit` is the caller's hook on the *commit*, which the returned promise
+ * deliberately does not wait for. It runs exactly once: when React commits
+ * this navigation's tree, or — so nothing waits on a commit that will never
+ * come — when the navigation is abandoned instead: superseded by a newer
+ * transition (before or after its tree was handed to React) or failed. It is
+ * how `<Link>` keeps `isPending` up until the destination is on screen
+ * without scheduling anything against React's lanes (TIM-1418).
+ *
+ * `owner` is the `RenderOwner` for this render (TIM-1481). Supersession is
+ * detected via `owner.outcome` (sync) and `owner.displaced` (async).
+ * No module-level state; no globalThis singleton.
+ *
+ * Used for: navigate(), refresh(), popstate with fetch.
+ */
+export function navigateTransition(
+  owner: RenderOwner,
+  perform: () => Promise<TransitionResult>,
+  render: NavigationRender,
+  onCommit?: (outcome: CommitOutcome) => void
+): Promise<void> {
+  const superseded = () => new DOMException('Navigation superseded', 'AbortError');
+
+  // `onCommit`, exactly once, on whichever comes first: the commit, a
+  // supersession, or a failure.
+  let commitSettled = onCommit === undefined;
+  const settleCommit = (outcome: CommitOutcome): void => {
+    if (commitSettled) return;
+    commitSettled = true;
+    onCommit?.(outcome);
+  };
+
+  // Watch for displacement from outside (a successor taking the slot).
+  if (!commitSettled) {
+    void owner.displaced.then(() => {
+      if (owner.outcome === 'superseded') settleCommit('superseded');
+    });
+  }
+
+  return (async () => {
+    try {
+      const { element, decodePromise, commit } = await perform();
+      if (owner.outcome !== null) {
+        decodePromise?.catch(() => {});
+        throw superseded();
+      }
+      // Hand the tree over with its commit attached. NavigationRoot 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);
+      // `render` is the synchronous transition around `root.render`.
+      render(element, () => {
+        try {
+          commit();
+        } finally {
+          settleCommit('committed');
+        }
+      });
+      // 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.
+      if (decodePromise) {
+        await settleOnDecodeOrDisplacement(decodePromise, owner);
+      }
+      if (owner.outcome !== null && owner.outcome !== 'committed') {
+        throw superseded();
+      }
+    } catch (error) {
+      settleCommit('failed');
+      throw error;
+    }
+  })();
+}
+
+/**
+ * Wait for the payload to finish decoding, OR for this owner to be
+ * displaced — whichever happens first.
+ *
+ * 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
+ * `RenderOwner.handedOff`), 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.
+ */
+function settleOnDecodeOrDisplacement(
+  decodePromise: Promise<void>,
+  owner: RenderOwner
+): Promise<void> {
+  // Only bail early for displacement (superseded/failed), not for commit.
+  // A committed tree still needs to wait for its decode to finish — pending
+  // state and the Link indicator are timed against it.
+  if (owner.outcome !== null && owner.outcome !== 'committed') {
+    return Promise.resolve();
+  }
+  return Promise.race([decodePromise, owner.displaced]);
+}

package/src/client/nuqs-adapter.tsx

@@ -19,7 +19,9 @@ import {
   type unstable_AdapterInterface as AdapterInterface,
   type unstable_AdapterOptions as AdapterOptions,
 } from 'nuqs/adapters/custom';
-import { getRouter } from './router-ref.js';
+import { getRouter } from './router-ref.ts';
+import { getNavigationApi } from './navigation-api.ts';
+import { locationSearch } from './location-search.ts';
 
 // ─── Adapter Hook ─────────────────────────────────────────────────
 
@@ -31,15 +33,13 @@ import { getRouter } from './router-ref.js';
  *   (used by nuqs for selective re-rendering)
  */
 function useTimberAdapter(_watchKeys: string[]): AdapterInterface {
-  const [searchParams, setSearchParams] = useState(
-    () => new URLSearchParams(window.location.search)
-  );
+  const [searchParams, setSearchParams] = useState(() => new URLSearchParams(locationSearch()));
 
   // Sync search params on popstate (back/forward) and after
   // timber navigations that change the URL.
   useEffect(() => {
     function sync() {
-      setSearchParams(new URLSearchParams(window.location.search));
+      setSearchParams(new URLSearchParams(locationSearch()));
     }
 
     window.addEventListener('popstate', sync);
@@ -59,9 +59,21 @@ function useTimberAdapter(_watchKeys: string[]): AdapterInterface {
 
       if (options.shallow) {
         // Shallow: update URL only, no server roundtrip.
-        const method =
-          options.history === 'push' ? window.history.pushState : window.history.replaceState;
-        method.call(window.history, window.history.state, '', url.toString());
+        // When Navigation API is available, use navigation.navigate() with
+        // info: { shallow: true } so the navigate event handler knows to
+        // skip interception. Without this, the navigate event fired by
+        // history.pushState/replaceState would trigger a full RSC fetch.
+        const nav = getNavigationApi();
+        if (nav) {
+          nav.navigate(url.toString(), {
+            history: options.history === 'push' ? 'push' : 'replace',
+            info: { shallow: true },
+          });
+        } else {
+          const method =
+            options.history === 'push' ? window.history.pushState : window.history.replaceState;
+          method.call(window.history, window.history.state, '', url.toString());
+        }
 
         // Update local state to reflect the new URL
         setSearchParams(new URLSearchParams(url.search));
@@ -84,7 +96,7 @@ function useTimberAdapter(_watchKeys: string[]): AdapterInterface {
   return {
     searchParams,
     updateUrl,
-    getSearchParamsSnapshot: () => new URLSearchParams(window.location.search),
+    getSearchParamsSnapshot: () => new URLSearchParams(locationSearch()),
   };
 }
 

package/src/client/params-context.ts

@@ -0,0 +1,187 @@
+/**
+ * Segment params context — the one channel params use to reach the browser.
+ *
+ * Params ride the RSC payload's root row as a sibling of the tree
+ * (`{ tree, params, slotParams }`), rather than in four side channels that
+ * raced to seed them: a response header, an inline script, and two build-time
+ * manifest fields all previously carried the same record, each with its own
+ * `JSON.stringify` (TIM-1294).
+ *
+ * Riding the payload is what makes them *typed*. `defineSchema` takes any
+ * `Codec<T>`, so a coerced param is whatever the codec returned — a `Date`, a
+ * `bigint` — and `JSON.stringify` either flattened it to a string or threw
+ * mid-response. React Flight carries those values natively, so the client
+ * reads the value the server produced instead of a lossy copy of it. See
+ * design/41-global-params.md §"Transport".
+ *
+ * **The client owns the provider.** There is exactly one `ParamsProvider` in
+ * the browser's tree, rendered by `PayloadRoot` above the point where a
+ * partial navigation splices the new payload into the retained tree. It has to
+ * be there and it has to be alone: a provider *inside* the payload lands below
+ * the retained region, whose own root is the departing route's provider, so
+ * every reader in a skipped layout resolves to the departing record and no
+ * amount of wrapping above it helps (TIM-1297).
+ *
+ * Ordering still holds without a bootstrap contract, for the same reason it
+ * did when the provider was in the tree: a provider renders before its own
+ * descendants by construction, so `useSegmentParams()` is correct during
+ * hydration without anything having to run before `hydrateRoot()`.
+ */
+
+'use client';
+
+import React, { createElement, useMemo, use } from 'react';
+import { toNullProtoRecord, type CoercedParams } from '../shared/param-value.ts';
+import { readPublishedParams, type PublishedParams } from '../shared/payload-root.ts';
+import type { SlotParamsRecord } from '../shared/slot-params.ts';
+
+// ─── Types ───────────────────────────────────────────────────────
+
+export type ParamsContextValue = PublishedParams;
+
+// ─── Context ─────────────────────────────────────────────────────
+
+/**
+ * SINGLETON GUARANTEE: globalThis + `Symbol.for`, the same pattern as
+ * `NavigationContext` and `SegmentUpdateContext`.
+ *
+ * The RSC client bundler can duplicate a module across chunks, and with ESM
+ * output each chunk gets its own module scope — so a bare `createContext` at
+ * module level yields one context per chunk. This module is now reached from
+ * *both* graphs: `PayloadRoot` is imported by the browser entry, while
+ * `useParamsContext()` arrives through the client-reference graph with the
+ * app's own components. A duplicate would put the provider on instance A and
+ * every reader on instance B, so `useContext` returns `null` and every
+ * `useSegmentParams()` call throws the outside-the-timber-app-tree error
+ * even though the provider is mounted (the module-snapshot fallback it once
+ * silently landed on was deleted in TIM-1425).
+ *
+ * This module was the one client context without the guard — harmless while
+ * the provider travelled inside the payload, in the same graph as its readers,
+ * and load-bearing the moment the client started rendering it (TIM-1297).
+ *
+ * The React APIs are reached through the namespace rather than named imports,
+ * for the same reason `segment-update-context.ts` and `navigation-context.ts`
+ * do it: React's `react-server` export provides neither `createContext` nor
+ * `useContext`, and a *named* ESM import of a missing export fails at module
+ * instantiation — before any feature check could run. This module is reachable
+ * from every entry a Server Component imports, so the named form crashed
+ * those entries outright (codex, PR #992; originally reproduced against
+ * `@timber-js/app/segment-params`, an entry point since deleted by TIM-1342 —
+ * the hazard is unchanged for the entries that remain).
+ *
+ * See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
+ */
+const PARAMS_CTX_KEY = Symbol.for('__timber_params_ctx');
+
+function getOrCreateContext(): React.Context<ParamsContextValue | null> {
+  const store = globalThis as Record<symbol, unknown>;
+  const existing = store[PARAMS_CTX_KEY] as React.Context<ParamsContextValue | null> | undefined;
+  if (existing !== undefined) return existing;
+  if (typeof React.createContext !== 'function') {
+    // RSC environment — no contexts here. Nothing in this module runs on that
+    // side; it only has to import cleanly.
+    return undefined as unknown as React.Context<ParamsContextValue | null>;
+  }
+  const ctx = React.createContext<ParamsContextValue | null>(null);
+  store[PARAMS_CTX_KEY] = ctx;
+  return ctx;
+}
+
+const ParamsContext = getOrCreateContext();
+
+/**
+ * Read the params provided by the tree. Returns null only when no provider
+ * is above the caller — a component rendered outside a timber route. During
+ * SSR the wrapper chain mounts `PayloadRoot` too (TIM-1424), so both sides
+ * resolve through this context.
+ */
+export function useParamsContext(): ParamsContextValue | null {
+  return React.useContext(ParamsContext);
+}
+
+// ─── Provider ────────────────────────────────────────────────────
+
+interface ParamsProviderProps {
+  params: CoercedParams;
+  slotParams: SlotParamsRecord | null;
+  children?: React.ReactNode;
+}
+
+/**
+ * Provides the current navigation's params to everything below it.
+ *
+ * Rendered only by `PayloadRoot`. Not exported: a second provider anywhere in
+ * the tree would shadow this one for the region below it, which is precisely
+ * the defect TIM-1297 fixed.
+ *
+ * This used to also write a module-level snapshot during render, as the
+ * fallback for `useSegmentParams()` called outside a component. That tier is
+ * gone (TIM-1425) — the provider is unconditional on every render path,
+ * browser and SSR alike, so the hook reads context or throws. Removing the
+ * write also removes render-phase shared mutation from the SSR environment,
+ * where concurrent requests rendered through this component.
+ */
+function ParamsProvider({ params, slotParams, children }: ParamsProviderProps) {
+  // Restore the null prototype the wire could not carry. Flight rejects a
+  // null-prototype object, so `withPublishedParams` flattens the records;
+  // rebuilding them here is what keeps `params.constructor` returning
+  // `undefined` instead of a function for a param the route does not define
+  // (design/13-security.md #36c). Memoized on the props so a re-render with
+  // the same records does not rebuild — the identity of what the hook returns
+  // is load-bearing for `useEffect` dependencies (TIM-1285).
+  const value = useMemo(
+    () => ({
+      params: toNullProtoRecord(params),
+      slotParams: toNullProtoRecord(slotParams),
+    }),
+    [params, slotParams]
+  );
+
+  return createElement(ParamsContext.Provider, { value }, children);
+}
+
+// ─── Payload root ────────────────────────────────────────────────
+
+/**
+ * The client's root: publishes a payload's params over the tree being shown.
+ *
+ * Rendered at the same position in the wrapper chain on **every** render path
+ * — hydration, full navigation, partial navigation, popstate replay, shallow
+ * search sync, and revalidation from a server action. Being unconditional is
+ * load-bearing twice over: an element type that appears on one render and not
+ * the next remounts everything below it, destroying exactly the layout state a
+ * partial navigation exists to preserve; and a reader in a skipped layout has
+ * to have *some* provider above it on every path or it falls back to the
+ * module-level snapshot.
+ *
+ * `children` is the tree to display, which is not always `source`'s tree:
+ *
+ * - Full navigation, hydration, replay — `source` is the payload being shown,
+ *   and `children` is its own tree.
+ * - **Partial navigation** — `children` is the *retained* tree and `source` is
+ *   the *incoming* payload. This is the case the whole design exists for: the
+ *   retained tree is not re-rendered, so the destination's params can only
+ *   reach it from above, and this provider is above it.
+ *
+ * `source` may be a thenable, in which case this suspends on the payload's
+ * root row. That happens on the hydration path only, where the payload
+ * promise was going to be rendered at this position anyway. Every other path
+ * resolves the row in the router — inside the navigation transition — and
+ * hands over a settled value, so a decode rejection surfaces where React
+ * renders the tree and is caught by the error boundary *around* it, rather
+ * than here, above every boundary the app has.
+ */
+export function PayloadRoot({ source, children }: { source: unknown; children?: React.ReactNode }) {
+  const resolved = isThenable(source) ? use(source) : source;
+  const { params, slotParams } = readPublishedParams(resolved);
+  return createElement(ParamsProvider, { params, slotParams }, children);
+}
+
+function isThenable(value: unknown): value is Promise<unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { then?: unknown }).then === 'function'
+  );
+}

package/src/client/react-root.ts

@@ -0,0 +1,72 @@
+/**
+ * React root host — the one React root the router renders the page through.
+ *
+ * The router owns the displayed tree and drives React: every render is
+ * `startTransition(() => root.render(<NavigationRoot rendered={…} />))`,
+ * synchronous, with a fresh `rendered` object whose `publish` NavigationRoot
+ * runs when React commits that tree (TIM-1301, TIM-1431).
+ *
+ * The root itself is created lazily. On the RSC-payload path `hydrate()`
+ * creates it by hydrating the server HTML. On the JS-only path (no inlined
+ * payload, TIM-600) nothing may create it at bootstrap — `createRoot(document)`
+ * followed by a render would take React ownership of the document and blank
+ * the SSR HTML — so the first `render()` (the first navigation, or a
+ * revalidation after a server action) creates it with the tree it renders.
+ * That first render carries no placeholder, and a fresh root with nothing
+ * committed leaves the container alone until it can commit, so the SSR HTML
+ * stays until the destination is ready (TIM-580).
+ *
+ * `container` is `document` in production; tests pass an element.
+ */
+
+import { createElement, startTransition, type ReactNode } from 'react';
+import { createRoot, hydrateRoot, type HydrationOptions, type Root } from 'react-dom/client';
+import { NavigationRoot, type NavigationRender, type RenderedTree } from './navigation-root.tsx';
+import type { TopLoaderConfig } from './top-loader.tsx';
+
+export interface ReactRootHost {
+  /**
+   * Hydrate the server HTML with `element` as the initial tree. Nothing is
+   * published on that commit — the address bar, pathname and history already
+   * describe the page the server sent.
+   */
+  hydrate(element: ReactNode, options?: HydrationOptions): void;
+  /**
+   * Hand a tree to React in a synchronous transition; `publish` runs when
+   * React commits it. Creates the root on first use.
+   */
+  render: NavigationRender;
+  /** Tear the root down (tests). */
+  unmount(): void;
+}
+
+export function createReactRoot(options: {
+  container: Document | Element;
+  topLoaderConfig?: TopLoaderConfig;
+}): ReactRootHost {
+  const { container, topLoaderConfig } = options;
+  let root: Root | null = null;
+
+  const rootElement = (rendered: RenderedTree) =>
+    createElement(NavigationRoot, { rendered, topLoaderConfig });
+
+  return {
+    hydrate(element, hydrationOptions) {
+      root = hydrateRoot(container, rootElement({ element, publish: null }), hydrationOptions);
+    },
+    render(element, publish) {
+      const target = (root ??= createRoot(container));
+      // Synchronous, and returns nothing: an async callback would drop the
+      // transition scope at its first await, and a returned thenable would
+      // open an action scope that holds the commit until it settles
+      // (TIM-1306, TIM-1307 — see client/navigation-transition.ts).
+      startTransition(() => {
+        target.render(rootElement({ element, publish }));
+      });
+    },
+    unmount() {
+      root?.unmount();
+      root = null;
+    },
+  };
+}