@ilha/router 0.8.13 → 0.9.1

package/dist/plugin.d.ts

@@ -8,7 +8,7 @@ export declare const RESOLVED_LOADERS = "\0ilha:loaders";
 export declare const RESOLVED_VIRTUAL_IDS: readonly ["\0ilha:pages/server", "\0ilha:pages/client", "\0ilha:loaders"];
 /** Query suffix used on page/layout imports in the client file. */
 export declare const CLIENT_QUERY = "?client";
-/** Query suffix that re-exports a page/layout's `clientLoad` for the browser bundle. */
+/** Query suffix that re-exports a page/layout's `load` (loader.client) for the browser bundle. */
 export declare const CLIENT_LOADER_QUERY = "?client-loader";
 export interface IlhaPagesOptions {
     /** Directory containing page files. Default: `src/pages` */
@@ -28,6 +28,14 @@ export interface IlhaPagesOptions {
      * Default: `true`.
      */
     interceptLinks?: boolean;
+    /**
+     * Guard consulted on every `/__ilha/frame` request before a render runs.
+     * Return a `Response` to reject; return nothing to allow. Island state is
+     * world-readable through frames unless gated — install a session check here
+     * when islands serve private data. Production equivalents register via
+     * `setFrameGuard()` from `@ilha/router/server-island-registry`.
+     */
+    frameGuard?: (request: Request) => Response | void | Promise<Response | void>;
     /**
      * Fail codegen on duplicate route patterns / registry name collisions
      * instead of warning. Recommended for CI/production builds. Default: `false`.

package/dist/request-scope-C4reU4v0.js

@@ -0,0 +1,34 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+//#region src/request-scope.ts
+/**
+* Request scope for server-owned island rendering.
+*
+* A `.server.tsx` island's render function always executes on the server —
+* page SSR through the router, or streamed frames through the plugin's
+* `/__ilha/frame` endpoint. Both seed this scope with the originating
+* `Request`, so render functions can read request data (URL, headers,
+* cookies) through `useContext().request` or a host integration such as Oxide's `useRequest()`.
+*
+* The storage lives on `globalThis` under `ilha.requestAls` so every module
+* copy (plugin bundle, SSR graph) shares one instance. The public accessor
+* is `useContext()` from the main `@ilha/router` entry, which reads the
+* storage without importing `node:async_hooks`; this node-only module is the
+* sole place that constructs it.
+*/
+const REQUEST_ALS_KEY = Symbol.for("ilha.requestAls");
+/** Installed by oxidejs when its module loads. Lets `useRequest()` resolve
+* inside island renders and frames, not just `/__oxide/action`. */
+const OXIDE_RUN_WITH_REQUEST = Symbol.for("oxidejs.runWithRequest");
+/** Run `fn` with `request` available to `useContext().request`. When oxidejs
+* is loaded, its action scope is entered too, so `useRequest()` works in
+* island renders and streamed frames. */
+function runWithIslandRequest(request, fn) {
+	const g = globalThis;
+	const als = g[REQUEST_ALS_KEY] ??= new AsyncLocalStorage();
+	const oxide = g[OXIDE_RUN_WITH_REQUEST];
+	return als.run(request, () => oxide ? oxide(request, fn) : fn());
+}
+
+//#endregion
+export { runWithIslandRequest as t };

package/dist/request-scope.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Request scope for server-owned island rendering.
+ *
+ * A `.server.tsx` island's render function always executes on the server —
+ * page SSR through the router, or streamed frames through the plugin's
+ * `/__ilha/frame` endpoint. Both seed this scope with the originating
+ * `Request`, so render functions can read request data (URL, headers,
+ * cookies) through `useContext().request` or a host integration such as Oxide's `useRequest()`.
+ *
+ * The storage lives on `globalThis` under `ilha.requestAls` so every module
+ * copy (plugin bundle, SSR graph) shares one instance. The public accessor
+ * is `useContext()` from the main `@ilha/router` entry, which reads the
+ * storage without importing `node:async_hooks`; this node-only module is the
+ * sole place that constructs it.
+ */
+import type { IslandContext } from "./index";
+export declare const REQUEST_ALS_KEY: unique symbol;
+/** Run `fn` with `request` available to `useContext().request`. When oxidejs
+ * is loaded, its action scope is entered too, so `useRequest()` works in
+ * island renders and streamed frames. */
+export declare function runWithIslandRequest<T>(request: Request, fn: () => T): T;
+export type { IslandContext };

package/dist/rolldown.d.ts

@@ -2,4 +2,5 @@ export type { LayoutHandler, ErrorHandler, RouteSnapshot, AppError } from "./ind
 export { ilhaPages, type IlhaPagesOptions } from "./plugin";
 import { type IlhaPagesOptions } from "./plugin";
 /** Rolldown plugin — use via `@ilha/router/rolldown`. */
-export declare function pages(options?: IlhaPagesOptions): import("unplugin").RolldownPlugin<any> | import("unplugin").RolldownPlugin<any>[];
+export declare function pages(options?: IlhaPagesOptions): import("rolldown").Plugin<any> | import("rolldown").Plugin<any>[];
+export default pages;

package/dist/rolldown.js

@@ -1,4 +1,4 @@
-import { t as ilhaPages } from "./plugin-DdquB3Nf.js";
+import { t as ilhaPages } from "./plugin-DogkskcY.js";
 
 //#region src/rolldown.ts
 /** Rolldown plugin — use via `@ilha/router/rolldown`. */
@@ -7,4 +7,4 @@ function pages(options = {}) {
 }
 
 //#endregion
-export { ilhaPages, pages };
+export { pages as default, pages, ilhaPages };

package/dist/rspack.d.ts

@@ -3,3 +3,4 @@ export { ilhaPages, type IlhaPagesOptions } from "./plugin";
 import { type IlhaPagesOptions } from "./plugin";
 /** Rspack plugin — use via `@ilha/router/rspack`. */
 export declare function pages(options?: IlhaPagesOptions): RspackPluginInstance;
+export default pages;

package/dist/rspack.js

@@ -1,4 +1,4 @@
-import { t as ilhaPages } from "./plugin-DdquB3Nf.js";
+import { t as ilhaPages } from "./plugin-DogkskcY.js";
 
 //#region src/rspack.ts
 /** Rspack plugin — use via `@ilha/router/rspack`. */
@@ -7,4 +7,4 @@ function pages(options = {}) {
 }
 
 //#endregion
-export { ilhaPages, pages };
+export { pages as default, pages, ilhaPages };

package/dist/server-island-registry.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Process-global registry of server-island renderers, keyed by the public
+ * island id (`sha256(file#name)`, see `serverIslandPublicId`). Lives on
+ * `globalThis` so every module copy (plugin bundle, SSR graph, frame entry)
+ * shares one instance — same pattern as `request-scope.ts`.
+ *
+ * `.server` modules self-register when the plugin appends registration code
+ * to their server-graph copy; the production `/__ilha/frame` handler (see
+ * `@ilha/router/frame`) consumes the registry to re-render an island from a
+ * client state snapshot. Server pages additionally register their `load` and
+ * route pattern so frame handlers can run the loader with matched params.
+ */
+/** Loader context for server-page `load` — mirrors the router's shape. */
+export interface FrameLoaderContext {
+    params: Record<string, string>;
+    request: Request;
+    url: URL;
+    signal: AbortSignal;
+}
+export type ServerPageLoader = (ctx: FrameLoaderContext) => unknown;
+/** A frame render: optionally preceded by running the page's `load`. */
+export interface ServerIslandEntry {
+    /** Returns the renderState fn (`Symbol.for("ilha.renderState")` getter). */
+    render: () => unknown;
+    /** The module's `load` export — runs at frame time; its return value
+     * becomes the island's render props. */
+    load?: ServerPageLoader;
+    /** Route pattern for the page (`/user/:id`) — matches params for `load`. */
+    pattern?: string;
+}
+export type FrameGuard = (request: Request) => Response | void | Promise<Response | void>;
+/**
+ * Install a guard consulted by every `/__ilha/frame` request (dev middleware
+ * and the production `@ilha/router/frame` handler share this slot — both read
+ * it from `globalThis`). Return a `Response` to reject; return nothing to
+ * allow. Island state is world-readable through frames unless you gate them,
+ * so apps serving private data should install a session check here.
+ */
+export declare function setFrameGuard(guard: FrameGuard): void;
+export declare function getFrameGuard(): FrameGuard | undefined;
+export type FrameLoaderRunner = (path: string) => Promise<{
+    kind: string;
+    data?: unknown;
+    headEntries?: unknown;
+    status?: number;
+    to?: string;
+    message?: string;
+}>;
+/**
+ * Install the handler backing `GET /__ilha/loader` in production. The
+ * generated `pages.server.ts` wires this to `pageRouter.runLoader`, so
+ * regular-page server loads get full route matching, layout chains, and
+ * redirect/error semantics. Dev and prod handlers share the slot.
+ */
+export declare function setFrameLoaderRunner(runner: FrameLoaderRunner): void;
+export declare function getFrameLoaderRunner(): FrameLoaderRunner | undefined;
+/** Register `id` → entry. Later registrations win (id encodes file + name). */
+export declare function registerServerIsland(id: string, render: () => unknown, options?: {
+    load?: ServerPageLoader;
+    pattern?: string;
+}): void;
+export declare function getServerIslandEntry(id: string): ServerIslandEntry | undefined;
+/** Back-compat alias used by tests. */
+export declare const getServerIslandRenderer: typeof getServerIslandEntry;
+/** Client-facing frame failure. `redirect` carries a loader redirect target. */
+export declare class FrameError extends Error {
+    status: number;
+    redirect?: string;
+    constructor(status: number, message: string, redirect?: string);
+}
+/**
+ * Shared tail of every frame request: run the page's `load` when registered
+ * (params matched from the frame path), then invoke the renderer inside the
+ * caller's scope. Throws `FrameError` with an HTTP status for client-facing
+ * failures; loader redirects surface via `FrameError.redirect`.
+ */
+export declare function renderServerIsland(id: string, request: Request, runWithScope: <T>(request: Request, fn: () => T) => T | Promise<T>): Promise<string>;

package/dist/server-island-registry.js

@@ -0,0 +1,134 @@
+//#region src/server-island-registry.ts
+const REGISTRY_KEY = Symbol.for("ilha.serverIslandRenderers");
+function registry() {
+	const g = globalThis;
+	let map = g[REGISTRY_KEY];
+	if (!map) {
+		map = /* @__PURE__ */ new Map();
+		g[REGISTRY_KEY] = map;
+	}
+	return map;
+}
+const GUARD_KEY = Symbol.for("ilha.frameGuard");
+/**
+* Install a guard consulted by every `/__ilha/frame` request (dev middleware
+* and the production `@ilha/router/frame` handler share this slot — both read
+* it from `globalThis`). Return a `Response` to reject; return nothing to
+* allow. Island state is world-readable through frames unless you gate them,
+* so apps serving private data should install a session check here.
+*/
+function setFrameGuard(guard) {
+	const g = globalThis;
+	g[GUARD_KEY] = guard;
+}
+function getFrameGuard() {
+	return globalThis[GUARD_KEY];
+}
+const LOADER_RUNNER_KEY = Symbol.for("ilha.frameLoaderRunner");
+/**
+* Install the handler backing `GET /__ilha/loader` in production. The
+* generated `pages.server.ts` wires this to `pageRouter.runLoader`, so
+* regular-page server loads get full route matching, layout chains, and
+* redirect/error semantics. Dev and prod handlers share the slot.
+*/
+function setFrameLoaderRunner(runner) {
+	const g = globalThis;
+	g[LOADER_RUNNER_KEY] = runner;
+}
+function getFrameLoaderRunner() {
+	return globalThis[LOADER_RUNNER_KEY];
+}
+/** Register `id` → entry. Later registrations win (id encodes file + name). */
+function registerServerIsland(id, render, options) {
+	registry().set(id, {
+		render,
+		load: options?.load,
+		pattern: options?.pattern
+	});
+}
+function getServerIslandEntry(id) {
+	return registry().get(id);
+}
+/** Back-compat alias used by tests. */
+const getServerIslandRenderer = getServerIslandEntry;
+/** Client-facing frame failure. `redirect` carries a loader redirect target. */
+var FrameError = class extends Error {
+	status;
+	redirect;
+	constructor(status, message, redirect) {
+		super(message);
+		this.status = status;
+		this.redirect = redirect;
+	}
+};
+/** Match a route pattern (`/user/:id`, `/docs/**:slug`) against a pathname.
+* Returns raw (still-encoded) params, or null when the path doesn't match.
+* Mirrors the router's matcher semantics in miniature. */
+function matchPatternParams(pattern, pathname) {
+	const patternSegments = pattern.split("/").filter(Boolean);
+	const pathSegments = pathname.split("/").filter(Boolean);
+	const params = {};
+	let cursor = 0;
+	for (const segment of patternSegments) {
+		if (segment.startsWith("*")) {
+			const name = segment.slice(2).replace(/^:/, "");
+			if (name) params[name] = pathSegments.slice(cursor).join("/");
+			cursor = pathSegments.length;
+			break;
+		}
+		const value = pathSegments[cursor];
+		if (value === void 0) return null;
+		if (segment.startsWith(":")) params[segment.slice(1)] = value;
+		else if (value !== segment) return null;
+		cursor++;
+	}
+	return cursor === pathSegments.length ? params : null;
+}
+/**
+* Shared tail of every frame request: run the page's `load` when registered
+* (params matched from the frame path), then invoke the renderer inside the
+* caller's scope. Throws `FrameError` with an HTTP status for client-facing
+* failures; loader redirects surface via `FrameError.redirect`.
+*/
+async function renderServerIsland(id, request, runWithScope) {
+	const entry = registry().get(id);
+	if (!entry) throw new FrameError(400, "unknown island");
+	let props;
+	if (entry.load) {
+		let url;
+		try {
+			url = new URL(request.url);
+		} catch {
+			throw new FrameError(400, "frame failed");
+		}
+		const params = entry.pattern ? matchPatternParams(entry.pattern, url.pathname) : {};
+		if (!params) throw new FrameError(400, "frame failed");
+		try {
+			props = { load: {
+				loading: false,
+				value: await entry.load({
+					params,
+					request,
+					url,
+					signal: request.signal
+				}) ?? {},
+				error: void 0
+			} };
+		} catch (error) {
+			const marker = error;
+			if (marker.__ilhaRedirect === true) {
+				const r = error;
+				throw new FrameError(r.status || 302, "frame failed", r.to);
+			}
+			if (marker.__ilhaLoaderError === true) throw new FrameError(error.status || 500, "frame failed");
+			throw error;
+		}
+	}
+	const render = entry.render();
+	if (typeof render !== "function") throw new FrameError(400, "unknown island");
+	const html = await runWithScope(request, () => render(props));
+	return String(html);
+}
+
+//#endregion
+export { FrameError, getFrameGuard, getFrameLoaderRunner, getServerIslandEntry, getServerIslandRenderer, registerServerIsland, renderServerIsland, setFrameGuard, setFrameLoaderRunner };

package/dist/server-island.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Client-side proxies for islands defined in server-only modules
+ * (`*.server.ts(x)`).
+ *
+ * The real island never ships to the browser — it closes over server code.
+ * The Vite plugin rewrites client-graph imports of island exports to this
+ * factory, wiring each stream/action key to the tacho stub of the exported
+ * function it calls. The proxy is a branded ilha island so composition
+ * (`<Tasks />` inside a parent render) works unchanged:
+ *
+ * - SSR (server graph): imports resolve to the REAL module — no proxies.
+ * - Hydration (client): `mount` seeds state from `data-ilha-state`, preserves
+ *   the SSR DOM, resumes streams through the wired stubs, and reconnects
+ *   `[data-ilha-on]` event sentinels to named actions using the
+ *   `data-ilha-actions` manifest emitted by `hydratable()`.
+ */
+export type ServerStreamFn = (signal: AbortSignal) => AsyncGenerator<unknown> | Generator<unknown>;
+export interface ServerIslandWiring {
+    /** Stream key → client transport. The plugin wires these to tacho stubs. */
+    streams?: Record<string, ServerStreamFn>;
+    /** Action key → client transport. Event payloads are not serializable;
+     * handlers receive `undefined` and should read island state instead. */
+    actions?: Record<string, (payload?: unknown) => unknown>;
+    /** Frame transport: re-renders the island from server-owned state. */
+    frame?: () => unknown;
+    /** RPC transport for the module's `loader.client` export — invoked once
+     * when the view hydrates. Side-effect loader on server pages. */
+    clientLoader?: () => unknown;
+    /** Client-capable islands nested in the server render, keyed by opaque ref. */
+    children?: Record<string, unknown>;
+}
+export interface ServerIslandHandle {
+    unmount: () => void;
+    updateProps: (props?: Record<string, unknown>) => void;
+}
+/**
+ * Create a client proxy island for a server-defined island. Called by
+ * generated virtual modules — not by application code.
+ *
+ * @param id - Stable identity (`<relative-path>#<export>`), for diagnostics.
+ * @param as - Slot tag declared by the server island's `.as()` (default div).
+ * @param wiring - Stream/action transports wired to tacho stubs by codegen.
+ */
+export declare function __ilhaServerIsland(id: string, as: string, wiring?: ServerIslandWiring): unknown;

package/dist/server-island.js

@@ -0,0 +1,229 @@
+import { morph } from "ilha";
+
+//#region src/server-island.ts
+/**
+* Client-side proxies for islands defined in server-only modules
+* (`*.server.ts(x)`).
+*
+* The real island never ships to the browser — it closes over server code.
+* The Vite plugin rewrites client-graph imports of island exports to this
+* factory, wiring each stream/action key to the tacho stub of the exported
+* function it calls. The proxy is a branded ilha island so composition
+* (`<Tasks />` inside a parent render) works unchanged:
+*
+* - SSR (server graph): imports resolve to the REAL module — no proxies.
+* - Hydration (client): `mount` seeds state from `data-ilha-state`, preserves
+*   the SSR DOM, resumes streams through the wired stubs, and reconnects
+*   `[data-ilha-on]` event sentinels to named actions using the
+*   `data-ilha-actions` manifest emitted by `hydratable()`.
+*/
+/** Symbol.for keeps brands stable across duplicate ilha copies in one realm. */
+const ISLAND = Symbol.for("ilha.island");
+const ISLAND_SLOT_TAG = Symbol.for("ilha.islandSlotTag");
+const ISLAND_MOUNT_INTERNAL$1 = Symbol.for("ilha.islandMountInternal");
+const STATE_ATTR = "data-ilha-state";
+const EVENT_SENTINEL_ATTR = "data-ilha-on";
+const ACTIONS_ATTR = "data-ilha-actions";
+const PROPS_ATTR = "data-ilha-props";
+const CLIENT_REF_ATTR = "data-ilha-client-ref";
+/** Defensive snapshot parse — mirrors core's guards in miniature. */
+function parseSnapshot(raw) {
+	if (raw.length > 262144) return void 0;
+	try {
+		const parsed = JSON.parse(raw);
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return void 0;
+		return parsed;
+	} catch {
+		return;
+	}
+}
+function assertValidTag(tag) {
+	const trimmed = tag.trim();
+	if (/^[a-z][a-z0-9-]*$/i.test(trimmed)) return trimmed.toLowerCase();
+	return "div";
+}
+/** True when `candidate` is owned by `host`: walking up must not cross another
+* island or slot boundary before reaching it. */
+function belongsToHost(host, candidate) {
+	let el = candidate.parentElement;
+	while (el && el !== host) {
+		if (el.hasAttribute("data-ilha") || el.hasAttribute("data-ilha-slot")) return false;
+		el = el.parentElement;
+	}
+	return el === host;
+}
+function hydrateServerIsland(host, id, wiring) {
+	const controller = new AbortController();
+	const cleanups = [];
+	cleanups.push(() => controller.abort());
+	const state = {};
+	const rawState = host.getAttribute(STATE_ATTR);
+	if (rawState) {
+		const parsed = parseSnapshot(rawState);
+		if (parsed) {
+			for (const [key, value] of Object.entries(parsed)) if (!key.startsWith("_")) state[key] = value;
+		}
+	}
+	const frame = wiring.frame;
+	let repaintChain = Promise.resolve();
+	const scheduleRepaint = () => {
+		if (!frame || controller.signal.aborted) return;
+		repaintChain = repaintChain.then(async () => {
+			if (controller.signal.aborted || !host.isConnected) return;
+			const html = await frame();
+			if (controller.signal.aborted || typeof html !== "string") return;
+			morph(host, html);
+			syncChildren();
+			wireEvents();
+		}).catch((err) => {
+			if (!controller.signal.aborted) console.error(`[ilha-router] frame render failed for "${id}":`, err);
+		});
+	};
+	const attached = [];
+	const readManifest = () => {
+		const raw = Array.from(host.children).find((c) => c.matches(`template[${ACTIONS_ATTR}]`))?.getAttribute(ACTIONS_ATTR) ?? host.getAttribute(ACTIONS_ATTR) ?? null;
+		return raw ? parseSnapshot(raw) : void 0;
+	};
+	const wireEvents = () => {
+		for (const { el, type, listener } of attached) el.removeEventListener(type, listener);
+		attached.length = 0;
+		const manifest = readManifest();
+		if (!manifest) return;
+		const sentinels = [host, ...Array.from(host.querySelectorAll(`[${EVENT_SENTINEL_ATTR}]`))];
+		for (const el of sentinels) {
+			if (!el.hasAttribute(EVENT_SENTINEL_ATTR)) continue;
+			if (el !== host && !belongsToHost(host, el)) continue;
+			const spec = el.getAttribute(EVENT_SENTINEL_ATTR) ?? "";
+			for (const part of spec.split(",")) {
+				const sep = part.lastIndexOf(":");
+				if (sep < 1) continue;
+				const type = part.slice(0, sep);
+				const entry = manifest[part];
+				let actionKey;
+				let callArgs = [];
+				if (typeof entry === "string") actionKey = entry;
+				else if (entry && typeof entry === "object") {
+					actionKey = String(entry.k);
+					if (Array.isArray(entry.a)) callArgs = entry.a;
+				}
+				const action = actionKey == null ? void 0 : wiring.actions?.[actionKey];
+				if (!action) continue;
+				const listener = () => {
+					Promise.resolve(action(...callArgs)).then(() => scheduleRepaint()).catch((err) => {
+						console.error(`[ilha-router] action "${String(actionKey)}" failed:`, err);
+					});
+				};
+				el.addEventListener(type, listener);
+				attached.push({
+					el,
+					type,
+					listener
+				});
+			}
+		}
+	};
+	wireEvents();
+	const mountedChildren = /* @__PURE__ */ new Map();
+	const reviveChildProps = (props) => {
+		if (!props) return void 0;
+		for (const [key, value] of Object.entries(props)) {
+			if (!value || typeof value !== "object") continue;
+			const marker = value;
+			if (marker.__ilha !== "action" || typeof marker.k !== "string") continue;
+			const action = wiring.actions?.[marker.k];
+			if (!action) continue;
+			const args = Array.isArray(marker.a) ? marker.a : [];
+			props[key] = (..._runtimeArgs) => Promise.resolve(action(...args)).then((result) => {
+				scheduleRepaint();
+				return result;
+			});
+		}
+		return props;
+	};
+	const syncChildren = () => {
+		for (const [el, handle] of mountedChildren) {
+			if (el.isConnected && belongsToHost(host, el) && el.hasAttribute(CLIENT_REF_ATTR)) continue;
+			handle.unmount();
+			mountedChildren.delete(el);
+		}
+		for (const el of host.querySelectorAll(`[${CLIENT_REF_ATTR}]`)) {
+			if (!belongsToHost(host, el)) continue;
+			const props = reviveChildProps(parseSnapshot(el.getAttribute(PROPS_ATTR) ?? "") ?? void 0);
+			const mounted = mountedChildren.get(el);
+			if (mounted) {
+				mounted.updateProps(props);
+				continue;
+			}
+			const mount = (wiring.children?.[el.getAttribute(CLIENT_REF_ATTR) ?? ""])?.[ISLAND_MOUNT_INTERNAL$1];
+			if (mount) mountedChildren.set(el, mount(el, props));
+		}
+	};
+	syncChildren();
+	for (const [key, fn] of Object.entries(wiring.streams ?? {})) (async () => {
+		try {
+			const gen = await fn(controller.signal);
+			try {
+				for (;;) {
+					const { done, value } = await gen.next();
+					if (controller.signal.aborted || done) break;
+					state[key] = value;
+					scheduleRepaint();
+				}
+			} catch (err) {
+				if (!controller.signal.aborted && err?.name !== "AbortError") console.error(`[ilha-router] stream "${key}" failed:`, err);
+			} finally {
+				Promise.resolve(gen.return?.(void 0)).catch(() => {});
+			}
+		} catch (err) {
+			if (!controller.signal.aborted && err?.name !== "AbortError") console.error(`[ilha-router] stream "${key}" failed:`, err);
+		}
+	})();
+	if (frame && !host.hasAttribute(STATE_ATTR) && host.childNodes.length === 0) scheduleRepaint();
+	if (wiring.clientLoader) Promise.resolve(wiring.clientLoader()).catch((err) => {
+		if (!controller.signal.aborted) console.error(`[ilha-router] client loader failed for "${id}":`, err);
+	});
+	return {
+		unmount: () => {
+			for (const { el, type, listener } of attached) el.removeEventListener(type, listener);
+			attached.length = 0;
+			for (const handle of mountedChildren.values()) handle.unmount();
+			mountedChildren.clear();
+			for (const cleanup of cleanups) cleanup();
+			cleanups.length = 0;
+		},
+		updateProps: () => {}
+	};
+}
+/**
+* Create a client proxy island for a server-defined island. Called by
+* generated virtual modules — not by application code.
+*
+* @param id - Stable identity (`<relative-path>#<export>`), for diagnostics.
+* @param as - Slot tag declared by the server island's `.as()` (default div).
+* @param wiring - Stream/action transports wired to tacho stubs by codegen.
+*/
+function __ilhaServerIsland(id, as, wiring = {}) {
+	const slotTag = assertValidTag(as);
+	const island = ((props) => {
+		return "";
+	});
+	island[ISLAND] = true;
+	island[ISLAND_SLOT_TAG] = slotTag;
+	island.toString = () => "";
+	const ISLAND_CALL = Symbol.for("ilha.islandCall");
+	island.key = (slotKey) => {
+		if (typeof slotKey !== "string" || slotKey.trim().length === 0 || slotKey.includes(":")) throw new Error("server island key() requires a non-empty key without \":\".");
+		return (props) => ({
+			[ISLAND_CALL]: true,
+			island,
+			props,
+			key: slotKey
+		});
+	};
+	island[ISLAND_MOUNT_INTERNAL$1] = (host) => hydrateServerIsland(host, id, wiring);
+	island.mount = (host) => hydrateServerIsland(host, id, wiring).unmount;
+	return island;
+}
+
+//#endregion
+export { __ilhaServerIsland };