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

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

@@ -0,0 +1,272 @@
+/**
+ * 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 { HistoryStack } from './history.ts';
+import type { TransitionResult, CommitOutcome, RenderOwner } from './navigation-transition.ts';
+import type { NavigationEpoch } from './router-lifecycle.ts';
+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;
+    /**
+     * 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 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, 
+/**
+ * Publishes the state that makes this tree the current page (segment
+ * cache, pathname, history stack, address bar). The renderer runs it when
+ * the tree is on screen — in production from React's commit of the tree
+ * (`NavigationRoot`'s layout effect), a test double synchronously. It is not run before
+ * handing the tree over: a replay or revalidation whose tree suspends is
+ * given to React without being on screen, and publishing then advertises
+ * slot content keys the slot content cache has not recorded (TIM-1423).
+ */
+commit: () => void) => 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, owner: RenderOwner, 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?: {
+        onCommit?: (outcome: CommitOutcome) => void;
+    }): 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;
+    /**
+     * Snapshot the router's navigation state before dispatching a server action.
+     * Hand the epoch back to `applyActionResult` with the response (TIM-1474).
+     */
+    epoch(): NavigationEpoch;
+    /**
+     * 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;
+    /**
+     * Invalidate client caches for a path so the next navigation fetches
+     * fresh data. Called when `revalidatePath` targeted a non-current path.
+     */
+    invalidatePath(path: string): 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. The current URL's history entry is preserved
+     * so `applyActionResult` can read its segment metadata.
+     */
+    evictStaleCaches(): 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.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":"AAyBA,OAAO,KAAK,EAAqB,UAAU,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAKvF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,cAAc,CAwd7D"}

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.
@@ -66,15 +111,48 @@ export declare class RedirectError extends Error {
     readonly redirectUrl: string;
     constructor(url: string);
 }
+/**
+ * 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
+ * broken RSC stream for any RenderError (4xx or 5xx). 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. 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).
- *
- * Also extracts head elements from the X-Timber-Head response header
- * so the client can update document.title and <meta> tags after navigation.
  */
 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

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

@@ -1 +1 @@
-{"version":3,"file":"rsc-fetch.d.ts","sourceRoot":"","sources":["../../src/client/rsc-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAI3C,uFAAuF;AACvF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACnC,uFAAuF;IACvF,WAAW,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IAClC,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IACjD,+EAA+E;IAC/E,eAAe,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAClC;AAID,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AA2BnD,wBAAgB,eAAe,CAC7B,SAAS,EAAE;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,SAAS,EAC7C,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAexB;AAID;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,EAAE,GAAG,IAAI,CAQ5E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,EAAE,GAAG,IAAI,CAQ3E;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,EAAE,GAAG,IAAI,CAS1E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAQ1F;AAID;;;GAGG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBACjB,GAAG,EAAE,MAAM;CAIxB;AAID;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,UAAU,EAChB,SAAS,CAAC,EAAE;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,EAClC,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,WAAW,CAAC,CAuDtB"}
+{"version":3,"file":"rsc-fetch.d.ts","sourceRoot":"","sources":["../../src/client/rsc-fetch.ts"],"names":[],"mappings":"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"}