@abraca/plugin 2.3.0

package/src/registry.ts

@@ -0,0 +1,287 @@
+/**
+ * `PluginRegistry` — the host-side manager for `AbraPlugin` instances.
+ *
+ * One registry per host (cou-shell, an `@abraca/nuxt` app, …). Generic over
+ * the plugin type so apps that narrow `AbraPlugin` to their own interface
+ * (e.g. `CouPlugin`, `AbracadabraPlugin`) get correctly-typed aggregator
+ * methods without casts.
+ *
+ * Two tiers:
+ *
+ * - **Built-in plugins**: registered before `freeze()`. Frozen at boot;
+ *   `register()` after that point logs a warning and returns.
+ * - **Space plugins**: registered/unregistered any time. Reactive consumers
+ *   poll `getSpacePluginVersion()` to detect changes.
+ *
+ * Aggregator methods return contributions from both tiers in registration
+ * order, built-ins first.
+ */
+
+import type {
+	AbraPlugin,
+	AbraTiptapExtension,
+	EditorPluginCtx,
+	DragHandlePluginCtx,
+	CommandPaletteCtx,
+	AbraMentionProvider,
+	AbraAwarenessContribution,
+	AbraNodePanelSlot,
+	AbraSettingsPanel,
+	AbraKeyboardShortcut,
+	AbraCommandItem,
+} from "./types.ts";
+
+// ── Type helpers for narrowed plugin generics ─────────────────────────────────
+
+/** Extract the value type from a `Record<string, V>`-shaped optional field. */
+type RecordValueOf<T> = T extends Record<string, infer V> ? V : never;
+
+/** Extract the item type from a `(ctx) => readonly (readonly T[])[]` field. */
+type GroupedItemOf<T> = T extends
+	(...args: never[]) => readonly (infer Group)[]
+	? Group extends readonly (infer Item)[]
+		? Item
+		: never
+	: never;
+
+/** Extract the array element type from an optional array field. */
+type ElementOf<T> = T extends readonly (infer V)[] ? V : never;
+
+/** Result-shape of `commandPaletteItems` collapsed to its item type. */
+type CommandItemOf<T> = T extends
+	(...args: never[]) => infer R
+	? R extends Promise<readonly (infer Item)[]>
+		? Item
+		: R extends readonly (infer Item)[]
+			? Item
+			: never
+	: never;
+
+// ── Aggregator return types — derived from the plugin generic ─────────────────
+
+type PageTypeOf<P> = P extends { pageTypes?: infer R } ? RecordValueOf<R> : never;
+type CustomHandlerOf<P> = P extends { customHandlers?: () => infer R } ? R : never;
+type ToolbarItemOf<P> = P extends { toolbarItems?: infer F } ? GroupedItemOf<F> : never;
+type BubbleItemOf<P> = P extends { bubbleMenuItems?: infer F } ? GroupedItemOf<F> : never;
+type SuggestionItemOf<P> = P extends { suggestionItems?: infer F } ? GroupedItemOf<F> : never;
+type DragHandleItemOf<P> = P extends { dragHandleItems?: infer F } ? GroupedItemOf<F> : never;
+type MentionProviderOf<P> = P extends { mentionProviders?: infer A }
+	? ElementOf<A>
+	: never;
+type AwarenessContributionOf<P> = P extends { awarenessContributions?: infer A }
+	? ElementOf<A>
+	: never;
+type CommandPaletteItemOf<P> = P extends { commandPaletteItems?: infer F }
+	? CommandItemOf<F>
+	: never;
+type NodePanelSlotOf<P> = P extends { nodePanelSlots?: infer A } ? ElementOf<A> : never;
+type SettingsPanelOf<P> = P extends { settingsPanel?: infer V } ? NonNullable<V> : never;
+type KeyboardShortcutOf<P> = P extends { keyboardShortcuts?: infer A } ? ElementOf<A> : never;
+
+// ── Registry implementation ───────────────────────────────────────────────────
+
+export class PluginRegistry<P extends AbraPlugin = AbraPlugin> {
+	private _builtins: P[] = [];
+	private _spacePlugins: P[] = [];
+	private _frozen = false;
+	private _spaceVersion = 0;
+
+	/**
+	 * Register a built-in plugin. No-ops with a warning after `freeze()`.
+	 * Use `registerSpacePlugin()` for plugins that arrive after boot.
+	 */
+	register(plugin: P): void {
+		if (this._frozen) {
+			console.warn(
+				`[@abraca/plugin] Registry frozen — cannot register "${plugin.name}". Use registerSpacePlugin() for post-boot plugins.`,
+			);
+			return;
+		}
+		if (this._builtins.some((p) => p.name === plugin.name)) {
+			console.warn(
+				`[@abraca/plugin] Plugin "${plugin.name}" already registered`,
+			);
+			return;
+		}
+		this._builtins.push(plugin);
+	}
+
+	/** Lock the registry. Called once after all built-in + external plugins are loaded. */
+	freeze(): void {
+		this._frozen = true;
+	}
+
+	isFrozen(): boolean {
+		return this._frozen;
+	}
+
+	/** Reactive registration channel for space-driven plugins (bypasses freeze). */
+	registerSpacePlugin(plugin: P): void {
+		if (
+			this._spacePlugins.some((p) => p.name === plugin.name) ||
+			this._builtins.some((p) => p.name === plugin.name)
+		) {
+			console.warn(
+				`[@abraca/plugin] Plugin "${plugin.name}" already registered`,
+			);
+			return;
+		}
+		this._spacePlugins.push(plugin);
+		this._spaceVersion++;
+	}
+
+	unregisterSpacePlugin(name: string): void {
+		const idx = this._spacePlugins.findIndex((p) => p.name === name);
+		if (idx === -1) return;
+		this._spacePlugins.splice(idx, 1);
+		this._spaceVersion++;
+	}
+
+	clearSpacePlugins(): void {
+		if (this._spacePlugins.length === 0) return;
+		this._spacePlugins.length = 0;
+		this._spaceVersion++;
+	}
+
+	/** Monotonically increasing counter — bump when space plugins change. */
+	getSpacePluginVersion(): number {
+		return this._spaceVersion;
+	}
+
+	getBuiltinPlugins(): readonly P[] {
+		return this._builtins;
+	}
+
+	getSpacePlugins(): readonly P[] {
+		return this._spacePlugins;
+	}
+
+	/** All active plugins — built-ins first, then space plugins. */
+	getPlugins(): readonly P[] {
+		return [...this._builtins, ...this._spacePlugins];
+	}
+
+	// ── Aggregators ──────────────────────────────────────────────────────────
+
+	getAllExtensions(): AbraTiptapExtension[] {
+		return this.getPlugins().flatMap((p) => p.extensions?.() ?? []);
+	}
+
+	getServerExtensions(): AbraTiptapExtension[] {
+		return this.getPlugins().flatMap((p) => p.serverExtensions?.() ?? []);
+	}
+
+	/** Resolves once every plugin with `extensionsReady` has settled. */
+	async waitForExtensions(): Promise<void> {
+		await Promise.all(
+			this.getPlugins().map((p) => p.extensionsReady ?? Promise.resolve()),
+		);
+	}
+
+	getAllPageTypes(): Record<string, PageTypeOf<P>> {
+		const merged: Record<string, PageTypeOf<P>> = {};
+		for (const p of this.getPlugins()) {
+			if (p.pageTypes) {
+				Object.assign(merged, p.pageTypes as Record<string, PageTypeOf<P>>);
+			}
+		}
+		return merged;
+	}
+
+	getAllCustomHandlers(): CustomHandlerOf<P> {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const merged: Record<string, any> = {};
+		for (const p of this.getPlugins()) {
+			if (p.customHandlers) Object.assign(merged, p.customHandlers());
+		}
+		return merged as CustomHandlerOf<P>;
+	}
+
+	getAllToolbarItems(ctx: EditorPluginCtx): ToolbarItemOf<P>[][] {
+		return this.getPlugins().flatMap(
+			(p) =>
+				(p.toolbarItems?.(ctx) ?? []) as readonly (readonly ToolbarItemOf<P>[])[],
+		) as ToolbarItemOf<P>[][];
+	}
+
+	getAllBubbleMenuItems(ctx: EditorPluginCtx): BubbleItemOf<P>[][] {
+		return this.getPlugins().flatMap(
+			(p) =>
+				(p.bubbleMenuItems?.(ctx) ?? []) as readonly (readonly BubbleItemOf<P>[])[],
+		) as BubbleItemOf<P>[][];
+	}
+
+	getAllSuggestionItems(ctx: EditorPluginCtx): SuggestionItemOf<P>[][] {
+		return this.getPlugins().flatMap(
+			(p) =>
+				(p.suggestionItems?.(ctx) ?? []) as readonly (readonly SuggestionItemOf<P>[])[],
+		) as SuggestionItemOf<P>[][];
+	}
+
+	getAllDragHandleItems(ctx: DragHandlePluginCtx): DragHandleItemOf<P>[][] {
+		return this.getPlugins().flatMap(
+			(p) =>
+				(p.dragHandleItems?.(ctx) ?? []) as readonly (readonly DragHandleItemOf<P>[])[],
+		) as DragHandleItemOf<P>[][];
+	}
+
+	getAllMentionProviders(): MentionProviderOf<P>[] {
+		return this.getPlugins().flatMap(
+			(p) => (p.mentionProviders ?? []) as unknown as readonly MentionProviderOf<P>[],
+		) as MentionProviderOf<P>[];
+	}
+
+	getAllAwarenessContributions(): AwarenessContributionOf<P>[] {
+		return this.getPlugins().flatMap(
+			(p) => (p.awarenessContributions ?? []) as unknown as readonly AwarenessContributionOf<P>[],
+		) as AwarenessContributionOf<P>[];
+	}
+
+	async getAllCommandPaletteItems(
+		ctx: CommandPaletteCtx,
+	): Promise<CommandPaletteItemOf<P>[]> {
+		const results = await Promise.all(
+			this.getPlugins()
+				.filter((p) => p.commandPaletteItems)
+				.map((p) => Promise.resolve(p.commandPaletteItems!(ctx))),
+		);
+		const flat = results.flat() as CommandPaletteItemOf<P>[];
+		return flat.filter((item) => {
+			const w = (item as AbraCommandItem).when;
+			return !w || w(ctx);
+		});
+	}
+
+	getAllNodePanelSlots(): NodePanelSlotOf<P>[] {
+		return this.getPlugins().flatMap(
+			(p) => (p.nodePanelSlots ?? []) as unknown as readonly NodePanelSlotOf<P>[],
+		) as NodePanelSlotOf<P>[];
+	}
+
+	getSettingsPanels(): SettingsPanelOf<P>[] {
+		return this.getPlugins()
+			.map((p) => p.settingsPanel)
+			.filter((v): v is NonNullable<typeof v> => v !== undefined) as SettingsPanelOf<P>[];
+	}
+
+	getAllKeyboardShortcuts(): KeyboardShortcutOf<P>[] {
+		return this.getPlugins().flatMap(
+			(p) => (p.keyboardShortcuts ?? []) as unknown as readonly KeyboardShortcutOf<P>[],
+		) as KeyboardShortcutOf<P>[];
+	}
+}
+
+// ── Re-export aggregator types so consumer-side aliases can name them ─────────
+
+export type {
+	AbraPlugin,
+	EditorPluginCtx,
+	DragHandlePluginCtx,
+	CommandPaletteCtx,
+	AbraMentionProvider,
+	AbraAwarenessContribution,
+	AbraNodePanelSlot,
+	AbraSettingsPanel,
+	AbraKeyboardShortcut,
+	AbraCommandItem,
+};

package/src/sandbox.ts

@@ -0,0 +1,381 @@
+/**
+ * Iframe-based sandbox for external plugins.
+ *
+ * Plugins from outside the built-in set are loaded into a sandboxed
+ * `<iframe sandbox="allow-scripts">` — same origin restricted to the
+ * iframe's null origin, no access to the parent's globals, no cookies,
+ * no localStorage. The plugin module evaluates inside the iframe and
+ * communicates back via `postMessage`.
+ *
+ * The host side of the bridge (this file) exposes the same surface as
+ * `createPluginHost(manifest)` — fetch, clipboard, notifications —
+ * gated by the same manifest capabilities. The difference: in Phase F
+ * the contract was advisory (a plugin could grab `globalThis.fetch`);
+ * here the iframe doesn't have access to those globals at all, so the
+ * only path is through `postMessage`.
+ *
+ * Wire protocol (versioned via `v: 1` envelope):
+ *
+ *   host → frame:
+ *     { v:1, kind:'init',    pluginId, capabilities, artifactUrl }
+ *     { v:1, kind:'fetch.response', id, ok, status, body }
+ *     { v:1, kind:'clipboard.response', id, value? }
+ *     { v:1, kind:'notification.response', id }
+ *     { v:1, kind:'error', id, message }
+ *
+ *   frame → host:
+ *     { v:1, kind:'ready' }
+ *     { v:1, kind:'fetch.request', id, url, init? }
+ *     { v:1, kind:'clipboard.read.request', id }
+ *     { v:1, kind:'clipboard.write.request', id, text }
+ *     { v:1, kind:'notification.request', id, title, options? }
+ *     { v:1, kind:'plugin.export', value }    // the plugin's default export
+ *     { v:1, kind:'plugin.error', message }
+ *
+ * Phase F.2 ships the host side only. The frame-side runtime that
+ * imports plugin bundles + speaks this protocol is `sandbox-runtime.ts`
+ * (sibling file).
+ */
+
+import {
+	CapabilityDenied,
+	matchesNetworkCapability,
+	type GuardedClipboard,
+	type GuardedFetch,
+	type GuardedNotifications,
+	type PluginHostOptions,
+} from "./host.ts";
+import type { PluginCapability, PluginManifest } from "./manifest.ts";
+
+/** Public result of `loadSandboxedPlugin` — what the host actually keeps. */
+export interface SandboxedPlugin {
+	/** Stable id from the manifest. */
+	pluginId: string;
+	/** Capabilities granted to this sandbox. */
+	capabilities: ReadonlySet<PluginCapability>;
+	/** The plugin's default export, copied across the postMessage boundary. */
+	exported: unknown;
+	/** Tear down: removes the iframe + closes the bridge. */
+	dispose(): void;
+}
+
+export interface SandboxOptions extends PluginHostOptions {
+	/**
+	 * Override the document the iframe attaches to. Tests inject a jsdom
+	 * document; production hosts use the default `document` global.
+	 */
+	doc?: Document;
+	/**
+	 * Hard timeout (ms) on the plugin's `ready` handshake. Defaults to
+	 * 10 s. Plugins that don't post `ready` within the window get the
+	 * sandbox torn down + a load failure.
+	 */
+	readyTimeoutMs?: number;
+}
+
+interface InboundEnvelope {
+	v: 1;
+	kind: string;
+	id?: string;
+	[k: string]: unknown;
+}
+
+/**
+ * Spin up a sandboxed iframe, load the plugin bundle inside it, wait
+ * for the plugin to post `ready`, then return a handle. The host bridges
+ * capability-gated APIs to the iframe via postMessage.
+ */
+export async function loadSandboxedPlugin(
+	manifest: Pick<PluginManifest, "id" | "capabilities">,
+	artifactUrl: string,
+	options: SandboxOptions = {},
+): Promise<SandboxedPlugin> {
+	const doc = options.doc ?? (typeof document !== "undefined" ? document : null);
+	if (!doc) {
+		throw new Error("loadSandboxedPlugin requires a Document — call from a browser context");
+	}
+
+	const granted = new Set<PluginCapability>([
+		...(manifest.capabilities.required ?? []),
+		...(manifest.capabilities.optional ?? []),
+	]);
+	const pluginId = manifest.id;
+
+	const iframe = doc.createElement("iframe");
+	// `allow-scripts` lets the plugin run; we deliberately omit
+	// `allow-same-origin` so the iframe has a null origin — it can't
+	// reach our cookies, localStorage, IndexedDB, or service worker.
+	iframe.setAttribute("sandbox", "allow-scripts");
+	iframe.setAttribute("aria-hidden", "true");
+	iframe.style.display = "none";
+	iframe.style.width = "0";
+	iframe.style.height = "0";
+	iframe.style.border = "0";
+
+	// The runtime that the plugin runs inside the frame. Imports the
+	// plugin bundle by URL, listens for messages, and proxies the
+	// gated APIs through postMessage.
+	const frameSrc = buildFrameSource(artifactUrl);
+	const blob = new Blob([frameSrc], { type: "text/html" });
+	iframe.src = URL.createObjectURL(blob);
+
+	doc.body.appendChild(iframe);
+
+	const pendingFetch = new Map<string, (resp: Response) => void>();
+	const pendingFetchErr = new Map<string, (err: Error) => void>();
+	const pendingClip = new Map<string, (v: unknown) => void>();
+	const pendingClipErr = new Map<string, (err: Error) => void>();
+	const pendingNotif = new Map<string, () => void>();
+	const pendingNotifErr = new Map<string, (err: Error) => void>();
+
+	let resolveReady!: (value: unknown) => void;
+	let rejectReady!: (err: Error) => void;
+	const ready = new Promise<unknown>((res, rej) => {
+		resolveReady = res;
+		rejectReady = rej;
+	});
+
+	const post = (envelope: Record<string, unknown>) => {
+		iframe.contentWindow?.postMessage({ v: 1, ...envelope }, "*");
+	};
+
+	const messageHandler = async (e: MessageEvent) => {
+		if (e.source !== iframe.contentWindow) return;
+		const msg = e.data as InboundEnvelope | null;
+		if (!msg || msg.v !== 1) return;
+
+		switch (msg.kind) {
+			case "ready": {
+				post({ kind: "init", pluginId, capabilities: [...granted], artifactUrl });
+				break;
+			}
+
+			case "plugin.export": {
+				resolveReady(msg.value);
+				break;
+			}
+
+			case "plugin.error": {
+				rejectReady(new Error(String(msg.message ?? "plugin failed to load")));
+				break;
+			}
+
+			case "fetch.request": {
+				const id = String(msg.id);
+				const url = String(msg.url);
+				const init = msg.init as RequestInit | undefined;
+				try {
+					const host = extractHost(url);
+					if (!host || !matchesNetworkCapability(granted, host)) {
+						throw new CapabilityDenied(
+							pluginId,
+							host ? `network:${host}` : "network",
+							"declare in capabilities.required or capabilities.optional",
+						);
+					}
+					const real = options.fetch ?? globalThis.fetch;
+					const resp = await real(url, init);
+					const body = await resp.text();
+					post({
+						kind: "fetch.response",
+						id,
+						ok: resp.ok,
+						status: resp.status,
+						body,
+					});
+				}
+				catch (err) {
+					post({ kind: "error", id, message: (err as Error).message });
+				}
+				break;
+			}
+
+			case "clipboard.read.request": {
+				const id = String(msg.id);
+				try {
+					if (!granted.has("clipboard:read")) {
+						throw new CapabilityDenied(pluginId, "clipboard:read");
+					}
+					const value = options.clipboard?.readText
+						? await options.clipboard.readText()
+						: typeof navigator !== "undefined" && navigator.clipboard?.readText
+							? await navigator.clipboard.readText()
+							: "";
+					post({ kind: "clipboard.response", id, value });
+				}
+				catch (err) {
+					post({ kind: "error", id, message: (err as Error).message });
+				}
+				break;
+			}
+
+			case "clipboard.write.request": {
+				const id = String(msg.id);
+				try {
+					if (!granted.has("clipboard:write")) {
+						throw new CapabilityDenied(pluginId, "clipboard:write");
+					}
+					const text = String(msg.text ?? "");
+					if (options.clipboard?.writeText) await options.clipboard.writeText(text);
+					else if (typeof navigator !== "undefined" && navigator.clipboard?.writeText) {
+						await navigator.clipboard.writeText(text);
+					}
+					post({ kind: "clipboard.response", id });
+				}
+				catch (err) {
+					post({ kind: "error", id, message: (err as Error).message });
+				}
+				break;
+			}
+
+			case "notification.request": {
+				const id = String(msg.id);
+				try {
+					if (!granted.has("notifications:show")) {
+						throw new CapabilityDenied(pluginId, "notifications:show");
+					}
+					const title = String(msg.title ?? "");
+					const opts = msg.options as NotificationOptions | undefined;
+					if (options.showNotification) await options.showNotification(title, opts);
+					else if (typeof Notification !== "undefined") new Notification(title, opts);
+					post({ kind: "notification.response", id });
+				}
+				catch (err) {
+					post({ kind: "error", id, message: (err as Error).message });
+				}
+				break;
+			}
+		}
+	};
+
+	(typeof window !== "undefined" ? window : (doc.defaultView as Window))
+		?.addEventListener("message", messageHandler);
+
+	const timeoutMs = options.readyTimeoutMs ?? 10_000;
+	const timeoutHandle = setTimeout(
+		() => rejectReady(new Error(`plugin '${pluginId}' did not become ready within ${timeoutMs}ms`)),
+		timeoutMs,
+	);
+
+	let exported: unknown;
+	try {
+		exported = await ready;
+	}
+	catch (err) {
+		// Tear down on failure — never leak the iframe.
+		(typeof window !== "undefined" ? window : (doc.defaultView as Window))
+			?.removeEventListener("message", messageHandler);
+		iframe.remove();
+		URL.revokeObjectURL(iframe.src);
+		clearTimeout(timeoutHandle);
+		throw err;
+	}
+	clearTimeout(timeoutHandle);
+
+	// Drain any in-flight requests so they don't hang refs to disposed iframe.
+	const dispose = () => {
+		for (const reject of pendingFetchErr.values()) reject(new Error("sandbox disposed"));
+		for (const reject of pendingClipErr.values()) reject(new Error("sandbox disposed"));
+		for (const reject of pendingNotifErr.values()) reject(new Error("sandbox disposed"));
+		pendingFetch.clear();
+		pendingFetchErr.clear();
+		pendingClip.clear();
+		pendingClipErr.clear();
+		pendingNotif.clear();
+		pendingNotifErr.clear();
+		(typeof window !== "undefined" ? window : (doc.defaultView as Window))
+			?.removeEventListener("message", messageHandler);
+		iframe.remove();
+		URL.revokeObjectURL(iframe.src);
+	};
+
+	return {
+		pluginId,
+		capabilities: granted,
+		exported,
+		dispose,
+	};
+}
+
+// ── Helpers (shared with host.ts but inlined here to avoid export churn) ─────
+
+function extractHost(rawUrl: string): string | null {
+	try {
+		return new URL(rawUrl, "http://placeholder").host;
+	}
+	catch {
+		return null;
+	}
+}
+
+// ── Frame runtime ────────────────────────────────────────────────────────────
+
+/**
+ * HTML+JS that runs inside the iframe. Imports the plugin bundle by URL
+ * (in the iframe's null origin — no cookies, no localStorage), proxies
+ * fetch/clipboard/notifications back to the host via postMessage, and
+ * posts the plugin's default export once it loads.
+ *
+ * Kept inline so the package has zero runtime files — every consumer
+ * picks up the latest version on a single import.
+ */
+function buildFrameSource(artifactUrl: string): string {
+	// The frame's globals: a guarded `pluginHost` mirror, ready for
+	// plugins to import. The plugin code reads `globalThis.pluginHost`.
+	return `<!doctype html>
+<html><head><meta charset="utf-8"></head><body>
+<script type="module">
+const pending = new Map();
+let nextId = 0;
+function rpc(kind, payload) {
+  return new Promise((resolve, reject) => {
+    const id = String(++nextId);
+    pending.set(id, { resolve, reject });
+    parent.postMessage({ v: 1, kind, id, ...payload }, '*');
+  });
+}
+window.addEventListener('message', (e) => {
+  const msg = e.data;
+  if (!msg || msg.v !== 1) return;
+  if (msg.kind === 'init') {
+    globalThis.__abraPluginContext = {
+      pluginId: msg.pluginId,
+      capabilities: new Set(msg.capabilities),
+    };
+    return;
+  }
+  if (msg.id && pending.has(msg.id)) {
+    const { resolve, reject } = pending.get(msg.id);
+    pending.delete(msg.id);
+    if (msg.kind === 'error') reject(new Error(msg.message));
+    else resolve(msg);
+  }
+});
+globalThis.pluginHost = {
+  async fetch(url, init) {
+    const r = await rpc('fetch.request', { url: String(url), init });
+    return new Response(r.body, { status: r.status });
+  },
+  clipboard: {
+    readText() { return rpc('clipboard.read.request', {}).then(r => r.value); },
+    writeText(text) { return rpc('clipboard.write.request', { text }).then(() => undefined); },
+  },
+  notifications: {
+    show(title, options) { return rpc('notification.request', { title, options }).then(() => undefined); },
+  },
+};
+parent.postMessage({ v: 1, kind: 'ready' }, '*');
+try {
+  const mod = await import(${JSON.stringify(artifactUrl)});
+  const value = mod && (mod.default ?? mod);
+  // Strip functions before posting — they don't survive postMessage.
+  // We send the plain serialisable bits; functions stay in the iframe
+  // and the host calls them via separate RPC channels (future work).
+  const serialisable = JSON.parse(JSON.stringify(value, (_, v) =>
+    typeof v === 'function' ? '[Function]' : v));
+  parent.postMessage({ v: 1, kind: 'plugin.export', value: serialisable }, '*');
+} catch (e) {
+  parent.postMessage({ v: 1, kind: 'plugin.error', message: String((e && e.message) || e) }, '*');
+}
+</script></body></html>`;
+}