@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

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"}

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

@@ -0,0 +1,84 @@
+/**
+ * Navigation Pipeline — URL in, tree in React's hands.
+ *
+ * Everything between "the user asked for this URL" and "React is holding the
+ * destination's tree": consult the prefetch cache or fetch, prepare the commit
+ * that makes the page current, and hand the result over inside a transition.
+ *
+ * `router.ts` keeps the *operations* — `navigate`, `refresh`, `handlePopState`,
+ * `prefetch`, `applyRevalidation` — and each of them is a call into here. The
+ * split is the same one `router-effects.ts` and `router-lifecycle.ts` made
+ * (design/18-build-system.md §"No file >500 lines").
+ *
+ * See design/19-client-navigation.md §"Partial Rendering" and §"Prefetching".
+ */
+import type { FetchResult } from './rsc-fetch.js';
+import { type ParamsSource } from '../shared/payload-root.js';
+import type { PrefetchCache, PrefetchKey } from './segment-cache.js';
+import type { StateTree } from '../shared/segment-info.js';
+import type { NavigationState } from './navigation-context.js';
+import type { NavigationCommitter } from './navigation-commit.js';
+import type { RouterDeps } from './router-types.js';
+/** A fetched payload plus the state update that makes it the current page. */
+export type NavigationPayload = FetchResult & {
+    navState: NavigationState;
+    commit: () => void;
+};
+/** Options for a single `performNavigationFetch` call. */
+export interface NavigationFetchOptions {
+    replace: boolean;
+    commitUrl?: string;
+    signal?: AbortSignal;
+    skipHistory?: boolean;
+    departingUrl?: string;
+}
+export interface NavigationPipelineDeps extends Pick<NavigationCommitter, 'prepareNavigation' | 'currentStateTree'> {
+    deps: RouterDeps;
+    prefetchCache: PrefetchCache;
+    /** Record that this navigation's tree reached React (router-lifecycle.ts). */
+    markHandedOff: (owner: AbortController) => void;
+    /** React committed this navigation's tree (router-lifecycle.ts). */
+    forgetOlderHandoffs: (owner: AbortController) => void;
+}
+export interface NavigationPipeline {
+    /** Fetch (or replay a prefetch), then stage the commit. */
+    performNavigationFetch: (url: string, options: NavigationFetchOptions) => Promise<NavigationPayload>;
+    /** Hand a payload to React inside a transition, or render it directly in tests. */
+    renderViaTransition: (url: string, owner: AbortController, perform: () => Promise<NavigationPayload>) => Promise<void>;
+    /** Render a decoded payload into the DOM if a renderer is available. */
+    renderPayload: (payload: unknown, navState: NavigationState, params: ParamsSource) => void;
+    /** Resolve thenable payloads on the fallback (test) path. */
+    resolveForFallback: (payload: unknown) => Promise<unknown>;
+}
+/**
+ * Normalize a departing URL to the pathname the server is told about.
+ *
+ * This is the value sent as `X-Timber-URL` *and* the source half of the
+ * prefetch cache key — one function so a prefetch and the click that consumes
+ * it can never disagree about what "where we came from" means (TIM-1265). The
+ * query is dropped deliberately: it would land in the `_rsc` digest, which is
+ * logged (TIM-1268), and nothing downstream reads it — slot-skip resolution
+ * and interception scope both compare pathnames.
+ *
+ * Absolute inputs parse against the base and ignore it, so one call handles
+ * both `location.href` and a bare pathname.
+ */
+export declare function departingPathname(raw: string): string;
+/**
+ * The prefetch cache key for a destination.
+ *
+ * Both halves of the cache are keyed through here — the hover that writes an
+ * entry (`router.ts`'s `prefetch()`) and the click that consumes it
+ * (`performNavigationFetch` below) — so the two cannot disagree about what
+ * identifies a payload. That is the whole point of the key: `from` scopes it
+ * to the page the link was on (TIM-1265) and `scope` to the tree that was
+ * mounted (TIM-1282), and an entry written under one reading of either would
+ * simply never be found under the other, silently costing every prefetch.
+ *
+ * `departingPathname` is applied here rather than by callers for the same
+ * reason: it is also what goes out as `X-Timber-URL`, so the key and the
+ * request describe the same departure point.
+ */
+export declare function prefetchKeyFor(url: string, departingUrl: string, stateTree: StateTree | undefined): PrefetchKey;
+export declare function createNavigationPipeline({ deps, prefetchCache, currentStateTree, prepareNavigation, markHandedOff, forgetOlderHandoffs, }: NavigationPipelineDeps): NavigationPipeline;
+//# sourceMappingURL=router-pipeline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"router-pipeline.d.ts","sourceRoot":"","sources":["../../src/client/router-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACnF,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAErE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGpD,8EAA8E;AAC9E,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG;IAC5C,QAAQ,EAAE,eAAe,CAAC;IAC1B,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB,CAAC;AAEF,0DAA0D;AAC1D,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAClD,mBAAmB,EACnB,mBAAmB,GAAG,kBAAkB,CACzC;IACC,IAAI,EAAE,UAAU,CAAC;IACjB,aAAa,EAAE,aAAa,CAAC;IAC7B,8EAA8E;IAC9E,aAAa,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IAChD,oEAAoE;IACpE,mBAAmB,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;CACvD;AAED,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,sBAAsB,EAAE,CACtB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,sBAAsB,KAC5B,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAChC,mFAAmF;IACnF,mBAAmB,EAAE,CACnB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,KACtC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,wEAAwE;IACxE,aAAa,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAC3F,6DAA6D;IAC7D,kBAAkB,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,SAAS,GAAG,SAAS,GAC/B,WAAW,CAEb;AAwCD,wBAAgB,wBAAwB,CAAC,EACvC,IAAI,EACJ,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,GACpB,EAAE,sBAAsB,GAAG,kBAAkB,CA4O7C"}

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

@@ -1,4 +1,4 @@
-import type { RouterInstance } from './router.js';
+import type { RouterInstance } from './router-types.js';
 /**
  * Set the global router instance. Called once during bootstrap.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"router-ref.d.ts","sourceRoot":"","sources":["../../src/client/router-ref.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAE5D;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,cAAc,CAK1C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,cAAc,GAAG,IAAI,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}
+{"version":3,"file":"router-ref.d.ts","sourceRoot":"","sources":["../../src/client/router-ref.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGxD;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAE5D;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,cAAc,CAK1C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,cAAc,GAAG,IAAI,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}

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

@@ -0,0 +1,21 @@
+/**
+ * Router Skew Recording — turning a rejection into "this bundle is superseded".
+ *
+ * Detection lives in `stale-client.ts`; this is the one place the router (and
+ * anything else holding an RSC rejection) turns an error into that verdict.
+ * Recovery is not here: every path that gives up on client-side navigation —
+ * skew or not — leaves through `createSpaExits()` in `router-effects.ts`.
+ *
+ * See design/33-version-skew.md §"Recovery on the next navigation"
+ */
+/**
+ * Record a version skew if `error` is one, and report whether it was.
+ *
+ * `VersionSkewError` is the origin saying so outright; the reactive shapes are
+ * inferred from the error text and are a no-op in dev.
+ *
+ * Closes over nothing — anywhere an RSC payload can fail needs it, including
+ * places that have no router instance to hand.
+ */
+export declare function recordSkew(error: unknown): boolean;
+//# sourceMappingURL=router-skew.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"router-skew.d.ts","sourceRoot":"","sources":["../../src/client/router-skew.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAMlD"}

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

@@ -0,0 +1,207 @@
+/**
+ * Router Types — the router's surface, stated once.
+ *
+ * Split out of `router.ts` so the factory file is navigation logic rather than
+ * declarations (design/18-build-system.md §"No file >500 lines"), and because
+ * `rsc-fetch.ts` needs `RouterDeps` while `router.ts` needs `FetchResult`:
+ * with the types here, neither imports the other.
+ *
+ * See design/19-client-navigation.md for the architecture these describe.
+ */
+import type { NavigationState } from './navigation-context.js';
+import type { ParamsSource } from '../shared/payload-root.js';
+import type { SegmentInfo } from '../shared/segment-info.js';
+import type { SegmentCache, PrefetchCache } from './segment-cache.js';
+import type { HistoryStack } from './history.js';
+import type { TransitionResult } from './navigation-root.js';
+export interface NavigationOptions {
+    /** Set to false to prevent scroll-to-top on forward navigation */
+    scroll?: boolean;
+    /** Use replaceState instead of pushState (replaces current history entry) */
+    replace?: boolean;
+    /**
+     * @internal AbortSignal from the Navigation API's NavigateEvent.
+     * When provided, the signal is linked to the router's per-navigation
+     * AbortController so in-flight RSC fetches are cancelled when a new
+     * navigation starts.
+     */
+    _signal?: AbortSignal;
+    /**
+     * @internal Skip pushState/replaceState — the Navigation API has already
+     * updated the URL via event.intercept(). Used for external navigations
+     * intercepted by the navigate event handler.
+     */
+    _skipHistory?: boolean;
+    /**
+     * @internal The URL the user is navigating FROM, captured before the
+     * Navigation API commits the destination. Sent as X-Timber-URL for
+     * slot skip comparison on the server (TIM-1232).
+     */
+    _departingUrl?: string;
+}
+/**
+ * Function that decodes an RSC Flight stream into a React element tree.
+ * In production: createFromFetch from @vitejs/plugin-rsc/browser.
+ * In tests: a mock that returns the raw payload.
+ */
+export type RscDecoder = (fetchPromise: Promise<Response>) => unknown;
+/**
+ * Function that renders a decoded RSC element tree into the DOM.
+ * In production: reactRoot.render(element).
+ * In tests: a no-op or mock.
+ *
+ * Receives the current NavigationState explicitly — no temporal
+ * coupling with setNavigationState/getNavigationState. The renderer
+ * wraps the element in NavigationProvider with this state.
+ */
+export type RootRenderer = (element: unknown, navState: NavigationState, params: ParamsSource) => void;
+/**
+ * Platform dependencies injected for testability. In production these
+ * map to browser APIs; in tests they're replaced with mocks.
+ */
+export interface RouterDeps {
+    fetch: (url: string, init: RequestInit) => Promise<Response>;
+    pushState: (data: unknown, unused: string, url: string) => void;
+    replaceState: (data: unknown, unused: string, url: string) => void;
+    scrollTo: (x: number, y: number) => void;
+    getCurrentUrl: () => string;
+    getScrollY: () => number;
+    /** Decode RSC Flight stream into React elements. If not provided, raw response text is stored. */
+    decodeRsc?: RscDecoder;
+    /** Render decoded RSC tree into the DOM. If not provided, rendering is a no-op. */
+    renderRoot?: RootRenderer;
+    /**
+     * Schedule a callback after the next paint. In the browser, this is
+     * requestAnimationFrame + setTimeout(0) to run after React commits.
+     * In tests, this runs the callback synchronously.
+     */
+    afterPaint?: (callback: () => void) => void;
+    /**
+     * Hand a navigation's tree to React in a transition, so the departing page
+     * stays visible while the destination resolves. Pending state is not React
+     * state — it lives in this router's external store (`setPending`), which
+     * `TopLoader` and `usePendingNavigation()` subscribe to (TIM-1307).
+     *
+     * The `perform` callback receives a `wrapPayload` function to wrap the
+     * decoded RSC payload with NavigationProvider + NuqsAdapter before
+     * NavigationRoot sets it as the new element. The `wrapPayload` function
+     * receives the NavigationState explicitly — no temporal coupling with
+     * getNavigationState().
+     *
+     * If not provided (tests), the router falls back to renderRoot.
+     */
+    navigateTransition?: (pendingUrl: string, perform: (wrapPayload: (payload: unknown, navState: NavigationState, 
+    /**
+     * The params to publish over `payload`. On a partial navigation
+     * `payload` is the *retained* tree and these are the *incoming*
+     * route's — the two deliberately come from different payloads,
+     * which is the entire point of the client owning the provider
+     * (TIM-1297).
+     */
+    params: ParamsSource, segmentUpdates?: Map<string, unknown>) => unknown) => Promise<TransitionResult<unknown>>) => Promise<void>;
+    /**
+     * Whether the Navigation API is active and handling traversals.
+     * When true, the popstate handler is a no-op — the Navigation API's
+     * navigate event covers back/forward button presses.
+     */
+    navigationApiActive?: boolean;
+    /**
+     * Called around pushState/replaceState to set a flag that prevents
+     * the Navigation API's navigate listener from double-handling
+     * router-initiated navigations.
+     */
+    setRouterNavigating?: (value: boolean) => void;
+    /**
+     * Save scroll position via the Navigation API's per-entry state.
+     * When provided, used instead of history.replaceState for scroll storage.
+     */
+    saveNavigationEntryScroll?: (scrollY: number) => void;
+    /**
+     * Signal that a router-initiated navigation has completed. Resolves the
+     * deferred promise that ties the browser's native loading state to the
+     * navigation lifecycle. Called in the finally block of navigate/refresh,
+     * the same place `setPending(false)` clears the TopLoader.
+     */
+    completeRouterNavigation?: () => void;
+    /**
+     * Get the current unwrapped RSC payload element. Used for partial
+     * navigation: the router re-wraps the same element with new
+     * NavigationProvider context so mounted SegmentOutlets are preserved.
+     */
+    _getCurrentPayload?: () => unknown;
+    /**
+     * Initiate a navigation via the Navigation API (`navigation.navigate()`).
+     * Fires the navigate event BEFORE committing the URL, allowing Chrome
+     * to show its native loading indicator. Falls back to pushState when
+     * unavailable.
+     */
+    navigationNavigate?: (url: string, replace: boolean) => void;
+    /**
+     * Scroll the element matching a URL #fragment into view. Returns true
+     * when a matching element was found and scrolled. When absent or false,
+     * the router falls back to scroll-to-top on forward navigation — same
+     * as a full page load with an unknown fragment landing at the top.
+     */
+    scrollToHash?: (hash: string) => boolean;
+    /**
+     * Whether the client segment cache is enabled. When false (the default),
+     * the router sends no segment/slot lists, so every navigation gets a full
+     * RSC payload.
+     *
+     * It does NOT gate the `treePaths` half of X-Timber-State-Tree. Those
+     * describe the tree currently mounted, and interception scoping needs them
+     * to open a modal on top of a modal — a routing behaviour, not a caching
+     * optimization, so it must not depend on a performance opt-in (TIM-1282).
+     */
+    clientSegmentCache?: boolean;
+}
+export interface RouterInstance {
+    /** Navigate to a new URL (forward navigation) */
+    navigate(url: string, options?: NavigationOptions): Promise<void>;
+    /** Full re-render of the current URL — no state tree sent */
+    refresh(): Promise<void>;
+    /** Handle a popstate event (back/forward button). scrollY is read from history.state. */
+    handlePopState(url: string, scrollY?: number, externalSignal?: AbortSignal): Promise<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;
+    /** Prefetch an RSC payload for a URL (used by Link hover) */
+    prefetch(url: string): void;
+    /**
+     * Apply a piggybacked revalidation payload from a server action response.
+     * Takes the decoded payload *root* — tree plus the params it published —
+     * and renders it without a server fetch.
+     * See design/08-forms-and-actions.md §"Single-Roundtrip Revalidation".
+     */
+    applyRevalidation(payloadRoot: unknown): void;
+    /**
+     * Populate the segment cache from server-provided segment metadata.
+     * Called on initial hydration with segment info embedded in the HTML.
+     */
+    initSegmentCache(segments: SegmentInfo[]): void;
+    /** The segment cache (exposed for tests and <Link> prefetch) */
+    segmentCache: SegmentCache;
+    /** The prefetch cache (exposed for tests and <Link> prefetch) */
+    prefetchCache: PrefetchCache;
+    /** The history stack (exposed for tests) */
+    historyStack: HistoryStack;
+}
+/**
+ * Router navigation phase — discriminated union replacing scattered
+ * `pending` + `pendingUrl` boolean flags.
+ *
+ * - `idle`: No navigation in flight. The committed params/pathname
+ *   are current.
+ * - `navigating`: A fetch or render is in progress. `targetUrl` is
+ *   the destination being navigated to.
+ */
+export type RouterPhase = {
+    phase: 'idle';
+} | {
+    phase: 'navigating';
+    targetUrl: string;
+};
+//# sourceMappingURL=router-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"router-types.d.ts","sourceRoot":"","sources":["../../src/client/router-types.ts"],"names":[],"mappings":"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"}

package/dist/client/router.d.ts

@@ -1,188 +1,7 @@
-import { SegmentCache, PrefetchCache } from './segment-cache';
-import type { SegmentInfo } from './segment-cache';
-import { HistoryStack } from './history';
-import { type NavigationState } from './navigation-context.js';
-export interface NavigationOptions {
-    /** Set to false to prevent scroll-to-top on forward navigation */
-    scroll?: boolean;
-    /** Use replaceState instead of pushState (replaces current history entry) */
-    replace?: boolean;
-    /**
-     * @internal AbortSignal from the Navigation API's NavigateEvent.
-     * When provided, the signal is linked to the router's per-navigation
-     * AbortController so in-flight RSC fetches are cancelled when a new
-     * navigation starts.
-     */
-    _signal?: AbortSignal;
-    /**
-     * @internal Skip pushState/replaceState — the Navigation API has already
-     * updated the URL via event.intercept(). Used for external navigations
-     * intercepted by the navigate event handler.
-     */
-    _skipHistory?: boolean;
-    /**
-     * @internal The URL the user is navigating FROM, captured before the
-     * Navigation API commits the destination. Sent as X-Timber-URL for
-     * slot skip comparison on the server (TIM-1232).
-     */
-    _departingUrl?: string;
-}
-/**
- * Function that decodes an RSC Flight stream into a React element tree.
- * In production: createFromFetch from @vitejs/plugin-rsc/browser.
- * In tests: a mock that returns the raw payload.
- */
-export type RscDecoder = (fetchPromise: Promise<Response>) => unknown;
-/**
- * Function that renders a decoded RSC element tree into the DOM.
- * In production: reactRoot.render(element).
- * In tests: a no-op or mock.
- *
- * Receives the current NavigationState explicitly — no temporal
- * coupling with setNavigationState/getNavigationState. The renderer
- * wraps the element in NavigationProvider with this state.
- */
-export type RootRenderer = (element: unknown, navState: NavigationState) => void;
-/**
- * Platform dependencies injected for testability. In production these
- * map to browser APIs; in tests they're replaced with mocks.
- */
-export interface RouterDeps {
-    fetch: (url: string, init: RequestInit) => Promise<Response>;
-    pushState: (data: unknown, unused: string, url: string) => void;
-    replaceState: (data: unknown, unused: string, url: string) => void;
-    scrollTo: (x: number, y: number) => void;
-    getCurrentUrl: () => string;
-    getScrollY: () => number;
-    /** Decode RSC Flight stream into React elements. If not provided, raw response text is stored. */
-    decodeRsc?: RscDecoder;
-    /** Render decoded RSC tree into the DOM. If not provided, rendering is a no-op. */
-    renderRoot?: RootRenderer;
-    /**
-     * Schedule a callback after the next paint. In the browser, this is
-     * requestAnimationFrame + setTimeout(0) to run after React commits.
-     * In tests, this runs the callback synchronously.
-     */
-    afterPaint?: (callback: () => void) => void;
-    /**
-     * Run a navigation inside a React transition with optimistic pending URL.
-     * The pending URL shows immediately (useOptimistic urgent update) and
-     * reverts when the transition commits (atomic with the new tree).
-     *
-     * The `perform` callback receives a `wrapPayload` function to wrap the
-     * decoded RSC payload with NavigationProvider + NuqsAdapter before
-     * NavigationRoot sets it as the new element. The `wrapPayload` function
-     * receives the NavigationState explicitly — no temporal coupling with
-     * getNavigationState().
-     *
-     * If not provided (tests), the router falls back to renderRoot.
-     */
-    navigateTransition?: (pendingUrl: string, perform: (wrapPayload: (payload: unknown, navState: NavigationState, segmentUpdates?: Map<string, unknown>) => unknown) => Promise<{
-        element: unknown;
-        decodePromise: Promise<void> | null;
-    }>) => Promise<void>;
-    /**
-     * Whether the Navigation API is active and handling traversals.
-     * When true, the popstate handler is a no-op — the Navigation API's
-     * navigate event covers back/forward button presses.
-     */
-    navigationApiActive?: boolean;
-    /**
-     * Called around pushState/replaceState to set a flag that prevents
-     * the Navigation API's navigate listener from double-handling
-     * router-initiated navigations.
-     */
-    setRouterNavigating?: (value: boolean) => void;
-    /**
-     * Save scroll position via the Navigation API's per-entry state.
-     * When provided, used instead of history.replaceState for scroll storage.
-     */
-    saveNavigationEntryScroll?: (scrollY: number) => void;
-    /**
-     * Signal that a router-initiated navigation has completed. Resolves the
-     * deferred promise that ties the browser's native loading state to the
-     * navigation lifecycle. Called in the finally block of navigate/refresh,
-     * aligned with when the TopLoader's pendingUrl clears.
-     */
-    completeRouterNavigation?: () => void;
-    /**
-     * Get the current unwrapped RSC payload element. Used for partial
-     * navigation: the router re-wraps the same element with new
-     * NavigationProvider context so mounted SegmentOutlets are preserved.
-     */
-    _getCurrentPayload?: () => unknown;
-    /**
-     * Initiate a navigation via the Navigation API (`navigation.navigate()`).
-     * Fires the navigate event BEFORE committing the URL, allowing Chrome
-     * to show its native loading indicator. Falls back to pushState when
-     * unavailable.
-     */
-    navigationNavigate?: (url: string, replace: boolean) => void;
-    /**
-     * Scroll the element matching a URL #fragment into view. Returns true
-     * when a matching element was found and scrolled. When absent or false,
-     * the router falls back to scroll-to-top on forward navigation — same
-     * as a full page load with an unknown fragment landing at the top.
-     */
-    scrollToHash?: (hash: string) => boolean;
-    /**
-     * Whether the client segment cache is enabled. When false (the default),
-     * the router does not send X-Timber-State-Tree headers and does not
-     * populate the segment cache. Every navigation gets a full RSC payload.
-     */
-    clientSegmentCache?: boolean;
-}
-export interface RouterInstance {
-    /** Navigate to a new URL (forward navigation) */
-    navigate(url: string, options?: NavigationOptions): Promise<void>;
-    /** Full re-render of the current URL — no state tree sent */
-    refresh(): Promise<void>;
-    /** Handle a popstate event (back/forward button). scrollY is read from history.state. */
-    handlePopState(url: string, scrollY?: number, externalSignal?: AbortSignal): Promise<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;
-    /** Prefetch an RSC payload for a URL (used by Link hover) */
-    prefetch(url: string): void;
-    /**
-     * Apply a piggybacked revalidation payload from a server action response.
-     * Renders the element tree and updates head elements without a server fetch.
-     * See design/08-forms-and-actions.md §"Single-Roundtrip Revalidation".
-     */
-    applyRevalidation(element: unknown): void;
-    /**
-     * Populate the segment cache from server-provided segment metadata.
-     * Called on initial hydration with segment info embedded in the HTML.
-     */
-    initSegmentCache(segments: SegmentInfo[]): void;
-    /** The segment cache (exposed for tests and <Link> prefetch) */
-    segmentCache: SegmentCache;
-    /** The prefetch cache (exposed for tests and <Link> prefetch) */
-    prefetchCache: PrefetchCache;
-    /** The history stack (exposed for tests) */
-    historyStack: HistoryStack;
-}
+import type { RouterDeps, RouterInstance } from './router-types.js';
 /**
  * Create a router instance. In production, called once at app hydration
  * with real browser APIs. In tests, called with mock dependencies.
  */
-/**
- * Router navigation phase — discriminated union replacing scattered
- * `pending` + `pendingUrl` boolean flags.
- *
- * - `idle`: No navigation in flight. The committed params/pathname
- *   are current.
- * - `navigating`: A fetch or render is in progress. `targetUrl` is
- *   the destination being navigated to.
- */
-export type RouterPhase = {
-    phase: 'idle';
-} | {
-    phase: 'navigating';
-    targetUrl: string;
-};
 export declare function createRouter(deps: RouterDeps): RouterInstance;
 //# sourceMappingURL=router.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/client/router.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/client/router.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAqB,UAAU,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIvF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,cAAc,CAoY7D"}