@moku-labs/web 2.4.1 → 2.4.3

package/README.md

@@ -140,7 +140,7 @@ route("/board/{id}/issue/{issueId}")
 
 - **`viewTransitions`** accepts `boolean` (`true` → `"crossfade"`, `false` → `"none"`) **or** a named `TransitionMode` (`"none" | "crossfade" | "slide" | "morph"`). A named transition tags the swap so your CSS can target it two ways — `:root[data-view-transition~="slide"]` (every View-Transitions engine) and the standards-track `:active-view-transition-type(slide)` — and a shared `view-transition-name` left across the swap morphs one element into another. Reduced-motion and unsupported browsers fall back to an instant swap.
 - **`scrollRestoration`** is `"top"` (reset, the default) or `"preserve"` (keep the current scroll — e.g. opening an overlay route over content that must stay still). Back/forward always restores its saved position.
-- **`ctx.navigate(path, options?)`** — every island can navigate programmatically with no `app` handle (an always-present context member, like `ctx.set`/`ctx.url`). `app.spa.navigate` takes the same optional `{ scroll }`.
+- **`ctx.navigate(path, options?)`** — every island can navigate programmatically with no `app` handle (an always-present context member, like `ctx.set`/`ctx.url`). `app.spa.navigate` takes the same optional `{ scroll, replace }`: `replace: true` swaps the current history entry instead of adding one, so Back skips the page navigated from (e.g. the same page in another language).
 - **`navigate(path, options?)` / `hardNavigate(url)`** — importable from `@moku-labs/web/browser` for module-scope callers (shared chrome/nav helpers with no `app` or island `ctx`); they bind to the single booted app and no-op before `app.start()`. `hardNavigate` (also `app.spa.hardNavigate`) does a REAL full-page load for crossing a boundary the SPA can't swap — a different layout or an auth split — by detaching the SPA's own interceptor first, so `location.assign` isn't caught and converted to a region swap.
 
 ```ts

package/dist/browser.d.mts

@@ -920,6 +920,11 @@ declare namespace types_d_exports$5 {
 interface NavigateOptions {
   /** Override the scroll behaviour for this single navigation (else the route/app default). */
   scroll?: ScrollMode;
+  /**
+   * Replace the current history entry instead of adding one (`history.replaceState`), so Back
+   * skips the page navigated from; e.g. the same page in another language.
+   */
+  replace?: boolean;
 }
 /** Payload map for the events `spa` emits, used to type the kernel's `emit` closure. */
 type SpaEvents = {

package/dist/browser.mjs

@@ -3867,6 +3867,17 @@ function createSpaKernel(state, config, emit, deps) {
 	let pendingScrollToTop = true;
 	let pendingTransition = resolveTransition(resolved.defaultTransition);
 	let pushingOwnUrl = false;
+	let programmatic;
+	/**
+	* Aborts the programmatic navigation still loading, if any.
+	*
+	* @example
+	* supersedeProgrammatic(); // a link click or back/forward starts
+	*/
+	const supersedeProgrammatic = () => {
+		programmatic?.abort();
+		programmatic = void 0;
+	};
 	/**
 	* Resolve a {@link TransitionMode} into the runtime {@link SwapTransition} the swap
 	* consumes: `"none"` ⇒ disabled; `"crossfade"` ⇒ enabled, no named types (default root
@@ -4181,25 +4192,35 @@ function createSpaKernel(state, config, emit, deps) {
 	* swaps but the address bar (and the back button / refresh / deep link) stays on the old URL.
 	* Where the Navigation API exists, `history.pushState` fires a `navigate` event synchronously
 	* (Chrome, Edge, Safari 26): `pushingOwnUrl` marks it, so the interceptor does not run this
-	* navigation a second time. The current scroll is saved first so a later back restores it.
+	* navigation a second time. The current scroll is saved first so a later back restores it. It
+	* carries its own abort signal: any later navigation aborts it before it can swap.
+	*
+	* `options.replace` swaps the current history entry (`replaceState`) instead of adding one.
 	*
 	* @param path - The destination path (pathname + optional search).
-	* @param scroll - The optional per-call scroll override.
+	* @param options - Optional per-call overrides: `scroll`, `replace`.
 	* @example
-	* navigateProgrammatic("/board/abc/issue/1", "preserve");
+	* navigateProgrammatic("/board/abc/issue/1", { scroll: "preserve" });
 	*/
-	const navigateProgrammatic = (path, scroll) => {
+	const navigateProgrammatic = (path, options = {}) => {
 		if (typeof document === "undefined") return;
+		const { scroll, replace = false } = options;
 		if (path !== currentLocationUrl()) {
 			saveScrollPosition(currentLocationUrl());
 			pushingOwnUrl = true;
 			try {
-				history.pushState({}, "", path);
+				if (replace) history.replaceState({}, "", path);
+				else history.pushState({}, "", path);
 			} finally {
 				pushingOwnUrl = false;
 			}
 		}
-		navigate(path, true, void 0, scroll).catch(() => {});
+		supersedeProgrammatic();
+		const controller = new AbortController();
+		programmatic = controller;
+		navigate(path, true, controller.signal, scroll).catch(() => {}).finally(() => {
+			if (programmatic === controller) programmatic = void 0;
+		});
 	};
 	return {
 		/**
@@ -4212,7 +4233,7 @@ function createSpaKernel(state, config, emit, deps) {
 			for (const island of resolved.islands) registerIsland(state, island);
 			state.currentUrl = currentLocationUrl();
 			state.navigate = (path, options) => {
-				navigateProgrammatic(path, options?.scroll);
+				navigateProgrammatic(path, options);
 			};
 		},
 		/**
@@ -4226,7 +4247,10 @@ function createSpaKernel(state, config, emit, deps) {
 			if (state.started) throw new Error(`${ERROR_PREFIX} spa kernel already started.\n  Call app.stop() before booting again (single boot per app).`);
 			progress = createProgressBar(resolved.progressBar);
 			state.currentUrl = currentLocationUrl();
-			state.destroyRouter = attachRouter(handlers, navigate, () => pushingOwnUrl);
+			state.destroyRouter = attachRouter(handlers, (pathname, scrollToTop, signal, scrollOverride) => {
+				supersedeProgrammatic();
+				return navigate(pathname, scrollToTop, signal, scrollOverride);
+			}, () => pushingOwnUrl);
 			const matchPath = state.currentUrl.split("?")[0] ?? state.currentUrl;
 			const hit = deps.router.match(matchPath);
 			if (hit?.route._handlers.render && isClientOnlyRoute(deps.router.mode(), hit.route)) bootRender(state.currentUrl);
@@ -4244,16 +4268,16 @@ function createSpaKernel(state, config, emit, deps) {
 			registerIsland(state, island);
 		},
 		/**
-		* Process a navigation to `path` (fetch then swap; full reload on error). An optional
-		* per-call `scroll` override flows through to the swap's scroll intent.
+		* Process a navigation to `path` (fetch then swap; full reload on error). Optional per-call
+		* overrides: `scroll` for the swap's scroll intent, `replace` to replace the history entry.
 		*
 		* @param path - The target path to navigate to.
-		* @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve" }`).
+		* @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve", replace: true }`).
 		* @example
 		* kernel.processNav("/about");
 		*/
 		processNav(path, options) {
-			navigateProgrammatic(path, options?.scroll);
+			navigateProgrammatic(path, options);
 		},
 		/**
 		* Cross a boundary the SPA cannot swap (a different layout, the auth split) with a REAL

package/dist/index.cjs

@@ -10961,6 +10961,17 @@ function createSpaKernel(state, config, emit, deps) {
 	let pendingScrollToTop = true;
 	let pendingTransition = resolveTransition(resolved.defaultTransition);
 	let pushingOwnUrl = false;
+	let programmatic;
+	/**
+	* Aborts the programmatic navigation still loading, if any.
+	*
+	* @example
+	* supersedeProgrammatic(); // a link click or back/forward starts
+	*/
+	const supersedeProgrammatic = () => {
+		programmatic?.abort();
+		programmatic = void 0;
+	};
 	/**
 	* Resolve a {@link TransitionMode} into the runtime {@link SwapTransition} the swap
 	* consumes: `"none"` ⇒ disabled; `"crossfade"` ⇒ enabled, no named types (default root
@@ -11275,25 +11286,35 @@ function createSpaKernel(state, config, emit, deps) {
 	* swaps but the address bar (and the back button / refresh / deep link) stays on the old URL.
 	* Where the Navigation API exists, `history.pushState` fires a `navigate` event synchronously
 	* (Chrome, Edge, Safari 26): `pushingOwnUrl` marks it, so the interceptor does not run this
-	* navigation a second time. The current scroll is saved first so a later back restores it.
+	* navigation a second time. The current scroll is saved first so a later back restores it. It
+	* carries its own abort signal: any later navigation aborts it before it can swap.
+	*
+	* `options.replace` swaps the current history entry (`replaceState`) instead of adding one.
 	*
 	* @param path - The destination path (pathname + optional search).
-	* @param scroll - The optional per-call scroll override.
+	* @param options - Optional per-call overrides: `scroll`, `replace`.
 	* @example
-	* navigateProgrammatic("/board/abc/issue/1", "preserve");
+	* navigateProgrammatic("/board/abc/issue/1", { scroll: "preserve" });
 	*/
-	const navigateProgrammatic = (path, scroll) => {
+	const navigateProgrammatic = (path, options = {}) => {
 		if (typeof document === "undefined") return;
+		const { scroll, replace = false } = options;
 		if (path !== currentLocationUrl()) {
 			saveScrollPosition(currentLocationUrl());
 			pushingOwnUrl = true;
 			try {
-				history.pushState({}, "", path);
+				if (replace) history.replaceState({}, "", path);
+				else history.pushState({}, "", path);
 			} finally {
 				pushingOwnUrl = false;
 			}
 		}
-		navigate(path, true, void 0, scroll).catch(() => {});
+		supersedeProgrammatic();
+		const controller = new AbortController();
+		programmatic = controller;
+		navigate(path, true, controller.signal, scroll).catch(() => {}).finally(() => {
+			if (programmatic === controller) programmatic = void 0;
+		});
 	};
 	return {
 		/**
@@ -11306,7 +11327,7 @@ function createSpaKernel(state, config, emit, deps) {
 			for (const island of resolved.islands) registerIsland(state, island);
 			state.currentUrl = currentLocationUrl();
 			state.navigate = (path, options) => {
-				navigateProgrammatic(path, options?.scroll);
+				navigateProgrammatic(path, options);
 			};
 		},
 		/**
@@ -11320,7 +11341,10 @@ function createSpaKernel(state, config, emit, deps) {
 			if (state.started) throw new Error(`${ERROR_PREFIX} spa kernel already started.\n  Call app.stop() before booting again (single boot per app).`);
 			progress = createProgressBar(resolved.progressBar);
 			state.currentUrl = currentLocationUrl();
-			state.destroyRouter = attachRouter(handlers, navigate, () => pushingOwnUrl);
+			state.destroyRouter = attachRouter(handlers, (pathname, scrollToTop, signal, scrollOverride) => {
+				supersedeProgrammatic();
+				return navigate(pathname, scrollToTop, signal, scrollOverride);
+			}, () => pushingOwnUrl);
 			const matchPath = state.currentUrl.split("?")[0] ?? state.currentUrl;
 			const hit = deps.router.match(matchPath);
 			if (hit?.route._handlers.render && isClientOnlyRoute(deps.router.mode(), hit.route)) bootRender(state.currentUrl);
@@ -11338,16 +11362,16 @@ function createSpaKernel(state, config, emit, deps) {
 			registerIsland(state, island);
 		},
 		/**
-		* Process a navigation to `path` (fetch then swap; full reload on error). An optional
-		* per-call `scroll` override flows through to the swap's scroll intent.
+		* Process a navigation to `path` (fetch then swap; full reload on error). Optional per-call
+		* overrides: `scroll` for the swap's scroll intent, `replace` to replace the history entry.
 		*
 		* @param path - The target path to navigate to.
-		* @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve" }`).
+		* @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve", replace: true }`).
 		* @example
 		* kernel.processNav("/about");
 		*/
 		processNav(path, options) {
-			navigateProgrammatic(path, options?.scroll);
+			navigateProgrammatic(path, options);
 		},
 		/**
 		* Cross a boundary the SPA cannot swap (a different layout, the auth split) with a REAL

package/dist/index.d.cts

@@ -921,6 +921,11 @@ declare namespace types_d_exports$8 {
 interface NavigateOptions {
   /** Override the scroll behaviour for this single navigation (else the route/app default). */
   scroll?: ScrollMode;
+  /**
+   * Replace the current history entry instead of adding one (`history.replaceState`), so Back
+   * skips the page navigated from; e.g. the same page in another language.
+   */
+  replace?: boolean;
 }
 /** Payload map for the events `spa` emits, used to type the kernel's `emit` closure. */
 type SpaEvents = {

package/dist/index.d.mts

@@ -919,6 +919,11 @@ declare namespace types_d_exports$8 {
 interface NavigateOptions {
   /** Override the scroll behaviour for this single navigation (else the route/app default). */
   scroll?: ScrollMode;
+  /**
+   * Replace the current history entry instead of adding one (`history.replaceState`), so Back
+   * skips the page navigated from; e.g. the same page in another language.
+   */
+  replace?: boolean;
 }
 /** Payload map for the events `spa` emits, used to type the kernel's `emit` closure. */
 type SpaEvents = {

package/dist/index.mjs

@@ -10917,6 +10917,17 @@ function createSpaKernel(state, config, emit, deps) {
 	let pendingScrollToTop = true;
 	let pendingTransition = resolveTransition(resolved.defaultTransition);
 	let pushingOwnUrl = false;
+	let programmatic;
+	/**
+	* Aborts the programmatic navigation still loading, if any.
+	*
+	* @example
+	* supersedeProgrammatic(); // a link click or back/forward starts
+	*/
+	const supersedeProgrammatic = () => {
+		programmatic?.abort();
+		programmatic = void 0;
+	};
 	/**
 	* Resolve a {@link TransitionMode} into the runtime {@link SwapTransition} the swap
 	* consumes: `"none"` ⇒ disabled; `"crossfade"` ⇒ enabled, no named types (default root
@@ -11231,25 +11242,35 @@ function createSpaKernel(state, config, emit, deps) {
 	* swaps but the address bar (and the back button / refresh / deep link) stays on the old URL.
 	* Where the Navigation API exists, `history.pushState` fires a `navigate` event synchronously
 	* (Chrome, Edge, Safari 26): `pushingOwnUrl` marks it, so the interceptor does not run this
-	* navigation a second time. The current scroll is saved first so a later back restores it.
+	* navigation a second time. The current scroll is saved first so a later back restores it. It
+	* carries its own abort signal: any later navigation aborts it before it can swap.
+	*
+	* `options.replace` swaps the current history entry (`replaceState`) instead of adding one.
 	*
 	* @param path - The destination path (pathname + optional search).
-	* @param scroll - The optional per-call scroll override.
+	* @param options - Optional per-call overrides: `scroll`, `replace`.
 	* @example
-	* navigateProgrammatic("/board/abc/issue/1", "preserve");
+	* navigateProgrammatic("/board/abc/issue/1", { scroll: "preserve" });
 	*/
-	const navigateProgrammatic = (path, scroll) => {
+	const navigateProgrammatic = (path, options = {}) => {
 		if (typeof document === "undefined") return;
+		const { scroll, replace = false } = options;
 		if (path !== currentLocationUrl()) {
 			saveScrollPosition(currentLocationUrl());
 			pushingOwnUrl = true;
 			try {
-				history.pushState({}, "", path);
+				if (replace) history.replaceState({}, "", path);
+				else history.pushState({}, "", path);
 			} finally {
 				pushingOwnUrl = false;
 			}
 		}
-		navigate(path, true, void 0, scroll).catch(() => {});
+		supersedeProgrammatic();
+		const controller = new AbortController();
+		programmatic = controller;
+		navigate(path, true, controller.signal, scroll).catch(() => {}).finally(() => {
+			if (programmatic === controller) programmatic = void 0;
+		});
 	};
 	return {
 		/**
@@ -11262,7 +11283,7 @@ function createSpaKernel(state, config, emit, deps) {
 			for (const island of resolved.islands) registerIsland(state, island);
 			state.currentUrl = currentLocationUrl();
 			state.navigate = (path, options) => {
-				navigateProgrammatic(path, options?.scroll);
+				navigateProgrammatic(path, options);
 			};
 		},
 		/**
@@ -11276,7 +11297,10 @@ function createSpaKernel(state, config, emit, deps) {
 			if (state.started) throw new Error(`${ERROR_PREFIX} spa kernel already started.\n  Call app.stop() before booting again (single boot per app).`);
 			progress = createProgressBar(resolved.progressBar);
 			state.currentUrl = currentLocationUrl();
-			state.destroyRouter = attachRouter(handlers, navigate, () => pushingOwnUrl);
+			state.destroyRouter = attachRouter(handlers, (pathname, scrollToTop, signal, scrollOverride) => {
+				supersedeProgrammatic();
+				return navigate(pathname, scrollToTop, signal, scrollOverride);
+			}, () => pushingOwnUrl);
 			const matchPath = state.currentUrl.split("?")[0] ?? state.currentUrl;
 			const hit = deps.router.match(matchPath);
 			if (hit?.route._handlers.render && isClientOnlyRoute(deps.router.mode(), hit.route)) bootRender(state.currentUrl);
@@ -11294,16 +11318,16 @@ function createSpaKernel(state, config, emit, deps) {
 			registerIsland(state, island);
 		},
 		/**
-		* Process a navigation to `path` (fetch then swap; full reload on error). An optional
-		* per-call `scroll` override flows through to the swap's scroll intent.
+		* Process a navigation to `path` (fetch then swap; full reload on error). Optional per-call
+		* overrides: `scroll` for the swap's scroll intent, `replace` to replace the history entry.
 		*
 		* @param path - The target path to navigate to.
-		* @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve" }`).
+		* @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve", replace: true }`).
 		* @example
 		* kernel.processNav("/about");
 		*/
 		processNav(path, options) {
-			navigateProgrammatic(path, options?.scroll);
+			navigateProgrammatic(path, options);
 		},
 		/**
 		* Cross a boundary the SPA cannot swap (a different layout, the auth split) with a REAL

package/dist/testing.d.mts

@@ -13,6 +13,11 @@ type ScrollMode = "top" | "preserve";
 interface NavigateOptions {
   /** Override the scroll behaviour for this single navigation (else the route/app default). */
   scroll?: ScrollMode;
+  /**
+   * Replace the current history entry instead of adding one (`history.replaceState`), so Back
+   * skips the page navigated from; e.g. the same page in another language.
+   */
+  replace?: boolean;
 }
 /**
  * What a island's `render` may return:

package/package.json

@@ -137,5 +137,5 @@
     "release:doctor": "moku-release doctor",
     "release": "moku-release"
   },
-  "version": "2.4.1"
+  "version": "2.4.3"
 }