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

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"react-root.d.ts","sourceRoot":"","sources":["../../src/client/react-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAkC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACvE,OAAO,EAA2B,KAAK,gBAAgB,EAAa,MAAM,kBAAkB,CAAC;AAC7F,OAAO,EAAkB,KAAK,gBAAgB,EAAqB,MAAM,uBAAuB,CAAC;AACjG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC9D;;;OAGG;IACH,MAAM,EAAE,gBAAgB,CAAC;IACzB,kCAAkC;IAClC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACvC,SAAS,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC9B,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC,GAAG,aAAa,CA0BhB"}

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

@@ -0,0 +1,130 @@
+/**
+ * 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"
+ */
+import type { RenderOwner } from './navigation-transition.ts';
+/** 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 owner that holds the router right now, or null when idle. */
+    currentOwner: () => RenderOwner | null;
+    /** Supersede whatever is in flight and take ownership. */
+    supersede: () => void;
+}
+export interface SpaExits {
+    /**
+     * Leave the SPA — but only if `owner` 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: (owner: RenderOwner, 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({ currentOwner, supersede }: SpaExitDeps): SpaExits;
+export interface NavigationRecoveryDeps {
+    /** The owner that holds the router right now, or null when idle. */
+    currentOwner: () => RenderOwner | 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({ currentOwner, leaveSpaIfOwned, navigate, }: NavigationRecoveryDeps): (error: unknown, owner: RenderOwner, 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;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAI9D,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,oEAAoE;IACpE,YAAY,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IACvC,0DAA0D;IAC1D,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB;;;;;;;;;;;;OAYG;IACH,eAAe,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAErF;;;;;;;;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,YAAY,EAAE,SAAS,EAAE,EAAE,WAAW,GAAG,QAAQ,CAYjF;AAED,MAAM,WAAW,sBAAsB;IACrC,oEAAoE;IACpE,YAAY,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IACvC,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,YAAY,EACZ,eAAe,EACf,QAAQ,GACT,EAAE,sBAAsB,WAEd,OAAO,SACP,WAAW,OACb,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,98 @@
+/**
+ * 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
+ * as a single `RenderOwner` slot, the rule for taking it (`createNavOwner`
+ * supersedes), the wrapper every navigation runs inside (`runNavigation`),
+ * and the pending store that `TopLoader` and `usePendingNavigation()`
+ * subscribe to.
+ *
+ * TIM-1481: replaced the transition counter, the `handedOffNavAborts` set,
+ * and the `AbortController`-as-owner pattern with `RenderOwner`. Supersession
+ * is "take the slot": settle the previous owner and abort its fetch unless
+ * handed off.
+ *
+ * See design/19-client-navigation.md §"How Pending State Works".
+ */
+import { type RenderOwner } from './navigation-transition.ts';
+/**
+ * A snapshot of "which page, and was a navigation in flight" at one instant.
+ * Captured before an action's POST and compared at response time so the
+ * router can tell whether the response still describes the page on screen.
+ *
+ * `seq` is a monotonic counter bumped on every `createNavOwner` — covering
+ * every path through `runNavigation`. `idle` is false when the router is
+ * mid-navigation OR a handed-off tree has not yet committed (the
+ * handover-to-commit window on the History API fallback).
+ *
+ * See design/19-client-navigation.md §State Update Invariants (TIM-1474).
+ */
+export interface NavigationEpoch {
+    readonly seq: number;
+    readonly idle: boolean;
+}
+/** 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 owner that holds the router right now, or null when idle. */
+    currentOwner: () => RenderOwner | null;
+    /**
+     * Take ownership of the router, superseding whatever held it. Returns
+     * a fresh `RenderOwner` for the new navigation. See the implementation
+     * for the three parts of superseding.
+     */
+    createNavOwner: (kind: 'navigation' | 'revalidation', externalSignal?: AbortSignal) => RenderOwner;
+    /**
+     * Run `fn` inside the abort/pending/cleanup lifecycle. AbortErrors are
+     * swallowed (not application errors); all other errors propagate.
+     */
+    runNavigation: (url: string, fn: (owner: RenderOwner) => 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: RenderOwner) => void;
+    /** React has committed `owner`'s tree — every earlier handoff is off screen. */
+    forgetOlderHandoffs: (owner: RenderOwner) => 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;
+    /**
+     * Place a revalidation owner in the slot without bumping the navigation
+     * sequence. Unlike `createNavOwner`, this does not supersede what's in the
+     * slot — the caller (applyActionResult) has already verified the slot is
+     * idle via the epoch check. A concurrent navigation will supersede this
+     * owner through the normal `createNavOwner` path.
+     */
+    placeRevalidationOwner: (owner: RenderOwner) => void;
+    /** Snapshot the router's navigation state (TIM-1474). */
+    epoch: () => NavigationEpoch;
+    /** True iff no navigation has started or is in flight since `e` was taken. */
+    isEpochCurrent: (e: NavigationEpoch) => boolean;
+    /**
+     * Run `task` now if the router is idle, otherwise once when it next becomes
+     * idle (pending false AND commit done). Single slot — a later request
+     * replaces an earlier one (TIM-1474).
+     */
+    runWhenIdle: (task: () => void) => void;
+    /**
+     * Settle any handed-off-but-uncommitted owners as superseded, then flush
+     * the idle task if the router is now idle. Called by `syncShallowSearch`
+     * when a shallow URL update displaces a suspended transition — without
+     * it, `hasUncommittedNav` stays true indefinitely and `runWhenIdle`
+     * tasks never fire (TIM-1480).
+     */
+    settleHandoffs: () => 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;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAGjF;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,iEAAiE;AACjE,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,MAAM,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,YAAY,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,cAAc,EAAE,CACd,IAAI,EAAE,YAAY,GAAG,cAAc,EACnC,cAAc,CAAC,EAAE,WAAW,KACzB,WAAW,CAAC;IACjB;;;OAGG;IACH,aAAa,EAAE,CACb,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,EACzC,cAAc,CAAC,EAAE,WAAW,KACzB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB;;;OAGG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IAC5C,gFAAgF;IAChF,mBAAmB,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IAElD,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;IAEtE;;;;;;OAMG;IACH,sBAAsB,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACrD,yDAAyD;IACzD,KAAK,EAAE,MAAM,eAAe,CAAC;IAC7B,8EAA8E;IAC9E,cAAc,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC;IAChD;;;;OAIG;IACH,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IACxC;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,IAAI,CAAC;CAC5B;AAYD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,uBAAuB,GAAG,mBAAmB,CAwO5F"}

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

@@ -0,0 +1,87 @@
+/**
+ * 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`, `applyActionResult` — 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.ts';
+import { type ParamsSource } from '../shared/payload-root.ts';
+import type { PrefetchCache, PrefetchKey } from './segment-cache.ts';
+import type { StateTree } from '../shared/segment-info.ts';
+import type { NavigationState } from './navigation-context.ts';
+import { type NavigationCommitter } from './navigation-commit.ts';
+import type { RouterDeps } from './router-types.ts';
+import type { CommitOutcome, RenderOwner } from './navigation-transition.ts';
+/** 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: RenderOwner) => void;
+    /** React committed this navigation's tree (router-lifecycle.ts). */
+    forgetOlderHandoffs: (owner: RenderOwner) => 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: RenderOwner, perform: () => Promise<NavigationPayload>, 
+    /** See `NavigationOptions.onCommit`. */
+    onCommit?: (outcome: CommitOutcome) => void) => Promise<void>;
+    /** Render a decoded payload into the DOM if a renderer is available. */
+    renderPayload: (payload: unknown, navState: NavigationState, params: ParamsSource, commit: () => void) => 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,EAAiB,MAAM,oBAAoB,CAAC;AAEpF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAuB,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AACvF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAqB7E,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,WAAW,KAAK,IAAI,CAAC;IAC5C,oEAAoE;IACpE,mBAAmB,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;CACnD;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,WAAW,EAClB,OAAO,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC;IACzC,wCAAwC;IACxC,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,KACxC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,wEAAwE;IACxE,aAAa,EAAE,CACb,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,eAAe,EACzB,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,IAAI,KACf,IAAI,CAAC;IACV,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;AAoCD,wBAAgB,wBAAwB,CAAC,EACvC,IAAI,EACJ,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,GACpB,EAAE,sBAAsB,GAAG,kBAAkB,CAuT7C"}

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

@@ -1,11 +1,11 @@
-import type { RouterInstance } from './router.js';
+import type { RouterInstance } from './router-types.ts';
 /**
  * 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"}