@ilha/router 0.9.2 → 0.10.0

package/dist/{plugin-BHuojFhQ.js → plugin-CmI3Brr2.js}

@@ -1,5 +1,4 @@
-import { t as runWithIslandRequest } from "./request-scope-C4reU4v0.js";
-import { FrameError, getFrameAuth, getFrameGuard, isTrustedOrigin, renderServerIsland, setFrameAuth, setFrameGuard, setLoaderGuard } from "./server-island-registry.js";
+import { C as setLoaderGuard, T as runWithIslandRequest, b as setFrameAuth, c as frameEnvelope, m as isSafeFramePath, n as FrameError, o as authorizeFrameRequest, u as getFrameGuard, x as setFrameGuard, y as renderServerIsland } from "./ssr-BxrcUYy5.js";
 import { existsSync, readFileSync, statSync, watch } from "node:fs";
 import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { createUnplugin } from "unplugin";
@@ -7,10 +6,24 @@ import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 
 //#region src/server-islands.ts
+/**
+* Replace identity `action(` wrappers of exported server actions with the
+* capture-aware shim on ALREADY-COMPILED module code. Must run inside the
+* SSR transform so upstream JSX/TS output is preserved.
+*/
+function rewriteServerActions(code, rpcActions) {
+	const names = Object.keys(rpcActions);
+	if (names.length === 0) return code;
+	const re = new RegExp(`(export\\s+(?:const|let|var)\\s+(${names.join("|")})\\b\\s*=\\s*)action\\s*\\(`, "g");
+	return code.replace(re, (_match, head, name) => {
+		const key = rpcActions[name];
+		return `${head}__ilhaServerAction(${JSON.stringify(key)}, `;
+	});
+}
 const EXPORT_RE = /(?:^|\n)\s*export\s+(?:declare\s+)?(?:async\s+)?(?:function\s*\*?|const|let|var|class)\s+([A-Za-z_$][\w$]*)/g;
 const ISLAND_EXPORT_RE = /(?:^|\n)\s*export\s+(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*ilha\b/g;
 const DEFAULT_ISLAND_RE = /export\s+default\s+ilha\b/;
-const AS_RE = /\.as\(\s*["'`]([a-z][a-z0-9-]*)["'`]\s*\)/;
+const AS_RES = [/\{\s*as:\s*["'`]([a-z][a-z0-9-]*)["'`]\s*[,}]?/];
 function clientRefPublicId(spec, imported) {
 	return createHash("sha256").update(`${spec}#${imported}`).digest("base64url");
 }
@@ -69,35 +82,12 @@ function extractCallArgs(source, openParen, limit = 4e3) {
 	console.warn("[ilha-router] scanServerIslands: argument list exceeded the scan limit — call skipped.");
 	return null;
 }
-/** First callback body inside an args list: everything after the first top-level
-* comma. Used to scan which module exports a stream/action closure references. */
-function callbackBody(args) {
-	let depth = 0;
-	let quote = null;
-	for (let i = 0; i < args.length; i++) {
-		const ch = args[i];
-		if (quote !== null) {
-			if (ch === "\\") i++;
-			else if (ch === quote) quote = null;
-			continue;
-		}
-		if (ch === "\"" || ch === "'" || ch === "`") {
-			quote = ch;
-			continue;
-		}
-		if (ch === "(" || ch === "{" || ch === "[") depth++;
-		else if (ch === ")" || ch === "}" || ch === "]") depth--;
-		else if (ch === "," && depth === 0) return args.slice(i + 1);
-	}
-	return "";
-}
-/** Identifiers in `body` that are members of `candidates`, excluding keywords. */
 function referencedExports(body, candidates) {
 	for (const match of body.matchAll(/([A-Za-z_$][\w$]*)\s*\(/g)) if (candidates.has(match[1])) return match[1];
 }
 /** 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(() => …)`). */
+* function components (`ilha(() => …)`) and `ilha(schema, component)`. */
 function scanServerIslands(source) {
 	const exports = [];
 	for (const match of source.matchAll(EXPORT_RE)) exports.push(match[1]);
@@ -107,20 +97,36 @@ function scanServerIslands(source) {
 		if (name && /^[A-Za-z_$][\w$]*$/.test(name) && !exports.includes(name)) exports.push(name);
 	}
 	const candidates = new Set(exports);
+	const rpcActions = {};
+	for (const match of source.matchAll(/export\s+(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*action\s*\(/g)) rpcActions[match[1]] = `x:${match[1]}`;
 	const islands = [];
 	const collect = (name, start, sliceEnd) => {
 		const slice = source.slice(start, sliceEnd);
-		const as = slice.match(AS_RE)?.[1] ?? "div";
+		let as = "div";
+		for (const re of AS_RES) {
+			const hit = slice.match(re)?.[1];
+			if (hit) {
+				as = hit;
+				break;
+			}
+		}
 		const streams = {};
 		const actions = {};
-		for (const kind of ["stream", "action"]) {
-			const re = new RegExp(`\\.${kind}\\s*\\(\\s*["'\`](\\w+)["'\`]\\s*,`, "g");
+		let actionOrder = 0;
+		let streamOrder = 0;
+		for (const kind of ["action", "derived"]) {
+			const re = new RegExp(kind === "action" ? "[A-Za-z0-9_$]*[Aa]ction\\s*\\(" : "\\bderived\\s*\\(", "g");
 			for (const match of slice.matchAll(re)) {
-				const key = match[1];
-				const args = extractCallArgs(slice, (match.index ?? 0) + match[0].indexOf("("));
+				const args = extractCallArgs(slice, match.index + match[0].indexOf("("));
 				if (!args) continue;
-				const target = referencedExports(callbackBody(args), candidates);
-				if (target) (kind === "stream" ? streams : actions)[key] = target;
+				if (kind === "derived") {
+					if (!/(async\s+function\s*\*|yield\b|for\s+await)/.test(args)) continue;
+					const target = referencedExports(args, candidates);
+					if (target) streams[`d${streamOrder++}`] = target;
+					continue;
+				}
+				const target = referencedExports(args, candidates);
+				actions[`a${actionOrder++}`] = target ?? "";
 			}
 		}
 		islands.push({
@@ -145,6 +151,7 @@ function scanServerIslands(source) {
 	return {
 		islands,
 		exports,
+		rpcActions,
 		clientRefs: scanClientRefs(source),
 		clientLoader: /(^|\n)\s*export\s+(?:const|let|var)\s+load\b\s*=\s*loader\.client\b/.test(source)
 	};
@@ -174,7 +181,7 @@ function generateServerIslandModule(spec, scan) {
 	const moduleKey = basename(spec).replace(/\.server\.(?:[jt]sx?)$/i, "");
 	const lines = [
 		`import { client as $$rpc } from "virtual:oxide/client";`,
-		`import { __ilhaServerIsland } from "@ilha/router/server-island";`,
+		`import { __ilhaApplyHead, __ilhaServerIsland } from "@ilha/router/server-island";`,
 		`const $$call = (method, args) => { const opts = args.at(-1); return opts && typeof opts === "object" && opts.signal instanceof AbortSignal && Object.keys(opts).length === 1 ? $$rpc[${JSON.stringify(moduleKey)}][method](args.slice(0, -1), opts) : $$rpc[${JSON.stringify(moduleKey)}][method](args); };`,
 		...scan.clientRefs.map((ref, index) => ref.imported === "default" ? `import $$child${index} from ${JSON.stringify(ref.spec)};` : `import { ${ref.imported} as $$child${index} } from ${JSON.stringify(ref.spec)};`)
 	];
@@ -182,12 +189,16 @@ function generateServerIslandModule(spec, scan) {
 	for (const island of scan.islands) {
 		const wiring = [];
 		const streams = Object.entries(island.streams).map(([key, target]) => `${JSON.stringify(key)}: (signal) => $$call(${JSON.stringify(target)}, [{ signal }])`);
-		const actions = Object.entries(island.actions).map(([key, target]) => `${JSON.stringify(key)}: (...args) => $$call(${JSON.stringify(target)}, args)`);
+		const rpcEntries = Object.entries(scan.rpcActions).map(([name, key]) => [key, name]);
+		const actions = Object.entries({
+			...island.actions,
+			...Object.fromEntries(rpcEntries)
+		}).map(([key, target]) => `${JSON.stringify(key)}: (...args) => $$call(${JSON.stringify(target)}, args)`);
 		if (streams.length) wiring.push(`streams: { ${streams.join(", ")} }`);
 		if (actions.length) wiring.push(`actions: { ${actions.join(", ")} }`);
 		if (scan.clientRefs.length) wiring.push(`children: { ${scan.clientRefs.map((ref, index) => `${JSON.stringify(ref.id)}: $$child${index}`).join(", ")} }`);
 		const id = serverIslandPublicId(spec, island.name);
-		wiring.push(`frame: () => fetch("/__ilha/frame", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ id: ${JSON.stringify(id)}, path: location.pathname + location.search }) }).then((r) => { if (!r.ok) throw new Error("frame failed"); return r.json(); }).then((j) => { if (j.redirect) { location.assign(j.redirect); throw new Error("frame redirected"); } return j.html; })`);
+		wiring.push(`frame: () => fetch("/__ilha/frame", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ id: ${JSON.stringify(id)}, path: location.pathname + location.search }) }).then((r) => { if (!r.ok) throw new Error("frame failed"); return r.json(); }).then((j) => { if (j.redirect) { location.assign(j.redirect); throw new Error("frame redirected"); } __ilhaApplyHead(j.head); return j.html; })`);
 		if (scan.clientLoader) wiring.push(`clientLoader: () => $$call("load", [])`);
 		const call = `__ilhaServerIsland(${JSON.stringify(id)}, ${JSON.stringify(island.as)}, { ${wiring.join(", ")} })`;
 		if (island.name === "default") lines.push(`export default ${call};`);
@@ -472,11 +483,11 @@ function buildServerFile(entries, serverFile) {
 		`// Import via: import { pageRouter, registry } from "ilha:pages/server";`,
 		``,
 		...imports,
-		...entries.some((e) => e.hasLoader || e.loaderLayouts.length > 0) ? [`import { setFrameLoaderRunner } from "@ilha/router/server-island-registry";`, `setFrameLoaderRunner((path, request) => pageRouter.runLoader(path, request));`] : [],
+		...entries.some((e) => e.hasLoader || e.loaderLayouts.length > 0) ? [`import { setFrameLoaderRunner } from "@ilha/router/ssr";`, `setFrameLoaderRunner((path, request) => pageRouter.runLoader(path, request));`] : [],
 		``,
 		...wrappedIslandLines,
 		``,
-		`export const registry: Record<string, Island<any, any>> = {`,
+		`export const registry: Record<string, Island<any>> = {`,
 		...registryLines,
 		`};`,
 		``,
@@ -556,7 +567,7 @@ function buildClientFile(entries, clientFile, opts) {
 		``,
 		...wrappedIslandLines,
 		``,
-		`export const registry: Record<string, Island<any, any>> = {`,
+		`export const registry: Record<string, Island<any>> = {`,
 		...registryLines,
 		`};`,
 		``
@@ -626,14 +637,14 @@ async function generateTypes(outDir) {
 		`  import type { RouterBuilder } from "@ilha/router";`,
 		`  import type { Island } from "ilha";`,
 		`  export const pageRouter: RouterBuilder;`,
-		`  export const registry: Record<string, Island<any, any>>;`,
+		`  export const registry: Record<string, Island<any>>;`,
 		`}`,
 		``,
 		`declare module "ilha:pages/client" {`,
 		`  import type { RouterBuilder } from "@ilha/router";`,
 		`  import type { Island } from "ilha";`,
 		`  export const pageRouter: RouterBuilder;`,
-		`  export const registry: Record<string, Island<any, any>>;`,
+		`  export const registry: Record<string, Island<any>>;`,
 		`}`,
 		``,
 		`declare module "ilha:loaders" {`,
@@ -722,8 +733,8 @@ function detectIlhaConsumers(root) {
 	const appPkg = readJson(join(root, "package.json"));
 	if (!appPkg) return [];
 	const deps = {
-		...appPkg.dependencies ?? {},
-		...appPkg.devDependencies ?? {}
+		...appPkg.dependencies,
+		...appPkg.devDependencies
 	};
 	const found = [];
 	for (const name of Object.keys(deps)) {
@@ -902,7 +913,6 @@ const pagesFactory = (options = {}) => {
 			config(userConfig) {
 				const singletonPeers = [
 					"ilha",
-					"@ilha/store",
 					"@ilha/router",
 					"alien-signals",
 					...detectIlhaConsumers(userConfig.root ? resolve(userConfig.root) : process.cwd())
@@ -919,7 +929,6 @@ const pagesFactory = (options = {}) => {
 							"ilha",
 							"ilha/jsx-runtime",
 							"ilha/jsx-dev-runtime",
-							"@ilha/store",
 							"alien-signals"
 						])]
 					}
@@ -937,16 +946,19 @@ const pagesFactory = (options = {}) => {
 					const lines = [];
 					for (const ref of scan?.clientRefs ?? []) lines.push(`if (${ref.local}?.[Symbol.for("ilha.island")]) ${ref.local}[Symbol.for("ilha.clientRef")] = ${JSON.stringify(ref.id)};`);
 					if (scan && scan.islands.length > 0 && !code.startsWith("// oxidejs:client-stub")) {
+						if (Object.keys(scan.rpcActions).length > 0) lines.unshift(`import { __ilhaServerAction } from "@ilha/router/ssr";`);
 						lines.unshift(`import * as __ilhaSelf from ${JSON.stringify(file)};`);
-						lines.unshift(`import { registerServerIsland } from "@ilha/router/server-island-registry";`);
+						lines.unshift(`import { registerServerIsland } from "@ilha/router/ssr";`);
 						for (const island of scan.islands) {
 							const id2 = serverIslandPublicId(file, island.name);
 							const isServerPage = SERVER_PAGE_RE.test(file) && state.isUnderPagesDir(file) && scan.exports.includes("load") ? `, { load: __ilhaSelf.load, pattern: ${JSON.stringify(fileToPattern(state.pagesDir, file))} }` : "";
 							lines.push(`registerServerIsland(${JSON.stringify(id2)}, () => __ilhaSelf[${JSON.stringify(island.name)}]?.[Symbol.for("ilha.renderState")]${isServerPage});`);
 						}
 					}
-					if (lines.length === 0) return null;
-					return `${code}\n${lines.join("\n")}`;
+					const base = rewriteServerActions(code, scan?.rpcActions ?? {});
+					if (base === code && lines.length === 0) return null;
+					if (lines.length === 0) return base;
+					return `${base}\n${lines.join("\n")}`;
 				}
 				if (id.startsWith("\0") || id.includes("node_modules")) return null;
 				if (serverFile) return null;
@@ -990,7 +1002,7 @@ const pagesFactory = (options = {}) => {
 				server.watcher.add(state.pagesDir);
 				if (options.frameGuard) setFrameGuard(options.frameGuard);
 				if (options.loaderGuard) setLoaderGuard(options.loaderGuard);
-				if (options.trustedOrigins || options.csrf) setFrameAuth({
+				setFrameAuth({
 					trustedOrigins: options.trustedOrigins,
 					csrf: options.csrf,
 					defaultAction: "open"
@@ -1007,48 +1019,17 @@ const pagesFactory = (options = {}) => {
 						res.end();
 						return;
 					}
-					const guardHeaders = new Headers();
-					if (req.headers.origin) guardHeaders.set("origin", String(req.headers.origin));
-					if (req.headers.host) guardHeaders.set("host", String(req.headers.host));
-					if (!isTrustedOrigin(new Request(`http://${req.headers.host ?? "localhost"}${req.url ?? "/"}`, { headers: guardHeaders }), getFrameAuth())) {
-						console.warn(`[ilha-router] dev frame request rejected: Origin ${String(req.headers.origin)} is not trusted (host: ${String(req.headers.host ?? "localhost")}). Configure trustedOrigins via IlhaPagesOptions if this origin is expected.`);
-						res.statusCode = 403;
-						res.end();
-						return;
-					}
-					const identityHeaders = new Headers();
-					for (const name of ["cookie", "authorization"]) {
-						const v = req.headers[name];
-						if (typeof v === "string") identityHeaders.set(name, v);
-					}
-					try {
-						const denied = await getFrameGuard()?.(new Request(`http://${req.headers.host ?? "localhost"}${req.url ?? "/"}`, {
-							method: req.method,
-							headers: identityHeaders
-						}));
-						if (denied) {
-							res.statusCode = denied.status;
-							res.setHeader("cache-control", "no-store");
-							res.end();
-							return;
-						}
-					} catch {
-						res.statusCode = 403;
-						res.end();
-						return;
-					}
-					const csrf = getFrameAuth()?.csrf;
-					if (csrf) try {
-						if (!await csrf(new Request(`http://${req.headers.host ?? "localhost"}${req.url ?? "/"}`, {
-							method: req.method,
-							headers: identityHeaders
-						}))) {
-							res.statusCode = 403;
-							res.end();
-							return;
-						}
-					} catch {
-						res.statusCode = 403;
+					const frameUrl = `http://${req.headers.host ?? "localhost"}${req.url ?? "/"}`;
+					const authorized = await authorizeFrameRequest(new Request(frameUrl, {
+						method: req.method,
+						headers: new Headers(req.headers)
+					}), {
+						defaultAction: "open",
+						onGuardError: () => {}
+					});
+					if (!authorized.ok) {
+						if (authorized.status === 403 && !getFrameGuard()) console.warn(`[ilha-router] dev frame request rejected: Origin ${String(req.headers.origin)} is not trusted (host: ${String(req.headers.host ?? "localhost")}). Configure trustedOrigins via IlhaPagesOptions if this origin is expected.`);
+						res.statusCode = authorized.status;
 						res.end();
 						return;
 					}
@@ -1067,42 +1048,48 @@ const pagesFactory = (options = {}) => {
 						const body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
 						const target = serverIslands.get(body.id ?? "");
 						if (!target) throw new Error("unknown island");
-						let framePath = "/__ilha/frame";
-						if (typeof body.path === "string" && body.path.startsWith("/") && !body.path.includes("//") && !body.path.includes("\\") && body.path.length <= 2048) framePath = body.path;
+						let framePath = "/";
+						if (typeof body.path === "string") {
+							if (!isSafeFramePath(body.path)) {
+								const env = frameEnvelope(400, { error: "frame failed" });
+								res.statusCode = env.status;
+								for (const [k, v] of Object.entries(env.headers)) res.setHeader(k, v);
+								res.end(env.body);
+								return;
+							}
+							framePath = body.path;
+						}
 						await server.ssrLoadModule(VIRTUAL_PAGES_SERVER);
 						if (typeof (await server.ssrLoadModule(target.file))[target.name]?.[Symbol.for("ilha.renderState")] !== "function") throw new Error("unknown island");
-						const headers = new Headers();
-						for (const name of [
-							"cookie",
-							"authorization",
-							"user-agent"
-						]) {
-							const value = req.headers[name];
-							if (typeof value === "string") headers.set(name, value);
-						}
+						const headers = authorized.identityHeaders;
 						const requestOrigin = `http://${req.headers.host ?? "localhost"}`;
 						const request = new Request(new URL(framePath, requestOrigin), {
 							method: "POST",
 							headers
 						});
-						const html = await renderServerIsland(body.id ?? "", request, (r, fn) => runWithIslandRequest(r, fn));
-						res.setHeader("cache-control", "no-store");
-						res.setHeader("content-type", "application/json;charset=utf-8");
-						res.end(JSON.stringify({ html: String(html) }));
+						let head;
+						const html = await renderServerIsland(body.id ?? "", request, (r, fn) => runWithIslandRequest(r, fn), (entries) => head = entries);
+						const env = frameEnvelope(200, {
+							html: String(html),
+							head
+						});
+						res.statusCode = env.status;
+						for (const [k, v] of Object.entries(env.headers)) res.setHeader(k, v);
+						res.end(env.body);
 					} catch (err) {
 						if (err instanceof FrameError && err.redirect) {
-							res.statusCode = err.status;
-							res.setHeader("cache-control", "no-store");
-							res.setHeader("content-type", "application/json;charset=utf-8");
-							res.end(JSON.stringify({ redirect: err.redirect }));
+							const env = frameEnvelope(err.status, { redirect: err.redirect });
+							res.statusCode = env.status;
+							for (const [k, v] of Object.entries(env.headers)) res.setHeader(k, v);
+							res.end(env.body);
 							return;
 						}
 						const status = err instanceof FrameError ? err.status : 400;
 						if (!(err instanceof FrameError) || err.status >= 500) console.error("[ilha-router] frame render failed:", err);
-						res.statusCode = status;
-						res.setHeader("cache-control", "no-store");
-						res.setHeader("content-type", "application/json;charset=utf-8");
-						res.end(JSON.stringify({ error: "frame failed" }));
+						const env = frameEnvelope(status, { error: "frame failed" });
+						res.statusCode = env.status;
+						for (const [k, v] of Object.entries(env.headers)) res.setHeader(k, v);
+						res.end(env.body);
 					}
 				});
 				const structuralInvalidate = createStructuralInvalidate(state, async () => {

package/dist/plugin.d.ts

@@ -33,7 +33,7 @@ export interface IlhaPagesOptions {
      * 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`.
+     * `setFrameGuard()` from `@ilha/router/ssr`.
      */
     frameGuard?: (request: Request) => Response | void | Promise<Response | void>;
     /**

package/dist/route-match.d.ts

@@ -1,6 +1,6 @@
 /**
  * Shared, decoded-aware route pattern matching used by both the router
- * (`index.ts`) and the server-frame path (`server-island-registry.ts`) so the
+ * (`index.ts`) and the server-frame path (`ssr.ts`) so the
  * two never drift on segment semantics or parameter decoding.
  *
  * Patterns support `:name` segments, a bare mid-pattern `*` (one segment), and

package/dist/{rspack.d.ts → rsbuild.d.ts}

@@ -1,6 +1,6 @@
 export type { LayoutHandler, ErrorHandler, RouteSnapshot, AppError } from "./index";
 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;
+/** Rsbuild plugin — use via `@ilha/router/rsbuild`. */
+export declare function pages(options?: IlhaPagesOptions): any;
 export default pages;

package/dist/rsbuild.js

@@ -0,0 +1,10 @@
+import { t as ilhaPages } from "./plugin-CmI3Brr2.js";
+
+//#region src/rsbuild.ts
+/** Rsbuild plugin — use via `@ilha/router/rsbuild`. */
+function pages(options = {}) {
+	return ilhaPages.rsbuild(options);
+}
+
+//#endregion
+export { pages as default, pages, ilhaPages };

package/dist/server-island.d.ts

@@ -14,6 +14,7 @@
  *   `[data-ilha-on]` event sentinels to named actions using the
  *   `data-ilha-actions` manifest emitted by `hydratable()`.
  */
+declare const ISLAND_CALL: unique symbol;
 export type ServerStreamFn = (signal: AbortSignal) => AsyncGenerator<unknown> | Generator<unknown>;
 export interface ServerIslandWiring {
     /** Stream key → client transport. The plugin wires these to tacho stubs. */
@@ -33,12 +34,26 @@ export interface ServerIslandHandle {
     unmount: () => void;
     updateProps: (props?: Record<string, unknown>) => void;
 }
+/** @internal Apply head entries returned with a server-page frame. */
+export declare function __ilhaApplyHead(entries: 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 as - Slot tag declared by the server island's `{ as }` option (default div).
  * @param wiring - Stream/action transports wired to tacho stubs by codegen.
  */
-export declare function __ilhaServerIsland(id: string, as: string, wiring?: ServerIslandWiring): unknown;
+interface IslandCallShape {
+    [ISLAND_CALL]: true;
+    island: ServerIslandCallable;
+    props?: Record<string, unknown>;
+    key: string;
+}
+export type ServerIslandCallable = Record<symbol, unknown> & ((props?: Record<string, unknown>) => string) & {
+    mount: (host: Element) => () => void;
+    toString: () => string;
+    key: (slotKey: string) => (props?: Record<string, unknown>) => IslandCallShape;
+};
+export declare function __ilhaServerIsland(id: string, as: string, wiring?: ServerIslandWiring): ServerIslandCallable;
+export {};

package/dist/server-island.js

@@ -1,3 +1,4 @@
+import { n as applyHeadEntriesToDocument, t as parseSnapshotAttr } from "./snapshot-CsEaY6h_.js";
 import { morph } from "ilha";
 
 //#region src/server-island.ts
@@ -20,23 +21,18 @@ import { morph } from "ilha";
 /** 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 ISLAND_MOUNT_INTERNAL = 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;
-	}
+/** @internal Apply head entries returned with a server-page frame. */
+function __ilhaApplyHead(entries) {
+	if (Array.isArray(entries)) applyHeadEntriesToDocument(entries);
 }
+/** Defensive snapshot parse — reuses the shared guarded parser (size cap,
+* plain-object check, depth cap, prototype-key stripping). */
 function assertValidTag(tag) {
 	const trimmed = tag.trim();
 	if (/^[a-z][a-z0-9-]*$/i.test(trimmed)) return trimmed.toLowerCase();
@@ -59,7 +55,7 @@ function hydrateServerIsland(host, id, wiring) {
 	const state = {};
 	const rawState = host.getAttribute(STATE_ATTR);
 	if (rawState) {
-		const parsed = parseSnapshot(rawState);
+		const parsed = parseSnapshotAttr(rawState);
 		if (parsed) {
 			for (const [key, value] of Object.entries(parsed)) if (!key.startsWith("_")) state[key] = value;
 		}
@@ -82,7 +78,7 @@ function hydrateServerIsland(host, id, wiring) {
 	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;
+		return raw ? parseSnapshotAttr(raw) : void 0;
 	};
 	const wireEvents = () => {
 		for (const { el, type, listener } of attached) el.removeEventListener(type, listener);
@@ -148,13 +144,13 @@ function hydrateServerIsland(host, id, wiring) {
 		}
 		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 props = reviveChildProps(parseSnapshotAttr(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];
+			const mount = (wiring.children?.[el.getAttribute(CLIENT_REF_ATTR) ?? ""])?.[ISLAND_MOUNT_INTERNAL];
 			if (mount) mountedChildren.set(el, mount(el, props));
 		}
 	};
@@ -194,14 +190,6 @@ function hydrateServerIsland(host, id, wiring) {
 		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) => {
@@ -220,10 +208,10 @@ function __ilhaServerIsland(id, as, wiring = {}) {
 			key: slotKey
 		});
 	};
-	island[ISLAND_MOUNT_INTERNAL$1] = (host) => hydrateServerIsland(host, id, wiring);
+	island[ISLAND_MOUNT_INTERNAL] = (host) => hydrateServerIsland(host, id, wiring);
 	island.mount = (host) => hydrateServerIsland(host, id, wiring).unmount;
 	return island;
 }
 
 //#endregion
-export { __ilhaServerIsland };
+export { __ilhaApplyHead, __ilhaServerIsland };

package/dist/server-islands.d.ts

@@ -9,7 +9,7 @@
 export interface ScannedServerIsland {
     /** Export binding name, or `"default"` for `export default ilha…`. */
     name: string;
-    /** Slot tag from `.as()` — must match what SSR emits. */
+    /** Slot tag from the `{ as }` option — must match what SSR emits. */
     as: string;
     /** Stream key → referenced module export used as its transport. */
     streams: Record<string, string>;
@@ -22,10 +22,24 @@ export interface ClientIslandRef {
     imported: string;
     spec: string;
 }
+/**
+ * Replace identity `action(` wrappers of exported server actions with the
+ * capture-aware shim on ALREADY-COMPILED module code. Must run inside the
+ * SSR transform so upstream JSX/TS output is preserved.
+ */
+export declare function rewriteServerActions(code: string, rpcActions: Record<string, string>): string;
 export interface ServerModuleScan {
     islands: ScannedServerIsland[];
     /** All value-export names of the module (transport candidates). */
     exports: string[];
+    /**
+     * Exported server actions rewritten to capture-aware shims: name → the
+     * `x:<name>` manifest key the client proxy wires an RPC transport for.
+     * Event closures may call these directly without wrapping in ilha's
+     * action() — during hydration-manifest rendering the call is recorded,
+     * not executed.
+     */
+    rpcActions: Record<string, string>;
     /** Imported JSX components that must hydrate inside the server island. */
     clientRefs: ClientIslandRef[];
     /** True when the module declares `export const load = loader.client(…)` —
@@ -35,7 +49,7 @@ export interface ServerModuleScan {
 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(() => …)`). */
+ * function components (`ilha(() => …)`) and `ilha(schema, component)`. */
 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.