@snaptrude/plugin-client 0.6.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @snaptrude/plugin-client
 
+## 0.7.1
+
+### Patch Changes
+
+- 8f22cb7: Expand `presentation.aiInspiration` to the full AI Inspiration surface (18 methods) and make it a required member of `PluginPresentationApi` now that the host implementation lands.
+  - New methods: `getModelCapabilities`, `getSelection`, `getPresetCatalog`, `getJob`, `cancelJob`, `listJobs`, `getWorkflowForShape`, `getSelectedBranchRerunPlan`, `rerunSelectedBranch`, `extractRecipeFromShape`, `listRecipes`, `saveRecipe`, `deleteRecipe`, `runRecipe` (plus job/workflow/recipe Zod schemas).
+  - `generate`/`refine` (and `rerunSelectedBranch`/`runRecipe`) accept `runMode: "blocking" | "job"`; `PluginAIInspirationRunResult` is accordingly loosened to `{ jobId?, output?, outputs?, metadata? }` — job-mode calls resolve with a `jobId` instead of outputs.
+
+- Updated dependencies [8f22cb7]
+  - @snaptrude/plugin-core@0.7.1
+
+## 0.7.0
+
+### Minor Changes
+
+- e1915e4: Plugin API 0.7.0 — new families and methods (supersedes the cancelled `design.update.setLabel` 0.6.1 patch, now folded in).
+  - **`core.proposals.*`** — design options as infrastructure: `list` / `get` / `getActive` / `listForComponent` / `isActive` (reads) plus `create` / `rename` / `setActive` / `delete` (non-undoable writes).
+  - **`program.layout.*`** — the space-solver promoted to a real async-job family: `arrange` / `pack` now start a backend job and return immediately, with `getState` (poll) and `cancel`.
+  - **Door & window catalogs + placement** — `design.doors.*` / `design.windows.*` gain `listCatalogGroups` / `listCatalog` / `getCatalogItem` / `exists` (shared catalog DTOs), and `design.create.door` / `design.create.window` place a catalog item into a host wall.
+  - **`design.create.smartLayout`** — clone an in-scene template cluster into one or more target spaces in a single undo batch.
+  - **Furniture categories** — `design.furniture.listCategories` plus a `category` filter on `listCatalog`, and `thumbnailUrl` on catalog items.
+  - **`design.transform.align`** — snap components' bounding-box edges (left/right/center/top/bottom/middle), optionally to a reference.
+  - **Per-face materials** — `design.materials.applyToFaces` / `resetFaces` / `getByFace` / `listByFace` (BREP faces by durable index, visual-only).
+  - **Staircase params** — `design.query.getStaircaseParams` (read) and `design.update.staircase` (sparse parametric write).
+  - **Footprint-area lock** — `design.lockArea` / `unlockArea` / `isAreaLocked` / `listAreaLocked` for Room/Department spaces.
+  - **`entity.story.duplicate`** — duplicate a storey (or a subset) up/down, auto-creating the target storey.
+  - **`presentation.import.svg`** — import a guaranteed-vector SVG onto the Present sheet.
+  - **View display settings** — `presentation.views.getSettings` / `updateSettings` (background, color mode, axis, edges, labels).
+  - **`design.update.setLabel`** — set any component's panel Label (write pair of `design.query.getLabel`); undoable, lock-aware, validated.
+  - **`program.areas`** — area members now report their `areaClass` (`NET` / `GROSS` / `EXCLUDED`), with net/gross documented as the plain-English synonyms for carpet/built-up.
+  - **Typed plugin API errors** — every host failure now crosses the wire as a structured envelope instead of a flattened `Execution error: <msg>` string: a stable `code` from the shared plugin-core error registry, the offending handle, an authored `hint`, and `retryAfterMs` / `didYouMean` enrichment where applicable. Zod validation failures forward the first 10 issues, each projected to `{path, code, message}` (full count in `details.issueCount`); internal faults are sanitized and host-logged under an `errorId`. Every handler across the API surface now throws typed codes, each doc page gained an Errors section, and a drift test pins thrown code literals to the registry.
+
+### Patch Changes
+
+- Updated dependencies [e1915e4]
+  - @snaptrude/plugin-core@0.7.0
+
 ## 0.6.0
 
 ### Minor Changes

package/dist/host-api.d.ts

@@ -7,5 +7,7 @@ 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

@@ -1 +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"}
+{"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;AAG/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,CAyC3C"}

package/dist/index.cjs

@@ -30,25 +30,46 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CODE_META: () => import_plugin_core3.CODE_META,
   ClientPluginApi: () => ClientPluginApi,
+  PLUGIN_ERROR_CODES: () => import_plugin_core3.PLUGIN_ERROR_CODES,
+  PluginError: () => import_plugin_core3.PluginError,
+  PluginExecutionError: () => import_plugin_core3.PluginExecutionError,
+  PluginHandleError: () => import_plugin_core3.PluginHandleError,
+  PluginInternalError: () => import_plugin_core3.PluginInternalError,
+  PluginLifecycleError: () => import_plugin_core3.PluginLifecycleError,
+  PluginNotFoundError: () => import_plugin_core3.PluginNotFoundError,
+  PluginPermissionError: () => import_plugin_core3.PluginPermissionError,
+  PluginQuotaError: () => import_plugin_core3.PluginQuotaError,
+  PluginTimeoutError: () => import_plugin_core3.PluginTimeoutError,
+  PluginTransportError: () => import_plugin_core3.PluginTransportError,
+  PluginValidationError: () => import_plugin_core3.PluginValidationError,
   PluginWorker: () => PluginWorker,
+  __setHostApiInstance: () => __setHostApiInstance,
   createHostApi: () => createHostApi,
+  fromEnvelope: () => import_plugin_core3.fromEnvelope,
   getHostApi: () => getHostApi,
+  isErrorEnvelope: () => import_plugin_core3.isErrorEnvelope,
+  isPluginErrorCode: () => import_plugin_core3.isPluginErrorCode,
   snaptrude: () => snaptrude
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/api/index.ts
-var import_plugin_core = require("@snaptrude/plugin-core");
+var import_plugin_core2 = require("@snaptrude/plugin-core");
 
 // src/host-api.ts
 var Comlink = __toESM(require("comlink"), 1);
+var import_plugin_core = require("@snaptrude/plugin-core");
 function createHostApi(endpoint) {
   return Comlink.wrap(
     endpoint ?? globalThis
   );
 }
 var _instance = null;
+function __setHostApiInstance(instance) {
+  _instance = instance ?? null;
+}
 function getHostApi() {
   if (!_instance) {
     _instance = createHostApi();
@@ -58,16 +79,35 @@ function getHostApi() {
       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);
-        }
-      });
+      let result;
+      try {
+        result = await _instance.call(payload);
+      } catch (transportErr) {
+        if (import_plugin_core.PluginError.is(transportErr)) throw transportErr;
+        throw rehydrate(
+          (0, import_plugin_core.makeClientEnvelope)(
+            "TRANSPORT_LOST",
+            transportErr instanceof Error ? transportErr.message : String(transportErr),
+            { methodPath: payload.method }
+          )
+        );
+      }
+      if (result.success) {
+        return result.data;
+      }
+      throw rehydrate(
+        result.errorInfo ?? (0, import_plugin_core.makeClientEnvelope)("UNKNOWN", result.error ?? "Unknown host error", {
+          methodPath: payload.method
+        })
+      );
     }
   };
 }
+function rehydrate(envelope) {
+  const error = (0, import_plugin_core.fromEnvelope)(envelope);
+  Error.captureStackTrace?.(error, rehydrate);
+  return error;
+}
 
 // src/rpc-proxy.ts
 function createRpcNamespace(basePath) {
@@ -90,7 +130,7 @@ var NOOP = () => {
 };
 
 // src/api/index.ts
-var ClientPluginApi = class _ClientPluginApi extends import_plugin_core.PluginApi {
+var ClientPluginApi = class _ClientPluginApi extends import_plugin_core2.PluginApi {
   constructor() {
     super();
     this.core = createRpcNamespace("core");
@@ -167,13 +207,31 @@ var PluginWorker = class {
 };
 
 // src/index.ts
+var import_plugin_core3 = 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,
+  PluginError,
+  PluginExecutionError,
+  PluginHandleError,
+  PluginInternalError,
+  PluginLifecycleError,
+  PluginNotFoundError,
+  PluginPermissionError,
+  PluginQuotaError,
+  PluginTimeoutError,
+  PluginTransportError,
+  PluginValidationError,
   PluginWorker,
+  __setHostApiInstance,
   createHostApi,
+  fromEnvelope,
   getHostApi,
+  isErrorEnvelope,
+  isPluginErrorCode,
   snaptrude
 });
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +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  PluginAnalysisApi,\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\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  }\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"]}
+{"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// 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} 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\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  }\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\"\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        return result.data\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 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":["import_plugin_core","Comlink","import_plugin_core"]}

package/dist/index.d.ts

@@ -2,6 +2,8 @@ import { ClientPluginApi } from "./api";
 export * from "./api";
 export * from "./host-api";
 export * from "./plugin-worker";
+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.
  *

package/dist/index.d.ts.map

@@ -1 +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"}
+{"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;AAG/B,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

@@ -5,12 +5,16 @@ import {
 
 // src/host-api.ts
 import * as Comlink from "comlink";
+import { PluginError, fromEnvelope, makeClientEnvelope } from "@snaptrude/plugin-core";
 function createHostApi(endpoint) {
   return Comlink.wrap(
     endpoint ?? globalThis
   );
 }
 var _instance = null;
+function __setHostApiInstance(instance) {
+  _instance = instance ?? null;
+}
 function getHostApi() {
   if (!_instance) {
     _instance = createHostApi();
@@ -20,16 +24,35 @@ function getHostApi() {
       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);
-        }
-      });
+      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 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) {
@@ -129,12 +152,47 @@ var PluginWorker = class {
 };
 
 // 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,
+  PluginError2 as PluginError,
+  PluginExecutionError,
+  PluginHandleError,
+  PluginInternalError,
+  PluginLifecycleError,
+  PluginNotFoundError,
+  PluginPermissionError,
+  PluginQuotaError,
+  PluginTimeoutError,
+  PluginTransportError,
+  PluginValidationError,
   PluginWorker,
+  __setHostApiInstance,
   createHostApi,
+  fromEnvelope2 as fromEnvelope,
   getHostApi,
+  isErrorEnvelope,
+  isPluginErrorCode,
   snaptrude
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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  PluginAnalysisApi,\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\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  }\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"]}
+{"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  PluginAnalysisApi,\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\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  }\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\"\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        return result.data\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 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// 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":"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","names":["Comlink","PluginError","fromEnvelope"]}

package/package.json

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

package/src/host-api.ts

@@ -5,6 +5,7 @@ import type {
   PluginApiCallWrappedResult,
   PluginApiCallResult,
 } from "@snaptrude/plugin-core"
+import { PluginError, fromEnvelope, makeClientEnvelope } from "@snaptrude/plugin-core"
 
 export interface HostApi {
   call<M extends PluginApiMethod>(
@@ -26,6 +27,11 @@ export function createHostApi(endpoint?: Comlink.Endpoint): HostApi {
 
 let _instance: HostApi | null = null
 
+/** TEST SEAM ONLY: replace the Comlink host instance (pass `undefined` to reset). */
+export function __setHostApiInstance(instance?: HostApi): void {
+  _instance = instance ?? null
+}
+
 export function getHostApi(): HostApiWrapped {
   if (!_instance) {
     _instance = createHostApi()
@@ -35,13 +41,47 @@ export function getHostApi(): HostApiWrapped {
       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)
-        }
-      })
+
+      let result: PluginApiCallWrappedResult<M>
+      try {
+        result = await _instance.call(payload)
+      } catch (transportErr) {
+        // Comlink-level rejection: port closed, worker terminated, clone
+        // failure. Never a routed failure — the router always RETURNS its
+        // envelope — so normalize to a typed transport error.
+        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 result.data
+      }
+
+      // Structured envelope when the host provides one; legacy hosts (string
+      // `error` only) degrade to UNKNOWN with the message preserved.
+      throw rehydrate(
+        result.errorInfo ??
+          makeClientEnvelope("UNKNOWN", result.error ?? "Unknown host error", {
+            methodPath: payload.method,
+          })
+      )
     }
   }
 }
+
+/**
+ * Envelope → typed `PluginError`, with the stack trimmed to the plugin's call
+ * site (V8 only; harmless no-op elsewhere) instead of transport internals.
+ */
+function rehydrate(envelope: Parameters<typeof fromEnvelope>[0]): PluginError {
+  const error = fromEnvelope(envelope)
+  ;(Error as { captureStackTrace?: (target: object, ctor: Function) => void })
+    .captureStackTrace?.(error, rehydrate)
+  return error
+}

package/src/index.ts

@@ -4,6 +4,32 @@ export * from "./api"
 export * from "./host-api"
 export * from "./plugin-worker"
 
+// Error surface — plugins branch on `PluginError.is(e)` + `e.code`.
+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.
  *

package/test/host-api-errors.test.mjs

@@ -0,0 +1,101 @@
+// Node built-in test runner suite for host-api error rehydration.
+// Run: node --test test/host-api-errors.test.mjs
+// Imports the BUILT package (dist) — run `pnpm build` first.
+import test from "node:test"
+import assert from "node:assert/strict"
+import {
+  getHostApi,
+  __setHostApiInstance,
+  PluginError,
+  PluginQuotaError,
+  PluginTransportError,
+  PluginInternalError,
+} from "../dist/index.js"
+
+const PAYLOAD = { method: "design.boolean.union", args: [] }
+
+/** Install a fake Comlink instance whose call() resolves/rejects as directed. */
+function stubHost(behavior) {
+  __setHostApiInstance({ call: behavior })
+}
+
+test.afterEach(() => {
+  __setHostApiInstance(undefined)
+})
+
+test("success path returns data verbatim (handles are branded strings on the wire)", async () => {
+  const data = { value: 42, h: "mass_x" }
+  stubHost(async () => ({ success: true, data }))
+  const result = await getHostApi().call(PAYLOAD)
+  assert.equal(result, data) // pass-through: no cloning, no re-wrapping
+  assert.equal(result.value, 42)
+  assert.equal(result.h, "mass_x") // a handle IS its plain string id
+})
+
+test("errorInfo envelope rehydrates into the typed subclass with fields intact", async () => {
+  stubHost(async () => ({
+    success: false,
+    error: "Execution error: Rate limit exceeded",
+    errorInfo: {
+      envelopeVersion: 1,
+      code: "RATE_LIMITED",
+      message: "Rate limit exceeded",
+      errorId: "h-1",
+      details: { retryAfterMs: 250 },
+      methodPath: "design.boolean.union",
+    },
+  }))
+  await assert.rejects(getHostApi().call(PAYLOAD), (err) => {
+    assert.equal(PluginError.is(err), true)
+    assert.ok(err instanceof PluginQuotaError)
+    assert.equal(err.code, "RATE_LIMITED")
+    assert.equal(err.errorId, "h-1")
+    assert.deepEqual(err.details, { retryAfterMs: 250 })
+    assert.equal(err.methodPath, "design.boolean.union")
+    return true
+  })
+})
+
+test("unknown envelope code still rehydrates as a PluginError (forward compat)", async () => {
+  stubHost(async () => ({
+    success: false,
+    error: "Execution error: new thing",
+    errorInfo: {
+      envelopeVersion: 1,
+      code: "FUTURE_CODE",
+      message: "new thing",
+      errorId: "h-2",
+    },
+  }))
+  await assert.rejects(getHostApi().call(PAYLOAD), (err) => {
+    assert.equal(PluginError.is(err), true)
+    assert.equal(err.code, "FUTURE_CODE")
+    return true
+  })
+})
+
+test("legacy host (string error only) degrades to UNKNOWN with the message preserved", async () => {
+  stubHost(async () => ({ success: false, error: "Execution error: something broke" }))
+  await assert.rejects(getHostApi().call(PAYLOAD), (err) => {
+    assert.equal(PluginError.is(err), true)
+    assert.ok(err instanceof PluginInternalError)
+    assert.equal(err.code, "UNKNOWN")
+    assert.equal(err.message, "Execution error: something broke")
+    assert.ok(err.errorId.startsWith("c-"))
+    assert.equal(err.methodPath, "design.boolean.union")
+    return true
+  })
+})
+
+test("transport-level rejection normalizes to TRANSPORT_LOST", async () => {
+  stubHost(async () => {
+    throw new Error("port closed")
+  })
+  await assert.rejects(getHostApi().call(PAYLOAD), (err) => {
+    assert.ok(err instanceof PluginTransportError)
+    assert.equal(err.code, "TRANSPORT_LOST")
+    assert.equal(err.message, "port closed")
+    assert.ok(err.errorId.startsWith("c-"))
+    return true
+  })
+})