@ilha/router 0.11.6 → 0.11.8

package/dist/frame.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Shared server-frame helpers used by the Vite/Rsbuild pages plugin and by
+ * `@ilha/router/ssr`. Kept free of the optional `oxidejs` peer so
+ * `@ilha/router/vite` can load without oxide installed.
+ *
+ * Server-frame state (renderers registry, frame/loader guards, auth policy)
+ * lives on `globalThis` so every module copy (plugin bundle, SSR graph, frame
+ * entry) shares one instance — same pattern as `request-scope.ts`.
+ */
+import * as Effect from "effect/Effect";
+import type * as Result from "effect/Result";
+import type { SnapshotObject } from "./snapshot";
+/** JSON payload for frame envelopes. */
+export type FrameJsonValue = string | number | boolean | null | FrameJsonValue[] | FrameJsonObject;
+export interface FrameJsonObject {
+    readonly [key: string]: FrameJsonValue | undefined;
+}
+/** A frame render: optionally preceded by running the page's `load`. */
+export interface ServerIslandEntry {
+    /** Returns the renderState fn (`Symbol.for("ilha.renderState")` getter). */
+    render: () => ServerIslandRenderFn;
+}
+export type ServerIslandRenderFn = (props?: SnapshotObject) => string | Promise<string> | object;
+export type FrameGuard = (request: Request) => Response | undefined | Promise<Response | undefined>;
+/**
+ * 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 const setFrameGuard: (guard: FrameGuard) => void;
+export declare const getFrameGuard: () => 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 const setFrameAuth: (policy: FrameAuthPolicy) => void;
+export declare const 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 const 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 const isSafeFramePath: (framePath: string) => boolean;
+/**
+ * Build the scoped frame render URL from the incoming request URL and frame
+ * path. Absolute `incomingUrl` values supply the origin. Relative values (for
+ * example Vite's `req.url`) require an explicit trusted `serverOrigin` — never
+ * a client `Host` header.
+ */
+export declare const frameScopedUrl: (incomingUrl: string, framePath: string, serverOrigin?: string) => string;
+type HeaderSource = Headers | Readonly<Record<string, string | string[] | undefined>>;
+/**
+ * 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 const forwardIdentityHeaders: (source: HeaderSource) => 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 const frameEnvelope: (status: number, body: FrameJsonObject) => FrameEnvelope;
+export declare const registerServerIsland: (id: string, render: () => ServerIslandRenderFn) => void;
+export declare const getServerIslandEntry: (id: string) => ServerIslandEntry | undefined;
+declare const FrameError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "FrameError";
+} & Readonly<A>;
+/** Client-facing frame failure. `redirect` carries a same-origin redirect target. */
+export declare class FrameError extends FrameError_base<{
+    status: number;
+    message?: string;
+    redirect?: string;
+}> {
+}
+/**
+ * Render a registered server island. Typed error channel: the only failure is
+ * `FrameError`; everything else is a defect surfaced as a 400 to the client.
+ */
+export declare const renderServerIsland: (id: string, request: Request, runWithScope: <T>(request: Request, fn: () => T) => T | Promise<T>, incomingProps?: SnapshotObject) => Effect.Effect<string, FrameError>;
+/** Convenience for non-Effect callers: run the render and resolve to a Result. */
+export declare const renderServerIslandResult: (id: string, request: Request, runWithScope: <T>(request: Request, fn: () => T) => T | Promise<T>, incomingProps?: SnapshotObject) => Promise<Result.Result<string, FrameError>>;
+export declare const FRAME_ENDPOINT = "/__ilha/frame";
+/** Max request body size — matches the dev middleware cap. */
+export declare const MAX_BODY: number;
+/** Parent-island props on a frame POST. Missing is fine; anything else is 400. */
+export declare const parseFrameProps: <T>(value?: T) => SnapshotObject | undefined;
+export declare const json: (status: number, body: FrameJsonObject) => Response;
+/**
+ * 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.
+ */
+export declare const 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 const authorizeFrameRequest: (request: Request, options: {
+    defaultAction: "open" | "deny";
+    onGuardError?: <E>(error: E) => void;
+}) => Promise<{
+    ok: true;
+    identityHeaders: Headers;
+} | {
+    ok: false;
+    status: number;
+}>;
+export {};

package/dist/oxide-action.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Oxide-branded server-action wrapper.
+ *
+ * Lives in its own module so `@ilha/router/vite` / the pages plugin can load
+ * frame helpers without resolving the optional `oxidejs` peer.
+ */
+import type { SnapshotValue } from "./snapshot";
+/** Brand an exported server action with its generated RPC transport key. */
+export declare const __ilhaServerAction: <A extends SnapshotValue[], R extends SnapshotValue>(key: string, fn: (...args: A) => R | Promise<R>) => import("oxidejs").ServerActionHandle<A, Awaited<Awaited<R>>>;

package/dist/{plugin-Ci-W2rMt.js → plugin-Cn_H92L0.js}

@@ -1,4 +1,4 @@
-import { C as runWithIslandRequest, a as authorizeFrameRequest, b as setFrameAuth, c as frameScopedUrl, f as isSafeFramePath, h as parseFrameProps, n as FrameError, s as frameEnvelope, u as getFrameGuard, x as setFrameGuard, y as renderServerIslandResult } from "./ssr-D9q5C-OV.js";
+import { a as authorizeFrameRequest, b as setFrameAuth, c as frameScopedUrl, f as isSafeFramePath, h as parseFrameProps, r as FrameError, s as frameEnvelope, t as runWithIslandRequest, u as getFrameGuard, x as setFrameGuard, y as renderServerIslandResult } from "./request-scope-CI9BJVS-.js";
 import { existsSync, readFileSync, statSync, watch } from "node:fs";
 import path from "node:path";
 import * as Result from "effect/Result";

package/dist/{ssr-D9q5C-OV.js → request-scope-CI9BJVS-.js}

@@ -2,158 +2,19 @@ import { t as REQUEST_ALS_KEY } from "./als-key-CVxbuM3z.js";
 import { a as withHeadStore } from "./head-WG_AtbdX.js";
 import { n as sanitizeSnapshotObject } from "./snapshot-XpAkSV8s.js";
 import { renderToString } from "ilha";
-import * as Result from "effect/Result";
-import { AsyncLocalStorage } from "node:async_hooks";
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
-import { action, brandServerAction } from "oxidejs";
-
-//#region src/webcontainer.ts
-/**
-* StackBlitz WebContainer detection for AsyncLocalStorage fallbacks.
-* Safe to import from browser-shared modules: on the client this always
-* returns false (no `process.versions.webcontainer`).
-*/
-let webcontainerOverride = null;
-/** StackBlitz sets `process.versions.webcontainer` inside WebContainers. */
-const inWebcontainer = () => {
-	if (webcontainerOverride !== null) return webcontainerOverride;
-	try {
-		const versions = globalThis.process?.versions;
-		return Boolean(versions?.webcontainer);
-	} catch {
-		return false;
-	}
-};
-
-//#endregion
-//#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.
-*
-* StackBlitz WebContainers lose AsyncLocalStorage across `async/await`. A
-* module sync fallback keeps `useContext().request` readable, and unrelated
-* fallback entries are serialized so concurrent renders cannot stomp each
-* other. Nested calls reenter only while owned by the active entry (sync nest
-* or ALS owner) so a suspended outer cannot admit unrelated concurrent work.
-*/
-/** 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");
-const innerAls = new AsyncLocalStorage();
-/** Tracks the active fallback lock owner across awaits where ALS survives. */
-const entryOwnerAls = new AsyncLocalStorage();
-let syncStore = null;
-/** When true, getStore ignores ALS so tests exercise the sync fallback path. */
-let alsBypassForTests = false;
-/** Serialize unrelated WebContainer fallback entries (set syncStore → run → clear). */
-let fallbackTail = Promise.resolve(null);
-/** Lock holder identity — nested reentry requires matching ALS owner (or sync nest). */
-let activeOwner = null;
-/**
-* Sync-only nest depth while `runScoped` is invoking `fn`. Lets nested
-* `runWithIslandRequest` reenter before `fn` awaits; cleared before awaiting
-* so a suspended entry does not admit unrelated concurrent requests.
-*/
-let syncNestDepth = 0;
-const withFallbackEntry = async (fn) => {
-	const owner = alsBypassForTests ? void 0 : entryOwnerAls.getStore();
-	if (syncNestDepth > 0 || owner !== void 0 && owner === activeOwner) return await fn();
-	const previous = fallbackTail;
-	const next = Promise.withResolvers();
-	fallbackTail = next.promise;
-	await previous;
-	const myOwner = {};
-	activeOwner = myOwner;
-	try {
-		return await entryOwnerAls.run(myOwner, fn);
-	} finally {
-		activeOwner = null;
-		next.resolve(null);
-	}
-};
-const ensureScope = () => {
-	const g = globalThis;
-	const existing = g[REQUEST_ALS_KEY];
-	if (existing && "getStore" in existing) return existing;
-	const scope = { getStore: () => (alsBypassForTests ? void 0 : innerAls.getStore()) ?? syncStore ?? void 0 };
-	g[REQUEST_ALS_KEY] = scope;
-	return scope;
-};
-const runScoped = (request, oxide, fn) => innerAls.run(request, () => oxide ? oxide(request, fn) : fn());
-/**
-* 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.
-*
-* On WebContainer the return is always a `Promise` (fallback lock). Elsewhere
-* the return matches `fn` (sync or async).
-*/
-const runWithIslandRequest = (request, fn) => {
-	ensureScope();
-	const oxideSlot = globalThis[OXIDE_RUN_WITH_REQUEST];
-	const oxide = oxideSlot === void 0 ? void 0 : oxideSlot;
-	if (!inWebcontainer()) return runScoped(request, oxide, fn);
-	return withFallbackEntry(async () => {
-		const previous = syncStore;
-		syncStore = request;
-		try {
-			syncNestDepth += 1;
-			let result;
-			try {
-				result = runScoped(request, oxide, fn);
-			} finally {
-				syncNestDepth -= 1;
-			}
-			return await Promise.resolve(result);
-		} finally {
-			syncStore = previous;
-		}
-	});
-};
+import { AsyncLocalStorage } from "node:async_hooks";
 
-//#endregion
-//#region src/ssr.ts
-/**
-* Production SSR endpoint for server-owned islands.
-*
-* 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.
-*/
+//#region src/frame.ts
 /**
-* 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`.
+* Shared server-frame helpers used by the Vite/Rsbuild pages plugin and by
+* `@ilha/router/ssr`. Kept free of the optional `oxidejs` peer so
+* `@ilha/router/vite` can load without oxide installed.
 *
-* `.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.
+* Server-frame state (renderers registry, frame/loader guards, auth policy)
+* lives on `globalThis` so every module copy (plugin bundle, SSR graph, frame
+* entry) shares one instance — same pattern as `request-scope.ts`.
 */
 const objectTag = (value) => Object.prototype.toString.call(value);
 const isString = (value) => objectTag(value) === "[object String]";
@@ -291,11 +152,6 @@ const frameEnvelope = (status, body) => ({
 	},
 	status
 });
-/** Brand an exported server action with its generated RPC transport key. */
-const __ilhaServerAction = (key, fn) => {
-	const handle = fn.$$atom === 1 ? fn : action(fn);
-	return brandServerAction(key, handle);
-};
 const registerServerIsland = (id, render) => {
 	registry().set(id, { render });
 };
@@ -406,7 +262,7 @@ const authorizeFrameRequest = async (request, options) => {
 		status: 403
 	};
 	const guard = getFrameGuard();
-	if (!guard && (auth?.defaultAction ?? "deny") === "deny") return {
+	if (!guard && (auth?.defaultAction ?? options.defaultAction ?? "deny") === "deny") return {
 		ok: false,
 		status: 403
 	};
@@ -439,76 +295,123 @@ const authorizeFrameRequest = async (request, options) => {
 		ok: true
 	};
 };
-const copyFrameworkSymbols = (from, to) => {
-	for (const sym of Object.getOwnPropertySymbols(from)) {
-		if (Symbol.keyFor(sym) === void 0) continue;
-		const desc = Object.getOwnPropertyDescriptor(from, sym);
-		if (!desc) continue;
-		try {
-			Object.defineProperty(to, sym, desc);
-		} catch {}
+
+//#endregion
+//#region src/webcontainer.ts
+/**
+* StackBlitz WebContainer detection for AsyncLocalStorage fallbacks.
+* Safe to import from browser-shared modules: on the client this always
+* returns false (no `process.versions.webcontainer`).
+*/
+let webcontainerOverride = null;
+/** StackBlitz sets `process.versions.webcontainer` inside WebContainers. */
+const inWebcontainer = () => {
+	if (webcontainerOverride !== null) return webcontainerOverride;
+	try {
+		const versions = globalThis.process?.versions;
+		return Boolean(versions?.webcontainer);
+	} catch {
+		return false;
 	}
 };
-const ssr = async (request) => {
-	let url;
+
+//#endregion
+//#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.
+*
+* StackBlitz WebContainers lose AsyncLocalStorage across `async/await`. A
+* module sync fallback keeps `useContext().request` readable, and unrelated
+* fallback entries are serialized so concurrent renders cannot stomp each
+* other. Nested calls reenter only while owned by the active entry (sync nest
+* or ALS owner) so a suspended outer cannot admit unrelated concurrent work.
+*/
+/** 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");
+const innerAls = new AsyncLocalStorage();
+/** Tracks the active fallback lock owner across awaits where ALS survives. */
+const entryOwnerAls = new AsyncLocalStorage();
+let syncStore = null;
+/** When true, getStore ignores ALS so tests exercise the sync fallback path. */
+let alsBypassForTests = false;
+/** Serialize unrelated WebContainer fallback entries (set syncStore → run → clear). */
+let fallbackTail = Promise.resolve(null);
+/** Lock holder identity — nested reentry requires matching ALS owner (or sync nest). */
+let activeOwner = null;
+/**
+* Sync-only nest depth while `runScoped` is invoking `fn`. Lets nested
+* `runWithIslandRequest` reenter before `fn` awaits; cleared before awaiting
+* so a suspended entry does not admit unrelated concurrent requests.
+*/
+let syncNestDepth = 0;
+const withFallbackEntry = async (fn) => {
+	const owner = alsBypassForTests ? void 0 : entryOwnerAls.getStore();
+	if (syncNestDepth > 0 || owner !== void 0 && owner === activeOwner) return await fn();
+	const previous = fallbackTail;
+	const next = Promise.withResolvers();
+	fallbackTail = next.promise;
+	await previous;
+	const myOwner = {};
+	activeOwner = myOwner;
 	try {
-		url = new URL(request.url);
-	} catch {
-		return json(400, { error: "frame failed" });
+		return await entryOwnerAls.run(myOwner, fn);
+	} finally {
+		activeOwner = null;
+		next.resolve(null);
 	}
-	if (url.pathname !== "/__ilha/frame") return;
-	const program = Effect.gen(function* handleFrame() {
-		const auth = getFrameAuth();
-		if (!isTrustedOrigin(request, auth)) return yield* Effect.fail(frameFail(403));
-		if (request.method !== "POST") return yield* Effect.fail(frameFail(405));
-		if (!(request.headers.get("content-type") ?? "").startsWith("application/json")) return yield* Effect.fail(frameFail(415));
-		const authorized = yield* Effect.tryPromise({
-			catch: () => frameFail(403),
-			try: () => authorizeFrameRequest(request, {
-				defaultAction: auth?.defaultAction ?? "deny",
-				onGuardError: (error) => console.error("[ilha-router] frame guard failed:", error)
-			})
-		});
-		if (!authorized.ok) return yield* Effect.fail(frameFail(authorized.status));
-		let id;
-		let framePath = "/";
-		let incomingProps;
-		{
-			const text = yield* Effect.tryPromise({
-				catch: () => frameFail(400),
-				try: () => readBodyBounded(request, MAX_BODY)
-			});
-			if (text === null) return yield* Effect.fail(frameFail(413));
+};
+const ensureScope = () => {
+	const g = globalThis;
+	const existing = g[REQUEST_ALS_KEY];
+	if (existing && "getStore" in existing) return existing;
+	const scope = { getStore: () => (alsBypassForTests ? void 0 : innerAls.getStore()) ?? syncStore ?? void 0 };
+	g[REQUEST_ALS_KEY] = scope;
+	return scope;
+};
+const runScoped = (request, oxide, fn) => innerAls.run(request, () => oxide ? oxide(request, fn) : fn());
+/**
+* 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.
+*
+* On WebContainer the return is always a `Promise` (fallback lock). Elsewhere
+* the return matches `fn` (sync or async).
+*/
+const runWithIslandRequest = (request, fn) => {
+	ensureScope();
+	const oxideSlot = globalThis[OXIDE_RUN_WITH_REQUEST];
+	const oxide = oxideSlot === void 0 ? void 0 : oxideSlot;
+	if (!inWebcontainer()) return runScoped(request, oxide, fn);
+	return withFallbackEntry(async () => {
+		const previous = syncStore;
+		syncStore = request;
+		try {
+			syncNestDepth += 1;
+			let result;
 			try {
-				const body = JSON.parse(text);
-				id = String(body.id ?? "");
-				incomingProps = parseFrameProps(body.props);
-				if (isString(body.path)) {
-					if (!isSafeFramePath(body.path)) return yield* Effect.fail(frameFail(400));
-					framePath = body.path;
-				}
-			} catch {
-				return yield* Effect.fail(frameFail(400));
+				result = runScoped(request, oxide, fn);
+			} finally {
+				syncNestDepth -= 1;
 			}
+			return await Promise.resolve(result);
+		} finally {
+			syncStore = previous;
 		}
-		const scoped = new Request(frameScopedUrl(url.href, framePath), {
-			headers: forwardIdentityHeaders(request.headers),
-			method: "POST"
-		});
-		copyFrameworkSymbols(request, scoped);
-		const html = yield* renderServerIsland(id, scoped, (scopedRequest, fn) => Promise.resolve(runWithIslandRequest(scopedRequest, fn)), incomingProps);
-		return json(200, { html });
 	});
-	return await Effect.runPromise(Effect.map(Effect.result(program), Result.match({
-		onFailure: (error) => {
-			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" });
-		},
-		onSuccess: (response) => response
-	})));
 };
-const ssrWithImports = Object.assign(ssr, { imports: ["ilha:pages/server"] });
 
 //#endregion
-export { runWithIslandRequest as C, ssrWithImports as S, registerServerIsland as _, authorizeFrameRequest as a, setFrameAuth as b, frameScopedUrl as c, getServerIslandEntry as d, isSafeFramePath as f, readBodyBounded as g, parseFrameProps as h, __ilhaServerAction as i, getFrameAuth as l, json as m, FrameError as n, forwardIdentityHeaders as o, isTrustedOrigin as p, MAX_BODY as r, frameEnvelope as s, FRAME_ENDPOINT as t, getFrameGuard as u, renderServerIsland as v, setFrameGuard as x, renderServerIslandResult as y };
+export { registerServerIsland as _, authorizeFrameRequest as a, setFrameAuth as b, frameScopedUrl as c, getServerIslandEntry as d, isSafeFramePath as f, readBodyBounded as g, parseFrameProps as h, MAX_BODY as i, getFrameAuth as l, json as m, FRAME_ENDPOINT as n, forwardIdentityHeaders as o, isTrustedOrigin as p, FrameError as r, frameEnvelope as s, runWithIslandRequest as t, getFrameGuard as u, renderServerIsland as v, setFrameGuard as x, renderServerIslandResult as y };

package/dist/rsbuild.js

@@ -1,4 +1,4 @@
-import { t as ilhaPages } from "./plugin-Ci-W2rMt.js";
+import { t as ilhaPages } from "./plugin-Cn_H92L0.js";
 
 //#region src/rsbuild.ts
 /** Rsbuild plugin — use via `@ilha/router/rsbuild`. */

package/dist/ssr.d.ts

@@ -12,150 +12,14 @@
  * 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.
- */
-import * as Effect from "effect/Effect";
-import * as Result from "effect/Result";
-import type { SnapshotObject, SnapshotValue } from "./snapshot";
-/** JSON payload for frame envelopes. */
-export type FrameJsonValue = string | number | boolean | null | FrameJsonValue[] | FrameJsonObject;
-export interface FrameJsonObject {
-    readonly [key: string]: FrameJsonValue | undefined;
-}
-/** A frame render: optionally preceded by running the page's `load`. */
-export interface ServerIslandEntry {
-    /** Returns the renderState fn (`Symbol.for("ilha.renderState")` getter). */
-    render: () => ServerIslandRenderFn;
-}
-export type ServerIslandRenderFn = (props?: SnapshotObject) => string | Promise<string> | object;
-export type FrameGuard = (request: Request) => Response | undefined | Promise<Response | undefined>;
-/**
- * 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 const setFrameGuard: (guard: FrameGuard) => void;
-export declare const getFrameGuard: () => 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 const setFrameAuth: (policy: FrameAuthPolicy) => void;
-export declare const 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 const 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 const isSafeFramePath: (framePath: string) => boolean;
-/**
- * Build the scoped frame render URL from the incoming request URL and frame
- * path. Absolute `incomingUrl` values supply the origin. Relative values (for
- * example Vite's `req.url`) require an explicit trusted `serverOrigin` — never
- * a client `Host` header.
- */
-export declare const frameScopedUrl: (incomingUrl: string, framePath: string, serverOrigin?: string) => string;
-type HeaderSource = Headers | Readonly<Record<string, string | string[] | undefined>>;
-/**
- * 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 const forwardIdentityHeaders: (source: HeaderSource) => 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 const frameEnvelope: (status: number, body: FrameJsonObject) => FrameEnvelope;
-/** Brand an exported server action with its generated RPC transport key. */
-export declare const __ilhaServerAction: <A extends SnapshotValue[], R>(key: string, fn: (...args: A) => R | Promise<R>) => import("oxidejs").ServerActionHandle<A, Awaited<Awaited<R>>>;
-export declare const registerServerIsland: (id: string, render: () => ServerIslandRenderFn) => void;
-export declare const getServerIslandEntry: (id: string) => ServerIslandEntry | undefined;
-declare const FrameError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
-    readonly _tag: "FrameError";
-} & Readonly<A>;
-/** Client-facing frame failure. `redirect` carries a same-origin redirect target. */
-export declare class FrameError extends FrameError_base<{
-    status: number;
-    message?: string;
-    redirect?: string;
-}> {
-}
-/**
- * Render a registered server island. Typed error channel: the only failure is
- * `FrameError`; everything else is a defect surfaced as a 400 to the client.
- */
-export declare const renderServerIsland: (id: string, request: Request, runWithScope: <T>(request: Request, fn: () => T) => T | Promise<T>, incomingProps?: SnapshotObject) => Effect.Effect<string, FrameError>;
-/** Convenience for non-Effect callers: run the render and resolve to a Result. */
-export declare const renderServerIslandResult: (id: string, request: Request, runWithScope: <T>(request: Request, fn: () => T) => T | Promise<T>, incomingProps?: SnapshotObject) => Promise<Result.Result<string, FrameError>>;
-export declare const FRAME_ENDPOINT = "/__ilha/frame";
-/** Max request body size — matches the dev middleware cap. */
-export declare const MAX_BODY: number;
-/** Parent-island props on a frame POST. Missing is fine; anything else is 400. */
-export declare const parseFrameProps: <T>(value?: T) => SnapshotObject | undefined;
-export declare const json: (status: number, body: FrameJsonObject) => Response;
-/**
- * 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.
- */
-export declare const 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.
+ * Frame helpers live in `./frame` (no oxidejs). `__ilhaServerAction` lives in
+ * `./oxide-action` so `@ilha/router/vite` can load the pages plugin without
+ * the optional oxide peer.
  */
-export declare const authorizeFrameRequest: (request: Request, options: {
-    defaultAction: "open" | "deny";
-    onGuardError?: <E>(error: E) => void;
-}) => Promise<{
-    ok: true;
-    identityHeaders: Headers;
-} | {
-    ok: false;
-    status: number;
-}>;
+export { FRAME_ENDPOINT, FrameError, MAX_BODY, authorizeFrameRequest, forwardIdentityHeaders, frameEnvelope, frameScopedUrl, getFrameAuth, getFrameGuard, getServerIslandEntry, isSafeFramePath, isTrustedOrigin, json, parseFrameProps, readBodyBounded, registerServerIsland, renderServerIsland, renderServerIslandResult, setFrameAuth, setFrameGuard, } from "./frame";
+export type { FrameAuthPolicy, FrameEnvelope, FrameGuard, FrameJsonObject, FrameJsonValue, ServerIslandEntry, ServerIslandRenderFn, } from "./frame";
+export { __ilhaServerAction } from "./oxide-action";
 /** Side-effect imports required alongside this handler. */
 interface SsrMiddleware {
     (request: Request): Promise<Response | undefined>;

package/dist/ssr.js

@@ -1,3 +1,118 @@
-import { S as ssrWithImports, _ as registerServerIsland, a as authorizeFrameRequest, b as setFrameAuth, c as frameScopedUrl, d as getServerIslandEntry, f as isSafeFramePath, g as readBodyBounded, h as parseFrameProps, i as __ilhaServerAction, l as getFrameAuth, m as json, n as FrameError, o as forwardIdentityHeaders, p as isTrustedOrigin, r as MAX_BODY, s as frameEnvelope, t as FRAME_ENDPOINT, u as getFrameGuard, v as renderServerIsland, x as setFrameGuard, y as renderServerIslandResult } from "./ssr-D9q5C-OV.js";
+import { _ as registerServerIsland, a as authorizeFrameRequest, b as setFrameAuth, c as frameScopedUrl, d as getServerIslandEntry, f as isSafeFramePath, g as readBodyBounded, h as parseFrameProps, i as MAX_BODY, l as getFrameAuth, m as json, n as FRAME_ENDPOINT, o as forwardIdentityHeaders, p as isTrustedOrigin, r as FrameError, s as frameEnvelope, t as runWithIslandRequest, u as getFrameGuard, v as renderServerIsland, x as setFrameGuard, y as renderServerIslandResult } from "./request-scope-CI9BJVS-.js";
+import * as Result from "effect/Result";
+import * as Effect from "effect/Effect";
+import { action, brandServerAction } from "oxidejs";
 
+//#region src/oxide-action.ts
+/**
+* Oxide-branded server-action wrapper.
+*
+* Lives in its own module so `@ilha/router/vite` / the pages plugin can load
+* frame helpers without resolving the optional `oxidejs` peer.
+*/
+/** Brand an exported server action with its generated RPC transport key. */
+const __ilhaServerAction = (key, fn) => {
+	const handle = fn.$$atom === 1 ? fn : action(fn);
+	return brandServerAction(key, handle);
+};
+
+//#endregion
+//#region src/ssr.ts
+/**
+* Production SSR endpoint for server-owned islands.
+*
+* 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.
+*
+* Frame helpers live in `./frame` (no oxidejs). `__ilhaServerAction` lives in
+* `./oxide-action` so `@ilha/router/vite` can load the pages plugin without
+* the optional oxide peer.
+*/
+const objectTag = (value) => Object.prototype.toString.call(value);
+const isString = (value) => objectTag(value) === "[object String]";
+const copyFrameworkSymbols = (from, to) => {
+	for (const sym of Object.getOwnPropertySymbols(from)) {
+		if (Symbol.keyFor(sym) === void 0) continue;
+		const desc = Object.getOwnPropertyDescriptor(from, sym);
+		if (!desc) continue;
+		try {
+			Object.defineProperty(to, sym, desc);
+		} catch {}
+	}
+};
+const frameFail = (status, message) => new FrameError({
+	message: message ?? "frame failed",
+	status
+});
+const ssr = async (request) => {
+	let url;
+	try {
+		url = new URL(request.url);
+	} catch {
+		return json(400, { error: "frame failed" });
+	}
+	if (url.pathname !== "/__ilha/frame") return;
+	const program = Effect.gen(function* handleFrame() {
+		const auth = getFrameAuth();
+		if (!isTrustedOrigin(request, auth)) return yield* Effect.fail(frameFail(403));
+		if (request.method !== "POST") return yield* Effect.fail(frameFail(405));
+		if (!(request.headers.get("content-type") ?? "").startsWith("application/json")) return yield* Effect.fail(frameFail(415));
+		const authorized = yield* Effect.tryPromise({
+			catch: () => frameFail(403),
+			try: () => authorizeFrameRequest(request, {
+				defaultAction: auth?.defaultAction ?? "deny",
+				onGuardError: (error) => console.error("[ilha-router] frame guard failed:", error)
+			})
+		});
+		if (!authorized.ok) return yield* Effect.fail(frameFail(authorized.status));
+		let id;
+		let framePath = "/";
+		let incomingProps;
+		{
+			const text = yield* Effect.tryPromise({
+				catch: () => frameFail(400),
+				try: () => readBodyBounded(request, MAX_BODY)
+			});
+			if (text === null) return yield* Effect.fail(frameFail(413));
+			try {
+				const body = JSON.parse(text);
+				id = String(body.id ?? "");
+				incomingProps = parseFrameProps(body.props);
+				if (isString(body.path)) {
+					if (!isSafeFramePath(body.path)) return yield* Effect.fail(frameFail(400));
+					framePath = body.path;
+				}
+			} catch {
+				return yield* Effect.fail(frameFail(400));
+			}
+		}
+		const scoped = new Request(frameScopedUrl(url.href, framePath), {
+			headers: forwardIdentityHeaders(request.headers),
+			method: "POST"
+		});
+		copyFrameworkSymbols(request, scoped);
+		const html = yield* renderServerIsland(id, scoped, (scopedRequest, fn) => Promise.resolve(runWithIslandRequest(scopedRequest, fn)), incomingProps);
+		return json(200, { html });
+	});
+	return await Effect.runPromise(Effect.map(Effect.result(program), Result.match({
+		onFailure: (error) => {
+			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" });
+		},
+		onSuccess: (response) => response
+	})));
+};
+const ssrWithImports = Object.assign(ssr, { imports: ["ilha:pages/server"] });
+
+//#endregion
 export { FRAME_ENDPOINT, FrameError, MAX_BODY, __ilhaServerAction, authorizeFrameRequest, ssrWithImports as default, forwardIdentityHeaders, frameEnvelope, frameScopedUrl, getFrameAuth, getFrameGuard, getServerIslandEntry, isSafeFramePath, isTrustedOrigin, json, parseFrameProps, readBodyBounded, registerServerIsland, renderServerIsland, renderServerIslandResult, setFrameAuth, setFrameGuard };

package/dist/vite.js

@@ -1,4 +1,4 @@
-import { t as ilhaPages } from "./plugin-Ci-W2rMt.js";
+import { t as ilhaPages } from "./plugin-Cn_H92L0.js";
 
 //#region src/vite.ts
 /** Vite plugin — use via `@ilha/router/vite`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ilha/router",
-  "version": "0.11.6",
+  "version": "0.11.8",
   "description": "A tiny SPA router for Ilha",
   "keywords": [
     "frontend",
@@ -73,12 +73,12 @@
     "unplugin": "3.3.0"
   },
   "devDependencies": {
-    "ilha": "^0.14.4",
+    "ilha": "^0.14.5",
     "oxidejs": "^0.3.2",
     "vite": "^8.2.2"
   },
   "peerDependencies": {
-    "ilha": ">=0.14.4",
+    "ilha": ">=0.14.5",
     "oxidejs": ">=0.3.2"
   },
   "peerDependenciesMeta": {