@ilha/router 0.9.2 → 0.10.0

package/dist/ssr-BxrcUYy5.js

@@ -0,0 +1,498 @@
+import { M as parsePattern, N as safeDecode, b as resolveRedirectTarget, j as matchSegments } from "./src-B5dHU24f.js";
+import { setServerManifestSerializer } from "ilha/internal";
+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
+//#region src/ssr.ts
+/**
+* Production SSR endpoints for server-owned islands and regular-page loads.
+*
+* Default export is an oxidejs-style fetch middleware:
+* `(request) => Response | undefined`. Returns `undefined` for any request it
+* does not own, so hosts can chain it ahead of their own handler:
+*
+* ```ts
+* oxide({ middleware: ["@ilha/router/ssr"] });
+* ```
+*
+* Serves:
+* - `POST /__ilha/frame` — re-renders a server island (JSON `{ id, path }` in,
+*   `{ html }` out). Renderers come from the process-global registry
+*   populated by self-registration code appended to `.server` modules.
+* - `GET /__ilha/loader?path=…` — regular-page server loads via the loader
+*   runner (`setFrameLoaderRunner`, wired by the generated server module).
+*/
+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/ssr` 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_GUARD_KEY = Symbol.for("ilha.loaderGuard");
+/**
+* Install a guard consulted only by `GET /__ilha/loader`. When absent, the
+* loader endpoint falls back to `getFrameGuard()` for backwards compatibility.
+* Prefer a dedicated loader guard so gating the loader endpoint is independent
+* of frame rendering.
+*/
+function setLoaderGuard(guard) {
+	const g = globalThis;
+	g[LOADER_GUARD_KEY] = guard;
+}
+function getLoaderGuard() {
+	return globalThis[LOADER_GUARD_KEY];
+}
+const AUTH_KEY = Symbol.for("ilha.frameAuth");
+/**
+* Install the frame-authorization policy consumed by the production
+* `@ilha/router/ssr` handler. `trustedOrigins` and `csrf` are also applied by
+* the dev middleware (via `IlhaPagesOptions`).
+*/
+function setFrameAuth(policy) {
+	const g = globalThis;
+	g[AUTH_KEY] = policy;
+}
+function getFrameAuth() {
+	return globalThis[AUTH_KEY];
+}
+function normalizeOrigin(value) {
+	try {
+		return new URL(value).origin;
+	} catch {
+		return null;
+	}
+}
+/**
+* Same-origin check for frame/loader requests. Browsers always send `Origin`
+* on cross-origin and same-origin `POST`; its absence implies a non-browser
+* caller (allowed — gate those via a guard or `csrf`). When `Origin` is
+* present it must match the configured trusted origins, else the request's
+* own `Host`.
+*/
+function isTrustedOrigin(request, policy) {
+	const originHeader = request.headers.get("origin");
+	if (originHeader === null) return true;
+	const origin = normalizeOrigin(originHeader);
+	if (origin === null) return false;
+	const trusted = policy?.trustedOrigins ?? [];
+	if (trusted.length > 0) return trusted.some((o) => normalizeOrigin(o) === origin);
+	const host = request.headers.get("host");
+	if (!host) return false;
+	return origin === `https://${host}` || origin === `http://${host}`;
+}
+/**
+* Path-only route context for frame/loader scoped requests. Leading slash,
+* no `//` or backslash (WHATWG URLs treat `\` as `/` for http(s), so a
+* `\evil.com` prefix would smuggle a foreign authority past a plain `//`
+* check), bounded length. `false` for anything else.
+*/
+function isSafeFramePath(path) {
+	return path.startsWith("/") && !path.includes("//") && !path.includes("\\") && path.length <= 2048;
+}
+/** Identity headers forwarded onto scoped render/loader requests. */
+const FORWARD_IDENTITY_HEADERS = [
+	"cookie",
+	"authorization",
+	"user-agent"
+];
+/**
+* Copy identity headers (cookie, authorization, user-agent) onto a fresh
+* `Headers`. Accepts a `Headers` or a Node `IncomingHttpHeaders`-style plain
+* object. Client-supplied `x-forwarded-for` is deliberately NOT forwarded —
+* it is spoofable and must not be trusted by loaders for IP checks.
+*/
+function forwardIdentityHeaders(source) {
+	const out = new Headers();
+	const read = (name) => {
+		const s = source;
+		if (typeof s.get === "function") return s.get(name);
+		const v = source[name];
+		return Array.isArray(v) ? v[0] : v;
+	};
+	for (const name of FORWARD_IDENTITY_HEADERS) {
+		const v = read(name);
+		if (v !== null && v !== void 0) out.set(name, v);
+	}
+	return out;
+}
+function frameEnvelope(status, body) {
+	return {
+		status,
+		headers: {
+			"cache-control": "no-store",
+			"content-type": "application/json;charset=utf-8"
+		},
+		body: JSON.stringify(body)
+	};
+}
+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];
+}
+setServerManifestSerializer({ template(manifest) {
+	return `<template data-ilha-actions='${JSON.stringify(Object.fromEntries(manifest)).replace(/&/g, "&amp;").replace(/'/g, "&#39;").replace(/</g, "&lt;")}'></template>`;
+} });
+/** Register `id` → entry. Later registrations win (id encodes file + name). */
+/**
+* Wrap an exported server action with a named transport key. Ilha never
+* executes event-handler closures during server rendering (fail closed), so
+* this is a transparent passthrough kept for API compatibility; the `key`
+* documents the RPC transport name used by tooling.
+*/
+function __ilhaServerAction(key, fn) {
+	return typeof fn === "function" ? fn : () => fn;
+}
+function registerServerIsland(id, render, options) {
+	registry().set(id, {
+		render,
+		load: options?.load,
+		pattern: options?.pattern
+	});
+}
+function getServerIslandEntry(id) {
+	return registry().get(id);
+}
+/** 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 decoded params, or null when the path doesn't match. Shares the
+* router's matcher semantics via `route-match.ts`. */
+function matchPatternParams(pattern, pathname) {
+	const raw = matchSegments(parsePattern(pattern).segments, pathname);
+	if (!raw) return null;
+	const params = {};
+	for (const [k, v] of Object.entries(raw)) params[k] = safeDecode(v);
+	return params;
+}
+/**
+* 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, onHead) {
+	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 {
+			const headEntries = [];
+			const result = await entry.load({
+				params,
+				request,
+				url,
+				signal: request.signal,
+				head: (input) => headEntries.push(input)
+			});
+			if (headEntries.length > 0) onHead?.(headEntries);
+			props = { load: {
+				loading: false,
+				value: result ?? {},
+				error: void 0
+			} };
+		} catch (error) {
+			const marker = error;
+			if (marker.__ilhaRedirect === true) {
+				const r = error;
+				const safe = resolveRedirectTarget(r.to, url, false);
+				if (!safe.ok) throw new FrameError(500, "unsafe redirect target");
+				throw new FrameError(r.status || 302, "frame failed", safe.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);
+}
+const FRAME_ENDPOINT = "/__ilha/frame";
+/** Regular-page server loads: served through the loader-runner slot. */
+const LOADER_ENDPOINT = "/__ilha/loader";
+/** Max request body size — matches the dev middleware cap. */
+const MAX_BODY = 16384;
+function json(status, body) {
+	const env = frameEnvelope(status, body);
+	return new Response(env.body, {
+		status: env.status,
+		headers: env.headers
+	});
+}
+/**
+* Read a request body as UTF-8, streaming it with a hard byte cap. Returns
+* `null` when the body exceeds `maxBytes` (the reader is cancelled before the
+* cap is far exceeded) or when decoding fails.
+*/
+async function readBodyBounded(request, maxBytes) {
+	const contentLength = request.headers.get("content-length");
+	if (contentLength !== null && Number(contentLength) > maxBytes) return null;
+	const reader = request.body?.getReader();
+	if (!reader) return "";
+	const chunks = [];
+	let size = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		size += value?.byteLength ?? 0;
+		if (size > maxBytes) {
+			await reader.cancel().catch(() => {});
+			return null;
+		}
+		chunks.push(value);
+	}
+	const decoder = new TextDecoder();
+	return chunks.map((c) => decoder.decode(c, { stream: true })).join("") + decoder.decode();
+}
+/**
+* Shared frame-request authorization used by both the production handler
+* below and the Vite/Rsbuild dev middleware: same-origin check against the
+* frame-auth policy, the registered frame guard, and the optional CSRF
+* verifier. `defaultAction` selects the deny-by-default production posture or
+* the permissive development one.
+*
+* Returns the forwarded identity headers on success so callers render frames
+* with cookie/auth/UA context, or the HTTP status to reject with.
+*/
+async function authorizeFrameRequest(request, options) {
+	const auth = getFrameAuth();
+	if (!isTrustedOrigin(request, auth)) return {
+		ok: false,
+		status: 403
+	};
+	const guard = getFrameGuard();
+	if (!guard && (auth?.defaultAction ?? "deny") === "deny") return {
+		ok: false,
+		status: 403
+	};
+	try {
+		const denied = await guard?.(request);
+		if (denied) return {
+			ok: false,
+			status: denied.status
+		};
+	} catch (error) {
+		options.onGuardError?.(error);
+		return {
+			ok: false,
+			status: 403
+		};
+	}
+	if (auth?.csrf) try {
+		if (!await auth.csrf(request)) return {
+			ok: false,
+			status: 403
+		};
+	} catch {
+		return {
+			ok: false,
+			status: 403
+		};
+	}
+	return {
+		ok: true,
+		identityHeaders: forwardIdentityHeaders(request.headers)
+	};
+}
+async function ssr(request) {
+	let pathname;
+	try {
+		pathname = new URL(request.url).pathname;
+	} catch {
+		return json(400, { error: "frame failed" });
+	}
+	if (pathname !== "/__ilha/frame" && pathname !== "/__ilha/loader") return;
+	const auth = getFrameAuth();
+	if (!isTrustedOrigin(request, auth)) return json(403, { error: "frame failed" });
+	if (pathname === "/__ilha/loader") {
+		if (request.method !== "GET") return json(405, { error: "method not allowed" });
+		const guard = getLoaderGuard() ?? getFrameGuard();
+		if (!guard && (auth?.defaultAction ?? "deny") === "deny") return json(403, { error: "loader failed" });
+		try {
+			const denied = await guard?.(request);
+			if (denied) return denied;
+		} catch {
+			return json(403, { error: "loader failed" });
+		}
+		const runner = getFrameLoaderRunner();
+		if (!runner) return json(404, {
+			kind: "error",
+			status: 404,
+			message: "not found"
+		});
+		const cl = request.headers.get("content-length");
+		if (cl && Number(cl) > 16384) return json(413, { error: "frame failed" });
+		let target = "/";
+		try {
+			target = new URL(request.url).searchParams.get("path") ?? "/";
+		} catch {
+			return json(400, {
+				kind: "error",
+				status: 400,
+				message: "bad request"
+			});
+		}
+		if (!isSafeFramePath(target)) return json(400, {
+			kind: "error",
+			status: 400,
+			message: "bad request"
+		});
+		try {
+			const result = await runWithIslandRequest(request, () => runner(target, request));
+			if (result.kind === "redirect") return json(result.status || 302, {
+				kind: "redirect",
+				to: result.to,
+				status: result.status
+			});
+			if (result.kind !== "data") {
+				const status = result.status || 500;
+				return json(status, {
+					kind: result.kind,
+					status,
+					message: result.message
+				});
+			}
+			return json(200, result);
+		} catch (error) {
+			console.error("[ilha-router] loader endpoint failed:", error);
+			return json(500, {
+				kind: "error",
+				status: 500,
+				message: "loader failed"
+			});
+		}
+	}
+	if (request.method !== "POST") return json(405, { error: "frame failed" });
+	if (!(request.headers.get("content-type") ?? "").startsWith("application/json")) return json(415, { error: "frame failed" });
+	const authorized = await authorizeFrameRequest(request, {
+		defaultAction: auth?.defaultAction ?? "deny",
+		onGuardError: (error) => console.error("[ilha-router] frame guard failed:", error)
+	});
+	if (!authorized.ok) return json(authorized.status, { error: "frame failed" });
+	let id;
+	let path = "/";
+	try {
+		const text = await readBodyBounded(request, MAX_BODY);
+		if (text === null) return json(413, { error: "frame failed" });
+		const body = JSON.parse(text);
+		id = String(body.id ?? "");
+		if (typeof body.path === "string") {
+			if (!isSafeFramePath(body.path)) return json(400, { error: "frame failed" });
+			path = body.path;
+		}
+	} catch {
+		return json(400, { error: "frame failed" });
+	}
+	try {
+		let origin;
+		try {
+			origin = new URL(request.url).origin;
+		} catch {
+			return json(400, { error: "frame failed" });
+		}
+		const headers = forwardIdentityHeaders(request.headers);
+		const scoped = new Request(new URL(path, origin), {
+			method: "POST",
+			headers
+		});
+		for (const sym of Object.getOwnPropertySymbols(request)) {
+			if (Symbol.keyFor(sym) === void 0) continue;
+			try {
+				scoped[sym] = request[sym];
+			} catch {}
+		}
+		let head;
+		return json(200, {
+			html: await renderServerIsland(id, scoped, (scopedRequest, fn) => Promise.resolve(runWithIslandRequest(scopedRequest, fn)), (entries) => head = entries),
+			head
+		});
+	} catch (error) {
+		if (error instanceof FrameError) {
+			if (error.redirect) return json(error.status, { redirect: error.redirect });
+			if (error.status >= 500) console.error("[ilha-router] frame render failed:", error);
+			return json(error.status, { error: "frame failed" });
+		}
+		console.error("[ilha-router] frame render failed:", error);
+		return json(400, { error: "frame failed" });
+	}
+}
+/** Side-effect imports required alongside this handler. */
+ssr.imports = ["ilha:pages/server", "ilha:loaders"];
+
+//#endregion
+export { setLoaderGuard as C, setFrameLoaderRunner as S, runWithIslandRequest as T, readBodyBounded as _, __ilhaServerAction as a, setFrameAuth as b, frameEnvelope as c, getFrameLoaderRunner as d, getLoaderGuard as f, json as g, isTrustedOrigin as h, MAX_BODY as i, getFrameAuth as l, isSafeFramePath as m, FrameError as n, authorizeFrameRequest as o, getServerIslandEntry as p, LOADER_ENDPOINT as r, forwardIdentityHeaders as s, FRAME_ENDPOINT as t, getFrameGuard as u, registerServerIsland as v, ssr as w, setFrameGuard as x, renderServerIsland as y };

package/dist/ssr.d.ts

@@ -16,6 +16,159 @@
  * - `GET /__ilha/loader?path=…` — regular-page server loads via the loader
  *   runner (`setFrameLoaderRunner`, wired by the generated server module).
  */
+import type { HeadInput } from "./head";
+/**
+ * Server-frame state shared by the dev middleware and the production
+ * `@ilha/router/ssr` handler: the renderers registry (keyed by the public
+ * island id, `sha256(file#name)`, see `serverIslandPublicId`), frame/loader
+ * guards and auth policy, and the loader runner. 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 `/__ilha/frame` handler below 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;
+    /** Contribute `<head>` data for this route. Safe to call multiple times. */
+    head: (input: HeadInput) => void;
+}
+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/ssr` 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;
+/**
+ * Install a guard consulted only by `GET /__ilha/loader`. When absent, the
+ * loader endpoint falls back to `getFrameGuard()` for backwards compatibility.
+ * Prefer a dedicated loader guard so gating the loader endpoint is independent
+ * of frame rendering.
+ */
+export declare function setLoaderGuard(guard: FrameGuard): void;
+export declare function getLoaderGuard(): FrameGuard | undefined;
+/** Frame-authorization policy, installed via {@link setFrameAuth}. */
+export interface FrameAuthPolicy {
+    /**
+     * Action taken when no frame guard is registered. `"deny"` (default in the
+     * production handler) rejects every `/__ilha/frame` request with 403;
+     * `"open"` preserves the legacy unauthenticated behavior. The dev
+     * middleware stays permissive unless a guard is registered.
+     */
+    defaultAction?: "open" | "deny";
+    /**
+     * Explicit trusted origins (e.g. `"https://app.example.com"`). When set,
+     * origin checks accept only these; otherwise the check compares the `Origin`
+     * header against `https://{host}` / `http://{host}`.
+     */
+    trustedOrigins?: string[];
+    /**
+     * Optional CSRF verifier for the state-changing frame POST. Receives the
+     * original `Request`; returning falsy rejects the request. Use this for
+     * server-to-server frame callers that have no browser `Origin`.
+     */
+    csrf?: (request: Request) => boolean | Promise<boolean>;
+}
+/**
+ * Install the frame-authorization policy consumed by the production
+ * `@ilha/router/ssr` handler. `trustedOrigins` and `csrf` are also applied by
+ * the dev middleware (via `IlhaPagesOptions`).
+ */
+export declare function setFrameAuth(policy: FrameAuthPolicy): void;
+export declare function getFrameAuth(): FrameAuthPolicy | undefined;
+/**
+ * Same-origin check for frame/loader requests. Browsers always send `Origin`
+ * on cross-origin and same-origin `POST`; its absence implies a non-browser
+ * caller (allowed — gate those via a guard or `csrf`). When `Origin` is
+ * present it must match the configured trusted origins, else the request's
+ * own `Host`.
+ */
+export declare function isTrustedOrigin(request: Request, policy: FrameAuthPolicy | undefined): boolean;
+/**
+ * Path-only route context for frame/loader scoped requests. Leading slash,
+ * no `//` or backslash (WHATWG URLs treat `\` as `/` for http(s), so a
+ * `\evil.com` prefix would smuggle a foreign authority past a plain `//`
+ * check), bounded length. `false` for anything else.
+ */
+export declare function isSafeFramePath(path: string): boolean;
+/**
+ * Copy identity headers (cookie, authorization, user-agent) onto a fresh
+ * `Headers`. Accepts a `Headers` or a Node `IncomingHttpHeaders`-style plain
+ * object. Client-supplied `x-forwarded-for` is deliberately NOT forwarded —
+ * it is spoofable and must not be trusted by loaders for IP checks.
+ */
+export declare function forwardIdentityHeaders(source: Headers | Record<string, string | string[] | undefined>): Headers;
+/** No-store JSON envelope shared by dev and production frame handlers. */
+export interface FrameEnvelope {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+export declare function frameEnvelope(status: number, body: Record<string, unknown>): FrameEnvelope;
+export type FrameLoaderRunner = (path: string, request?: Request) => 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). */
+/**
+ * Wrap an exported server action with a named transport key. Ilha never
+ * executes event-handler closures during server rendering (fail closed), so
+ * this is a transparent passthrough kept for API compatibility; the `key`
+ * documents the RPC transport name used by tooling.
+ */
+export declare function __ilhaServerAction<A extends unknown[], R>(key: string, fn: (...args: A) => R): (...args: A) => R | undefined;
+export declare function registerServerIsland(id: string, render: () => unknown, options?: {
+    load?: ServerPageLoader;
+    pattern?: string;
+}): void;
+export declare function getServerIslandEntry(id: string): ServerIslandEntry | undefined;
+/** 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>, onHead?: (entries: HeadInput[]) => void): Promise<string>;
 export declare const FRAME_ENDPOINT = "/__ilha/frame";
 /** Regular-page server loads: served through the loader-runner slot. */
 export declare const LOADER_ENDPOINT = "/__ilha/loader";
@@ -28,5 +181,25 @@ export declare function json(status: number, body: Record<string, unknown>): Res
  * cap is far exceeded) or when decoding fails.
  */
 export declare function readBodyBounded(request: Request, maxBytes: number): Promise<string | null>;
+/**
+ * Shared frame-request authorization used by both the production handler
+ * below and the Vite/Rsbuild dev middleware: same-origin check against the
+ * frame-auth policy, the registered frame guard, and the optional CSRF
+ * verifier. `defaultAction` selects the deny-by-default production posture or
+ * the permissive development one.
+ *
+ * Returns the forwarded identity headers on success so callers render frames
+ * with cookie/auth/UA context, or the HTTP status to reject with.
+ */
+export declare function authorizeFrameRequest(request: Request, options: {
+    defaultAction: "open" | "deny";
+    onGuardError?: (error: unknown) => void;
+}): Promise<{
+    ok: true;
+    identityHeaders: Headers;
+} | {
+    ok: false;
+    status: number;
+}>;
 declare function ssr(request: Request): Promise<Response | undefined>;
 export default ssr;