@moku-labs/web 2.4.2 → 2.4.4

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 = {
@@ -2797,7 +2802,7 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
     name: string;
     el: Element;
   };
-}> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>]>> | undefined) => import("@moku-labs/core").App<Config$5, Events, (import("@moku-labs/core").PluginInstance<"site", Config$4, Record<string, never>, Api$4, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$3, Record<string, never>, Api$3, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
+}> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>]>, import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi> | import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>> | undefined) => import("@moku-labs/core").App<Config$5, Events, (import("@moku-labs/core").PluginInstance<"site", Config$4, Record<string, never>, Api$4, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$3, Record<string, never>, Api$3, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
   route: typeof route;
   defineRoutes: typeof defineRoutes;
   createUrls: typeof createUrls;

package/dist/browser.mjs

@@ -4195,18 +4195,22 @@ function createSpaKernel(state, config, emit, deps) {
 	* 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;
 			}
@@ -4229,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);
 			};
 		},
 		/**
@@ -4264,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

@@ -11289,18 +11289,22 @@ function createSpaKernel(state, config, emit, deps) {
 	* 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;
 			}
@@ -11323,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);
 			};
 		},
 		/**
@@ -11358,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 = {
@@ -4155,7 +4160,7 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
     name: string;
     el: Element;
   };
-}> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>]>> | undefined) => import("@moku-labs/core").App<Config$8, Events, (import("@moku-labs/core").PluginInstance<"site", Config$7, Record<string, never>, Api$7, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
+}> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>]>, import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi> | import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>> | undefined) => import("@moku-labs/core").App<Config$8, Events, (import("@moku-labs/core").PluginInstance<"site", Config$7, Record<string, never>, Api$7, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
   route: typeof route;
   defineRoutes: typeof defineRoutes;
   createUrls: typeof createUrls;

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 = {
@@ -4153,7 +4158,7 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
     name: string;
     el: Element;
   };
-}> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>]>> | undefined) => import("@moku-labs/core").App<Config$8, Events, (import("@moku-labs/core").PluginInstance<"site", Config$7, Record<string, never>, Api$7, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
+}> & Record<never, never>) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>]>, import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi> | import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>> | undefined) => import("@moku-labs/core").App<Config$8, Events, (import("@moku-labs/core").PluginInstance<"site", Config$7, Record<string, never>, Api$7, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"i18n", Config$6, Record<string, never>, Api$6, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"router", RouterConfig, RouterState, RouterApi, {}> & {
   route: typeof route;
   defineRoutes: typeof defineRoutes;
   createUrls: typeof createUrls;

package/dist/index.mjs

@@ -11245,18 +11245,22 @@ function createSpaKernel(state, config, emit, deps) {
 	* 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;
 			}
@@ -11279,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);
 			};
 		},
 		/**
@@ -11314,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

@@ -64,8 +64,6 @@
     "bun": ">=1.3.14"
   },
   "dependencies": {
-    "@moku-labs/common": "0.3.2",
-    "@moku-labs/core": "1.6.0",
     "@resvg/resvg-js": "2.6.2",
     "@shikijs/rehype": "3.22.0",
     "feed": "5.2.0",
@@ -87,10 +85,30 @@
     "unist-util-visit": "5.1.0"
   },
   "peerDependencies": {
+    "@moku-labs/common": "^0.3.4",
+    "@moku-labs/core": "^1.7.1",
     "mermaid-isomorphic": "^3.0.0",
     "preact": "^10.29.2",
     "preact-render-to-string": "^6.6.0"
   },
+  "scripts": {
+    "build": "tsdown",
+    "validate": "publint",
+    "check:bundle": "bun scripts/verify-browser-bundle.ts",
+    "lint": "biome check . && eslint .",
+    "lint:fix": "biome check --write . && eslint --fix .",
+    "format": "biome format --write .",
+    "test": "vitest run",
+    "test:unit": "vitest run --project unit",
+    "test:integration": "vitest run --project integration",
+    "test:cli-e2e": "bun test --timeout 30000 src/plugins/cli/__tests__/e2e/",
+    "test:build-e2e": "bun test src/plugins/build/__tests__/e2e/",
+    "test:coverage": "vitest run --project unit --project integration --coverage",
+    "typecheck": "tsc --noEmit",
+    "release:setup": "moku-release setup",
+    "release:doctor": "moku-release doctor",
+    "release": "moku-release"
+  },
   "peerDependenciesMeta": {
     "mermaid-isomorphic": {
       "optional": true
@@ -99,6 +117,8 @@
   "devDependencies": {
     "@biomejs/biome": "2.4.16",
     "@moku-labs/ci": "1.2.6",
+    "@moku-labs/common": "0.3.4",
+    "@moku-labs/core": "1.7.1",
     "@types/bun": "1.3.14",
     "@vitest/coverage-istanbul": "4.0.18",
     "eslint": "9.39.3",
@@ -119,23 +139,5 @@
     "typescript-eslint": "8.58.0",
     "vitest": "4.0.18"
   },
-  "scripts": {
-    "build": "tsdown",
-    "validate": "publint",
-    "check:bundle": "bun scripts/verify-browser-bundle.ts",
-    "lint": "biome check . && eslint .",
-    "lint:fix": "biome check --write . && eslint --fix .",
-    "format": "biome format --write .",
-    "test": "vitest run",
-    "test:unit": "vitest run --project unit",
-    "test:integration": "vitest run --project integration",
-    "test:cli-e2e": "bun test --timeout 30000 src/plugins/cli/__tests__/e2e/",
-    "test:build-e2e": "bun test src/plugins/build/__tests__/e2e/",
-    "test:coverage": "vitest run --project unit --project integration --coverage",
-    "typecheck": "tsc --noEmit",
-    "release:setup": "moku-release setup",
-    "release:doctor": "moku-release doctor",
-    "release": "moku-release"
-  },
-  "version": "2.4.2"
+  "version": "2.4.4"
 }