@timber-js/app 0.2.0-alpha.67 → 0.2.0-alpha.69

package/LICENSE

@@ -0,0 +1,8 @@
+DONTFUCKINGUSE LICENSE
+
+Copyright (c) 2025 Daniel Saewitz
+
+This software may not be used, copied, modified, merged, published,
+distributed, sublicensed, or sold by anyone other than the copyright holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

package/dist/client/history.d.ts

@@ -14,16 +14,31 @@ export interface HistoryEntry {
  * On forward navigation, the new page's payload is pushed onto the stack.
  * On popstate, the cached payload is replayed instantly.
  *
- * Scroll positions are stored in history.state (browser History API),
- * not in this stack — see design/19-client-navigation.md §Scroll Restoration.
+ * Supports two keying modes:
+ * - **URL-keyed** (default): entries keyed by pathname + search.
+ *   Used with the History API fallback.
+ * - **Entry-key + URL**: when the Navigation API is available,
+ *   entries can also be stored by Navigation entry key for
+ *   disambiguation of duplicate URLs in the history stack.
+ *   Falls back to URL lookup when entry key is not found.
+ *
+ * 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.
  */
 export declare class HistoryStack {
     private entries;
-    push(url: string, entry: HistoryEntry): void;
-    get(url: string): HistoryEntry | undefined;
+    /** Entries keyed by Navigation API entry key for duplicate URL disambiguation. */
+    private entryKeyMap;
+    push(url: string, entry: HistoryEntry, entryKey?: string): void;
+    /**
+     * Get an entry. When an entry key is provided (Navigation API),
+     * tries the entry-key map first for accurate disambiguation of
+     * duplicate URLs, then falls back to URL lookup.
+     */
+    get(url: string, entryKey?: string): HistoryEntry | undefined;
     has(url: string): boolean;
 }
 //# sourceMappingURL=history.d.ts.map

package/dist/client/history.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/client/history.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAI1C,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,4FAA4F;IAC5F,YAAY,CAAC,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACpC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;CACnD;AAID;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAmC;IAElD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI;IAI5C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI1C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;CAG1B"}
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/client/history.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAI1C,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,4FAA4F;IAC5F,YAAY,CAAC,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACpC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;CACnD;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAmC;IAClD,kFAAkF;IAClF,OAAO,CAAC,WAAW,CAAmC;IAEtD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAO/D;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAQ7D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;CAG1B"}

package/dist/client/index.js

@@ -107,6 +107,226 @@ function unmountLinkForCurrentNavigation(link) {
 	const store = getStore();
 	if (store.current === link) store.current = null;
 }
+/**
+* Store metadata from Link's onClick for the next navigate event.
+* Called synchronously in the click handler — the navigate event
+* fires synchronously after onClick returns.
+*/
+function setNavLinkMetadata(metadata) {}
+//#endregion
+//#region src/client/navigation-context.ts
+/**
+* NavigationContext — React context for navigation state.
+*
+* Holds the current route params and pathname, updated atomically
+* with the RSC tree on each navigation. This replaces the previous
+* useSyncExternalStore approach for useSegmentParams() and usePathname(),
+* which suffered from a timing gap: the new tree could commit before
+* the external store re-renders fired, causing a frame where both
+* old and new active states were visible simultaneously.
+*
+* By wrapping the RSC payload element in NavigationProvider inside
+* renderRoot(), the context value and the element tree are passed to
+* reactRoot.render() in the same call — atomic by construction.
+* All consumers (useParams, usePathname) see the new values in the
+* same render pass as the new tree.
+*
+* During SSR, no NavigationProvider is mounted. Hooks fall back to
+* the ALS-backed getSsrData() for per-request isolation.
+*
+* IMPORTANT: createContext and useContext are NOT available in the RSC
+* environment (React Server Components use a stripped-down React).
+* The context is lazily initialized on first access, and all functions
+* that depend on these APIs are safe to call from any environment —
+* they return null or no-op when the APIs aren't available.
+*
+* SINGLETON GUARANTEE: All shared mutable state uses globalThis via
+* Symbol.for keys. The RSC client bundler can duplicate this module
+* across chunks (browser-entry graph + client-reference graph). With
+* ESM output, each chunk gets its own module scope — module-level
+* variables would create separate singleton instances per chunk.
+* globalThis guarantees a single instance regardless of duplication.
+*
+* This workaround will be removed when Rolldown ships `format: 'app'`
+* (module registry format that deduplicates like webpack/Turbopack).
+* See design/27-chunking-strategy.md.
+*
+* See design/19-client-navigation.md §"NavigationContext"
+*/
+/**
+* The context is created lazily to avoid calling createContext at module
+* level. In the RSC environment, React.createContext doesn't exist —
+* calling it at import time would crash the server.
+*
+* Context instances are stored on globalThis (NOT in module-level
+* variables) because the ESM bundler can duplicate this module across
+* chunks. Module-level variables would create separate instances per
+* chunk — the provider in NavigationRoot (index chunk) would use
+* context A while the consumer in useNavigationPending (shared chunk)
+* reads from context B. globalThis guarantees a single instance.
+*
+* See design/27-chunking-strategy.md §"Singleton Safety"
+*/
+var NAV_CTX_KEY = Symbol.for("__timber_nav_ctx");
+var PENDING_CTX_KEY = Symbol.for("__timber_pending_nav_ctx");
+function getOrCreateContext() {
+	const existing = globalThis[NAV_CTX_KEY];
+	if (existing !== void 0) return existing;
+	if (typeof React.createContext === "function") {
+		const ctx = React.createContext(null);
+		globalThis[NAV_CTX_KEY] = ctx;
+		return ctx;
+	}
+}
+/**
+* Read the navigation context. Returns null during SSR (no provider)
+* or in the RSC environment (no context available).
+* Internal — used by useSegmentParams() and usePathname().
+*/
+function useNavigationContext() {
+	const ctx = getOrCreateContext();
+	if (!ctx) return null;
+	if (typeof React.useContext !== "function") return null;
+	return React.useContext(ctx);
+}
+/**
+* Wraps children with NavigationContext.Provider.
+*
+* Used in browser-entry.ts renderRoot to wrap the RSC payload element
+* so that navigation state updates atomically with the tree render.
+*/
+function NavigationProvider({ value, children }) {
+	const ctx = getOrCreateContext();
+	if (!ctx) return children;
+	return createElement(ctx.Provider, { value }, children);
+}
+/**
+* Navigation state communicated between the router and renderRoot.
+*
+* The router calls setNavigationState() before renderRoot(). The
+* renderRoot callback reads via getNavigationState() to create the
+* NavigationProvider with the correct params/pathname.
+*
+* This is NOT used by hooks directly — hooks read from React context.
+*
+* Stored on globalThis (like the context instances above) because the
+* router lives in one chunk while renderRoot lives in another. Module-
+* level variables would be separate per chunk.
+*/
+var NAV_STATE_KEY = Symbol.for("__timber_nav_state");
+function _getNavStateStore() {
+	const g = globalThis;
+	if (!g[NAV_STATE_KEY]) g[NAV_STATE_KEY] = { current: {
+		params: {},
+		pathname: "/"
+	} };
+	return g[NAV_STATE_KEY];
+}
+function setNavigationState(state) {
+	_getNavStateStore().current = state;
+}
+function getNavigationState() {
+	return _getNavStateStore().current;
+}
+/**
+* Separate context for the in-flight navigation URL. Provided by
+* NavigationRoot (urgent useState), consumed by useNavigationPending
+* and TopLoader. Per-link pending state uses useOptimistic instead
+* (see link-pending-store.ts).
+*
+* Uses globalThis via Symbol.for for the same reason as NavigationContext
+* above — the bundler may duplicate this module across chunks, and module-
+* level variables would create separate context instances.
+*/
+function getOrCreatePendingContext() {
+	const existing = globalThis[PENDING_CTX_KEY];
+	if (existing !== void 0) return existing;
+	if (typeof React.createContext === "function") {
+		const ctx = React.createContext(null);
+		globalThis[PENDING_CTX_KEY] = ctx;
+		return ctx;
+	}
+}
+/**
+* Read the pending navigation URL from context.
+* Returns null during SSR (no provider) or in the RSC environment.
+*/
+function usePendingNavigationUrl() {
+	const ctx = getOrCreatePendingContext();
+	if (!ctx) return null;
+	if (typeof React.useContext !== "function") return null;
+	return React.useContext(ctx);
+}
+//#endregion
+//#region src/client/top-loader.tsx
+/**
+* TopLoader — Built-in progress bar for client navigations.
+*
+* Shows an animated progress bar at the top of the viewport while an RSC
+* navigation is in flight. Injected automatically by the framework into
+* NavigationRoot — users never render this component directly.
+*
+* Configuration is via timber.config.ts `topLoader` key. Enabled by default.
+* Users who want a fully custom progress indicator disable the built-in one
+* (`topLoader: { enabled: false }`) and use `useNavigationPending()` directly.
+*
+* Animation approach: pure CSS @keyframes. The bar crawls from 0% to ~90%
+* width over ~30s using ease-out timing. When navigation completes, the bar
+* snaps to 100% and fades out over 200ms. No JS animation loops (RAF, setInterval).
+*
+* Phase transitions are derived synchronously during render (React's
+* getDerivedStateFromProps pattern) — no useEffect needed for state tracking.
+* The finishing → hidden cleanup uses onTransitionEnd from the CSS transition.
+*
+* When delay > 0, CSS animation-delay + a visibility keyframe ensure the bar
+* stays invisible during the delay period. If navigation finishes before the
+* delay, the bar was never visible so the finish transition is also invisible.
+*
+* See design/19-client-navigation.md §"useNavigationPending()"
+* See LOCAL-336 for design decisions.
+*/
+//#endregion
+//#region src/client/navigation-root.tsx
+/**
+* Module-level flag indicating a hard (MPA) navigation is in progress.
+*
+* When true:
+* - NavigationRoot throws an unresolved thenable to suspend forever,
+*   preventing React from rendering children during page teardown
+*   (avoids "Rendered more hooks" crashes).
+* - The Navigation API handler skips interception, letting the browser
+*   perform a full page load (prevents infinite loops where
+*   window.location.href → navigate event → router.navigate → 500 →
+*   window.location.href → ...).
+*
+* Uses globalThis for singleton guarantee across chunks (same pattern
+* as NavigationContext). See design/19-client-navigation.md §"Singleton
+* Guarantee via globalThis".
+*/
+var HARD_NAV_KEY = Symbol.for("__timber_hard_navigating");
+function getHardNavStore() {
+	const g = globalThis;
+	if (!g[HARD_NAV_KEY]) g[HARD_NAV_KEY] = { value: false };
+	return g[HARD_NAV_KEY];
+}
+/**
+* Set the hard-navigating flag. Call this BEFORE setting
+* window.location.href or window.location.reload() to prevent:
+* 1. React from rendering children during page teardown
+* 2. Navigation API from intercepting the hard navigation
+*/
+function setHardNavigating(value) {
+	getHardNavStore().value = value;
+}
+//#endregion
+//#region src/client/navigation-api.ts
+/**
+* Returns true if the Navigation API is available in the current environment.
+* Feature-detected at runtime — no polyfill.
+*/
+function hasNavigationApi() {
+	return typeof window !== "undefined" && "navigation" in window && window.navigation != null;
+}
 //#endregion
 //#region src/client/link.tsx
 /**
@@ -285,11 +505,18 @@ function Link({ href, prefetch, scroll, segmentParams, searchParams, preserveSea
 		}
 		const router = getRouterOrNull();
 		if (!router) return;
-		event.preventDefault();
 		const shouldScroll = scroll !== false;
-		const navHref = preserveSearchParams ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams) : resolvedHref;
 		setLinkStatus(PENDING_LINK_STATUS);
 		setLinkForCurrentNavigation(linkInstanceRef.current);
+		if (hasNavigationApi()) {
+			setNavLinkMetadata({
+				scroll: shouldScroll,
+				linkInstance: linkInstanceRef.current
+			});
+			return;
+		}
+		event.preventDefault();
+		const navHref = preserveSearchParams ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams) : resolvedHref;
 		router.navigate(navHref, { scroll: shouldScroll });
 	} : userOnClick;
 	const handleMouseEnter = internal && prefetch ? (event) => {
@@ -424,18 +651,38 @@ var PrefetchCache = class PrefetchCache {
 * On forward navigation, the new page's payload is pushed onto the stack.
 * On popstate, the cached payload is replayed instantly.
 *
-* Scroll positions are stored in history.state (browser History API),
-* not in this stack — see design/19-client-navigation.md §Scroll Restoration.
+* Supports two keying modes:
+* - **URL-keyed** (default): entries keyed by pathname + search.
+*   Used with the History API fallback.
+* - **Entry-key + URL**: when the Navigation API is available,
+*   entries can also be stored by Navigation entry key for
+*   disambiguation of duplicate URLs in the history stack.
+*   Falls back to URL lookup when entry key is not found.
+*
+* 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) {
+	/** Entries keyed by Navigation API entry key for duplicate URL disambiguation. */
+	entryKeyMap = /* @__PURE__ */ new Map();
+	push(url, entry, entryKey) {
 		this.entries.set(url, entry);
+		if (entryKey) this.entryKeyMap.set(entryKey, entry);
 	}
-	get(url) {
+	/**
+	* Get an entry. When an entry key is provided (Navigation API),
+	* tries the entry-key map first for accurate disambiguation of
+	* duplicate URLs, then falls back to URL lookup.
+	*/
+	get(url, entryKey) {
+		if (entryKey) {
+			const byKey = this.entryKeyMap.get(entryKey);
+			if (byKey) return byKey;
+		}
 		return this.entries.get(url);
 	}
 	has(url) {
@@ -443,150 +690,6 @@ var HistoryStack = class {
 	}
 };
 //#endregion
-//#region src/client/navigation-context.ts
-/**
-* NavigationContext — React context for navigation state.
-*
-* Holds the current route params and pathname, updated atomically
-* with the RSC tree on each navigation. This replaces the previous
-* useSyncExternalStore approach for useSegmentParams() and usePathname(),
-* which suffered from a timing gap: the new tree could commit before
-* the external store re-renders fired, causing a frame where both
-* old and new active states were visible simultaneously.
-*
-* By wrapping the RSC payload element in NavigationProvider inside
-* renderRoot(), the context value and the element tree are passed to
-* reactRoot.render() in the same call — atomic by construction.
-* All consumers (useParams, usePathname) see the new values in the
-* same render pass as the new tree.
-*
-* During SSR, no NavigationProvider is mounted. Hooks fall back to
-* the ALS-backed getSsrData() for per-request isolation.
-*
-* IMPORTANT: createContext and useContext are NOT available in the RSC
-* environment (React Server Components use a stripped-down React).
-* The context is lazily initialized on first access, and all functions
-* that depend on these APIs are safe to call from any environment —
-* they return null or no-op when the APIs aren't available.
-*
-* SINGLETON GUARANTEE: All shared mutable state uses globalThis via
-* Symbol.for keys. The RSC client bundler can duplicate this module
-* across chunks (browser-entry graph + client-reference graph). With
-* ESM output, each chunk gets its own module scope — module-level
-* variables would create separate singleton instances per chunk.
-* globalThis guarantees a single instance regardless of duplication.
-*
-* This workaround will be removed when Rolldown ships `format: 'app'`
-* (module registry format that deduplicates like webpack/Turbopack).
-* See design/27-chunking-strategy.md.
-*
-* See design/19-client-navigation.md §"NavigationContext"
-*/
-/**
-* The context is created lazily to avoid calling createContext at module
-* level. In the RSC environment, React.createContext doesn't exist —
-* calling it at import time would crash the server.
-*
-* Context instances are stored on globalThis (NOT in module-level
-* variables) because the ESM bundler can duplicate this module across
-* chunks. Module-level variables would create separate instances per
-* chunk — the provider in TransitionRoot (index chunk) would use
-* context A while the consumer in useNavigationPending (shared chunk)
-* reads from context B. globalThis guarantees a single instance.
-*
-* See design/27-chunking-strategy.md §"Singleton Safety"
-*/
-var NAV_CTX_KEY = Symbol.for("__timber_nav_ctx");
-var PENDING_CTX_KEY = Symbol.for("__timber_pending_nav_ctx");
-function getOrCreateContext() {
-	const existing = globalThis[NAV_CTX_KEY];
-	if (existing !== void 0) return existing;
-	if (typeof React.createContext === "function") {
-		const ctx = React.createContext(null);
-		globalThis[NAV_CTX_KEY] = ctx;
-		return ctx;
-	}
-}
-/**
-* Read the navigation context. Returns null during SSR (no provider)
-* or in the RSC environment (no context available).
-* Internal — used by useSegmentParams() and usePathname().
-*/
-function useNavigationContext() {
-	const ctx = getOrCreateContext();
-	if (!ctx) return null;
-	if (typeof React.useContext !== "function") return null;
-	return React.useContext(ctx);
-}
-/**
-* Wraps children with NavigationContext.Provider.
-*
-* Used in browser-entry.ts renderRoot to wrap the RSC payload element
-* so that navigation state updates atomically with the tree render.
-*/
-function NavigationProvider({ value, children }) {
-	const ctx = getOrCreateContext();
-	if (!ctx) return children;
-	return createElement(ctx.Provider, { value }, children);
-}
-/**
-* Navigation state communicated between the router and renderRoot.
-*
-* The router calls setNavigationState() before renderRoot(). The
-* renderRoot callback reads via getNavigationState() to create the
-* NavigationProvider with the correct params/pathname.
-*
-* This is NOT used by hooks directly — hooks read from React context.
-*
-* Stored on globalThis (like the context instances above) because the
-* router lives in one chunk while renderRoot lives in another. Module-
-* level variables would be separate per chunk.
-*/
-var NAV_STATE_KEY = Symbol.for("__timber_nav_state");
-function _getNavStateStore() {
-	const g = globalThis;
-	if (!g[NAV_STATE_KEY]) g[NAV_STATE_KEY] = { current: {
-		params: {},
-		pathname: "/"
-	} };
-	return g[NAV_STATE_KEY];
-}
-function setNavigationState(state) {
-	_getNavStateStore().current = state;
-}
-function getNavigationState() {
-	return _getNavStateStore().current;
-}
-/**
-* Separate context for the in-flight navigation URL. Provided by
-* TransitionRoot (urgent useState), consumed by useNavigationPending
-* and TopLoader. Per-link pending state uses useOptimistic instead
-* (see link-pending-store.ts).
-*
-* Uses globalThis via Symbol.for for the same reason as NavigationContext
-* above — the bundler may duplicate this module across chunks, and module-
-* level variables would create separate context instances.
-*/
-function getOrCreatePendingContext() {
-	const existing = globalThis[PENDING_CTX_KEY];
-	if (existing !== void 0) return existing;
-	if (typeof React.createContext === "function") {
-		const ctx = React.createContext(null);
-		globalThis[PENDING_CTX_KEY] = ctx;
-		return ctx;
-	}
-}
-/**
-* Read the pending navigation URL from context.
-* Returns null during SSR (no provider) or in the RSC environment.
-*/
-function usePendingNavigationUrl() {
-	const ctx = getOrCreatePendingContext();
-	if (!ctx) return null;
-	if (typeof React.useContext !== "function") return null;
-	return React.useContext(ctx);
-}
-//#endregion
 //#region src/client/use-params.ts
 /**
 * Set the current route params in the module-level store.
@@ -979,13 +1082,14 @@ var ServerErrorResponse = class extends Error {
 * Also extracts head elements from the X-Timber-Head response header
 * so the client can update document.title and <meta> tags after navigation.
 */
-async function fetchRscPayload(url, deps, stateTree, currentUrl) {
+async function fetchRscPayload(url, deps, stateTree, currentUrl, signal) {
 	const rscUrl = appendRscParam(url);
 	const headers = buildRscHeaders(stateTree, currentUrl);
 	if (deps.decodeRsc) {
 		const fetchPromise = deps.fetch(rscUrl, {
 			headers,
-			redirect: "manual"
+			redirect: "manual",
+			signal
 		});
 		let headElements = null;
 		let segmentInfo = null;
@@ -1013,7 +1117,8 @@ async function fetchRscPayload(url, deps, stateTree, currentUrl) {
 	}
 	const response = await deps.fetch(rscUrl, {
 		headers,
-		redirect: "manual"
+		redirect: "manual",
+		signal
 	});
 	if (response.status >= 300 && response.status < 400) {
 		const location = response.headers.get("Location");
@@ -1045,6 +1150,20 @@ function createRouter(deps) {
 	const segmentElementCache = new SegmentElementCache();
 	let routerPhase = { phase: "idle" };
 	const pendingListeners = /* @__PURE__ */ new Set();
+	let currentNavAbort = null;
+	/**
+	* Create a new AbortController for a navigation, aborting any
+	* previous in-flight navigation. Optionally links to an external
+	* signal (e.g., from the Navigation API's NavigateEvent.signal).
+	*/
+	function createNavAbort(externalSignal) {
+		currentNavAbort?.abort();
+		const controller = new AbortController();
+		currentNavAbort = controller;
+		if (externalSignal) if (externalSignal.aborted) controller.abort();
+		else externalSignal.addEventListener("abort", () => controller.abort(), { once: true });
+		return controller;
+	}
 	function setPending(value, url) {
 		const next = value && url ? {
 			phase: "navigating",
@@ -1160,16 +1279,20 @@ function createRouter(deps) {
 		if (result === void 0) {
 			const stateTree = segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths());
 			const rawCurrentUrl = deps.getCurrentUrl();
-			result = await fetchRscPayload(url, deps, stateTree, rawCurrentUrl.startsWith("http") ? new URL(rawCurrentUrl).pathname : new URL(rawCurrentUrl, "http://localhost").pathname);
+			result = await fetchRscPayload(url, deps, stateTree, rawCurrentUrl.startsWith("http") ? new URL(rawCurrentUrl).pathname : new URL(rawCurrentUrl, "http://localhost").pathname, options.signal);
+		}
+		if (!options.skipHistory) {
+			deps.setRouterNavigating?.(true);
+			if (options.replace) deps.replaceState({
+				timber: true,
+				scrollY: 0
+			}, "", url);
+			else deps.pushState({
+				timber: true,
+				scrollY: 0
+			}, "", url);
+			deps.setRouterNavigating?.(false);
 		}
-		if (options.replace) deps.replaceState({
-			timber: true,
-			scrollY: 0
-		}, "", url);
-		else deps.pushState({
-			timber: true,
-			scrollY: 0
-		}, "", url);
 		updateSegmentCache(result.segmentInfo);
 		const navState = updateNavigationState(result.params, url);
 		return {
@@ -1180,43 +1303,64 @@ function createRouter(deps) {
 	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 navAbort = createNavAbort(externalSignal);
 		const currentScrollY = deps.getScrollY();
-		deps.replaceState({
+		if (deps.saveNavigationEntryScroll) deps.saveNavigationEntryScroll(currentScrollY);
+		else deps.replaceState({
 			timber: true,
 			scrollY: currentScrollY
 		}, "", deps.getCurrentUrl());
+		let effectiveSkipHistory = skipHistory;
+		if (!skipHistory && deps.navigationNavigate) {
+			deps.setRouterNavigating?.(true);
+			deps.navigationNavigate(url, replace);
+			deps.setRouterNavigating?.(false);
+			effectiveSkipHistory = true;
+		}
 		setPending(true, url);
 		try {
-			applyHead(await renderViaTransition(url, () => performNavigationFetch(url, { replace })));
+			applyHead(await renderViaTransition(url, () => performNavigationFetch(url, {
+				replace,
+				signal: navAbort.signal,
+				skipHistory: effectiveSkipHistory
+			})));
 			window.dispatchEvent(new Event("timber:navigation-end"));
 			restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
 		} catch (error) {
 			if (error instanceof VersionSkewError) {
+				setHardNavigating(true);
 				const { triggerStaleReload } = await import("../_chunks/stale-reload-BeyHXZ5B.js");
 				triggerStaleReload();
 				return new Promise(() => {});
 			}
 			if (error instanceof RedirectError) {
 				setPending(false);
+				deps.completeRouterNavigation?.();
 				await navigate(error.redirectUrl, { replace: true });
 				return;
 			}
 			if (error instanceof ServerErrorResponse) {
+				setHardNavigating(true);
 				window.location.href = error.url;
 				return new Promise(() => {});
 			}
 			if (isAbortError(error)) return;
 			throw error;
 		} finally {
+			if (currentNavAbort === navAbort) currentNavAbort = null;
 			setPending(false);
+			deps.completeRouterNavigation?.();
 		}
 	}
 	async function refresh() {
 		const currentUrl = deps.getCurrentUrl();
+		const navAbort = createNavAbort();
 		setPending(true, currentUrl);
 		try {
 			applyHead(await renderViaTransition(currentUrl, async () => {
-				const result = await fetchRscPayload(currentUrl, deps);
+				const result = await fetchRscPayload(currentUrl, deps, void 0, void 0, navAbort.signal);
 				updateSegmentCache(result.segmentInfo);
 				const navState = updateNavigationState(result.params, currentUrl);
 				return {
@@ -1224,11 +1368,16 @@ function createRouter(deps) {
 					navState
 				};
 			}));
+		} catch (error) {
+			if (isAbortError(error)) return;
+			throw error;
 		} finally {
+			if (currentNavAbort === navAbort) currentNavAbort = null;
 			setPending(false);
+			deps.completeRouterNavigation?.();
 		}
 	}
-	async function handlePopState(url, scrollY = 0) {
+	async function handlePopState(url, scrollY = 0, externalSignal) {
 		const entry = historyStack.get(url);
 		if (entry && entry.payload !== null) {
 			const navState = updateNavigationState(entry.params, url);
@@ -1236,10 +1385,11 @@ function createRouter(deps) {
 			applyHead(entry.headElements);
 			restoreScrollAfterPaint(scrollY);
 		} else {
+			const navAbort = createNavAbort(externalSignal);
 			setPending(true, url);
 			try {
 				applyHead(await renderViaTransition(url, async () => {
-					const result = await fetchRscPayload(url, deps, segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths()));
+					const result = await fetchRscPayload(url, deps, segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths()), void 0, navAbort.signal);
 					updateSegmentCache(result.segmentInfo);
 					const navState = updateNavigationState(result.params, url);
 					return {
@@ -1248,7 +1398,11 @@ function createRouter(deps) {
 					};
 				}));
 				restoreScrollAfterPaint(scrollY);
+			} catch (error) {
+				if (isAbortError(error)) return;
+				throw error;
 			} finally {
+				if (currentNavAbort === navAbort) currentNavAbort = null;
 				setPending(false);
 			}
 		}