@ilha/router 0.8.13 → 0.9.0

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-D6_4rqMb.js

@@ -0,0 +1,27 @@
+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) without depending on Oxide's action-only `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");
+/** Run `fn` with `request` available to `useContext().request`. */
+function runWithIslandRequest(request, fn) {
+	const g = globalThis;
+	return (g[REQUEST_ALS_KEY] ??= new AsyncLocalStorage()).run(request, fn);
+}
+
+//#endregion
+export { runWithIslandRequest as t };

package/dist/request-scope.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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) without depending on Oxide's action-only `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`. */
+export declare function runWithIslandRequest<T>(request: Request, fn: () => T): T;
+export type { IslandContext };

package/dist/rolldown.d.ts

@@ -3,3 +3,4 @@ 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 default pages;

package/dist/rolldown.js

@@ -1,4 +1,4 @@
-import { t as ilhaPages } from "./plugin-DdquB3Nf.js";
+import { t as ilhaPages } from "./plugin-DPGzrIVj.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-DPGzrIVj.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,130 @@
+//#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 = await entry.load({
+				params,
+				request,
+				url,
+				signal: request.signal
+			});
+		} 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 };

package/dist/server-islands.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Build-time support for server-defined islands. The plugin scans
+ * `*.server.ts(x)` modules for island exports (`export const X = ilha…`),
+ * generates a client virtual module per file that re-creates those exports as
+ * proxies wired to tacho stubs, and rewrites client-graph import sites so
+ * island bindings resolve to the proxy while everything else keeps flowing
+ * through oxidejs's tacho stub replacement.
+ */
+export interface ScannedServerIsland {
+    /** Export binding name, or `"default"` for `export default ilha…`. */
+    name: string;
+    /** Slot tag from `.as()` — must match what SSR emits. */
+    as: string;
+    /** Stream key → referenced module export used as its transport. */
+    streams: Record<string, string>;
+    /** Action key → referenced module export used as its transport. */
+    actions: Record<string, string>;
+}
+export interface ClientIslandRef {
+    id: string;
+    local: string;
+    imported: string;
+    spec: string;
+}
+export interface ServerModuleScan {
+    islands: ScannedServerIsland[];
+    /** All value-export names of the module (transport candidates). */
+    exports: string[];
+    /** Imported JSX components that must hydrate inside the server island. */
+    clientRefs: ClientIslandRef[];
+    /** True when the module declares `export const load = loader.client(…)` —
+     * the proxy wires it as an RPC call invoked when the view hydrates. */
+    clientLoader?: boolean;
+}
+export declare function clientRefPublicId(spec: string, imported: string): string;
+/** Scan a `*.server.ts(x)` module source for island exports and their
+ * declarative wiring. Convention: islands start with `ilha` — both builder
+ * chains (`ilha.state()…render()`) and direct factories (`ilha(() => …)`). */
+export declare function scanServerIslands(source: string): ServerModuleScan;
+export declare function loadServerModuleScan(path: string): ServerModuleScan;
+/** Virtual-module id prefix for generated client proxies of server islands.
+ * The file path rides base64url-encoded: a raw suffix like
+ * `\0…:…/tasks.server.tsx` would end in `.server.*` and oxidejs's client-stub
+ * loader would claim the virtual module before us. */
+export declare const SERVER_ISLAND_PREFIX = "\0ilha:server-island:";
+/** Virtual-module specifier serving the client proxy for one server island file. */
+export declare function serverIslandVirtualSpec(file: string): string;
+/** Emit the client virtual module for one scanned server file. Plain JS —
+ * `\0` virtual modules bypass Vite's built-in TS transform, so type-only
+ * constructs here would reach the browser unparsed. Editor types are
+ * unaffected: TS resolves the ORIGINAL specifier (the real server module);
+ * this module exists only inside the client bundle. Frames are fetched from
+ * the plugin's `/__ilha/frame` dev middleware. */
+export declare function serverIslandPublicId(spec: string, name: string): string;
+export declare function generateServerIslandModule(spec: string, scan: ServerModuleScan): string;
+export interface SplitContext {
+    /** Resolved absolute path of the imported specifier, when it's a scanned
+     * server module carrying islands; null otherwise. */
+    islandNamesFor(spec: string): {
+        islands: Set<string>;
+        hasDefault: boolean;
+    } | null;
+    /** Virtual module specifier that provides the island bindings. */
+    virtualSpecFor(spec: string): string;
+}
+/**
+ * Rewrite import sites whose specifier targets a server module containing
+ * island exports. Island bindings move to the virtual proxy module; all other
+ * bindings stay on the original specifier (oxidejs replaces them with tacho
+ * stubs). Returns null when no statement needed rewriting.
+ */
+export declare function splitServerImports(code: string, ctx: SplitContext): string | null;