@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.190

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

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,11 +1,11 @@
-import type { RouterInstance } from './router.js';
+import type { RouterInstance } from './router-types.js';
 /**
  * Set the global router instance. Called once during bootstrap.
  */
 export declare function setGlobalRouter(router: RouterInstance): void;
 /**
  * Get the global router instance. Throws if called before bootstrap.
- * Used by client-side hooks (useNavigationPending, etc.)
+ * Used by client-side hooks (usePendingNavigation, etc.)
  */
 export declare function getRouter(): RouterInstance;
 /**

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,100 +1,4 @@
-import { SegmentCache, PrefetchCache } from './segment-cache';
-import type { SegmentInfo } from './segment-cache';
-import { HistoryStack } from './history';
-import type { HeadElement } from './head';
-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;
-}
-/**
- * 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.
- */
-export type RootRenderer = (element: unknown) => 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;
-    /** Apply resolved head elements (title, meta tags) to the DOM after navigation. */
-    applyHead?: (elements: HeadElement[]) => 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
-     * TransitionRoot sets it as the new element.
-     *
-     * If not provided (tests), the router falls back to renderRoot.
-     */
-    navigateTransition?: (pendingUrl: string, perform: (wrapPayload: (payload: unknown) => unknown) => Promise<unknown>) => Promise<void>;
-}
-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): 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, headElements: HeadElement[] | null): 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;
-    /**
-     * Cache segment elements from a decoded RSC element tree.
-     * Called on initial hydration to populate the element cache so the
-     * first client navigation can use partial payloads.
-     */
-    cacheElementTree(element: unknown): 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.