@moku-labs/web 1.6.0 → 1.6.1

package/dist/browser.mjs

@@ -3636,15 +3636,28 @@ async function performNavigation(pathname, handlers) {
 * Run a DOM-mutating swap, optionally wrapped in the View Transitions API when
 * enabled and supported (instant swap otherwise — never throws).
 *
+* `beforeCapture` runs synchronously immediately before the swap — for the View
+* Transitions path that is before `startViewTransition` captures the "old" snapshot.
+* Scroll restoration belongs HERE, not in the router after the navigation: setting
+* the destination scroll at this moment means the old and new snapshots share the
+* same scrollY, so there is no scroll delta for the transition to animate and a
+* `position: sticky` header never un-pins (the cross-engine flicker, worst on WebKit).
+* Because the swap is post-fetch, doing it here also avoids the visible "scroll up,
+* THEN the page loads" pause that scrolling in the router (pre-fetch) produced.
+*
 * @param doSwap - The synchronous DOM mutation to perform.
 * @param viewTransitions - Whether to wrap the swap in `startViewTransition`.
+* @param beforeCapture - Optional hook run synchronously just before the swap/capture
+*   (e.g. scroll to the destination position).
 * @example
-* runSwap(() => current.replaceWith(next), true);
+* runSwap(() => current.replaceWith(next), true, () => scrollTo({ top: 0, behavior: "instant" }));
 */
-function runSwap(doSwap, viewTransitions) {
+function runSwap(doSwap, viewTransitions, beforeCapture) {
 	const reduced = typeof globalThis.matchMedia === "function" && globalThis.matchMedia("(prefers-reduced-motion: reduce)").matches;
 	const docWithVt = document;
-	if (viewTransitions && !reduced && typeof docWithVt.startViewTransition === "function") docWithVt.startViewTransition(doSwap);
+	const canUseViewTransitions = viewTransitions && !reduced && typeof docWithVt.startViewTransition === "function";
+	beforeCapture?.();
+	if (canUseViewTransitions) docWithVt.startViewTransition(doSwap);
 	else doSwap();
 }
 /**
@@ -3657,17 +3670,19 @@ function runSwap(doSwap, viewTransitions) {
 * @param swapSelector - CSS selector for the region to replace.
 * @param viewTransitions - Whether to wrap the swap in `startViewTransition`.
 * @param onSwapped - Callback run after the DOM mutation (mount/notify/scroll).
+* @param beforeCapture - Optional hook run synchronously just before the swap/capture
+*   (forwarded to {@link runSwap} — e.g. scroll to the destination position).
 * @example
 * swapRegion(doc, "main > section", false, () => mountNew());
 */
-function swapRegion(doc, swapSelector, viewTransitions, onSwapped) {
+function swapRegion(doc, swapSelector, viewTransitions, onSwapped, beforeCapture) {
 	const newContent = doc.querySelector(swapSelector);
 	const currentContent = document.querySelector(swapSelector);
 	if (!newContent || !currentContent) return;
 	runSwap(() => {
 		currentContent.replaceWith(newContent);
 		onSwapped();
-	}, viewTransitions);
+	}, viewTransitions, beforeCapture);
 }
 /**
 * Resolve a navigable internal URL from a click event, or `undefined` when the
@@ -3722,7 +3737,7 @@ function attachHistoryFallback(handlers, navigate = (pathname) => performNavigat
 		}
 		saveScrollPosition(location.pathname);
 		history.pushState({ scrollY: 0 }, "", url.pathname);
-		navigate(url.pathname).then(() => window.scrollTo(0, 0)).catch(() => {});
+		navigate(url.pathname).catch(() => {});
 	};
 	/**
 	* Re-run navigation on back/forward, restoring the saved scroll position.
@@ -3731,7 +3746,7 @@ function attachHistoryFallback(handlers, navigate = (pathname) => performNavigat
 	* globalThis.addEventListener("popstate", onPopState);
 	*/
 	const onPopState = () => {
-		navigate(location.pathname).then(() => restoreScrollPosition(location.pathname)).catch(() => {});
+		navigate(location.pathname, false).then(() => restoreScrollPosition(location.pathname)).catch(() => {});
 	};
 	document.addEventListener("click", onClick);
 	globalThis.addEventListener("popstate", onPopState);
@@ -3775,9 +3790,10 @@ function attachNavigationApi(navigation, handlers, navigate = (pathname) => perf
 		navEvent.intercept({
 			scroll: "manual",
 			handler: async () => {
-				await navigate(url.pathname);
-				if (navEvent.navigationType === "traverse") navEvent.scroll();
-				else window.scrollTo(0, 0);
+				if (navEvent.navigationType === "traverse") {
+					await navigate(url.pathname, false);
+					navEvent.scroll();
+				} else await navigate(url.pathname);
 			}
 		});
 	};
@@ -3936,6 +3952,25 @@ function syncDataHead(route, routeContext) {
 function createSpaKernel(state, config, emit, deps) {
 	const resolved = resolveSpaConfig(config);
 	let progress;
+	let pendingScrollToTop = true;
+	/**
+	* Apply the in-flight navigation's scroll intent — the swap's `beforeCapture` hook.
+	* For a forward nav it scrolls to top BEFORE the snapshot is captured, so the old and
+	* new states share scrollY=0 (no delta → the sticky header never un-pins) and there is
+	* no pre-fetch scroll pause. `behavior: "instant"` defeats a page-level
+	* `scroll-behavior: smooth` that would otherwise animate the reset and re-create the
+	* delta. Traverse (back/forward) sets `pendingScrollToTop = false` and restores its
+	* saved position after the swap instead.
+	*
+	* @example
+	* runSwap(renderAndMount, viewTransitions, applyPendingScroll);
+	*/
+	const applyPendingScroll = () => {
+		if (pendingScrollToTop) window.scrollTo({
+			top: 0,
+			behavior: "instant"
+		});
+	};
 	/**
 	* Process one navigation: head-sync, unmount, swap, re-mount, emit navigated.
 	*
@@ -3951,7 +3986,7 @@ function createSpaKernel(state, config, emit, deps) {
 		swapRegion(doc, resolved.swapSelector, resolved.viewTransitions, () => {
 			scanAndMount(state, emit, resolved.swapSelector);
 			notifyNavEnd(state);
-		});
+		}, applyPendingScroll);
 		state.currentUrl = pathname;
 		progress?.done();
 		emit("spa:navigated", { url: pathname });
@@ -4046,7 +4081,7 @@ function createSpaKernel(state, config, emit, deps) {
 		*
 		* @example
 		* ```ts
-		* runSwap(renderAndMount, resolved.viewTransitions);
+		* runSwap(renderAndMount, resolved.viewTransitions, applyPendingScroll);
 		* ```
 		*/
 		const renderAndMount = () => {
@@ -4054,7 +4089,7 @@ function createSpaKernel(state, config, emit, deps) {
 			scanAndMount(state, emit, resolved.swapSelector);
 			notifyNavEnd(state);
 		};
-		runSwap(renderAndMount, resolved.viewTransitions);
+		runSwap(renderAndMount, resolved.viewTransitions, applyPendingScroll);
 		state.currentUrl = pathname;
 		progress?.done();
 		emit("spa:navigated", { url: pathname });
@@ -4091,11 +4126,14 @@ function createSpaKernel(state, config, emit, deps) {
 	* navigation entry point (Navigation API, History, programmatic) goes through it.
 	*
 	* @param pathname - The destination pathname.
+	* @param scrollToTop - Whether the swap should scroll to top before its snapshot
+	*   (default `true`; forward navs). Traverse passes `false` to keep its restored scroll.
 	* @returns A promise resolving once the swap (or fallback) is dispatched.
 	* @example
 	* await navigate("/en/world/");
 	*/
-	const navigate = async (pathname) => {
+	const navigate = async (pathname, scrollToTop = true) => {
+		pendingScrollToTop = scrollToTop;
 		if (deps.router.mode() !== "ssg" && await tryDataRender(pathname)) return;
 		await performNavigation(pathname, handlers);
 	};

package/dist/index.cjs

@@ -10112,15 +10112,28 @@ async function performNavigation(pathname, handlers) {
 * Run a DOM-mutating swap, optionally wrapped in the View Transitions API when
 * enabled and supported (instant swap otherwise — never throws).
 *
+* `beforeCapture` runs synchronously immediately before the swap — for the View
+* Transitions path that is before `startViewTransition` captures the "old" snapshot.
+* Scroll restoration belongs HERE, not in the router after the navigation: setting
+* the destination scroll at this moment means the old and new snapshots share the
+* same scrollY, so there is no scroll delta for the transition to animate and a
+* `position: sticky` header never un-pins (the cross-engine flicker, worst on WebKit).
+* Because the swap is post-fetch, doing it here also avoids the visible "scroll up,
+* THEN the page loads" pause that scrolling in the router (pre-fetch) produced.
+*
 * @param doSwap - The synchronous DOM mutation to perform.
 * @param viewTransitions - Whether to wrap the swap in `startViewTransition`.
+* @param beforeCapture - Optional hook run synchronously just before the swap/capture
+*   (e.g. scroll to the destination position).
 * @example
-* runSwap(() => current.replaceWith(next), true);
+* runSwap(() => current.replaceWith(next), true, () => scrollTo({ top: 0, behavior: "instant" }));
 */
-function runSwap(doSwap, viewTransitions) {
+function runSwap(doSwap, viewTransitions, beforeCapture) {
 	const reduced = typeof globalThis.matchMedia === "function" && globalThis.matchMedia("(prefers-reduced-motion: reduce)").matches;
 	const docWithVt = document;
-	if (viewTransitions && !reduced && typeof docWithVt.startViewTransition === "function") docWithVt.startViewTransition(doSwap);
+	const canUseViewTransitions = viewTransitions && !reduced && typeof docWithVt.startViewTransition === "function";
+	beforeCapture?.();
+	if (canUseViewTransitions) docWithVt.startViewTransition(doSwap);
 	else doSwap();
 }
 /**
@@ -10133,17 +10146,19 @@ function runSwap(doSwap, viewTransitions) {
 * @param swapSelector - CSS selector for the region to replace.
 * @param viewTransitions - Whether to wrap the swap in `startViewTransition`.
 * @param onSwapped - Callback run after the DOM mutation (mount/notify/scroll).
+* @param beforeCapture - Optional hook run synchronously just before the swap/capture
+*   (forwarded to {@link runSwap} — e.g. scroll to the destination position).
 * @example
 * swapRegion(doc, "main > section", false, () => mountNew());
 */
-function swapRegion(doc, swapSelector, viewTransitions, onSwapped) {
+function swapRegion(doc, swapSelector, viewTransitions, onSwapped, beforeCapture) {
 	const newContent = doc.querySelector(swapSelector);
 	const currentContent = document.querySelector(swapSelector);
 	if (!newContent || !currentContent) return;
 	runSwap(() => {
 		currentContent.replaceWith(newContent);
 		onSwapped();
-	}, viewTransitions);
+	}, viewTransitions, beforeCapture);
 }
 /**
 * Resolve a navigable internal URL from a click event, or `undefined` when the
@@ -10198,7 +10213,7 @@ function attachHistoryFallback(handlers, navigate = (pathname) => performNavigat
 		}
 		saveScrollPosition(location.pathname);
 		history.pushState({ scrollY: 0 }, "", url.pathname);
-		navigate(url.pathname).then(() => window.scrollTo(0, 0)).catch(() => {});
+		navigate(url.pathname).catch(() => {});
 	};
 	/**
 	* Re-run navigation on back/forward, restoring the saved scroll position.
@@ -10207,7 +10222,7 @@ function attachHistoryFallback(handlers, navigate = (pathname) => performNavigat
 	* globalThis.addEventListener("popstate", onPopState);
 	*/
 	const onPopState = () => {
-		navigate(location.pathname).then(() => restoreScrollPosition(location.pathname)).catch(() => {});
+		navigate(location.pathname, false).then(() => restoreScrollPosition(location.pathname)).catch(() => {});
 	};
 	document.addEventListener("click", onClick);
 	globalThis.addEventListener("popstate", onPopState);
@@ -10251,9 +10266,10 @@ function attachNavigationApi(navigation, handlers, navigate = (pathname) => perf
 		navEvent.intercept({
 			scroll: "manual",
 			handler: async () => {
-				await navigate(url.pathname);
-				if (navEvent.navigationType === "traverse") navEvent.scroll();
-				else window.scrollTo(0, 0);
+				if (navEvent.navigationType === "traverse") {
+					await navigate(url.pathname, false);
+					navEvent.scroll();
+				} else await navigate(url.pathname);
 			}
 		});
 	};
@@ -10412,6 +10428,25 @@ function syncDataHead(route, routeContext) {
 function createSpaKernel(state, config, emit, deps) {
 	const resolved = resolveSpaConfig(config);
 	let progress;
+	let pendingScrollToTop = true;
+	/**
+	* Apply the in-flight navigation's scroll intent — the swap's `beforeCapture` hook.
+	* For a forward nav it scrolls to top BEFORE the snapshot is captured, so the old and
+	* new states share scrollY=0 (no delta → the sticky header never un-pins) and there is
+	* no pre-fetch scroll pause. `behavior: "instant"` defeats a page-level
+	* `scroll-behavior: smooth` that would otherwise animate the reset and re-create the
+	* delta. Traverse (back/forward) sets `pendingScrollToTop = false` and restores its
+	* saved position after the swap instead.
+	*
+	* @example
+	* runSwap(renderAndMount, viewTransitions, applyPendingScroll);
+	*/
+	const applyPendingScroll = () => {
+		if (pendingScrollToTop) window.scrollTo({
+			top: 0,
+			behavior: "instant"
+		});
+	};
 	/**
 	* Process one navigation: head-sync, unmount, swap, re-mount, emit navigated.
 	*
@@ -10427,7 +10462,7 @@ function createSpaKernel(state, config, emit, deps) {
 		swapRegion(doc, resolved.swapSelector, resolved.viewTransitions, () => {
 			scanAndMount(state, emit, resolved.swapSelector);
 			notifyNavEnd(state);
-		});
+		}, applyPendingScroll);
 		state.currentUrl = pathname;
 		progress?.done();
 		emit("spa:navigated", { url: pathname });
@@ -10522,7 +10557,7 @@ function createSpaKernel(state, config, emit, deps) {
 		*
 		* @example
 		* ```ts
-		* runSwap(renderAndMount, resolved.viewTransitions);
+		* runSwap(renderAndMount, resolved.viewTransitions, applyPendingScroll);
 		* ```
 		*/
 		const renderAndMount = () => {
@@ -10530,7 +10565,7 @@ function createSpaKernel(state, config, emit, deps) {
 			scanAndMount(state, emit, resolved.swapSelector);
 			notifyNavEnd(state);
 		};
-		runSwap(renderAndMount, resolved.viewTransitions);
+		runSwap(renderAndMount, resolved.viewTransitions, applyPendingScroll);
 		state.currentUrl = pathname;
 		progress?.done();
 		emit("spa:navigated", { url: pathname });
@@ -10567,11 +10602,14 @@ function createSpaKernel(state, config, emit, deps) {
 	* navigation entry point (Navigation API, History, programmatic) goes through it.
 	*
 	* @param pathname - The destination pathname.
+	* @param scrollToTop - Whether the swap should scroll to top before its snapshot
+	*   (default `true`; forward navs). Traverse passes `false` to keep its restored scroll.
 	* @returns A promise resolving once the swap (or fallback) is dispatched.
 	* @example
 	* await navigate("/en/world/");
 	*/
-	const navigate = async (pathname) => {
+	const navigate = async (pathname, scrollToTop = true) => {
+		pendingScrollToTop = scrollToTop;
 		if (deps.router.mode() !== "ssg" && await tryDataRender(pathname)) return;
 		await performNavigation(pathname, handlers);
 	};

package/dist/index.mjs

@@ -10099,15 +10099,28 @@ async function performNavigation(pathname, handlers) {
 * Run a DOM-mutating swap, optionally wrapped in the View Transitions API when
 * enabled and supported (instant swap otherwise — never throws).
 *
+* `beforeCapture` runs synchronously immediately before the swap — for the View
+* Transitions path that is before `startViewTransition` captures the "old" snapshot.
+* Scroll restoration belongs HERE, not in the router after the navigation: setting
+* the destination scroll at this moment means the old and new snapshots share the
+* same scrollY, so there is no scroll delta for the transition to animate and a
+* `position: sticky` header never un-pins (the cross-engine flicker, worst on WebKit).
+* Because the swap is post-fetch, doing it here also avoids the visible "scroll up,
+* THEN the page loads" pause that scrolling in the router (pre-fetch) produced.
+*
 * @param doSwap - The synchronous DOM mutation to perform.
 * @param viewTransitions - Whether to wrap the swap in `startViewTransition`.
+* @param beforeCapture - Optional hook run synchronously just before the swap/capture
+*   (e.g. scroll to the destination position).
 * @example
-* runSwap(() => current.replaceWith(next), true);
+* runSwap(() => current.replaceWith(next), true, () => scrollTo({ top: 0, behavior: "instant" }));
 */
-function runSwap(doSwap, viewTransitions) {
+function runSwap(doSwap, viewTransitions, beforeCapture) {
 	const reduced = typeof globalThis.matchMedia === "function" && globalThis.matchMedia("(prefers-reduced-motion: reduce)").matches;
 	const docWithVt = document;
-	if (viewTransitions && !reduced && typeof docWithVt.startViewTransition === "function") docWithVt.startViewTransition(doSwap);
+	const canUseViewTransitions = viewTransitions && !reduced && typeof docWithVt.startViewTransition === "function";
+	beforeCapture?.();
+	if (canUseViewTransitions) docWithVt.startViewTransition(doSwap);
 	else doSwap();
 }
 /**
@@ -10120,17 +10133,19 @@ function runSwap(doSwap, viewTransitions) {
 * @param swapSelector - CSS selector for the region to replace.
 * @param viewTransitions - Whether to wrap the swap in `startViewTransition`.
 * @param onSwapped - Callback run after the DOM mutation (mount/notify/scroll).
+* @param beforeCapture - Optional hook run synchronously just before the swap/capture
+*   (forwarded to {@link runSwap} — e.g. scroll to the destination position).
 * @example
 * swapRegion(doc, "main > section", false, () => mountNew());
 */
-function swapRegion(doc, swapSelector, viewTransitions, onSwapped) {
+function swapRegion(doc, swapSelector, viewTransitions, onSwapped, beforeCapture) {
 	const newContent = doc.querySelector(swapSelector);
 	const currentContent = document.querySelector(swapSelector);
 	if (!newContent || !currentContent) return;
 	runSwap(() => {
 		currentContent.replaceWith(newContent);
 		onSwapped();
-	}, viewTransitions);
+	}, viewTransitions, beforeCapture);
 }
 /**
 * Resolve a navigable internal URL from a click event, or `undefined` when the
@@ -10185,7 +10200,7 @@ function attachHistoryFallback(handlers, navigate = (pathname) => performNavigat
 		}
 		saveScrollPosition(location.pathname);
 		history.pushState({ scrollY: 0 }, "", url.pathname);
-		navigate(url.pathname).then(() => window.scrollTo(0, 0)).catch(() => {});
+		navigate(url.pathname).catch(() => {});
 	};
 	/**
 	* Re-run navigation on back/forward, restoring the saved scroll position.
@@ -10194,7 +10209,7 @@ function attachHistoryFallback(handlers, navigate = (pathname) => performNavigat
 	* globalThis.addEventListener("popstate", onPopState);
 	*/
 	const onPopState = () => {
-		navigate(location.pathname).then(() => restoreScrollPosition(location.pathname)).catch(() => {});
+		navigate(location.pathname, false).then(() => restoreScrollPosition(location.pathname)).catch(() => {});
 	};
 	document.addEventListener("click", onClick);
 	globalThis.addEventListener("popstate", onPopState);
@@ -10238,9 +10253,10 @@ function attachNavigationApi(navigation, handlers, navigate = (pathname) => perf
 		navEvent.intercept({
 			scroll: "manual",
 			handler: async () => {
-				await navigate(url.pathname);
-				if (navEvent.navigationType === "traverse") navEvent.scroll();
-				else window.scrollTo(0, 0);
+				if (navEvent.navigationType === "traverse") {
+					await navigate(url.pathname, false);
+					navEvent.scroll();
+				} else await navigate(url.pathname);
 			}
 		});
 	};
@@ -10399,6 +10415,25 @@ function syncDataHead(route, routeContext) {
 function createSpaKernel(state, config, emit, deps) {
 	const resolved = resolveSpaConfig(config);
 	let progress;
+	let pendingScrollToTop = true;
+	/**
+	* Apply the in-flight navigation's scroll intent — the swap's `beforeCapture` hook.
+	* For a forward nav it scrolls to top BEFORE the snapshot is captured, so the old and
+	* new states share scrollY=0 (no delta → the sticky header never un-pins) and there is
+	* no pre-fetch scroll pause. `behavior: "instant"` defeats a page-level
+	* `scroll-behavior: smooth` that would otherwise animate the reset and re-create the
+	* delta. Traverse (back/forward) sets `pendingScrollToTop = false` and restores its
+	* saved position after the swap instead.
+	*
+	* @example
+	* runSwap(renderAndMount, viewTransitions, applyPendingScroll);
+	*/
+	const applyPendingScroll = () => {
+		if (pendingScrollToTop) window.scrollTo({
+			top: 0,
+			behavior: "instant"
+		});
+	};
 	/**
 	* Process one navigation: head-sync, unmount, swap, re-mount, emit navigated.
 	*
@@ -10414,7 +10449,7 @@ function createSpaKernel(state, config, emit, deps) {
 		swapRegion(doc, resolved.swapSelector, resolved.viewTransitions, () => {
 			scanAndMount(state, emit, resolved.swapSelector);
 			notifyNavEnd(state);
-		});
+		}, applyPendingScroll);
 		state.currentUrl = pathname;
 		progress?.done();
 		emit("spa:navigated", { url: pathname });
@@ -10509,7 +10544,7 @@ function createSpaKernel(state, config, emit, deps) {
 		*
 		* @example
 		* ```ts
-		* runSwap(renderAndMount, resolved.viewTransitions);
+		* runSwap(renderAndMount, resolved.viewTransitions, applyPendingScroll);
 		* ```
 		*/
 		const renderAndMount = () => {
@@ -10517,7 +10552,7 @@ function createSpaKernel(state, config, emit, deps) {
 			scanAndMount(state, emit, resolved.swapSelector);
 			notifyNavEnd(state);
 		};
-		runSwap(renderAndMount, resolved.viewTransitions);
+		runSwap(renderAndMount, resolved.viewTransitions, applyPendingScroll);
 		state.currentUrl = pathname;
 		progress?.done();
 		emit("spa:navigated", { url: pathname });
@@ -10554,11 +10589,14 @@ function createSpaKernel(state, config, emit, deps) {
 	* navigation entry point (Navigation API, History, programmatic) goes through it.
 	*
 	* @param pathname - The destination pathname.
+	* @param scrollToTop - Whether the swap should scroll to top before its snapshot
+	*   (default `true`; forward navs). Traverse passes `false` to keep its restored scroll.
 	* @returns A promise resolving once the swap (or fallback) is dispatched.
 	* @example
 	* await navigate("/en/world/");
 	*/
-	const navigate = async (pathname) => {
+	const navigate = async (pathname, scrollToTop = true) => {
+		pendingScrollToTop = scrollToTop;
 		if (deps.router.mode() !== "ssg" && await tryDataRender(pathname)) return;
 		await performNavigation(pathname, handlers);
 	};

package/package.json

@@ -113,5 +113,5 @@
     "test:cli-e2e": "bun test src/plugins/cli/__tests__/e2e/",
     "test:coverage": "vitest run --project unit --project integration --coverage"
   },
-  "version": "1.6.0"
+  "version": "1.6.1"
 }