signalk-plotterext-bus 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joel Kozikowski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# signalk-plotterext-bus
+
+Reference implementation of the **Signal K plotter extension bus** — the
+message protocol between a chartplotter host application (e.g. Freeboard-SK)
+and extension iframes (panels, widgets, background runtimes) provided by
+Signal K server plugins via the `plotterExtensions` resource type.
+
+The **documented wire format below is the contract**; this package is a
+convenience. Any conforming implementation interoperates.
+
+## Install
+
+```sh
+npm install signalk-plotterext-bus
+```
+
+- Extensions import `signalk-plotterext-bus/extension`.
+- Hosts import `signalk-plotterext-bus/host`.
+
+## Wire Format
+
+Every message is a JSON-RPC 2.0 object inside a routing envelope, sent with
+`postMessage` (window-to-iframe or `MessageChannel`):
+
+```json
+{ "bus": "plotterExt/1", "msg": { "jsonrpc": "2.0", "...": "..." } }
+```
+
+The `bus` field identifies protocol and major version so frames can ignore
+unrelated `postMessage` traffic.
+
+### Calls
+
+A call is a JSON-RPC request with a fresh per-call correlation `id` (never
+correlate by method name — concurrent calls to the same method must not
+collide):
+
+```json
+{ "jsonrpc": "2.0", "id": "ab12-1", "method": "state.get", "params": { "keys": ["path"] } }
+```
+
+Exactly one response per request, `result` and `error` mutually exclusive:
+
+```json
+{ "jsonrpc": "2.0", "id": "ab12-1", "result": { "values": { "path": "navigation.speedOverGround" } } }
+{ "jsonrpc": "2.0", "id": "ab12-1", "error": { "code": -32602, "message": "…", "data": { "reason": "INVALID_PARAMS" } } }
+```
+
+Protocol errors use the JSON-RPC reserved codes (`-32601` method not found,
+`-32602` invalid params, `-32603` internal). Host API errors use
+implementation-defined codes (this package defaults to `-32000`) and put a
+stable string identifier in `error.data.reason`. Callers apply timeouts and
+discard the pending-call entry when one fires.
+
+### Events
+
+An event is a JSON-RPC *notification* (no `id`); its `method` is a
+hierarchical dot-separated event name:
+
+```json
+{ "jsonrpc": "2.0", "method": "sk.navigation.speedOverGround", "params": { "path": "navigation.speedOverGround", "value": 3.6 } }
+```
+
+`postMessage` is point-to-point, so hosts only forward events a context has
+subscribed to via `events.subscribe` / `events.unsubscribe`. Subscription
+patterns use eventemitter2-style wildcards: `*` matches exactly one segment,
+`**` matches zero or more segments (`map.*`, `sk.navigation.**`).
+
+### Connection establishment
+
+1. The extension sends the notification `bus.ready` (repeating every ~250 ms
+   until answered, in case the host attaches late).
+2. The host replies with the notification `bus.handshake`:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "bus.handshake",
+  "params": {
+    "host": "freeboard-sk",
+    "hostVersion": "2.14.0",
+    "apiVersion": "1",
+    "capabilities": ["widgets", "panels.iframe", "signalk.stream"],
+    "context": { "kind": "widget", "id": "gauge", "instanceId": "…", "targetInstance": null }
+  }
+}
+```
+
+### Built-in methods
+
+Implemented by `HostConnection` automatically:
+
+| Method | Params | Result |
+| --- | --- | --- |
+| `events.subscribe` | `{ patterns: string[] }` | `{ subscriptionId }` |
+| `events.unsubscribe` | `{ subscriptionId }` | `{}` |
+
+Host API methods (`state.*`, `signalk.*`, `map.*`, …) are supplied by the
+embedding host application; see the plotter extension specification for the
+vocabulary.
+
+## Usage — extension side
+
+```js
+import { connectExtension } from 'signalk-plotterext-bus/extension'
+
+const client = await connectExtension()
+console.log(client.context)           // { kind: 'widget', id: 'gauge', instanceId: '…' }
+
+// Per-instance configuration
+const { path } = await client.state.get(['path'])
+
+// Live Signal K data, relayed by the host
+const stop = await client.signalk.subscribe([path], (ev) => {
+  render(ev.value)
+})
+
+// React to configuration changes made by the config panel
+await client.subscribe(['state.changed'], async () => {
+  const values = await client.state.get()
+  reconfigure(values)
+})
+```
+
+## Usage — host side
+
+```js
+import { HostConnection, windowPort } from 'signalk-plotterext-bus/host'
+
+const conn = new HostConnection({
+  port: windowPort(iframe.contentWindow),
+  hostInfo: {
+    host: 'my-plotter',
+    hostVersion: '1.0.0',
+    apiVersion: '1',
+    capabilities: ['widgets', 'panels.iframe', 'signalk.stream']
+  },
+  context: { kind: 'widget', id: 'gauge', instanceId, targetInstance: null },
+  methods: {
+    'state.get': async ({ keys }) => ({ values: await loadState(instanceId, keys) }),
+    'state.set': async ({ values }) => { await saveState(instanceId, values) },
+    'signalk.subscribe': ({ paths }) => startRelay(conn, paths),
+    'signalk.unsubscribe': ({ subscriptionId }) => stopRelay(subscriptionId)
+  },
+  onSubscriptionsChanged: (patterns) => updateUpstream(patterns)
+})
+
+// Later, from the host's data stream:
+conn.publish('sk.navigation.speedOverGround', { path, value, timestamp })
+```
+
+Throw `RpcError` from method handlers to return structured errors:
+
+```js
+import { RpcError, RPC_ERRORS } from 'signalk-plotterext-bus/host'
+throw new RpcError('unknown path', { code: RPC_ERRORS.INVALID_PARAMS, reason: 'UNKNOWN_PATH' })
+```
+
+## Conformance testing
+
+The test suite drives a real `HostConnection` against a real
+`connectExtension()` over a `MessageChannel` pair with no DOM. A host
+implementing its own endpoint can reuse the same harness shape to verify
+conformance.
+
+```sh
+npm test
+```
+
+## License
+
+MIT

package/dist/chunk-EGWZMA5J.js

@@ -0,0 +1,159 @@
+import {
+  BusEndpoint,
+  EVENT_HANDSHAKE,
+  EVENT_READY,
+  RPC_ERRORS,
+  RpcError,
+  windowPort
+} from "./chunk-ZYQKQSOC.js";
+
+// src/extension.ts
+var ExtensionClient = class {
+  handshake;
+  endpoint;
+  constructor(endpoint, handshake) {
+    this.endpoint = endpoint;
+    this.handshake = handshake;
+  }
+  get context() {
+    return this.handshake.context;
+  }
+  get apiVersion() {
+    return this.handshake.apiVersion;
+  }
+  get capabilities() {
+    return this.handshake.capabilities;
+  }
+  hasCapability(id) {
+    return this.handshake.capabilities.includes(id);
+  }
+  /** Call a host API method. */
+  call(method, params, opts) {
+    return this.endpoint.call(method, params, opts);
+  }
+  /** Send a notification to the host. */
+  notify(method, params) {
+    this.endpoint.notify(method, params);
+  }
+  /**
+   * Subscribe to host events matching wildcard patterns. Registers both the
+   * host-side forwarding subscription and local dispatch; the returned
+   * function tears down both.
+   */
+  async subscribe(patterns, handler) {
+    const off = this.endpoint.onEvent(patterns, handler);
+    let subscriptionId;
+    try {
+      const result = await this.call("events.subscribe", { patterns });
+      subscriptionId = result.subscriptionId;
+    } catch (err) {
+      off();
+      throw err;
+    }
+    return async () => {
+      off();
+      await this.call("events.unsubscribe", { subscriptionId }).catch(() => {
+      });
+    };
+  }
+  /** Host-persisted key/value state (see spec: State Storage). */
+  state = {
+    get: async (keys, scope) => {
+      const result = await this.call("state.get", {
+        ...scope ? { scope } : {},
+        ...keys ? { keys } : {}
+      });
+      return result.values ?? {};
+    },
+    set: async (values, scope) => {
+      await this.call("state.set", {
+        ...scope ? { scope } : {},
+        values
+      });
+    }
+  };
+  /** Signal K data relayed by the host (capabilities signalk.stream / .put). */
+  signalk = {
+    /**
+     * Subscribe to Signal K path values. The host publishes them as
+     * `sk.<path>` events; this helper hides the event-name mapping and
+     * establishes both the event-forwarding subscription and the host's
+     * upstream Signal K subscription.
+     */
+    subscribe: async (paths, handler) => {
+      const patterns = paths.map((p) => `sk.${p}`);
+      const offEvents = await this.subscribe(
+        patterns,
+        (_name, params) => handler(params)
+      );
+      let subscriptionId;
+      try {
+        const result = await this.call("signalk.subscribe", { paths });
+        subscriptionId = result.subscriptionId;
+      } catch (err) {
+        await offEvents();
+        throw err;
+      }
+      return async () => {
+        await offEvents();
+        await this.call("signalk.unsubscribe", { subscriptionId }).catch(
+          () => {
+          }
+        );
+      };
+    },
+    put: (path, value) => {
+      return this.call("signalk.put", { path, value });
+    }
+  };
+  close() {
+    this.endpoint.close();
+  }
+};
+function connectExtension(opts = {}) {
+  const port = opts.port ?? windowPort(globalThis.parent, {
+    origin: "*"
+  });
+  const endpoint = new BusEndpoint({
+    port,
+    callTimeoutMs: opts.callTimeoutMs,
+    onError: opts.onError
+  });
+  return new Promise((resolve, reject) => {
+    let done = false;
+    const off = endpoint.onEvent([EVENT_HANDSHAKE], (_name, params) => {
+      if (done) return;
+      done = true;
+      cleanup();
+      resolve(new ExtensionClient(endpoint, params));
+    });
+    const interval = setInterval(
+      () => endpoint.notify(EVENT_READY),
+      opts.readyIntervalMs ?? 250
+    );
+    const timeout = setTimeout(() => {
+      if (done) return;
+      done = true;
+      cleanup();
+      endpoint.close();
+      reject(
+        new RpcError("Timed out waiting for host handshake", {
+          code: RPC_ERRORS.TIMEOUT,
+          reason: "HANDSHAKE_TIMEOUT"
+        })
+      );
+    }, opts.timeoutMs ?? 1e4);
+    const cleanup = () => {
+      off();
+      clearInterval(interval);
+      clearTimeout(timeout);
+    };
+    endpoint.notify(EVENT_READY);
+  });
+}
+
+export {
+  ExtensionClient,
+  connectExtension
+};
+//# sourceMappingURL=chunk-EGWZMA5J.js.map

package/dist/chunk-EGWZMA5J.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/extension.ts"],"sourcesContent":["import { BusEndpoint, EventHandler } from './endpoint'\nimport { BusPort, windowPort } from './port'\nimport {\n  EVENT_HANDSHAKE,\n  EVENT_READY,\n  Handshake,\n  HandshakeContext,\n  RPC_ERRORS,\n  RpcError,\n  SignalKValueEvent,\n  StateScope\n} from './protocol'\n\nexport interface ConnectOptions {\n  /** Transport. Defaults to window.postMessage to window.parent. */\n  port?: BusPort\n  /** Interval for re-sending bus.ready until the handshake arrives. */\n  readyIntervalMs?: number\n  /** How long to wait for the host handshake before rejecting. */\n  timeoutMs?: number\n  /** Default timeout for host API calls. */\n  callTimeoutMs?: number\n  onError?: (err: unknown) => void\n}\n\nexport type Unsubscribe = () => Promise<void>\n\n/**\n * The extension side of the bus: one per iframe context (panel, widget, or\n * background runtime). Create via connectExtension().\n */\nexport class ExtensionClient {\n  readonly handshake: Handshake\n  readonly endpoint: BusEndpoint\n\n  constructor(endpoint: BusEndpoint, handshake: Handshake) {\n    this.endpoint = endpoint\n    this.handshake = handshake\n  }\n\n  get context(): HandshakeContext {\n    return this.handshake.context\n  }\n\n  get apiVersion(): string {\n    return this.handshake.apiVersion\n  }\n\n  get capabilities(): string[] {\n    return this.handshake.capabilities\n  }\n\n  hasCapability(id: string): boolean {\n    return this.handshake.capabilities.includes(id)\n  }\n\n  /** Call a host API method. */\n  call(\n    method: string,\n    params?: unknown,\n    opts?: { timeoutMs?: number }\n  ): Promise<unknown> {\n    return this.endpoint.call(method, params, opts)\n  }\n\n  /** Send a notification to the host. */\n  notify(method: string, params?: unknown): void {\n    this.endpoint.notify(method, params)\n  }\n\n  /**\n   * Subscribe to host events matching wildcard patterns. Registers both the\n   * host-side forwarding subscription and local dispatch; the returned\n   * function tears down both.\n   */\n  async subscribe(\n    patterns: string[],\n    handler: EventHandler\n  ): Promise<Unsubscribe> {\n    const off = this.endpoint.onEvent(patterns, handler)\n    let subscriptionId: string\n    try {\n      const result = (await this.call('events.subscribe', { patterns })) as {\n        subscriptionId: string\n      }\n      subscriptionId = result.subscriptionId\n    } catch (err) {\n      off()\n      throw err\n    }\n    return async () => {\n      off()\n      await this.call('events.unsubscribe', { subscriptionId }).catch(() => {\n        // Best-effort: the host may already have dropped the connection.\n      })\n    }\n  }\n\n  /** Host-persisted key/value state (see spec: State Storage). */\n  readonly state = {\n    get: async (\n      keys?: string[],\n      scope?: StateScope\n    ): Promise<Record<string, unknown>> => {\n      const result = (await this.call('state.get', {\n        ...(scope ? { scope } : {}),\n        ...(keys ? { keys } : {})\n      })) as { values: Record<string, unknown> }\n      return result.values ?? {}\n    },\n    set: async (\n      values: Record<string, unknown>,\n      scope?: StateScope\n    ): Promise<void> => {\n      await this.call('state.set', {\n        ...(scope ? { scope } : {}),\n        values\n      })\n    }\n  }\n\n  /** Signal K data relayed by the host (capabilities signalk.stream / .put). */\n  readonly signalk = {\n    /**\n     * Subscribe to Signal K path values. The host publishes them as\n     * `sk.<path>` events; this helper hides the event-name mapping and\n     * establishes both the event-forwarding subscription and the host's\n     * upstream Signal K subscription.\n     */\n    subscribe: async (\n      paths: string[],\n      handler: (ev: SignalKValueEvent) => void\n    ): Promise<Unsubscribe> => {\n      const patterns = paths.map((p) => `sk.${p}`)\n      const offEvents = await this.subscribe(patterns, (_name, params) =>\n        handler(params as SignalKValueEvent)\n      )\n      let subscriptionId: string\n      try {\n        const result = (await this.call('signalk.subscribe', { paths })) as {\n          subscriptionId: string\n        }\n        subscriptionId = result.subscriptionId\n      } catch (err) {\n        await offEvents()\n        throw err\n      }\n      return async () => {\n        await offEvents()\n        await this.call('signalk.unsubscribe', { subscriptionId }).catch(\n          () => {}\n        )\n      }\n    },\n    put: (path: string, value: unknown): Promise<unknown> => {\n      return this.call('signalk.put', { path, value })\n    }\n  }\n\n  close(): void {\n    this.endpoint.close()\n  }\n}\n\n/**\n * Connect to the host from inside an extension iframe. Sends `bus.ready`\n * (repeating until answered) and resolves once the host's `bus.handshake`\n * arrives.\n */\nexport function connectExtension(\n  opts: ConnectOptions = {}\n): Promise<ExtensionClient> {\n  // Default transport: postMessage to the embedding window. Origin checks\n  // are relaxed to '*' on the extension side because the host page's origin\n  // may legitimately differ from the extension asset origin (e.g. a host dev\n  // server embedding extension assets served by the Signal K server); the\n  // peer-source check in windowPort still applies, and the host side\n  // enforces a strict origin for the extension's frame.\n  const port =\n    opts.port ??\n    windowPort((globalThis as unknown as Window).parent as Window, {\n      origin: '*'\n    })\n  const endpoint = new BusEndpoint({\n    port,\n    callTimeoutMs: opts.callTimeoutMs,\n    onError: opts.onError\n  })\n  return new Promise<ExtensionClient>((resolve, reject) => {\n    let done = false\n    const off = endpoint.onEvent([EVENT_HANDSHAKE], (_name, params) => {\n      if (done) return\n      done = true\n      cleanup()\n      resolve(new ExtensionClient(endpoint, params as Handshake))\n    })\n    const interval = setInterval(\n      () => endpoint.notify(EVENT_READY),\n      opts.readyIntervalMs ?? 250\n    )\n    const timeout = setTimeout(() => {\n      if (done) return\n      done = true\n      cleanup()\n      endpoint.close()\n      reject(\n        new RpcError('Timed out waiting for host handshake', {\n          code: RPC_ERRORS.TIMEOUT,\n          reason: 'HANDSHAKE_TIMEOUT'\n        })\n      )\n    }, opts.timeoutMs ?? 10_000)\n    const cleanup = () => {\n      off()\n      clearInterval(interval)\n      clearTimeout(timeout)\n    }\n    endpoint.notify(EVENT_READY)\n  })\n}\n\nexport * from './protocol'\nexport * from './wildcard'\nexport { BusEndpoint } from './endpoint'\nexport type { MethodHandler, MethodContext, EventHandler } from './endpoint'\nexport * from './port'\n"],"mappings":"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","names":[]}

package/dist/chunk-JJEZW66E.js

@@ -0,0 +1,106 @@
+import {
+  BusEndpoint,
+  EVENT_HANDSHAKE,
+  EVENT_READY,
+  RPC_ERRORS,
+  RpcError,
+  matchesAny
+} from "./chunk-ZYQKQSOC.js";
+
+// src/host.ts
+var HostConnection = class {
+  endpoint;
+  context;
+  hostInfo;
+  subs = /* @__PURE__ */ new Map();
+  onSubscriptionsChanged;
+  subSeq = 0;
+  constructor(opts) {
+    this.hostInfo = opts.hostInfo;
+    this.context = opts.context;
+    this.onSubscriptionsChanged = opts.onSubscriptionsChanged;
+    this.endpoint = new BusEndpoint({
+      port: opts.port,
+      callTimeoutMs: opts.callTimeoutMs,
+      onError: opts.onError
+    });
+    for (const [name, handler] of Object.entries(opts.methods ?? {})) {
+      this.endpoint.registerMethod(name, handler);
+    }
+    this.endpoint.registerMethod(
+      "events.subscribe",
+      (params) => this.handleSubscribe(params)
+    );
+    this.endpoint.registerMethod(
+      "events.unsubscribe",
+      (params) => this.handleUnsubscribe(params)
+    );
+    this.endpoint.onEvent([EVENT_READY], () => this.sendHandshake());
+  }
+  registerMethod(name, handler) {
+    this.endpoint.registerMethod(name, handler);
+  }
+  /**
+   * Publish an event to this context. Delivered only when the context has a
+   * matching subscription; returns whether it was delivered.
+   */
+  publish(eventName, params) {
+    if (!this.hasSubscriber(eventName)) return false;
+    this.endpoint.notify(eventName, params);
+    return true;
+  }
+  hasSubscriber(eventName) {
+    for (const [, patterns] of this.subs) {
+      if (matchesAny(patterns, eventName)) return true;
+    }
+    return false;
+  }
+  /** Union of currently subscribed patterns. */
+  subscribedPatterns() {
+    const all = /* @__PURE__ */ new Set();
+    for (const [, patterns] of this.subs) {
+      for (const p of patterns) all.add(p);
+    }
+    return [...all];
+  }
+  close() {
+    this.endpoint.close();
+    this.subs.clear();
+  }
+  sendHandshake() {
+    this.endpoint.notify(EVENT_HANDSHAKE, {
+      ...this.hostInfo,
+      context: this.context
+    });
+  }
+  handleSubscribe(params) {
+    const patterns = params?.patterns;
+    if (!Array.isArray(patterns) || patterns.length === 0 || !patterns.every((p) => typeof p === "string" && p.length > 0)) {
+      throw new RpcError("events.subscribe requires a non-empty patterns array", {
+        code: RPC_ERRORS.INVALID_PARAMS,
+        reason: "INVALID_PATTERNS"
+      });
+    }
+    const subscriptionId = `sub-${++this.subSeq}`;
+    this.subs.set(subscriptionId, patterns);
+    this.onSubscriptionsChanged?.(this.subscribedPatterns());
+    return { subscriptionId };
+  }
+  handleUnsubscribe(params) {
+    const id = params?.subscriptionId;
+    if (typeof id !== "string" || !this.subs.has(id)) {
+      throw new RpcError("Unknown subscriptionId", {
+        code: RPC_ERRORS.INVALID_PARAMS,
+        reason: "UNKNOWN_SUBSCRIPTION"
+      });
+    }
+    this.subs.delete(id);
+    this.onSubscriptionsChanged?.(this.subscribedPatterns());
+    return {};
+  }
+};
+
+export {
+  HostConnection
+};
+//# sourceMappingURL=chunk-JJEZW66E.js.map

package/dist/chunk-JJEZW66E.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/host.ts"],"sourcesContent":["import { BusEndpoint, MethodHandler } from './endpoint'\nimport { BusPort } from './port'\nimport {\n  EVENT_HANDSHAKE,\n  EVENT_READY,\n  HandshakeContext,\n  RPC_ERRORS,\n  RpcError\n} from './protocol'\nimport { matchesAny } from './wildcard'\n\nexport interface HostInfo {\n  host: string\n  hostVersion: string\n  apiVersion: string\n  capabilities: string[]\n}\n\nexport interface HostConnectionOptions {\n  port: BusPort\n  hostInfo: HostInfo\n  context: HandshakeContext\n  /** Host API methods (e.g. 'state.get', 'signalk.subscribe', 'map.center'). */\n  methods?: Record<string, MethodHandler>\n  callTimeoutMs?: number\n  onError?: (err: unknown) => void\n  /**\n   * Called whenever the union of subscribed event patterns changes, with the\n   * current pattern list. Lets the host start/stop upstream work lazily.\n   */\n  onSubscriptionsChanged?: (patterns: string[]) => void\n}\n\n/**\n * The host side of one extension context (one iframe). Sends the handshake\n * in reply to `bus.ready`, dispatches host API methods, and tracks the\n * context's event subscriptions so `publish()` only forwards events the\n * context asked for.\n */\nexport class HostConnection {\n  readonly endpoint: BusEndpoint\n  readonly context: HandshakeContext\n\n  private readonly hostInfo: HostInfo\n  private readonly subs = new Map<string, string[]>()\n  private readonly onSubscriptionsChanged?: (patterns: string[]) => void\n  private subSeq = 0\n\n  constructor(opts: HostConnectionOptions) {\n    this.hostInfo = opts.hostInfo\n    this.context = opts.context\n    this.onSubscriptionsChanged = opts.onSubscriptionsChanged\n    this.endpoint = new BusEndpoint({\n      port: opts.port,\n      callTimeoutMs: opts.callTimeoutMs,\n      onError: opts.onError\n    })\n    for (const [name, handler] of Object.entries(opts.methods ?? {})) {\n      this.endpoint.registerMethod(name, handler)\n    }\n    this.endpoint.registerMethod('events.subscribe', (params) =>\n      this.handleSubscribe(params)\n    )\n    this.endpoint.registerMethod('events.unsubscribe', (params) =>\n      this.handleUnsubscribe(params)\n    )\n    this.endpoint.onEvent([EVENT_READY], () => this.sendHandshake())\n  }\n\n  registerMethod(name: string, handler: MethodHandler): void {\n    this.endpoint.registerMethod(name, handler)\n  }\n\n  /**\n   * Publish an event to this context. Delivered only when the context has a\n   * matching subscription; returns whether it was delivered.\n   */\n  publish(eventName: string, params?: unknown): boolean {\n    if (!this.hasSubscriber(eventName)) return false\n    this.endpoint.notify(eventName, params)\n    return true\n  }\n\n  hasSubscriber(eventName: string): boolean {\n    for (const [, patterns] of this.subs) {\n      if (matchesAny(patterns, eventName)) return true\n    }\n    return false\n  }\n\n  /** Union of currently subscribed patterns. */\n  subscribedPatterns(): string[] {\n    const all = new Set<string>()\n    for (const [, patterns] of this.subs) {\n      for (const p of patterns) all.add(p)\n    }\n    return [...all]\n  }\n\n  close(): void {\n    this.endpoint.close()\n    this.subs.clear()\n  }\n\n  private sendHandshake(): void {\n    this.endpoint.notify(EVENT_HANDSHAKE, {\n      ...this.hostInfo,\n      context: this.context\n    })\n  }\n\n  private handleSubscribe(params: unknown): { subscriptionId: string } {\n    const patterns = (params as { patterns?: unknown })?.patterns\n    if (\n      !Array.isArray(patterns) ||\n      patterns.length === 0 ||\n      !patterns.every((p) => typeof p === 'string' && p.length > 0)\n    ) {\n      throw new RpcError('events.subscribe requires a non-empty patterns array', {\n        code: RPC_ERRORS.INVALID_PARAMS,\n        reason: 'INVALID_PATTERNS'\n      })\n    }\n    const subscriptionId = `sub-${++this.subSeq}`\n    this.subs.set(subscriptionId, patterns as string[])\n    this.onSubscriptionsChanged?.(this.subscribedPatterns())\n    return { subscriptionId }\n  }\n\n  private handleUnsubscribe(params: unknown): Record<string, never> {\n    const id = (params as { subscriptionId?: unknown })?.subscriptionId\n    if (typeof id !== 'string' || !this.subs.has(id)) {\n      throw new RpcError('Unknown subscriptionId', {\n        code: RPC_ERRORS.INVALID_PARAMS,\n        reason: 'UNKNOWN_SUBSCRIPTION'\n      })\n    }\n    this.subs.delete(id)\n    this.onSubscriptionsChanged?.(this.subscribedPatterns())\n    return {}\n  }\n}\n\nexport * from './protocol'\nexport * from './wildcard'\nexport { BusEndpoint } from './endpoint'\nexport type { MethodHandler, MethodContext, EventHandler } from './endpoint'\nexport * from './port'\n"],"mappings":";;;;;;;;;;AAuCO,IAAM,iBAAN,MAAqB;AAAA,EACjB;AAAA,EACA;AAAA,EAEQ;AAAA,EACA,OAAO,oBAAI,IAAsB;AAAA,EACjC;AAAA,EACT,SAAS;AAAA,EAEjB,YAAY,MAA6B;AACvC,SAAK,WAAW,KAAK;AACrB,SAAK,UAAU,KAAK;AACpB,SAAK,yBAAyB,KAAK;AACnC,SAAK,WAAW,IAAI,YAAY;AAAA,MAC9B,MAAM,KAAK;AAAA,MACX,eAAe,KAAK;AAAA,MACpB,SAAS,KAAK;AAAA,IAChB,CAAC;AACD,eAAW,CAAC,MAAM,OAAO,KAAK,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,GAAG;AAChE,WAAK,SAAS,eAAe,MAAM,OAAO;AAAA,IAC5C;AACA,SAAK,SAAS;AAAA,MAAe;AAAA,MAAoB,CAAC,WAChD,KAAK,gBAAgB,MAAM;AAAA,IAC7B;AACA,SAAK,SAAS;AAAA,MAAe;AAAA,MAAsB,CAAC,WAClD,KAAK,kBAAkB,MAAM;AAAA,IAC/B;AACA,SAAK,SAAS,QAAQ,CAAC,WAAW,GAAG,MAAM,KAAK,cAAc,CAAC;AAAA,EACjE;AAAA,EAEA,eAAe,MAAc,SAA8B;AACzD,SAAK,SAAS,eAAe,MAAM,OAAO;AAAA,EAC5C;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,QAAQ,WAAmB,QAA2B;AACpD,QAAI,CAAC,KAAK,cAAc,SAAS,EAAG,QAAO;AAC3C,SAAK,SAAS,OAAO,WAAW,MAAM;AACtC,WAAO;AAAA,EACT;AAAA,EAEA,cAAc,WAA4B;AACxC,eAAW,CAAC,EAAE,QAAQ,KAAK,KAAK,MAAM;AACpC,UAAI,WAAW,UAAU,SAAS,EAAG,QAAO;AAAA,IAC9C;AACA,WAAO;AAAA,EACT;AAAA;AAAA,EAGA,qBAA+B;AAC7B,UAAM,MAAM,oBAAI,IAAY;AAC5B,eAAW,CAAC,EAAE,QAAQ,KAAK,KAAK,MAAM;AACpC,iBAAW,KAAK,SAAU,KAAI,IAAI,CAAC;AAAA,IACrC;AACA,WAAO,CAAC,GAAG,GAAG;AAAA,EAChB;AAAA,EAEA,QAAc;AACZ,SAAK,SAAS,MAAM;AACpB,SAAK,KAAK,MAAM;AAAA,EAClB;AAAA,EAEQ,gBAAsB;AAC5B,SAAK,SAAS,OAAO,iBAAiB;AAAA,MACpC,GAAG,KAAK;AAAA,MACR,SAAS,KAAK;AAAA,IAChB,CAAC;AAAA,EACH;AAAA,EAEQ,gBAAgB,QAA6C;AACnE,UAAM,WAAY,QAAmC;AACrD,QACE,CAAC,MAAM,QAAQ,QAAQ,KACvB,SAAS,WAAW,KACpB,CAAC,SAAS,MAAM,CAAC,MAAM,OAAO,MAAM,YAAY,EAAE,SAAS,CAAC,GAC5D;AACA,YAAM,IAAI,SAAS,wDAAwD;AAAA,QACzE,MAAM,WAAW;AAAA,QACjB,QAAQ;AAAA,MACV,CAAC;AAAA,IACH;AACA,UAAM,iBAAiB,OAAO,EAAE,KAAK,MAAM;AAC3C,SAAK,KAAK,IAAI,gBAAgB,QAAoB;AAClD,SAAK,yBAAyB,KAAK,mBAAmB,CAAC;AACvD,WAAO,EAAE,eAAe;AAAA,EAC1B;AAAA,EAEQ,kBAAkB,QAAwC;AAChE,UAAM,KAAM,QAAyC;AACrD,QAAI,OAAO,OAAO,YAAY,CAAC,KAAK,KAAK,IAAI,EAAE,GAAG;AAChD,YAAM,IAAI,SAAS,0BAA0B;AAAA,QAC3C,MAAM,WAAW;AAAA,QACjB,QAAQ;AAAA,MACV,CAAC;AAAA,IACH;AACA,SAAK,KAAK,OAAO,EAAE;AACnB,SAAK,yBAAyB,KAAK,mBAAmB,CAAC;AACvD,WAAO,CAAC;AAAA,EACV;AACF;","names":[]}