@snaptrude/plugin-client 0.0.0-dev-20260708130115 → 0.0.0-walkthroughs-20261005121215

package/CHANGELOG.md

@@ -1,11 +1,210 @@
 # @snaptrude/plugin-client
 
-## 0.0.0-dev-20260708130115
+## 0.9.16
 
 ### Patch Changes
 
+- Updated dependencies [e8d4ec3]
+  - @snaptrude/plugin-core@0.9.16
+
+## 0.9.15
+
+### Patch Changes
+
+- Updated dependencies [4bfe118]
+- Updated dependencies [80c1a2b]
+- Updated dependencies [0e3df96]
+- Updated dependencies [d84ea44]
+  - @snaptrude/plugin-core@0.9.15
+
+## 0.9.14
+
+### Patch Changes
+
+- Updated dependencies [22c919b]
+  - @snaptrude/plugin-core@0.9.14
+
+## 0.9.13
+
+### Patch Changes
+
+- Updated dependencies [6c85137]
+  - @snaptrude/plugin-core@0.9.13
+
+## 0.9.12
+
+### Patch Changes
+
+- Updated dependencies [6e4a055]
+- Updated dependencies [8e37e1f]
+- Updated dependencies [2a06dd9]
+  - @snaptrude/plugin-core@0.9.12
+
+## 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.8
+
+### Patch Changes
+
+- Updated dependencies [7fd374e]
+  - @snaptrude/plugin-core@0.9.8
+
+## 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, PluginWorkspaceApi } from "@snaptrude/plugin-core";
 export declare class ClientPluginApi extends PluginApi {
     private static instance;
     /**
@@ -12,6 +12,8 @@ export declare class ClientPluginApi extends PluginApi {
     entity: PluginEntityApi;
     program: PluginProgramApi;
     presentation: PluginPresentationApi;
+    analysis: PluginAnalysisApi;
+    workspace: PluginWorkspaceApi;
     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,EACjB,kBAAkB,EACnB,MAAM,wBAAwB,CAAA;AAG/B,qBAAa,eAAgB,SAAQ,SAAS;IAC5C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAiB;IAExC;;;;;OAKG;IACI,IAAI,EAAE,aAAa,CAAA;IACnB,MAAM,EAAE,eAAe,CAAA;IACvB,MAAM,EAAE,eAAe,CAAA;IACvB,OAAO,EAAE,gBAAgB,CAAA;IACzB,YAAY,EAAE,qBAAqB,CAAA;IACnC,QAAQ,EAAE,iBAAiB,CAAA;IAC3B,SAAS,EAAE,kBAAkB,CAAA;IAEpC,OAAO;IAYP,MAAM,CAAC,WAAW,IAAI,eAAe;CAMtC"}

package/dist/events.d.ts

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

package/dist/events.d.ts.map

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

package/dist/handle-runtime.d.ts

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

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

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

package/dist/host-api.d.ts

@@ -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;AAI/B,MAAM,WAAW,OAAO;IACtB,IAAI,CAAC,CAAC,SAAS,eAAe,EAC5B,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC/B,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAA;CAC1C;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,CAAC,SAAS,eAAe,EAC5B,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC/B,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAA;CACnC;AAED,wBAAgB,aAAa,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,QAAQ,GAAG,OAAO,CAIlE;AAID,qFAAqF;AACrF,wBAAgB,oBAAoB,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAE7D;AAED,wBAAgB,UAAU,IAAI,cAAc,CA0C3C"}

package/dist/index.cjs

@@ -30,25 +30,163 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CODE_META: () => import_plugin_core4.CODE_META,
   ClientPluginApi: () => ClientPluginApi,
+  PLUGIN_ERROR_CODES: () => import_plugin_core4.PLUGIN_ERROR_CODES,
+  PLUGIN_EVENTS: () => PLUGIN_EVENTS,
+  PluginError: () => import_plugin_core4.PluginError,
+  PluginExecutionError: () => import_plugin_core4.PluginExecutionError,
+  PluginHandleError: () => import_plugin_core4.PluginHandleError,
+  PluginInternalError: () => import_plugin_core4.PluginInternalError,
+  PluginLifecycleError: () => import_plugin_core4.PluginLifecycleError,
+  PluginNotFoundError: () => import_plugin_core4.PluginNotFoundError,
+  PluginPermissionError: () => import_plugin_core4.PluginPermissionError,
+  PluginQuotaError: () => import_plugin_core4.PluginQuotaError,
+  PluginTimeoutError: () => import_plugin_core4.PluginTimeoutError,
+  PluginTransportError: () => import_plugin_core4.PluginTransportError,
+  PluginValidationError: () => import_plugin_core4.PluginValidationError,
   PluginWorker: () => PluginWorker,
+  __setHostApiInstance: () => __setHostApiInstance,
+  __setReleaseTransport: () => __setReleaseTransport,
   createHostApi: () => createHostApi,
+  flushReleaseQueue: () => flushReleaseQueue,
+  fromEnvelope: () => import_plugin_core4.fromEnvelope,
   getHostApi: () => getHostApi,
-  snaptrude: () => snaptrude
+  intern: () => intern,
+  isErrorEnvelope: () => import_plugin_core4.isErrorEnvelope,
+  isPluginErrorCode: () => import_plugin_core4.isPluginErrorCode,
+  rewrapResult: () => rewrapResult,
+  snaptrude: () => snaptrude,
+  unwrapArgs: () => unwrapArgs
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/api/index.ts
-var import_plugin_core = require("@snaptrude/plugin-core");
+var import_plugin_core3 = require("@snaptrude/plugin-core");
 
 // src/host-api.ts
 var Comlink = __toESM(require("comlink"), 1);
+var import_plugin_core2 = require("@snaptrude/plugin-core");
+
+// src/handle-runtime.ts
+var import_plugin_core = require("@snaptrude/plugin-core");
+var interned = /* @__PURE__ */ new Map();
+var RELEASE_FLUSH_SIZE = 64;
+var RELEASE_FLUSH_MS = 250;
+var MAX_FLUSH_FAILURES = 5;
+var releaseQueue = /* @__PURE__ */ new Set();
+var flushTimer = null;
+var consecutiveFlushFailures = 0;
+var finalizer = new FinalizationRegistry((id) => {
+  if (interned.get(id)?.deref()) return;
+  interned.delete(id);
+  enqueueRelease(id);
+});
+function intern(id) {
+  releaseQueue.delete(id);
+  const existing = interned.get(id)?.deref();
+  if (existing) return existing;
+  const handle = new import_plugin_core.Handle(id);
+  handle[Symbol.asyncDispose] = async () => {
+    if (interned.get(id)?.deref() === handle) interned.delete(id);
+    enqueueRelease(id);
+  };
+  interned.set(id, new WeakRef(handle));
+  finalizer.register(handle, id);
+  return handle;
+}
+function enqueueRelease(id) {
+  releaseQueue.add(id);
+  if (releaseQueue.size >= RELEASE_FLUSH_SIZE) {
+    void flushReleaseQueue();
+    return;
+  }
+  flushTimer ?? (flushTimer = setTimeout(() => {
+    void flushReleaseQueue();
+  }, RELEASE_FLUSH_MS));
+}
+var releaseTransport = async (batch) => {
+  await getHostApi().call({
+    method: "core.handles.release",
+    args: [batch]
+  });
+};
+function __setReleaseTransport(transport) {
+  releaseTransport = transport ?? (async (batch) => {
+    await getHostApi().call({
+      method: "core.handles.release",
+      args: [batch]
+    });
+  });
+}
+async function flushReleaseQueue() {
+  if (flushTimer) {
+    clearTimeout(flushTimer);
+    flushTimer = null;
+  }
+  if (releaseQueue.size === 0) return;
+  const batch = [...releaseQueue];
+  releaseQueue.clear();
+  try {
+    await releaseTransport(batch);
+    consecutiveFlushFailures = 0;
+  } catch (err) {
+    consecutiveFlushFailures += 1;
+    if (consecutiveFlushFailures >= MAX_FLUSH_FAILURES) {
+      console.warn(
+        `[snaptrude] dropping ${batch.length} handle release(s) after ${consecutiveFlushFailures} failed flushes`,
+        err
+      );
+      consecutiveFlushFailures = 0;
+      return;
+    }
+    for (const id of batch) {
+      if (!interned.get(id)?.deref()) releaseQueue.add(id);
+    }
+  }
+}
+function rewrapResult(value) {
+  if (Array.isArray(value)) return value.map(rewrapResult);
+  if (value && typeof value === "object") {
+    const record = value;
+    const keys = Object.keys(record);
+    if (keys.length === 1 && keys[0] === "__h" && typeof record.__h === "string") {
+      return intern(record.__h);
+    }
+    for (const key of keys) record[key] = rewrapResult(record[key]);
+    return record;
+  }
+  return value;
+}
+function unwrapArgs(value, memo = /* @__PURE__ */ new Map()) {
+  if (value instanceof import_plugin_core.Handle) return value.id;
+  if (value === null || typeof value !== "object") return value;
+  const hit = memo.get(value);
+  if (hit !== void 0) return hit;
+  if (Array.isArray(value)) {
+    const out2 = [];
+    memo.set(value, out2);
+    for (const item of value) out2.push(unwrapArgs(item, memo));
+    return out2;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return value;
+  const out = {};
+  memo.set(value, out);
+  for (const [key, item] of Object.entries(value)) out[key] = unwrapArgs(item, memo);
+  return out;
+}
+
+// src/host-api.ts
 function createHostApi(endpoint) {
   return Comlink.wrap(
     endpoint ?? globalThis
   );
 }
 var _instance = null;
+function __setHostApiInstance(instance) {
+  _instance = instance ?? null;
+}
 function getHostApi() {
   if (!_instance) {
     _instance = createHostApi();
@@ -58,16 +196,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_core2.PluginError.is(transportErr)) throw transportErr;
+        throw rehydrate(
+          (0, import_plugin_core2.makeClientEnvelope)(
+            "TRANSPORT_LOST",
+            transportErr instanceof Error ? transportErr.message : String(transportErr),
+            { methodPath: payload.method }
+          )
+        );
+      }
+      if (result.success) {
+        return rewrapResult(result.data);
+      }
+      throw rehydrate(
+        result.errorInfo ?? (0, import_plugin_core2.makeClientEnvelope)("UNKNOWN", result.error ?? "Unknown host error", {
+          methodPath: payload.method
+        })
+      );
     }
   };
 }
+function rehydrate(envelope) {
+  const error = (0, import_plugin_core2.fromEnvelope)(envelope);
+  Error.captureStackTrace?.(error, rehydrate);
+  return error;
+}
 
 // src/rpc-proxy.ts
 function createRpcNamespace(basePath) {
@@ -79,7 +236,8 @@ function createRpcNamespace(basePath) {
     apply(_target, _thisArg, argArray) {
       const payload = {
         method: path,
-        args: argArray
+        // Handle instances anywhere in the tuple become their wire id strings.
+        args: argArray.map((arg) => unwrapArgs(arg))
       };
       return getHostApi().call(payload);
     }
@@ -90,7 +248,7 @@ var NOOP = () => {
 };
 
 // src/api/index.ts
-var ClientPluginApi = class _ClientPluginApi extends import_plugin_core.PluginApi {
+var ClientPluginApi = class _ClientPluginApi extends import_plugin_core3.PluginApi {
   constructor() {
     super();
     this.core = createRpcNamespace("core");
@@ -98,6 +256,8 @@ 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");
+    this.workspace = createRpcNamespace("workspace");
   }
   static getInstance() {
     if (!_ClientPluginApi.instance) {
@@ -119,6 +279,17 @@ var PluginWorker = class {
     ;
     this.hostAPI.ui.sendToUI({ action, payload });
   }
+  /**
+   * Show a transient notification toast in the Snaptrude editor.
+   *
+   * @param message - Text to display.
+   * @param type - Severity; `"error"`/`"warning"` linger a little longer than
+   *   `"info"`. Defaults to `"info"`.
+   */
+  notify(message, type = "info") {
+    ;
+    this.hostAPI.ui.showNotification(message, type);
+  }
   /**
    * Signal the host that this plugin has finished its work and should be
    * stopped. Use this in headless (UI-less) plugins that run a task and
@@ -128,6 +299,35 @@ var PluginWorker = class {
     ;
     this.hostAPI.lifecycle.complete();
   }
+  /**
+   * Subscribe to a host event (e.g. `"model:changed"`, fired debounced on any
+   * user- or plugin-initiated model edit). The callback runs in this worker
+   * each time the event fires; its argument is a small structured-clone-safe
+   * payload (see the event's payload type, e.g. `ModelChangedEvent`).
+   *
+   * Fire-and-forget: subscribe once (typically in `init()`). Subscriptions live
+   * for the plugin's lifetime and are cleared automatically when the plugin is
+   * stopped — there is no `unsubscribe` yet.
+   *
+   * @example
+   * ```ts
+   * import type { ModelChangedEvent } from "@snaptrude/plugin-client";
+   *
+   * async init() {
+   *   this.subscribe("model:changed", (e) => {
+   *     const { source } = e as ModelChangedEvent;
+   *     console.log("model changed via", source);
+   *   });
+   * }
+   * ```
+   */
+  subscribe(event, callback) {
+    ;
+    this.hostAPI.events.on(
+      event,
+      Comlink2.proxy(callback)
+    );
+  }
   async init() {
     console.log(this.pluginId, "init() called");
     console.log(this.pluginId, "Initialization complete");
@@ -165,14 +365,47 @@ var PluginWorker = class {
   }
 };
 
+// src/events.ts
+var PLUGIN_EVENTS = [
+  "selection:changed",
+  "tool:activated",
+  "project:saved",
+  "view:changed",
+  "model:changed"
+];
+
 // src/index.ts
+var import_plugin_core4 = require("@snaptrude/plugin-core");
 var snaptrude = ClientPluginApi.getInstance();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CODE_META,
   ClientPluginApi,
+  PLUGIN_ERROR_CODES,
+  PLUGIN_EVENTS,
+  PluginError,
+  PluginExecutionError,
+  PluginHandleError,
+  PluginInternalError,
+  PluginLifecycleError,
+  PluginNotFoundError,
+  PluginPermissionError,
+  PluginQuotaError,
+  PluginTimeoutError,
+  PluginTransportError,
+  PluginValidationError,
   PluginWorker,
+  __setHostApiInstance,
+  __setReleaseTransport,
   createHostApi,
+  flushReleaseQueue,
+  fromEnvelope,
   getHostApi,
-  snaptrude
+  intern,
+  isErrorEnvelope,
+  isPluginErrorCode,
+  rewrapResult,
+  snaptrude,
+  unwrapArgs
 });
 //# sourceMappingURL=index.cjs.map