@timber-js/app 0.2.0-alpha.66 → 0.2.0-alpha.68

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,21 @@ 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-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 +300,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 +446,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) {
@@ -979,13 +1021,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 +1056,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 +1089,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 +1218,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,14 +1242,29 @@ 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) {
@@ -1198,6 +1275,7 @@ function createRouter(deps) {
 			}
 			if (error instanceof RedirectError) {
 				setPending(false);
+				deps.completeRouterNavigation?.();
 				await navigate(error.redirectUrl, { replace: true });
 				return;
 			}
@@ -1209,14 +1287,16 @@ function createRouter(deps) {
 			throw error;
 		} finally {
 			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 {
@@ -1226,9 +1306,10 @@ function createRouter(deps) {
 			}));
 		} finally {
 			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 +1317,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 {