/** * Plugin host: the `window.registerKandevPlugin` global + the loader that * imports plugin bundles from the boot payload (docs/plans/plugins/PLUGIN-API.md). * * Loading sequence per bundle: inject `styleUrls` as `` tags, dynamically * `import(/* @vite-ignore *\/ bundleUrl)` the bundle (module-level side effect * calls `window.registerKandevPlugin`), then call the registered plugin's * `initialize(registry, host)`. A bad plugin (throwing bundle, missing * registration, or throwing `initialize`) is logged and swallowed — it never * breaks boot or blocks other plugins. */ import { pluginRegistry } from "./registry"; import type { ActivePlugin, KandevPlugin, PluginHostApi } from "./types"; /** Builds the per-plugin `PluginHostApi` for a given pluginId. */ export type PluginHostFactory = (pluginId: string) => PluginHostApi; /** Injectable bundle loader — defaults to a real dynamic import. Tests pass a fake. */ export type BundleImporter = (url: string) => Promise; const defaultImporter: BundleImporter = (url) => import(/* @vite-ignore */ url); type PluginGlobalWindow = Window & { registerKandevPlugin?: (id: string, plugin: KandevPlugin) => void; }; /** Bundles registered via `window.registerKandevPlugin`, keyed by pluginId. */ const registeredPlugins = new Map(); /** Defines `window.registerKandevPlugin` before any bundle loads. Idempotent. */ export function installPluginGlobal(win: Window = window): void { (win as PluginGlobalWindow).registerKandevPlugin = (id, plugin) => { registeredPlugins.set(id, plugin); }; } /** * Loads every plugin from the boot payload: injects styles, imports the * bundle, then runs `initialize(registry, host)`. Each plugin is isolated — * a failure anywhere in its load path is logged and does not affect the * others or the boot sequence. */ export async function loadPlugins( bootPlugins: ActivePlugin[], hostFactory: PluginHostFactory, importer: BundleImporter = defaultImporter, win: Window = window, ): Promise { installPluginGlobal(win); for (const plugin of bootPlugins) { await loadPlugin(plugin, hostFactory, importer); } } async function loadPlugin( plugin: ActivePlugin, hostFactory: PluginHostFactory, importer: BundleImporter, ): Promise { try { injectStyles(plugin.styleUrls); await importer(plugin.bundleUrl); const registered = registeredPlugins.get(plugin.id); if (!registered) { console.error(`[plugins] "${plugin.id}" bundle did not call registerKandevPlugin`); return; } const host = hostFactory(plugin.id); const registry = pluginRegistry.forPlugin(plugin.id); await registered.initialize(registry, host); } catch (error) { console.error(`[plugins] failed to load plugin "${plugin.id}"`, error); } } function injectStyles(styleUrls: string[] | undefined): void { if (!styleUrls) return; for (const href of styleUrls) { const link = document.createElement("link"); link.rel = "stylesheet"; link.href = href; document.head.appendChild(link); } } /** Disables a plugin: calls `destroy?.()` then bulk-revokes its registrations. */ export function unloadPlugin(id: string): void { const plugin = registeredPlugins.get(id); try { plugin?.destroy?.(); } catch (error) { console.error(`[plugins] error destroying plugin "${id}"`, error); } finally { pluginRegistry.unregisterPlugin(id); registeredPlugins.delete(id); } }