@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

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

@@ -0,0 +1,334 @@
+/**
+ * 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.ts';
+import type { ParamsSource } from '../shared/payload-root.ts';
+import type { SegmentInfo } from '../shared/segment-info.ts';
+import type { SegmentCache, PrefetchCache } from './segment-cache.ts';
+import type { TransitionResult, CommitOutcome, RenderOwner } from './navigation-transition.ts';
+import type { NavigationEpoch } from './router-lifecycle.ts';
+/**
+ * The view transition type the router adds to a render it hands React —
+ * exactly one per navigation, traversal, refresh or revalidation render,
+ * beside any `transitionTypes` the caller passed.
+ * A `<ViewTransition>` keys its animations on these
+ * (design/37-navigation-api.md §"Transition types", TIM-1471).
+ *
+ * - `navigation-forward` — a push or replace (`<Link>`, `router.push`,
+ *   a server action redirect, a non-shallow nuqs update), or a traversal
+ *   forward through history.
+ * - `navigation-back` — a traversal back through history.
+ * - `navigation-traverse` — a traversal whose direction the router cannot
+ *   know: the History API fallback, where `popstate` carries no index.
+ * - `refresh` — `router.refresh()`.
+ * - `revalidate` — the page re-rendered after a server action.
+ *
+ * The shallow search re-wrap and hydration add none. A server redirect the
+ * router follows keeps the types of the render it interrupted.
+ */
+export type NavigationTransitionType = 'navigation-forward' | 'navigation-back' | 'navigation-traverse' | 'refresh' | 'revalidate';
+/** The type a traversal adds: its direction, when the router knows it. */
+export type TraverseDirection = Extract<NavigationTransitionType, 'navigation-forward' | 'navigation-back' | 'navigation-traverse'>;
+/** Options for `RouterInstance.refresh`. */
+export interface RefreshOptions {
+    /** See `NavigationOptions.onCommit`. */
+    onCommit?: (outcome: CommitOutcome) => void;
+    /**
+     * Why the page is being re-fetched, as the view transition type the render
+     * adds: `refresh` (the default) when the user asked, `revalidate` when a
+     * server action left the page to be re-fetched.
+     */
+    transitionType?: Extract<NavigationTransitionType, 'refresh' | 'revalidate'>;
+}
+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;
+    /**
+     * View transition types to add to this navigation, beside the router's own
+     * `navigation-forward`. They are added in the router's transition, the one
+     * that renders the destination — not in the caller's: React claims types
+     * per root at the next transition commit, and the destination is handed to
+     * React only after its fetch, so a type added around the `navigate()` call
+     * never reaches it (design/37-navigation-api.md §"Transition types").
+     */
+    transitionTypes?: readonly string[];
+    /**
+     * @internal The complete view transition types for this render, replacing
+     * `navigation-forward` + `transitionTypes`. Set only when the router
+     * follows a redirect, which keeps the types of the render it interrupted.
+     */
+    _renderTypes?: readonly string[];
+    /**
+     * Runs exactly once, when React commits this navigation's tree — or when
+     * the navigation is abandoned (superseded or failed) and no such commit
+     * will come. The returned promise resolves on decode, which can be before
+     * OR after the commit; this is the hook for the other event. `<Link>`
+     * holds `isPending` until both have happened (TIM-1418). The outcome says
+     * which of the three it was.
+     */
+    onCommit?: (outcome: CommitOutcome) => void;
+    /**
+     * @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 the payload root.
+ * In production: createFromFetch from @vitejs/plugin-rsc/browser. Tests use
+ * the same Flight client over Flight bytes (tests/helpers/router-harness.ts),
+ * so every response is classified and decoded by the one path production runs.
+ */
+export type RscDecoder = (fetchPromise: Promise<Response>) => unknown;
+/**
+ * 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 an RSC Flight stream into the payload root. */
+    decodeRsc: RscDecoder;
+    /**
+     * 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 — there is no store to read it
+     * from.
+     *
+     * Every render goes through here — a navigation, a refresh, a traversal
+     * (fetched or replayed) and a server action's revalidation — so each one
+     * gets the same handover, commit and supersession.
+     */
+    navigateTransition: (pendingUrl: string, owner: RenderOwner, 
+    /** The view transition types this render adds; see `NavigationRender`. */
+    types: readonly 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>>, 
+    /** See `NavigationOptions.onCommit`; forwarded to `navigateTransition`. */
+    onCommit?: (outcome: CommitOutcome) => void) => 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(options?: RefreshOptions): Promise<void>;
+    /**
+     * Handle a traversal (back/forward button). scrollY is read from the
+     * destination entry's state. `direction` is the transition type the
+     * render adds; it defaults to `navigation-traverse`, the type for a
+     * traversal whose direction is unknown.
+     */
+    handlePopState(url: string, scrollY?: number, externalSignal?: AbortSignal, direction?: TraverseDirection): 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;
+    /**
+     * Snapshot the router's navigation state before dispatching a server action.
+     * Hand the epoch back to `applyActionResult` with the response (TIM-1474).
+     */
+    epoch(): NavigationEpoch;
+    /**
+     * True when no navigation has started since `epoch` was taken and the
+     * router was idle then and is idle now — the same test
+     * `applyActionResult` applies. Action branches that never reach
+     * `applyActionResult` use it to detect a navigation that ran while the
+     * action was in flight and may have rendered pre-mutation data (TIM-1483).
+     */
+    isEpochCurrent(epoch: NavigationEpoch): boolean;
+    /**
+     * Reconcile the page after a server action. `tree` is the piggybacked
+     * revalidation payload root, or `undefined` when the server sent none.
+     *
+     * Returns `true` when the result was applied, `false` when stale (a
+     * navigation happened since `epoch` was taken or the router was busy at
+     * dispatch). Async because the no-tree path awaits `refresh()` — the next
+     * queued action must not capture its epoch while the refresh is in-flight.
+     *
+     * Does NOT call `runWhenIdle` — that is the action queue's responsibility
+     * (gated on "queue empty", not just "router idle").
+     *
+     * See design/08-forms-and-actions.md §"Single-Roundtrip Revalidation".
+     */
+    applyActionResult(epoch: NavigationEpoch, tree?: unknown): Promise<boolean>;
+    /**
+     * Run `task` now if the router is idle (not pending, no uncommitted tree),
+     * otherwise once when it next becomes idle. Single slot — the action queue
+     * uses this to flush one deferred refresh when both queue-empty and
+     * router-idle are true (TIM-1474).
+     */
+    runWhenIdle(task: () => void): void;
+    /**
+     * Settle any handed-off-but-uncommitted owners as superseded, then flush
+     * idle tasks. Called by `syncShallowSearch` when a shallow URL update
+     * displaces a suspended transition (TIM-1480).
+     */
+    settleHandoffs(): void;
+    /**
+     * Make the next navigation a full render: the server re-renders every
+     * segment instead of skipping the shared layouts the client reports as
+     * mounted (TIM-1466). Called when `revalidatePath` named a page other
+     * than the current one — a layout that page shares with this one may now
+     * be stale, and the server cannot tell that from the state tree.
+     */
+    suppressSegmentReuse(): void;
+    /**
+     * Evict all prefetch cache entries and history stack payloads (TIM-1476).
+     * Called after a server action that revalidated data — the mutation may
+     * affect any route's data, not just the paths the server named, so every
+     * cached payload is stale. In-flight prefetch singleflights are fenced
+     * by the eviction generation — their results are discarded if they
+     * complete after eviction. `applyActionResult` does not need the history
+     * stack: the current page's segment metadata is the committer's record.
+     */
+    evictStaleCaches(): void;
+    /**
+     * Make the server-rendered page the current page — the hydration entry
+     * point, and the only one: bootstrap does not reach into the router's
+     * caches. Returns the `NavigationState` the page renders with.
+     *
+     * Goes through the same `prepareNavigation` every navigation uses, and
+     * commits at once rather than on React's hydration commit. The server's
+     * HTML is already the page on screen, and React does not promise that
+     * commit: a render that reaches the root while hydration is suspended (a
+     * shallow search update, a navigation the Navigation API intercepted
+     * before hydration) switches the root to client rendering, and the
+     * hydration tree — with any publish attached to it — never commits. A
+     * status document is still kept out of the cache: its `StatusPageMarker`
+     * clears the cache when it reports (navigation-commit.ts).
+     */
+    hydrate(page: HydrationPage): NavigationState;
+    /** The segment cache (exposed for tests and <Link> prefetch) */
+    segmentCache: SegmentCache;
+    /** The prefetch cache (exposed for tests and <Link> prefetch) */
+    prefetchCache: PrefetchCache;
+}
+/** The page the server rendered, as the browser entry decoded it. */
+export interface HydrationPage {
+    /** The inlined payload's tree, or null when the document carried none. */
+    payload: unknown;
+    /** The params published beside it. */
+    params: ParamsSource;
+    /** The rendered chain's metadata (`self.__timber_segments`), or null. */
+    segmentInfo: SegmentInfo[] | null;
+}
+/**
+ * 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-url.d.ts

@@ -0,0 +1,24 @@
+/**
+ * How the client router reads the URLs it is handed.
+ *
+ * One parser, so the places that key or compare by URL — the history stack,
+ * the navigation state a page renders with, the departing page sent as
+ * `X-Timber-URL` — cannot disagree about what a URL says. They did: a
+ * history entry stored under `navigate('/café')`'s spelling was looked up
+ * under the address bar's `/caf%C3%A9`, and missed (TIM-1541).
+ */
+/**
+ * Parse a router URL. A URL that starts with "/" is a path — including one
+ * that starts with "//": that is the pathname a document at
+ * `https://host//a/b` reports, and resolved against a base it would parse as
+ * a scheme-relative reference to host `a`. Anything else resolves against a
+ * placeholder origin, so an absolute URL keeps its own.
+ */
+export declare function parseRouterUrl(url: string): URL;
+/**
+ * The spelling a URL is stored and looked up under: the browser's own
+ * pathname + search, so `/a?` and `/a`, `/café` and `/caf%C3%A9`, are one
+ * key. The fragment is dropped — it is client-only.
+ */
+export declare function routerUrlKey(url: string): string;
+//# sourceMappingURL=router-url.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"router-url.d.ts","sourceRoot":"","sources":["../../src/client/router-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGhD"}

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.ts';
 /**
  * Create a router instance. In production, called once at app hydration
  * with real browser APIs. In tests, called with mock dependencies.

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":"AAwBA,OAAO,KAAK,EAIV,UAAU,EACV,cAAc,EAEf,MAAM,mBAAmB,CAAC;AAK3B;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,cAAc,CAugB7D"}

package/dist/client/rsc-fetch.d.ts

@@ -10,34 +10,86 @@
  *
  * See design/19-client-navigation.md §"RSC Payload Handling"
  */
-import type { SegmentInfo } from './segment-cache';
-import type { HeadElement } from './head';
-import type { RouterDeps } from './router';
-/** Result of fetching an RSC payload — includes head elements and segment metadata. */
+import type { RscManifest } from '../shared/rsc-manifest.ts';
+import { type PublishedParams } from '../shared/payload-root.ts';
+import type { SegmentInfo, StateTree } from '../shared/segment-info.ts';
+import type { RouterDeps } from './router-types.ts';
+/** Result of fetching an RSC payload — includes segment metadata. */
 export interface FetchResult {
+    /** The renderable tree, split off the payload root. */
     payload: unknown;
-    headElements: HeadElement[] | null;
+    /**
+     * The params the same payload published beside that tree.
+     *
+     * Not a separate channel: both fields come out of one `splitPayloadRoot`
+     * call on one decoded root, so a response cannot deliver a tree and another
+     * route's params. They used to arrive on their own header, which is how a
+     * navigation could render one route and publish another's (TIM-1285,
+     * TIM-1294).
+     */
+    params: PublishedParams | Promise<PublishedParams>;
+    /**
+     * Promise that settles when the RSC decode completes or fails.
+     * The payload thenable is NOT awaited before returning (for streaming),
+     * so callers must monitor this to catch async decode errors
+     * (truncated streams, Flight parse failures) that would otherwise
+     * become unhandled rejections.
+     */
+    decodePromise: Promise<void> | null;
     /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
     segmentInfo: SegmentInfo[] | null;
-    /** Route params from X-Timber-Params header for populating useParams(). */
-    params: Record<string, string | string[]> | null;
     /** Segment paths that were skipped by the server (for client-side merging). */
     skippedSegments: string[] | null;
 }
-export declare const RSC_CONTENT_TYPE = "text/x-component";
-export declare function buildRscHeaders(stateTree: {
-    segments: string[];
-} | undefined, currentUrl?: string): Record<string, string>;
+/** Set the client deployment ID. Called once at bootstrap. */
+export declare function setClientDeploymentId(id: string | null): void;
+/** Get the client deployment ID. */
+export declare function getClientDeploymentId(): string | null;
+/** Set the deployment base path. Called once at bootstrap. */
+export declare function setBasePath(base: string | undefined): void;
+/** Get the normalized deployment base path. @internal Exported for testing. */
+export declare function getBasePath(): string;
+export declare function setStaticMode(enabled: boolean): void;
+export declare function isStaticMode(): boolean;
+/** @internal Exported for testing. */
+export declare function setRscManifest(manifest: RscManifest | null): void;
 /**
- * Extract head elements from the X-Timber-Head response header.
- * Returns null if the header is missing or malformed.
+ * Compute the unhashed `_rsc/*.rsc` path for a route URL.
+ *
+ * Returns a **route-space** path: the deployment base is stripped from the
+ * incoming URL and is NOT re-applied, because this value doubles as the RSC
+ * manifest key, and the manifest is base-less. `toStaticRscUrl` applies the
+ * base to whatever is actually fetched.
+ *
+ * @internal Exported for testing.
  */
-export declare function extractHeadElements(response: Response): HeadElement[] | null;
+export declare function toUnhashedRscUrl(url: string): string;
+/** Header name used by the server to signal a version skew reload. */
+export declare const RELOAD_HEADER = "X-Timber-Reload";
+/** Header name for the client's deployment ID. */
+export declare const DEPLOYMENT_ID_HEADER = "X-Timber-Deployment-Id";
+/**
+ * Check if a response signals a version skew reload.
+ * Triggers a full page reload if the server indicates the client is stale.
+ */
+export declare function checkReloadSignal(response: Response): boolean;
+/**
+ * Build the headers for an RSC payload request.
+ *
+ * **Every header added here is hashed into the payload URL** as the `_rsc`
+ * cache key (see `rscCacheKey`), and URLs are logged by proxies, CDNs, and
+ * origin access logs. So: no credentials, no session identifiers, no
+ * user-supplied content. `fnv1aHash` is a cache-key hash, not a KDF — a
+ * low-entropy secret would be recoverable from the URL by brute force.
+ * Authentication already travels on cookies, which are not part of this
+ * object and never enter the key.
+ */
+export declare function buildRscHeaders(stateTree: StateTree | undefined, currentUrl?: string): Record<string, string>;
 /**
  * Extract segment metadata from the X-Timber-Segments response header.
  * Returns null if the header is missing or malformed.
  *
- * Format: JSON array of {path, isAsync} objects describing the rendered
+ * Format: JSON array of {path, isRequestDependent} objects describing the rendered
  * segment chain from root to leaf. Used to populate the client-side
  * segment cache for state tree diffing on subsequent navigations.
  */
@@ -51,13 +103,6 @@ export declare function extractSegmentInfo(response: Response): SegmentInfo[] |
  * The client uses this to merge the partial payload with cached segments.
  */
 export declare function extractSkippedSegments(response: Response): string[] | null;
-/**
- * Extract route params from the X-Timber-Params response header.
- * Returns null if the header is missing or malformed.
- *
- * Used to populate useParams() after client-side navigation.
- */
-export declare function extractParams(response: Response): Record<string, string | string[]> | null;
 /**
  * Thrown when an RSC payload response contains X-Timber-Redirect header.
  * Caught in navigate() to trigger a soft router navigation to the redirect target.
@@ -67,14 +112,51 @@ export declare class RedirectError extends Error {
     constructor(url: string);
 }
 /**
- * Fetch an RSC payload from the server. If a decodeRsc function is provided,
- * the response is decoded into a React element tree via createFromFetch.
- * Otherwise, the raw response text is returned (test mode).
+ * Thrown when the server signals a version skew (X-Timber-Reload header).
+ * Caught in navigate() to trigger a full page reload.
+ * See TIM-446.
+ */
+export declare class VersionSkewError extends Error {
+    constructor();
+}
+/**
+ * Thrown when the server returns an error for an RSC payload request.
+ * The server sends X-Timber-Error header and a JSON body instead of a
+ * RSC stream it cannot answer in-SPA (a deny that needs a fallback page, a
+ * broken first read). Caught in
+ * navigate() to trigger a hard navigation so the server can render
+ * the error page as HTML.
+ *
+ * See design/10-error-handling.md §"Error Page Rendering for Client Navigation"
+ */
+export declare class ServerErrorResponse extends Error {
+    readonly status: number;
+    readonly url: string;
+    constructor(status: number, url: string);
+}
+/**
+ * Thrown when the RSC fetch response has a Content-Type that is not
+ * text/x-component — e.g., a static asset (image, CSS, JS) served
+ * for a same-origin URL that isn't a route. The response body is
+ * cancelled immediately (headers-only cost). Caught in navigate()
+ * to trigger a hard navigation; caught in prefetch() to store a
+ * negative cache entry so click hard-navigates without a second fetch.
+ *
+ * See TIM-1231.
+ */
+export declare class NonRscResponse extends Error {
+    readonly url: string;
+    constructor(url: string);
+}
+/**
+ * Fetch an RSC payload from the server and start decoding it.
  *
- * Also extracts head elements from the X-Timber-Head response header
- * so the client can update document.title and <meta> tags after navigation.
+ * Every response is classified here, once: a version-skew reload, a 204 or
+ * 3xx redirect, a server error envelope and a non-RSC body are each turned
+ * into their error before `decodeRsc` sees the body. There is no second
+ * path — tests decode real Flight bytes through the same code (TIM-1541).
  */
 export declare function fetchRscPayload(url: string, deps: RouterDeps, stateTree?: {
     segments: string[];
-}, currentUrl?: string): Promise<FetchResult>;
+}, currentUrl?: string, signal?: AbortSignal): Promise<FetchResult>;
 //# sourceMappingURL=rsc-fetch.d.ts.map