@timber-js/app 0.2.0-alpha.184 → 0.2.0-alpha.186

package/dist/client/navigation-api.d.ts

@@ -81,8 +81,8 @@ export interface NavigationApiController {
     /**
      * Resolve the deferred promise created by setRouterNavigating(true),
      * clearing the browser's native loading state. Call this when the
-     * navigation fully completes — aligned with when the TopLoader's
-     * pendingUrl clears (same finally block in router.navigate).
+     * navigation fully completes — the same finally block in router.navigate
+     * that clears the router's pending store.
      */
     completeRouterNavigation: () => void;
     /**

package/dist/client/navigation-commit.d.ts

@@ -0,0 +1,71 @@
+/**
+ * What it means for a page to be "current" on the client.
+ *
+ * One module owns every write that makes a navigation's destination the
+ * current page, and the read that describes the current page back to the
+ * server. Keeping them together is the point: `X-Timber-State-Tree` is
+ * derived from the segment cache, so the thing that publishes and the thing
+ * that reports have to agree about when a page becomes current.
+ *
+ * See design/19-client-navigation.md §"State Update Invariants".
+ */
+import { type SegmentCache } from './segment-cache.js';
+import type { HistoryStack } from './history.js';
+import type { SegmentInfo, StateTree } from '../shared/segment-info.js';
+import type { ParamsSource } from '../shared/payload-root.js';
+import { type NavigationState } from './navigation-context.js';
+/** Everything a commit needs to describe the page it makes current. */
+export interface NavigationCommitInput {
+    payload: unknown;
+    /** The params that payload published — replayed with it on popstate. */
+    params: ParamsSource;
+    /**
+     * The rendered chain's metadata, or null/undefined when this commit
+     * carries none at all — a revalidation payload, or a history entry
+     * stored before the channel existed.
+     *
+     * An empty *array* is a different statement from an absent one: the
+     * server rendered a route with no layout-bearing segments (a layoutless
+     * app — the missing-root-layout check is a warning, not an error), so
+     * the correct tree is the empty one. Collapsing the two left the
+     * departing route's tree in place, which `treePaths` then reported as
+     * mounted — enough to select an intercepting rewrite whose slot is not
+     * on screen (TIM-1282).
+     */
+    segmentInfo?: SegmentInfo[] | null;
+    /** When true, clear the segment cache if segmentInfo is absent
+     *  (popstate replay for entries without layout metadata). */
+    clearSegmentCacheOnEmpty?: boolean;
+}
+/**
+ * A navigation's destination, split into what a render needs and what a
+ * commit publishes.
+ */
+export interface PreparedNavigation {
+    /** The state the incoming tree renders with. Pure — safe before winning. */
+    navState: NavigationState;
+    /** Publishes the destination. Call only once the render has won. */
+    commit: () => void;
+}
+export interface NavigationCommitter {
+    prepareNavigation(url: string, opts: NavigationCommitInput): PreparedNavigation;
+    currentStateTree(): StateTree | undefined;
+    updateSegmentCache(segmentInfo: SegmentInfo[] | null | undefined): void;
+}
+/**
+ * Derive the navigation state (pathname + search) a URL renders with.
+ *
+ * Pure: publishing it — the module-level fallback for tests and SSR, and the
+ * globalThis bridge — is `prepareNavigation`'s commit, which runs only once
+ * the render is known to have won (TIM-1301). Callers pass the returned value
+ * explicitly to renderRoot/wrapPayload, so a render never depends on the
+ * publish having happened first.
+ */
+export declare function deriveNavigationState(url: string): NavigationState;
+export declare function createNavigationCommitter(deps: {
+    segmentCache: SegmentCache;
+    historyStack: HistoryStack;
+    /** Read at call time — the router's `clientSegmentCache` opt-in. */
+    clientSegmentCache: () => boolean | undefined;
+}): NavigationCommitter;
+//# sourceMappingURL=navigation-commit.d.ts.map

package/dist/client/navigation-commit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-commit.d.ts","sourceRoot":"","sources":["../../src/client/navigation-commit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAEnF,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,MAAM,EAAE,YAAY,CAAC;IACrB;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACnC;iEAC6D;IAC7D,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,QAAQ,EAAE,eAAe,CAAC;IAC1B,oEAAoE;IACpE,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,GAAG,kBAAkB,CAAC;IAChF,gBAAgB,IAAI,SAAS,GAAG,SAAS,CAAC;IAC1C,kBAAkB,CAAC,WAAW,EAAE,WAAW,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAAC;CACzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAQlE;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC9C,YAAY,EAAE,YAAY,CAAC;IAC3B,YAAY,EAAE,YAAY,CAAC;IAC3B,oEAAoE;IACpE,kBAAkB,EAAE,MAAM,OAAO,GAAG,SAAS,CAAC;CAC/C,GAAG,mBAAmB,CA0FtB"}

package/dist/client/navigation-context.d.ts

@@ -1,17 +1,19 @@
 /**
  * NavigationContext — React context for navigation state.
  *
- * Holds the current route params and pathname, updated atomically
- * with the RSC tree on each navigation. This replaces the previous
- * useSyncExternalStore approach for useSegmentParams() and usePathname(),
- * which suffered from a timing gap: the new tree could commit before
- * the external store re-renders fired, causing a frame where both
- * old and new active states were visible simultaneously.
+ * Holds the current pathname and search, updated atomically with the RSC
+ * tree on each navigation. This replaces the previous useSyncExternalStore
+ * approach for usePathname() and useSearchParams(), which suffered from a
+ * timing gap: the new tree could commit before the external store
+ * re-renders fired, causing a frame where both old and new active states
+ * were visible simultaneously.
+ *
+ * Segment params are NOT here — see the note on NavigationState below.
  *
  * By wrapping the RSC payload element in NavigationProvider inside
  * renderRoot(), the context value and the element tree are passed to
  * reactRoot.render() in the same call — atomic by construction.
- * All consumers (useParams, usePathname) see the new values in the
+ * All consumers (usePathname, useSearchParams) see the new values in the
  * same render pass as the new tree.
  *
  * During SSR, no NavigationProvider is mounted. Hooks fall back to
@@ -37,15 +39,24 @@
  * See design/19-client-navigation.md §"NavigationContext"
  */
 import React, { type ReactNode } from 'react';
+/**
+ * What the browser knows about the current location.
+ *
+ * Params are deliberately absent: they are a property of the tree the server
+ * rendered, not of the address bar, and they now travel inside the payload as
+ * the payload root. Keeping a copy here meant the router had to thread
+ * the record from a response header into context on every path — navigation,
+ * traversal, prefetch, revalidation — and each of those was a place to drop it
+ * (TIM-1294).
+ */
 export interface NavigationState {
-    params: Record<string, string | string[]>;
     pathname: string;
     search: string;
 }
 /**
  * Read the navigation context. Returns null during SSR (no provider)
  * or in the RSC environment (no context available).
- * Internal — used by useSegmentParams() and usePathname().
+ * Internal — used by usePathname() and useSearchParams().
  */
 export declare function useNavigationContext(): NavigationState | null;
 export interface NavigationProviderProps {
@@ -62,16 +73,22 @@ export declare function NavigationProvider({ value, children, }: NavigationProvi
 export declare function setNavigationState(state: NavigationState): void;
 export declare function getNavigationState(): NavigationState;
 /**
- * Read the pending navigation URL from context.
- * Returns null during SSR (no provider) or in the RSC environment.
- */
-export declare function usePendingNavigationUrl(): string | null;
-/**
- * Provider for the pending navigation URL. Wraps children with
- * the pending context Provider.
+ * There was a second React context here — `PendingNavigationContext`, holding
+ * the in-flight navigation URL, provided by `NavigationRoot` out of a
+ * `useState` — plus a `usePendingNavigationUrl()` reader for it. Both are gone
+ * (TIM-1307).
+ *
+ * Nothing read them. `usePendingNavigation()` (use-pending-navigation.ts) and
+ * `TopLoader` both subscribe to the router's external pending store via
+ * `useSyncExternalStore`: sync priority, immune to transition entanglement,
+ * and cleared by `runNavigation`'s supersession-guarded `finally` (TIM-1034).
+ * The context was a parallel representation of the same fact that no consumer
+ * ever migrated to, and one that could not even agree with the store — a
+ * navigation superseded by a cached popstate replay left its URL set until the
+ * next full navigation, because the staleness guard skipped the clear and no
+ * other path touched it.
+ *
+ * One representation, and it is the router's. See
+ * design/19-client-navigation.md §"How Pending State Works".
  */
-export declare function PendingNavigationProvider({ value, children, }: {
-    value: string | null;
-    children?: ReactNode;
-}): React.ReactElement;
 //# sourceMappingURL=navigation-context.d.ts.map

package/dist/client/navigation-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation-context.d.ts","sourceRoot":"","sources":["../../src/client/navigation-context.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAM7D,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AA2CD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,GAAG,IAAI,CAO7D;AAMD,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,KAAK,EACL,QAAQ,GACT,EAAE,uBAAuB,GAAG,KAAK,CAAC,YAAY,CAO9C;AA6BD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAE/D;AAED,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD;AA8BD;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAMvD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB,GAAG,KAAK,CAAC,YAAY,CAMrB"}
+{"version":3,"file":"navigation-context.d.ts","sourceRoot":"","sources":["../../src/client/navigation-context.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAO7D;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAsCD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,GAAG,IAAI,CAO7D;AAMD,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,KAAK,EACL,QAAQ,GACT,EAAE,uBAAuB,GAAG,KAAK,CAAC,YAAY,CAO9C;AA6BD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAE/D;AAED,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD;AAMD;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/client/navigation-root.d.ts

@@ -9,14 +9,18 @@
  * 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
- * any new Suspense boundaries in the transition resolve.
+ * the new tree resolves, instead of hiding it behind a Suspense fallback.
  *
- * Also manages `pendingUrl` as React state with an urgent/transition split:
- * - Navigation START: `setPendingUrl(url)` is an urgent update — React
- *   commits it before the next paint, showing the spinner immediately.
- * - Navigation END: `setPendingUrl(null)` is inside `startTransition`
- *   alongside `setElement(newTree)` — both commit atomically, so the
- *   spinner disappears in the same frame as the new content appears.
+ * 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).
+ *
+ * This component holds no pending state. The `TopLoader` it renders and the
+ * public `usePendingNavigation()` both subscribe to the router's external
+ * pending store; NavigationRoot's own `pendingUrl` was a second, unread
+ * representation of the same fact and is gone (TIM-1307).
  *
  * Hard navigation guard: When a hard navigation is triggered (500 error,
  * version skew), the component throws an unresolved thenable AFTER all
@@ -32,6 +36,32 @@
  */
 import { type ReactNode } from 'react';
 import { type TopLoaderConfig } from './top-loader.js';
+/**
+ * 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;
+}
 /**
  * Invalidate all in-flight navigation transitions. Any navigateTransition()
  * call whose perform() has not yet committed will reject with AbortError
@@ -61,9 +91,8 @@ export declare function isHardNavigating(): boolean;
 /**
  * Root wrapper component that enables transition-based rendering.
  *
- * Renders PendingNavigationProvider around children for the pending URL
- * context. The DOM tree matches the server-rendered HTML during hydration
- * (the provider renders no extra DOM elements).
+ * 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 });
@@ -88,22 +117,33 @@ export declare function NavigationRoot({ initial, topLoaderConfig, }: {
  */
 export declare function transitionRender(element: ReactNode): void;
 /**
- * Run a full navigation inside a React transition with optimistic pending URL.
- *
- * The `perform` callback runs inside `startTransition` — it should fetch the
- * RSC payload, update router state, and return the wrapped React element.
- * The pending URL shows immediately (urgent update) and reverts
- * to null when the transition commits (atomic with the new tree).
- *
- * Returns a Promise that resolves when the async work completes (note: the
- * React transition may not have committed yet, but all state updates are done).
+ * 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 declare function navigateTransition(pendingUrl: string, perform: () => Promise<{
-    element: ReactNode;
-    decodePromise: Promise<void> | null;
-}>): Promise<void>;
+export declare function navigateTransition(url: string, perform: () => Promise<TransitionResult>): Promise<void>;
 /**
  * Install one-shot deferred callbacks for the no-RSC bootstrap path (TIM-600).
  *

package/dist/client/navigation-root.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation-root.d.ts","sourceRoot":"","sources":["../../src/client/navigation-root.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAsD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAE3F,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAyBlE;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,IAAI,IAAI,CAErD;AA8BD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAoCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,eAAe,GAChB,EAAE;IACD,OAAO,EAAE,SAAS,CAAC;IACnB,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC,GAAG,SAAS,CAyGZ;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAIzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,OAAO,CAAC;IAAE,OAAO,EAAE,SAAS,CAAC;IAAC,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAAE,CAAC,GAClF,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,CAAC,OAAO,EAAE,SAAS,KAAK,IAAI,GAAG,IAAI,CAiB5F"}
+{"version":3,"file":"navigation-root.d.ts","sourceRoot":"","sources":["../../src/client/navigation-root.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAIlE;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,SAAS;IAC7C,kCAAkC;IAClC,OAAO,EAAE,CAAC,CAAC;IACX,kEAAkE;IAClE,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpC;;;;;;;;;;OAUG;IACH,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AA4DD;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,IAAI,IAAI,CAErD;AA6ED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAmCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,eAAe,GAChB,EAAE;IACD,OAAO,EAAE,SAAS,CAAC;IACnB,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC,GAAG,SAAS,CAoMZ;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAIzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,GACvC,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,CAAC,OAAO,EAAE,SAAS,KAAK,IAAI,GAAG,IAAI,CAe5F"}

package/dist/client/params-context.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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()`.
+ */
+import React from 'react';
+import { type PublishedParams } from '../shared/payload-root.js';
+import type { SlotParamsRecord } from '../shared/slot-params.js';
+export type ParamsContextValue = PublishedParams;
+/**
+ * Read the params provided by the tree. Returns null when no provider is
+ * above the caller — a component rendered outside a timber route, a
+ * `useSegmentParams()` call from outside React entirely, or any component
+ * during SSR (where the params reach the hook through the ALS-backed SSR data
+ * context instead, and there is no client-owned tree to hold a provider).
+ */
+export declare function useParamsContext(): ParamsContextValue | null;
+interface ParamsProviderProps {
+    params: Record<string, string | string[]>;
+    slotParams: SlotParamsRecord | null;
+    children?: React.ReactNode;
+}
+/**
+ * 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 declare function PayloadRoot({ source, children }: {
+    source: unknown;
+    children?: React.ReactNode;
+}): React.FunctionComponentElement<ParamsProviderProps>;
+export {};
+//# sourceMappingURL=params-context.d.ts.map

package/dist/client/params-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"params-context.d.ts","sourceRoot":"","sources":["../../src/client/params-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,KAAsC,MAAM,OAAO,CAAC;AAG3D,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAIjE,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAmDjD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,kBAAkB,GAAG,IAAI,CAE5D;AAID,UAAU,mBAAmB;IAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B;AA0CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,WAAW,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,uDAIhG"}

package/dist/client/router-effects.d.ts

@@ -0,0 +1,129 @@
+/**
+ * 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"
+ */
+/** 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 declare function createScrollEffects(deps: ScrollEffectDeps): ScrollEffects;
+/**
+ * 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 declare function leaveSpa(url: string, fromUrl: string): Promise<never>;
+export interface SpaExitDeps {
+    /** The controller that owns the router right now, or null when idle. */
+    currentNavAbort: () => AbortController | null;
+    /** Supersede whatever is in flight and take ownership. */
+    supersede: () => void;
+}
+export interface SpaExits {
+    /**
+     * Leave the SPA — but only if `navAbort` 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: (navAbort: AbortController, 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 declare function createSpaExits({ currentNavAbort, supersede }: SpaExitDeps): SpaExits;
+export interface NavigationRecoveryDeps {
+    /** The controller that owns the router right now, or null when idle. */
+    currentNavAbort: () => AbortController | 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 declare function createNavigationRecovery({ currentNavAbort, leaveSpaIfOwned, navigate, }: NavigationRecoveryDeps): (error: unknown, navAbort: AbortController, url: string, fromUrl: string) => Promise<boolean>;
+/**
+ * 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 declare function hardNavigate(url: string, fromUrl: string): void;
+//# sourceMappingURL=router-effects.d.ts.map

package/dist/client/router-effects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-effects.d.ts","sourceRoot":"","sources":["../../src/client/router-effects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IAC5C,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1C;AAED,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,uBAAuB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD;;;;;OAKG;IACH,sBAAsB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,GAAG,aAAa,CA2BzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAIrE;AAED,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,eAAe,EAAE,MAAM,eAAe,GAAG,IAAI,CAAC;IAC9C,0DAA0D;IAC1D,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB;;;;;;;;;;;;OAYG;IACH,eAAe,EAAE,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5F;;;;;;;;OAQG;IACH,mBAAmB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC;CACvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,EAAE,eAAe,EAAE,SAAS,EAAE,EAAE,WAAW,GAAG,QAAQ,CAgBpF;AAED,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,eAAe,EAAE,MAAM,eAAe,GAAG,IAAI,CAAC;IAC9C,eAAe,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAC;IAC7C,4EAA4E;IAC5E,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,wBAAwB,CAAC,EACvC,eAAe,EACf,eAAe,EACf,QAAQ,GACT,EAAE,sBAAsB,WAEd,OAAO,YACJ,eAAe,OACpB,MAAM,WACF,MAAM,KACd,OAAO,CAAC,OAAO,CAAC,CAsBpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAS/D"}

package/dist/client/router-lifecycle.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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.
+ *
+ * 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").
+ *
+ * See design/19-client-navigation.md §"How Pending State Works".
+ */
+/** 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 controller that owns the router right now, or null when idle. */
+    currentNavAbort: () => AbortController | null;
+    /**
+     * Take ownership of the router, superseding whatever held it. See the
+     * implementation for the three parts of superseding.
+     */
+    createNavAbort: (externalSignal?: AbortSignal) => AbortController;
+    /**
+     * 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>, 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;
+    /** React has committed `owner`'s tree — every earlier handoff is off screen. */
+    forgetOlderHandoffs: (owner: AbortController) => 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;
+}
+export declare function createNavigationLifecycle(deps: NavigationLifecycleDeps): NavigationLifecycle;
+//# sourceMappingURL=router-lifecycle.d.ts.map

package/dist/client/router-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-lifecycle.d.ts","sourceRoot":"","sources":["../../src/client/router-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,iEAAiE;AACjE,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,MAAM,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,eAAe,EAAE,MAAM,eAAe,GAAG,IAAI,CAAC;IAC9C;;;OAGG;IACH,cAAc,EAAE,CAAC,cAAc,CAAC,EAAE,WAAW,KAAK,eAAe,CAAC;IAClE;;;OAGG;IACH,aAAa,EAAE,CACb,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,EAChD,cAAc,CAAC,EAAE,WAAW,KACzB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB;;;OAGG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IAChD,gFAAgF;IAChF,mBAAmB,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IAEtD,mDAAmD;IACnD,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,6DAA6D;IAC7D,aAAa,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACnC,0CAA0C;IAC1C,eAAe,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CACvE;AAYD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,uBAAuB,GAAG,mBAAmB,CAqN5F"}