@moku-labs/web 2.3.3 → 2.4.1

package/dist/browser.mjs

@@ -3645,11 +3645,13 @@ function attachHistoryFallback(handlers, navigate = (pathname, _scrollToTop, sig
 * @param navigation - The Navigation API object to attach the listener to.
 * @param handlers - The navigation lifecycle callbacks.
 * @param navigate - The navigation strategy (defaults to HTML-over-fetch via `performNavigation`).
+* @param isOwnPush - True while the kernel's programmatic navigation runs its own
+*   `history.pushState`: the `navigate` event it fires is left alone, the kernel runs it once.
 * @returns A teardown that removes the `navigate` listener.
 * @example
 * const dispose = attachNavigationApi(navigation, handlers);
 */
-function attachNavigationApi(navigation, handlers, navigate = (pathname, _scrollToTop, signal) => performNavigation(pathname, handlers, signal)) {
+function attachNavigationApi(navigation, handlers, navigate = (pathname, _scrollToTop, signal) => performNavigation(pathname, handlers, signal), isOwnPush = () => false) {
 	/**
 	* Handle a `navigate` event: classify, then intercept with fetch-and-swap.
 	*
@@ -3658,6 +3660,7 @@ function attachNavigationApi(navigation, handlers, navigate = (pathname, _scroll
 	* navigation.addEventListener("navigate", onNavigate);
 	*/
 	const onNavigate = (navEvent) => {
+		if (isOwnPush()) return;
 		const url = new URL(navEvent.destination.url);
 		if (!navEvent.canIntercept || navEvent.hashChange || navEvent.downloadRequest) return;
 		if (!isInternalLink(url)) return;
@@ -3690,13 +3693,15 @@ function attachNavigationApi(navigation, handlers, navigate = (pathname, _scroll
 *
 * @param handlers - The navigation lifecycle callbacks the kernel supplies.
 * @param navigate - The navigation strategy (defaults to HTML-over-fetch via `performNavigation`).
+* @param isOwnPush - True while the kernel runs its own `history.pushState` (Navigation API path
+*   only; the History fallback never sees an event for it).
 * @returns A teardown removing all attached listeners.
 * @example
-* const dispose = attachRouter(handlers, navigate);
+* const dispose = attachRouter(handlers, navigate, () => pushingOwnUrl);
 */
-function attachRouter(handlers, navigate) {
+function attachRouter(handlers, navigate, isOwnPush) {
 	const navigation = getNavigation();
-	return navigation ? attachNavigationApi(navigation, handlers, navigate) : attachHistoryFallback(handlers, navigate);
+	return navigation ? attachNavigationApi(navigation, handlers, navigate, isOwnPush) : attachHistoryFallback(handlers, navigate);
 }
 //#endregion
 //#region src/plugins/spa/state.ts
@@ -3861,6 +3866,7 @@ function createSpaKernel(state, config, emit, deps) {
 	let progress;
 	let pendingScrollToTop = true;
 	let pendingTransition = resolveTransition(resolved.defaultTransition);
+	let pushingOwnUrl = false;
 	/**
 	* Resolve a {@link TransitionMode} into the runtime {@link SwapTransition} the swap
 	* consumes: `"none"` ⇒ disabled; `"crossfade"` ⇒ enabled, no named types (default root
@@ -4173,8 +4179,9 @@ function createSpaKernel(state, config, emit, deps) {
 	* Navigation API commits the address bar before the interceptor calls {@link navigate}; a
 	* programmatic call does NOT, so it must commit the URL itself first — otherwise the content
 	* swaps but the address bar (and the back button / refresh / deep link) stays on the old URL.
-	* `history.pushState` updates the URL WITHOUT firing a `navigate` event, so it can't
-	* double-trigger the interceptor. The current scroll is saved first so a later back restores it.
+	* 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.
 	*
 	* @param path - The destination path (pathname + optional search).
 	* @param scroll - The optional per-call scroll override.
@@ -4185,7 +4192,12 @@ function createSpaKernel(state, config, emit, deps) {
 		if (typeof document === "undefined") return;
 		if (path !== currentLocationUrl()) {
 			saveScrollPosition(currentLocationUrl());
-			history.pushState({}, "", path);
+			pushingOwnUrl = true;
+			try {
+				history.pushState({}, "", path);
+			} finally {
+				pushingOwnUrl = false;
+			}
 		}
 		navigate(path, true, void 0, scroll).catch(() => {});
 	};
@@ -4214,7 +4226,7 @@ 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);
+			state.destroyRouter = attachRouter(handlers, navigate, () => 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);

package/dist/index.cjs

@@ -2357,10 +2357,11 @@ const CSS_EXTERNAL_FONT_GLOBS = [
 * @param options.naming.chunk - Naming template for lazy split chunks.
 * @param options.naming.asset - Naming template for additional emitted assets.
 * @param options.external - Import/url() globs left unresolved in the output.
+* @param options.define - Global names replaced with constant expressions.
 * @returns The structural build result.
 * @example
 * ```ts
-* await defaultRunner({ entrypoints: ["a.css"], outdir: "dist", minify: true, splitting: true, target: "browser", naming: FINGERPRINT_NAMING, external: [] });
+* await defaultRunner({ entrypoints: ["a.css"], outdir: "dist", minify: true, splitting: true, target: "browser", naming: FINGERPRINT_NAMING, external: [], define: {} });
 * ```
 */
 async function defaultRunner(options) {
@@ -2372,6 +2373,33 @@ async function defaultRunner(options) {
 	return bun.build(options);
 }
 /**
+* The bundle-time constants for the `build.env` names. Each name becomes `process.env.<NAME>` and
+* `import.meta.env.<NAME>`, and the whole `import.meta.env` object is set too, because
+* `browserEnv()` spreads it. The value is the build process's own variable, or `""` when unset.
+* With `minify`, a branch on an unset flag is removed together with the dynamic `import()` chunk
+* it guards, so developer-only code never ships in a build without the flag.
+*
+* @param names - The `build.env` names.
+* @param source - Where the values come from; the build process's environment by default.
+* @returns The `define` map for `Bun.build`; empty without names.
+* @example
+* ```ts
+* envDefines(["IS_DEVELOPMENT"], { IS_DEVELOPMENT: "true" });
+* // { "process.env.IS_DEVELOPMENT": "\"true\"", "import.meta.env.IS_DEVELOPMENT": "\"true\"",
+* //   "import.meta.env": "{\"IS_DEVELOPMENT\":\"true\"}" }
+* ```
+*/
+function envDefines(names, source = process.env) {
+	if (names.length === 0) return {};
+	const values = Object.fromEntries(names.map((name) => [name, source[name] ?? ""]));
+	const define = { "import.meta.env": JSON.stringify(values) };
+	for (const [name, value] of Object.entries(values)) {
+		define[`process.env.${name}`] = JSON.stringify(value);
+		define[`import.meta.env.${name}`] = JSON.stringify(value);
+	}
+	return define;
+}
+/**
 * Resolve the first existing entry file from a candidate list (project-relative).
 *
 * @param candidates - Ordered candidate paths to probe.
@@ -2440,12 +2468,13 @@ function normalizeAssetPath(absolutePath, outDir) {
 * @param outDir - The publish root; stored asset paths are made relative to it.
 * @param outdir - The bundler output directory (`<outDir>/assets`).
 * @param minify - Whether to minify.
+* @param define - Global names replaced with constant expressions.
 * @example
 * ```ts
-* await runOne(ctx, runner, "css", ["a.css"], "dist", true);
+* await runOne(ctx, runner, "css", ["a.css"], "dist", true, {});
 * ```
 */
-async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
+async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify, define) {
 	if (entrypoints.length === 0) return;
 	const result = await runner({
 		entrypoints,
@@ -2454,7 +2483,8 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
 		splitting: true,
 		target: "browser",
 		naming: FINGERPRINT_NAMING,
-		external: kind === "css" ? [...CSS_EXTERNAL_FONT_GLOBS] : []
+		external: kind === "css" ? [...CSS_EXTERNAL_FONT_GLOBS] : [],
+		define
 	});
 	if (!result.success) throw new Error(`[web] build.bundle ${kind} build failed`);
 	const hashed = {};
@@ -2489,10 +2519,11 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
 async function bundle(ctx, options = {}) {
 	const runner = options.runner ?? defaultRunner;
 	const { minify, outDir } = ctx.config;
+	const define = envDefines(ctx.config.env ?? []);
 	const assetsDir = node_path$1.default.join(outDir, "assets");
 	const cssEntrypoints = options.cssEntrypoints ?? resolveEntrypoints(CSS_ENTRY_CANDIDATES);
 	const jsEntrypoints = options.jsEntrypoints ?? resolveJsEntrypoints(ctx);
-	await Promise.all([runOne(ctx, runner, "css", cssEntrypoints, outDir, assetsDir, minify), runOne(ctx, runner, "js", jsEntrypoints, outDir, assetsDir, minify)]);
+	await Promise.all([runOne(ctx, runner, "css", cssEntrypoints, outDir, assetsDir, minify, define), runOne(ctx, runner, "js", jsEntrypoints, outDir, assetsDir, minify, define)]);
 }
 //#endregion
 //#region src/plugins/build/phases/asset-tags.ts
@@ -5821,6 +5852,22 @@ function validateFonts(og) {
 	if (isMissingFontDir(og.fontDir)) throw new Error(`${ERROR_PREFIX$7}.ogImage: fontDir "${og.fontDir}" does not exist — provide a directory with at least one font.`);
 	if (!(0, node_fs.readdirSync)(og.fontDir).some((name) => FONT_EXTENSIONS.some((extension) => name.endsWith(extension)))) throw new Error(`${ERROR_PREFIX$7}.ogImage: fontDir "${og.fontDir}" contains no .ttf/.otf/.woff font files.`);
 }
+/** An environment variable name: letters, digits and `_`, not starting with a digit. */
+const ENV_NAME = /^[A-Z_a-z]\w*$/;
+/**
+* Whether a `build.env` value lists environment variable names.
+*
+* @param value - The configured `build.env`.
+* @returns True for an array of valid names.
+* @example
+* ```ts
+* isEnvNameList(["IS_DEVELOPMENT"]); // true
+* isEnvNameList(["process.env.X"]); // false
+* ```
+*/
+function isEnvNameList(value) {
+	return Array.isArray(value) && value.every((name) => typeof name === "string" && ENV_NAME.test(name));
+}
 /**
 * Validates `build` config synchronously in `onInit` (return value discarded).
 * Throws an actionable `[web] build.<field>` error when `outDir` is empty, or
@@ -5837,6 +5884,7 @@ function validateConfig$2(config) {
 	if (config.publicDir !== void 0 && typeof config.publicDir !== "string") throw new Error(`${ERROR_PREFIX$7}.publicDir: must be a string when set.`);
 	if (config.template !== void 0 && typeof config.template !== "string") throw new Error(`${ERROR_PREFIX$7}.template: must be a string path when set.`);
 	if (config.clientEntry !== void 0 && typeof config.clientEntry !== "string") throw new Error(`${ERROR_PREFIX$7}.clientEntry: must be a string path when set.`);
+	if (config.env !== void 0 && !isEnvNameList(config.env)) throw new Error(`${ERROR_PREFIX$7}.env: must list environment variable names.\n  Use names like "IS_DEVELOPMENT".`);
 	if (config.ogImage) validateFonts(config.ogImage);
 }
 //#endregion
@@ -10691,11 +10739,13 @@ function attachHistoryFallback(handlers, navigate = (pathname, _scrollToTop, sig
 * @param navigation - The Navigation API object to attach the listener to.
 * @param handlers - The navigation lifecycle callbacks.
 * @param navigate - The navigation strategy (defaults to HTML-over-fetch via `performNavigation`).
+* @param isOwnPush - True while the kernel's programmatic navigation runs its own
+*   `history.pushState`: the `navigate` event it fires is left alone, the kernel runs it once.
 * @returns A teardown that removes the `navigate` listener.
 * @example
 * const dispose = attachNavigationApi(navigation, handlers);
 */
-function attachNavigationApi(navigation, handlers, navigate = (pathname, _scrollToTop, signal) => performNavigation(pathname, handlers, signal)) {
+function attachNavigationApi(navigation, handlers, navigate = (pathname, _scrollToTop, signal) => performNavigation(pathname, handlers, signal), isOwnPush = () => false) {
 	/**
 	* Handle a `navigate` event: classify, then intercept with fetch-and-swap.
 	*
@@ -10704,6 +10754,7 @@ function attachNavigationApi(navigation, handlers, navigate = (pathname, _scroll
 	* navigation.addEventListener("navigate", onNavigate);
 	*/
 	const onNavigate = (navEvent) => {
+		if (isOwnPush()) return;
 		const url = new URL(navEvent.destination.url);
 		if (!navEvent.canIntercept || navEvent.hashChange || navEvent.downloadRequest) return;
 		if (!isInternalLink(url)) return;
@@ -10736,13 +10787,15 @@ function attachNavigationApi(navigation, handlers, navigate = (pathname, _scroll
 *
 * @param handlers - The navigation lifecycle callbacks the kernel supplies.
 * @param navigate - The navigation strategy (defaults to HTML-over-fetch via `performNavigation`).
+* @param isOwnPush - True while the kernel runs its own `history.pushState` (Navigation API path
+*   only; the History fallback never sees an event for it).
 * @returns A teardown removing all attached listeners.
 * @example
-* const dispose = attachRouter(handlers, navigate);
+* const dispose = attachRouter(handlers, navigate, () => pushingOwnUrl);
 */
-function attachRouter(handlers, navigate) {
+function attachRouter(handlers, navigate, isOwnPush) {
 	const navigation = getNavigation();
-	return navigation ? attachNavigationApi(navigation, handlers, navigate) : attachHistoryFallback(handlers, navigate);
+	return navigation ? attachNavigationApi(navigation, handlers, navigate, isOwnPush) : attachHistoryFallback(handlers, navigate);
 }
 //#endregion
 //#region src/plugins/spa/state.ts
@@ -10907,6 +10960,7 @@ function createSpaKernel(state, config, emit, deps) {
 	let progress;
 	let pendingScrollToTop = true;
 	let pendingTransition = resolveTransition(resolved.defaultTransition);
+	let pushingOwnUrl = false;
 	/**
 	* Resolve a {@link TransitionMode} into the runtime {@link SwapTransition} the swap
 	* consumes: `"none"` ⇒ disabled; `"crossfade"` ⇒ enabled, no named types (default root
@@ -11219,8 +11273,9 @@ function createSpaKernel(state, config, emit, deps) {
 	* Navigation API commits the address bar before the interceptor calls {@link navigate}; a
 	* programmatic call does NOT, so it must commit the URL itself first — otherwise the content
 	* swaps but the address bar (and the back button / refresh / deep link) stays on the old URL.
-	* `history.pushState` updates the URL WITHOUT firing a `navigate` event, so it can't
-	* double-trigger the interceptor. The current scroll is saved first so a later back restores it.
+	* 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.
 	*
 	* @param path - The destination path (pathname + optional search).
 	* @param scroll - The optional per-call scroll override.
@@ -11231,7 +11286,12 @@ function createSpaKernel(state, config, emit, deps) {
 		if (typeof document === "undefined") return;
 		if (path !== currentLocationUrl()) {
 			saveScrollPosition(currentLocationUrl());
-			history.pushState({}, "", path);
+			pushingOwnUrl = true;
+			try {
+				history.pushState({}, "", path);
+			} finally {
+				pushingOwnUrl = false;
+			}
 		}
 		navigate(path, true, void 0, scroll).catch(() => {});
 	};
@@ -11260,7 +11320,7 @@ 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);
+			state.destroyRouter = attachRouter(handlers, navigate, () => 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);

package/dist/index.d.cts

@@ -1715,6 +1715,13 @@ type Config$3 = {
   }; /** Emit per-path i18n bare-path redirect HTML pages. Default `false`. */
   localeRedirects?: boolean; /** Authoritative client bundle entry path (overrides the conventional scan). */
   clientEntry?: string;
+  /**
+   * Environment variable names the client bundle reads, e.g. `["IS_DEVELOPMENT", "IS_LOCAL"]`.
+   * Each becomes a constant under `process.env.<NAME>` and `import.meta.env.<NAME>`: the value
+   * the build process has, or `""` when unset. With `minify`, a branch on an unset flag is dropped
+   * together with the dynamic `import()` chunk it guards. Default: none.
+   */
+  env?: readonly string[];
   /**
    * Path to a custom HTML document shell, giving the app full control over the
    * scaffold (charset, viewport, `<html lang>`, body attributes, wrapper markup).

package/dist/index.d.mts

@@ -1713,6 +1713,13 @@ type Config$3 = {
   }; /** Emit per-path i18n bare-path redirect HTML pages. Default `false`. */
   localeRedirects?: boolean; /** Authoritative client bundle entry path (overrides the conventional scan). */
   clientEntry?: string;
+  /**
+   * Environment variable names the client bundle reads, e.g. `["IS_DEVELOPMENT", "IS_LOCAL"]`.
+   * Each becomes a constant under `process.env.<NAME>` and `import.meta.env.<NAME>`: the value
+   * the build process has, or `""` when unset. With `minify`, a branch on an unset flag is dropped
+   * together with the dynamic `import()` chunk it guards. Default: none.
+   */
+  env?: readonly string[];
   /**
    * Path to a custom HTML document shell, giving the app full control over the
    * scaffold (charset, viewport, `<html lang>`, body attributes, wrapper markup).

package/dist/index.mjs

@@ -2313,10 +2313,11 @@ const CSS_EXTERNAL_FONT_GLOBS = [
 * @param options.naming.chunk - Naming template for lazy split chunks.
 * @param options.naming.asset - Naming template for additional emitted assets.
 * @param options.external - Import/url() globs left unresolved in the output.
+* @param options.define - Global names replaced with constant expressions.
 * @returns The structural build result.
 * @example
 * ```ts
-* await defaultRunner({ entrypoints: ["a.css"], outdir: "dist", minify: true, splitting: true, target: "browser", naming: FINGERPRINT_NAMING, external: [] });
+* await defaultRunner({ entrypoints: ["a.css"], outdir: "dist", minify: true, splitting: true, target: "browser", naming: FINGERPRINT_NAMING, external: [], define: {} });
 * ```
 */
 async function defaultRunner(options) {
@@ -2328,6 +2329,33 @@ async function defaultRunner(options) {
 	return bun.build(options);
 }
 /**
+* The bundle-time constants for the `build.env` names. Each name becomes `process.env.<NAME>` and
+* `import.meta.env.<NAME>`, and the whole `import.meta.env` object is set too, because
+* `browserEnv()` spreads it. The value is the build process's own variable, or `""` when unset.
+* With `minify`, a branch on an unset flag is removed together with the dynamic `import()` chunk
+* it guards, so developer-only code never ships in a build without the flag.
+*
+* @param names - The `build.env` names.
+* @param source - Where the values come from; the build process's environment by default.
+* @returns The `define` map for `Bun.build`; empty without names.
+* @example
+* ```ts
+* envDefines(["IS_DEVELOPMENT"], { IS_DEVELOPMENT: "true" });
+* // { "process.env.IS_DEVELOPMENT": "\"true\"", "import.meta.env.IS_DEVELOPMENT": "\"true\"",
+* //   "import.meta.env": "{\"IS_DEVELOPMENT\":\"true\"}" }
+* ```
+*/
+function envDefines(names, source = process.env) {
+	if (names.length === 0) return {};
+	const values = Object.fromEntries(names.map((name) => [name, source[name] ?? ""]));
+	const define = { "import.meta.env": JSON.stringify(values) };
+	for (const [name, value] of Object.entries(values)) {
+		define[`process.env.${name}`] = JSON.stringify(value);
+		define[`import.meta.env.${name}`] = JSON.stringify(value);
+	}
+	return define;
+}
+/**
 * Resolve the first existing entry file from a candidate list (project-relative).
 *
 * @param candidates - Ordered candidate paths to probe.
@@ -2396,12 +2424,13 @@ function normalizeAssetPath(absolutePath, outDir) {
 * @param outDir - The publish root; stored asset paths are made relative to it.
 * @param outdir - The bundler output directory (`<outDir>/assets`).
 * @param minify - Whether to minify.
+* @param define - Global names replaced with constant expressions.
 * @example
 * ```ts
-* await runOne(ctx, runner, "css", ["a.css"], "dist", true);
+* await runOne(ctx, runner, "css", ["a.css"], "dist", true, {});
 * ```
 */
-async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
+async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify, define) {
 	if (entrypoints.length === 0) return;
 	const result = await runner({
 		entrypoints,
@@ -2410,7 +2439,8 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
 		splitting: true,
 		target: "browser",
 		naming: FINGERPRINT_NAMING,
-		external: kind === "css" ? [...CSS_EXTERNAL_FONT_GLOBS] : []
+		external: kind === "css" ? [...CSS_EXTERNAL_FONT_GLOBS] : [],
+		define
 	});
 	if (!result.success) throw new Error(`[web] build.bundle ${kind} build failed`);
 	const hashed = {};
@@ -2445,10 +2475,11 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
 async function bundle(ctx, options = {}) {
 	const runner = options.runner ?? defaultRunner;
 	const { minify, outDir } = ctx.config;
+	const define = envDefines(ctx.config.env ?? []);
 	const assetsDir = path.join(outDir, "assets");
 	const cssEntrypoints = options.cssEntrypoints ?? resolveEntrypoints(CSS_ENTRY_CANDIDATES);
 	const jsEntrypoints = options.jsEntrypoints ?? resolveJsEntrypoints(ctx);
-	await Promise.all([runOne(ctx, runner, "css", cssEntrypoints, outDir, assetsDir, minify), runOne(ctx, runner, "js", jsEntrypoints, outDir, assetsDir, minify)]);
+	await Promise.all([runOne(ctx, runner, "css", cssEntrypoints, outDir, assetsDir, minify, define), runOne(ctx, runner, "js", jsEntrypoints, outDir, assetsDir, minify, define)]);
 }
 //#endregion
 //#region src/plugins/build/phases/asset-tags.ts
@@ -5777,6 +5808,22 @@ function validateFonts(og) {
 	if (isMissingFontDir(og.fontDir)) throw new Error(`${ERROR_PREFIX$7}.ogImage: fontDir "${og.fontDir}" does not exist — provide a directory with at least one font.`);
 	if (!readdirSync(og.fontDir).some((name) => FONT_EXTENSIONS.some((extension) => name.endsWith(extension)))) throw new Error(`${ERROR_PREFIX$7}.ogImage: fontDir "${og.fontDir}" contains no .ttf/.otf/.woff font files.`);
 }
+/** An environment variable name: letters, digits and `_`, not starting with a digit. */
+const ENV_NAME = /^[A-Z_a-z]\w*$/;
+/**
+* Whether a `build.env` value lists environment variable names.
+*
+* @param value - The configured `build.env`.
+* @returns True for an array of valid names.
+* @example
+* ```ts
+* isEnvNameList(["IS_DEVELOPMENT"]); // true
+* isEnvNameList(["process.env.X"]); // false
+* ```
+*/
+function isEnvNameList(value) {
+	return Array.isArray(value) && value.every((name) => typeof name === "string" && ENV_NAME.test(name));
+}
 /**
 * Validates `build` config synchronously in `onInit` (return value discarded).
 * Throws an actionable `[web] build.<field>` error when `outDir` is empty, or
@@ -5793,6 +5840,7 @@ function validateConfig$2(config) {
 	if (config.publicDir !== void 0 && typeof config.publicDir !== "string") throw new Error(`${ERROR_PREFIX$7}.publicDir: must be a string when set.`);
 	if (config.template !== void 0 && typeof config.template !== "string") throw new Error(`${ERROR_PREFIX$7}.template: must be a string path when set.`);
 	if (config.clientEntry !== void 0 && typeof config.clientEntry !== "string") throw new Error(`${ERROR_PREFIX$7}.clientEntry: must be a string path when set.`);
+	if (config.env !== void 0 && !isEnvNameList(config.env)) throw new Error(`${ERROR_PREFIX$7}.env: must list environment variable names.\n  Use names like "IS_DEVELOPMENT".`);
 	if (config.ogImage) validateFonts(config.ogImage);
 }
 //#endregion
@@ -10647,11 +10695,13 @@ function attachHistoryFallback(handlers, navigate = (pathname, _scrollToTop, sig
 * @param navigation - The Navigation API object to attach the listener to.
 * @param handlers - The navigation lifecycle callbacks.
 * @param navigate - The navigation strategy (defaults to HTML-over-fetch via `performNavigation`).
+* @param isOwnPush - True while the kernel's programmatic navigation runs its own
+*   `history.pushState`: the `navigate` event it fires is left alone, the kernel runs it once.
 * @returns A teardown that removes the `navigate` listener.
 * @example
 * const dispose = attachNavigationApi(navigation, handlers);
 */
-function attachNavigationApi(navigation, handlers, navigate = (pathname, _scrollToTop, signal) => performNavigation(pathname, handlers, signal)) {
+function attachNavigationApi(navigation, handlers, navigate = (pathname, _scrollToTop, signal) => performNavigation(pathname, handlers, signal), isOwnPush = () => false) {
 	/**
 	* Handle a `navigate` event: classify, then intercept with fetch-and-swap.
 	*
@@ -10660,6 +10710,7 @@ function attachNavigationApi(navigation, handlers, navigate = (pathname, _scroll
 	* navigation.addEventListener("navigate", onNavigate);
 	*/
 	const onNavigate = (navEvent) => {
+		if (isOwnPush()) return;
 		const url = new URL(navEvent.destination.url);
 		if (!navEvent.canIntercept || navEvent.hashChange || navEvent.downloadRequest) return;
 		if (!isInternalLink(url)) return;
@@ -10692,13 +10743,15 @@ function attachNavigationApi(navigation, handlers, navigate = (pathname, _scroll
 *
 * @param handlers - The navigation lifecycle callbacks the kernel supplies.
 * @param navigate - The navigation strategy (defaults to HTML-over-fetch via `performNavigation`).
+* @param isOwnPush - True while the kernel runs its own `history.pushState` (Navigation API path
+*   only; the History fallback never sees an event for it).
 * @returns A teardown removing all attached listeners.
 * @example
-* const dispose = attachRouter(handlers, navigate);
+* const dispose = attachRouter(handlers, navigate, () => pushingOwnUrl);
 */
-function attachRouter(handlers, navigate) {
+function attachRouter(handlers, navigate, isOwnPush) {
 	const navigation = getNavigation();
-	return navigation ? attachNavigationApi(navigation, handlers, navigate) : attachHistoryFallback(handlers, navigate);
+	return navigation ? attachNavigationApi(navigation, handlers, navigate, isOwnPush) : attachHistoryFallback(handlers, navigate);
 }
 //#endregion
 //#region src/plugins/spa/state.ts
@@ -10863,6 +10916,7 @@ function createSpaKernel(state, config, emit, deps) {
 	let progress;
 	let pendingScrollToTop = true;
 	let pendingTransition = resolveTransition(resolved.defaultTransition);
+	let pushingOwnUrl = false;
 	/**
 	* Resolve a {@link TransitionMode} into the runtime {@link SwapTransition} the swap
 	* consumes: `"none"` ⇒ disabled; `"crossfade"` ⇒ enabled, no named types (default root
@@ -11175,8 +11229,9 @@ function createSpaKernel(state, config, emit, deps) {
 	* Navigation API commits the address bar before the interceptor calls {@link navigate}; a
 	* programmatic call does NOT, so it must commit the URL itself first — otherwise the content
 	* swaps but the address bar (and the back button / refresh / deep link) stays on the old URL.
-	* `history.pushState` updates the URL WITHOUT firing a `navigate` event, so it can't
-	* double-trigger the interceptor. The current scroll is saved first so a later back restores it.
+	* 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.
 	*
 	* @param path - The destination path (pathname + optional search).
 	* @param scroll - The optional per-call scroll override.
@@ -11187,7 +11242,12 @@ function createSpaKernel(state, config, emit, deps) {
 		if (typeof document === "undefined") return;
 		if (path !== currentLocationUrl()) {
 			saveScrollPosition(currentLocationUrl());
-			history.pushState({}, "", path);
+			pushingOwnUrl = true;
+			try {
+				history.pushState({}, "", path);
+			} finally {
+				pushingOwnUrl = false;
+			}
 		}
 		navigate(path, true, void 0, scroll).catch(() => {});
 	};
@@ -11216,7 +11276,7 @@ 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);
+			state.destroyRouter = attachRouter(handlers, navigate, () => 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);

package/package.json

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