@moku-labs/web 2.1.0 → 2.2.0

package/README.md

@@ -141,6 +141,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 }`.
+- **`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
 createIsland("issue", {

package/dist/browser.d.mts

@@ -1395,6 +1395,16 @@ interface SpaKernel {
    * kernel.processNav("/about");
    */
   processNav(path: string, options?: NavigateOptions): void;
+  /**
+   * Cross a boundary the SPA cannot swap (different layout / auth split) with a REAL
+   * full-page load — detaches the interceptor first so the navigation isn't caught.
+   *
+   * @param url - The destination URL.
+   * @returns void
+   * @example
+   * kernel.hardNavigate("/signin/");
+   */
+  hardNavigate(url: string): void;
   /**
    * Query the swap region and mount islands for matching elements.
    *
@@ -1456,6 +1466,17 @@ type SpaApi = {
    * app.spa.navigate("/about");
    */
   navigate(path: string, options?: NavigateOptions): void;
+  /**
+   * Cross a boundary the SPA cannot swap (a different layout, the auth split) with a REAL
+   * full-page navigation. Detaches the SPA interceptor first, so the navigation is a true
+   * document load (rendering the destination's own layout) rather than an intercepted swap.
+   *
+   * @param url - The destination URL (internal path or absolute).
+   * @returns void
+   * @example
+   * app.spa.hardNavigate("/signin/"); // sign-out / 401: leave the app chrome for the auth split
+   */
+  hardNavigate(url: string): void;
   /**
    * Read the current resolved URL.
    *
@@ -1827,6 +1848,31 @@ declare function createIsland<S extends object = object, A = unknown>(name: stri
  */
 declare const lazyEmbed: IslandDef;
 //#endregion
+//#region src/plugins/spa/lifecycle.d.ts
+/**
+ * Navigate the booted SPA to an internal path — the SAME swap pipeline as a link click,
+ * `ctx.navigate`, or `app.spa.navigate`, for module-scope callers with no `app`/island `ctx`.
+ * No-op before `app.start()`. Build `path` from the route map's `urls`, never a literal.
+ *
+ * @param path - The internal destination path (e.g. `urls.toUrl("board", { id })`).
+ * @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve" }`).
+ * @example
+ * import { navigate } from "@moku-labs/web/browser";
+ * navigate(urls.toUrl("issue", { id, issueId }));
+ */
+declare function navigate(path: string, options?: NavigateOptions): void;
+/**
+ * Cross a boundary the SPA cannot swap (a different layout, the auth split) with a REAL
+ * full-page load — detaches the SPA interceptor first so the navigation isn't caught and
+ * converted to a swap. For module-scope callers with no `app`/island `ctx`. No-op before boot.
+ *
+ * @param url - The destination URL (internal path or absolute).
+ * @example
+ * import { hardNavigate } from "@moku-labs/web/browser";
+ * hardNavigate(urls.toUrl("signin", {})); // sign-out / 401: leave the app chrome for the auth split
+ */
+declare function hardNavigate(url: string): void;
+//#endregion
 //#region src/plugins/spa/index.d.ts
 /**
  * SPA plugin — progressive client-side navigation layered over the static site:
@@ -2614,4 +2660,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  */
 declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$5, Events, 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>]>>;
 //#endregion
-export { type Channel, type ChannelKeepAlive, type ChannelOptions, type ChannelReconnect, types_d_exports as Content, types_d_exports$1 as Data, type Env, types_d_exports$2 as Head, type Log, types_d_exports$3 as Router, types_d_exports$4 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createChannel, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { type Channel, type ChannelKeepAlive, type ChannelOptions, type ChannelReconnect, types_d_exports as Content, types_d_exports$1 as Data, type Env, types_d_exports$2 as Head, type Log, types_d_exports$3 as Router, types_d_exports$4 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createChannel, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, hardNavigate, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, navigate, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };

package/dist/browser.mjs

@@ -2259,6 +2259,17 @@ function createApi(ctx) {
 			ctx.state.kernel?.processNav(path, options);
 		},
 		/**
+		* Cross a boundary the SPA cannot swap (different layout / auth split) with a REAL
+		* full-page load — detaches the interceptor first so the navigation isn't intercepted.
+		*
+		* @param url - The destination URL.
+		* @example
+		* app.spa.hardNavigate("/signin/");
+		*/
+		hardNavigate(url) {
+			ctx.state.kernel?.hardNavigate(url);
+		},
+		/**
 		* Read the current resolved URL.
 		*
 		* @returns The current pathname + search.
@@ -4156,6 +4167,27 @@ function createSpaKernel(state, config, emit, deps) {
 		if (signal?.aborted) return;
 		await performNavigation(pathname, handlers, signal);
 	};
+	/**
+	* Programmatic navigation entry (`app.spa.navigate` / `ctx.navigate`). A link click or the
+	* 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.
+	*
+	* @param path - The destination path (pathname + optional search).
+	* @param scroll - The optional per-call scroll override.
+	* @example
+	* navigateProgrammatic("/board/abc/issue/1", "preserve");
+	*/
+	const navigateProgrammatic = (path, scroll) => {
+		if (typeof document === "undefined") return;
+		if (path !== currentLocationUrl()) {
+			saveScrollPosition(currentLocationUrl());
+			history.pushState({}, "", path);
+		}
+		navigate(path, true, void 0, scroll).catch(() => {});
+	};
 	return {
 		/**
 		* Register config islands and seed currentUrl from the document.
@@ -4167,8 +4199,7 @@ function createSpaKernel(state, config, emit, deps) {
 			for (const island of resolved.islands) registerIsland(state, island);
 			state.currentUrl = currentLocationUrl();
 			state.navigate = (path, options) => {
-				if (typeof document === "undefined") return;
-				navigate(path, true, void 0, options?.scroll).catch(() => {});
+				navigateProgrammatic(path, options?.scroll);
 			};
 		},
 		/**
@@ -4209,8 +4240,24 @@ function createSpaKernel(state, config, emit, deps) {
 		* kernel.processNav("/about");
 		*/
 		processNav(path, options) {
+			navigateProgrammatic(path, options?.scroll);
+		},
+		/**
+		* Cross a boundary the SPA cannot swap (a different layout, the auth split) with a REAL
+		* full-page navigation. The click / Navigation-API interceptor catches even
+		* `location.assign`, converting it to a region swap — so this DETACHES that interceptor
+		* first (the same teardown `dispose` runs) and only THEN assigns, guaranteeing a true
+		* document load that renders the destination's own layout. No-op headless.
+		*
+		* @param url - The destination URL (internal path or absolute).
+		* @example
+		* kernel.hardNavigate("/signin/");
+		*/
+		hardNavigate(url) {
 			if (typeof document === "undefined") return;
-			navigate(path, true, void 0, options?.scroll).catch(() => {});
+			state.destroyRouter?.();
+			state.destroyRouter = null;
+			location.assign(url);
 		},
 		/**
 		* Scan the swap region and mount islands for matching elements.
@@ -4267,6 +4314,49 @@ function initSpa(ctx) {
 let teardown;
 /** Captured log ref — onStop has no `ctx.log` (spec/08 §4). */
 let logRef;
+/** The booted app's navigators, or undefined before boot / after stop (single-app-per-document). */
+let boundNavigators;
+/**
+* Bind the running app's navigators from its kernel — called by the plugin's `onStart` after
+* `kernel.boot()`, so the module-level {@link navigate}/{@link hardNavigate} delegate to it.
+*
+* @param kernel - The booted spa kernel.
+* @example
+* bindKernelNavigators(ctx.state.kernel);
+*/
+function bindKernelNavigators(kernel) {
+	boundNavigators = {
+		navigate: (path, options) => kernel.processNav(path, options),
+		hardNavigate: (url) => kernel.hardNavigate(url)
+	};
+}
+/**
+* Navigate the booted SPA to an internal path — the SAME swap pipeline as a link click,
+* `ctx.navigate`, or `app.spa.navigate`, for module-scope callers with no `app`/island `ctx`.
+* No-op before `app.start()`. Build `path` from the route map's `urls`, never a literal.
+*
+* @param path - The internal destination path (e.g. `urls.toUrl("board", { id })`).
+* @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve" }`).
+* @example
+* import { navigate } from "@moku-labs/web/browser";
+* navigate(urls.toUrl("issue", { id, issueId }));
+*/
+function navigate(path, options) {
+	boundNavigators?.navigate(path, options);
+}
+/**
+* Cross a boundary the SPA cannot swap (a different layout, the auth split) with a REAL
+* full-page load — detaches the SPA interceptor first so the navigation isn't caught and
+* converted to a swap. For module-scope callers with no `app`/island `ctx`. No-op before boot.
+*
+* @param url - The destination URL (internal path or absolute).
+* @example
+* import { hardNavigate } from "@moku-labs/web/browser";
+* hardNavigate(urls.toUrl("signin", {})); // sign-out / 401: leave the app chrome for the auth split
+*/
+function hardNavigate(url) {
+	boundNavigators?.hardNavigate(url);
+}
 /**
 * Capture the teardown + log handles during `onStart` (no-op without a DOM —
 * the SSR/build guard, so onStop has nothing to release). The kernel built in
@@ -4299,6 +4389,7 @@ function disposeSpa() {
 	} finally {
 		teardown = void 0;
 		logRef = void 0;
+		boundNavigators = void 0;
 	}
 }
 //#endregion
@@ -4673,6 +4764,7 @@ const spaPlugin = createPlugin$1("spa", {
 	onStart(ctx) {
 		captureTeardown(ctx);
 		ctx.state.kernel?.boot();
+		if (ctx.state.kernel) bindKernelNavigators(ctx.state.kernel);
 	},
 	onStop: disposeSpa
 });
@@ -5316,4 +5408,4 @@ const createApp = core.createApp;
 */
 const createPlugin = core.createPlugin;
 //#endregion
-export { types_exports as Content, types_exports$1 as Data, types_exports$2 as Head, types_exports$3 as Router, types_exports$4 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createChannel, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_exports as Content, types_exports$1 as Data, types_exports$2 as Head, types_exports$3 as Router, types_exports$4 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createChannel, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, hardNavigate, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, navigate, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };

package/dist/index.cjs

@@ -9217,6 +9217,17 @@ function createApi(ctx) {
 			ctx.state.kernel?.processNav(path, options);
 		},
 		/**
+		* Cross a boundary the SPA cannot swap (different layout / auth split) with a REAL
+		* full-page load — detaches the interceptor first so the navigation isn't intercepted.
+		*
+		* @param url - The destination URL.
+		* @example
+		* app.spa.hardNavigate("/signin/");
+		*/
+		hardNavigate(url) {
+			ctx.state.kernel?.hardNavigate(url);
+		},
+		/**
 		* Read the current resolved URL.
 		*
 		* @returns The current pathname + search.
@@ -10862,6 +10873,27 @@ function createSpaKernel(state, config, emit, deps) {
 		if (signal?.aborted) return;
 		await performNavigation(pathname, handlers, signal);
 	};
+	/**
+	* Programmatic navigation entry (`app.spa.navigate` / `ctx.navigate`). A link click or the
+	* 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.
+	*
+	* @param path - The destination path (pathname + optional search).
+	* @param scroll - The optional per-call scroll override.
+	* @example
+	* navigateProgrammatic("/board/abc/issue/1", "preserve");
+	*/
+	const navigateProgrammatic = (path, scroll) => {
+		if (typeof document === "undefined") return;
+		if (path !== currentLocationUrl()) {
+			saveScrollPosition(currentLocationUrl());
+			history.pushState({}, "", path);
+		}
+		navigate(path, true, void 0, scroll).catch(() => {});
+	};
 	return {
 		/**
 		* Register config islands and seed currentUrl from the document.
@@ -10873,8 +10905,7 @@ function createSpaKernel(state, config, emit, deps) {
 			for (const island of resolved.islands) registerIsland(state, island);
 			state.currentUrl = currentLocationUrl();
 			state.navigate = (path, options) => {
-				if (typeof document === "undefined") return;
-				navigate(path, true, void 0, options?.scroll).catch(() => {});
+				navigateProgrammatic(path, options?.scroll);
 			};
 		},
 		/**
@@ -10915,8 +10946,24 @@ function createSpaKernel(state, config, emit, deps) {
 		* kernel.processNav("/about");
 		*/
 		processNav(path, options) {
+			navigateProgrammatic(path, options?.scroll);
+		},
+		/**
+		* Cross a boundary the SPA cannot swap (a different layout, the auth split) with a REAL
+		* full-page navigation. The click / Navigation-API interceptor catches even
+		* `location.assign`, converting it to a region swap — so this DETACHES that interceptor
+		* first (the same teardown `dispose` runs) and only THEN assigns, guaranteeing a true
+		* document load that renders the destination's own layout. No-op headless.
+		*
+		* @param url - The destination URL (internal path or absolute).
+		* @example
+		* kernel.hardNavigate("/signin/");
+		*/
+		hardNavigate(url) {
 			if (typeof document === "undefined") return;
-			navigate(path, true, void 0, options?.scroll).catch(() => {});
+			state.destroyRouter?.();
+			state.destroyRouter = null;
+			location.assign(url);
 		},
 		/**
 		* Scan the swap region and mount islands for matching elements.
@@ -10973,6 +11020,49 @@ function initSpa(ctx) {
 let teardown;
 /** Captured log ref — onStop has no `ctx.log` (spec/08 §4). */
 let logRef;
+/** The booted app's navigators, or undefined before boot / after stop (single-app-per-document). */
+let boundNavigators;
+/**
+* Bind the running app's navigators from its kernel — called by the plugin's `onStart` after
+* `kernel.boot()`, so the module-level {@link navigate}/{@link hardNavigate} delegate to it.
+*
+* @param kernel - The booted spa kernel.
+* @example
+* bindKernelNavigators(ctx.state.kernel);
+*/
+function bindKernelNavigators(kernel) {
+	boundNavigators = {
+		navigate: (path, options) => kernel.processNav(path, options),
+		hardNavigate: (url) => kernel.hardNavigate(url)
+	};
+}
+/**
+* Navigate the booted SPA to an internal path — the SAME swap pipeline as a link click,
+* `ctx.navigate`, or `app.spa.navigate`, for module-scope callers with no `app`/island `ctx`.
+* No-op before `app.start()`. Build `path` from the route map's `urls`, never a literal.
+*
+* @param path - The internal destination path (e.g. `urls.toUrl("board", { id })`).
+* @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve" }`).
+* @example
+* import { navigate } from "@moku-labs/web/browser";
+* navigate(urls.toUrl("issue", { id, issueId }));
+*/
+function navigate(path, options) {
+	boundNavigators?.navigate(path, options);
+}
+/**
+* Cross a boundary the SPA cannot swap (a different layout, the auth split) with a REAL
+* full-page load — detaches the SPA interceptor first so the navigation isn't caught and
+* converted to a swap. For module-scope callers with no `app`/island `ctx`. No-op before boot.
+*
+* @param url - The destination URL (internal path or absolute).
+* @example
+* import { hardNavigate } from "@moku-labs/web/browser";
+* hardNavigate(urls.toUrl("signin", {})); // sign-out / 401: leave the app chrome for the auth split
+*/
+function hardNavigate(url) {
+	boundNavigators?.hardNavigate(url);
+}
 /**
 * Capture the teardown + log handles during `onStart` (no-op without a DOM —
 * the SSR/build guard, so onStop has nothing to release). The kernel built in
@@ -11005,6 +11095,7 @@ function disposeSpa() {
 	} finally {
 		teardown = void 0;
 		logRef = void 0;
+		boundNavigators = void 0;
 	}
 }
 //#endregion
@@ -11379,6 +11470,7 @@ const spaPlugin = createPlugin$1("spa", {
 	onStart(ctx) {
 		captureTeardown(ctx);
 		ctx.state.kernel?.boot();
+		if (ctx.state.kernel) bindKernelNavigators(ctx.state.kernel);
 	},
 	onStop: disposeSpa
 });
@@ -13691,6 +13783,7 @@ Object.defineProperty(exports, "envPlugin", {
 });
 exports.feedLink = feedLink;
 exports.fileSystemContent = fileSystemContent;
+exports.hardNavigate = hardNavigate;
 exports.headPlugin = headPlugin;
 exports.hreflang = hreflang;
 exports.i18nPlugin = i18nPlugin;
@@ -13703,6 +13796,7 @@ Object.defineProperty(exports, "logPlugin", {
 	}
 });
 exports.meta = meta;
+exports.navigate = navigate;
 exports.og = og;
 Object.defineProperty(exports, "processEnv", {
 	enumerable: true,

package/dist/index.d.cts

@@ -1396,6 +1396,16 @@ interface SpaKernel {
    * kernel.processNav("/about");
    */
   processNav(path: string, options?: NavigateOptions): void;
+  /**
+   * Cross a boundary the SPA cannot swap (different layout / auth split) with a REAL
+   * full-page load — detaches the interceptor first so the navigation isn't caught.
+   *
+   * @param url - The destination URL.
+   * @returns void
+   * @example
+   * kernel.hardNavigate("/signin/");
+   */
+  hardNavigate(url: string): void;
   /**
    * Query the swap region and mount islands for matching elements.
    *
@@ -1457,6 +1467,17 @@ type SpaApi = {
    * app.spa.navigate("/about");
    */
   navigate(path: string, options?: NavigateOptions): void;
+  /**
+   * Cross a boundary the SPA cannot swap (a different layout, the auth split) with a REAL
+   * full-page navigation. Detaches the SPA interceptor first, so the navigation is a true
+   * document load (rendering the destination's own layout) rather than an intercepted swap.
+   *
+   * @param url - The destination URL (internal path or absolute).
+   * @returns void
+   * @example
+   * app.spa.hardNavigate("/signin/"); // sign-out / 401: leave the app chrome for the auth split
+   */
+  hardNavigate(url: string): void;
   /**
    * Read the current resolved URL.
    *
@@ -3747,6 +3768,31 @@ declare function createIsland<S extends object = object, A = unknown>(name: stri
  */
 declare const lazyEmbed: IslandDef;
 //#endregion
+//#region src/plugins/spa/lifecycle.d.ts
+/**
+ * Navigate the booted SPA to an internal path — the SAME swap pipeline as a link click,
+ * `ctx.navigate`, or `app.spa.navigate`, for module-scope callers with no `app`/island `ctx`.
+ * No-op before `app.start()`. Build `path` from the route map's `urls`, never a literal.
+ *
+ * @param path - The internal destination path (e.g. `urls.toUrl("board", { id })`).
+ * @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve" }`).
+ * @example
+ * import { navigate } from "@moku-labs/web/browser";
+ * navigate(urls.toUrl("issue", { id, issueId }));
+ */
+declare function navigate(path: string, options?: NavigateOptions): void;
+/**
+ * Cross a boundary the SPA cannot swap (a different layout, the auth split) with a REAL
+ * full-page load — detaches the SPA interceptor first so the navigation isn't caught and
+ * converted to a swap. For module-scope callers with no `app`/island `ctx`. No-op before boot.
+ *
+ * @param url - The destination URL (internal path or absolute).
+ * @example
+ * import { hardNavigate } from "@moku-labs/web/browser";
+ * hardNavigate(urls.toUrl("signin", {})); // sign-out / 401: leave the app chrome for the auth split
+ */
+declare function hardNavigate(url: string): void;
+//#endregion
 //#region src/plugins/spa/index.d.ts
 /**
  * SPA plugin — progressive client-side navigation layered over the static site:
@@ -3946,4 +3992,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  */
 declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$8, Events, 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>]>>;
 //#endregion
-export { types_d_exports as Build, type Channel, type ChannelKeepAlive, type ChannelOptions, type ChannelReconnect, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, type EmbedFacade, EmbedFacadeButton, type EmbedFacadeProps, type EmbedOptions, type Env, type GalleryComponent, type GalleryOptions, type GalleryProps, type GallerySlide, GalleryTrack, types_d_exports$5 as Head, type Log, types_d_exports$6 as Router, types_d_exports$7 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createChannel, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_d_exports as Build, type Channel, type ChannelKeepAlive, type ChannelOptions, type ChannelReconnect, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, type EmbedFacade, EmbedFacadeButton, type EmbedFacadeProps, type EmbedOptions, type Env, type GalleryComponent, type GalleryOptions, type GalleryProps, type GallerySlide, GalleryTrack, types_d_exports$5 as Head, type Log, types_d_exports$6 as Router, types_d_exports$7 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createChannel, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, hardNavigate, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, navigate, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };

package/dist/index.d.mts

@@ -1394,6 +1394,16 @@ interface SpaKernel {
    * kernel.processNav("/about");
    */
   processNav(path: string, options?: NavigateOptions): void;
+  /**
+   * Cross a boundary the SPA cannot swap (different layout / auth split) with a REAL
+   * full-page load — detaches the interceptor first so the navigation isn't caught.
+   *
+   * @param url - The destination URL.
+   * @returns void
+   * @example
+   * kernel.hardNavigate("/signin/");
+   */
+  hardNavigate(url: string): void;
   /**
    * Query the swap region and mount islands for matching elements.
    *
@@ -1455,6 +1465,17 @@ type SpaApi = {
    * app.spa.navigate("/about");
    */
   navigate(path: string, options?: NavigateOptions): void;
+  /**
+   * Cross a boundary the SPA cannot swap (a different layout, the auth split) with a REAL
+   * full-page navigation. Detaches the SPA interceptor first, so the navigation is a true
+   * document load (rendering the destination's own layout) rather than an intercepted swap.
+   *
+   * @param url - The destination URL (internal path or absolute).
+   * @returns void
+   * @example
+   * app.spa.hardNavigate("/signin/"); // sign-out / 401: leave the app chrome for the auth split
+   */
+  hardNavigate(url: string): void;
   /**
    * Read the current resolved URL.
    *
@@ -3745,6 +3766,31 @@ declare function createIsland<S extends object = object, A = unknown>(name: stri
  */
 declare const lazyEmbed: IslandDef;
 //#endregion
+//#region src/plugins/spa/lifecycle.d.ts
+/**
+ * Navigate the booted SPA to an internal path — the SAME swap pipeline as a link click,
+ * `ctx.navigate`, or `app.spa.navigate`, for module-scope callers with no `app`/island `ctx`.
+ * No-op before `app.start()`. Build `path` from the route map's `urls`, never a literal.
+ *
+ * @param path - The internal destination path (e.g. `urls.toUrl("board", { id })`).
+ * @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve" }`).
+ * @example
+ * import { navigate } from "@moku-labs/web/browser";
+ * navigate(urls.toUrl("issue", { id, issueId }));
+ */
+declare function navigate(path: string, options?: NavigateOptions): void;
+/**
+ * Cross a boundary the SPA cannot swap (a different layout, the auth split) with a REAL
+ * full-page load — detaches the SPA interceptor first so the navigation isn't caught and
+ * converted to a swap. For module-scope callers with no `app`/island `ctx`. No-op before boot.
+ *
+ * @param url - The destination URL (internal path or absolute).
+ * @example
+ * import { hardNavigate } from "@moku-labs/web/browser";
+ * hardNavigate(urls.toUrl("signin", {})); // sign-out / 401: leave the app chrome for the auth split
+ */
+declare function hardNavigate(url: string): void;
+//#endregion
 //#region src/plugins/spa/index.d.ts
 /**
  * SPA plugin — progressive client-side navigation layered over the static site:
@@ -3944,4 +3990,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  */
 declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$8, Events, 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>]>>;
 //#endregion
-export { types_d_exports as Build, type Channel, type ChannelKeepAlive, type ChannelOptions, type ChannelReconnect, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, type EmbedFacade, EmbedFacadeButton, type EmbedFacadeProps, type EmbedOptions, type Env, type GalleryComponent, type GalleryOptions, type GalleryProps, type GallerySlide, GalleryTrack, types_d_exports$5 as Head, type Log, types_d_exports$6 as Router, types_d_exports$7 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createChannel, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_d_exports as Build, type Channel, type ChannelKeepAlive, type ChannelOptions, type ChannelReconnect, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, type EmbedFacade, EmbedFacadeButton, type EmbedFacadeProps, type EmbedOptions, type Env, type GalleryComponent, type GalleryOptions, type GalleryProps, type GallerySlide, GalleryTrack, types_d_exports$5 as Head, type Log, types_d_exports$6 as Router, types_d_exports$7 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createChannel, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, hardNavigate, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, navigate, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };

package/dist/index.mjs

@@ -9204,6 +9204,17 @@ function createApi(ctx) {
 			ctx.state.kernel?.processNav(path, options);
 		},
 		/**
+		* Cross a boundary the SPA cannot swap (different layout / auth split) with a REAL
+		* full-page load — detaches the interceptor first so the navigation isn't intercepted.
+		*
+		* @param url - The destination URL.
+		* @example
+		* app.spa.hardNavigate("/signin/");
+		*/
+		hardNavigate(url) {
+			ctx.state.kernel?.hardNavigate(url);
+		},
+		/**
 		* Read the current resolved URL.
 		*
 		* @returns The current pathname + search.
@@ -10849,6 +10860,27 @@ function createSpaKernel(state, config, emit, deps) {
 		if (signal?.aborted) return;
 		await performNavigation(pathname, handlers, signal);
 	};
+	/**
+	* Programmatic navigation entry (`app.spa.navigate` / `ctx.navigate`). A link click or the
+	* 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.
+	*
+	* @param path - The destination path (pathname + optional search).
+	* @param scroll - The optional per-call scroll override.
+	* @example
+	* navigateProgrammatic("/board/abc/issue/1", "preserve");
+	*/
+	const navigateProgrammatic = (path, scroll) => {
+		if (typeof document === "undefined") return;
+		if (path !== currentLocationUrl()) {
+			saveScrollPosition(currentLocationUrl());
+			history.pushState({}, "", path);
+		}
+		navigate(path, true, void 0, scroll).catch(() => {});
+	};
 	return {
 		/**
 		* Register config islands and seed currentUrl from the document.
@@ -10860,8 +10892,7 @@ function createSpaKernel(state, config, emit, deps) {
 			for (const island of resolved.islands) registerIsland(state, island);
 			state.currentUrl = currentLocationUrl();
 			state.navigate = (path, options) => {
-				if (typeof document === "undefined") return;
-				navigate(path, true, void 0, options?.scroll).catch(() => {});
+				navigateProgrammatic(path, options?.scroll);
 			};
 		},
 		/**
@@ -10902,8 +10933,24 @@ function createSpaKernel(state, config, emit, deps) {
 		* kernel.processNav("/about");
 		*/
 		processNav(path, options) {
+			navigateProgrammatic(path, options?.scroll);
+		},
+		/**
+		* Cross a boundary the SPA cannot swap (a different layout, the auth split) with a REAL
+		* full-page navigation. The click / Navigation-API interceptor catches even
+		* `location.assign`, converting it to a region swap — so this DETACHES that interceptor
+		* first (the same teardown `dispose` runs) and only THEN assigns, guaranteeing a true
+		* document load that renders the destination's own layout. No-op headless.
+		*
+		* @param url - The destination URL (internal path or absolute).
+		* @example
+		* kernel.hardNavigate("/signin/");
+		*/
+		hardNavigate(url) {
 			if (typeof document === "undefined") return;
-			navigate(path, true, void 0, options?.scroll).catch(() => {});
+			state.destroyRouter?.();
+			state.destroyRouter = null;
+			location.assign(url);
 		},
 		/**
 		* Scan the swap region and mount islands for matching elements.
@@ -10960,6 +11007,49 @@ function initSpa(ctx) {
 let teardown;
 /** Captured log ref — onStop has no `ctx.log` (spec/08 §4). */
 let logRef;
+/** The booted app's navigators, or undefined before boot / after stop (single-app-per-document). */
+let boundNavigators;
+/**
+* Bind the running app's navigators from its kernel — called by the plugin's `onStart` after
+* `kernel.boot()`, so the module-level {@link navigate}/{@link hardNavigate} delegate to it.
+*
+* @param kernel - The booted spa kernel.
+* @example
+* bindKernelNavigators(ctx.state.kernel);
+*/
+function bindKernelNavigators(kernel) {
+	boundNavigators = {
+		navigate: (path, options) => kernel.processNav(path, options),
+		hardNavigate: (url) => kernel.hardNavigate(url)
+	};
+}
+/**
+* Navigate the booted SPA to an internal path — the SAME swap pipeline as a link click,
+* `ctx.navigate`, or `app.spa.navigate`, for module-scope callers with no `app`/island `ctx`.
+* No-op before `app.start()`. Build `path` from the route map's `urls`, never a literal.
+*
+* @param path - The internal destination path (e.g. `urls.toUrl("board", { id })`).
+* @param options - Optional per-navigation overrides (e.g. `{ scroll: "preserve" }`).
+* @example
+* import { navigate } from "@moku-labs/web/browser";
+* navigate(urls.toUrl("issue", { id, issueId }));
+*/
+function navigate(path, options) {
+	boundNavigators?.navigate(path, options);
+}
+/**
+* Cross a boundary the SPA cannot swap (a different layout, the auth split) with a REAL
+* full-page load — detaches the SPA interceptor first so the navigation isn't caught and
+* converted to a swap. For module-scope callers with no `app`/island `ctx`. No-op before boot.
+*
+* @param url - The destination URL (internal path or absolute).
+* @example
+* import { hardNavigate } from "@moku-labs/web/browser";
+* hardNavigate(urls.toUrl("signin", {})); // sign-out / 401: leave the app chrome for the auth split
+*/
+function hardNavigate(url) {
+	boundNavigators?.hardNavigate(url);
+}
 /**
 * Capture the teardown + log handles during `onStart` (no-op without a DOM —
 * the SSR/build guard, so onStop has nothing to release). The kernel built in
@@ -10992,6 +11082,7 @@ function disposeSpa() {
 	} finally {
 		teardown = void 0;
 		logRef = void 0;
+		boundNavigators = void 0;
 	}
 }
 //#endregion
@@ -11366,6 +11457,7 @@ const spaPlugin = createPlugin$1("spa", {
 	onStart(ctx) {
 		captureTeardown(ctx);
 		ctx.state.kernel?.boot();
+		if (ctx.state.kernel) bindKernelNavigators(ctx.state.kernel);
 	},
 	onStop: disposeSpa
 });
@@ -13589,4 +13681,4 @@ const createApp = core.createApp;
 */
 const createPlugin = core.createPlugin;
 //#endregion
-export { types_exports as Build, types_exports$1 as Cli, types_exports$2 as Content, types_exports$3 as Data, types_exports$4 as Deploy, EmbedFacadeButton, GalleryTrack, types_exports$5 as Head, types_exports$6 as Router, types_exports$7 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createChannel, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_exports as Build, types_exports$1 as Cli, types_exports$2 as Content, types_exports$3 as Data, types_exports$4 as Deploy, EmbedFacadeButton, GalleryTrack, types_exports$5 as Head, types_exports$6 as Router, types_exports$7 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createChannel, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, hardNavigate, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, navigate, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };

package/package.json

@@ -132,5 +132,5 @@
     "test:build-e2e": "bun test src/plugins/build/__tests__/e2e/",
     "test:coverage": "vitest run --project unit --project integration --coverage"
   },
-  "version": "2.1.0"
+  "version": "2.2.0"
 }