@snaptrude/plugin-client 0.7.1 → 0.9.0

package/upgrade-notes/0.7.1-to-0.8.0.md

@@ -0,0 +1,44 @@
+---
+from: 0.7.1
+to: 0.8.0
+breaking: true
+---
+
+## Summary
+
+0.8.0 turns handles into real objects with a managed lifecycle, adds the 0.8 API wave (export, element editing, camera, storey management, visibility, dimensions, locale, events), and fixes several host behaviors that silently produced wrong geometry or wrong data. Most plugin code compiles and runs unchanged — the breaking surface is code that treats handles as plain strings, plus the behavior corrections below.
+
+## Breaking changes
+
+- **`Handle` is now a class, not a string.** Public type names are unchanged (`Vec3Handle`, `ProfileHandle`, `BrepHandle`, …) and every API keeps accepting the values it returns, but a handle is no longer a `string` at runtime:
+  - `typeof handle` is now `"object"`, not `"string"`. Remove `typeof x === "string"` checks on handles.
+  - `JSON.stringify(handle)` now emits the wire tag `{"__h":"<id>"}` instead of a bare id string. Code that persists or logs stringified structures containing handles sees a new shape. To keep the old output use `handle.toString()` / `` `${handle}` `` / `handle.id`.
+  - String operations (`.startsWith`, concatenation, using a handle as an object key) must go through `handle.id` (the bare wire id) — template literals and `toString()` still produce the bare id.
+  - Compare handles with `a.equals(b)` (or `a.id === b.id`), not `a === b`. Identity `===` still works for handles returned by the same call chain (the client interns wrappers per id), but `.equals()` is the guaranteed form.
+  - Entity-style kinds are NOT affected: component/material/underlay/terrain/importJob ids remain branded strings.
+- **`program.site` footprints are now world Snaptrude units, not metres.** Site parcel footprints were the only plan-geometry read scaled to scene metres (×0.254), so they could not be overlaid on `planPoints` / space footprints. They now return world XZ plan coordinates in Snaptrude units — the same plan space as every other plan read. Code that scaled site footprints by 1/0.254 to compensate must drop that correction. Areas and the geographic reads (`listGeoPolygons`, `getContext`) are unchanged.
+- **`design.create.beam` / `design.create.column` build real geometry where they previously built degenerate solids.** Horizontal beams (the documented canonical call) used to build a zero-height flat sheet sunk below ground; they now build a true beam via tool-parity footprint synthesis (section X extent = width, Z extent = depth, body hangs below the authoring plane by its depth). Columns are built to exactly the requested height — the silent slab-thickness deduction is gone (previously every API column was one slab short, and heights below slab thickness built inverted). Degenerate inputs (zero/diagonal/in-plane directions, zero height) now throw VALIDATION errors instead of silently producing corrupt geometry. Direction vectors are normalized, so magnitude no longer scales dimensions.
+- **`design.query.list*` no longer lists engine-internal shells.** After an instance-mode copy, the replaced originals (parked at infinity) and disposed phantoms no longer appear in `listSpaces` and the other list reads — previously one copy silently doubled space counts and schedules. If code relied on seeing the parked originals, it must stop; they were never user-visible geometry.
+
+## New APIs
+
+- **`core.handles.*` — handle lifecycle.** `release(handles[])` (batched, arena-agnostic, silent no-op on unknown/already-released ids), `releaseAll(kind?)`, mint-recording scopes `beginScope()` → `endScope(scope, retain?)` (token-addressed close; `retain` promotes handles to the enclosing scope), and `stats()`. The client also runs a GC-backed auto-release queue (FinalizationRegistry), so handles you drop are reclaimed host-side without explicit code; use explicit `release`/scopes for deterministic cleanup in long-running or handle-heavy plugins.
+- **The 0.8 API wave.** Model/presentation export (`core.io.export`, `presentation.export`), element editing widenings on `design.update`/`design.edit`, `core.camera.*`, storey management, `design.visibility.*`, dimensions, locale/user reads (`core.user`), `design.types.list`, presentation annotate — see the 0.8.0 changelog for the full list.
+- **Events.** `this.subscribe("model:changed", handler)` on `PluginWorker` — debounced model-change notifications delivered to the plugin worker (fires for user and plugin edits alike); see the Plugin Development guide.
+
+## Behavior changes
+
+- `core.geom.delete.profile` / `core.geom.delete.contour` are deprecated aliases of `core.handles.release` — they keep working, but migrate to `core.handles.release([handle])`.
+- `design.create.copy` with `count > 1` no longer freezes the canvas after the call resolves (the post-commit properties-panel storm is fixed); results are unchanged.
+- `design.delete.entities` deletes instance copies before their source meshes within a batch, so mixed batches no longer fail midway with invalidated handles.
+- `design.update.wall` rebuilds (thickness/type changes) replace the wall — always re-bind to the returned `affected[0]` handle; the old handle dies with the rebuilt mesh.
+
+## No action needed
+
+Plugin code that only passes handles back into API calls (the overwhelmingly common pattern) compiles and runs unchanged against 0.8.0 — template literals and `toString()` still produce the bare id, and every API accepts the values it returns. Action is needed only for the handle-as-string patterns and behavior corrections above; the migration is:
+
+1. Bump `@snaptrude/plugin-client` to `0.8.0` and reinstall.
+2. Grep for `typeof` checks, string methods, `===` comparisons, object/Map keys, and `JSON.stringify` on handle values; route them through `handle.id` / `handle.equals()`.
+3. Replace `core.geom.delete.*` calls with `core.handles.release([...])`.
+4. Drop any 1/0.254 compensation on `program.site` footprints, and re-bind wall handles from `design.update.wall`'s `affected`.
+5. Rebuild; existing additive API usage needs no changes.

package/upgrade-notes/0.8.0-to-0.9.0.md

@@ -0,0 +1,61 @@
+---
+from: 0.8.0
+to: 0.9.0
+breaking: false
+---
+
+## Summary
+
+0.9.0 reorganizes the namespace map: the `entity` top-level is retired (storeys move under `core`, reference lines and buildable envelopes join the `design` family), two straggler renames land (`core.zoom` → `core.camera`, `getTagsForComponent` → `listForComponent`), and a new `workspace` top-level plus `core.mode` and a façade heatmap API are introduced. Nothing breaks: every deprecated path keeps working — each delegates to the same implementation as its canonical replacement — so existing plugins compile and run unchanged. Migrate names at your own pace; new code should use the canonical paths.
+
+## Breaking changes
+
+None. All 0.9.0 moves are deprecate-in-place aliases; no signatures or result shapes changed on existing paths.
+
+## Moved paths (deprecated → canonical)
+
+- `entity.story.get` → `core.storeys.get`
+- `entity.story.getAll` → `core.storeys.list` — the canonical result names the field `storeys` where `getAll` named it `stories`; the records are identical
+- `entity.story.create` → `core.storeys.create`
+- `entity.story.update` → `core.storeys.update`
+- `entity.story.delete` → `core.storeys.delete`
+- `entity.story.duplicate` → `core.storeys.copy`
+- `entity.story.setActive` → `core.storeys.setActive`
+- `entity.referenceLine.createMulti` → `design.create.referenceLines` — adds optional styling args and returns a `ComponentHandle[]` where `createMulti` returned `{ referenceLineIds }`
+- `entity.referenceLine.get` → `design.query.referenceLines.get`
+- `entity.referenceLine.getAll` → `design.query.listReferenceLines` — returns a filterable `ComponentHandle[]` where `getAll` returned `{ referenceLineIds }`
+- `entity.referenceLine.delete` → `design.delete.entities`
+- `entity.buildableEnvelope.create` → `design.create.buildableEnvelope`
+- `entity.buildableEnvelope.update` → `design.update.buildableEnvelope`
+- `core.zoom.extents` → `core.camera.zoomExtents`
+- `core.zoom.selection` → `core.camera.zoomSelection`
+- `core.tags.getTagsForComponent` → `core.tags.listForComponent`
+
+## New APIs
+
+- **`workspace.*` — dashboard-level operations.** `workspace.projects.{list, get, create, copy, rename}` (`copy` is the dashboard's Save As) and `workspace.teams.{list, get, listMembers}` — project and team operations that previously had no plugin surface. Mutators are write-gated like every other mutating API.
+- **`core.mode.{list, get, set}` — application mode.** Read and switch between `design`, `bim`, `present`, and `program`. `set("program")` throws `PRECONDITION_FAILED` (Program opens in a paired browser tab the plugin worker cannot drive).
+- **`analysis.heatmaps.renderSurfaceGrid`** — oriented-plane (façade) heatmap grids: `renderGrid` plus a plane-normal argument, for vertical and tilted surfaces.
+- **`analysis.heatmaps` named overlays** — render calls accept `options.name` to register up to 16 concurrent overlays (unnamed renders keep the old replace-in-place behaviour via a shared default), and the new `analysis.heatmaps.overlays` sub-API manages them: `list()`, `show(name)` / `hide(name)` / `remove(name)`, `removeAll()`; exactly one overlay is visible at a time (legend follows it), and `reset()` clears them all. Overlays are in-session only and every overlay clears on any scene-mutating edit.
+- **`analysis.heatmaps.renderField(cells, options?)`** — arbitrary cell geometry: planar polygon rings (host-triangulated) or pre-tessellated `vertices`/`indices` meshes, one value each. Every heatmap render call now also accepts `options.scale`: discrete `bands` (2–64, default 11 — unchanged default), binary `threshold` (pass/fail with a labelled two-swatch legend), or exact-match `categorical` classes.
+- **Heatmap hover tooltips** — pass `hover: true` in any `analysis.heatmaps` render call to get a per-cell tooltip while that overlay is visible, showing the cell's `value` (+ unit) and optional `meta` payload; grid/surface-grid cells now accept `meta` like field cells.
+- **`design.query.geometry.getTriangulatedMeshes(components, options?)`** — triangulated render meshes as plain world-space arrays (`{ meshes: [{ id, positions, indices, materialIds? }] }`, no kernel handles), in plan units; optional per-triangle material names via `includeMaterialIds: true` (`null` = unpainted/default); capped at 500 000 triangles per call (over-cap throws `VALIDATION` with the actual total — split the component list and batch).
+- **`presentation.shapes` — plugin-owned keyed shapes on Present sheets.** `upsert(key, shape, { sheetId? })` creates-or-updates one stable shape per key (deterministic id, returns `{ shapeId, created }`), so rerunning an analysis updates the sheet instead of duplicating; plus `remove(key)`, `removeAll()`, and `list()`. The `shape` spec is a `type: "text" | "note" | "arrow" | "geo"` union taking the same options as the matching `presentation.annotate` call.
+- **`program.site.getTimezone()`** — the IANA timezone id (e.g. `"Asia/Kolkata"`) of the project's geo-location, or `null` when the project is not geo-located on terrain.
+- **`analysis.weather.getSeries(args)`** — hourly weather rows (dry-bulb, humidity, wind, radiation, sky cover) for a date range from the project's resolved EPW station, with full source metadata (station, WMO, distance, checksum) and per-field quality flags. Throws typed `PRECONDITION_FAILED` / `NOT_GEOLOCATED` on non-geo-located projects.
+- **`analysis.solar.sampleGrid(args)`** — per-point solar sampling at arbitrary world positions: direct-sun visibility, shade fraction, sky-view factor, and direct/diffuse/total irradiance (W/m² instant or kWh/m² over a range), GPU-raytraced against the full model + terrain context. Pro-gated and write-gated like `analysis.illuminance`.
+- **`analysis.daylight.compute(args)` + `poll({ runId, cursor? })`** — IES LM-83 annual daylight metrics as numbers (no textures): per-sensor records and per-space/storey/project aggregates with a full provenance echo (weather file, thresholds, grid, resolved optics, blind operation). `metrics: ["ASE"]` runs synchronously as before; runs including `"sDA"` now compute real sDA300/50% (Radiance) with LM-83 dynamic blind operation (2% rule, 5% diffuse closed-blind default — the API operates the blinds; sDA without blinds is not LM-83-compliant) and are asynchronous: `compute` returns `{ status: "running", runId }` immediately, and the new `analysis.daylight.poll` fetches results until `status === "complete"`. Optional `optics` arg overrides surface optics per material (keyed by material name as shown in Snaptrude) or per category, over LM-83/convention defaults (wall 0.5 / ceiling 0.7 / floor 0.2 / furniture 0.5 / glazing Tvis 0.65 / context 0.2); glazing takes visible transmittance (Tvis), converted to Radiance transmissivity backend-side. Sensor records gain `da300Percent`/`sdaPass`, aggregates gain `sdaPercent`; ASE fields are present when ASE is requested.
+- **`program.site.getWeather()`** — the project's resolved weather source (station metadata + any pinned override), without fetching rows.
+- **`core.io.import` accepts `.epw` weather files** — upload into the project weather catalog (deduped by checksum) and optionally pin as the project's weather override; `analysis.weather`/`solar`/`daylight` then resolve to the pinned file.
+- **`design.query.geometry.getTriangulatedMeshes` `includeFaceIndices`** — per-triangle B-rep face ids (`faceIds`, honest `null` when a component has no face mapping), enabling face-level post-processing on the triangulated output.
+- **`design.query.spaces.getEnclosure(space)`** — geometric v1 enclosure read: the surfaces bounding a space and its adjacent spaces, derived from live geometry.
+- **`program.spreadsheet.datasets.{set, list}` + plugin-sourced bindings** — store named plugin datasets (upsert; 10 000-row / 2 MB caps) and bind them to ranges with `bindings.create(name, { dataset: "plugin", name }, target)`; re-running `datasets.set` auto-refreshes every binding bound to that dataset. The takeoff source (`{ dataset: "takeoff" }`) is unchanged.
+- **`program.spreadsheet.addImage(sheetName, image, options?)`** — floating images in workbook sheets from PNG/JPEG/SVG data URIs (2 MB cap): cell-anchored, optional explicit size (intrinsic by default), and a stable `name` replaces the picture on rerun. For images on Present-mode sheets use `presentation.shapes` instead.
+- **`program.spreadsheet.addChart` contract enum** — the ratified `chartType` names (`"column"`, `"bar"`) now work on the wire; the legacy internal names (`"columnClustered"`, `"barClustered"`) remain accepted.
+- **`core.geom.create.brepFrom*` — constructive solid modeling.** A full family of brep constructors that mint `BrepHandle`s at authored coordinates: `brepFromFaces(faces)` (plain `{x, y, z}` face loops — host validates welding, planarity, edge coherence and fixes global orientation), `brepFromExtrusion(contour, direction, amount)` (prisms along any direction, holes and arc profiles included), `brepFromLoft(bottomContour, topContour)` (tapered solids; lofts that would produce non-planar side faces are rejected), `brepFromMesh(positions, faces)` (indexed vertex + face-index input), and the booleans `brepFromUnion` / `brepFromSubtraction` (`a` minus `b`) / `brepFromIntersection` — the production OpenCascade lane; scene-derived `getBrep` handles are accepted as read-only boolean inputs, and empty or disjoint results throw typed `VALIDATION` errors. All minted breps are inspectable through `core.geom.query.brep.*` before committing.
+- **`design.create.massFromBrep(brep, label?)`** — commit a mass from any `core.geom.create` brep constructor's handle (scene-derived `getBrep` breps stay read-only → `PRECONDITION_FAILED`): generic mass at the authored coordinates, single undo step, collab-synced. Together with the constructors this closes the loop — author faces / extrude / loft / boolean, then place the result in the scene.
+- **`presentation.placedViews` — layout control over placed views.** Inspect and edit the LAYOUT of view shapes already placed on Present sheets (content refresh stays on `sheets.updatePlacedView`): `list(sheetId?)` / `get(shapeId)` return sheet, sheet-local position, size, architectural scale (`null` for 3D), rotation, crop and link state; `move(shapeId, position, { sheetId? })` repositions or reparents across sheets; `scale(shapeId, factor)` is a uniform corner-drag-equivalent resize; `setScale(shapeId, scale)` sets a standard architectural scale (2D views only); `setCrop(shapeId, crop | null)` crops with native tldraw fractions, keeping the visible region page-anchored — and the crop survives `updatePlacedView` refreshes. Identity is the shape id `sheets.place` returns.
+
+## No action needed
+
+All 0.9.0 changes are additive. Deprecated paths remain until at least the next major version, and removal is gated on call metrics showing zero live traffic plus a consumer sweep. To modernize a plugin: rename calls per the moved-paths list above (only `core.storeys.list` and the two reference-line list/create reads have different result shapes from their predecessors — everything else is a pure rename).

package/upgrade-notes/index.json

@@ -0,0 +1,42 @@
+{
+  "package": "@snaptrude/plugin-client",
+  "latest": "0.9.0",
+  "spans": [
+    {
+      "from": "0.4.0",
+      "to": "0.5.0",
+      "file": "0.4.0-to-0.5.0.md",
+      "breaking": false
+    },
+    {
+      "from": "0.5.0",
+      "to": "0.6.0",
+      "file": "0.5.0-to-0.6.0.md",
+      "breaking": false
+    },
+    {
+      "from": "0.6.0",
+      "to": "0.7.0",
+      "file": "0.6.0-to-0.7.0.md",
+      "breaking": true
+    },
+    {
+      "from": "0.7.0",
+      "to": "0.7.1",
+      "file": "0.7.0-to-0.7.1.md",
+      "breaking": false
+    },
+    {
+      "from": "0.7.1",
+      "to": "0.8.0",
+      "file": "0.7.1-to-0.8.0.md",
+      "breaking": true
+    },
+    {
+      "from": "0.8.0",
+      "to": "0.9.0",
+      "file": "0.8.0-to-0.9.0.md",
+      "breaking": false
+    }
+  ]
+}

package/AGENTS.md

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

package/CLAUDE.md

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

package/src/api/index.ts

@@ -1,45 +0,0 @@
-import {
-  PluginApi,
-  PluginCoreApi,
-  PluginDesignApi,
-  PluginEntityApi,
-  PluginProgramApi,
-  PluginPresentationApi,
-  PluginAnalysisApi,
-} from "@snaptrude/plugin-core"
-import { createRpcNamespace } from "../rpc-proxy"
-
-export class ClientPluginApi extends PluginApi {
-  private static instance: ClientPluginApi
-
-  /**
-   * Every namespace is fully remote under the all-handle model: math/geom now
-   * cross to the host (values are opaque handles), so there is no in-worker
-   * compute left. All dispatch through a single generic RPC Proxy. Units live
-   * under `core.units`, so they ride the `core` proxy.
-   */
-  public core: PluginCoreApi
-  public design: PluginDesignApi
-  public entity: PluginEntityApi
-  public program: PluginProgramApi
-  public presentation: PluginPresentationApi
-  public analysis: PluginAnalysisApi
-
-  private constructor() {
-    super()
-    this.core = createRpcNamespace<PluginCoreApi>("core")
-    this.design = createRpcNamespace<PluginDesignApi>("design")
-    this.entity = createRpcNamespace<PluginEntityApi>("entity")
-    this.program = createRpcNamespace<PluginProgramApi>("program")
-    this.presentation =
-      createRpcNamespace<PluginPresentationApi>("presentation")
-    this.analysis = createRpcNamespace<PluginAnalysisApi>("analysis")
-  }
-
-  static getInstance(): ClientPluginApi {
-    if (!ClientPluginApi.instance) {
-      ClientPluginApi.instance = new ClientPluginApi()
-    }
-    return ClientPluginApi.instance
-  }
-}

package/src/host-api.ts

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

package/src/index.ts

@@ -1,38 +0,0 @@
-import { ClientPluginApi } from "./api"
-
-export * from "./api"
-export * from "./host-api"
-export * from "./plugin-worker"
-
-// Error surface — plugins branch on `PluginError.is(e)` + `e.code`.
-export {
-  PluginError,
-  PluginValidationError,
-  PluginNotFoundError,
-  PluginPermissionError,
-  PluginHandleError,
-  PluginQuotaError,
-  PluginTimeoutError,
-  PluginTransportError,
-  PluginLifecycleError,
-  PluginExecutionError,
-  PluginInternalError,
-  fromEnvelope,
-  isErrorEnvelope,
-  isPluginErrorCode,
-  PLUGIN_ERROR_CODES,
-  CODE_META,
-} from "@snaptrude/plugin-core"
-export type {
-  ErrorEnvelope,
-  PluginErrorCode,
-  WirePluginErrorCode,
-  PluginErrorCategory,
-} from "@snaptrude/plugin-core"
-
-/**
- * The Snaptrude plugin client API.
- *
- * The main entry point for plugins to interact with the Snaptrude platform.
- */
-export const snaptrude = ClientPluginApi.getInstance()

package/src/plugin-worker.ts

@@ -1,99 +0,0 @@
-import * as Comlink from "comlink"
-
-export interface UIMessage {
-  action: string
-  payload: unknown
-}
-
-interface PluginConfig {
-  pluginId: string
-}
-
-/**
- * Base class for Snaptrude plugin workers.
- *
- * Handles Comlink wiring, host communication, and the standard lifecycle
- * methods (`init`, `destroy`, `ping`, `onUIMessage`). Subclass this and
- * override only the methods you need — then call `start()` to expose the
- * worker API.
- *
- * The plugin ID is received automatically from the host during
- * initialization — no need to pass it manually.
- *
- * @example
- * ```ts
- * import { PluginWorker } from "@snaptrude/plugin-client";
- *
- * class MyPlugin extends PluginWorker {
- *   async onUIMessage(message: UIMessage) {
- *     // handle messages from the UI panel
- *   }
- * }
- *
- * new MyPlugin().start();
- * ```
- */
-export abstract class PluginWorker {
-  protected pluginId!: string
-  private hostAPI: Comlink.Remote<Record<string, unknown>>
-
-  constructor() {
-    this.hostAPI = Comlink.wrap<Record<string, unknown>>(
-      self as unknown as Comlink.Endpoint
-    )
-  }
-
-  protected sendToUI(action: string, payload: unknown): void {
-    ;(this.hostAPI as Record<string, any>).ui.sendToUI({ action, payload })
-  }
-
-  /**
-   * Signal the host that this plugin has finished its work and should be
-   * stopped. Use this in headless (UI-less) plugins that run a task and
-   * self-terminate.
-   */
-  protected complete(): void {
-    ;(this.hostAPI as Record<string, any>).lifecycle.complete()
-  }
-
-  async init(): Promise<void> {
-    console.log(this.pluginId, "init() called")
-    console.log(this.pluginId, "Initialization complete")
-  }
-
-  async destroy(): Promise<void> {
-    console.log(this.pluginId, "destroy() called — cleaning up")
-  }
-
-  async ping(): Promise<string> {
-    return "pong"
-  }
-
-  async onUIMessage(_message: UIMessage): Promise<void> {
-    // Override in subclass to handle UI messages
-  }
-
-  /**
-   * Expose the worker API via Comlink and start listening.
-   * Call this once after constructing the plugin instance.
-   *
-   * The host calls `init(config)` with `{ pluginId }`,
-   * which is captured here to set `this.pluginId` before the
-   * subclass's `init()` runs.
-   */
-  start(): void {
-    Comlink.expose(
-      {
-        init: (config: PluginConfig) => {
-          this.pluginId = config.pluginId
-          return this.init()
-        },
-        destroy: () => this.destroy(),
-        ping: () => this.ping(),
-        onUIMessage: (message: UIMessage) => this.onUIMessage(message),
-      },
-      self as unknown as Comlink.Endpoint
-    )
-    console.log("Worker loaded, API exposed via Comlink")
-  }
-}

package/src/rpc-proxy.ts

@@ -1,56 +0,0 @@
-import type {
-  PluginApiCallPayload,
-  PluginApiMethod,
-} from "@snaptrude/plugin-core"
-import { getHostApi } from "./host-api"
-
-/**
- * Build a namespace object whose nested property access maps to a
- * dot-separated host RPC method path, and whose every call dispatches that
- * path through the host bridge.
- *
- * The host exposes the entire plugin API behind a single generic `call()`
- * (see the host `bridge.ts`), and the method string is exactly the property
- * path — so one Proxy replaces every hand-written per-method RPC wrapper for
- * every namespace (`core.*`, `design.*`, `entity.*`):
- *
- * The POSITIONAL transport forwards the whole argument tuple; the host router
- * spreads it back into the resolved method (`fn(...args)`):
- *
- * ```ts
- * snaptrude.core.math.vec3.new(1, 2, 3)
- *   // → getHostApi().call({ method: "core.math.vec3.new", args: [1, 2, 3] })
- * ```
- *
- * Typed at the call site, e.g. `createRpcNamespace<PluginEntityApi>("entity")`.
- * The Proxy is structurally cast to the abstract API type — argument and
- * return types are enforced by that type, while dispatch is dynamic.
- *
- * Every namespace uses this — including `core.math.*` and `core.geom.*`: under
- * the all-handle model there is no in-worker compute; math and geometry are
- * host calls like everything else.
- */
-export function createRpcNamespace<T extends object>(basePath: string): T {
-  const build = (path: string): unknown =>
-    new Proxy(NOOP, {
-      get(_target, prop) {
-        // Symbols and `then` must not resolve to a callable proxy, otherwise
-        // the namespace would look thenable and break Promise resolution if it
-        // ever reached an `await`.
-        if (typeof prop !== "string" || prop === "then") return undefined
-        return build(`${path}.${prop}`)
-      },
-      apply(_target, _thisArg, argArray: unknown[]) {
-        const payload = {
-          method: path,
-          args: argArray,
-        } as unknown as PluginApiCallPayload<PluginApiMethod>
-        return getHostApi().call(payload)
-      },
-    })
-
-  return build(basePath) as T
-}
-
-/** Proxy target must be callable for the `apply` trap; identity is irrelevant. */
-const NOOP = (): void => {}