@ilha/router 0.4.3 → 0.5.1

package/README.md

@@ -300,7 +300,7 @@ pageRouter.mount("#app", { hydrate: true, registry });
 
 #### `.hydrate(registry, options?)` — browser only
 
-Convenience method that combines `.prime()`, `ilha.mount()`, and `.mount()` into a single call. **This is the recommended client entry point.**
+Convenience method that combines `.prime()`, `ilha.mount()`, and `.mount()` into a single call. **This is the recommended client entry point for SPA apps.**
 
 ```ts
 pageRouter.hydrate(registry);
@@ -318,6 +318,23 @@ Returns an `unmount` function that tears down all listeners and hydrated islands
 
 ---
 
+#### `.hydrateStatic(registry, options?)` — browser only
+
+The lightest client entry point. Calls `prime()` then `ilha.mount()` — no route view is mounted, no navigation handler is installed, and no route graph is touched. Use this in `static` mode where each page is a self-contained pre-rendered HTML file.
+
+```ts
+pageRouter.hydrateStatic(registry);
+
+// With options:
+pageRouter.hydrateStatic(registry, {
+  root: document.getElementById("app"), // defaults to document.body
+});
+```
+
+Internal `<a href>` links navigate via normal browser page loads. Only interactive islands in the current page are activated.
+
+---
+
 #### `.attachLoader(pattern, loader)` — runtime
 
 Attaches or replaces a loader on an already-registered route pattern. No-op if the pattern was never registered via `.route()`. Used by the `ilha:loaders` virtual module to wire server-only loaders onto the client-safe `pageRouter` at SSR time.
@@ -658,18 +675,21 @@ interface NavigateOptions {
 interface MountOptions {
   hydrate?: boolean;
   registry?: Record<string, Island>;
+  interceptLinks?: boolean; // default: true
 }
 
 interface HydrateOptions {
   root?: Element;
   target?: string | Element;
+  interceptLinks?: boolean; // default: true
 }
 
 type HistoryMode = "history" | "hash";
-type RouterMode = "spa" | "mpa";
+type RouterMode = "spa" | "static";
 
 interface RouterOptions {
-  mode?: RouterMode; // default: "spa"
+  mode?: RouterMode; // "spa" | "static", default: "spa"
+  interceptLinks?: boolean; // default: true — only meaningful in spa mode
 }
 
 // Helper — returns fn as-is with LayoutHandler type enforced
@@ -932,20 +952,14 @@ pageRouter.hydrate(registry);
 pages({
   dir: "src/pages", // pages directory (default: "src/pages")
   generated: ".ilha/routes.ts", // generated file output (default: ".ilha/routes.ts")
-  mode: "spa", // "spa" | "mpa" (default: "spa")
+  mode: "spa", // "spa" | "static" (default: "spa")
+  interceptLinks: true, // only meaningful in spa mode (default: true)
 });
 ```
 
-Use `mode: "mpa"` when you want filesystem-routed pages to behave like a multi-page app: the current page can still be SSR-rendered and hydrated, but in-app links are not intercepted by the router, so navigation is handled by the browser as a full document request.
-
-```ts
-// vite.config.ts
-import { pages } from "@ilha/router/vite";
-
-export default defineConfig({
-  plugins: [pages({ mode: "mpa" })],
-});
-```
+- **`mode: "spa"`** — full client route graph, SSR/hydration, and client-side navigation.
+- **`mode: "spa", interceptLinks: false`** — full route graph and SSR/hydration, but internal links perform full document navigations.
+- **`mode: "static"`** — island registry only; no route graph bundled. Each pre-rendered page hydrates its own islands via `pageRouter.hydrateStatic(registry)`.
 
 The plugin regenerates the routes file only when content actually changes — avoiding unnecessary HMR invalidations. Structural changes (file add/remove, `+layout.ts`/`+error.ts` edits, or changes to loader exports) trigger full HMR reloads.
 

package/dist/{index-CJT0h4u4.d.ts → index-DZA_1KrG.d.ts}

@@ -92,24 +92,43 @@ declare function defineLayout(layout: LayoutHandler): LayoutHandler;
 interface NavigateOptions {
   replace?: boolean;
 }
-type RouterMode = "spa" | "mpa";
+type RouterMode = "spa" | "static";
 interface RouterOptions {
   /**
-   * Client navigation mode. `spa` intercepts in-app links and renders routes
-   * in-place. `mpa` leaves links to the browser, so each page navigation is a
-   * full document request while still allowing hydration of the current route.
+   * Client navigation mode.
+   * - `spa` — full route graph, SSR/hydration, client-side navigation.
+   * - `static` — no route graph bundled; hydrate islands on the current
+   *   pre-rendered page only.
    * Default: `spa`.
    */
   mode?: RouterMode;
+  /**
+   * When `true` (default), internal `<a>` clicks are intercepted and handled
+   * by the client router. Set to `false` for MPA-style behavior where links
+   * perform full document navigations.
+   * Only meaningful in `spa` mode; ignored in `static` mode.
+   * Default: `true`.
+   */
+  interceptLinks?: boolean;
 }
 interface HydratableRenderOptions extends Partial<Omit<HydratableOptions, "name">> {}
 interface HydrateOptions {
   root?: Element;
   target?: string | Element;
+  /**
+   * When `true` (default), internal `<a>` clicks are intercepted for
+   * client-side navigation. Set to `false` for MPA-style full-page navigations.
+   */
+  interceptLinks?: boolean;
 }
 interface MountOptions {
   hydrate?: boolean;
   registry?: Record<string, Island<any, any>>;
+  /**
+   * When `true` (default), internal `<a>` clicks are intercepted for
+   * client-side navigation. Set to `false` for MPA-style full-page navigations.
+   */
+  interceptLinks?: boolean;
 }
 /** Response envelope returned by `renderResponse` — lets the host app handle redirects. */
 type RenderResponse = {
@@ -189,6 +208,14 @@ interface RouterBuilder {
    * @returns Cleanup function
    */
   hydrate(registry: Record<string, Island<any, any>>, options?: HydrateOptions): () => void;
+  /**
+   * Hydrate islands on the current pre-rendered page without mounting a route
+   * view or enabling client navigation. Intended for `static` mode: each page
+   * is a self-contained HTML file; only interactive islands need activation.
+   */
+  hydrateStatic(registry: Record<string, Island<any, any>>, options?: {
+    root?: Element;
+  }): () => void;
 }
 /** Path of the loader endpoint served by the Vite plugin / production adapter. */
 declare const LOADER_ENDPOINT = "/__ilha/loader";

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { A as loader, B as useRoute, C as RouterView, D as enableLinkInterception, E as defineLayout, F as routeHash, G as setHistoryMode, H as wrapLayout, I as routeParams, L as routePath, M as prefetch, N as prime, O as error, P as redirect, R as routeSearch, S as RouterOptions, T as composeLoaders, U as HistoryMode, V as wrapError, W as getHistoryMode, _ as RouteRecord, a as InferLoader, b as RouterLink, c as LinkInterceptionOptions, d as LoaderError, f as MergeLoaders, g as RenderResponse, h as Redirect, i as HydrateOptions, j as navigate, k as isActive, l as Loader, m as NavigateOptions, n as ErrorHandler, o as LOADER_ENDPOINT, p as MountOptions, r as HydratableRenderOptions, s as LayoutHandler, t as AppError, u as LoaderContext, v as RouteSnapshot, w as _default, x as RouterMode, y as RouterBuilder, z as router } from "./index-CJT0h4u4.js";
+import { A as loader, B as useRoute, C as RouterView, D as enableLinkInterception, E as defineLayout, F as routeHash, G as setHistoryMode, H as wrapLayout, I as routeParams, L as routePath, M as prefetch, N as prime, O as error, P as redirect, R as routeSearch, S as RouterOptions, T as composeLoaders, U as HistoryMode, V as wrapError, W as getHistoryMode, _ as RouteRecord, a as InferLoader, b as RouterLink, c as LinkInterceptionOptions, d as LoaderError, f as MergeLoaders, g as RenderResponse, h as Redirect, i as HydrateOptions, j as navigate, k as isActive, l as Loader, m as NavigateOptions, n as ErrorHandler, o as LOADER_ENDPOINT, p as MountOptions, r as HydratableRenderOptions, s as LayoutHandler, t as AppError, u as LoaderContext, v as RouteSnapshot, w as _default, x as RouterMode, y as RouterBuilder, z as router } from "./index-DZA_1KrG.js";
 export { AppError, ErrorHandler, HistoryMode, HydratableRenderOptions, HydrateOptions, InferLoader, LOADER_ENDPOINT, LayoutHandler, LinkInterceptionOptions, Loader, LoaderContext, LoaderError, MergeLoaders, MountOptions, NavigateOptions, Redirect, RenderResponse, RouteRecord, RouteSnapshot, RouterBuilder, RouterLink, RouterMode, RouterOptions, RouterView, composeLoaders, _default as default, defineLayout, enableLinkInterception, error, getHistoryMode, isActive, loader, navigate, prefetch, prime, redirect, routeHash, routeParams, routePath, routeSearch, router, setHistoryMode, useRoute, wrapError, wrapLayout };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { C as wrapError, E as setHistoryMode, S as useRoute, T as getHistoryMode, _ as routeParams, a as RouterView, b as router, c as enableLinkInterception, d as loader, f as navigate, g as routeHash, h as redirect, i as RouterLink, l as error, m as prime, n as LoaderError, o as composeLoaders, p as prefetch, r as Redirect, s as defineLayout, t as LOADER_ENDPOINT, u as isActive, v as routePath, w as wrapLayout, x as src_default, y as routeSearch } from "./src-BqAWh426.js";
+import { C as wrapError, E as setHistoryMode, S as useRoute, T as getHistoryMode, _ as routeParams, a as RouterView, b as router, c as enableLinkInterception, d as loader, f as navigate, g as routeHash, h as redirect, i as RouterLink, l as error, m as prime, n as LoaderError, o as composeLoaders, p as prefetch, r as Redirect, s as defineLayout, t as LOADER_ENDPOINT, u as isActive, v as routePath, w as wrapLayout, x as src_default, y as routeSearch } from "./src-BP38YTMC.js";
 export { LOADER_ENDPOINT, LoaderError, Redirect, RouterLink, RouterView, composeLoaders, src_default as default, defineLayout, enableLinkInterception, error, getHistoryMode, isActive, loader, navigate, prefetch, prime, redirect, routeHash, routeParams, routePath, routeSearch, router, setHistoryMode, useRoute, wrapError, wrapLayout };

package/dist/plugin-BizQQLsn.d.ts

@@ -0,0 +1,28 @@
+import * as _$unplugin from "unplugin";
+
+//#region src/codegen.d.ts
+type PagesMode = "spa" | "static";
+//#endregion
+//#region src/plugin.d.ts
+interface IlhaPagesOptions {
+  /** Directory containing page files. Default: `src/pages` */
+  dir?: string;
+  /** Output path for the generated routes + registry file. Default: `.ilha/routes.ts` */
+  generated?: string;
+  /**
+   * File-system router navigation mode.
+   * - `spa` — full client route graph with SSR/hydration and client navigation.
+   * - `static` — island registry only; no route graph bundled into the client.
+   * Default: `spa`.
+   */
+  mode?: PagesMode;
+  /**
+   * When `false`, internal `<a>` clicks are not intercepted — browser performs
+   * full document navigations. Only meaningful in `spa` mode.
+   * Default: `true`.
+   */
+  interceptLinks?: boolean;
+}
+declare const ilhaPages: _$unplugin.UnpluginInstance<IlhaPagesOptions | undefined, boolean>;
+//#endregion
+export { ilhaPages as n, IlhaPagesOptions as t };

package/dist/{plugin-BMk5Ey9X.js → plugin-C-TVH3XD.js}

@@ -140,13 +140,15 @@ function validateEntries(entries, pagesDir) {
 }
 async function generate(pagesDir, outFile, options = {}) {
 	const mode = options.mode ?? "spa";
+	const interceptLinks = options.interceptLinks;
+	const isStatic = mode === "static";
 	const entries = sortEntries(await scanPages(pagesDir));
 	validateEntries(entries, pagesDir);
 	const rel = (abs) => {
 		const r = toPosix(relative(dirname(outFile), abs));
 		return r.startsWith(".") ? r : `./${r}`;
 	};
-	const imports = [`import { router, wrapLayout, wrapError } from "@ilha/router";`, `import type { Island } from "ilha";`];
+	const imports = isStatic ? [`import type { Island } from "ilha";`] : [`import { router, wrapLayout, wrapError } from "@ilha/router";`, `import type { Island } from "ilha";`];
 	const wrappedIslandLines = [];
 	const registryLines = [];
 	const routeLines = [];
@@ -154,19 +156,26 @@ async function generate(pagesDir, outFile, options = {}) {
 	for (const [i, entry] of entries.entries()) {
 		const pageId = `_page${i}`;
 		imports.push(`import { default as ${pageId} } from ${JSON.stringify(clientImport(entry.file))};`);
-		for (const [j, l] of entry.layouts.entries()) imports.push(`import { default as _layout${i}_${j} } from ${JSON.stringify(clientImport(l))};`);
-		for (const [j, e] of entry.errors.entries()) imports.push(`import { default as _error${i}_${j} } from ${JSON.stringify(clientImport(e))};`);
+		if (!isStatic) {
+			for (const [j, l] of entry.layouts.entries()) imports.push(`import { default as _layout${i}_${j} } from ${JSON.stringify(clientImport(l))};`);
+			for (const [j, e] of entry.errors.entries()) imports.push(`import { default as _error${i}_${j} } from ${JSON.stringify(clientImport(e))};`);
+		}
 		let expr = pageId;
-		for (let j = entry.errors.length - 1; j >= 0; j--) expr = `wrapError(_error${i}_${j}, ${expr})`;
-		for (let j = entry.layouts.length - 1; j >= 0; j--) expr = `wrapLayout(_layout${i}_${j}, ${expr})`;
+		if (!isStatic) {
+			for (let j = entry.errors.length - 1; j >= 0; j--) expr = `wrapError(_error${i}_${j}, ${expr})`;
+			for (let j = entry.layouts.length - 1; j >= 0; j--) expr = `wrapLayout(_layout${i}_${j}, ${expr})`;
+		}
 		const wrappedId = `_wrapped${i}`;
 		wrappedIslandLines.push(`const ${wrappedId} = ${expr};`);
 		registryLines.push(`  ${JSON.stringify(entry.name)}: ${wrappedId}` + (i < entries.length - 1 ? "," : ""));
-		routeLines.push(`  .route(${JSON.stringify(entry.pattern)}, ${wrappedId})` + (entry.hasLoader || entry.loaderLayouts.length > 0 ? `.markLoader(${JSON.stringify(entry.pattern)})` : ""));
+		if (!isStatic) routeLines.push(`  .route(${JSON.stringify(entry.pattern)}, ${wrappedId})` + (entry.hasLoader || entry.loaderLayouts.length > 0 ? `.markLoader(${JSON.stringify(entry.pattern)})` : ""));
 	}
-	const code = [
+	const code = isStatic ? [
 		`// @generated by @ilha/router — do not edit`,
+		`// static mode: no route graph, no client navigation.`,
+		`// Import registry to hydrate islands; use pageRouter.hydrateStatic(registry).`,
 		``,
+		`import { router as _router } from "@ilha/router";`,
 		...imports,
 		``,
 		...wrappedIslandLines,
@@ -175,12 +184,28 @@ async function generate(pagesDir, outFile, options = {}) {
 		...registryLines,
 		`};`,
 		``,
-		`export const pageRouter = router(${mode === "mpa" ? `{ mode: "mpa" }` : ""})`,
+		`export const pageRouter = _router({ mode: "static" });`
+	].join("\n") : [
+		`// @generated by @ilha/router — do not edit`,
+		``,
+		...imports,
+		``,
+		...wrappedIslandLines,
+		``,
+		`export const registry: Record<string, Island<any, any>> = {`,
+		...registryLines,
+		`};`,
+		``,
+		`export const pageRouter = router(${interceptLinks === false ? `{ interceptLinks: false }` : ""})`,
 		...routeLines,
 		`  ;`
 	].join("\n");
 	await mkdir(dirname(outFile), { recursive: true });
 	const routesChanged = await writeIfChanged(outFile, code);
+	if (isStatic) {
+		if (routesChanged) await generateTypes(outFile);
+		return;
+	}
 	const loadersFile = join(dirname(outFile), "loaders.ts");
 	const loadersChanged = await writeIfChanged(loadersFile, buildLoadersFile(entries, loadersFile, outFile));
 	if (routesChanged || loadersChanged) await generateTypes(outFile);
@@ -286,7 +311,10 @@ function createPagesPluginState(options) {
 	};
 	const regen = async () => {
 		try {
-			await generate(pagesDir, outFile, { mode: options.mode });
+			await generate(pagesDir, outFile, {
+				mode: options.mode,
+				interceptLinks: options.interceptLinks
+			});
 		} catch (e) {
 			console.error("[ilha:pages] codegen failed:", e);
 		}

package/dist/rolldown.d.ts

@@ -1,5 +1,5 @@
-import { H as wrapLayout, V as wrapError, n as ErrorHandler, s as LayoutHandler, t as AppError, v as RouteSnapshot } from "./index-CJT0h4u4.js";
-import { n as ilhaPages, t as IlhaPagesOptions } from "./plugin-Diq1AxSa.js";
+import { H as wrapLayout, V as wrapError, n as ErrorHandler, s as LayoutHandler, t as AppError, v as RouteSnapshot } from "./index-DZA_1KrG.js";
+import { n as ilhaPages, t as IlhaPagesOptions } from "./plugin-BizQQLsn.js";
 import * as _$unplugin from "unplugin";
 
 //#region src/rolldown.d.ts

package/dist/rolldown.js

@@ -1,5 +1,5 @@
-import { C as wrapError, w as wrapLayout } from "./src-BqAWh426.js";
-import { t as ilhaPages } from "./plugin-BMk5Ey9X.js";
+import { C as wrapError, w as wrapLayout } from "./src-BP38YTMC.js";
+import { t as ilhaPages } from "./plugin-C-TVH3XD.js";
 //#region src/rolldown.ts
 /** Rolldown plugin — use via `@ilha/router/rolldown`. */
 function pages(options = {}) {

package/dist/rspack.d.ts

@@ -1,5 +1,5 @@
-import { H as wrapLayout, V as wrapError, n as ErrorHandler, s as LayoutHandler, t as AppError, v as RouteSnapshot } from "./index-CJT0h4u4.js";
-import { n as ilhaPages, t as IlhaPagesOptions } from "./plugin-Diq1AxSa.js";
+import { H as wrapLayout, V as wrapError, n as ErrorHandler, s as LayoutHandler, t as AppError, v as RouteSnapshot } from "./index-DZA_1KrG.js";
+import { n as ilhaPages, t as IlhaPagesOptions } from "./plugin-BizQQLsn.js";
 import * as _$unplugin from "unplugin";
 
 //#region src/rspack.d.ts

package/dist/rspack.js

@@ -1,5 +1,5 @@
-import { C as wrapError, w as wrapLayout } from "./src-BqAWh426.js";
-import { t as ilhaPages } from "./plugin-BMk5Ey9X.js";
+import { C as wrapError, w as wrapLayout } from "./src-BP38YTMC.js";
+import { t as ilhaPages } from "./plugin-C-TVH3XD.js";
 //#region src/rspack.ts
 /** Rspack plugin — use via `@ilha/router/rspack`. */
 function pages(options = {}) {

package/dist/{src-BqAWh426.js → src-BP38YTMC.js}

@@ -579,6 +579,7 @@ async function executeLoader(loader, url, params, request, signal) {
 }
 function router(options = {}) {
 	const mode = options.mode ?? "spa";
+	const defaultInterceptLinks = options.interceptLinks !== false;
 	_records = [];
 	_rou3 = createRouter();
 	_islandToPattern = /* @__PURE__ */ new Map();
@@ -634,7 +635,14 @@ function router(options = {}) {
 			return _records.map((record) => ({ ...record }));
 		},
 		prime,
-		mount(target, { hydrate = false, registry } = {}) {
+		hydrateStatic(registry, options = {}) {
+			if (!isBrowser) return () => {};
+			const root = options.root ?? document.body;
+			prime();
+			const { unmount } = mount(registry, { root });
+			return unmount;
+		},
+		mount(target, { hydrate = false, registry, interceptLinks: mountInterceptLinks } = {}) {
 			if (!isBrowser) {
 				console.warn("[ilha-router] mount() called in a non-browser environment");
 				return () => {};
@@ -645,9 +653,13 @@ function router(options = {}) {
 				return () => {};
 			}
 			syncRouteFromLocation();
+			if (mode === "static") {
+				console.warn("[ilha-router] router.mount() called in static mode. Use router.hydrateStatic(registry) instead.");
+				return () => {};
+			}
 			const popHandler = () => syncRouteFromLocation();
 			_navChangeCleanup = getAdapter().onChange(popHandler);
-			_linkCleanup = mode === "spa" ? enableLinkInterception(document) : null;
+			_linkCleanup = mountInterceptLinks ?? defaultInterceptLinks ? enableLinkInterception(document) : null;
 			let unmountView = null;
 			let navAbort = null;
 			if (hydrate) {
@@ -841,7 +853,8 @@ function router(options = {}) {
 			const { unmount } = mount(registry, { root });
 			const unmountRouter = this.mount(target, {
 				hydrate: true,
-				registry
+				registry,
+				interceptLinks: options.interceptLinks
 			});
 			return () => {
 				unmount();

package/dist/vite.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="node" />
-import { H as wrapLayout, V as wrapError, n as ErrorHandler, s as LayoutHandler, t as AppError, v as RouteSnapshot } from "./index-CJT0h4u4.js";
-import { n as ilhaPages, t as IlhaPagesOptions } from "./plugin-Diq1AxSa.js";
+import { H as wrapLayout, V as wrapError, n as ErrorHandler, s as LayoutHandler, t as AppError, v as RouteSnapshot } from "./index-DZA_1KrG.js";
+import { n as ilhaPages, t as IlhaPagesOptions } from "./plugin-BizQQLsn.js";
 import * as fs from "node:fs";
 import * as http from "node:http";
 import { Agent, ClientRequest, ClientRequestArgs, OutgoingHttpHeaders } from "node:http";

package/dist/vite.js

@@ -1,5 +1,5 @@
-import { C as wrapError, w as wrapLayout } from "./src-BqAWh426.js";
-import { t as ilhaPages } from "./plugin-BMk5Ey9X.js";
+import { C as wrapError, w as wrapLayout } from "./src-BP38YTMC.js";
+import { t as ilhaPages } from "./plugin-C-TVH3XD.js";
 //#region src/vite.ts
 /** Vite plugin — use via `@ilha/router/vite`. */
 function pages(options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ilha/router",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "description": "A tiny SPA router for Ilha",
   "license": "MIT",
   "author": "Ryuz <ryuzer@proton.me>",
@@ -38,7 +38,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "ilha": "0.7.0",
+    "ilha": "0.7.1",
     "rou3": "0.8.1",
     "unplugin": "3.0.0"
   },

package/dist/plugin-Diq1AxSa.d.ts

@@ -1,21 +0,0 @@
-import * as _$unplugin from "unplugin";
-
-//#region src/codegen.d.ts
-type PagesMode = "spa" | "mpa";
-//#endregion
-//#region src/plugin.d.ts
-interface IlhaPagesOptions {
-  /** Directory containing page files. Default: `src/pages` */
-  dir?: string;
-  /** Output path for the generated routes + registry file. Default: `.ilha/routes.ts` */
-  generated?: string;
-  /**
-   * File-system router navigation mode. `spa` intercepts in-app links and
-   * renders routes client-side; `mpa` leaves links to the browser for full
-   * document navigations. Default: `spa`.
-   */
-  mode?: PagesMode;
-}
-declare const ilhaPages: _$unplugin.UnpluginInstance<IlhaPagesOptions | undefined, boolean>;
-//#endregion
-export { ilhaPages as n, IlhaPagesOptions as t };