@snaptrude/plugin-client 0.0.0-dev-20260708130115

package/AGENTS.md

@@ -0,0 +1,86 @@
+# Plugin Client — Agent Guide
+
+This package implements the plugin-core API for the **worker side** (plugin runtime).
+Plugins import `snaptrude` from this package to interact with the Snaptrude host.
+
+## Relationship to plugin-core
+
+> Source of truth: [`packages/plugin-core/AGENTS.md`](../plugin-core/AGENTS.md)
+
+This package implements the API surface defined in `@snaptrude/plugin-core`. Only the
+root `PluginApi` class is extended; every namespace under it is satisfied structurally
+by a generic RPC proxy (see below). When plugin-core changes its top-level shape,
+this package must be updated to match.
+
+## What this package contains
+
+- `src/api/index.ts` — `ClientPluginApi`: wires one generic RPC proxy per top-level namespace
+- `src/rpc-proxy.ts` — `createRpcNamespace()`: Proxy mapping dotted property paths to host RPC calls
+- `src/host-api.ts` — Comlink RPC wrapper (`HostApi.call()`); unwraps success/error results
+- `src/plugin-worker.ts` — `PluginWorker` base class (lifecycle, UI messaging, Comlink exposure)
+- `src/index.ts` — Exports the `snaptrude` singleton (`ClientPluginApi` instance)
+
+## Quick commands
+
+```bash
+pnpm check-types   # typecheck (no emit)
+pnpm build          # tsup build (ESM + CJS)
+pnpm dev            # tsup watch mode
+```
+
+## Implementation patterns
+
+### Everything is a generic RPC proxy (async, remote)
+
+Under the all-handle model there is no in-worker compute: `core.math.*` and
+`core.geom.*` values are opaque handles, so **every** namespace — `core.*`
+(including `core.units`), `design.*`, `entity.*`, `tools.*` — is a
+`createRpcNamespace<PluginXApi>("x")` Proxy. There are no hand-written
+per-method wrappers. Nested property access builds the dot-separated method
+path; the call marshals `{ method, args }` to the host via Comlink
+(`getHostApi().call()`):
+
+```typescript
+// src/api/index.ts — one proxy per top-level namespace
+this.core = createRpcNamespace<PluginCoreApi>("core")
+
+// Plugin code — positional args (whole tuple crosses the wire), values are handles:
+const v = await snaptrude.core.math.vec3.new(1, 2, 3)
+await snaptrude.entity.space.createRectangular(position, dimensions)
+//   → getHostApi().call({ method: "entity.space.createRectangular", args: [position, dimensions] })
+```
+
+The proxy is structurally cast to the abstract API type, so argument and return
+types are enforced by plugin-core while dispatch stays dynamic. The `method`
+string is exactly the property path and must match `PluginApiMethod`
+(auto-inferred from the class hierarchy in `plugin-core/src/host-utils.ts`).
+
+## When to update this package
+
+- **plugin-core adds/removes/changes a method**: Usually nothing to do here — the
+  proxy dispatches dynamically and types flow from plugin-core. Rebuild plugin-core,
+  then run `pnpm check-types` here.
+- **plugin-core adds a new top-level namespace on `PluginApi`**: Add a matching
+  `createRpcNamespace<PluginNewApi>("new")` property in `ClientPluginApi`
+  (`src/api/index.ts`). Nested modules under an existing namespace need no wiring.
+
+After making changes, always run `pnpm check-types` to verify everything compiles.
+
+## File mapping (plugin-core -> plugin-client)
+
+There are no per-namespace files here anymore — the whole plugin-core API tree is
+served by two files:
+
+| plugin-core                                   | plugin-client                                                        |
+| --------------------------------------------- | -------------------------------------------------------------------- |
+| `src/api/**` (all namespaces, e.g. `core.math.vec3`) | `src/api/index.ts` (`ClientPluginApi`, one `createRpcNamespace` each) |
+| `src/host-utils.ts` (`PluginApiMethod` types) | `src/rpc-proxy.ts` + `src/host-api.ts` (dispatch + Comlink transport) |
+
+## Downstream consumers
+
+Changes to this package's **public exports** affect:
+
+- Internal plugins under `plugins/`
+- Example plugins under `examples/`
+
+If you change or remove an export, search these directories for usage.

package/CHANGELOG.md

@@ -0,0 +1,106 @@
+# @snaptrude/plugin-client
+
+## 0.0.0-dev-20260708130115
+
+### Patch Changes
+
+- Updated dependencies [8f22cb7]
+  - @snaptrude/plugin-core@0.0.0-dev-20260708130115
+
+## 0.5.0
+
+### Minor Changes
+
+- 7750aa3: Exposed more snaptrude APIs
+
+### Patch Changes
+
+- Updated dependencies [7750aa3]
+  - @snaptrude/plugin-core@0.5.0
+
+## 0.2.9
+
+### Patch Changes
+
+- 94842d0: added new space areaClass and innerProfiles APIs
+- Updated dependencies [94842d0]
+- Updated dependencies [ddf05fa]
+  - @snaptrude/plugin-core@0.2.9
+
+## 0.2.8
+
+### Patch Changes
+
+- 445e0b8: Add Present-mode AI Inspiration plugin APIs under `snaptrude.documentation.aiInspiration`.
+- Updated dependencies [445e0b8]
+  - @snaptrude/plugin-core@0.2.8
+
+## 0.2.7
+
+### Patch Changes
+
+- c5afd9a: added adjacecny
+- Updated dependencies [c5afd9a]
+  - @snaptrude/plugin-core@0.2.7
+
+## 0.2.6
+
+### Patch Changes
+
+- c17d287: Add bulk space APIs: `space.bulkCreate`, `space.bulkUpdate`, and `space.bulkDelete`. Each batches its work into a single undo/redo step. All items are validated up front and the call throws if any item is invalid (nothing is applied), consistent with the single-item space methods. `bulkCreate` supports `spaceType`/`massType`/`departmentId` per item and returns `{ spaceIds }`; `bulkUpdate` takes geometry (`profile`+`extrudeHeight`) and/or nested `properties` per item and returns `{ spaces }` (one echoed result per item, like `update`); `bulkDelete` returns `{ deletedSpaceIds }`.
+- 0683194: bulk apis
+- Updated dependencies [c17d287]
+- Updated dependencies [0683194]
+  - @snaptrude/plugin-core@0.2.6
+
+## 0.2.5
+
+### Patch Changes
+
+- Restore declaration files in published plugin packages.
+- Updated dependencies
+  - @snaptrude/plugin-core@0.2.5
+
+## 0.2.4
+
+### Patch Changes
+
+- Add inner profile hole support to space creation from profiles.
+
+- Updated dependencies
+  - @snaptrude/plugin-core@0.2.4
+
+## 0.2.3
+
+### Patch Changes
+
+- 647466b: fixed merge issues
+- Updated dependencies [647466b]
+  - @snaptrude/plugin-core@0.2.3
+
+## 0.2.2
+
+### Patch Changes
+
+- 064777a: buildable envelope apis
+- Updated dependencies [064777a]
+  - @snaptrude/plugin-core@0.2.2
+
+## 0.2.1
+
+### Patch Changes
+
+- 3b37f4a: added buildable envelop api
+- Updated dependencies [3b37f4a]
+  - @snaptrude/plugin-core@0.2.1
+
+## 0.2.0
+
+### Minor Changes
+
+- 4d959a4: Exposed new offset and copy APIs for tools
+
+### Patch Changes
+
+- Updated dependencies [4d959a4]
+  - @snaptrude/plugin-core@0.2.0

package/CLAUDE.md

@@ -0,0 +1,11 @@
+# CLAUDE.md
+
+> **All coding standards, checks, and guidance live in [`AGENTS.md`](AGENTS.md).**
+> `CLAUDE.md` is a pointer only — add all new rules, patterns, and instructions to `AGENTS.md`.
+
+See [AGENTS.md](AGENTS.md) for:
+
+- Implementation pattern (generic RPC proxy — every namespace is async host RPC)
+- File mapping from plugin-core to plugin-client
+- When and how to update this package in response to plugin-core changes
+- Downstream consumer notes

package/dist/api/index.d.ts

@@ -0,0 +1,18 @@
+import { PluginApi, PluginCoreApi, PluginDesignApi, PluginEntityApi, PluginProgramApi, PluginPresentationApi } 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;
+    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,EACtB,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;IAE1C,OAAO;IAUP,MAAM,CAAC,WAAW,IAAI,eAAe;CAMtC"}

package/dist/host-api.d.ts

@@ -0,0 +1,11 @@
+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;
+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;AAE/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,wBAAgB,UAAU,IAAI,cAAc,CAkB3C"}

package/dist/index.cjs

@@ -0,0 +1,178 @@
+"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, {
+  ClientPluginApi: () => ClientPluginApi,
+  PluginWorker: () => PluginWorker,
+  createHostApi: () => createHostApi,
+  getHostApi: () => getHostApi,
+  snaptrude: () => snaptrude
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/api/index.ts
+var import_plugin_core = require("@snaptrude/plugin-core");
+
+// src/host-api.ts
+var Comlink = __toESM(require("comlink"), 1);
+function createHostApi(endpoint) {
+  return Comlink.wrap(
+    endpoint ?? globalThis
+  );
+}
+var _instance = null;
+function getHostApi() {
+  if (!_instance) {
+    _instance = createHostApi();
+  }
+  return {
+    call: async (payload) => {
+      if (!_instance) {
+        throw new Error("Host API not initialized");
+      }
+      return _instance.call(payload).then((result) => {
+        if (result.success) {
+          return result.data;
+        } else {
+          throw new Error(result.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,
+        args: argArray
+      };
+      return getHostApi().call(payload);
+    }
+  });
+  return build(basePath);
+}
+var NOOP = () => {
+};
+
+// src/api/index.ts
+var ClientPluginApi = class _ClientPluginApi extends import_plugin_core.PluginApi {
+  constructor() {
+    super();
+    this.core = createRpcNamespace("core");
+    this.design = createRpcNamespace("design");
+    this.entity = createRpcNamespace("entity");
+    this.program = createRpcNamespace("program");
+    this.presentation = createRpcNamespace("presentation");
+  }
+  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 });
+  }
+  /**
+   * 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();
+  }
+  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/index.ts
+var snaptrude = ClientPluginApi.getInstance();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ClientPluginApi,
+  PluginWorker,
+  createHostApi,
+  getHostApi,
+  snaptrude
+});
+//# 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/rpc-proxy.ts","../src/plugin-worker.ts"],"sourcesContent":["import { ClientPluginApi } from \"./api\"\n\nexport * from \"./api\"\nexport * from \"./host-api\"\nexport * from \"./plugin-worker\"\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} 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\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  }\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\"\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\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      return _instance.call(payload).then(result => {\n        if (result.success) {\n          return result.data\n        } else {\n          throw new Error(result.error)\n        }\n      })\n    }\n  }\n}\n","import type {\n  PluginApiCallPayload,\n  PluginApiMethod,\n} from \"@snaptrude/plugin-core\"\nimport { getHostApi } from \"./host-api\"\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          args: argArray,\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\"\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   * 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  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"],"mappings":"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","names":["Comlink"]}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { ClientPluginApi } from "./api";
+export * from "./api";
+export * from "./host-api";
+export * from "./plugin-worker";
+/**
+ * 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;AAE/B;;;;GAIG;AACH,eAAO,MAAM,SAAS,iBAAgC,CAAA"}

package/dist/index.js

@@ -0,0 +1,139 @@
+// src/api/index.ts
+import {
+  PluginApi
+} from "@snaptrude/plugin-core";
+
+// src/host-api.ts
+import * as Comlink from "comlink";
+function createHostApi(endpoint) {
+  return Comlink.wrap(
+    endpoint ?? globalThis
+  );
+}
+var _instance = null;
+function getHostApi() {
+  if (!_instance) {
+    _instance = createHostApi();
+  }
+  return {
+    call: async (payload) => {
+      if (!_instance) {
+        throw new Error("Host API not initialized");
+      }
+      return _instance.call(payload).then((result) => {
+        if (result.success) {
+          return result.data;
+        } else {
+          throw new Error(result.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,
+        args: argArray
+      };
+      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");
+  }
+  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 });
+  }
+  /**
+   * 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();
+  }
+  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/index.ts
+var snaptrude = ClientPluginApi.getInstance();
+export {
+  ClientPluginApi,
+  PluginWorker,
+  createHostApi,
+  getHostApi,
+  snaptrude
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/api/index.ts","../src/host-api.ts","../src/rpc-proxy.ts","../src/plugin-worker.ts","../src/index.ts"],"sourcesContent":["import {\n  PluginApi,\n  PluginCoreApi,\n  PluginDesignApi,\n  PluginEntityApi,\n  PluginProgramApi,\n  PluginPresentationApi,\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\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  }\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\"\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\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      return _instance.call(payload).then(result => {\n        if (result.success) {\n          return result.data\n        } else {\n          throw new Error(result.error)\n        }\n      })\n    }\n  }\n}\n","import type {\n  PluginApiCallPayload,\n  PluginApiMethod,\n} from \"@snaptrude/plugin-core\"\nimport { getHostApi } from \"./host-api\"\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          args: argArray,\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\"\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   * 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  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","import { ClientPluginApi } from \"./api\"\n\nexport * from \"./api\"\nexport * from \"./host-api\"\nexport * from \"./plugin-worker\"\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":"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","names":["Comlink"]}

package/dist/plugin-worker.d.ts

@@ -0,0 +1,54 @@
+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;
+    /**
+     * 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;
+    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":"AAEA,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;;;;OAIG;IACH,SAAS,CAAC,QAAQ,IAAI,IAAI;IAIpB,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":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,CAoBxE"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@snaptrude/plugin-client",
+  "version": "0.0.0-dev-20260708130115",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "comlink": "^4.4.2",
+    "@snaptrude/plugin-core": "0.0.0-dev-20260708130115"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.5.4"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit",
+    "build": "tsup --clean",
+    "dev": "tsup --watch",
+    "clean-dist": "rm -rf dist"
+  }
+}

package/src/api/index.ts

@@ -0,0 +1,42 @@
+import {
+  PluginApi,
+  PluginCoreApi,
+  PluginDesignApi,
+  PluginEntityApi,
+  PluginProgramApi,
+  PluginPresentationApi,
+} from "@snaptrude/plugin-core"
+import { createRpcNamespace } from "../rpc-proxy"
+
+export class ClientPluginApi extends PluginApi {
+  private static instance: ClientPluginApi
+
+  /**
+   * 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.
+   */
+  public core: PluginCoreApi
+  public design: PluginDesignApi
+  public entity: PluginEntityApi
+  public program: PluginProgramApi
+  public presentation: PluginPresentationApi
+
+  private constructor() {
+    super()
+    this.core = createRpcNamespace<PluginCoreApi>("core")
+    this.design = createRpcNamespace<PluginDesignApi>("design")
+    this.entity = createRpcNamespace<PluginEntityApi>("entity")
+    this.program = createRpcNamespace<PluginProgramApi>("program")
+    this.presentation =
+      createRpcNamespace<PluginPresentationApi>("presentation")
+  }
+
+  static getInstance(): ClientPluginApi {
+    if (!ClientPluginApi.instance) {
+      ClientPluginApi.instance = new ClientPluginApi()
+    }
+    return ClientPluginApi.instance
+  }
+}

package/src/host-api.ts

@@ -0,0 +1,47 @@
+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 function createHostApi(endpoint?: Comlink.Endpoint): HostApi {
+  return Comlink.wrap<HostApi>(
+    endpoint ?? (globalThis as unknown as Comlink.Endpoint)
+  ) as unknown as HostApi
+}
+
+let _instance: HostApi | null = null
+
+export function getHostApi(): HostApiWrapped {
+  if (!_instance) {
+    _instance = createHostApi()
+  }
+  return {
+    call: async <M extends PluginApiMethod>(payload: PluginApiCallPayload<M>): Promise<PluginApiCallResult<M>> => {
+      if (!_instance) {
+        throw new Error("Host API not initialized")
+      }
+      return _instance.call(payload).then(result => {
+        if (result.success) {
+          return result.data
+        } else {
+          throw new Error(result.error)
+        }
+      })
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+import { ClientPluginApi } from "./api"
+
+export * from "./api"
+export * from "./host-api"
+export * from "./plugin-worker"
+
+/**
+ * The Snaptrude plugin client API.
+ *
+ * The main entry point for plugins to interact with the Snaptrude platform.
+ */
+export const snaptrude = ClientPluginApi.getInstance()

package/src/plugin-worker.ts

@@ -0,0 +1,99 @@
+import * as Comlink from "comlink"
+
+export interface UIMessage {
+  action: string
+  payload: unknown
+}
+
+interface PluginConfig {
+  pluginId: string
+}
+
+/**
+ * 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 abstract class PluginWorker {
+  protected pluginId!: string
+  private hostAPI: Comlink.Remote<Record<string, unknown>>
+
+  constructor() {
+    this.hostAPI = Comlink.wrap<Record<string, unknown>>(
+      self as unknown as Comlink.Endpoint
+    )
+  }
+
+  protected sendToUI(action: string, payload: unknown): void {
+    ;(this.hostAPI as Record<string, any>).ui.sendToUI({ action, payload })
+  }
+
+  /**
+   * 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 {
+    ;(this.hostAPI as Record<string, any>).lifecycle.complete()
+  }
+
+  async init(): Promise<void> {
+    console.log(this.pluginId, "init() called")
+    console.log(this.pluginId, "Initialization complete")
+  }
+
+  async destroy(): Promise<void> {
+    console.log(this.pluginId, "destroy() called — cleaning up")
+  }
+
+  async ping(): Promise<string> {
+    return "pong"
+  }
+
+  async onUIMessage(_message: UIMessage): Promise<void> {
+    // Override in subclass to handle UI messages
+  }
+
+  /**
+   * 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 {
+    Comlink.expose(
+      {
+        init: (config: PluginConfig) => {
+          this.pluginId = config.pluginId
+          return this.init()
+        },
+        destroy: () => this.destroy(),
+        ping: () => this.ping(),
+        onUIMessage: (message: UIMessage) => this.onUIMessage(message),
+      },
+      self as unknown as Comlink.Endpoint
+    )
+    console.log("Worker loaded, API exposed via Comlink")
+  }
+}

package/src/rpc-proxy.ts

@@ -0,0 +1,56 @@
+import type {
+  PluginApiCallPayload,
+  PluginApiMethod,
+} from "@snaptrude/plugin-core"
+import { getHostApi } from "./host-api"
+
+/**
+ * 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 function createRpcNamespace<T extends object>(basePath: string): T {
+  const build = (path: string): unknown =>
+    new Proxy(NOOP, {
+      get(_target, prop) {
+        // Symbols and `then` must not resolve to a callable proxy, otherwise
+        // the namespace would look thenable and break Promise resolution if it
+        // ever reached an `await`.
+        if (typeof prop !== "string" || prop === "then") return undefined
+        return build(`${path}.${prop}`)
+      },
+      apply(_target, _thisArg, argArray: unknown[]) {
+        const payload = {
+          method: path,
+          args: argArray,
+        } as unknown as PluginApiCallPayload<PluginApiMethod>
+        return getHostApi().call(payload)
+      },
+    })
+
+  return build(basePath) as T
+}
+
+/** Proxy target must be callable for the `apply` trap; identity is irrelevant. */
+const NOOP = (): void => {}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "moduleResolution": "bundler",
+    "lib": ["ES2020", "WebWorker"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "emitDeclarationOnly": true,
+    "typeRoots": [],
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"]
+}

package/tsup.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "tsup"
+
+export default defineConfig( (options) => {
+  return {
+    entry: ["src/index.ts"],
+    format: ["cjs", "esm"],
+    dts: false,
+    sourcemap: true,
+    onSuccess: "tsc", // Run tsc to generate d.ts and d.ts.map
+    watch: options.watch,
+  }
+})