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

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

@@ -0,0 +1,98 @@
+/**
+ * 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.ts';
+import type { HistoryStack } from './history.ts';
+import type { SegmentInfo, StateTree } from '../shared/segment-info.ts';
+import type { ParamsSource } from '../shared/payload-root.ts';
+import { type NavigationState } from './navigation-context.ts';
+/**
+ * Record that a status page for the main route is on screen. Called from
+ * `StatusPageMarker`'s layout effect; consumed by the commit of the
+ * navigation whose tree it belongs to, and acted on immediately for the
+ * commits that have none.
+ */
+export declare function reportStatusPageRendered(): void;
+/** 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;
+    /**
+     * Layouts the server skipped on this response (`X-Timber-Skipped-Segments`),
+     * when it came from a fetch. Omitted by replays and revalidation.
+     *
+     * Together with `skipped` slot entries in `segmentInfo`, this decides
+     * whether the payload can be *replayed*. A partial payload only renders
+     * merged over the tree on screen, and a `skip=true` outlet resolves against
+     * the slot content cache at render time — so a stored copy of either,
+     * replayed later, shows whatever the client holds *then*, not what was on
+     * screen when the entry committed. Such entries store a null payload and
+     * traversals to them fetch instead. Decided here, not at the fetch call
+     * sites, because there are three of those (`performNavigationFetch`,
+     * `refresh()`, and uncached traversal) and a rule applied at one of them
+     * holds by accident: `performNavigationFetch` had the check and
+     * `fetchCommitAndRender` did not, so a back/forward fetch that was
+     * answered with skips stored the holes (TIM-1432).
+     */
+    skippedSegments?: string[] | null;
+}
+/** Whether a response skipped layouts — its payload merges over the tree on screen. */
+export declare function isPartialNavigation(skippedSegments: string[] | null | undefined): 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;AA2CnF;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAG/C;AAED,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;IACnC;;;;;;;;;;;;;;;;OAgBG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CACnC;AAED,uFAAuF;AACvF,wBAAgB,mBAAmB,CAAC,eAAe,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAEzF;AA0BD;;;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,CAgHtB"}

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

@@ -1,27 +1,30 @@
 /**
  * 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 useParams() 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
- * the ALS-backed getSsrData() for per-request isolation.
+ * During SSR, the wrapper chain mounts this same provider with the
+ * request's pathname and raw search string (TIM-1424), so the hooks
+ * resolve through the identical code path on both sides. Per-request
+ * isolation is by construction — the value is part of the request's
+ * element tree.
  *
- * IMPORTANT: createContext and useContext are NOT available in the RSC
- * environment (React Server Components use a stripped-down React).
- * The context is lazily initialized on first access, and all functions
- * that depend on these APIs are safe to call from any environment —
- * they return null or no-op when the APIs aren't available.
+ * This module is `'use client'` and is never evaluated in the RSC
+ * environment. The shims plugin resolves next/navigation to
+ * navigation-rsc.ts in RSC, which has throwing stubs (TIM-1420).
  *
  * SINGLETON GUARANTEE: All shared mutable state uses globalThis via
  * Symbol.for keys. The RSC client bundler can duplicate this module
@@ -36,15 +39,26 @@
  *
  * See design/19-client-navigation.md §"NavigationContext"
  */
-import React, { type ReactNode } from 'react';
+import { 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 useParams() and usePathname().
+ * Read the navigation context. Returns null only when no provider is above
+ * the caller — a component rendered outside the timber app.
+ *
+ * Internal — used by usePathname() and useSearchParams().
  */
 export declare function useNavigationContext(): NavigationState | null;
 export interface NavigationProviderProps {
@@ -57,20 +71,26 @@ export interface NavigationProviderProps {
  * Used in browser-entry.ts renderRoot to wrap the RSC payload element
  * so that navigation state updates atomically with the tree render.
  */
-export declare function NavigationProvider({ value, children, }: NavigationProviderProps): React.ReactElement;
+export declare function NavigationProvider({ value, children, }: NavigationProviderProps): import('react').ReactElement;
 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;CAClB;AAuCD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,GAAG,IAAI,CAM7D;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;AA6BD;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAKvD;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAA4C,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAOjF;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAkCD;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,GAAG,IAAI,CAE7D;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,OAAO,OAAO,EAAE,YAAY,CAExD;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

@@ -0,0 +1,98 @@
+/**
+ * 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
+ * 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
+ * hooks to suspend forever — preventing React from rendering children
+ * during page teardown. The throw must come after hooks to satisfy
+ * React's rules (same hook count every render) while still preventing
+ * child renders that could hit hook count mismatches in components
+ * whose positions shift during teardown. This pattern is borrowed from
+ * Next.js (app-router.tsx pushRef.mpaNavigation — also after hooks).
+ *
+ * See design/05-streaming.md §"deferSuspenseFor"
+ * See design/19-client-navigation.md §"NavigationContext"
+ */
+import { type ReactNode } from 'react';
+import { type TopLoaderConfig } from './top-loader.tsx';
+/**
+ * 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 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. 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).
+     */
+    publish: (() => void) | null;
+}
+/**
+ * Hand a tree to React in a transition. `publish` runs when React commits 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`.
+ */
+export type NavigationRender = (element: ReactNode, publish: (() => void) | null) => void;
+/**
+ * Set the hard-navigating flag. Call this BEFORE setting
+ * window.location.href or window.location.reload() to prevent:
+ * 1. React from rendering children during page teardown
+ * 2. Navigation API from intercepting the hard navigation
+ */
+export declare function setHardNavigating(value: boolean): void;
+/**
+ * Check if a hard navigation is in progress.
+ * Used by NavigationRoot (throw unresolvedThenable) and by the
+ * Navigation API handler (skip interception).
+ */
+export declare function isHardNavigating(): boolean;
+/**
+ * Root component the router renders the page through.
+ *
+ * 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.
+ *
+ * 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 declare function NavigationRoot({ rendered, topLoaderConfig, }: {
+    rendered: RenderedTree;
+    topLoaderConfig?: TopLoaderConfig;
+}): ReactNode;
+//# sourceMappingURL=navigation-root.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-root.d.ts","sourceRoot":"","sources":["../../src/client/navigation-root.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAoD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACzF,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAInE;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,SAAS,CAAC;IACnB;;;;;;OAMG;IACH,OAAO,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC;AA8B1F;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAgBD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,EAC7B,QAAQ,EACR,eAAe,GAChB,EAAE;IACD,QAAQ,EAAE,YAAY,CAAC;IACvB,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC,GAAG,SAAS,CAsEZ"}

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

@@ -0,0 +1,187 @@
+/**
+ * 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';
+/**
+ * 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';
+/**
+ * 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 declare function createRenderOwner(kind: 'navigation' | 'revalidation'): RenderOwner;
+/**
+ * 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 declare function navigateTransition(owner: RenderOwner, perform: () => Promise<TransitionResult>, render: NavigationRender, onCommit?: (outcome: CommitOutcome) => void): Promise<void>;
+//# sourceMappingURL=navigation-transition.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-transition.d.ts","sourceRoot":"","sources":["../../src/client/navigation-transition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAI9D;;;;;;;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;AAED,+CAA+C;AAC/C,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,YAAY,GAAG,QAAQ,CAAC;AAIlE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,cAAc,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,SAAS,EAAE,OAAO,CAAC;IACnB,kEAAkE;IAClE,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC;;;;OAIG;IACH,MAAM,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAC;CAC1C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,cAAc,GAAG,WAAW,CAmClF;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,EACxC,MAAM,EAAE,gBAAgB,EACxB,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,GAC1C,OAAO,CAAC,IAAI,CAAC,CA2Df"}

package/dist/client/nuqs-adapter.d.ts

@@ -7,5 +7,5 @@ import { type ReactNode } from 'react';
  */
 export declare function TimberNuqsAdapter({ children }: {
     children: ReactNode;
-}): import("react/jsx-runtime").JSX.Element;
+}): import("react").JSX.Element;
 //# sourceMappingURL=nuqs-adapter.d.ts.map

package/dist/client/nuqs-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nuqs-adapter.d.ts","sourceRoot":"","sources":["../../src/client/nuqs-adapter.tsx"],"names":[],"mappings":"AAcA,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAmFrE;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,2CAatE"}
+{"version":3,"file":"nuqs-adapter.d.ts","sourceRoot":"","sources":["../../src/client/nuqs-adapter.tsx"],"names":[],"mappings":"AAcA,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AA+FrE;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAatE"}

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 CoercedParams } from '../shared/param-value.ts';
+import { type PublishedParams } from '../shared/payload-root.ts';
+import type { SlotParamsRecord } from '../shared/slot-params.ts';
+export type ParamsContextValue = PublishedParams;
+/**
+ * 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 declare function useParamsContext(): ParamsContextValue | null;
+interface ParamsProviderProps {
+    params: CoercedParams;
+    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;AAC3D,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACjF,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAIjE,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAqDjD;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,kBAAkB,GAAG,IAAI,CAE5D;AAID,UAAU,mBAAmB;IAC3B,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B;AAqCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}