@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.186

package/dist/client/internal.js

@@ -1,10 +1,79 @@
-import { t as bindUseQueryStates } from "../_chunks/use-query-states-DFvWd-EA.js";
-import { c as cachedSearchParams, i as _setCachedSearch, n as getSsrData, r as setSsrData, s as cachedSearch, t as clearSsrData } from "../_chunks/ssr-data-BOWsq18U.js";
-import { a as setNavigationState, i as getNavigationState, o as useNavigationContext, r as NavigationProvider, t as setCurrentParams } from "../_chunks/use-segment-params-D1CzlgBo.js";
-import { n as getRouterOrNull, r as setGlobalRouter, t as getRouter } from "../_chunks/router-ref-CtmF-aPv.js";
-import { TimberErrorBoundary } from "./error-boundary.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-DpYRI_I1.js";
 import { n as useSegmentContext, t as SegmentProvider } from "../_chunks/segment-context-ZDnXDkbz.js";
-import { n as supersedeNavigationTransitions, t as setHardNavigating } from "../_chunks/navigation-root-bUDZLw74.js";
+import "../_chunks/rsc-error-envelope-tT5PJs4q.js";
+import { a as setNavigationState, i as getNavigationState, n as supersedeNavigationTransitions, o as useNavigationContext, r as NavigationProvider, t as setHardNavigating } from "../_chunks/navigation-root-B29qg0_T.js";
+import { n as setCurrentSlotParams, t as setCurrentParams } from "../_chunks/use-segment-params-ClyUNq4d.js";
+import { t as bindUseQueryStates } from "../_chunks/use-query-states-DFvWd-EA.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
@@ -32,18 +101,28 @@ var SegmentCache = class {
 	* 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;
 	}
 };
@@ -52,6 +131,17 @@ 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 cacheable slot paths from the tree */
 function collectSyncSlots(node, out) {
 	if (node.slots) {
@@ -83,6 +173,7 @@ function buildSegmentTree(segments) {
 		const id = info.segmentId ?? info.path;
 		const node = {
 			segment: id,
+			treePath: info.treePath,
 			payload: null,
 			isRequestDependent: info.isRequestDependent,
 			children: /* @__PURE__ */ new Map()
@@ -112,6 +203,22 @@ function buildSegmentTree(segments) {
 /** 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.
@@ -122,34 +229,42 @@ var NEGATIVE_ENTRY = Object.freeze({ payload: null });
 var PrefetchCache = class PrefetchCache {
 	static TTL_MS = 3e4;
 	entries = /* @__PURE__ */ new Map();
-	set(url, result) {
-		this.entries.set(url, {
+	set(key, result) {
+		this.entries.set(prefetchMapKey(key), {
 			result,
 			expiresAt: Date.now() + PrefetchCache.TTL_MS
 		});
 	}
-	get(url) {
-		const entry = this.entries.get(url);
+	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(url);
+			this.entries.delete(mapKey);
 			return;
 		}
 		return entry.result;
 	}
 	/** Get and remove the entry (used when navigation consumes a prefetch) */
-	consume(url) {
-		const result = this.get(url);
-		if (result !== void 0) this.entries.delete(url);
+	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). */
-	setNegative(url) {
-		this.set(url, NEGATIVE_ENTRY);
+	/**
+	* 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(url) {
-		return this.get(url) === NEGATIVE_ENTRY;
+	isNegative(key) {
+		return this.get(key) === NEGATIVE_ENTRY;
 	}
 };
 //#endregion
@@ -183,30 +298,164 @@ var HistoryStack = class {
 	}
 };
 //#endregion
-//#region src/client/rsc-fetch.ts
-var RSC_CONTENT_TYPE = "text/x-component";
+//#region src/client/navigation-commit.ts
 /**
-* Generate a short random cache-busting ID (5 chars, a-z0-9).
-* Matches the format Next.js uses for _rsc params.
+* 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 generateCacheBustId() {
-	const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
-	let id = "";
-	for (let i = 0; i < 5; i++) id += chars[Math.random() * 36 | 0];
-	return id;
+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);
+			return {
+				navState,
+				commit() {
+					if (opts.segmentInfo && opts.segmentInfo.length > 0) updateSegmentCache(opts.segmentInfo);
+					else if (opts.segmentInfo?.length === 0 || opts.clearSegmentCacheOnEmpty) segmentCache.clear();
+					setNavigationState(navState);
+					historyStack.push(url, {
+						payload: opts.payload,
+						params: opts.params,
+						segmentInfo: opts.segmentInfo
+					});
+				}
+			};
+		}
+	};
 }
+//#endregion
+//#region src/client/rsc-fetch.ts
 /**
-* Append a `_rsc=<id>` query parameter to the URL.
-* Follows Next.js's pattern — prevents CDN/browser from serving cached HTML
-* for RSC navigation requests and signals that this is an RSC fetch.
+* 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"
+*/
+var RSC_CONTENT_TYPE = "text/x-component";
+/**
+* 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.
 */
-function appendRscParam(url) {
+async function appendRscParam(url, headers) {
 	const hashIndex = url.indexOf("#");
 	const urlWithoutHash = hashIndex === -1 ? url : url.slice(0, hashIndex);
-	return `${urlWithoutHash}${urlWithoutHash.includes("?") ? "&" : "?"}_rsc=${generateCacheBustId()}`;
+	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.
@@ -215,6 +464,17 @@ function appendRscParam(url) {
 */
 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
@@ -222,9 +482,10 @@ var clientDeploymentId = null;
 */
 var staticMode = false;
 /**
-* RSC manifest mapping unhashed → hashed URLs + params. Populated from
-* `window.__TIMBER_RSC_MANIFEST__` (injected into HTML during
-* static generation). See TIM-1254, TIM-1255.
+* 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() {
@@ -233,22 +494,35 @@ function getRscManifest() {
 	return rscManifest;
 }
 /**
-* Convert a route URL to the corresponding _rsc/*.rsc file path.
-* Mirrors the naming in plugins/static-build.ts staticOutputPath.
+* 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.rsc (or /_rsc/about-C8ZzFLfO.rsc with manifest)
-*   /blog/hello → /_rsc/blog/hello.rsc
+*   /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);
-	return manifestLookup(unhashed) ?? unhashed;
+	const hashedUrl = manifestLookup(unhashed);
+	return {
+		url: withBasePath(basePath, hashedUrl ?? unhashed),
+		hashed: hashedUrl !== null
+	};
 }
 /**
-* Compute the unhashed _rsc/*.rsc URL for a route path.
+* 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) {
@@ -257,9 +531,9 @@ function toUnhashedRscUrl(url) {
 	const hashEnd = hashIndex === -1 ? url.length : hashIndex;
 	const queryEnd = queryIndex === -1 ? url.length : queryIndex;
 	const end = Math.min(hashEnd, queryEnd);
-	let pathname = url.slice(0, end);
+	let pathname = stripBasePath(basePath, url.slice(0, end));
 	if (pathname.length > 1 && pathname.endsWith("/")) pathname = pathname.slice(0, -1);
-	return `/_rsc${pathname === "/" ? "/index" : pathname}.rsc`;
+	return rscPayloadPath(pathname);
 }
 /**
 * Look up a key in the RSC manifest, falling back to percent-decoded
@@ -281,12 +555,6 @@ function manifestEntry(key) {
 function manifestLookup(key) {
 	return manifestEntry(key)?.url ?? null;
 }
-/**
-* Look up inlined route params for a route from the manifest. TIM-1255.
-*/
-function manifestParams(url) {
-	return manifestEntry(toUnhashedRscUrl(url))?.params ?? 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. */
@@ -298,6 +566,17 @@ var DEPLOYMENT_ID_HEADER = "X-Timber-Deployment-Id";
 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);
@@ -350,22 +629,6 @@ function extractSkippedSegments(response) {
 	}
 }
 /**
-* Extract route params from the X-Timber-Params response header.
-* Returns null if the header is missing or malformed.
-*
-* Used to populate useSegmentParams() after client-side navigation.
-*/
-function extractParams(response) {
-	const header = response.headers.get("X-Timber-Params");
-	if (!header) return null;
-	try {
-		return JSON.parse(header);
-	} catch {
-		warnMalformedHeader("X-Timber-Params", 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.
 */
@@ -427,9 +690,10 @@ var NonRscResponse = class extends Error {
 * a `done` promise that resolves when the last chunk is read (or
 * rejects if the stream errors).
 *
-* Used to keep React transitions open for the full RSC stream
-* duration — createFromFetch's thenable resolves on shell arrival,
-* but we need stream completion for useOptimistic pending state.
+* 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;
@@ -467,9 +731,11 @@ function trackStreamCompletion(body) {
 * Otherwise, the raw response text is returned (test mode).
 */
 async function fetchRscPayload(url, deps, stateTree, currentUrl, signal) {
-	const fetchTarget = staticMode ? toStaticRscUrl(url) : url;
-	const rscUrl = staticMode && fetchTarget !== toUnhashedRscUrl(url) ? fetchTarget : appendRscParam(fetchTarget);
-	const headers = buildRscHeaders(staticMode ? void 0 : stateTree, currentUrl);
+	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,
@@ -477,7 +743,6 @@ async function fetchRscPayload(url, deps, stateTree, currentUrl, signal) {
 			signal
 		});
 		let segmentInfo = null;
-		let params = null;
 		let skippedSegments = null;
 		let streamDone = Promise.resolve();
 		const wrappedPromise = fetchPromise.then((response) => {
@@ -499,7 +764,6 @@ async function fetchRscPayload(url, deps, stateTree, currentUrl, signal) {
 				}
 			}
 			segmentInfo = extractSegmentInfo(response);
-			params = extractParams(response);
 			skippedSegments = extractSkippedSegments(response);
 			if (response.body) {
 				const tracked = trackStreamCompletion(response.body);
@@ -513,17 +777,19 @@ async function fetchRscPayload(url, deps, stateTree, currentUrl, signal) {
 			return response;
 		});
 		await wrappedPromise;
-		if (staticMode && !params) params = manifestParams(url);
-		const payload = deps.decodeRsc(wrappedPromise);
+		const root = deps.decodeRsc(wrappedPromise);
+		const { tree: payload, params } = splitPayloadRoot(root);
 		const payloadError = new Promise((_, reject) => {
-			Promise.resolve(payload).then(() => {}, reject);
+			Promise.resolve(root).then(() => {}, reject);
 		});
 		payloadError.catch(() => {});
+		const decodePromise = Promise.race([streamDone, payloadError]);
+		decodePromise.catch(() => {});
 		return {
 			payload,
-			decodePromise: Promise.race([streamDone, payloadError]),
-			segmentInfo,
 			params,
+			decodePromise,
+			segmentInfo,
 			skippedSegments
 		};
 	}
@@ -550,18 +816,191 @@ async function fetchRscPayload(url, deps, stateTree, currentUrl, signal) {
 			throw new NonRscResponse(url);
 		}
 	}
-	let fallbackParams = extractParams(response);
-	if (staticMode && !fallbackParams) fallbackParams = manifestParams(url);
 	return {
 		payload: await response.text(),
+		params: readPublishedParams(void 0),
 		decodePromise: null,
 		segmentInfo: extractSegmentInfo(response),
-		params: fallbackParams,
 		skippedSegments: extractSkippedSegments(response)
 	};
 }
 //#endregion
-//#region src/client/router.ts
+//#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.
@@ -571,22 +1010,82 @@ function isAbortError(error) {
 	if (error instanceof Error && error.name === "AbortError") return true;
 	return false;
 }
-function createRouter(deps) {
-	const segmentCache = new SegmentCache();
-	const prefetchCache = new PrefetchCache();
-	const historyStack = new HistoryStack();
+function createNavigationLifecycle(deps) {
+	let currentNavAbort = null;
 	let routerPhase = { phase: "idle" };
 	const pendingListeners = /* @__PURE__ */ new Set();
-	let currentNavAbort = null;
+	/**
+	* 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.
+	* 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
@@ -594,14 +1093,14 @@ function createRouter(deps) {
 	*/
 	function createNavAbort(externalSignal) {
 		if (currentNavAbort) {
-			currentNavAbort.abort();
+			abortUnlessHandedOff(currentNavAbort);
 			supersedeNavigationTransitions();
 			deps.completeRouterNavigation?.();
 		}
 		const controller = new AbortController();
 		currentNavAbort = controller;
-		if (externalSignal) if (externalSignal.aborted) controller.abort();
-		else externalSignal.addEventListener("abort", () => controller.abort(), { once: true });
+		if (externalSignal) if (externalSignal.aborted) abortUnlessHandedOff(controller);
+		else externalSignal.addEventListener("abort", () => abortUnlessHandedOff(controller), { once: true });
 		return controller;
 	}
 	function setPending(value, url) {
@@ -613,38 +1112,6 @@ function createRouter(deps) {
 		routerPhase = next;
 		for (const listener of pendingListeners) listener(value);
 	}
-	/** Update the segment cache from server-provided segment metadata. */
-	function updateSegmentCache(segmentInfo) {
-		if (!deps.clientSegmentCache) return;
-		if (!segmentInfo || segmentInfo.length === 0) return;
-		const tree = buildSegmentTree(segmentInfo);
-		if (tree) segmentCache.set("/", tree);
-	}
-	/** Render a decoded RSC payload into the DOM if a renderer is available. */
-	function renderPayload(payload, navState) {
-		if (deps.renderRoot) deps.renderRoot(payload, navState);
-	}
-	/**
-	* Atomically update all navigation-owned state for a new page. Every
-	* code path that changes the "current page" must go through this
-	* function — making "forgot a field" impossible by construction.
-	*
-	* The three operations:
-	* 1. Segment cache — update from server-provided segment metadata
-	* 2. Navigation state — params + pathname for useSegmentParams/usePathname
-	* 3. History stack — store the payload for instant back/forward replay
-	*/
-	function commitNavigation(url, opts) {
-		if (opts.segmentInfo && opts.segmentInfo.length > 0) updateSegmentCache(opts.segmentInfo);
-		else if (opts.clearSegmentCacheOnEmpty) segmentCache.clear();
-		const navState = updateNavigationState(opts.params, url);
-		historyStack.push(url, {
-			payload: opts.payload,
-			params: navState.params,
-			segmentInfo: opts.segmentInfo
-		});
-		return navState;
-	}
 	/**
 	* Wrap a navigation in the standard abort/pending/cleanup lifecycle.
 	* Consolidates the createNavAbort + setPending + staleness-guarded
@@ -668,6 +1135,117 @@ function createRouter(deps) {
 			}
 		}
 	}
+	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
@@ -677,141 +1255,75 @@ function createRouter(deps) {
 		if (!deps.navigateTransition && payload != null && typeof payload === "object" && "then" in payload) return await payload;
 		return payload;
 	}
-	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;
-	}
-	/**
-	* Update navigation state (params + pathname) for the next render.
-	*
-	* Sets the module-level fallback (for tests and SSR) and the
-	* globalThis bridge, then returns the NavigationState so callers
-	* can pass it explicitly to renderRoot/wrapPayload — eliminating
-	* temporal coupling with getNavigationState().
-	*/
-	function updateNavigationState(params, url) {
-		const resolvedParams = params ?? {};
-		setCurrentParams(resolvedParams);
-		const parsed = new URL(url, "http://localhost");
-		const navState = {
-			params: resolvedParams,
-			pathname: parsed.pathname || "/",
-			search: parsed.search
-		};
-		setNavigationState(navState);
-		return navState;
-	}
 	/**
 	* Render a payload via navigateTransition (production) or renderRoot (tests).
-	* The perform callback should fetch data, call commitNavigation, and return
-	* the FetchResult plus the NavigationState.
+	* The perform callback should fetch data, prepare the commit, and return the
+	* FetchResult plus the NavigationState and the commit thunk.
 	*
-	* State management (segmentCache, navState, historyStack) is handled by
-	* commitNavigation inside perform — this function only handles rendering.
+	* 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, perform) {
+	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: wrapPayload(deps._getCurrentPayload?.() ?? result.payload, result.navState, segmentUpdates),
-						decodePromise: result.decodePromise
+						element,
+						decodePromise: observeSkew(result.decodePromise),
+						commit: commitAndForget(result.commit)
 					};
 				}
+				const element = wrapPayload(result.payload, result.navState, params);
+				handOff();
 				return {
-					element: wrapPayload(result.payload, result.navState),
-					decodePromise: result.decodePromise
+					element,
+					decodePromise: observeSkew(result.decodePromise),
+					commit: commitAndForget(result.commit)
 				};
 			});
 			return;
 		}
 		const result = await perform();
-		if (!isPartialNavigation(result.skippedSegments)) renderPayload(result.payload, result.navState);
-	}
-	/**
-	* Perform a hard navigation to a URL. When the target is same-document
-	* (same pathname+search, different hash), `location.href = url` is a
-	* hash change — no reload. Use `location.reload()` instead (TIM-1235).
-	*
-	* `fromUrl` is the departing URL captured before any pushState or
-	* Navigation API commit — deps.getCurrentUrl() is unreliable here
-	* because the URL may have already been updated.
-	*/
-	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;
-	}
-	/** Run a callback after the next paint (after React commit). */
-	function afterPaint(callback) {
-		if (deps.afterPaint) deps.afterPaint(callback);
-		else callback();
-	}
-	/**
-	* Schedule scroll restoration after the next paint and fire the
-	* scroll-restored event. Used by navigate, popstate, and refresh.
-	*/
-	function restoreScrollAfterPaint(scrollY) {
-		afterPaint(() => {
-			deps.scrollTo(0, scrollY);
-			window.dispatchEvent(new Event("timber:scroll-restored"));
-		});
-	}
-	/**
-	* Scroll to the element matching the URL #fragment after paint, falling
-	* back to scroll-to-top when no element matches (matching full-page-load
-	* behavior for an unknown fragment). Used by forward navigation to a
-	* hash-bearing URL (TIM-1035).
-	*/
-	function scrollToHashAfterPaint(hash) {
-		afterPaint(() => {
-			if (deps.scrollToHash?.(hash) !== true) deps.scrollTo(0, 0);
-			window.dispatchEvent(new Event("timber:scroll-restored"));
-		});
+		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) {
-		if (prefetchCache.isNegative(url)) {
-			prefetchCache.consume(url);
+		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(url);
+		const prefetched = prefetchCache.consume(cacheKey);
 		let result = prefetched ? {
 			payload: prefetched.payload,
-			decodePromise: null,
+			params: prefetched.params ?? readPublishedParams(void 0),
+			decodePromise: prefetched.decodePromise ?? null,
 			segmentInfo: prefetched.segmentInfo ?? null,
-			params: prefetched.params ?? null,
 			skippedSegments: prefetched.skippedSegments ?? null
 		} : void 0;
-		if (result === void 0) {
-			const stateTree = deps.clientSegmentCache ? segmentCache.serializeStateTree() : void 0;
-			const rawDepartingUrl = options.departingUrl ?? deps.getCurrentUrl();
-			result = await fetchRscPayload(url, deps, stateTree, rawDepartingUrl.startsWith("http") ? new URL(rawDepartingUrl).pathname : new URL(rawDepartingUrl, "http://localhost").pathname, options.signal);
-		}
-		if (!options.skipHistory) {
+		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({
@@ -823,21 +1335,69 @@ function createRouter(deps) {
 				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 = commitNavigation(url, {
+		const { navState, commit } = prepareNavigation(url, {
 			payload: isPartial || hasSkippedSlots ? null : payload,
-			params: result.params,
+			params,
 			segmentInfo: result.segmentInfo
 		});
 		return {
 			...result,
 			payload,
-			navState
+			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;
@@ -853,6 +1413,7 @@ function createRouter(deps) {
 			timber: true,
 			scrollY: currentScrollY
 		}, "", deps.getCurrentUrl());
+		if (isClientStale()) await leaveSpaSuperseding(url, departingUrl);
 		let effectiveSkipHistory = skipHistory;
 		await runNavigation(url, async (navAbort) => {
 			if (!effectiveSkipHistory && deps.navigationNavigate) {
@@ -862,128 +1423,126 @@ function createRouter(deps) {
 				effectiveSkipHistory = true;
 			}
 			try {
-				await renderViaTransition(fetchUrl, () => performNavigationFetch(fetchUrl, {
+				await renderViaTransition(fetchUrl, navAbort, () => performNavigationFetch(fetchUrl, {
 					replace,
 					commitUrl: url,
 					signal: navAbort.signal,
 					skipHistory: effectiveSkipHistory,
 					departingUrl
 				}));
-				window.dispatchEvent(new Event("timber:navigation-end"));
 				if (scroll && hash) scrollToHashAfterPaint(hash);
 				else restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
 			} catch (error) {
-				if (error instanceof VersionSkewError) {
-					setHardNavigating(true);
-					window.location.reload();
-					await new Promise(() => {});
-				}
-				if (error instanceof RedirectError) {
-					if (currentNavAbort !== navAbort) return;
-					await navigate(error.redirectUrl, { replace: true });
-					return;
-				}
-				if (error instanceof ServerErrorResponse) {
-					setHardNavigating(true);
-					hardNavigate(url, departingUrl);
-					await new Promise(() => {});
-				}
-				if (error instanceof NonRscResponse) {
-					setHardNavigating(true);
-					hardNavigate(url, departingUrl);
-					await new Promise(() => {});
-				}
+				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
+					});
+					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();
-		await runNavigation(currentUrl, async (navAbort) => {
-			await renderViaTransition(currentUrl, async () => {
-				const result = await fetchRscPayload(currentUrl, deps, void 0, void 0, navAbort.signal);
-				const payload = await resolveForFallback(result.payload);
-				const navState = commitNavigation(currentUrl, {
-					payload,
-					params: result.params,
-					segmentInfo: result.segmentInfo
-				});
-				return {
-					...result,
-					payload,
-					navState
-				};
-			});
-		});
+		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 = commitNavigation(url, {
+			const { navState, commit } = prepareNavigation(url, {
 				payload: entry.payload,
 				params: entry.params,
 				segmentInfo: entry.segmentInfo,
 				clearSegmentCacheOnEmpty: true
 			});
-			renderPayload(entry.payload, navState);
-			restoreScrollAfterPaint(scrollY);
-		}, externalSignal);
-		else await runNavigation(url, async (navAbort) => {
-			await renderViaTransition(url, async () => {
-				const result = await fetchRscPayload(url, deps, deps.clientSegmentCache ? segmentCache.serializeStateTree() : void 0, void 0, navAbort.signal);
-				const payload = await resolveForFallback(result.payload);
-				const navState = commitNavigation(url, {
-					payload,
-					params: result.params,
-					segmentInfo: result.segmentInfo
-				});
-				return {
-					...result,
-					payload,
-					navState
-				};
-			});
+			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);
-		if (prefetchCache.get(fetchUrl) !== void 0) return;
+		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, deps.clientSegmentCache ? segmentCache.serializeStateTree() : void 0).then((result) => {
-			result.decodePromise?.catch(() => {});
-			prefetchCache.set(fetchUrl, result);
+		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(fetchUrl);
+				prefetchCache.setNegative(cacheKey);
 				return;
 			}
+			recordSkew(error);
 		});
 	}
 	return {
 		navigate,
 		refresh,
 		handlePopState,
-		isPending: () => routerPhase.phase === "navigating",
-		getPendingUrl: () => routerPhase.phase === "navigating" ? routerPhase.targetUrl : null,
-		onPendingChange(listener) {
-			pendingListeners.add(listener);
-			return () => pendingListeners.delete(listener);
-		},
+		isPending,
+		getPendingUrl,
+		onPendingChange,
 		prefetch,
-		applyRevalidation(element) {
+		applyRevalidation(payloadRoot) {
 			const currentUrl = deps.getCurrentUrl();
+			const tree = readPayloadTree(payloadRoot);
+			const params = readPublishedParams(payloadRoot);
 			const existingEntry = historyStack.get(currentUrl);
-			renderPayload(element, commitNavigation(currentUrl, {
-				payload: element,
-				params: getNavigationState().params,
+			const { navState, commit } = prepareNavigation(currentUrl, {
+				payload: tree,
+				params,
 				segmentInfo: existingEntry?.segmentInfo
-			}));
+			});
+			commit();
+			renderPayload(tree, navState, params);
 		},
 		initSegmentCache: (segments) => updateSegmentCache(segments),
 		segmentCache,
@@ -1044,6 +1603,6 @@ function useSearchParams() {
 	return new URLSearchParams();
 }
 //#endregion
-export { HistoryStack, NavigationProvider, PrefetchCache, SegmentCache, SegmentProvider, TimberErrorBoundary, bindUseQueryStates, clearSsrData, createRouter, getNavigationState, getRouter, getRouterOrNull, getSsrData, setCurrentParams, setGlobalRouter, setNavigationState, setSsrData, useSearchParams, useSegmentContext };
+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