@timber-js/app 0.2.0-alpha.196 → 0.2.0-alpha.198

package/dist/client/internal.js

@@ -1,13 +1,14 @@
 import { n as isRscContentType, t as RSC_CONTENT_TYPE } from "../_chunks/rsc-media-type-DDc7duTD.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 { a as randomRscCacheKey, n as RSC_KEY_PARAM, o as recordLookup, s as rscCacheKey } from "../_chunks/rsc-cache-key-ClUiXQnK.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-Ya2HJPFp.js";
-import { n as getRouterOrNull, r as setGlobalRouter, t as getRouter } from "../_chunks/router-ref-BzqbPwYC.js";
-import { i as markStaleFromError, n as isClientStale, r as markClientStale, t as TimberErrorBoundary } from "../_chunks/error-boundary-D-lkwyaD.js";
-import { n as useSegmentContext, t as SegmentProvider } from "../_chunks/segment-context-CjOlyB8Y.js";
+import { n as createSingleflight, t as SingleflightTimeoutError } from "../_chunks/singleflight-2lUWfcAk.js";
+import { c as cachedSearchParams, i as _setCachedSearch, n as getSsrData, r as setSsrData, s as cachedSearch, t as clearSsrData } from "../_chunks/ssr-data-BQGhTPAK.js";
+import { n as getRouterOrNull, r as setGlobalRouter, t as getRouter } from "../_chunks/router-ref-8gr8qsxN.js";
+import { i as markStaleFromError, n as isClientStale, r as markClientStale, t as TimberErrorBoundary } from "../_chunks/error-boundary-BvRCCmbN.js";
+import { n as useSegmentContext, t as SegmentProvider } from "../_chunks/segment-context-D9_89u34.js";
 import "../_chunks/rsc-error-envelope-tT5PJs4q.js";
-import { a as supersedeNavigationTransitions, c as setNavigationState, i as setHardNavigating, l as useNavigationContext, n as setCurrentSlotParams, o as NavigationProvider, s as getNavigationState, t as setCurrentParams } from "../_chunks/use-segment-params-DzTBpkvj.js";
+import { a as useNavigationContext, i as setNavigationState, n as NavigationProvider, r as getNavigationState, t as setHardNavigating } from "../_chunks/navigation-root-B00jjGd5.js";
 import { t as bindUseQueryStates } from "../_chunks/use-query-states-I3JMng6J.js";
 //#region src/shared/payload-root.ts
 /**
@@ -212,6 +213,12 @@ function buildSegmentTree(segments) {
 /** Sentinel value for negative cache entries (URL is not a route). */
 var NEGATIVE_ENTRY = Object.freeze({ payload: null });
 /**
+* Timeout for the in-flight singleflight (TIM-1438). Per CLAUDE.md's
+* singleflight rule: "Never write a coalescing Map without a timeout."
+* A hung prefetch cannot block clicks or suppress hovers forever.
+*/
+var PREFETCH_SINGLEFLIGHT_TIMEOUT_MS = 5e3;
+/**
 * 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.
@@ -232,12 +239,19 @@ function prefetchScopeOf(stateTree) {
 * 30 seconds. When a link is clicked, the prefetched payload is consumed
 * (moved to the history stack) and removed from this cache.
 *
+* In-flight dedup (TIM-1438): concurrent fetches for the same key are
+* coalesced by a `createSingleflight` instance. A hover starts a flight;
+* a click for the same key joins it instead of issuing a duplicate. The
+* singleflight enforces a 5-second timeout and cleans up automatically
+* on settlement.
+*
 * timber.js does NOT prefetch on viewport intersection — only explicit
 * hover on <Link prefetch> triggers a prefetch.
 */
 var PrefetchCache = class PrefetchCache {
 	static TTL_MS = 3e4;
 	entries = /* @__PURE__ */ new Map();
+	flights = createSingleflight({ timeoutMs: PREFETCH_SINGLEFLIGHT_TIMEOUT_MS });
 	set(key, result) {
 		this.entries.set(prefetchMapKey(key), {
 			result,
@@ -254,6 +268,10 @@ var PrefetchCache = class PrefetchCache {
 		}
 		return entry.result;
 	}
+	/** True if a ready or negative entry exists for this key. */
+	has(key) {
+		return this.get(key) !== void 0;
+	}
 	/** Get and remove the entry (used when navigation consumes a prefetch) */
 	consume(key) {
 		const result = this.get(key);
@@ -261,6 +279,47 @@ var PrefetchCache = class PrefetchCache {
 		return result;
 	}
 	/**
+	* Fetch or coalesce with an in-flight fetch for this key (TIM-1438).
+	*
+	* Concurrent callers (hover + click, repeated hovers) get the same
+	* promise. On success the result is stored as a ready entry. On
+	* NonRscResponse a negative entry is stored and the outcome is
+	* `{ kind: 'non-route' }`. Other errors (network, version skew)
+	* reject — the singleflight cleans up the key and subsequent callers
+	* retry.
+	*
+	* The singleflight signal is passed to `doFetch` so a timed-out flight
+	* aborts the underlying fetch rather than leaving it running.
+	*/
+	fetchOrCoalesce(key, doFetch, isNonRoute) {
+		return this.flights.do(prefetchMapKey(key), async (signal) => {
+			try {
+				const result = await doFetch(signal);
+				if (!signal.aborted) this.set(key, result);
+				return {
+					kind: "ready",
+					result
+				};
+			} catch (err) {
+				if (isNonRoute(err)) {
+					if (!signal.aborted) this.setNegative(key);
+					return { kind: "non-route" };
+				}
+				throw err;
+			}
+		});
+	}
+	/**
+	* Join an in-flight singleflight fetch if one exists for this key.
+	* Returns the in-flight promise or undefined. Used by the click path to
+	* coalesce with a hover prefetch without starting a new flight — when no
+	* flight exists, the click issues its own fetch with the navigation's
+	* abort signal so superseded navigations abort immediately (TIM-1438).
+	*/
+	joinInflight(key) {
+		return this.flights.get(prefetchMapKey(key));
+	}
+	/**
 	* 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
@@ -319,6 +378,31 @@ var HistoryStack = class {
 *
 * See design/19-client-navigation.md §"State Update Invariants".
 */
+/** Whether a response skipped layouts — its payload merges over the tree on screen. */
+function isPartialNavigation(skippedSegments) {
+	return skippedSegments != null && skippedSegments.length > 0;
+}
+/**
+* Whether a payload can stand on its own when replayed from the history
+* stack. See `NavigationCommitInput.skippedSegments`.
+*/
+function isReplayable(opts) {
+	return !isPartialNavigation(opts.skippedSegments) && !hasSkippedSlot(opts.segmentInfo);
+}
+function hasSkippedSlot(segmentInfo) {
+	return segmentInfo?.some((s) => s.slot && s.skipped) ?? false;
+}
+/**
+* The metadata a history entry keeps. `skipped` describes the *response*
+* — "this slot's content was omitted" — and the entry stores no such
+* payload (it stores null). Left on the entry, the flag outlives the
+* response: `applyRevalidation()` reuses the entry's metadata beside a full
+* re-render and would have that judged non-replayable too.
+*/
+function storedSegmentInfo(segmentInfo) {
+	if (!hasSkippedSlot(segmentInfo)) return segmentInfo;
+	return segmentInfo.map(({ skipped: _skipped, ...rest }) => rest);
+}
 /**
 * Derive the navigation state (pathname + search) a URL renders with.
 *
@@ -402,6 +486,7 @@ function createNavigationCommitter(deps) {
 		prepareNavigation(url, opts) {
 			const navState = deriveNavigationState(url);
 			const segmentInfo = opts.status === void 0 || opts.status < 400 ? opts.segmentInfo : [];
+			const payload = isReplayable(opts) ? opts.payload : null;
 			return {
 				navState,
 				commit() {
@@ -409,9 +494,9 @@ function createNavigationCommitter(deps) {
 					else if (segmentInfo?.length === 0 || opts.clearSegmentCacheOnEmpty) segmentCache.clear();
 					setNavigationState(navState);
 					historyStack.push(url, {
-						payload: opts.payload,
+						payload,
 						params: opts.params,
-						segmentInfo
+						segmentInfo: storedSegmentInfo(segmentInfo)
 					});
 				}
 			};
@@ -990,6 +1075,44 @@ function hardNavigate(url, fromUrl) {
 	} else window.location.href = url;
 }
 //#endregion
+//#region src/client/navigation-transition.ts
+var NAV_TRANSITION_KEY = Symbol.for("__timber_nav_transition_counter");
+function getTransitionCounter() {
+	const g = globalThis;
+	const existing = g[NAV_TRANSITION_KEY];
+	if (!existing) {
+		const created = {
+			id: 0,
+			waiters: /* @__PURE__ */ new Set()
+		};
+		g[NAV_TRANSITION_KEY] = created;
+		return created;
+	}
+	existing.waiters ??= /* @__PURE__ */ new Set();
+	return existing;
+}
+/** Bump the counter and wake everything waiting on an older transition. */
+function bumpTransitionCounter() {
+	const counter = getTransitionCounter();
+	counter.id += 1;
+	for (const wake of [...counter.waiters]) wake();
+	return counter.id;
+}
+/**
+* Invalidate all in-flight navigation transitions. Any navigateTransition()
+* call whose perform() has not yet committed will reject with AbortError
+* instead of committing its element.
+*
+* Called by the router when a render supersedes in-flight navigations
+* WITHOUT going through navigateTransition() — the cached popstate replay
+* renders directly, which doesn't bump the counter, so a stale forward
+* navigation's render would otherwise pass the `counter.id !== transId`
+* guard and commit the forward page over the replayed back page (TIM-1022).
+*/
+function supersedeNavigationTransitions() {
+	bumpTransitionCounter();
+}
+//#endregion
 //#region src/client/router-lifecycle.ts
 /**
 * Navigation Lifecycle — who owns the router, and when a fetch may be cut.
@@ -1180,6 +1303,19 @@ function createNavigationLifecycle(deps) {
 * See design/19-client-navigation.md §"Partial Rendering" and §"Prefetching".
 */
 /**
+* Race a promise against an abort signal. The promise continues regardless —
+* only the *await* gives up. Used so a click superseded by a newer navigation
+* stops waiting for a shared prefetch flight without aborting the flight
+* itself (TIM-1438).
+*/
+function raceAbort(promise, signal) {
+	if (!signal) return promise;
+	if (signal.aborted) return Promise.reject(signal.reason);
+	return Promise.race([promise, new Promise((_, reject) => {
+		signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+	})]);
+}
+/**
 * 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
@@ -1217,9 +1353,6 @@ function prefetchKeyFor(url, departingUrl, stateTree) {
 		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.
@@ -1251,9 +1384,14 @@ function observeSkew(decodePromise) {
 	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);
+	/**
+	* Render a decoded RSC payload into the DOM, publishing `commit` when the
+	* tree is current. The renderer owns that moment (see `RootRenderer`);
+	* with no renderer there is no tree to wait for, so it publishes now.
+	*/
+	function renderPayload(payload, navState, params, commit) {
+		if (deps.renderRoot) deps.renderRoot(payload, navState, params, commit);
+		else commit();
 	}
 	/**
 	* Resolve thenable payloads in the test/fallback path (no navigateTransition).
@@ -1307,8 +1445,9 @@ function createNavigationPipeline({ deps, prefetchCache, currentStateTree, prepa
 		}
 		const result = await perform();
 		handOff();
-		commitAndForget(result.commit)();
-		if (!isPartialNavigation(result.skippedSegments)) renderPayload(result.payload, result.navState, await result.params);
+		const commit = commitAndForget(result.commit);
+		if (isPartialNavigation(result.skippedSegments)) commit();
+		else renderPayload(result.payload, result.navState, await result.params, commit);
 	}
 	/**
 	* Core navigation logic shared between the transition and fallback paths.
@@ -1331,6 +1470,26 @@ function createNavigationPipeline({ deps, prefetchCache, currentStateTree, prepa
 			skippedSegments: prefetched.skippedSegments ?? null,
 			status: prefetched.status ?? 200
 		} : void 0;
+		if (result === void 0) {
+			const inflight = prefetchCache.joinInflight(cacheKey);
+			if (inflight) try {
+				const outcome = await raceAbort(inflight, options.signal);
+				if (outcome.kind === "non-route") throw new NonRscResponse(url);
+				prefetchCache.consume(cacheKey);
+				result = {
+					payload: outcome.result.payload,
+					params: outcome.result.params ?? readPublishedParams(void 0),
+					decodePromise: outcome.result.decodePromise ?? null,
+					segmentInfo: outcome.result.segmentInfo ?? null,
+					skippedSegments: outcome.result.skippedSegments ?? null,
+					status: outcome.result.status ?? 200
+				};
+			} catch (error) {
+				if (error instanceof DOMException && error.name === "AbortError") throw error;
+				if (options.signal?.aborted) throw options.signal.reason;
+				if (error instanceof SingleflightTimeoutError || error instanceof TypeError) {} else throw error;
+			}
+		}
 		if (result === void 0) result = await fetchRscPayload(url, deps, stateTree, currentUrl, options.signal);
 		const commitHistoryUrl = () => {
 			if (options.skipHistory) return;
@@ -1348,13 +1507,12 @@ function createNavigationPipeline({ deps, prefetchCache, currentStateTree, prepa
 		};
 		const payload = await resolveForFallback(result.payload);
 		const params = await result.params;
-		const isPartial = isPartialNavigation(result.skippedSegments);
-		const hasSkippedSlots = result.segmentInfo?.some((s) => s.slot && s.skipped) ?? false;
 		const { navState, commit } = prepareNavigation(url, {
-			payload: isPartial || hasSkippedSlots ? null : payload,
+			payload,
 			params,
 			segmentInfo: result.segmentInfo,
-			status: result.status
+			status: result.status,
+			skippedSegments: result.skippedSegments
 		});
 		return {
 			...result,
@@ -1469,7 +1627,8 @@ function createRouter(deps) {
 						payload,
 						params,
 						segmentInfo: result.segmentInfo,
-						status: result.status
+						status: result.status,
+						skippedSegments: result.skippedSegments
 					});
 					return {
 						...result,
@@ -1501,8 +1660,7 @@ function createRouter(deps) {
 				segmentInfo: entry.segmentInfo,
 				clearSegmentCacheOnEmpty: true
 			});
-			commit();
-			renderPayload(entry.payload, navState, entry.params);
+			renderPayload(entry.payload, navState, entry.params, commit);
 			restoreScrollAfterPaint(scrollY);
 		}, externalSignal);
 		else await fetchCommitAndRender(url, {
@@ -1514,6 +1672,9 @@ function createRouter(deps) {
 	/**
 	* Prefetch an RSC payload for a URL and store it in the prefetch cache.
 	* Called on hover of <Link prefetch> elements.
+	*
+	* Concurrent hovers and a click during the round-trip coalesce via the
+	* singleflight inside PrefetchCache (TIM-1438).
 	*/
 	function prefetch(url) {
 		if (isClientStale()) return;
@@ -1522,16 +1683,11 @@ function createRouter(deps) {
 		const stateTree = currentStateTree();
 		const cacheKey = prefetchKeyFor(fetchUrl, deps.getCurrentUrl(), stateTree);
 		const from = cacheKey.from;
-		if (prefetchCache.get(cacheKey) !== void 0) return;
+		if (prefetchCache.has(cacheKey)) return;
 		if (historyStack.has(fetchUrl)) return;
-		fetchRscPayload(fetchUrl, deps, stateTree, from).then((result) => {
-			result.decodePromise?.catch((error) => void recordSkew(error));
-			prefetchCache.set(cacheKey, result);
+		prefetchCache.fetchOrCoalesce(cacheKey, (signal) => fetchRscPayload(fetchUrl, deps, stateTree, from, signal), (err) => err instanceof NonRscResponse).then((outcome) => {
+			if (outcome.kind === "ready") outcome.result.decodePromise?.catch((error) => void recordSkew(error));
 		}, (error) => {
-			if (error instanceof NonRscResponse) {
-				prefetchCache.setNegative(cacheKey);
-				return;
-			}
 			recordSkew(error);
 		});
 	}
@@ -1553,8 +1709,7 @@ function createRouter(deps) {
 				params,
 				segmentInfo: existingEntry?.segmentInfo
 			});
-			commit();
-			renderPayload(tree, navState, params);
+			renderPayload(tree, navState, params, commit);
 		},
 		initSegmentCache: (segments) => updateSegmentCache(segments),
 		segmentCache,
@@ -1570,25 +1725,23 @@ function createRouter(deps) {
 * Returns a read-only URLSearchParams instance reflecting the current
 * URL's query string. Updates when client-side navigation changes the URL.
 *
-* On the client, reads from NavigationContext which is updated atomically
-* with the RSC tree render during full navigations, AND by
-* syncShallowSearch() for shallow URL updates (nuqs shallow: true,
-* replaceUrl, or any external pushState/replaceState that changes the
-* query string). See router-init.ts.
+* One unconditional read of NavigationContext, on every side (TIM-1425):
 *
-* This replaces the previous useSyncExternalStore approach which read
-* window.location.search directly — causing React to detect external
-* store tearing during transitions and fall back to synchronous rendering
-* (renderRootSync instead of renderRootConcurrent), blocking the main
-* thread and freezing animations.
+* - In the browser, the provider is updated atomically with the RSC tree
+*   during full navigations, AND by syncShallowSearch() for shallow URL
+*   updates (nuqs shallow: true, replaceUrl, or any external
+*   pushState/replaceState that changes the query string). See router-init.ts.
+* - During SSR, the wrapper chain mounts the same provider carrying the
+*   request's RAW query string (TIM-1424), so repeated keys
+*   (`?tag=a&tag=b`) survive — the collapsed record the ALS context holds
+*   cannot represent them.
+* - In the RSC environment, this module is never evaluated — the shims plugin
+*   resolves next/navigation to navigation-rsc.ts (TIM-1420).
 *
 * Unlike Next.js's ReadonlyURLSearchParams, this returns a standard
 * URLSearchParams. Mutation methods (set, delete, append) work on the
 * local copy but do NOT affect the URL — use the router or nuqs for that.
 *
-* During SSR, reads the request search params from the SSR ALS context
-* (populated by ssr-entry.ts) instead of window.location.
-*
 * Compatible with Next.js's `useSearchParams()` from `next/navigation`.
 */
 function getSearchParams(search) {
@@ -1602,19 +1755,17 @@ function getSearchParams(search) {
 /**
 * Read the current URL search params.
 *
+* Throws when no NavigationProvider is above the caller.
+*
 * Compatible with Next.js's `useSearchParams()` from `next/navigation`.
 */
 function useSearchParams() {
-	try {
-		const navContext = useNavigationContext();
-		if (navContext !== null) return getSearchParams(navContext.search);
-	} catch {}
-	const ssrData = getSsrData();
-	if (ssrData) return new URLSearchParams(ssrData.searchParams);
-	if (typeof window !== "undefined") return getSearchParams(window.location.search);
-	return new URLSearchParams();
+	const nav = useNavigationContext();
+	if (nav === null) throw new Error("[timber] useSearchParams() was called outside the timber app tree (no NavigationProvider found). In tests, render the component inside the timber providers.");
+	if (typeof window === "undefined" || getSsrData()) return new URLSearchParams(nav.search);
+	return getSearchParams(nav.search);
 }
 //#endregion
-export { HistoryStack, NavigationProvider, PrefetchCache, SegmentCache, SegmentProvider, TimberErrorBoundary, bindUseQueryStates, clearSsrData, createRouter, getNavigationState, getRouter, getRouterOrNull, getSsrData, setCurrentParams, setCurrentSlotParams, setGlobalRouter, setNavigationState, setSsrData, useSearchParams, useSegmentContext };
+export { HistoryStack, NavigationProvider, PrefetchCache, SegmentCache, SegmentProvider, TimberErrorBoundary, bindUseQueryStates, clearSsrData, createRouter, getNavigationState, getRouter, getRouterOrNull, getSsrData, setGlobalRouter, setNavigationState, setSsrData, useSearchParams, useSegmentContext };
 
 //# sourceMappingURL=internal.js.map