@snaptrude/plugin-client 0.9.14 → 0.9.15

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @snaptrude/plugin-client
 
+## 0.9.15
+
+### Patch Changes
+
+- Updated dependencies [4bfe118]
+- Updated dependencies [80c1a2b]
+- Updated dependencies [0e3df96]
+- Updated dependencies [d84ea44]
+  - @snaptrude/plugin-core@0.9.15
+
 ## 0.9.14
 
 ### Patch Changes
@@ -52,6 +62,13 @@
 
 - Version bump to track plugin-core 0.9.9 (program.metadata, program.labels, program.departments.setTargetCount, custom program sheets on program.spreadsheet, core.tags.listForComponents). No client code change — every namespace is served by the generic RPC proxy, so new plugin-core methods dispatch automatically once plugin-core is rebuilt.
 
+## 0.9.8
+
+### Patch Changes
+
+- Updated dependencies [7fd374e]
+  - @snaptrude/plugin-core@0.9.8
+
 ## 0.9.7
 
 ### Patch Changes

package/dist/api/index.d.ts

@@ -0,0 +1,20 @@
+import { PluginApi, PluginCoreApi, PluginDesignApi, PluginEntityApi, PluginProgramApi, PluginPresentationApi, PluginAnalysisApi, PluginWorkspaceApi } from "@snaptrude/plugin-core";
+export declare class ClientPluginApi extends PluginApi {
+    private static instance;
+    /**
+     * Every namespace is fully remote under the all-handle model: math/geom now
+     * cross to the host (values are opaque handles), so there is no in-worker
+     * compute left. All dispatch through a single generic RPC Proxy. Units live
+     * under `core.units`, so they ride the `core` proxy.
+     */
+    core: PluginCoreApi;
+    design: PluginDesignApi;
+    entity: PluginEntityApi;
+    program: PluginProgramApi;
+    presentation: PluginPresentationApi;
+    analysis: PluginAnalysisApi;
+    workspace: PluginWorkspaceApi;
+    private constructor();
+    static getInstance(): ClientPluginApi;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,aAAa,EACb,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,wBAAwB,CAAA;AAG/B,qBAAa,eAAgB,SAAQ,SAAS;IAC5C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAiB;IAExC;;;;;OAKG;IACI,IAAI,EAAE,aAAa,CAAA;IACnB,MAAM,EAAE,eAAe,CAAA;IACvB,MAAM,EAAE,eAAe,CAAA;IACvB,OAAO,EAAE,gBAAgB,CAAA;IACzB,YAAY,EAAE,qBAAqB,CAAA;IACnC,QAAQ,EAAE,iBAAiB,CAAA;IAC3B,SAAS,EAAE,kBAAkB,CAAA;IAEpC,OAAO;IAYP,MAAM,CAAC,WAAW,IAAI,eAAe;CAMtC"}

package/dist/events.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Snaptrude plugin events.
+ *
+ * Plugins can react to changes in the host app. Events are delivered through
+ * the host event bus — a separate channel from the request/response
+ * `snaptrude.*` API — and carry a small structured-clone-safe payload, never
+ * live model data.
+ *
+ * Subscribe from a {@link PluginWorker} subclass with `this.subscribe(...)`.
+ *
+ * NOTE: events are a subscription surface, not `call()` RPC methods, so they do
+ * NOT appear in the discovery manifest (which enumerates callable methods
+ * only). This module is the typed, discoverable declaration of the surface.
+ */
+/** Every event a plugin can subscribe to. */
+export declare const PLUGIN_EVENTS: readonly ["selection:changed", "tool:activated", "project:saved", "view:changed", "model:changed"];
+/** Union of subscribable event names. */
+export type PluginEventName = (typeof PLUGIN_EVENTS)[number];
+/**
+ * Payload for `model:changed` — fired (debounced) whenever the project model is
+ * mutated, by a user edit OR a plugin edit. Deliberately minimal: it signals
+ * *that* the model changed, never *what* changed. Re-query the API for details.
+ */
+export interface ModelChangedEvent {
+    /** Origin of the change. Currently always `"command"` (the edit chokepoint). */
+    source: string;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,6CAA6C;AAC7C,eAAO,MAAM,aAAa,oGAMhB,CAAA;AAEV,yCAAyC;AACzC,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAA;AAE5D;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAA;CACf"}

package/dist/handle-runtime.d.ts

@@ -0,0 +1,27 @@
+import { Handle } from "@snaptrude/plugin-core";
+/**
+ * Return THE `Handle` instance for this id — the existing live wrapper when
+ * present, else a fresh one wired for auto-release.
+ */
+export declare function intern(id: string): Handle<string>;
+/** TEST SEAM ONLY: replace the release transport (pass `undefined` to restore). */
+export declare function __setReleaseTransport(transport?: (batch: string[]) => Promise<void>): void;
+/** Exported for tests and for an eager flush before a plugin self-completes. */
+export declare function flushReleaseQueue(): Promise<void>;
+/**
+ * Recursively re-wrap a host result: `{ __h: "<id>" }` tags (produced by
+ * `Handle.toJSON` through the host's JSON-round-trip serialization) become
+ * interned `Handle` instances. Arrays and plain records are walked; all other
+ * values pass through untouched.
+ */
+export declare function rewrapResult(value: unknown): unknown;
+/**
+ * Recursively unwrap outgoing args: `Handle` instances become their wire id
+ * strings. Uses a memo Map (not a bail-out set) so shared/diamond references
+ * get the SAME converted subtree — a bail-out would leak un-unwrapped Handle
+ * instances through the second reference. Cycles are handled by memoizing the
+ * output object before recursing. Non-plain objects pass through untouched
+ * (structured clone imposes plain-data args anyway).
+ */
+export declare function unwrapArgs(value: unknown, memo?: Map<object, unknown>): unknown;
+//# sourceMappingURL=handle-runtime.d.ts.map

package/dist/handle-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-runtime.d.ts","sourceRoot":"","sources":["../src/handle-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAqC/C;;;GAGG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAwBjD;AAqBD,mFAAmF;AACnF,wBAAgB,qBAAqB,CACnC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAC7C,IAAI,CASN;AAED,gFAAgF;AAChF,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAgCvD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAYpD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,uBAA6B,GAAG,OAAO,CAqBrF"}

package/dist/host-api.d.ts

@@ -0,0 +1,13 @@
+import * as Comlink from "comlink";
+import type { PluginApiMethod, PluginApiCallPayload, PluginApiCallWrappedResult, PluginApiCallResult } from "@snaptrude/plugin-core";
+export interface HostApi {
+    call<M extends PluginApiMethod>(payload: PluginApiCallPayload<M>): Promise<PluginApiCallWrappedResult<M>>;
+}
+export interface HostApiWrapped {
+    call<M extends PluginApiMethod>(payload: PluginApiCallPayload<M>): Promise<PluginApiCallResult<M>>;
+}
+export declare function createHostApi(endpoint?: Comlink.Endpoint): HostApi;
+/** TEST SEAM ONLY: replace the Comlink host instance (pass `undefined` to reset). */
+export declare function __setHostApiInstance(instance?: HostApi): void;
+export declare function getHostApi(): HostApiWrapped;
+//# sourceMappingURL=host-api.d.ts.map

package/dist/host-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-api.d.ts","sourceRoot":"","sources":["../src/host-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,SAAS,CAAA;AAClC,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EACpB,0BAA0B,EAC1B,mBAAmB,EACpB,MAAM,wBAAwB,CAAA;AAI/B,MAAM,WAAW,OAAO;IACtB,IAAI,CAAC,CAAC,SAAS,eAAe,EAC5B,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC/B,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAA;CAC1C;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,CAAC,SAAS,eAAe,EAC5B,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC/B,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAA;CACnC;AAED,wBAAgB,aAAa,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,QAAQ,GAAG,OAAO,CAIlE;AAID,qFAAqF;AACrF,wBAAgB,oBAAoB,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAE7D;AAED,wBAAgB,UAAU,IAAI,cAAc,CA0C3C"}

package/dist/index.cjs

@@ -0,0 +1,411 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CODE_META: () => import_plugin_core4.CODE_META,
+  ClientPluginApi: () => ClientPluginApi,
+  PLUGIN_ERROR_CODES: () => import_plugin_core4.PLUGIN_ERROR_CODES,
+  PLUGIN_EVENTS: () => PLUGIN_EVENTS,
+  PluginError: () => import_plugin_core4.PluginError,
+  PluginExecutionError: () => import_plugin_core4.PluginExecutionError,
+  PluginHandleError: () => import_plugin_core4.PluginHandleError,
+  PluginInternalError: () => import_plugin_core4.PluginInternalError,
+  PluginLifecycleError: () => import_plugin_core4.PluginLifecycleError,
+  PluginNotFoundError: () => import_plugin_core4.PluginNotFoundError,
+  PluginPermissionError: () => import_plugin_core4.PluginPermissionError,
+  PluginQuotaError: () => import_plugin_core4.PluginQuotaError,
+  PluginTimeoutError: () => import_plugin_core4.PluginTimeoutError,
+  PluginTransportError: () => import_plugin_core4.PluginTransportError,
+  PluginValidationError: () => import_plugin_core4.PluginValidationError,
+  PluginWorker: () => PluginWorker,
+  __setHostApiInstance: () => __setHostApiInstance,
+  __setReleaseTransport: () => __setReleaseTransport,
+  createHostApi: () => createHostApi,
+  flushReleaseQueue: () => flushReleaseQueue,
+  fromEnvelope: () => import_plugin_core4.fromEnvelope,
+  getHostApi: () => getHostApi,
+  intern: () => intern,
+  isErrorEnvelope: () => import_plugin_core4.isErrorEnvelope,
+  isPluginErrorCode: () => import_plugin_core4.isPluginErrorCode,
+  rewrapResult: () => rewrapResult,
+  snaptrude: () => snaptrude,
+  unwrapArgs: () => unwrapArgs
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/api/index.ts
+var import_plugin_core3 = require("@snaptrude/plugin-core");
+
+// src/host-api.ts
+var Comlink = __toESM(require("comlink"), 1);
+var import_plugin_core2 = require("@snaptrude/plugin-core");
+
+// src/handle-runtime.ts
+var import_plugin_core = require("@snaptrude/plugin-core");
+var interned = /* @__PURE__ */ new Map();
+var RELEASE_FLUSH_SIZE = 64;
+var RELEASE_FLUSH_MS = 250;
+var MAX_FLUSH_FAILURES = 5;
+var releaseQueue = /* @__PURE__ */ new Set();
+var flushTimer = null;
+var consecutiveFlushFailures = 0;
+var finalizer = new FinalizationRegistry((id) => {
+  if (interned.get(id)?.deref()) return;
+  interned.delete(id);
+  enqueueRelease(id);
+});
+function intern(id) {
+  releaseQueue.delete(id);
+  const existing = interned.get(id)?.deref();
+  if (existing) return existing;
+  const handle = new import_plugin_core.Handle(id);
+  handle[Symbol.asyncDispose] = async () => {
+    if (interned.get(id)?.deref() === handle) interned.delete(id);
+    enqueueRelease(id);
+  };
+  interned.set(id, new WeakRef(handle));
+  finalizer.register(handle, id);
+  return handle;
+}
+function enqueueRelease(id) {
+  releaseQueue.add(id);
+  if (releaseQueue.size >= RELEASE_FLUSH_SIZE) {
+    void flushReleaseQueue();
+    return;
+  }
+  flushTimer ?? (flushTimer = setTimeout(() => {
+    void flushReleaseQueue();
+  }, RELEASE_FLUSH_MS));
+}
+var releaseTransport = async (batch) => {
+  await getHostApi().call({
+    method: "core.handles.release",
+    args: [batch]
+  });
+};
+function __setReleaseTransport(transport) {
+  releaseTransport = transport ?? (async (batch) => {
+    await getHostApi().call({
+      method: "core.handles.release",
+      args: [batch]
+    });
+  });
+}
+async function flushReleaseQueue() {
+  if (flushTimer) {
+    clearTimeout(flushTimer);
+    flushTimer = null;
+  }
+  if (releaseQueue.size === 0) return;
+  const batch = [...releaseQueue];
+  releaseQueue.clear();
+  try {
+    await releaseTransport(batch);
+    consecutiveFlushFailures = 0;
+  } catch (err) {
+    consecutiveFlushFailures += 1;
+    if (consecutiveFlushFailures >= MAX_FLUSH_FAILURES) {
+      console.warn(
+        `[snaptrude] dropping ${batch.length} handle release(s) after ${consecutiveFlushFailures} failed flushes`,
+        err
+      );
+      consecutiveFlushFailures = 0;
+      return;
+    }
+    for (const id of batch) {
+      if (!interned.get(id)?.deref()) releaseQueue.add(id);
+    }
+  }
+}
+function rewrapResult(value) {
+  if (Array.isArray(value)) return value.map(rewrapResult);
+  if (value && typeof value === "object") {
+    const record = value;
+    const keys = Object.keys(record);
+    if (keys.length === 1 && keys[0] === "__h" && typeof record.__h === "string") {
+      return intern(record.__h);
+    }
+    for (const key of keys) record[key] = rewrapResult(record[key]);
+    return record;
+  }
+  return value;
+}
+function unwrapArgs(value, memo = /* @__PURE__ */ new Map()) {
+  if (value instanceof import_plugin_core.Handle) return value.id;
+  if (value === null || typeof value !== "object") return value;
+  const hit = memo.get(value);
+  if (hit !== void 0) return hit;
+  if (Array.isArray(value)) {
+    const out2 = [];
+    memo.set(value, out2);
+    for (const item of value) out2.push(unwrapArgs(item, memo));
+    return out2;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return value;
+  const out = {};
+  memo.set(value, out);
+  for (const [key, item] of Object.entries(value)) out[key] = unwrapArgs(item, memo);
+  return out;
+}
+
+// src/host-api.ts
+function createHostApi(endpoint) {
+  return Comlink.wrap(
+    endpoint ?? globalThis
+  );
+}
+var _instance = null;
+function __setHostApiInstance(instance) {
+  _instance = instance ?? null;
+}
+function getHostApi() {
+  if (!_instance) {
+    _instance = createHostApi();
+  }
+  return {
+    call: async (payload) => {
+      if (!_instance) {
+        throw new Error("Host API not initialized");
+      }
+      let result;
+      try {
+        result = await _instance.call(payload);
+      } catch (transportErr) {
+        if (import_plugin_core2.PluginError.is(transportErr)) throw transportErr;
+        throw rehydrate(
+          (0, import_plugin_core2.makeClientEnvelope)(
+            "TRANSPORT_LOST",
+            transportErr instanceof Error ? transportErr.message : String(transportErr),
+            { methodPath: payload.method }
+          )
+        );
+      }
+      if (result.success) {
+        return rewrapResult(result.data);
+      }
+      throw rehydrate(
+        result.errorInfo ?? (0, import_plugin_core2.makeClientEnvelope)("UNKNOWN", result.error ?? "Unknown host error", {
+          methodPath: payload.method
+        })
+      );
+    }
+  };
+}
+function rehydrate(envelope) {
+  const error = (0, import_plugin_core2.fromEnvelope)(envelope);
+  Error.captureStackTrace?.(error, rehydrate);
+  return error;
+}
+
+// src/rpc-proxy.ts
+function createRpcNamespace(basePath) {
+  const build = (path) => new Proxy(NOOP, {
+    get(_target, prop) {
+      if (typeof prop !== "string" || prop === "then") return void 0;
+      return build(`${path}.${prop}`);
+    },
+    apply(_target, _thisArg, argArray) {
+      const payload = {
+        method: path,
+        // Handle instances anywhere in the tuple become their wire id strings.
+        args: argArray.map((arg) => unwrapArgs(arg))
+      };
+      return getHostApi().call(payload);
+    }
+  });
+  return build(basePath);
+}
+var NOOP = () => {
+};
+
+// src/api/index.ts
+var ClientPluginApi = class _ClientPluginApi extends import_plugin_core3.PluginApi {
+  constructor() {
+    super();
+    this.core = createRpcNamespace("core");
+    this.design = createRpcNamespace("design");
+    this.entity = createRpcNamespace("entity");
+    this.program = createRpcNamespace("program");
+    this.presentation = createRpcNamespace("presentation");
+    this.analysis = createRpcNamespace("analysis");
+    this.workspace = createRpcNamespace("workspace");
+  }
+  static getInstance() {
+    if (!_ClientPluginApi.instance) {
+      _ClientPluginApi.instance = new _ClientPluginApi();
+    }
+    return _ClientPluginApi.instance;
+  }
+};
+
+// src/plugin-worker.ts
+var Comlink2 = __toESM(require("comlink"), 1);
+var PluginWorker = class {
+  constructor() {
+    this.hostAPI = Comlink2.wrap(
+      self
+    );
+  }
+  sendToUI(action, payload) {
+    ;
+    this.hostAPI.ui.sendToUI({ action, payload });
+  }
+  /**
+   * Show a transient notification toast in the Snaptrude editor.
+   *
+   * @param message - Text to display.
+   * @param type - Severity; `"error"`/`"warning"` linger a little longer than
+   *   `"info"`. Defaults to `"info"`.
+   */
+  notify(message, type = "info") {
+    ;
+    this.hostAPI.ui.showNotification(message, type);
+  }
+  /**
+   * Signal the host that this plugin has finished its work and should be
+   * stopped. Use this in headless (UI-less) plugins that run a task and
+   * self-terminate.
+   */
+  complete() {
+    ;
+    this.hostAPI.lifecycle.complete();
+  }
+  /**
+   * Subscribe to a host event (e.g. `"model:changed"`, fired debounced on any
+   * user- or plugin-initiated model edit). The callback runs in this worker
+   * each time the event fires; its argument is a small structured-clone-safe
+   * payload (see the event's payload type, e.g. `ModelChangedEvent`).
+   *
+   * Fire-and-forget: subscribe once (typically in `init()`). Subscriptions live
+   * for the plugin's lifetime and are cleared automatically when the plugin is
+   * stopped — there is no `unsubscribe` yet.
+   *
+   * @example
+   * ```ts
+   * import type { ModelChangedEvent } from "@snaptrude/plugin-client";
+   *
+   * async init() {
+   *   this.subscribe("model:changed", (e) => {
+   *     const { source } = e as ModelChangedEvent;
+   *     console.log("model changed via", source);
+   *   });
+   * }
+   * ```
+   */
+  subscribe(event, callback) {
+    ;
+    this.hostAPI.events.on(
+      event,
+      Comlink2.proxy(callback)
+    );
+  }
+  async init() {
+    console.log(this.pluginId, "init() called");
+    console.log(this.pluginId, "Initialization complete");
+  }
+  async destroy() {
+    console.log(this.pluginId, "destroy() called \u2014 cleaning up");
+  }
+  async ping() {
+    return "pong";
+  }
+  async onUIMessage(_message) {
+  }
+  /**
+   * Expose the worker API via Comlink and start listening.
+   * Call this once after constructing the plugin instance.
+   *
+   * The host calls `init(config)` with `{ pluginId }`,
+   * which is captured here to set `this.pluginId` before the
+   * subclass's `init()` runs.
+   */
+  start() {
+    Comlink2.expose(
+      {
+        init: (config) => {
+          this.pluginId = config.pluginId;
+          return this.init();
+        },
+        destroy: () => this.destroy(),
+        ping: () => this.ping(),
+        onUIMessage: (message) => this.onUIMessage(message)
+      },
+      self
+    );
+    console.log("Worker loaded, API exposed via Comlink");
+  }
+};
+
+// src/events.ts
+var PLUGIN_EVENTS = [
+  "selection:changed",
+  "tool:activated",
+  "project:saved",
+  "view:changed",
+  "model:changed"
+];
+
+// src/index.ts
+var import_plugin_core4 = require("@snaptrude/plugin-core");
+var snaptrude = ClientPluginApi.getInstance();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CODE_META,
+  ClientPluginApi,
+  PLUGIN_ERROR_CODES,
+  PLUGIN_EVENTS,
+  PluginError,
+  PluginExecutionError,
+  PluginHandleError,
+  PluginInternalError,
+  PluginLifecycleError,
+  PluginNotFoundError,
+  PluginPermissionError,
+  PluginQuotaError,
+  PluginTimeoutError,
+  PluginTransportError,
+  PluginValidationError,
+  PluginWorker,
+  __setHostApiInstance,
+  __setReleaseTransport,
+  createHostApi,
+  flushReleaseQueue,
+  fromEnvelope,
+  getHostApi,
+  intern,
+  isErrorEnvelope,
+  isPluginErrorCode,
+  rewrapResult,
+  snaptrude,
+  unwrapArgs
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/api/index.ts","../src/host-api.ts","../src/handle-runtime.ts","../src/rpc-proxy.ts","../src/plugin-worker.ts","../src/events.ts"],"sourcesContent":["import { ClientPluginApi } from \"./api\"\n\nexport * from \"./api\"\nexport * from \"./host-api\"\nexport * from \"./plugin-worker\"\nexport * from \"./events\"\nexport {\n  flushReleaseQueue,\n  intern,\n  rewrapResult,\n  unwrapArgs,\n  __setReleaseTransport,\n} from \"./handle-runtime\"\n\n// Error surface — plugins branch on `PluginError.is(e)` + `e.code`.\nexport {\n  PluginError,\n  PluginValidationError,\n  PluginNotFoundError,\n  PluginPermissionError,\n  PluginHandleError,\n  PluginQuotaError,\n  PluginTimeoutError,\n  PluginTransportError,\n  PluginLifecycleError,\n  PluginExecutionError,\n  PluginInternalError,\n  fromEnvelope,\n  isErrorEnvelope,\n  isPluginErrorCode,\n  PLUGIN_ERROR_CODES,\n  CODE_META,\n} from \"@snaptrude/plugin-core\"\nexport type {\n  ErrorEnvelope,\n  PluginErrorCode,\n  WirePluginErrorCode,\n  PluginErrorCategory,\n} from \"@snaptrude/plugin-core\"\n\n/**\n * The Snaptrude plugin client API.\n *\n * The main entry point for plugins to interact with the Snaptrude platform.\n */\nexport const snaptrude = ClientPluginApi.getInstance()\n","import {\n  PluginApi,\n  PluginCoreApi,\n  PluginDesignApi,\n  PluginEntityApi,\n  PluginProgramApi,\n  PluginPresentationApi,\n  PluginAnalysisApi,\n  PluginWorkspaceApi,\n} from \"@snaptrude/plugin-core\"\nimport { createRpcNamespace } from \"../rpc-proxy\"\n\nexport class ClientPluginApi extends PluginApi {\n  private static instance: ClientPluginApi\n\n  /**\n   * Every namespace is fully remote under the all-handle model: math/geom now\n   * cross to the host (values are opaque handles), so there is no in-worker\n   * compute left. All dispatch through a single generic RPC Proxy. Units live\n   * under `core.units`, so they ride the `core` proxy.\n   */\n  public core: PluginCoreApi\n  public design: PluginDesignApi\n  public entity: PluginEntityApi\n  public program: PluginProgramApi\n  public presentation: PluginPresentationApi\n  public analysis: PluginAnalysisApi\n  public workspace: PluginWorkspaceApi\n\n  private constructor() {\n    super()\n    this.core = createRpcNamespace<PluginCoreApi>(\"core\")\n    this.design = createRpcNamespace<PluginDesignApi>(\"design\")\n    this.entity = createRpcNamespace<PluginEntityApi>(\"entity\")\n    this.program = createRpcNamespace<PluginProgramApi>(\"program\")\n    this.presentation =\n      createRpcNamespace<PluginPresentationApi>(\"presentation\")\n    this.analysis = createRpcNamespace<PluginAnalysisApi>(\"analysis\")\n    this.workspace = createRpcNamespace<PluginWorkspaceApi>(\"workspace\")\n  }\n\n  static getInstance(): ClientPluginApi {\n    if (!ClientPluginApi.instance) {\n      ClientPluginApi.instance = new ClientPluginApi()\n    }\n    return ClientPluginApi.instance\n  }\n}\n","import * as Comlink from \"comlink\"\nimport type {\n  PluginApiMethod,\n  PluginApiCallPayload,\n  PluginApiCallWrappedResult,\n  PluginApiCallResult,\n} from \"@snaptrude/plugin-core\"\nimport { PluginError, fromEnvelope, makeClientEnvelope } from \"@snaptrude/plugin-core\"\nimport { rewrapResult } from \"./handle-runtime\"\n\nexport interface HostApi {\n  call<M extends PluginApiMethod>(\n    payload: PluginApiCallPayload<M>\n  ): Promise<PluginApiCallWrappedResult<M>>\n}\n\nexport interface HostApiWrapped {\n  call<M extends PluginApiMethod>(\n    payload: PluginApiCallPayload<M>\n  ): Promise<PluginApiCallResult<M>>\n}\n\nexport function createHostApi(endpoint?: Comlink.Endpoint): HostApi {\n  return Comlink.wrap<HostApi>(\n    endpoint ?? (globalThis as unknown as Comlink.Endpoint)\n  ) as unknown as HostApi\n}\n\nlet _instance: HostApi | null = null\n\n/** TEST SEAM ONLY: replace the Comlink host instance (pass `undefined` to reset). */\nexport function __setHostApiInstance(instance?: HostApi): void {\n  _instance = instance ?? null\n}\n\nexport function getHostApi(): HostApiWrapped {\n  if (!_instance) {\n    _instance = createHostApi()\n  }\n  return {\n    call: async <M extends PluginApiMethod>(payload: PluginApiCallPayload<M>): Promise<PluginApiCallResult<M>> => {\n      if (!_instance) {\n        throw new Error(\"Host API not initialized\")\n      }\n\n      let result: PluginApiCallWrappedResult<M>\n      try {\n        result = await _instance.call(payload)\n      } catch (transportErr) {\n        // Comlink-level rejection: port closed, worker terminated, clone\n        // failure. Never a routed failure — the router always RETURNS its\n        // envelope — so normalize to a typed transport error.\n        if (PluginError.is(transportErr)) throw transportErr\n        throw rehydrate(\n          makeClientEnvelope(\n            \"TRANSPORT_LOST\",\n            transportErr instanceof Error ? transportErr.message : String(transportErr),\n            { methodPath: payload.method }\n          )\n        )\n      }\n\n      if (result.success) {\n        // Re-wrap tagged handles ({__h: id} → interned Handle instances).\n        return rewrapResult(result.data) as PluginApiCallResult<M>\n      }\n\n      // Structured envelope when the host provides one; legacy hosts (string\n      // `error` only) degrade to UNKNOWN with the message preserved.\n      throw rehydrate(\n        result.errorInfo ??\n          makeClientEnvelope(\"UNKNOWN\", result.error ?? \"Unknown host error\", {\n            methodPath: payload.method,\n          })\n      )\n    }\n  }\n}\n\n/**\n * Envelope → typed `PluginError`, with the stack trimmed to the plugin's call\n * site (V8 only; harmless no-op elsewhere) instead of transport internals.\n */\nfunction rehydrate(envelope: Parameters<typeof fromEnvelope>[0]): PluginError {\n  const error = fromEnvelope(envelope)\n  ;(Error as { captureStackTrace?: (target: object, ctor: Function) => void })\n    .captureStackTrace?.(error, rehydrate)\n  return error\n}\n","import { Handle } from \"@snaptrude/plugin-core\"\nimport { getHostApi } from \"./host-api\"\n\n/**\n * Worker-side handle lifecycle runtime (P1):\n *\n * - **Interning** — one live `Handle` instance per id, so `===`, `Set`, and\n *   `Map` keys keep working exactly as they did when handles were raw strings\n *   (the host identity-dedups resource/topology handles, so the same id\n *   arrives repeatedly).\n * - **FinalizationRegistry backstop** — when the plugin drops every reference\n *   to a handle, its host registry entry is eventually released without any\n *   author action. Eventual, not timely: deterministic release\n *   (`core.handles.release` / scopes / `await using`) remains the primary tool.\n * - **Batched release queue** — finalizer hits and `Symbol.asyncDispose` calls\n *   collapse into one `core.handles.release([...])` RPC per flush.\n */\n\nconst interned = new Map<string, WeakRef<Handle<string>>>()\n\nconst RELEASE_FLUSH_SIZE = 64\nconst RELEASE_FLUSH_MS = 250\nconst MAX_FLUSH_FAILURES = 5\n\nconst releaseQueue = new Set<string>()\nlet flushTimer: ReturnType<typeof setTimeout> | null = null\nlet consecutiveFlushFailures = 0\n\nconst finalizer = new FinalizationRegistry<string>((id) => {\n  // A NEW wrapper for the same id may have been interned after the collected\n  // one died (deduped topology re-enumeration) — releasing then would free a\n  // handle the plugin still holds. Only release when no live wrapper remains.\n  if (interned.get(id)?.deref()) return\n  interned.delete(id)\n  enqueueRelease(id)\n})\n\n/**\n * Return THE `Handle` instance for this id — the existing live wrapper when\n * present, else a fresh one wired for auto-release.\n */\nexport function intern(id: string): Handle<string> {\n  // The host just (re-)vended this id, so it is live host-side. Cancel any\n  // PENDING auto-release for it — covers the finalizer-already-ran window\n  // (old wrapper collected, id queued, same id re-vended before the flush;\n  // without this the flush would release a handle the plugin holds live).\n  releaseQueue.delete(id)\n\n  const existing = interned.get(id)?.deref()\n  if (existing) return existing\n\n  const handle = new Handle<string>(id)\n  // Instance-level override shadows the class's no-op placeholder. Explicit\n  // dispose also UN-interns the wrapper: (a) the flush-failure retry filter\n  // skips ids with a live interned wrapper, so a still-interned explicit\n  // dispose would never be retried; (b) if the host re-vends the id later,\n  // a fresh wrapper is minted instead of resurrecting the disposed one.\n  ;(handle as { [Symbol.asyncDispose]?: () => Promise<void> })[Symbol.asyncDispose] =\n    async () => {\n      if (interned.get(id)?.deref() === handle) interned.delete(id)\n      enqueueRelease(id)\n    }\n  interned.set(id, new WeakRef(handle))\n  finalizer.register(handle, id)\n  return handle\n}\n\nfunction enqueueRelease(id: string): void {\n  releaseQueue.add(id)\n  if (releaseQueue.size >= RELEASE_FLUSH_SIZE) {\n    void flushReleaseQueue()\n    return\n  }\n  flushTimer ??= setTimeout(() => {\n    void flushReleaseQueue()\n  }, RELEASE_FLUSH_MS)\n}\n\n/** How a release batch reaches the host. Swappable for tests (`__setReleaseTransport`). */\nlet releaseTransport = async (batch: string[]): Promise<void> => {\n  await getHostApi().call({\n    method: \"core.handles.release\",\n    args: [batch],\n  } as never)\n}\n\n/** TEST SEAM ONLY: replace the release transport (pass `undefined` to restore). */\nexport function __setReleaseTransport(\n  transport?: (batch: string[]) => Promise<void>\n): void {\n  releaseTransport =\n    transport ??\n    (async (batch: string[]) => {\n      await getHostApi().call({\n        method: \"core.handles.release\",\n        args: [batch],\n      } as never)\n    })\n}\n\n/** Exported for tests and for an eager flush before a plugin self-completes. */\nexport async function flushReleaseQueue(): Promise<void> {\n  if (flushTimer) {\n    clearTimeout(flushTimer)\n    flushTimer = null\n  }\n  if (releaseQueue.size === 0) return\n  const batch = [...releaseQueue]\n  releaseQueue.clear()\n  try {\n    await releaseTransport(batch)\n    consecutiveFlushFailures = 0\n  } catch (err) {\n    // Transient failure (rate limit, timeout): re-queue so the entries are not\n    // permanently leaked host-side; the next enqueue/flush retries. Ids the\n    // plugin re-acquired in the meantime were already purged by intern() and\n    // must not be re-added. If the host is simply gone, the plugin is stopping\n    // and registry teardown reclaims everything anyway.\n    consecutiveFlushFailures += 1\n    if (consecutiveFlushFailures >= MAX_FLUSH_FAILURES) {\n      // Persistent failure: retrying forever would just spin. Drop the batch\n      // loudly — host teardown reclaims the entries when the plugin stops.\n      console.warn(\n        `[snaptrude] dropping ${batch.length} handle release(s) after ${consecutiveFlushFailures} failed flushes`,\n        err\n      )\n      consecutiveFlushFailures = 0\n      return\n    }\n    for (const id of batch) {\n      if (!interned.get(id)?.deref()) releaseQueue.add(id)\n    }\n  }\n}\n\n/**\n * Recursively re-wrap a host result: `{ __h: \"<id>\" }` tags (produced by\n * `Handle.toJSON` through the host's JSON-round-trip serialization) become\n * interned `Handle` instances. Arrays and plain records are walked; all other\n * values pass through untouched.\n */\nexport function rewrapResult(value: unknown): unknown {\n  if (Array.isArray(value)) return value.map(rewrapResult)\n  if (value && typeof value === \"object\") {\n    const record = value as Record<string, unknown>\n    const keys = Object.keys(record)\n    if (keys.length === 1 && keys[0] === \"__h\" && typeof record.__h === \"string\") {\n      return intern(record.__h)\n    }\n    for (const key of keys) record[key] = rewrapResult(record[key])\n    return record\n  }\n  return value\n}\n\n/**\n * Recursively unwrap outgoing args: `Handle` instances become their wire id\n * strings. Uses a memo Map (not a bail-out set) so shared/diamond references\n * get the SAME converted subtree — a bail-out would leak un-unwrapped Handle\n * instances through the second reference. Cycles are handled by memoizing the\n * output object before recursing. Non-plain objects pass through untouched\n * (structured clone imposes plain-data args anyway).\n */\nexport function unwrapArgs(value: unknown, memo = new Map<object, unknown>()): unknown {\n  if (value instanceof Handle) return value.id\n  if (value === null || typeof value !== \"object\") return value\n\n  const hit = memo.get(value)\n  if (hit !== undefined) return hit\n\n  if (Array.isArray(value)) {\n    const out: unknown[] = []\n    memo.set(value, out)\n    for (const item of value) out.push(unwrapArgs(item, memo))\n    return out\n  }\n\n  const proto = Object.getPrototypeOf(value)\n  if (proto !== Object.prototype && proto !== null) return value\n\n  const out: Record<string, unknown> = {}\n  memo.set(value, out)\n  for (const [key, item] of Object.entries(value)) out[key] = unwrapArgs(item, memo)\n  return out\n}\n","import type {\n  PluginApiCallPayload,\n  PluginApiMethod,\n} from \"@snaptrude/plugin-core\"\nimport { getHostApi } from \"./host-api\"\nimport { unwrapArgs } from \"./handle-runtime\"\n\n/**\n * Build a namespace object whose nested property access maps to a\n * dot-separated host RPC method path, and whose every call dispatches that\n * path through the host bridge.\n *\n * The host exposes the entire plugin API behind a single generic `call()`\n * (see the host `bridge.ts`), and the method string is exactly the property\n * path — so one Proxy replaces every hand-written per-method RPC wrapper for\n * every namespace (`core.*`, `design.*`, `entity.*`):\n *\n * The POSITIONAL transport forwards the whole argument tuple; the host router\n * spreads it back into the resolved method (`fn(...args)`):\n *\n * ```ts\n * snaptrude.core.math.vec3.new(1, 2, 3)\n *   // → getHostApi().call({ method: \"core.math.vec3.new\", args: [1, 2, 3] })\n * ```\n *\n * Typed at the call site, e.g. `createRpcNamespace<PluginEntityApi>(\"entity\")`.\n * The Proxy is structurally cast to the abstract API type — argument and\n * return types are enforced by that type, while dispatch is dynamic.\n *\n * Every namespace uses this — including `core.math.*` and `core.geom.*`: under\n * the all-handle model there is no in-worker compute; math and geometry are\n * host calls like everything else.\n */\nexport function createRpcNamespace<T extends object>(basePath: string): T {\n  const build = (path: string): unknown =>\n    new Proxy(NOOP, {\n      get(_target, prop) {\n        // Symbols and `then` must not resolve to a callable proxy, otherwise\n        // the namespace would look thenable and break Promise resolution if it\n        // ever reached an `await`.\n        if (typeof prop !== \"string\" || prop === \"then\") return undefined\n        return build(`${path}.${prop}`)\n      },\n      apply(_target, _thisArg, argArray: unknown[]) {\n        const payload = {\n          method: path,\n          // Handle instances anywhere in the tuple become their wire id strings.\n          args: argArray.map((arg) => unwrapArgs(arg)),\n        } as unknown as PluginApiCallPayload<PluginApiMethod>\n        return getHostApi().call(payload)\n      },\n    })\n\n  return build(basePath) as T\n}\n\n/** Proxy target must be callable for the `apply` trap; identity is irrelevant. */\nconst NOOP = (): void => {}\n","import * as Comlink from \"comlink\"\nimport type { PluginEventName } from \"./events\"\n\nexport interface UIMessage {\n  action: string\n  payload: unknown\n}\n\ninterface PluginConfig {\n  pluginId: string\n}\n\n/**\n * Base class for Snaptrude plugin workers.\n *\n * Handles Comlink wiring, host communication, and the standard lifecycle\n * methods (`init`, `destroy`, `ping`, `onUIMessage`). Subclass this and\n * override only the methods you need — then call `start()` to expose the\n * worker API.\n *\n * The plugin ID is received automatically from the host during\n * initialization — no need to pass it manually.\n *\n * @example\n * ```ts\n * import { PluginWorker } from \"@snaptrude/plugin-client\";\n *\n * class MyPlugin extends PluginWorker {\n *   async onUIMessage(message: UIMessage) {\n *     // handle messages from the UI panel\n *   }\n * }\n *\n * new MyPlugin().start();\n * ```\n */\nexport abstract class PluginWorker {\n  protected pluginId!: string\n  private hostAPI: Comlink.Remote<Record<string, unknown>>\n\n  constructor() {\n    this.hostAPI = Comlink.wrap<Record<string, unknown>>(\n      self as unknown as Comlink.Endpoint,\n    )\n  }\n\n  protected sendToUI(action: string, payload: unknown): void {\n    ;(this.hostAPI as Record<string, any>).ui.sendToUI({ action, payload })\n  }\n\n  /**\n   * Show a transient notification toast in the Snaptrude editor.\n   *\n   * @param message - Text to display.\n   * @param type - Severity; `\"error\"`/`\"warning\"` linger a little longer than\n   *   `\"info\"`. Defaults to `\"info\"`.\n   */\n  protected notify(\n    message: string,\n    type: \"info\" | \"warning\" | \"error\" = \"info\",\n  ): void {\n    ;(this.hostAPI as Record<string, any>).ui.showNotification(message, type)\n  }\n\n  /**\n   * Signal the host that this plugin has finished its work and should be\n   * stopped. Use this in headless (UI-less) plugins that run a task and\n   * self-terminate.\n   */\n  protected complete(): void {\n    ;(this.hostAPI as Record<string, any>).lifecycle.complete()\n  }\n\n  /**\n   * Subscribe to a host event (e.g. `\"model:changed\"`, fired debounced on any\n   * user- or plugin-initiated model edit). The callback runs in this worker\n   * each time the event fires; its argument is a small structured-clone-safe\n   * payload (see the event's payload type, e.g. `ModelChangedEvent`).\n   *\n   * Fire-and-forget: subscribe once (typically in `init()`). Subscriptions live\n   * for the plugin's lifetime and are cleared automatically when the plugin is\n   * stopped — there is no `unsubscribe` yet.\n   *\n   * @example\n   * ```ts\n   * import type { ModelChangedEvent } from \"@snaptrude/plugin-client\";\n   *\n   * async init() {\n   *   this.subscribe(\"model:changed\", (e) => {\n   *     const { source } = e as ModelChangedEvent;\n   *     console.log(\"model changed via\", source);\n   *   });\n   * }\n   * ```\n   */\n  protected subscribe(\n    event: PluginEventName,\n    callback: (payload?: unknown) => void,\n  ): void {\n    ;(this.hostAPI as Record<string, any>).events.on(\n      event,\n      Comlink.proxy(callback),\n    )\n  }\n\n  async init(): Promise<void> {\n    console.log(this.pluginId, \"init() called\")\n    console.log(this.pluginId, \"Initialization complete\")\n  }\n\n  async destroy(): Promise<void> {\n    console.log(this.pluginId, \"destroy() called — cleaning up\")\n  }\n\n  async ping(): Promise<string> {\n    return \"pong\"\n  }\n\n  async onUIMessage(_message: UIMessage): Promise<void> {\n    // Override in subclass to handle UI messages\n  }\n\n  /**\n   * Expose the worker API via Comlink and start listening.\n   * Call this once after constructing the plugin instance.\n   *\n   * The host calls `init(config)` with `{ pluginId }`,\n   * which is captured here to set `this.pluginId` before the\n   * subclass's `init()` runs.\n   */\n  start(): void {\n    Comlink.expose(\n      {\n        init: (config: PluginConfig) => {\n          this.pluginId = config.pluginId\n          return this.init()\n        },\n        destroy: () => this.destroy(),\n        ping: () => this.ping(),\n        onUIMessage: (message: UIMessage) => this.onUIMessage(message),\n      },\n      self as unknown as Comlink.Endpoint,\n    )\n    console.log(\"Worker loaded, API exposed via Comlink\")\n  }\n}\n","/**\n * Snaptrude plugin events.\n *\n * Plugins can react to changes in the host app. Events are delivered through\n * the host event bus — a separate channel from the request/response\n * `snaptrude.*` API — and carry a small structured-clone-safe payload, never\n * live model data.\n *\n * Subscribe from a {@link PluginWorker} subclass with `this.subscribe(...)`.\n *\n * NOTE: events are a subscription surface, not `call()` RPC methods, so they do\n * NOT appear in the discovery manifest (which enumerates callable methods\n * only). This module is the typed, discoverable declaration of the surface.\n */\n\n/** Every event a plugin can subscribe to. */\nexport const PLUGIN_EVENTS = [\n  \"selection:changed\",\n  \"tool:activated\",\n  \"project:saved\",\n  \"view:changed\",\n  \"model:changed\",\n] as const\n\n/** Union of subscribable event names. */\nexport type PluginEventName = (typeof PLUGIN_EVENTS)[number]\n\n/**\n * Payload for `model:changed` — fired (debounced) whenever the project model is\n * mutated, by a user edit OR a plugin edit. Deliberately minimal: it signals\n * *that* the model changed, never *what* changed. Re-query the API for details.\n */\nexport interface ModelChangedEvent {\n  /** Origin of the change. Currently always `\"command\"` (the edit chokepoint). */\n  source: string\n}\n"],"mappings":"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","names":["import_plugin_core","import_plugin_core","out","Comlink","import_plugin_core"]}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import { ClientPluginApi } from "./api";
+export * from "./api";
+export * from "./host-api";
+export * from "./plugin-worker";
+export * from "./events";
+export { flushReleaseQueue, intern, rewrapResult, unwrapArgs, __setReleaseTransport, } from "./handle-runtime";
+export { PluginError, PluginValidationError, PluginNotFoundError, PluginPermissionError, PluginHandleError, PluginQuotaError, PluginTimeoutError, PluginTransportError, PluginLifecycleError, PluginExecutionError, PluginInternalError, fromEnvelope, isErrorEnvelope, isPluginErrorCode, PLUGIN_ERROR_CODES, CODE_META, } from "@snaptrude/plugin-core";
+export type { ErrorEnvelope, PluginErrorCode, WirePluginErrorCode, PluginErrorCategory, } from "@snaptrude/plugin-core";
+/**
+ * The Snaptrude plugin client API.
+ *
+ * The main entry point for plugins to interact with the Snaptrude platform.
+ */
+export declare const snaptrude: ClientPluginApi;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,OAAO,CAAA;AAEvC,cAAc,OAAO,CAAA;AACrB,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,UAAU,CAAA;AACxB,OAAO,EACL,iBAAiB,EACjB,MAAM,EACN,YAAY,EACZ,UAAU,EACV,qBAAqB,GACtB,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,SAAS,GACV,MAAM,wBAAwB,CAAA;AAC/B,YAAY,EACV,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,wBAAwB,CAAA;AAE/B;;;;GAIG;AACH,eAAO,MAAM,SAAS,iBAAgC,CAAA"}

package/dist/index.js

@@ -0,0 +1,366 @@
+// src/api/index.ts
+import {
+  PluginApi
+} from "@snaptrude/plugin-core";
+
+// src/host-api.ts
+import * as Comlink from "comlink";
+import { PluginError, fromEnvelope, makeClientEnvelope } from "@snaptrude/plugin-core";
+
+// src/handle-runtime.ts
+import { Handle } from "@snaptrude/plugin-core";
+var interned = /* @__PURE__ */ new Map();
+var RELEASE_FLUSH_SIZE = 64;
+var RELEASE_FLUSH_MS = 250;
+var MAX_FLUSH_FAILURES = 5;
+var releaseQueue = /* @__PURE__ */ new Set();
+var flushTimer = null;
+var consecutiveFlushFailures = 0;
+var finalizer = new FinalizationRegistry((id) => {
+  if (interned.get(id)?.deref()) return;
+  interned.delete(id);
+  enqueueRelease(id);
+});
+function intern(id) {
+  releaseQueue.delete(id);
+  const existing = interned.get(id)?.deref();
+  if (existing) return existing;
+  const handle = new Handle(id);
+  handle[Symbol.asyncDispose] = async () => {
+    if (interned.get(id)?.deref() === handle) interned.delete(id);
+    enqueueRelease(id);
+  };
+  interned.set(id, new WeakRef(handle));
+  finalizer.register(handle, id);
+  return handle;
+}
+function enqueueRelease(id) {
+  releaseQueue.add(id);
+  if (releaseQueue.size >= RELEASE_FLUSH_SIZE) {
+    void flushReleaseQueue();
+    return;
+  }
+  flushTimer ?? (flushTimer = setTimeout(() => {
+    void flushReleaseQueue();
+  }, RELEASE_FLUSH_MS));
+}
+var releaseTransport = async (batch) => {
+  await getHostApi().call({
+    method: "core.handles.release",
+    args: [batch]
+  });
+};
+function __setReleaseTransport(transport) {
+  releaseTransport = transport ?? (async (batch) => {
+    await getHostApi().call({
+      method: "core.handles.release",
+      args: [batch]
+    });
+  });
+}
+async function flushReleaseQueue() {
+  if (flushTimer) {
+    clearTimeout(flushTimer);
+    flushTimer = null;
+  }
+  if (releaseQueue.size === 0) return;
+  const batch = [...releaseQueue];
+  releaseQueue.clear();
+  try {
+    await releaseTransport(batch);
+    consecutiveFlushFailures = 0;
+  } catch (err) {
+    consecutiveFlushFailures += 1;
+    if (consecutiveFlushFailures >= MAX_FLUSH_FAILURES) {
+      console.warn(
+        `[snaptrude] dropping ${batch.length} handle release(s) after ${consecutiveFlushFailures} failed flushes`,
+        err
+      );
+      consecutiveFlushFailures = 0;
+      return;
+    }
+    for (const id of batch) {
+      if (!interned.get(id)?.deref()) releaseQueue.add(id);
+    }
+  }
+}
+function rewrapResult(value) {
+  if (Array.isArray(value)) return value.map(rewrapResult);
+  if (value && typeof value === "object") {
+    const record = value;
+    const keys = Object.keys(record);
+    if (keys.length === 1 && keys[0] === "__h" && typeof record.__h === "string") {
+      return intern(record.__h);
+    }
+    for (const key of keys) record[key] = rewrapResult(record[key]);
+    return record;
+  }
+  return value;
+}
+function unwrapArgs(value, memo = /* @__PURE__ */ new Map()) {
+  if (value instanceof Handle) return value.id;
+  if (value === null || typeof value !== "object") return value;
+  const hit = memo.get(value);
+  if (hit !== void 0) return hit;
+  if (Array.isArray(value)) {
+    const out2 = [];
+    memo.set(value, out2);
+    for (const item of value) out2.push(unwrapArgs(item, memo));
+    return out2;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return value;
+  const out = {};
+  memo.set(value, out);
+  for (const [key, item] of Object.entries(value)) out[key] = unwrapArgs(item, memo);
+  return out;
+}
+
+// src/host-api.ts
+function createHostApi(endpoint) {
+  return Comlink.wrap(
+    endpoint ?? globalThis
+  );
+}
+var _instance = null;
+function __setHostApiInstance(instance) {
+  _instance = instance ?? null;
+}
+function getHostApi() {
+  if (!_instance) {
+    _instance = createHostApi();
+  }
+  return {
+    call: async (payload) => {
+      if (!_instance) {
+        throw new Error("Host API not initialized");
+      }
+      let result;
+      try {
+        result = await _instance.call(payload);
+      } catch (transportErr) {
+        if (PluginError.is(transportErr)) throw transportErr;
+        throw rehydrate(
+          makeClientEnvelope(
+            "TRANSPORT_LOST",
+            transportErr instanceof Error ? transportErr.message : String(transportErr),
+            { methodPath: payload.method }
+          )
+        );
+      }
+      if (result.success) {
+        return rewrapResult(result.data);
+      }
+      throw rehydrate(
+        result.errorInfo ?? makeClientEnvelope("UNKNOWN", result.error ?? "Unknown host error", {
+          methodPath: payload.method
+        })
+      );
+    }
+  };
+}
+function rehydrate(envelope) {
+  const error = fromEnvelope(envelope);
+  Error.captureStackTrace?.(error, rehydrate);
+  return error;
+}
+
+// src/rpc-proxy.ts
+function createRpcNamespace(basePath) {
+  const build = (path) => new Proxy(NOOP, {
+    get(_target, prop) {
+      if (typeof prop !== "string" || prop === "then") return void 0;
+      return build(`${path}.${prop}`);
+    },
+    apply(_target, _thisArg, argArray) {
+      const payload = {
+        method: path,
+        // Handle instances anywhere in the tuple become their wire id strings.
+        args: argArray.map((arg) => unwrapArgs(arg))
+      };
+      return getHostApi().call(payload);
+    }
+  });
+  return build(basePath);
+}
+var NOOP = () => {
+};
+
+// src/api/index.ts
+var ClientPluginApi = class _ClientPluginApi extends PluginApi {
+  constructor() {
+    super();
+    this.core = createRpcNamespace("core");
+    this.design = createRpcNamespace("design");
+    this.entity = createRpcNamespace("entity");
+    this.program = createRpcNamespace("program");
+    this.presentation = createRpcNamespace("presentation");
+    this.analysis = createRpcNamespace("analysis");
+    this.workspace = createRpcNamespace("workspace");
+  }
+  static getInstance() {
+    if (!_ClientPluginApi.instance) {
+      _ClientPluginApi.instance = new _ClientPluginApi();
+    }
+    return _ClientPluginApi.instance;
+  }
+};
+
+// src/plugin-worker.ts
+import * as Comlink2 from "comlink";
+var PluginWorker = class {
+  constructor() {
+    this.hostAPI = Comlink2.wrap(
+      self
+    );
+  }
+  sendToUI(action, payload) {
+    ;
+    this.hostAPI.ui.sendToUI({ action, payload });
+  }
+  /**
+   * Show a transient notification toast in the Snaptrude editor.
+   *
+   * @param message - Text to display.
+   * @param type - Severity; `"error"`/`"warning"` linger a little longer than
+   *   `"info"`. Defaults to `"info"`.
+   */
+  notify(message, type = "info") {
+    ;
+    this.hostAPI.ui.showNotification(message, type);
+  }
+  /**
+   * Signal the host that this plugin has finished its work and should be
+   * stopped. Use this in headless (UI-less) plugins that run a task and
+   * self-terminate.
+   */
+  complete() {
+    ;
+    this.hostAPI.lifecycle.complete();
+  }
+  /**
+   * Subscribe to a host event (e.g. `"model:changed"`, fired debounced on any
+   * user- or plugin-initiated model edit). The callback runs in this worker
+   * each time the event fires; its argument is a small structured-clone-safe
+   * payload (see the event's payload type, e.g. `ModelChangedEvent`).
+   *
+   * Fire-and-forget: subscribe once (typically in `init()`). Subscriptions live
+   * for the plugin's lifetime and are cleared automatically when the plugin is
+   * stopped — there is no `unsubscribe` yet.
+   *
+   * @example
+   * ```ts
+   * import type { ModelChangedEvent } from "@snaptrude/plugin-client";
+   *
+   * async init() {
+   *   this.subscribe("model:changed", (e) => {
+   *     const { source } = e as ModelChangedEvent;
+   *     console.log("model changed via", source);
+   *   });
+   * }
+   * ```
+   */
+  subscribe(event, callback) {
+    ;
+    this.hostAPI.events.on(
+      event,
+      Comlink2.proxy(callback)
+    );
+  }
+  async init() {
+    console.log(this.pluginId, "init() called");
+    console.log(this.pluginId, "Initialization complete");
+  }
+  async destroy() {
+    console.log(this.pluginId, "destroy() called \u2014 cleaning up");
+  }
+  async ping() {
+    return "pong";
+  }
+  async onUIMessage(_message) {
+  }
+  /**
+   * Expose the worker API via Comlink and start listening.
+   * Call this once after constructing the plugin instance.
+   *
+   * The host calls `init(config)` with `{ pluginId }`,
+   * which is captured here to set `this.pluginId` before the
+   * subclass's `init()` runs.
+   */
+  start() {
+    Comlink2.expose(
+      {
+        init: (config) => {
+          this.pluginId = config.pluginId;
+          return this.init();
+        },
+        destroy: () => this.destroy(),
+        ping: () => this.ping(),
+        onUIMessage: (message) => this.onUIMessage(message)
+      },
+      self
+    );
+    console.log("Worker loaded, API exposed via Comlink");
+  }
+};
+
+// src/events.ts
+var PLUGIN_EVENTS = [
+  "selection:changed",
+  "tool:activated",
+  "project:saved",
+  "view:changed",
+  "model:changed"
+];
+
+// src/index.ts
+import {
+  PluginError as PluginError2,
+  PluginValidationError,
+  PluginNotFoundError,
+  PluginPermissionError,
+  PluginHandleError,
+  PluginQuotaError,
+  PluginTimeoutError,
+  PluginTransportError,
+  PluginLifecycleError,
+  PluginExecutionError,
+  PluginInternalError,
+  fromEnvelope as fromEnvelope2,
+  isErrorEnvelope,
+  isPluginErrorCode,
+  PLUGIN_ERROR_CODES,
+  CODE_META
+} from "@snaptrude/plugin-core";
+var snaptrude = ClientPluginApi.getInstance();
+export {
+  CODE_META,
+  ClientPluginApi,
+  PLUGIN_ERROR_CODES,
+  PLUGIN_EVENTS,
+  PluginError2 as PluginError,
+  PluginExecutionError,
+  PluginHandleError,
+  PluginInternalError,
+  PluginLifecycleError,
+  PluginNotFoundError,
+  PluginPermissionError,
+  PluginQuotaError,
+  PluginTimeoutError,
+  PluginTransportError,
+  PluginValidationError,
+  PluginWorker,
+  __setHostApiInstance,
+  __setReleaseTransport,
+  createHostApi,
+  flushReleaseQueue,
+  fromEnvelope2 as fromEnvelope,
+  getHostApi,
+  intern,
+  isErrorEnvelope,
+  isPluginErrorCode,
+  rewrapResult,
+  snaptrude,
+  unwrapArgs
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/api/index.ts","../src/host-api.ts","../src/handle-runtime.ts","../src/rpc-proxy.ts","../src/plugin-worker.ts","../src/events.ts","../src/index.ts"],"sourcesContent":["import {\n  PluginApi,\n  PluginCoreApi,\n  PluginDesignApi,\n  PluginEntityApi,\n  PluginProgramApi,\n  PluginPresentationApi,\n  PluginAnalysisApi,\n  PluginWorkspaceApi,\n} from \"@snaptrude/plugin-core\"\nimport { createRpcNamespace } from \"../rpc-proxy\"\n\nexport class ClientPluginApi extends PluginApi {\n  private static instance: ClientPluginApi\n\n  /**\n   * Every namespace is fully remote under the all-handle model: math/geom now\n   * cross to the host (values are opaque handles), so there is no in-worker\n   * compute left. All dispatch through a single generic RPC Proxy. Units live\n   * under `core.units`, so they ride the `core` proxy.\n   */\n  public core: PluginCoreApi\n  public design: PluginDesignApi\n  public entity: PluginEntityApi\n  public program: PluginProgramApi\n  public presentation: PluginPresentationApi\n  public analysis: PluginAnalysisApi\n  public workspace: PluginWorkspaceApi\n\n  private constructor() {\n    super()\n    this.core = createRpcNamespace<PluginCoreApi>(\"core\")\n    this.design = createRpcNamespace<PluginDesignApi>(\"design\")\n    this.entity = createRpcNamespace<PluginEntityApi>(\"entity\")\n    this.program = createRpcNamespace<PluginProgramApi>(\"program\")\n    this.presentation =\n      createRpcNamespace<PluginPresentationApi>(\"presentation\")\n    this.analysis = createRpcNamespace<PluginAnalysisApi>(\"analysis\")\n    this.workspace = createRpcNamespace<PluginWorkspaceApi>(\"workspace\")\n  }\n\n  static getInstance(): ClientPluginApi {\n    if (!ClientPluginApi.instance) {\n      ClientPluginApi.instance = new ClientPluginApi()\n    }\n    return ClientPluginApi.instance\n  }\n}\n","import * as Comlink from \"comlink\"\nimport type {\n  PluginApiMethod,\n  PluginApiCallPayload,\n  PluginApiCallWrappedResult,\n  PluginApiCallResult,\n} from \"@snaptrude/plugin-core\"\nimport { PluginError, fromEnvelope, makeClientEnvelope } from \"@snaptrude/plugin-core\"\nimport { rewrapResult } from \"./handle-runtime\"\n\nexport interface HostApi {\n  call<M extends PluginApiMethod>(\n    payload: PluginApiCallPayload<M>\n  ): Promise<PluginApiCallWrappedResult<M>>\n}\n\nexport interface HostApiWrapped {\n  call<M extends PluginApiMethod>(\n    payload: PluginApiCallPayload<M>\n  ): Promise<PluginApiCallResult<M>>\n}\n\nexport function createHostApi(endpoint?: Comlink.Endpoint): HostApi {\n  return Comlink.wrap<HostApi>(\n    endpoint ?? (globalThis as unknown as Comlink.Endpoint)\n  ) as unknown as HostApi\n}\n\nlet _instance: HostApi | null = null\n\n/** TEST SEAM ONLY: replace the Comlink host instance (pass `undefined` to reset). */\nexport function __setHostApiInstance(instance?: HostApi): void {\n  _instance = instance ?? null\n}\n\nexport function getHostApi(): HostApiWrapped {\n  if (!_instance) {\n    _instance = createHostApi()\n  }\n  return {\n    call: async <M extends PluginApiMethod>(payload: PluginApiCallPayload<M>): Promise<PluginApiCallResult<M>> => {\n      if (!_instance) {\n        throw new Error(\"Host API not initialized\")\n      }\n\n      let result: PluginApiCallWrappedResult<M>\n      try {\n        result = await _instance.call(payload)\n      } catch (transportErr) {\n        // Comlink-level rejection: port closed, worker terminated, clone\n        // failure. Never a routed failure — the router always RETURNS its\n        // envelope — so normalize to a typed transport error.\n        if (PluginError.is(transportErr)) throw transportErr\n        throw rehydrate(\n          makeClientEnvelope(\n            \"TRANSPORT_LOST\",\n            transportErr instanceof Error ? transportErr.message : String(transportErr),\n            { methodPath: payload.method }\n          )\n        )\n      }\n\n      if (result.success) {\n        // Re-wrap tagged handles ({__h: id} → interned Handle instances).\n        return rewrapResult(result.data) as PluginApiCallResult<M>\n      }\n\n      // Structured envelope when the host provides one; legacy hosts (string\n      // `error` only) degrade to UNKNOWN with the message preserved.\n      throw rehydrate(\n        result.errorInfo ??\n          makeClientEnvelope(\"UNKNOWN\", result.error ?? \"Unknown host error\", {\n            methodPath: payload.method,\n          })\n      )\n    }\n  }\n}\n\n/**\n * Envelope → typed `PluginError`, with the stack trimmed to the plugin's call\n * site (V8 only; harmless no-op elsewhere) instead of transport internals.\n */\nfunction rehydrate(envelope: Parameters<typeof fromEnvelope>[0]): PluginError {\n  const error = fromEnvelope(envelope)\n  ;(Error as { captureStackTrace?: (target: object, ctor: Function) => void })\n    .captureStackTrace?.(error, rehydrate)\n  return error\n}\n","import { Handle } from \"@snaptrude/plugin-core\"\nimport { getHostApi } from \"./host-api\"\n\n/**\n * Worker-side handle lifecycle runtime (P1):\n *\n * - **Interning** — one live `Handle` instance per id, so `===`, `Set`, and\n *   `Map` keys keep working exactly as they did when handles were raw strings\n *   (the host identity-dedups resource/topology handles, so the same id\n *   arrives repeatedly).\n * - **FinalizationRegistry backstop** — when the plugin drops every reference\n *   to a handle, its host registry entry is eventually released without any\n *   author action. Eventual, not timely: deterministic release\n *   (`core.handles.release` / scopes / `await using`) remains the primary tool.\n * - **Batched release queue** — finalizer hits and `Symbol.asyncDispose` calls\n *   collapse into one `core.handles.release([...])` RPC per flush.\n */\n\nconst interned = new Map<string, WeakRef<Handle<string>>>()\n\nconst RELEASE_FLUSH_SIZE = 64\nconst RELEASE_FLUSH_MS = 250\nconst MAX_FLUSH_FAILURES = 5\n\nconst releaseQueue = new Set<string>()\nlet flushTimer: ReturnType<typeof setTimeout> | null = null\nlet consecutiveFlushFailures = 0\n\nconst finalizer = new FinalizationRegistry<string>((id) => {\n  // A NEW wrapper for the same id may have been interned after the collected\n  // one died (deduped topology re-enumeration) — releasing then would free a\n  // handle the plugin still holds. Only release when no live wrapper remains.\n  if (interned.get(id)?.deref()) return\n  interned.delete(id)\n  enqueueRelease(id)\n})\n\n/**\n * Return THE `Handle` instance for this id — the existing live wrapper when\n * present, else a fresh one wired for auto-release.\n */\nexport function intern(id: string): Handle<string> {\n  // The host just (re-)vended this id, so it is live host-side. Cancel any\n  // PENDING auto-release for it — covers the finalizer-already-ran window\n  // (old wrapper collected, id queued, same id re-vended before the flush;\n  // without this the flush would release a handle the plugin holds live).\n  releaseQueue.delete(id)\n\n  const existing = interned.get(id)?.deref()\n  if (existing) return existing\n\n  const handle = new Handle<string>(id)\n  // Instance-level override shadows the class's no-op placeholder. Explicit\n  // dispose also UN-interns the wrapper: (a) the flush-failure retry filter\n  // skips ids with a live interned wrapper, so a still-interned explicit\n  // dispose would never be retried; (b) if the host re-vends the id later,\n  // a fresh wrapper is minted instead of resurrecting the disposed one.\n  ;(handle as { [Symbol.asyncDispose]?: () => Promise<void> })[Symbol.asyncDispose] =\n    async () => {\n      if (interned.get(id)?.deref() === handle) interned.delete(id)\n      enqueueRelease(id)\n    }\n  interned.set(id, new WeakRef(handle))\n  finalizer.register(handle, id)\n  return handle\n}\n\nfunction enqueueRelease(id: string): void {\n  releaseQueue.add(id)\n  if (releaseQueue.size >= RELEASE_FLUSH_SIZE) {\n    void flushReleaseQueue()\n    return\n  }\n  flushTimer ??= setTimeout(() => {\n    void flushReleaseQueue()\n  }, RELEASE_FLUSH_MS)\n}\n\n/** How a release batch reaches the host. Swappable for tests (`__setReleaseTransport`). */\nlet releaseTransport = async (batch: string[]): Promise<void> => {\n  await getHostApi().call({\n    method: \"core.handles.release\",\n    args: [batch],\n  } as never)\n}\n\n/** TEST SEAM ONLY: replace the release transport (pass `undefined` to restore). */\nexport function __setReleaseTransport(\n  transport?: (batch: string[]) => Promise<void>\n): void {\n  releaseTransport =\n    transport ??\n    (async (batch: string[]) => {\n      await getHostApi().call({\n        method: \"core.handles.release\",\n        args: [batch],\n      } as never)\n    })\n}\n\n/** Exported for tests and for an eager flush before a plugin self-completes. */\nexport async function flushReleaseQueue(): Promise<void> {\n  if (flushTimer) {\n    clearTimeout(flushTimer)\n    flushTimer = null\n  }\n  if (releaseQueue.size === 0) return\n  const batch = [...releaseQueue]\n  releaseQueue.clear()\n  try {\n    await releaseTransport(batch)\n    consecutiveFlushFailures = 0\n  } catch (err) {\n    // Transient failure (rate limit, timeout): re-queue so the entries are not\n    // permanently leaked host-side; the next enqueue/flush retries. Ids the\n    // plugin re-acquired in the meantime were already purged by intern() and\n    // must not be re-added. If the host is simply gone, the plugin is stopping\n    // and registry teardown reclaims everything anyway.\n    consecutiveFlushFailures += 1\n    if (consecutiveFlushFailures >= MAX_FLUSH_FAILURES) {\n      // Persistent failure: retrying forever would just spin. Drop the batch\n      // loudly — host teardown reclaims the entries when the plugin stops.\n      console.warn(\n        `[snaptrude] dropping ${batch.length} handle release(s) after ${consecutiveFlushFailures} failed flushes`,\n        err\n      )\n      consecutiveFlushFailures = 0\n      return\n    }\n    for (const id of batch) {\n      if (!interned.get(id)?.deref()) releaseQueue.add(id)\n    }\n  }\n}\n\n/**\n * Recursively re-wrap a host result: `{ __h: \"<id>\" }` tags (produced by\n * `Handle.toJSON` through the host's JSON-round-trip serialization) become\n * interned `Handle` instances. Arrays and plain records are walked; all other\n * values pass through untouched.\n */\nexport function rewrapResult(value: unknown): unknown {\n  if (Array.isArray(value)) return value.map(rewrapResult)\n  if (value && typeof value === \"object\") {\n    const record = value as Record<string, unknown>\n    const keys = Object.keys(record)\n    if (keys.length === 1 && keys[0] === \"__h\" && typeof record.__h === \"string\") {\n      return intern(record.__h)\n    }\n    for (const key of keys) record[key] = rewrapResult(record[key])\n    return record\n  }\n  return value\n}\n\n/**\n * Recursively unwrap outgoing args: `Handle` instances become their wire id\n * strings. Uses a memo Map (not a bail-out set) so shared/diamond references\n * get the SAME converted subtree — a bail-out would leak un-unwrapped Handle\n * instances through the second reference. Cycles are handled by memoizing the\n * output object before recursing. Non-plain objects pass through untouched\n * (structured clone imposes plain-data args anyway).\n */\nexport function unwrapArgs(value: unknown, memo = new Map<object, unknown>()): unknown {\n  if (value instanceof Handle) return value.id\n  if (value === null || typeof value !== \"object\") return value\n\n  const hit = memo.get(value)\n  if (hit !== undefined) return hit\n\n  if (Array.isArray(value)) {\n    const out: unknown[] = []\n    memo.set(value, out)\n    for (const item of value) out.push(unwrapArgs(item, memo))\n    return out\n  }\n\n  const proto = Object.getPrototypeOf(value)\n  if (proto !== Object.prototype && proto !== null) return value\n\n  const out: Record<string, unknown> = {}\n  memo.set(value, out)\n  for (const [key, item] of Object.entries(value)) out[key] = unwrapArgs(item, memo)\n  return out\n}\n","import type {\n  PluginApiCallPayload,\n  PluginApiMethod,\n} from \"@snaptrude/plugin-core\"\nimport { getHostApi } from \"./host-api\"\nimport { unwrapArgs } from \"./handle-runtime\"\n\n/**\n * Build a namespace object whose nested property access maps to a\n * dot-separated host RPC method path, and whose every call dispatches that\n * path through the host bridge.\n *\n * The host exposes the entire plugin API behind a single generic `call()`\n * (see the host `bridge.ts`), and the method string is exactly the property\n * path — so one Proxy replaces every hand-written per-method RPC wrapper for\n * every namespace (`core.*`, `design.*`, `entity.*`):\n *\n * The POSITIONAL transport forwards the whole argument tuple; the host router\n * spreads it back into the resolved method (`fn(...args)`):\n *\n * ```ts\n * snaptrude.core.math.vec3.new(1, 2, 3)\n *   // → getHostApi().call({ method: \"core.math.vec3.new\", args: [1, 2, 3] })\n * ```\n *\n * Typed at the call site, e.g. `createRpcNamespace<PluginEntityApi>(\"entity\")`.\n * The Proxy is structurally cast to the abstract API type — argument and\n * return types are enforced by that type, while dispatch is dynamic.\n *\n * Every namespace uses this — including `core.math.*` and `core.geom.*`: under\n * the all-handle model there is no in-worker compute; math and geometry are\n * host calls like everything else.\n */\nexport function createRpcNamespace<T extends object>(basePath: string): T {\n  const build = (path: string): unknown =>\n    new Proxy(NOOP, {\n      get(_target, prop) {\n        // Symbols and `then` must not resolve to a callable proxy, otherwise\n        // the namespace would look thenable and break Promise resolution if it\n        // ever reached an `await`.\n        if (typeof prop !== \"string\" || prop === \"then\") return undefined\n        return build(`${path}.${prop}`)\n      },\n      apply(_target, _thisArg, argArray: unknown[]) {\n        const payload = {\n          method: path,\n          // Handle instances anywhere in the tuple become their wire id strings.\n          args: argArray.map((arg) => unwrapArgs(arg)),\n        } as unknown as PluginApiCallPayload<PluginApiMethod>\n        return getHostApi().call(payload)\n      },\n    })\n\n  return build(basePath) as T\n}\n\n/** Proxy target must be callable for the `apply` trap; identity is irrelevant. */\nconst NOOP = (): void => {}\n","import * as Comlink from \"comlink\"\nimport type { PluginEventName } from \"./events\"\n\nexport interface UIMessage {\n  action: string\n  payload: unknown\n}\n\ninterface PluginConfig {\n  pluginId: string\n}\n\n/**\n * Base class for Snaptrude plugin workers.\n *\n * Handles Comlink wiring, host communication, and the standard lifecycle\n * methods (`init`, `destroy`, `ping`, `onUIMessage`). Subclass this and\n * override only the methods you need — then call `start()` to expose the\n * worker API.\n *\n * The plugin ID is received automatically from the host during\n * initialization — no need to pass it manually.\n *\n * @example\n * ```ts\n * import { PluginWorker } from \"@snaptrude/plugin-client\";\n *\n * class MyPlugin extends PluginWorker {\n *   async onUIMessage(message: UIMessage) {\n *     // handle messages from the UI panel\n *   }\n * }\n *\n * new MyPlugin().start();\n * ```\n */\nexport abstract class PluginWorker {\n  protected pluginId!: string\n  private hostAPI: Comlink.Remote<Record<string, unknown>>\n\n  constructor() {\n    this.hostAPI = Comlink.wrap<Record<string, unknown>>(\n      self as unknown as Comlink.Endpoint,\n    )\n  }\n\n  protected sendToUI(action: string, payload: unknown): void {\n    ;(this.hostAPI as Record<string, any>).ui.sendToUI({ action, payload })\n  }\n\n  /**\n   * Show a transient notification toast in the Snaptrude editor.\n   *\n   * @param message - Text to display.\n   * @param type - Severity; `\"error\"`/`\"warning\"` linger a little longer than\n   *   `\"info\"`. Defaults to `\"info\"`.\n   */\n  protected notify(\n    message: string,\n    type: \"info\" | \"warning\" | \"error\" = \"info\",\n  ): void {\n    ;(this.hostAPI as Record<string, any>).ui.showNotification(message, type)\n  }\n\n  /**\n   * Signal the host that this plugin has finished its work and should be\n   * stopped. Use this in headless (UI-less) plugins that run a task and\n   * self-terminate.\n   */\n  protected complete(): void {\n    ;(this.hostAPI as Record<string, any>).lifecycle.complete()\n  }\n\n  /**\n   * Subscribe to a host event (e.g. `\"model:changed\"`, fired debounced on any\n   * user- or plugin-initiated model edit). The callback runs in this worker\n   * each time the event fires; its argument is a small structured-clone-safe\n   * payload (see the event's payload type, e.g. `ModelChangedEvent`).\n   *\n   * Fire-and-forget: subscribe once (typically in `init()`). Subscriptions live\n   * for the plugin's lifetime and are cleared automatically when the plugin is\n   * stopped — there is no `unsubscribe` yet.\n   *\n   * @example\n   * ```ts\n   * import type { ModelChangedEvent } from \"@snaptrude/plugin-client\";\n   *\n   * async init() {\n   *   this.subscribe(\"model:changed\", (e) => {\n   *     const { source } = e as ModelChangedEvent;\n   *     console.log(\"model changed via\", source);\n   *   });\n   * }\n   * ```\n   */\n  protected subscribe(\n    event: PluginEventName,\n    callback: (payload?: unknown) => void,\n  ): void {\n    ;(this.hostAPI as Record<string, any>).events.on(\n      event,\n      Comlink.proxy(callback),\n    )\n  }\n\n  async init(): Promise<void> {\n    console.log(this.pluginId, \"init() called\")\n    console.log(this.pluginId, \"Initialization complete\")\n  }\n\n  async destroy(): Promise<void> {\n    console.log(this.pluginId, \"destroy() called — cleaning up\")\n  }\n\n  async ping(): Promise<string> {\n    return \"pong\"\n  }\n\n  async onUIMessage(_message: UIMessage): Promise<void> {\n    // Override in subclass to handle UI messages\n  }\n\n  /**\n   * Expose the worker API via Comlink and start listening.\n   * Call this once after constructing the plugin instance.\n   *\n   * The host calls `init(config)` with `{ pluginId }`,\n   * which is captured here to set `this.pluginId` before the\n   * subclass's `init()` runs.\n   */\n  start(): void {\n    Comlink.expose(\n      {\n        init: (config: PluginConfig) => {\n          this.pluginId = config.pluginId\n          return this.init()\n        },\n        destroy: () => this.destroy(),\n        ping: () => this.ping(),\n        onUIMessage: (message: UIMessage) => this.onUIMessage(message),\n      },\n      self as unknown as Comlink.Endpoint,\n    )\n    console.log(\"Worker loaded, API exposed via Comlink\")\n  }\n}\n","/**\n * Snaptrude plugin events.\n *\n * Plugins can react to changes in the host app. Events are delivered through\n * the host event bus — a separate channel from the request/response\n * `snaptrude.*` API — and carry a small structured-clone-safe payload, never\n * live model data.\n *\n * Subscribe from a {@link PluginWorker} subclass with `this.subscribe(...)`.\n *\n * NOTE: events are a subscription surface, not `call()` RPC methods, so they do\n * NOT appear in the discovery manifest (which enumerates callable methods\n * only). This module is the typed, discoverable declaration of the surface.\n */\n\n/** Every event a plugin can subscribe to. */\nexport const PLUGIN_EVENTS = [\n  \"selection:changed\",\n  \"tool:activated\",\n  \"project:saved\",\n  \"view:changed\",\n  \"model:changed\",\n] as const\n\n/** Union of subscribable event names. */\nexport type PluginEventName = (typeof PLUGIN_EVENTS)[number]\n\n/**\n * Payload for `model:changed` — fired (debounced) whenever the project model is\n * mutated, by a user edit OR a plugin edit. Deliberately minimal: it signals\n * *that* the model changed, never *what* changed. Re-query the API for details.\n */\nexport interface ModelChangedEvent {\n  /** Origin of the change. Currently always `\"command\"` (the edit chokepoint). */\n  source: string\n}\n","import { ClientPluginApi } from \"./api\"\n\nexport * from \"./api\"\nexport * from \"./host-api\"\nexport * from \"./plugin-worker\"\nexport * from \"./events\"\nexport {\n  flushReleaseQueue,\n  intern,\n  rewrapResult,\n  unwrapArgs,\n  __setReleaseTransport,\n} from \"./handle-runtime\"\n\n// Error surface — plugins branch on `PluginError.is(e)` + `e.code`.\nexport {\n  PluginError,\n  PluginValidationError,\n  PluginNotFoundError,\n  PluginPermissionError,\n  PluginHandleError,\n  PluginQuotaError,\n  PluginTimeoutError,\n  PluginTransportError,\n  PluginLifecycleError,\n  PluginExecutionError,\n  PluginInternalError,\n  fromEnvelope,\n  isErrorEnvelope,\n  isPluginErrorCode,\n  PLUGIN_ERROR_CODES,\n  CODE_META,\n} from \"@snaptrude/plugin-core\"\nexport type {\n  ErrorEnvelope,\n  PluginErrorCode,\n  WirePluginErrorCode,\n  PluginErrorCategory,\n} from \"@snaptrude/plugin-core\"\n\n/**\n * The Snaptrude plugin client API.\n *\n * The main entry point for plugins to interact with the Snaptrude platform.\n */\nexport const snaptrude = ClientPluginApi.getInstance()\n"],"mappings":";AAAA;AAAA,EACE;AAAA,OAQK;;;ACTP,YAAY,aAAa;AAOzB,SAAS,aAAa,cAAc,0BAA0B;;;ACP9D,SAAS,cAAc;AAkBvB,IAAM,WAAW,oBAAI,IAAqC;AAE1D,IAAM,qBAAqB;AAC3B,IAAM,mBAAmB;AACzB,IAAM,qBAAqB;AAE3B,IAAM,eAAe,oBAAI,IAAY;AACrC,IAAI,aAAmD;AACvD,IAAI,2BAA2B;AAE/B,IAAM,YAAY,IAAI,qBAA6B,CAAC,OAAO;AAIzD,MAAI,SAAS,IAAI,EAAE,GAAG,MAAM,EAAG;AAC/B,WAAS,OAAO,EAAE;AAClB,iBAAe,EAAE;AACnB,CAAC;AAMM,SAAS,OAAO,IAA4B;AAKjD,eAAa,OAAO,EAAE;AAEtB,QAAM,WAAW,SAAS,IAAI,EAAE,GAAG,MAAM;AACzC,MAAI,SAAU,QAAO;AAErB,QAAM,SAAS,IAAI,OAAe,EAAE;AAMnC,EAAC,OAA2D,OAAO,YAAY,IAC9E,YAAY;AACV,QAAI,SAAS,IAAI,EAAE,GAAG,MAAM,MAAM,OAAQ,UAAS,OAAO,EAAE;AAC5D,mBAAe,EAAE;AAAA,EACnB;AACF,WAAS,IAAI,IAAI,IAAI,QAAQ,MAAM,CAAC;AACpC,YAAU,SAAS,QAAQ,EAAE;AAC7B,SAAO;AACT;AAEA,SAAS,eAAe,IAAkB;AACxC,eAAa,IAAI,EAAE;AACnB,MAAI,aAAa,QAAQ,oBAAoB;AAC3C,SAAK,kBAAkB;AACvB;AAAA,EACF;AACA,8BAAe,WAAW,MAAM;AAC9B,SAAK,kBAAkB;AAAA,EACzB,GAAG,gBAAgB;AACrB;AAGA,IAAI,mBAAmB,OAAO,UAAmC;AAC/D,QAAM,WAAW,EAAE,KAAK;AAAA,IACtB,QAAQ;AAAA,IACR,MAAM,CAAC,KAAK;AAAA,EACd,CAAU;AACZ;AAGO,SAAS,sBACd,WACM;AACN,qBACE,cACC,OAAO,UAAoB;AAC1B,UAAM,WAAW,EAAE,KAAK;AAAA,MACtB,QAAQ;AAAA,MACR,MAAM,CAAC,KAAK;AAAA,IACd,CAAU;AAAA,EACZ;AACJ;AAGA,eAAsB,oBAAmC;AACvD,MAAI,YAAY;AACd,iBAAa,UAAU;AACvB,iBAAa;AAAA,EACf;AACA,MAAI,aAAa,SAAS,EAAG;AAC7B,QAAM,QAAQ,CAAC,GAAG,YAAY;AAC9B,eAAa,MAAM;AACnB,MAAI;AACF,UAAM,iBAAiB,KAAK;AAC5B,+BAA2B;AAAA,EAC7B,SAAS,KAAK;AAMZ,gCAA4B;AAC5B,QAAI,4BAA4B,oBAAoB;AAGlD,cAAQ;AAAA,QACN,wBAAwB,MAAM,MAAM,4BAA4B,wBAAwB;AAAA,QACxF;AAAA,MACF;AACA,iCAA2B;AAC3B;AAAA,IACF;AACA,eAAW,MAAM,OAAO;AACtB,UAAI,CAAC,SAAS,IAAI,EAAE,GAAG,MAAM,EAAG,cAAa,IAAI,EAAE;AAAA,IACrD;AAAA,EACF;AACF;AAQO,SAAS,aAAa,OAAyB;AACpD,MAAI,MAAM,QAAQ,KAAK,EAAG,QAAO,MAAM,IAAI,YAAY;AACvD,MAAI,SAAS,OAAO,UAAU,UAAU;AACtC,UAAM,SAAS;AACf,UAAM,OAAO,OAAO,KAAK,MAAM;AAC/B,QAAI,KAAK,WAAW,KAAK,KAAK,CAAC,MAAM,SAAS,OAAO,OAAO,QAAQ,UAAU;AAC5E,aAAO,OAAO,OAAO,GAAG;AAAA,IAC1B;AACA,eAAW,OAAO,KAAM,QAAO,GAAG,IAAI,aAAa,OAAO,GAAG,CAAC;AAC9D,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAUO,SAAS,WAAW,OAAgB,OAAO,oBAAI,IAAqB,GAAY;AACrF,MAAI,iBAAiB,OAAQ,QAAO,MAAM;AAC1C,MAAI,UAAU,QAAQ,OAAO,UAAU,SAAU,QAAO;AAExD,QAAM,MAAM,KAAK,IAAI,KAAK;AAC1B,MAAI,QAAQ,OAAW,QAAO;AAE9B,MAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,UAAMA,OAAiB,CAAC;AACxB,SAAK,IAAI,OAAOA,IAAG;AACnB,eAAW,QAAQ,MAAO,CAAAA,KAAI,KAAK,WAAW,MAAM,IAAI,CAAC;AACzD,WAAOA;AAAA,EACT;AAEA,QAAM,QAAQ,OAAO,eAAe,KAAK;AACzC,MAAI,UAAU,OAAO,aAAa,UAAU,KAAM,QAAO;AAEzD,QAAM,MAA+B,CAAC;AACtC,OAAK,IAAI,OAAO,GAAG;AACnB,aAAW,CAAC,KAAK,IAAI,KAAK,OAAO,QAAQ,KAAK,EAAG,KAAI,GAAG,IAAI,WAAW,MAAM,IAAI;AACjF,SAAO;AACT;;;ADlKO,SAAS,cAAc,UAAsC;AAClE,SAAe;AAAA,IACb,YAAa;AAAA,EACf;AACF;AAEA,IAAI,YAA4B;AAGzB,SAAS,qBAAqB,UAA0B;AAC7D,cAAY,YAAY;AAC1B;AAEO,SAAS,aAA6B;AAC3C,MAAI,CAAC,WAAW;AACd,gBAAY,cAAc;AAAA,EAC5B;AACA,SAAO;AAAA,IACL,MAAM,OAAkC,YAAsE;AAC5G,UAAI,CAAC,WAAW;AACd,cAAM,IAAI,MAAM,0BAA0B;AAAA,MAC5C;AAEA,UAAI;AACJ,UAAI;AACF,iBAAS,MAAM,UAAU,KAAK,OAAO;AAAA,MACvC,SAAS,cAAc;AAIrB,YAAI,YAAY,GAAG,YAAY,EAAG,OAAM;AACxC,cAAM;AAAA,UACJ;AAAA,YACE;AAAA,YACA,wBAAwB,QAAQ,aAAa,UAAU,OAAO,YAAY;AAAA,YAC1E,EAAE,YAAY,QAAQ,OAAO;AAAA,UAC/B;AAAA,QACF;AAAA,MACF;AAEA,UAAI,OAAO,SAAS;AAElB,eAAO,aAAa,OAAO,IAAI;AAAA,MACjC;AAIA,YAAM;AAAA,QACJ,OAAO,aACL,mBAAmB,WAAW,OAAO,SAAS,sBAAsB;AAAA,UAClE,YAAY,QAAQ;AAAA,QACtB,CAAC;AAAA,MACL;AAAA,IACF;AAAA,EACF;AACF;AAMA,SAAS,UAAU,UAA2D;AAC5E,QAAM,QAAQ,aAAa,QAAQ;AAClC,EAAC,MACC,oBAAoB,OAAO,SAAS;AACvC,SAAO;AACT;;;AEvDO,SAAS,mBAAqC,UAAqB;AACxE,QAAM,QAAQ,CAAC,SACb,IAAI,MAAM,MAAM;AAAA,IACd,IAAI,SAAS,MAAM;AAIjB,UAAI,OAAO,SAAS,YAAY,SAAS,OAAQ,QAAO;AACxD,aAAO,MAAM,GAAG,IAAI,IAAI,IAAI,EAAE;AAAA,IAChC;AAAA,IACA,MAAM,SAAS,UAAU,UAAqB;AAC5C,YAAM,UAAU;AAAA,QACd,QAAQ;AAAA;AAAA,QAER,MAAM,SAAS,IAAI,CAAC,QAAQ,WAAW,GAAG,CAAC;AAAA,MAC7C;AACA,aAAO,WAAW,EAAE,KAAK,OAAO;AAAA,IAClC;AAAA,EACF,CAAC;AAEH,SAAO,MAAM,QAAQ;AACvB;AAGA,IAAM,OAAO,MAAY;AAAC;;;AH7CnB,IAAM,kBAAN,MAAM,yBAAwB,UAAU;AAAA,EAiBrC,cAAc;AACpB,UAAM;AACN,SAAK,OAAO,mBAAkC,MAAM;AACpD,SAAK,SAAS,mBAAoC,QAAQ;AAC1D,SAAK,SAAS,mBAAoC,QAAQ;AAC1D,SAAK,UAAU,mBAAqC,SAAS;AAC7D,SAAK,eACH,mBAA0C,cAAc;AAC1D,SAAK,WAAW,mBAAsC,UAAU;AAChE,SAAK,YAAY,mBAAuC,WAAW;AAAA,EACrE;AAAA,EAEA,OAAO,cAA+B;AACpC,QAAI,CAAC,iBAAgB,UAAU;AAC7B,uBAAgB,WAAW,IAAI,iBAAgB;AAAA,IACjD;AACA,WAAO,iBAAgB;AAAA,EACzB;AACF;;;AI/CA,YAAYC,cAAa;AAoClB,IAAe,eAAf,MAA4B;AAAA,EAIjC,cAAc;AACZ,SAAK,UAAkB;AAAA,MACrB;AAAA,IACF;AAAA,EACF;AAAA,EAEU,SAAS,QAAgB,SAAwB;AACzD;AAAC,IAAC,KAAK,QAAgC,GAAG,SAAS,EAAE,QAAQ,QAAQ,CAAC;AAAA,EACxE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASU,OACR,SACA,OAAqC,QAC/B;AACN;AAAC,IAAC,KAAK,QAAgC,GAAG,iBAAiB,SAAS,IAAI;AAAA,EAC1E;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOU,WAAiB;AACzB;AAAC,IAAC,KAAK,QAAgC,UAAU,SAAS;AAAA,EAC5D;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAwBU,UACR,OACA,UACM;AACN;AAAC,IAAC,KAAK,QAAgC,OAAO;AAAA,MAC5C;AAAA,MACQ,eAAM,QAAQ;AAAA,IACxB;AAAA,EACF;AAAA,EAEA,MAAM,OAAsB;AAC1B,YAAQ,IAAI,KAAK,UAAU,eAAe;AAC1C,YAAQ,IAAI,KAAK,UAAU,yBAAyB;AAAA,EACtD;AAAA,EAEA,MAAM,UAAyB;AAC7B,YAAQ,IAAI,KAAK,UAAU,qCAAgC;AAAA,EAC7D;AAAA,EAEA,MAAM,OAAwB;AAC5B,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,YAAY,UAAoC;AAAA,EAEtD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,QAAc;AACZ,IAAQ;AAAA,MACN;AAAA,QACE,MAAM,CAAC,WAAyB;AAC9B,eAAK,WAAW,OAAO;AACvB,iBAAO,KAAK,KAAK;AAAA,QACnB;AAAA,QACA,SAAS,MAAM,KAAK,QAAQ;AAAA,QAC5B,MAAM,MAAM,KAAK,KAAK;AAAA,QACtB,aAAa,CAAC,YAAuB,KAAK,YAAY,OAAO;AAAA,MAC/D;AAAA,MACA;AAAA,IACF;AACA,YAAQ,IAAI,wCAAwC;AAAA,EACtD;AACF;;;ACjIO,IAAM,gBAAgB;AAAA,EAC3B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;;;ACPA;AAAA,EACE,eAAAC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,gBAAAC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAaA,IAAM,YAAY,gBAAgB,YAAY;","names":["out","Comlink","PluginError","fromEnvelope"]}

package/dist/plugin-worker.d.ts

@@ -0,0 +1,86 @@
+import type { PluginEventName } from "./events";
+export interface UIMessage {
+    action: string;
+    payload: unknown;
+}
+/**
+ * Base class for Snaptrude plugin workers.
+ *
+ * Handles Comlink wiring, host communication, and the standard lifecycle
+ * methods (`init`, `destroy`, `ping`, `onUIMessage`). Subclass this and
+ * override only the methods you need — then call `start()` to expose the
+ * worker API.
+ *
+ * The plugin ID is received automatically from the host during
+ * initialization — no need to pass it manually.
+ *
+ * @example
+ * ```ts
+ * import { PluginWorker } from "@snaptrude/plugin-client";
+ *
+ * class MyPlugin extends PluginWorker {
+ *   async onUIMessage(message: UIMessage) {
+ *     // handle messages from the UI panel
+ *   }
+ * }
+ *
+ * new MyPlugin().start();
+ * ```
+ */
+export declare abstract class PluginWorker {
+    protected pluginId: string;
+    private hostAPI;
+    constructor();
+    protected sendToUI(action: string, payload: unknown): void;
+    /**
+     * Show a transient notification toast in the Snaptrude editor.
+     *
+     * @param message - Text to display.
+     * @param type - Severity; `"error"`/`"warning"` linger a little longer than
+     *   `"info"`. Defaults to `"info"`.
+     */
+    protected notify(message: string, type?: "info" | "warning" | "error"): void;
+    /**
+     * Signal the host that this plugin has finished its work and should be
+     * stopped. Use this in headless (UI-less) plugins that run a task and
+     * self-terminate.
+     */
+    protected complete(): void;
+    /**
+     * Subscribe to a host event (e.g. `"model:changed"`, fired debounced on any
+     * user- or plugin-initiated model edit). The callback runs in this worker
+     * each time the event fires; its argument is a small structured-clone-safe
+     * payload (see the event's payload type, e.g. `ModelChangedEvent`).
+     *
+     * Fire-and-forget: subscribe once (typically in `init()`). Subscriptions live
+     * for the plugin's lifetime and are cleared automatically when the plugin is
+     * stopped — there is no `unsubscribe` yet.
+     *
+     * @example
+     * ```ts
+     * import type { ModelChangedEvent } from "@snaptrude/plugin-client";
+     *
+     * async init() {
+     *   this.subscribe("model:changed", (e) => {
+     *     const { source } = e as ModelChangedEvent;
+     *     console.log("model changed via", source);
+     *   });
+     * }
+     * ```
+     */
+    protected subscribe(event: PluginEventName, callback: (payload?: unknown) => void): void;
+    init(): Promise<void>;
+    destroy(): Promise<void>;
+    ping(): Promise<string>;
+    onUIMessage(_message: UIMessage): Promise<void>;
+    /**
+     * Expose the worker API via Comlink and start listening.
+     * Call this once after constructing the plugin instance.
+     *
+     * The host calls `init(config)` with `{ pluginId }`,
+     * which is captured here to set `this.pluginId` before the
+     * subclass's `init()` runs.
+     */
+    start(): void;
+}
+//# sourceMappingURL=plugin-worker.d.ts.map

package/dist/plugin-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-worker.d.ts","sourceRoot":"","sources":["../src/plugin-worker.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAE/C,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,OAAO,CAAA;CACjB;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,8BAAsB,YAAY;IAChC,SAAS,CAAC,QAAQ,EAAG,MAAM,CAAA;IAC3B,OAAO,CAAC,OAAO,CAAyC;;IAQxD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAI1D;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,CACd,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAAM,GAAG,SAAS,GAAG,OAAgB,GAC1C,IAAI;IAIP;;;;OAIG;IACH,SAAS,CAAC,QAAQ,IAAI,IAAI;IAI1B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAS,CAAC,SAAS,CACjB,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,GACpC,IAAI;IAOD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAKrB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAIvB,WAAW,CAAC,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrD;;;;;;;OAOG;IACH,KAAK,IAAI,IAAI;CAed"}

package/dist/rpc-proxy.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Build a namespace object whose nested property access maps to a
+ * dot-separated host RPC method path, and whose every call dispatches that
+ * path through the host bridge.
+ *
+ * The host exposes the entire plugin API behind a single generic `call()`
+ * (see the host `bridge.ts`), and the method string is exactly the property
+ * path — so one Proxy replaces every hand-written per-method RPC wrapper for
+ * every namespace (`core.*`, `design.*`, `entity.*`):
+ *
+ * The POSITIONAL transport forwards the whole argument tuple; the host router
+ * spreads it back into the resolved method (`fn(...args)`):
+ *
+ * ```ts
+ * snaptrude.core.math.vec3.new(1, 2, 3)
+ *   // → getHostApi().call({ method: "core.math.vec3.new", args: [1, 2, 3] })
+ * ```
+ *
+ * Typed at the call site, e.g. `createRpcNamespace<PluginEntityApi>("entity")`.
+ * The Proxy is structurally cast to the abstract API type — argument and
+ * return types are enforced by that type, while dispatch is dynamic.
+ *
+ * Every namespace uses this — including `core.math.*` and `core.geom.*`: under
+ * the all-handle model there is no in-worker compute; math and geometry are
+ * host calls like everything else.
+ */
+export declare function createRpcNamespace<T extends object>(basePath: string): T;
+//# sourceMappingURL=rpc-proxy.d.ts.map

package/dist/rpc-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-proxy.d.ts","sourceRoot":"","sources":["../src/rpc-proxy.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,CAqBxE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-client",
-  "version": "0.9.14",
+  "version": "0.9.15",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -23,7 +23,7 @@
   ],
   "dependencies": {
     "comlink": "^4.4.2",
-    "@snaptrude/plugin-core": "0.9.14"
+    "@snaptrude/plugin-core": "0.9.15"
   },
   "devDependencies": {
     "tsup": "^8.5.1",