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

package/dist/client/internal.js

@@ -0,0 +1,1624 @@
+import { t as RSC_CONTENT_TYPE } from "../_chunks/rsc-media-type-DRqE_lD_.js";
+import { a as randomRscCacheKey, n as RSC_KEY_PARAM, o as recordLookup, s as rscCacheKey } from "../_chunks/rsc-cache-key-DD0fl_-s.js";
+import { i as withBasePath, r as stripBasePath } from "../_chunks/base-path-DaQrzbez.js";
+import { t as rscPayloadPath } from "../_chunks/rsc-payload-path-B_LBodc2.js";
+import { i as _setCachedSearch, l as cachedSearch, n as getSsrData, r as setSsrData, t as clearSsrData, u as cachedSearchParams } from "../_chunks/ssr-data-14MXm7Pj.js";
+import { n as getRouterOrNull, r as setGlobalRouter, t as getRouter } from "../_chunks/router-ref-DuYuV_0Q.js";
+import { i as markStaleFromError, n as isClientStale, r as markClientStale, t as TimberErrorBoundary } from "../_chunks/error-boundary-D-ODYX41.js";
+import { n as useSegmentContext, t as SegmentProvider } from "../_chunks/segment-context-CjOlyB8Y.js";
+import "../_chunks/rsc-error-envelope-tT5PJs4q.js";
+import { a as supersedeNavigationTransitions, c as setNavigationState, i as setHardNavigating, l as useNavigationContext, n as setCurrentSlotParams, o as NavigationProvider, s as getNavigationState, t as setCurrentParams } from "../_chunks/use-segment-params-C4r4BD9T.js";
+import { t as bindUseQueryStates } from "../_chunks/use-query-states-I3JMng6J.js";
+//#region src/shared/payload-root.ts
+/**
+* What a reader gets when the value it was handed is not a payload root.
+*
+* In the browser this is unreachable for a real response: all four producers
+* of a route payload go through `withPublishedParams`, and a client talking to
+* a different build is answered with 204 at Stage 1c
+* (`server/pipeline-phases.ts`) before any payload exists. It is reachable in
+* the router's test/fallback path, where `decodeRsc` is absent and the
+* "payload" is the raw response text.
+*/
+var NO_PUBLISHED_PARAMS = {
+	params: {},
+	slotParams: null
+};
+/** True when `value` carries published params — a root, or a read of one. */
+function hasPublishedParams(value) {
+	return typeof value === "object" && value !== null && "params" in value && typeof value.params === "object" && value.params !== null;
+}
+/**
+* Read the params published beside a tree.
+*
+* Accepts a payload root *or* a `PublishedParams` already split off one, so
+* the client can pre-resolve on the navigation path and still hand the same
+* value to the same provider. Never throws.
+*/
+function readPublishedParams(source) {
+	if (!hasPublishedParams(source)) return NO_PUBLISHED_PARAMS;
+	return {
+		params: source.params,
+		slotParams: source.slotParams ?? null
+	};
+}
+/**
+* Read the renderable tree out of a payload root.
+*
+* Returns the value unchanged when it is not a root — the router's fallback
+* path stores raw response text under the same name, and a test asserting on
+* that text should see the text.
+*/
+function readPayloadTree(root) {
+	if (typeof root === "object" && root !== null && "tree" in root && hasPublishedParams(root)) return root.tree;
+	return root;
+}
+/**
+* Split a decoded payload root into its tree and its params.
+*
+* Accepts a settled root or a thenable of one, and preserves which it was: a
+* settled root splits synchronously, so no code path gains a suspend point it
+* did not already have.
+*/
+function splitPayloadRoot(root) {
+	if (typeof root !== "object" || root === null || typeof root.then !== "function") return {
+		tree: readPayloadTree(root),
+		params: readPublishedParams(root)
+	};
+	const settled = root;
+	const tree = Promise.resolve(settled).then(readPayloadTree);
+	tree.catch(() => {});
+	return {
+		tree,
+		params: Promise.resolve(settled).then(readPublishedParams, () => NO_PUBLISHED_PARAMS)
+	};
+}
+//#endregion
+//#region src/client/segment-cache.ts
+/**
+* Maintains the client-side segment tree representing currently mounted
+* layouts and pages. Used for navigation reconciliation — the router diffs
+* new routes against this tree to determine which segments to re-fetch.
+*/
+var SegmentCache = class {
+	root;
+	get(segment) {
+		if (segment === "/" || segment === this.root?.segment) return this.root;
+	}
+	set(segment, node) {
+		if (segment === "/" || !this.root) this.root = node;
+	}
+	clear() {
+		this.root = void 0;
+	}
+	/**
+	* Serialize the mounted segment tree for the X-Timber-State-Tree header.
+	* Only includes sync segments — async segments are excluded because the
+	* server must always re-render them (they may depend on request context).
+	*
+	* When mergeableFilter is provided, only segments whose paths are in the
+	* set are included. This ensures the server only skips segments that the
+	* client can actually merge (i.e., segments whose cached element tree
+	* contains an inner SegmentProvider the merger can splice into).
+	*
+	* `treePaths` is collected UNFILTERED, unlike `segments` and `slots`. Those
+	* two answer "what may the server skip re-rendering?", so every reason a
+	* segment cannot be reused is a reason to leave it out. `treePaths` answers
+	* "what is mounted right now?" for interception scoping — a request-dependent
+	* layout is still on screen, and dropping it would silently narrow the scope
+	* the server sees and cancel a modal that should open (TIM-1282).
+	*
+	* This is a performance optimization only, NOT a security boundary.
+	* The server always runs all access.ts files regardless of the state tree.
+	*/
+	serializeStateTree(mergeableFilter) {
+		const segments = [];
+		const slots = [];
+		const treePaths = [];
+		if (this.root) {
+			collectSyncSegments(this.root, segments, mergeableFilter);
+			collectSyncSlots(this.root, slots);
+			collectTreePaths(this.root, treePaths);
+		}
+		const tree = { segments };
+		if (slots.length > 0) tree.slots = slots;
+		if (treePaths.length > 0) tree.treePaths = treePaths;
+		return tree;
+	}
+};
+/** Recursively collect sync segment paths from the tree */
+function collectSyncSegments(node, out, mergeableFilter) {
+	if (!node.isRequestDependent && (!mergeableFilter || mergeableFilter.has(node.segment))) out.push(node.segment);
+	for (const child of node.children.values()) collectSyncSegments(child, out, mergeableFilter);
+}
+/**
+* Recursively collect the `app/` directory path of every mounted segment.
+*
+* Slots are not walked: a slot's own sub-tree can never own an intercepting
+* slot's scope, because scopes are always ordinary segments (`interception.ts`
+* derives one from the slot owner's ancestor chain).
+*/
+function collectTreePaths(node, out) {
+	if (node.treePath) out.push(node.treePath);
+	for (const child of node.children.values()) collectTreePaths(child, out);
+}
+/**
+* Recursively collect content keys from cacheable slots.
+*
+* The server advertises a content key per slot on every render (TIM-1370),
+* encoding the owner's URL parts, the slot name, the matched entry file,
+* and the slot's params. The client stores this key and sends it back on
+* the next navigation so the server can decide skips by key membership —
+* no departing URL reconstruction needed.
+*/
+function collectSyncSlots(node, out) {
+	if (node.slots) {
+		for (const slot of node.slots.values()) if (!slot.isRequestDependent && !slot.denied && slot.contentKey) out.push(slot.contentKey);
+	}
+	for (const child of node.children.values()) collectSyncSlots(child, out);
+}
+/**
+* Build a SegmentNode tree from flat segment metadata.
+*
+* Takes an ordered list of segment descriptors (root → leaf) from the
+* server's X-Timber-Segments header and constructs the hierarchical
+* tree structure that SegmentCache expects.
+*
+* Each segment is nested as a child of the previous one, forming a
+* linear chain from root to leaf. The leaf segment (page) is excluded
+* from the tree — pages are never cached across navigations.
+*/
+function buildSegmentTree(segments) {
+	if (segments.length === 0) return void 0;
+	const segmentEntries = [];
+	const slotEntries = [];
+	for (const info of segments) if (info.slot) slotEntries.push(info);
+	else segmentEntries.push(info);
+	let root;
+	let parent;
+	const nodeById = /* @__PURE__ */ new Map();
+	for (const info of segmentEntries) {
+		const id = info.segmentId ?? info.path;
+		const node = {
+			segment: id,
+			treePath: info.treePath,
+			payload: null,
+			isRequestDependent: info.isRequestDependent,
+			children: /* @__PURE__ */ new Map()
+		};
+		nodeById.set(id, node);
+		if (!root) root = node;
+		if (parent) parent.children.set(id, node);
+		parent = node;
+	}
+	for (const slotInfo of slotEntries) {
+		const parentId = slotInfo.parentSegment;
+		const parentNode = parentId ? nodeById.get(parentId) : root;
+		if (!parentNode) continue;
+		const slotId = slotInfo.segmentId ?? slotInfo.path;
+		const slotNode = {
+			segment: slotId,
+			payload: null,
+			isRequestDependent: slotInfo.isRequestDependent,
+			children: /* @__PURE__ */ new Map(),
+			denied: slotInfo.denied,
+			contentKey: slotInfo.contentKey
+		};
+		if (!parentNode.slots) parentNode.slots = /* @__PURE__ */ new Map();
+		parentNode.slots.set(slotId, slotNode);
+	}
+	return root;
+}
+/** Sentinel value for negative cache entries (URL is not a route). */
+var NEGATIVE_ENTRY = Object.freeze({ payload: null });
+/**
+* Compose the map key. Length-prefixed rather than delimiter-joined for the
+* same reason `shared/rsc-cache-key.ts` is: any delimiter is forgeable by a
+* value containing it, and a URL may contain any character a delimiter could.
+*/
+function prefetchMapKey(key) {
+	return `${key.from.length}:${key.from}:${key.scope.length}:${key.scope}:${key.url}`;
+}
+/**
+* The `scope` half of a `PrefetchKey`, derived from the state tree that will
+* actually be sent. Taking it from the header value rather than re-walking the
+* cache is the point: the key varies by exactly what the request varies by.
+*/
+function prefetchScopeOf(stateTree) {
+	return stateTree?.treePaths?.join("\0") ?? "";
+}
+/**
+* Short-lived cache for hover-triggered prefetches. Entries expire after
+* 30 seconds. When a link is clicked, the prefetched payload is consumed
+* (moved to the history stack) and removed from this cache.
+*
+* timber.js does NOT prefetch on viewport intersection — only explicit
+* hover on <Link prefetch> triggers a prefetch.
+*/
+var PrefetchCache = class PrefetchCache {
+	static TTL_MS = 3e4;
+	entries = /* @__PURE__ */ new Map();
+	set(key, result) {
+		this.entries.set(prefetchMapKey(key), {
+			result,
+			expiresAt: Date.now() + PrefetchCache.TTL_MS
+		});
+	}
+	get(key) {
+		const mapKey = prefetchMapKey(key);
+		const entry = this.entries.get(mapKey);
+		if (!entry) return void 0;
+		if (Date.now() >= entry.expiresAt) {
+			this.entries.delete(mapKey);
+			return;
+		}
+		return entry.result;
+	}
+	/** Get and remove the entry (used when navigation consumes a prefetch) */
+	consume(key) {
+		const result = this.get(key);
+		if (result !== void 0) this.entries.delete(prefetchMapKey(key));
+		return result;
+	}
+	/**
+	* Store a negative entry — the URL is not a route (non-RSC Content-Type).
+	*
+	* Keyed like every other entry even though "not a route" does not actually
+	* vary by departing URL: a source-independent negative would be a second
+	* keying rule to keep correct, and the only cost of the uniform one is a
+	* repeated fetch for a link hovered from a second page.
+	*/
+	setNegative(key) {
+		this.set(key, NEGATIVE_ENTRY);
+	}
+	/** Check if the entry is a negative cache entry (URL is not a route). */
+	isNegative(key) {
+		return this.get(key) === NEGATIVE_ENTRY;
+	}
+};
+//#endregion
+//#region src/client/history.ts
+/**
+* Session-lived history stack keyed by URL. Enables instant back/forward
+* navigation without a server roundtrip.
+*
+* On forward navigation, the new page's payload is pushed onto the stack.
+* On popstate, the cached payload is replayed instantly.
+*
+* Entries are keyed by pathname + search. Used with the History API
+* fallback and the Navigation API.
+*
+* Scroll positions are stored in history.state or Navigation API entry
+* state, not in this stack — see design/19-client-navigation.md §Scroll Restoration.
+*
+* Entries persist for the session duration (no expiry) and are cleared
+* when the tab is closed — matching browser back-button behavior.
+*/
+var HistoryStack = class {
+	entries = /* @__PURE__ */ new Map();
+	push(url, entry) {
+		this.entries.set(url, entry);
+	}
+	get(url) {
+		return this.entries.get(url);
+	}
+	has(url) {
+		return this.entries.has(url);
+	}
+};
+//#endregion
+//#region src/client/navigation-commit.ts
+/**
+* What it means for a page to be "current" on the client.
+*
+* One module owns every write that makes a navigation's destination the
+* current page, and the read that describes the current page back to the
+* server. Keeping them together is the point: `X-Timber-State-Tree` is
+* derived from the segment cache, so the thing that publishes and the thing
+* that reports have to agree about when a page becomes current.
+*
+* See design/19-client-navigation.md §"State Update Invariants".
+*/
+/**
+* Derive the navigation state (pathname + search) a URL renders with.
+*
+* Pure: publishing it — the module-level fallback for tests and SSR, and the
+* globalThis bridge — is `prepareNavigation`'s commit, which runs only once
+* the render is known to have won (TIM-1301). Callers pass the returned value
+* explicitly to renderRoot/wrapPayload, so a render never depends on the
+* publish having happened first.
+*/
+function deriveNavigationState(url) {
+	const parsed = new URL(url, "http://localhost");
+	return {
+		pathname: parsed.pathname || "/",
+		search: parsed.search
+	};
+}
+function createNavigationCommitter(deps) {
+	const { segmentCache, historyStack } = deps;
+	/**
+	* Update the segment cache from server-provided segment metadata.
+	*
+	* Runs whether or not `clientSegmentCache` is enabled: the tree is also
+	* where the mounted tree paths come from, and those cross on every
+	* navigation. What the flag gates is which parts get serialized — see
+	* `currentStateTree`.
+	*/
+	function updateSegmentCache(segmentInfo) {
+		if (!segmentInfo || segmentInfo.length === 0) return;
+		const tree = buildSegmentTree(segmentInfo);
+		if (tree) segmentCache.set("/", tree);
+	}
+	return {
+		updateSegmentCache,
+		/**
+		* The X-Timber-State-Tree to send with the next RSC request.
+		*
+		* Two different things travel on one header. `segments`/`slots` are the
+		* caching opt-in and are omitted unless `clientSegmentCache` is on.
+		* `treePaths` is how the server learns which route is actually mounted,
+		* which stops being derivable from the address bar as soon as a modal is
+		* open — so it crosses regardless (TIM-1282). Undefined when there is
+		* nothing to say, so a no-op header never enters the `_rsc` cache key.
+		*
+		* Reads what the last *committed* navigation published, so a superseded
+		* navigation's destination can never end up describing the mounted tree
+		* (TIM-1301).
+		*/
+		currentStateTree() {
+			const tree = segmentCache.serializeStateTree();
+			if (deps.clientSegmentCache()) return tree;
+			return tree.treePaths ? {
+				segments: [],
+				treePaths: tree.treePaths
+			} : void 0;
+		},
+		/**
+		* Prepare all navigation-owned state for a new page — without publishing
+		* any of it. Every code path that changes the "current page" must go
+		* through this function, which is what makes "forgot a field" impossible
+		* by construction.
+		*
+		* Returns the destination's `NavigationState`, which is a pure function of
+		* the URL and is what the incoming tree is *rendered* with, plus a
+		* `commit` thunk that performs the writes that make a page current:
+		* 1. Segment cache — update from server-provided segment metadata
+		* 2. Navigation state — pathname/search for usePathname/useSearchParams
+		* 3. History stack — store the payload for instant back/forward replay
+		*
+		* Nothing is written until `commit()` runs, and on a transitioned
+		* navigation it runs only once the transition is known to have won — see
+		* `renderViaTransition` and `NavigationRoot`. A navigation superseded
+		* while its payload was in flight never calls it, so the cache, the
+		* pathname the client reports and the history stack all keep describing
+		* the route still on screen (TIM-1301).
+		*
+		* Callers with state of their own to publish — the address bar, the
+		* client's record of the mounted tree — wrap this thunk rather than
+		* commit beside it, so there stays exactly one moment at which a page
+		* becomes current.
+		*/
+		prepareNavigation(url, opts) {
+			const navState = deriveNavigationState(url);
+			const segmentInfo = opts.status === void 0 || opts.status < 400 ? opts.segmentInfo : [];
+			return {
+				navState,
+				commit() {
+					if (segmentInfo && segmentInfo.length > 0) updateSegmentCache(segmentInfo);
+					else if (segmentInfo?.length === 0 || opts.clearSegmentCacheOnEmpty) segmentCache.clear();
+					setNavigationState(navState);
+					historyStack.push(url, {
+						payload: opts.payload,
+						params: opts.params,
+						segmentInfo
+					});
+				}
+			};
+		}
+	};
+}
+//#endregion
+//#region src/client/rsc-fetch.ts
+/**
+* RSC Fetch — handles fetching and parsing RSC Flight payloads.
+*
+* Extracted from router.ts to keep both files under the 500-line limit.
+* This module handles:
+* - Cache-busting URL generation for RSC requests
+* - Building RSC request headers (Accept, X-Timber-State-Tree)
+* - Extracting metadata from RSC response headers
+* - Fetching and decoding RSC payloads
+*
+* See design/19-client-navigation.md §"RSC Payload Handling"
+*/
+/**
+* Append a `_rsc=<key>` query parameter to the URL (TIM-1268).
+*
+* The key is a deterministic hash of the RSC request headers, so identical
+* requests share a URL and the payload becomes cacheable. It also keeps the
+* document and the payload on different URLs, so a shared cache cannot
+* return HTML for an RSC request (or vice versa) even where `Vary` is
+* opt-in configuration rather than default behaviour — Cloudflare and
+* CloudFront both. See GHSA-wfc6-r584-vfw7, design/13-security.md.
+*
+* The origin recomputes this key from the received headers and refuses to
+* let a mismatched response be shared-cached, so a caller cannot claim
+* another client's key while sending its own headers.
+*
+* Falls back to a random value when no key can be derived — `crypto.subtle`
+* is absent in non-secure browsing contexts (plain `http://` on a LAN
+* address). Dropping the parameter instead would put the payload back on
+* the document URL, where a query-keyed cache that ignores `Vary` could
+* store a Flight response under `/about` and serve it to an HTML
+* navigation. The random parameter this feature replaced did separate those
+* representations, and the fallback must not be worse than what it
+* replaced. The origin cannot verify a random key, so it refuses to
+* share-cache the response — which is exactly the old behaviour, where a
+* unique URL was never a cache hit anyway.
+*
+* Strips any #fragment before appending — fragments are client-only and
+* fetch() discards them, so _rsc would land inside the hash and be lost.
+*/
+async function appendRscParam(url, headers) {
+	const hashIndex = url.indexOf("#");
+	const urlWithoutHash = hashIndex === -1 ? url : url.slice(0, hashIndex);
+	const key = await rscCacheKey(recordLookup(headers)) ?? randomRscCacheKey();
+	return `${urlWithoutHash}${urlWithoutHash.includes("?") ? "&" : "?"}${RSC_KEY_PARAM}=${key}`;
+}
+/**
+* The client's deployment ID, set at bootstrap from the runtime config.
+* Sent with every RSC/action request for version skew detection.
+* Null in dev mode. See TIM-446.
+*/
+var clientDeploymentId = null;
+/**
+* The deployment base path (Vite's resolved `base`), normalized.
+* Set at bootstrap from `virtual:timber-config`; `'/'` unless the app is
+* deployed under a sub-path. See design/11-platform.md, TIM-1261.
+*
+* **The base is applied in exactly one place: at fetch time**
+* (`toStaticRscUrl`). The static build writes the RSC manifest with
+* root-relative keys *and* root-relative URLs, so the generated site stays
+* relocatable and there is no second copy of the base to drift from this one.
+*/
+var basePath = "/";
+/**
+* When true, RSC fetches use _rsc/*.rsc file URLs instead of
+* the route URL with Accept headers. Static hosts ignore Accept
+* headers, so the client must fetch the pre-generated .rsc files
+* directly. Set at bootstrap from virtual:timber-config output mode.
+*/
+var staticMode = false;
+/**
+* RSC manifest mapping unhashed → content-hashed `.rsc` URLs. Populated from
+* `window.__TIMBER_RSC_MANIFEST__` (injected into HTML during static
+* generation). Shape shared with the static build that writes it — see
+* `shared/rsc-manifest.ts`. See TIM-1254.
+*/
+var rscManifest = null;
+function getRscManifest() {
+	if (rscManifest) return rscManifest;
+	if (typeof window !== "undefined" && window.__TIMBER_RSC_MANIFEST__) rscManifest = window.__TIMBER_RSC_MANIFEST__;
+	return rscManifest;
+}
+/**
+* Resolve a route URL to the `_rsc/*.rsc` file to fetch. The naming rule is
+* `shared/rsc-payload-path.ts`, shared with the build that writes the files.
+*
+* When an RSC manifest is available (hashed filenames from TIM-1254),
+* the manifest is consulted to resolve to the hashed path.
+*
+*   /           → /_rsc/index.rsc (or /_rsc/index-B7YxEKdN.rsc with manifest)
+*   /about      → /_rsc/about/index.rsc (or /_rsc/about/index-C8ZzFLfO.rsc)
+*   /blog/hello → /_rsc/blog/hello/index.rsc
+*
+* The manifest is written and read in route space (no base prefix), so the
+* base is applied here — once, on the way out. See client/base-path.ts.
+*/
+function toStaticRscUrl(url) {
+	const unhashed = toUnhashedRscUrl(url);
+	const hashedUrl = manifestLookup(unhashed);
+	return {
+		url: withBasePath(basePath, hashedUrl ?? unhashed),
+		hashed: hashedUrl !== null
+	};
+}
+/**
+* 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.
+*/
+function toUnhashedRscUrl(url) {
+	const hashIndex = url.indexOf("#");
+	const queryIndex = url.indexOf("?");
+	const hashEnd = hashIndex === -1 ? url.length : hashIndex;
+	const queryEnd = queryIndex === -1 ? url.length : queryIndex;
+	const end = Math.min(hashEnd, queryEnd);
+	let pathname = stripBasePath(basePath, url.slice(0, end));
+	if (pathname.length > 1 && pathname.endsWith("/")) pathname = pathname.slice(0, -1);
+	return rscPayloadPath(pathname);
+}
+/**
+* Look up a key in the RSC manifest, falling back to percent-decoded
+* lookup for encoded browser URLs. Returns the entry or null.
+*/
+function manifestEntry(key) {
+	const manifest = getRscManifest();
+	if (!manifest) return null;
+	if (manifest[key]) return manifest[key];
+	try {
+		const decoded = decodeURIComponent(key);
+		if (decoded !== key && manifest[decoded]) return manifest[decoded];
+	} catch {}
+	return null;
+}
+/**
+* Look up the hashed URL for an unhashed RSC path.
+*/
+function manifestLookup(key) {
+	return manifestEntry(key)?.url ?? null;
+}
+/** Header name used by the server to signal a version skew reload. */
+var RELOAD_HEADER = "X-Timber-Reload";
+/** Header name for the client's deployment ID. */
+var 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.
+*/
+function checkReloadSignal(response) {
+	return response.headers.get(RELOAD_HEADER) === "1";
+}
+/**
+* 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.
+*/
+function buildRscHeaders(stateTree, currentUrl) {
+	const headers = { Accept: RSC_CONTENT_TYPE };
+	if (stateTree) headers["X-Timber-State-Tree"] = JSON.stringify(stateTree);
+	if (currentUrl) headers["X-Timber-URL"] = currentUrl;
+	if (clientDeploymentId) headers[DEPLOYMENT_ID_HEADER] = clientDeploymentId;
+	return headers;
+}
+/** Dev-only warning for malformed framework headers. Tree-shaken in production. */
+function warnMalformedHeader(headerName, raw) {
+	if (process.env.NODE_ENV !== "production") {
+		const preview = raw.length > 200 ? raw.slice(0, 200) + "…" : raw;
+		console.warn(`[timber] Malformed ${headerName} header \u2014 JSON.parse failed. This indicates a framework bug or header corruption. Raw (first 200 chars): ${preview}`);
+	}
+}
+/**
+* Extract segment metadata from the X-Timber-Segments response header.
+* Returns null if the header is missing or malformed.
+*
+* 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.
+*/
+function extractSegmentInfo(response) {
+	const header = response.headers.get("X-Timber-Segments");
+	if (!header) return null;
+	try {
+		return JSON.parse(header);
+	} catch {
+		warnMalformedHeader("X-Timber-Segments", header);
+		return null;
+	}
+}
+/**
+* Extract skipped segment paths from the X-Timber-Skipped-Segments header.
+* Returns null if the header is missing or malformed.
+*
+* When the server skips sync layouts the client already has cached,
+* it sends this header listing the skipped segment paths (outermost first).
+* The client uses this to merge the partial payload with cached segments.
+*/
+function extractSkippedSegments(response) {
+	const header = response.headers.get("X-Timber-Skipped-Segments");
+	if (!header) return null;
+	try {
+		const parsed = JSON.parse(header);
+		return Array.isArray(parsed) ? parsed : null;
+	} catch {
+		warnMalformedHeader("X-Timber-Skipped-Segments", header);
+		return 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.
+*/
+var RedirectError = class extends Error {
+	redirectUrl;
+	constructor(url) {
+		super(`Server redirect to ${url}`);
+		this.redirectUrl = url;
+	}
+};
+/**
+* Thrown when the server signals a version skew (X-Timber-Reload header).
+* Caught in navigate() to trigger a full page reload.
+* See TIM-446.
+*/
+var VersionSkewError = class extends Error {
+	constructor() {
+		super("Version skew detected — server has been redeployed");
+	}
+};
+/**
+* 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"
+*/
+var ServerErrorResponse = class extends Error {
+	status;
+	url;
+	constructor(status, url) {
+		super(`Server error ${status} during navigation to ${url}`);
+		this.status = status;
+		this.url = url;
+	}
+};
+/**
+* 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.
+*/
+var NonRscResponse = class extends Error {
+	url;
+	constructor(url) {
+		super(`Non-RSC response for ${url}`);
+		this.url = url;
+	}
+};
+/**
+* Wrap a response body stream to track when it's fully consumed.
+* Returns a new body that passes all chunks through unchanged, plus
+* a `done` promise that resolves when the last chunk is read (or
+* rejects if the stream errors).
+*
+* createFromFetch's thenable resolves on shell arrival, but callers need to
+* know when the stream is fully decoded: that is what `navigateTransition`'s
+* returned promise means, and what the router's pending store, the Navigation
+* API deferred and `<Link>`'s `isPending` are all timed against.
+*/
+function trackStreamCompletion(body) {
+	let resolveDone;
+	let rejectDone;
+	const done = new Promise((res, rej) => {
+		resolveDone = res;
+		rejectDone = rej;
+	});
+	const reader = body.getReader();
+	return {
+		body: new ReadableStream({
+			async pull(controller) {
+				try {
+					const result = await reader.read();
+					if (result.done) {
+						controller.close();
+						resolveDone();
+					} else controller.enqueue(result.value);
+				} catch (error) {
+					controller.error(error);
+					rejectDone(error);
+				}
+			},
+			cancel(reason) {
+				reader.cancel(reason);
+				resolveDone();
+			}
+		}),
+		done
+	};
+}
+/**
+* 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).
+*/
+async function fetchRscPayload(url, deps, stateTree, currentUrl, signal) {
+	const staticTarget = staticMode ? toStaticRscUrl(url) : null;
+	const fetchTarget = staticTarget ? staticTarget.url : url;
+	const headers = staticMode ? buildRscHeaders(void 0, void 0) : buildRscHeaders(stateTree, currentUrl);
+	const rscUrl = staticTarget?.hashed ? fetchTarget : await appendRscParam(fetchTarget, headers);
+	signal?.throwIfAborted();
+	if (deps.decodeRsc) {
+		const fetchPromise = deps.fetch(rscUrl, {
+			headers,
+			redirect: "manual",
+			signal
+		});
+		let segmentInfo = null;
+		let skippedSegments = null;
+		let status = 200;
+		let streamDone = Promise.resolve();
+		const wrappedPromise = fetchPromise.then((response) => {
+			if (checkReloadSignal(response)) throw new VersionSkewError();
+			const redirectLocation = response.headers.get("X-Timber-Redirect") || (response.status >= 300 && response.status < 400 ? response.headers.get("Location") : null);
+			if (redirectLocation) throw new RedirectError(redirectLocation);
+			if (response.headers.get("X-Timber-Error") === "1") throw new ServerErrorResponse(response.status, url);
+			if (staticMode) {
+				const contentType = response.headers.get("content-type");
+				if (!response.ok || contentType && contentType.split(";")[0].trim().toLowerCase() === "text/html") {
+					response.body?.cancel();
+					throw new NonRscResponse(url);
+				}
+			} else {
+				const contentType = response.headers.get("content-type");
+				if (!contentType || !contentType.split(";")[0].trim().includes("text/x-component")) {
+					response.body?.cancel();
+					throw new NonRscResponse(url);
+				}
+			}
+			segmentInfo = extractSegmentInfo(response);
+			skippedSegments = extractSkippedSegments(response);
+			status = response.status;
+			if (response.body) {
+				const tracked = trackStreamCompletion(response.body);
+				streamDone = tracked.done;
+				streamDone.catch(() => {});
+				return new Response(tracked.body, {
+					headers: response.headers,
+					status: response.status
+				});
+			}
+			return response;
+		});
+		await wrappedPromise;
+		const root = deps.decodeRsc(wrappedPromise);
+		const { tree: payload, params } = splitPayloadRoot(root);
+		const payloadError = new Promise((_, reject) => {
+			Promise.resolve(root).then(() => {}, reject);
+		});
+		payloadError.catch(() => {});
+		const decodePromise = Promise.race([streamDone, payloadError]);
+		decodePromise.catch(() => {});
+		return {
+			payload,
+			params,
+			decodePromise,
+			segmentInfo,
+			skippedSegments,
+			status
+		};
+	}
+	const response = await deps.fetch(rscUrl, {
+		headers,
+		redirect: "manual",
+		signal
+	});
+	if (response.status >= 300 && response.status < 400) {
+		const location = response.headers.get("Location");
+		if (location) throw new RedirectError(location);
+	}
+	if (response.headers.get("X-Timber-Error") === "1") throw new ServerErrorResponse(response.status, url);
+	if (staticMode) {
+		const fallbackContentType = response.headers.get("content-type");
+		if (!response.ok || fallbackContentType && fallbackContentType.split(";")[0].trim().toLowerCase() === "text/html") {
+			response.body?.cancel();
+			throw new NonRscResponse(url);
+		}
+	} else {
+		const fallbackContentType = response.headers.get("content-type");
+		if (!fallbackContentType || !fallbackContentType.split(";")[0].trim().includes("text/x-component")) {
+			response.body?.cancel();
+			throw new NonRscResponse(url);
+		}
+	}
+	return {
+		payload: await response.text(),
+		params: readPublishedParams(void 0),
+		decodePromise: null,
+		segmentInfo: extractSegmentInfo(response),
+		skippedSegments: extractSkippedSegments(response),
+		status: response.status
+	};
+}
+//#endregion
+//#region src/client/router-skew.ts
+/**
+* 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.
+*/
+function recordSkew(error) {
+	if (error instanceof VersionSkewError) {
+		markClientStale();
+		return true;
+	}
+	return markStaleFromError(error);
+}
+//#endregion
+//#region src/client/router-effects.ts
+/**
+* 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"
+*/
+function createScrollEffects(deps) {
+	/** Run a callback after the next paint (after React commit). */
+	function afterPaint(callback) {
+		if (deps.afterPaint) deps.afterPaint(callback);
+		else callback();
+	}
+	function restoreScrollAfterPaint(scrollY) {
+		afterPaint(() => {
+			deps.scrollTo(0, scrollY);
+			window.dispatchEvent(new Event("timber:scroll-restored"));
+		});
+	}
+	function scrollToHashAfterPaint(hash) {
+		afterPaint(() => {
+			if (deps.scrollToHash?.(hash) !== true) deps.scrollTo(0, 0);
+			window.dispatchEvent(new Event("timber:scroll-restored"));
+		});
+	}
+	return {
+		restoreScrollAfterPaint,
+		scrollToHashAfterPaint
+	};
+}
+/**
+* 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)).
+*/
+function leaveSpa(url, fromUrl) {
+	setHardNavigating(true);
+	hardNavigate(url, fromUrl);
+	return new Promise(() => {});
+}
+/**
+* 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).
+*/
+function createSpaExits({ currentNavAbort, supersede }) {
+	async function leaveSpaIfOwned(navAbort, url, fromUrl) {
+		if (currentNavAbort() !== navAbort) return;
+		await leaveSpa(url, fromUrl);
+	}
+	function leaveSpaSuperseding(url, fromUrl) {
+		supersede();
+		return leaveSpa(url, fromUrl);
+	}
+	return {
+		leaveSpaIfOwned,
+		leaveSpaSuperseding
+	};
+}
+/**
+* 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}.
+*/
+function createNavigationRecovery({ currentNavAbort, leaveSpaIfOwned, navigate }) {
+	return async function recoverFromNavigationError(error, navAbort, url, fromUrl) {
+		if (error instanceof RedirectError) {
+			if (currentNavAbort() !== navAbort) return true;
+			await navigate(error.redirectUrl);
+			return true;
+		}
+		if (error instanceof ServerErrorResponse || error instanceof NonRscResponse || recordSkew(error)) {
+			await leaveSpaIfOwned(navAbort, url, fromUrl);
+			return true;
+		}
+		return false;
+	};
+}
+/**
+* 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).
+*/
+function hardNavigate(url, fromUrl) {
+	const current = new URL(fromUrl, window.location.origin);
+	const target = new URL(url, window.location.origin);
+	if (target.pathname === current.pathname && target.search === current.search) {
+		window.location.href = url;
+		window.location.reload();
+	} else window.location.href = url;
+}
+//#endregion
+//#region src/client/router-lifecycle.ts
+/**
+* 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".
+*/
+/**
+* Check if an error is an abort error (connection closed / fetch aborted).
+* Browsers throw DOMException with name 'AbortError' when a fetch is aborted.
+*/
+function isAbortError(error) {
+	if (error instanceof DOMException && error.name === "AbortError") return true;
+	if (error instanceof Error && error.name === "AbortError") return true;
+	return false;
+}
+function createNavigationLifecycle(deps) {
+	let currentNavAbort = null;
+	let routerPhase = { phase: "idle" };
+	const pendingListeners = /* @__PURE__ */ new Set();
+	/**
+	* The controllers of navigations whose trees have been HANDED TO REACT.
+	*
+	* Its response may still be streaming: a destination reveals as soon as
+	* React can render it, so the tree on screen routinely has Suspense
+	* boundaries still waiting on later Flight rows. Aborting that response
+	* rejects those rows, and the rejection surfaces through the tree into
+	* whatever error boundary the app has — replacing the page the user is
+	* looking at with an error state, while the successor navigation is still
+	* in flight (codex on #1004).
+	*
+	* So such a navigation's stream is allowed to finish. It is finite and
+	* already in flight; the alternative is a visible error on the page being
+	* departed from. Cancelling is still correct for a navigation whose payload
+	* never reached React at all, which is the case the abort was written for.
+	*
+	* **Handed over, not committed.** This is set when the tree is given to
+	* React, not when React commits it. Marking on commit is a whole React
+	* commit phase too late: the notification would be `NavigationRoot`'s
+	* layout effect, and React runs *descendant* layout effects first — so a
+	* destination that navigates from its own mount layout effect (a redirect
+	* guard) runs before the mark and its just-committed stream gets torn out
+	* from under it. `tests/navigation-supersede.test.ts` already pins that
+	* ordering, and there is no earlier hook short of an extra sibling fiber,
+	* which would shift every `useId` in the payload (see `server/ssr-wrappers`).
+	*
+	* Handing over is the right moment on its own terms, not merely a safe
+	* over-approximation: from the instant React holds the tree it may commit
+	* it without asking, so there is no later point at which "not on screen"
+	* is still knowable from out here. The residue is that a navigation
+	* superseded in the window between handover and commit keeps streaming a
+	* payload nobody sees — bandwidth on a finite response, against a visible
+	* error page the other way (codex on #1004, second round).
+	*
+	* A SET, not a single slot. Between a successor's handover and its commit
+	* React is still showing the previous tree — that is what the transition
+	* buys — so the previous navigation's stream is still feeding the screen and
+	* must stay unabortable. Entries are dropped when a later tree actually
+	* commits (`forgetOlderHandoffs`), which is the moment the trees they fed
+	* are gone. A single slot made a legitimate handover steal protection from
+	* a stream still on screen, and let a superseded navigation overwrite the
+	* winner's entry outright.
+	*/
+	const handedOffNavAborts = /* @__PURE__ */ new Set();
+	/**
+	* Cancel a navigation's RSC fetch — unless its tree is the one on screen.
+	*
+	* THE only place a navigation controller is aborted. Every path that gives
+	* up on a navigation calls this, so the "is this tree displayed?" question
+	* is asked once rather than at each site (the same reason `createSpaExits`
+	* exists for the SPA exits). A new abort path is a call to this, not a copy
+	* of `controller.abort()`.
+	*
+	* See `handedOffNavAborts` for why such a navigation keeps its stream.
+	*/
+	function abortUnlessHandedOff(controller) {
+		if (handedOffNavAborts.has(controller)) return;
+		controller.abort();
+	}
+	/**
+	* Create a new AbortController for a navigation, superseding any
+	* previous in-flight navigation. Optionally links to an external
+	* signal (e.g., from the Navigation API's NavigateEvent.signal).
+	*
+	* Superseding is one operation with three parts:
+	* 1. Abort the previous navigation's fetch — UNLESS its tree is the one on
+	*    screen, in which case tearing the stream down would error the page the
+	*    user is currently looking at. See `handedOffNavAborts`.
+	* 2. Invalidate its render transition so a response that already
+	*    arrived can't commit a stale tree (NavigationRoot's transId guard).
+	*    This happens either way, so skipping the abort cannot let a stale tree
+	*    displace the successor.
+	* 3. Resolve its Navigation API deferred — the superseded navigation's
+	*    finally block is staleness-guarded (see TIM-1034) and no longer
+	*    cleans up after itself, so the browser's native loading state for
+	*    the dead navigation is cleared here.
+	*/
+	function createNavAbort(externalSignal) {
+		if (currentNavAbort) {
+			abortUnlessHandedOff(currentNavAbort);
+			supersedeNavigationTransitions();
+			deps.completeRouterNavigation?.();
+		}
+		const controller = new AbortController();
+		currentNavAbort = controller;
+		if (externalSignal) if (externalSignal.aborted) abortUnlessHandedOff(controller);
+		else externalSignal.addEventListener("abort", () => abortUnlessHandedOff(controller), { once: true });
+		return controller;
+	}
+	function setPending(value, url) {
+		const next = value && url ? {
+			phase: "navigating",
+			targetUrl: url
+		} : { phase: "idle" };
+		if (routerPhase.phase === next.phase && (routerPhase.phase === "idle" || routerPhase.phase === "navigating" && next.phase === "navigating" && routerPhase.targetUrl === next.targetUrl)) return;
+		routerPhase = next;
+		for (const listener of pendingListeners) listener(value);
+	}
+	/**
+	* Wrap a navigation in the standard abort/pending/cleanup lifecycle.
+	* Consolidates the createNavAbort + setPending + staleness-guarded
+	* finally that was duplicated across navigate, refresh, and both
+	* handlePopState paths. AbortErrors are swallowed (not application
+	* errors); all other errors propagate to the caller.
+	*/
+	async function runNavigation(url, fn, externalSignal) {
+		const navAbort = createNavAbort(externalSignal);
+		setPending(true, url);
+		try {
+			await fn(navAbort);
+		} catch (error) {
+			if (isAbortError(error)) return;
+			throw error;
+		} finally {
+			if (currentNavAbort === navAbort) {
+				currentNavAbort = null;
+				setPending(false);
+				deps.completeRouterNavigation?.();
+			}
+		}
+	}
+	return {
+		currentNavAbort: () => currentNavAbort,
+		createNavAbort,
+		runNavigation,
+		markHandedOff(owner) {
+			if (currentNavAbort !== owner) return;
+			handedOffNavAborts.add(owner);
+		},
+		forgetOlderHandoffs(owner) {
+			for (const controller of handedOffNavAborts) if (controller !== owner) handedOffNavAborts.delete(controller);
+		},
+		isPending: () => routerPhase.phase === "navigating",
+		getPendingUrl: () => routerPhase.phase === "navigating" ? routerPhase.targetUrl : null,
+		onPendingChange(listener) {
+			pendingListeners.add(listener);
+			return () => pendingListeners.delete(listener);
+		}
+	};
+}
+//#endregion
+//#region src/client/router-pipeline.ts
+/**
+* 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".
+*/
+/**
+* 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.
+*/
+function departingPathname(raw) {
+	return new URL(raw, "http://localhost").pathname;
+}
+/**
+* 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.
+*/
+function prefetchKeyFor(url, departingUrl, stateTree) {
+	return {
+		url,
+		from: departingPathname(departingUrl),
+		scope: prefetchScopeOf(stateTree)
+	};
+}
+function isPartialNavigation(skippedSegments) {
+	return skippedSegments != null && skippedSegments.length > 0;
+}
+/**
+* Build a segment updates map for partial navigation. Identifies the
+* first non-skipped segment and maps it to the payload content.
+*/
+function buildSegmentUpdates(result) {
+	const skipped = new Set(result.skippedSegments);
+	const segmentInfo = result.segmentInfo;
+	const updates = /* @__PURE__ */ new Map();
+	if (segmentInfo) {
+		for (const info of segmentInfo) if (!skipped.has(info.segmentId ?? info.path)) {
+			updates.set(info.segmentId ?? info.path, result.payload);
+			break;
+		}
+	}
+	return updates;
+}
+/**
+* Inspect a decode rejection for version skew before handing the promise on,
+* without changing what the consumer sees.
+*
+* The decode rejects independently of the fetch, and not every consumer
+* awaits it — NavigationRoot drops it outright when the transition has been
+* superseded. A stale client reference arriving that way is still evidence
+* the bundle is superseded, so record it here where every consumer is fed
+* from, rather than at each place that might drop it (TIM-1275).
+*/
+function observeSkew(decodePromise) {
+	decodePromise?.catch((error) => void recordSkew(error));
+	return decodePromise;
+}
+function createNavigationPipeline({ deps, prefetchCache, currentStateTree, prepareNavigation, markHandedOff, forgetOlderHandoffs }) {
+	/** Render a decoded RSC payload into the DOM if a renderer is available. */
+	function renderPayload(payload, navState, params) {
+		if (deps.renderRoot) deps.renderRoot(payload, navState, params);
+	}
+	/**
+	* Resolve thenable payloads in the test/fallback path (no navigateTransition).
+	* In production, React handles thenables from createFromFetch directly via
+	* Suspense. In tests, renderRoot is a plain mock that expects resolved values.
+	*/
+	async function resolveForFallback(payload) {
+		if (!deps.navigateTransition && payload != null && typeof payload === "object" && "then" in payload) return await payload;
+		return payload;
+	}
+	/**
+	* Render a payload via navigateTransition (production) or renderRoot (tests).
+	* The perform callback should fetch data, prepare the commit, and return the
+	* FetchResult plus the NavigationState and the commit thunk.
+	*
+	* The thunk is handed *through* to NavigationRoot rather than called here:
+	* state management (segmentCache, navState, historyStack) has to happen on
+	* the far side of the supersession check, which only NavigationRoot can
+	* make (TIM-1301). The fallback path below has no transition to be
+	* superseded by, so it commits directly.
+	*/
+	async function renderViaTransition(url, owner, perform) {
+		const handOff = () => markHandedOff(owner);
+		const commitAndForget = (commit) => () => {
+			forgetOlderHandoffs(owner);
+			commit();
+		};
+		if (deps.navigateTransition) {
+			await deps.navigateTransition(url, async (wrapPayload) => {
+				const result = await perform();
+				const params = await result.params;
+				if (isPartialNavigation(result.skippedSegments)) {
+					const segmentUpdates = buildSegmentUpdates(result);
+					const element = wrapPayload(deps._getCurrentPayload?.() ?? result.payload, result.navState, params, segmentUpdates);
+					handOff();
+					return {
+						element,
+						decodePromise: observeSkew(result.decodePromise),
+						commit: commitAndForget(result.commit)
+					};
+				}
+				const element = wrapPayload(result.payload, result.navState, params);
+				handOff();
+				return {
+					element,
+					decodePromise: observeSkew(result.decodePromise),
+					commit: commitAndForget(result.commit)
+				};
+			});
+			return;
+		}
+		const result = await perform();
+		handOff();
+		commitAndForget(result.commit)();
+		if (!isPartialNavigation(result.skippedSegments)) renderPayload(result.payload, result.navState, await result.params);
+	}
+	/**
+	* Core navigation logic shared between the transition and fallback paths.
+	* Fetches the RSC payload, updates all state, and returns the result.
+	*/
+	async function performNavigationFetch(url, options) {
+		const stateTree = currentStateTree();
+		const cacheKey = prefetchKeyFor(url, options.departingUrl ?? deps.getCurrentUrl(), stateTree);
+		const currentUrl = cacheKey.from;
+		if (prefetchCache.isNegative(cacheKey)) {
+			prefetchCache.consume(cacheKey);
+			throw new NonRscResponse(url);
+		}
+		const prefetched = prefetchCache.consume(cacheKey);
+		let result = prefetched ? {
+			payload: prefetched.payload,
+			params: prefetched.params ?? readPublishedParams(void 0),
+			decodePromise: prefetched.decodePromise ?? null,
+			segmentInfo: prefetched.segmentInfo ?? null,
+			skippedSegments: prefetched.skippedSegments ?? null,
+			status: prefetched.status ?? 200
+		} : void 0;
+		if (result === void 0) result = await fetchRscPayload(url, deps, stateTree, currentUrl, options.signal);
+		const commitHistoryUrl = () => {
+			if (options.skipHistory) return;
+			const commitUrl = options.commitUrl ?? url;
+			deps.setRouterNavigating?.(true);
+			if (options.replace) deps.replaceState({
+				timber: true,
+				scrollY: 0
+			}, "", commitUrl);
+			else deps.pushState({
+				timber: true,
+				scrollY: 0
+			}, "", commitUrl);
+			deps.setRouterNavigating?.(false);
+		};
+		const payload = await resolveForFallback(result.payload);
+		const params = await result.params;
+		const isPartial = isPartialNavigation(result.skippedSegments);
+		const hasSkippedSlots = result.segmentInfo?.some((s) => s.slot && s.skipped) ?? false;
+		const { navState, commit } = prepareNavigation(url, {
+			payload: isPartial || hasSkippedSlots ? null : payload,
+			params,
+			segmentInfo: result.segmentInfo,
+			status: result.status
+		});
+		return {
+			...result,
+			payload,
+			params,
+			navState,
+			commit: () => {
+				commitHistoryUrl();
+				commit();
+				window.dispatchEvent(new Event("timber:navigation-end"));
+			}
+		};
+	}
+	return {
+		performNavigationFetch,
+		renderViaTransition,
+		renderPayload,
+		resolveForFallback
+	};
+}
+//#endregion
+//#region src/client/router.ts
+/**
+* Create a router instance. In production, called once at app hydration
+* with real browser APIs. In tests, called with mock dependencies.
+*/
+function createRouter(deps) {
+	const segmentCache = new SegmentCache();
+	const prefetchCache = new PrefetchCache();
+	const historyStack = new HistoryStack();
+	const { prepareNavigation, currentStateTree, updateSegmentCache } = createNavigationCommitter({
+		segmentCache,
+		historyStack,
+		clientSegmentCache: () => deps.clientSegmentCache
+	});
+	const { currentNavAbort, createNavAbort, runNavigation, markHandedOff, forgetOlderHandoffs, isPending, getPendingUrl, onPendingChange } = createNavigationLifecycle(deps);
+	const { performNavigationFetch, renderViaTransition, renderPayload, resolveForFallback } = createNavigationPipeline({
+		deps,
+		prefetchCache,
+		currentStateTree,
+		prepareNavigation,
+		markHandedOff,
+		forgetOlderHandoffs
+	});
+	const { restoreScrollAfterPaint, scrollToHashAfterPaint } = createScrollEffects(deps);
+	const { leaveSpaIfOwned, leaveSpaSuperseding } = createSpaExits({
+		currentNavAbort,
+		supersede: () => void createNavAbort()
+	});
+	const recoverFromNavigationError = createNavigationRecovery({
+		currentNavAbort,
+		leaveSpaIfOwned,
+		navigate: (url) => navigate(url, { replace: true })
+	});
+	async function navigate(url, options = {}) {
+		const scroll = options.scroll !== false;
+		const replace = options.replace === true;
+		const externalSignal = options._signal;
+		const skipHistory = options._skipHistory === true;
+		const hashIndex = url.indexOf("#");
+		const hash = hashIndex === -1 ? "" : url.slice(hashIndex);
+		const fetchUrl = hashIndex === -1 ? url : url.slice(0, hashIndex);
+		const departingUrl = options._departingUrl ?? deps.getCurrentUrl();
+		const currentScrollY = deps.getScrollY();
+		if (deps.saveNavigationEntryScroll) deps.saveNavigationEntryScroll(currentScrollY);
+		else deps.replaceState({
+			timber: true,
+			scrollY: currentScrollY
+		}, "", deps.getCurrentUrl());
+		if (isClientStale()) await leaveSpaSuperseding(url, departingUrl);
+		let effectiveSkipHistory = skipHistory;
+		await runNavigation(url, async (navAbort) => {
+			if (!effectiveSkipHistory && deps.navigationNavigate) {
+				deps.setRouterNavigating?.(true);
+				deps.navigationNavigate(url, replace);
+				deps.setRouterNavigating?.(false);
+				effectiveSkipHistory = true;
+			}
+			try {
+				await renderViaTransition(fetchUrl, navAbort, () => performNavigationFetch(fetchUrl, {
+					replace,
+					commitUrl: url,
+					signal: navAbort.signal,
+					skipHistory: effectiveSkipHistory,
+					departingUrl
+				}));
+				if (scroll && hash) scrollToHashAfterPaint(hash);
+				else restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
+			} catch (error) {
+				if (await recoverFromNavigationError(error, navAbort, url, departingUrl)) return;
+				throw error;
+			}
+		}, externalSignal);
+	}
+	/**
+	* Fetch a URL's RSC payload, commit it, and render — the pipeline shared by
+	* refresh() and an uncached back/forward traversal. Both can be the path
+	* that discovers a version skew, and both recover the same way (TIM-1275).
+	*
+	* Not `performNavigationFetch`: neither caller consults the prefetch cache
+	* (there is no link to have hovered) and neither moves the address bar (the
+	* browser is already where it is going), so the fetch is a plain one.
+	*/
+	async function fetchCommitAndRender(url, opts = {}) {
+		await runNavigation(url, async (navAbort) => {
+			try {
+				await renderViaTransition(url, navAbort, async () => {
+					const result = await fetchRscPayload(url, deps, opts.stateTree, void 0, navAbort.signal);
+					const payload = await resolveForFallback(result.payload);
+					const params = await result.params;
+					const { navState, commit } = prepareNavigation(url, {
+						payload,
+						params,
+						segmentInfo: result.segmentInfo,
+						status: result.status
+					});
+					return {
+						...result,
+						payload,
+						params,
+						navState,
+						commit
+					};
+				});
+			} catch (error) {
+				if (await recoverFromNavigationError(error, navAbort, url, url)) return;
+				throw error;
+			}
+			if (opts.scrollY !== void 0) restoreScrollAfterPaint(opts.scrollY);
+		}, opts.externalSignal);
+	}
+	async function refresh() {
+		const currentUrl = deps.getCurrentUrl();
+		if (isClientStale()) await leaveSpaSuperseding(currentUrl, currentUrl);
+		await fetchCommitAndRender(currentUrl);
+	}
+	async function handlePopState(url, scrollY = 0, externalSignal) {
+		if (isClientStale()) await leaveSpaSuperseding(url, url);
+		const entry = historyStack.get(url);
+		if (entry && entry.payload !== null) await runNavigation(url, async () => {
+			const { navState, commit } = prepareNavigation(url, {
+				payload: entry.payload,
+				params: entry.params,
+				segmentInfo: entry.segmentInfo,
+				clearSegmentCacheOnEmpty: true
+			});
+			commit();
+			renderPayload(entry.payload, navState, entry.params);
+			restoreScrollAfterPaint(scrollY);
+		}, externalSignal);
+		else await fetchCommitAndRender(url, {
+			stateTree: currentStateTree(),
+			scrollY,
+			externalSignal
+		});
+	}
+	/**
+	* Prefetch an RSC payload for a URL and store it in the prefetch cache.
+	* Called on hover of <Link prefetch> elements.
+	*/
+	function prefetch(url) {
+		if (isClientStale()) return;
+		const hashIndex = url.indexOf("#");
+		const fetchUrl = hashIndex === -1 ? url : url.slice(0, hashIndex);
+		const stateTree = currentStateTree();
+		const cacheKey = prefetchKeyFor(fetchUrl, deps.getCurrentUrl(), stateTree);
+		const from = cacheKey.from;
+		if (prefetchCache.get(cacheKey) !== void 0) return;
+		if (historyStack.has(fetchUrl)) return;
+		fetchRscPayload(fetchUrl, deps, stateTree, from).then((result) => {
+			result.decodePromise?.catch((error) => void recordSkew(error));
+			prefetchCache.set(cacheKey, result);
+		}, (error) => {
+			if (error instanceof NonRscResponse) {
+				prefetchCache.setNegative(cacheKey);
+				return;
+			}
+			recordSkew(error);
+		});
+	}
+	return {
+		navigate,
+		refresh,
+		handlePopState,
+		isPending,
+		getPendingUrl,
+		onPendingChange,
+		prefetch,
+		applyRevalidation(payloadRoot) {
+			const currentUrl = deps.getCurrentUrl();
+			const tree = readPayloadTree(payloadRoot);
+			const params = readPublishedParams(payloadRoot);
+			const existingEntry = historyStack.get(currentUrl);
+			const { navState, commit } = prepareNavigation(currentUrl, {
+				payload: tree,
+				params,
+				segmentInfo: existingEntry?.segmentInfo
+			});
+			commit();
+			renderPayload(tree, navState, params);
+		},
+		initSegmentCache: (segments) => updateSegmentCache(segments),
+		segmentCache,
+		prefetchCache,
+		historyStack
+	};
+}
+//#endregion
+//#region src/client/use-search-params.ts
+/**
+* useSearchParams() — client-side hook for reading URL search params.
+*
+* Returns a read-only URLSearchParams instance reflecting the current
+* URL's query string. Updates when client-side navigation changes the URL.
+*
+* On the client, reads from NavigationContext which is updated atomically
+* with the RSC tree render during full navigations, AND by
+* syncShallowSearch() for shallow URL updates (nuqs shallow: true,
+* replaceUrl, or any external pushState/replaceState that changes the
+* query string). See router-init.ts.
+*
+* This replaces the previous useSyncExternalStore approach which read
+* window.location.search directly — causing React to detect external
+* store tearing during transitions and fall back to synchronous rendering
+* (renderRootSync instead of renderRootConcurrent), blocking the main
+* thread and freezing animations.
+*
+* Unlike Next.js's ReadonlyURLSearchParams, this returns a standard
+* URLSearchParams. Mutation methods (set, delete, append) work on the
+* local copy but do NOT affect the URL — use the router or nuqs for that.
+*
+* During SSR, reads the request search params from the SSR ALS context
+* (populated by ssr-entry.ts) instead of window.location.
+*
+* Compatible with Next.js's `useSearchParams()` from `next/navigation`.
+*/
+function getSearchParams(search) {
+	if (search !== cachedSearch) {
+		const params = new URLSearchParams(search);
+		_setCachedSearch(search, params);
+		return params;
+	}
+	return cachedSearchParams;
+}
+/**
+* Read the current URL search params.
+*
+* Compatible with Next.js's `useSearchParams()` from `next/navigation`.
+*/
+function useSearchParams() {
+	try {
+		const navContext = useNavigationContext();
+		if (navContext !== null) return getSearchParams(navContext.search);
+	} catch {}
+	const ssrData = getSsrData();
+	if (ssrData) return new URLSearchParams(ssrData.searchParams);
+	if (typeof window !== "undefined") return getSearchParams(window.location.search);
+	return new URLSearchParams();
+}
+//#endregion
+export { HistoryStack, NavigationProvider, PrefetchCache, SegmentCache, SegmentProvider, TimberErrorBoundary, bindUseQueryStates, clearSsrData, createRouter, getNavigationState, getRouter, getRouterOrNull, getSsrData, setCurrentParams, setCurrentSlotParams, setGlobalRouter, setNavigationState, setSsrData, useSearchParams, useSegmentContext };
+
+//# sourceMappingURL=internal.js.map