@moku-labs/web 2.1.1 → 2.2.1

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.
@@ -3507,6 +3518,7 @@ function runSwap(doSwap, transition, beforeCapture) {
 	}
 	else result = docWithVt.startViewTransition(doSwap);
 	Promise.resolve(result?.finished).then(clearMarker).catch(clearMarker);
+	Promise.resolve(result?.ready).catch(() => {});
 }
 /**
 * Replace the `swapSelector` region of the live document with the matching
@@ -4232,6 +4244,23 @@ function createSpaKernel(state, config, emit, deps) {
 			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;
+			state.destroyRouter?.();
+			state.destroyRouter = null;
+			location.assign(url);
+		},
+		/**
 		* Scan the swap region and mount islands for matching elements.
 		*
 		* @example
@@ -4286,6 +4315,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
@@ -4318,6 +4390,7 @@ function disposeSpa() {
 	} finally {
 		teardown = void 0;
 		logRef = void 0;
+		boundNavigators = void 0;
 	}
 }
 //#endregion
@@ -4692,6 +4765,7 @@ const spaPlugin = createPlugin$1("spa", {
 	onStart(ctx) {
 		captureTeardown(ctx);
 		ctx.state.kernel?.boot();
+		if (ctx.state.kernel) bindKernelNavigators(ctx.state.kernel);
 	},
 	onStop: disposeSpa
 });
@@ -5335,4 +5409,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.
@@ -10213,6 +10224,7 @@ function runSwap(doSwap, transition, beforeCapture) {
 	}
 	else result = docWithVt.startViewTransition(doSwap);
 	Promise.resolve(result?.finished).then(clearMarker).catch(clearMarker);
+	Promise.resolve(result?.ready).catch(() => {});
 }
 /**
 * Replace the `swapSelector` region of the live document with the matching
@@ -10938,6 +10950,23 @@ function createSpaKernel(state, config, emit, deps) {
 			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;
+			state.destroyRouter?.();
+			state.destroyRouter = null;
+			location.assign(url);
+		},
+		/**
 		* Scan the swap region and mount islands for matching elements.
 		*
 		* @example
@@ -10992,6 +11021,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
@@ -11024,6 +11096,7 @@ function disposeSpa() {
 	} finally {
 		teardown = void 0;
 		logRef = void 0;
+		boundNavigators = void 0;
 	}
 }
 //#endregion
@@ -11398,6 +11471,7 @@ const spaPlugin = createPlugin$1("spa", {
 	onStart(ctx) {
 		captureTeardown(ctx);
 		ctx.state.kernel?.boot();
+		if (ctx.state.kernel) bindKernelNavigators(ctx.state.kernel);
 	},
 	onStop: disposeSpa
 });
@@ -13710,6 +13784,7 @@ Object.defineProperty(exports, "envPlugin", {
 });
 exports.feedLink = feedLink;
 exports.fileSystemContent = fileSystemContent;
+exports.hardNavigate = hardNavigate;
 exports.headPlugin = headPlugin;
 exports.hreflang = hreflang;
 exports.i18nPlugin = i18nPlugin;
@@ -13722,6 +13797,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.
@@ -10200,6 +10211,7 @@ function runSwap(doSwap, transition, beforeCapture) {
 	}
 	else result = docWithVt.startViewTransition(doSwap);
 	Promise.resolve(result?.finished).then(clearMarker).catch(clearMarker);
+	Promise.resolve(result?.ready).catch(() => {});
 }
 /**
 * Replace the `swapSelector` region of the live document with the matching
@@ -10925,6 +10937,23 @@ function createSpaKernel(state, config, emit, deps) {
 			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;
+			state.destroyRouter?.();
+			state.destroyRouter = null;
+			location.assign(url);
+		},
+		/**
 		* Scan the swap region and mount islands for matching elements.
 		*
 		* @example
@@ -10979,6 +11008,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
@@ -11011,6 +11083,7 @@ function disposeSpa() {
 	} finally {
 		teardown = void 0;
 		logRef = void 0;
+		boundNavigators = void 0;
 	}
 }
 //#endregion
@@ -11385,6 +11458,7 @@ const spaPlugin = createPlugin$1("spa", {
 	onStart(ctx) {
 		captureTeardown(ctx);
 		ctx.state.kernel?.boot();
+		if (ctx.state.kernel) bindKernelNavigators(ctx.state.kernel);
 	},
 	onStop: disposeSpa
 });
@@ -13608,4 +13682,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.1"
+  "version": "2.2.1"
 }