@snaptrude/plugin-client 0.0.0-dev-20260708130115 → 0.0.0-dev-20260921132444

package/CHANGELOG.md

@@ -1,11 +1,172 @@
 # @snaptrude/plugin-client
 
-## 0.0.0-dev-20260708130115
+## 0.0.0-dev-20260921132444
 
 ### Patch Changes
 
+- Updated dependencies [6e4a055]
+- Updated dependencies [8e37e1f]
+- Updated dependencies [2a06dd9]
+  - @snaptrude/plugin-core@0.0.0-dev-20260921132444
+
+## 0.9.11
+
+### Patch Changes
+
+- e325bee: Add the structural-grids API surface: queries, creators, a sparse patch updater, structural line edits, and generic-family acceptance.
+  - **Query** — `design.query.listGrids(filter?)` (standard `PluginEntityFilter`; `"grid"` joins `PluginEntityType`, so `listByType("grid")` works) and the field-projected `design.query.grids.get(gridId, properties[])`: `angle` (degrees, CCW about +Y), `props`, `storeyVisibility`, `wings` (per-wing spacing/tagStart/span and per-line world-space `CurveHandle`, tag, visibility, effective + override props), `bounds`. Unknown ids throw `HANDLE_INVALID`.
+  - **Create** — `design.create.grid(linesX, linesY, spacingX, spacingY, options?)` (free 2-wing grid; optional `angle` in degrees and `center`, which defaults to the native viewport-centre behavior), `design.create.gridFromCurve(curve, options?)` (one wing/one line — line or arc), `design.create.gridsFromMasses(masses, spacingX, spacingY, options?)` (fitted, one group per footprint cluster, lenient skipping, ONE undo unit), and `design.create.columnsFromGrids(grids, width, depth)` (columns at every line intersection, ONE undo unit).
+  - **Update** — `design.update.grid(grid, patch)`: GROUP-LEVEL sparse patch — `props` (default styling), absolute `angle` in degrees, and `storeyVisibility`; each changed field commits its own undoable command through the panel's setters.
+  - **Grids family** — `design.grids.updateWings(grid, wings[])` (per-wing `spacing`/`count`/`spanMin`/`spanMax`; a `count` change re-indexes lines — re-query) and `design.grids.updateLines(grid, lines[])` (per-line `tag`/`distanceToPrevious`|`distanceToNext` (mutually exclusive)/`props`/`visible: false` (hide-only, product parity — show the GROUP to restore all lines); hiding every remaining visible line hides the GROUP instead — native last-line rule); plus `design.grids.addLine(grid, wing, position)` and `design.grids.removeLines(grid, lines, tagPolicy?)` (`"rewrite"` default | `"preserve"`; removing the group's last line throws `OPERATION_FAILED` — delete the group instead). Every update routes through the exact setters the native panel uses — one undoable command per changed field, identical to panel edits.
+  - **Generic families** — grid groups are accepted by `design.transform.move`/`rotate`, `design.visibility.hide`/`show`, `design.lock`/`unlock`, `design.delete.entities`, and `design.selection`; `transform.align` and `transform.mirror` throw `OPERATION_FAILED` for grids.
+
+  Grid lines have no stable identity: every line-level operation addresses them positionally as `{ wing, line }` index pairs into the `wings` arrays returned by `grids.get`; structural edits re-index lines, so re-query after mutating.
+
+- Updated dependencies [7fd374e]
+- Updated dependencies [e325bee]
+  - @snaptrude/plugin-core@0.9.11
+
+## 0.9.10
+
+### Patch Changes
+
+- Version bump to track plugin-core 0.9.10 (`core.mode.set("program")` opens the Program tab; `workspace.openProgramMode` / `closeProgramMode`). No client code change.
+
+## 0.9.9
+
+### Patch Changes
+
+- Version bump to track plugin-core 0.9.9 (program.metadata, program.labels, program.departments.setTargetCount, custom program sheets on program.spreadsheet, core.tags.listForComponents). No client code change — every namespace is served by the generic RPC proxy, so new plugin-core methods dispatch automatically once plugin-core is rebuilt.
+
+## 0.9.7
+
+### Patch Changes
+
+- 6e60c61: Add bulk `design.create` creators — `wallRuns`, `floors`, `doors`, `windows`, `furnitureItems`: one host round-trip and one undo entry per batch.
+
+  Singular creators, fixes shipped alongside (behaviour changes for existing callers):
+  - `floor`, `slab`, `roof`, `ceiling`, `column`, `beam`: contour holes are now cut (holed contours previously failed or lost their holes).
+  - `floor`: the `position` offset is applied before the creation snapshot, so it survives redo and reload and drives storey assignment.
+  - `furniture`: `options.label` is now also the readable label (`design.query.getLabel`); `createNewSourceMesh` can no longer skip recording a source this call brought in (the host owns source persistence, recorded exactly once across concurrent calls); refuses with `PRECONDITION_FAILED` (`engineCode: "TOOL_ACTIVE"`) while the interactive furniture tool is active. The same refusal applies to `core.io.import.model` furniture placement.
+  - `door`, `window`: published as one save document instead of five; undo granularity unchanged.
+
+- 2f10e6b: Add `design.dimensions` — dimension lines (Measuring Tape): `create`, `list`, `get`, `delete`, `hide`, `show`, plus the new `DimensionHandle`.
+- Updated dependencies [6e60c61]
+- Updated dependencies [2f10e6b]
+  - @snaptrude/plugin-core@0.9.7
+
+## 0.9.6
+
+### Patch Changes
+
+- Updated dependencies
+  - @snaptrude/plugin-core@0.9.6
+
+## 0.9.4
+
+### Patch Changes
+
+- 0008010: `brepFromLoft` auto-matches section edge counts (deterministic vertex insertion) and auto-aligns seams for straight-edge sections; `brepFromSweep` accepts closed (ring) paths and gains an optional taper scale law (`startScale`/`endScale` or per-point `scales`).
+- f54ea17: `brepFromLoft` gains `options` (`compatibility: "strict" | "auto"`, `seamAlignment: "authored" | "auto"` — strict+authored restores pre-0.9.4 lofting); `brepFromSweep` options gain `transition` (`"miter"` default, `"round"` on open paths, `{ bevel }` chamfered corners on open and closed paths); new pure read `core.geom.query.brep.getEdgeCurve` returns exact line/arc/circle edge curve data.
+- Updated dependencies [0008010]
+- Updated dependencies [f54ea17]
+  - @snaptrude/plugin-core@0.9.4
+
+## 0.9.3
+
+### Patch Changes
+
+- 3584bde: Expose configured BIM creation and Site Analysis sheet APIs: `design.create.opening` (catalog door/window with width/height/sillHeight), staircase `dimensions` overrides (strict-validated, quarter-turn rotation), and `program.site.getSiteAnalysis`/`updateSiteAnalysis` with merge/append semantics. `PluginSiteAnalysisUpdateOptions` accepts `null` as "no options".
+- Updated dependencies [3584bde]
+  - @snaptrude/plugin-core@0.9.3
+
+## 0.9.2
+
+### Patch Changes
+
+- 5b91c7b: OCC geometry batch: new `core.geom.create` brep constructors — `brepFromFillet`, `brepFromChamfer`, `brepFromOffset`, `brepFromShell`, `brepsFromSplit`, `brepFromSweep`, `brepFromRevolution`; `brepFromLoft` widened with optional `intermediateContours` (multi-section lofts); new `core.geom.query.brep.getDistance` (minimum distance between two solids with witness points).
+- Updated dependencies [5b91c7b]
+  - @snaptrude/plugin-core@0.9.2
+
+## 0.9.0
+
+### Minor Changes
+
+- Plugin API 0.9.0 — client types/passthrough for the 0.9 surface: the namespace reorganization (deprecate-in-place aliases — `entity.*` retired, `core.zoom` → `core.camera`, new `workspace.*` and `core.mode`), the analysis wave (`analysis.weather`/`solar`/`daylight` incl. async sDA polling), heatmaps v2 (named overlays, `renderField`, `renderSurfaceGrid`, scales, hover), the constructive-geometry brep family (`core.geom.create.brepFrom*` + `design.create.massFromBrep`), `presentation.shapes` and `presentation.placedViews`, geometry reads (`getTriangulatedMeshes`, `getEnclosure`), and the spreadsheet data lane (`datasets`, plugin-sourced bindings, `addImage`, ratified `addChart` enum). See `@snaptrude/plugin-core@0.9.0` and `upgrade-notes/0.8.0-to-0.9.0.md`.
+
+## 0.8.0
+
+### Minor Changes
+
+- More additions to the APIs, infra changes.
+- Plugin API 0.8.0 — the 0.8 API wave, handle lifecycle, and worker events.
+  - **Events** — `PluginWorker.subscribe("model:changed", handler)`: debounced model-change notifications delivered to the worker for user and plugin edits alike; subscriptions live for the plugin's lifetime and are cleared automatically on stop.
+  - **The 0.8 API wave** — client types/passthrough for export, element editing, camera, storey management, visibility, dimensions, locale/user reads, and the behavior corrections in the host (world-unit `program.site` footprints, real beam/column geometry, live-only `design.query.list*`); see `@snaptrude/plugin-core@0.8.0` and `upgrade-notes/0.7.1-to-0.8.0.md`.
+  - **Handle lifecycle (`core.handles.*`) + GC-backed `Handle` objects** — `Handle` is now a class wrapping the wire id (public type names unchanged): `handle.id`, `toString()` stays the bare id, `equals()` compares by id, and `toJSON()` emits the `{__h: id}` wire tag — `JSON.stringify` output containing handles changes shape. New namespace: `core.handles.release(handles[])` (batched, arena-agnostic, silent no-op on unknown/released ids), `core.handles.releaseAll(kind?)`, mint-recording scopes `beginScope()` / `endScope(scope, retain?)` (token-addressed, retain promotes to the enclosing scope), and `core.handles.stats()`. The client runs a FinalizationRegistry-backed auto-release queue, so unreferenced handles are reclaimed host-side without explicit code. `core.geom.delete.profile/contour` are retained as deprecated aliases of `core.handles.release`. Entity-style kinds (component/material/underlay/terrain/importJob) remain branded strings.
+
+### Patch Changes
+
+- Updated dependencies
+  - @snaptrude/plugin-core@0.8.0
+
+## 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.0.0-dev-20260708130115
+  - @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
+
+- a68e866: New top-level `analysis` namespace:
+  `analysis.sunpath` (enable/disable/isActive), `analysis.shadows`
+  (enable/disable/isEnabled/setDateTime/getDateTime — ISO date-time strings),
+  and the async heatmap job families `analysis.sunlightHours` and
+  `analysis.illuminance` (compute/get/cancel/reset; illuminance is Pro-gated).
+  Also extends `program.site` with `getLocation()` and `getNorthAngle()` geo
+  reads. The react host has landed, so all new members are required `abstract`
+  and in the discovery manifest; the plugin-client mounts the `analysis` RPC
+  namespace.
+
+### Patch Changes
+
+- Updated dependencies [934405e]
+- Updated dependencies [a68e866]
+- Updated dependencies
+- Updated dependencies
+  - @snaptrude/plugin-core@0.6.0
 
 ## 0.5.0
 

package/dist/api/index.d.ts

@@ -1,4 +1,4 @@
-import { PluginApi, PluginCoreApi, PluginDesignApi, PluginEntityApi, PluginProgramApi, PluginPresentationApi } from "@snaptrude/plugin-core";
+import { PluginApi, PluginCoreApi, PluginDesignApi, PluginEntityApi, PluginProgramApi, PluginPresentationApi, PluginAnalysisApi } from "@snaptrude/plugin-core";
 export declare class ClientPluginApi extends PluginApi {
     private static instance;
     /**
@@ -12,6 +12,7 @@ export declare class ClientPluginApi extends PluginApi {
     entity: PluginEntityApi;
     program: PluginProgramApi;
     presentation: PluginPresentationApi;
+    analysis: PluginAnalysisApi;
     private constructor();
     static getInstance(): ClientPluginApi;
 }

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

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,aAAa,EACb,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EAClB,MAAM,wBAAwB,CAAA;AAG/B,qBAAa,eAAgB,SAAQ,SAAS;IAC5C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAiB;IAExC;;;;;OAKG;IACI,IAAI,EAAE,aAAa,CAAA;IACnB,MAAM,EAAE,eAAe,CAAA;IACvB,MAAM,EAAE,eAAe,CAAA;IACvB,OAAO,EAAE,gBAAgB,CAAA;IACzB,YAAY,EAAE,qBAAqB,CAAA;IACnC,QAAQ,EAAE,iBAAiB,CAAA;IAElC,OAAO;IAWP,MAAM,CAAC,WAAW,IAAI,eAAe;CAMtC"}

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");
@@ -98,6 +138,7 @@ var ClientPluginApi = class _ClientPluginApi extends import_plugin_core.PluginAp
     this.entity = createRpcNamespace("entity");
     this.program = createRpcNamespace("program");
     this.presentation = createRpcNamespace("presentation");
+    this.analysis = createRpcNamespace("analysis");
   }
   static getInstance() {
     if (!_ClientPluginApi.instance) {
@@ -166,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} 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"]}
+{"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) {
@@ -60,6 +83,7 @@ var ClientPluginApi = class _ClientPluginApi extends PluginApi {
     this.entity = createRpcNamespace("entity");
     this.program = createRpcNamespace("program");
     this.presentation = createRpcNamespace("presentation");
+    this.analysis = createRpcNamespace("analysis");
   }
   static getInstance() {
     if (!_ClientPluginApi.instance) {
@@ -128,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} 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":";AAAA;AAAA,EACE;AAAA,OAMK;;;ACPP,YAAY,aAAa;AAoBlB,SAAS,cAAc,UAAsC;AAClE,SAAe;AAAA,IACb,YAAa;AAAA,EACf;AACF;AAEA,IAAI,YAA4B;AAEzB,SAAS,aAA6B;AAC3C,MAAI,CAAC,WAAW;AACd,gBAAY,cAAc;AAAA,EAC5B;AACA,SAAO;AAAA,IACL,MAAM,OAAkC,YAAsE;AAC5G,UAAI,CAAC,WAAW;AACd,cAAM,IAAI,MAAM,0BAA0B;AAAA,MAC5C;AACA,aAAO,UAAU,KAAK,OAAO,EAAE,KAAK,YAAU;AAC5C,YAAI,OAAO,SAAS;AAClB,iBAAO,OAAO;AAAA,QAChB,OAAO;AACL,gBAAM,IAAI,MAAM,OAAO,KAAK;AAAA,QAC9B;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AACF;;;ACdO,SAAS,mBAAqC,UAAqB;AACxE,QAAM,QAAQ,CAAC,SACb,IAAI,MAAM,MAAM;AAAA,IACd,IAAI,SAAS,MAAM;AAIjB,UAAI,OAAO,SAAS,YAAY,SAAS,OAAQ,QAAO;AACxD,aAAO,MAAM,GAAG,IAAI,IAAI,IAAI,EAAE;AAAA,IAChC;AAAA,IACA,MAAM,SAAS,UAAU,UAAqB;AAC5C,YAAM,UAAU;AAAA,QACd,QAAQ;AAAA,QACR,MAAM;AAAA,MACR;AACA,aAAO,WAAW,EAAE,KAAK,OAAO;AAAA,IAClC;AAAA,EACF,CAAC;AAEH,SAAO,MAAM,QAAQ;AACvB;AAGA,IAAM,OAAO,MAAY;AAAC;;;AF7CnB,IAAM,kBAAN,MAAM,yBAAwB,UAAU;AAAA,EAerC,cAAc;AACpB,UAAM;AACN,SAAK,OAAO,mBAAkC,MAAM;AACpD,SAAK,SAAS,mBAAoC,QAAQ;AAC1D,SAAK,SAAS,mBAAoC,QAAQ;AAC1D,SAAK,UAAU,mBAAqC,SAAS;AAC7D,SAAK,eACH,mBAA0C,cAAc;AAAA,EAC5D;AAAA,EAEA,OAAO,cAA+B;AACpC,QAAI,CAAC,iBAAgB,UAAU;AAC7B,uBAAgB,WAAW,IAAI,iBAAgB;AAAA,IACjD;AACA,WAAO,iBAAgB;AAAA,EACzB;AACF;;;AGzCA,YAAYA,cAAa;AAmClB,IAAe,eAAf,MAA4B;AAAA,EAIjC,cAAc;AACZ,SAAK,UAAkB;AAAA,MACrB;AAAA,IACF;AAAA,EACF;AAAA,EAEU,SAAS,QAAgB,SAAwB;AACzD;AAAC,IAAC,KAAK,QAAgC,GAAG,SAAS,EAAE,QAAQ,QAAQ,CAAC;AAAA,EACxE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOU,WAAiB;AACzB;AAAC,IAAC,KAAK,QAAgC,UAAU,SAAS;AAAA,EAC5D;AAAA,EAEA,MAAM,OAAsB;AAC1B,YAAQ,IAAI,KAAK,UAAU,eAAe;AAC1C,YAAQ,IAAI,KAAK,UAAU,yBAAyB;AAAA,EACtD;AAAA,EAEA,MAAM,UAAyB;AAC7B,YAAQ,IAAI,KAAK,UAAU,qCAAgC;AAAA,EAC7D;AAAA,EAEA,MAAM,OAAwB;AAC5B,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,YAAY,UAAoC;AAAA,EAEtD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,QAAc;AACZ,IAAQ;AAAA,MACN;AAAA,QACE,MAAM,CAAC,WAAyB;AAC9B,eAAK,WAAW,OAAO;AACvB,iBAAO,KAAK,KAAK;AAAA,QACnB;AAAA,QACA,SAAS,MAAM,KAAK,QAAQ;AAAA,QAC5B,MAAM,MAAM,KAAK,KAAK;AAAA,QACtB,aAAa,CAAC,YAAuB,KAAK,YAAY,OAAO;AAAA,MAC/D;AAAA,MACA;AAAA,IACF;AACA,YAAQ,IAAI,wCAAwC;AAAA,EACtD;AACF;;;ACvFO,IAAM,YAAY,gBAAgB,YAAY;","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.0.0-dev-20260708130115",
+  "version": "0.0.0-dev-20260921132444",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -16,9 +16,14 @@
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "dist",
+    "upgrade-notes",
+    "CHANGELOG.md"
+  ],
   "dependencies": {
     "comlink": "^4.4.2",
-    "@snaptrude/plugin-core": "0.0.0-dev-20260708130115"
+    "@snaptrude/plugin-core": "0.0.0-dev-20260921132444"
   },
   "devDependencies": {
     "tsup": "^8.5.1",
@@ -28,6 +33,8 @@
     "check-types": "tsc --noEmit",
     "build": "tsup --clean",
     "dev": "tsup --watch",
-    "clean-dist": "rm -rf dist"
+    "clean-dist": "rm -rf dist",
+    "check:upgrade-notes": "node scripts/check-upgrade-notes.mjs",
+    "test": "node scripts/check-upgrade-notes.mjs && node --test --expose-gc test/*.test.mjs"
   }
 }