@nikolasp98/plugin-ui-bridge

postMessage protocol bridge between Minion plugin UIs (sandboxed iframes) and the hub host that mounts them. Ships the shared message types, the PluginBridge (plugin/iframe side), and a small HostBridge reference (the hub keeps its own richer host implementation).

What it provides

• Typed message contract — HostToPlugin / PluginToHost discriminated unions covering hello, theme/locale propagation, host-forwarded RPC, dirty state, and host-driven save.
• PluginBridge — the iframe-side client. Handles the handshake, exposes call() for gateway RPC forwarded through the host's privileged WebSocket, and surfaces theme/locale/save events.
• BRIDGE_PROTOCOL_VERSION — the bridge protocol version. Both sides advertise it in the handshake (host:hello.protocolVersion / plugin:ready.protocolVersion) so a peer can detect a mismatch instead of silently mis-parsing. This is distinct from the gateway WS frame protocol (hello-ok.protocol). Absent ⇒ treated as version 1 (backward-compatible).

Usage (plugin side)

import { PluginBridge, BRIDGE_PROTOCOL_VERSION } from "@nikolasp98/plugin-ui-bridge";

const bridge = new PluginBridge({
  self: window,
  parent: window.parent,
  expectedHostOrigin: "*", // or the resolved hub origin
});

bridge.onHello((hello) => {
  applyTheme(hello.theme, hello.tokens);
  setLocale(hello.locale ?? "en");
  // hello.protocolVersion (or bridge.hostProtocolVersion) tells you what the
  // host speaks; compare against BRIDGE_PROTOCOL_VERSION if you need a feature.
});

bridge.notifyReady(); // advertises BRIDGE_PROTOCOL_VERSION to the host

const result = await bridge.call("plugins.config.get", { pluginId: "my-plugin" });

Versioning

Semver, independent of the gateway. Bump the major/minor and BRIDGE_PROTOCOL_VERSION together on any breaking change to the message shapes.