@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

package/AGENTS.md

@@ -0,0 +1,231 @@
+# Plugin Core — Agent Guide
+
+This package is the **single source of truth** for all Snaptrude plugin API definitions.
+Every change here has downstream ripple effects. Follow the checklist below **before
+considering your work done**.
+
+## What this package contains
+
+- Abstract API classes (`src/api/`) — define method signatures, JSDoc, and Zod schemas
+- Shared types (`src/types.ts`) — `ComponentId`, `PluginApiReturn<T>`, etc.
+- Host utilities (`src/host-utils.ts`) — `PluginApiMethodMap`, `PluginApiMethod`, RPC payload types
+
+## Transport model — Handle vs value
+
+Every plugin API argument and return value crosses the worker↔host RPC boundary by one
+of exactly **two transports**. Choose the transport per type **before** writing the
+signature — it is a contract decision, not an implementation detail. Authoritative design
+record: [`PLUGIN_HANDLE_MIGRATION_HLD.md`](../../PLUGIN_HANDLE_MIGRATION_HLD.md) §2–§6.
+Handle types + Zod schemas live in `src/handles.ts`.
+
+### The decision rule (Handle or value)
+
+> **Is the type a JS primitive (`number` / `string` / `boolean`) or a string enum?**
+> **Yes → value. No (any structured type) → handle.** No third option: no value DTOs, no
+> `{x,y,z}`-as-input objects, no converter layer.
+
+- A `Vec3`, `Quat`, `Line`, `Arc`, `Curve`, `Circle`, `Profile`, `Contour`, a BREP
+  topology object, or any scene entity is **structured → always a handle** — even a vec3,
+  which is "just three numbers". We never send its components across as an input object.
+- A distance in mm, a boolean flag, a count, a `"round" | "square"` enum → **value**.
+- **Reads are the one exception:** a read returns a bare **primitive record** (e.g.
+  `{ x, y, z }`) by value. That is not a value transport for a structured *type*; it is the
+  irreducible read leaf. A read must never mint a handle per call (§3).
+
+### Value transport — rules
+
+- Primitives and enums only. No object arg may stand in for a structured type.
+- Validated for **shape** at the router (`validateRPCCall`); numbers use Zod `.finite()`
+  wherever a schema exists. Trusted for shape only — never for identity or existence.
+- Stateless: no arena, no registry, no lifecycle, no `dispose`.
+
+### Handle transport — rules
+
+A handle is an opaque, kind-tagged string `"<kind>_<token>"` (`Handle<K>`), engine-free
+and structured-clone-safe. The three method shapes:
+
+- **Construction** — primitives in → handle out, async: `vec3.new({x,y,z}): Promise<Vec3Handle>`.
+- **Operations** — handles in → handle out, async (every op is a host round-trip):
+  `vec3.add({a,b}): Promise<Vec3Handle>`.
+- **Reads** — handle in → **primitive record out** (never a handle, never a DTO):
+  `vec3.components({v}): Promise<{x,y,z}>`.
+
+Crossing/security rules:
+
+- **Validation**: `handleSchema(kind)` checks only the `"<kind>_"` prefix at the trust
+  boundary; existence + kind + ownership are enforced host-side on resolve, and any miss
+  throws one `HANDLE_INVALID` (anti-oracle). Never resolve a handle in plugin-core.
+- **Host wiring**: add a `register*`/`resolve*` pair in `plugins/handles/valueResolvers.ts`
+  (the one handle↔object converter) for value/resource handles. Entity handles are **not**
+  registered — they resolve live via the scene index. Reads build the record inline
+  (`{ x: v.x, y: v.y, z: v.z }`), never via a converter.
+
+#### Handle classes — pick by lifecycle
+
+All three are handles; they differ only in storage + lifecycle. Choose per backing object:
+
+| Class        | Kinds                                                                              | Token shape                              | Storage                                                    | Lifecycle                                                        |
+| ------------ | ---------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------- |
+| **Value**    | `vec3`, `quat`, `line`, `arc`, `curve`, `circle`                                   | `<kind>_<token>`                         | value arena (quota 100k)                                   | immutable; freed on plugin teardown; **not** deduped            |
+| **Resource** | `profile`, `contour`, `brep`, `face`, `edge`, `halfedge`, `vertex`                 | `<kind>_<token>`                         | resource arena (quota 10k)                                 | session-ephemeral; explicit `dispose` + teardown; dedup by identity |
+| **Entity**   | `component`/`mass`, `material`, `story`, `referenceLine`, `department`, `buildableEnvelope` | raw `Component.id` / `Material.name` (**no prefix**) | not stored — resolved live via `StructureCollection` / `getMaterialByName` | scene-owned; stable across undo/redo; persistable across sessions |
+
+- **Value vs Resource**: a lightweight immutable math/geom value with high churn → value
+  arena (big quota, no dispose obligation). A heavier engine object a plugin holds then
+  releases → resource arena (small quota, must `dispose`; deduped by object identity).
+- **Entity**: any live scene object with a stable `Component.id` → entity handle. No arena,
+  no quota, no `<kind>_` prefix — the token IS the id, so it round-trips with the ids the
+  host already hands out.
+
+## Quick commands
+
+```bash
+pnpm check-types   # typecheck (no emit)
+pnpm build          # tsup build (ESM + CJS)
+pnpm dev            # tsup watch mode
+```
+
+## Change propagation checklist
+
+Any time you add, remove, rename, or change the signature of an API method or type in
+this package, you **must** propagate changes to all downstream consumers. Use this
+checklist:
+
+### 1. Client implementation — `packages/plugin-client/`
+
+> See [`packages/plugin-client/AGENTS.md`](../../packages/plugin-client/AGENTS.md) for client-specific guidance.
+
+Every abstract method in `plugin-core` is served to plugins by `plugin-client`, but the
+client has **no per-method code**: every namespace is backed by a single generic RPC
+proxy (`createRpcNamespace` in `src/rpc-proxy.ts`). All calls — including math and
+geom — are forwarded to the host; structured values cross as opaque handles.
+
+| plugin-core source  | plugin-client counterpart                                          |
+| ------------------- | ------------------------------------------------------------------ |
+| `src/api/core/**`   | `createRpcNamespace<PluginCoreApi>("core")` in `src/api/index.ts`  |
+| `src/api/design/**` | `createRpcNamespace<PluginDesignApi>("design")` in the same file   |
+| `src/api/entity/**` | `createRpcNamespace<PluginEntityApi>("entity")` in the same file   |
+| `src/api/tools/**`  | `createRpcNamespace<PluginToolsApi>("tools")` in the same file     |
+
+- **New / removed / renamed method or signature change**: No client code change — the
+  proxy is generic and the types flow from plugin-core. Rebuild plugin-core so the
+  client picks up the new signatures.
+- **New nested API module** (e.g. a new file under `core/` or `design/`): No client change
+- **New top-level namespace**: Add a `createRpcNamespace<PluginXApi>("x")` property to
+  `ClientPluginApi` in `src/api/index.ts`
+
+### 2. Host implementation — `apps/snaptrudereact/src/app/plugins/api/`
+
+> See [`apps/snaptrudereact/src/app/plugins/AGENTS.md`](../../apps/snaptrudereact/src/app/plugins/AGENTS.md) for host-specific guidance.
+
+The host mirrors this package's `src/api/` file structure 1:1. Host classes extend the
+abstract classes from plugin-core and provide the actual Snaptrude-internal implementation.
+
+- **New method**: Implement using Snaptrude internals. Use Zod `.parse()` for input validation.
+- **Removed method**: Delete from host
+- **Renamed/signature change**: Update the host method to match
+- **New API module**: Create the host file, wire into barrel, and add to `SnaptrudePluginApi` in `api/index.ts`
+- **New structured type**: Structured types cross as opaque handles (all-handle model) — there is no DTO converter layer. Add a `register*`/`resolve*` pair in the host's `plugins/handles/valueResolvers.ts` (the one handle ↔ live-object converter); reads return primitive records built inline via `handles/readRecords.ts`.
+
+### 3. JSDoc — keep it complete
+
+All public methods and types **must** have JSDoc with:
+
+- A brief description
+- `@param` for each parameter (with type and description)
+- `@returns` description
+- `@example` where helpful (especially for entity/tools APIs)
+
+JSDoc in this package is the source of truth for the API docs site.
+
+### 4. API documentation — `apps/snaptrudereact/api-docs/`
+
+> See [`apps/snaptrudereact/api-docs/AGENTS.md`](../../apps/snaptrudereact/api-docs/AGENTS.md) for the full source-to-doc mapping and sync procedure.
+
+In summary:
+
+- **Changed method**: Update the corresponding `.md` doc page to match the new JSDoc
+- **New API module**: Create a new doc page following the template in `AGENTS.md`, and add it to `.vitepress/sidebar.mts`
+- **Removed API module**: Delete the doc page and remove from sidebar
+
+### 5. Console tests — `apps/snaptrudereact/src/app/plugins/apiConsoleTesting/`
+
+> See [`apps/snaptrudereact/src/app/plugins/AGENTS.md`](../../apps/snaptrudereact/src/app/plugins/AGENTS.md) for test harness details.
+
+These are in-browser integration tests that exercise the plugin API end-to-end.
+
+| plugin-core API module                            | Test file                    |
+| ------------------------------------------------- | ---------------------------- |
+| `core/math/*`                                     | `tests/math.ts`              |
+| `core/geom/*` (curve/arc/profile/contour)         | `tests/geom.ts`              |
+| `core/geom/query/*` (brep/face/edge/vertex topology) | `tests/geomTopology.ts`   |
+| `core/units/*`                                    | `tests/units.ts`             |
+| `core/history/*`                                  | `tests/history.ts`           |
+| `core/zoom/*`                                     | `tests/zoom.ts`              |
+| `core/project/*`                                  | `tests/project.ts`           |
+| `core/comment/*`                                  | `tests/comment.ts`           |
+| `design/boolean/*`                                | `tests/designBoolean.ts`     |
+| `design/create/*`                                 | `tests/designCreate.ts`      |
+| `design/query/*`                                  | `tests/designQuery.ts`       |
+| `design/selection/*`                              | `tests/designSelection.ts`   |
+| `design/lock.ts`                                  | `tests/designLock.ts`        |
+| `design/delete/*`                                 | `tests/delete.ts`            |
+| `design/erase/*`                                  | `tests/erase.ts`             |
+| `design/doors/*`                                  | `tests/doors.ts`             |
+| `design/windows/*`                                | `tests/windows.ts`           |
+| `design/furniture/*`                              | `tests/furniture.ts`         |
+| `design/materials/*`                              | `tests/materials.ts`         |
+| `entity/space.ts`                                 | `tests/spaces.ts`            |
+| `entity/story.ts`                                 | `tests/story.ts`             |
+| `entity/referenceLine.ts`                         | `tests/referenceLines.ts`    |
+| `entity/department.ts`                            | `tests/departments.ts`       |
+| `entity/buildableEnvelope.ts`                     | `tests/buildableEnvelope.ts` |
+| `program/metadata.ts`                             | `tests/programMetadata.ts`   |
+| `program/labels.ts`                               | `tests/programLabels.ts`     |
+| `program/spreadsheet.ts` (custom sheets)          | `tests/spreadsheetCustomSheets.ts` |
+| `core/tags.ts` (`listForComponents`)              | `tests/tagsBulk.ts`          |
+| `tools/selection.ts`                              | `tests/selection.ts`         |
+| `tools/transform.ts`                              | `tests/transform.ts`         |
+| `tools/copy.ts`                                   | `tests/copy.ts`              |
+| `tools/offset.ts`                                 | `tests/offset.ts`            |
+
+- **New method**: Add test cases covering the new method
+- **Removed method**: Remove corresponding tests
+- **Signature change**: Update test calls to match new signature
+- **New API module**: Create a new test file under `tests/` and import it in `tests/index.ts`
+
+### 6. Host-side Jest unit tests
+
+Some host implementations have co-located `.test.ts` files:
+
+- `api/core/math/vec3.test.ts`, `quat.test.ts`
+
+If your change affects pure math logic, update the corresponding Jest tests.
+
+### 7. Downstream consumers (breaking changes only)
+
+If your change is **breaking** (removed method, renamed method, changed required args),
+check **all** consumers of `@snaptrude/plugin-client` or `@snaptrude/plugin-core`:
+
+- Internal plugins under `plugins/`
+- Example plugins under `examples/` — these are consumer-facing templates used by
+  `create-snaptrude-plugin`, so they must compile and demonstrate correct API usage
+
+Search these directories for usage of the changed API and update accordingly.
+
+## Adding a new API namespace (end-to-end)
+
+When adding an entirely new namespace (e.g. `snaptrude.materials`):
+
+1. **plugin-core**: Create abstract class + Zod schemas + types in `src/api/<namespace>/`
+2. **plugin-core**: Export from `src/api/index.ts` and add as property on `PluginApi`
+3. **plugin-core**: Verify `host-utils.ts` types auto-infer the new methods (they should via `ExtractMethodPaths`)
+4. **plugin-client**: Only if it's a new **top-level** namespace, add a
+   `createRpcNamespace<PluginXApi>("x")` property to `ClientPluginApi` in
+   `src/api/index.ts` (nested namespaces need no client change)
+5. **host**: Create host implementation in `apps/snaptrudereact/src/app/plugins/api/<namespace>/`
+6. **host**: Add to `SnaptrudePluginApi` class in `api/index.ts`
+7. **docs**: Create doc pages, update sidebar, follow [`apps/snaptrudereact/api-docs/AGENTS.md`](../../apps/snaptrudereact/api-docs/AGENTS.md) template
+8. **tests**: Add console test file + Jest tests for pure logic
+9. **examples**: Update example plugins if they should showcase the new namespace
+10. **build**: Run `pnpm check-types` in plugin-core, plugin-client, and snaptrudereact

package/CHANGELOG.md

@@ -0,0 +1,341 @@
+# @snaptrude/plugin-core
+
+## 0.0.0-bimsvg-20260928124803
+
+### Minor Changes
+
+- 95fbff4: Add first-class drawing contracts, reusable view presets, drawing placement on sheets, and drawing-parented annotations.
+
+## 0.9.13
+
+### Patch Changes
+
+- 6c85137: design.family: add `delete({ id, instances? })` — archives the library row; `instances: true` also deletes this project's placed instances undoably. `create` result gains `placed` and `hint`.
+
+## 0.9.12
+
+### Patch Changes
+
+- 6e4a055: added param comps
+- 8e37e1f: `design.family`: `prepare` and `flex` warnings gain the `proportion` code — parts thinner than 0.5 mm, parts or a family larger than 50 m, a family smaller than 10 mm, each naming the parts — and `flex` now returns `warnings`.
+- 2a06dd9: `design.family`: `prepare`, `flex` and `getParameters` accept a `snapshot` option and return a `snapshot` block — an isolated offscreen picture of the family (iso, front, right, top tiles with a dimension line) as a PNG data URL, so an agent can look at what it built before reporting.
+
+## 0.9.11
+
+### Patch Changes
+
+- 7fd374e: Add `hinge` to `design.create.door` / `window` (in `options`), `doors[]` / `windows[]` items and `opening`: a world point near the jamb the leaf is hinged on; the placed item is reflected along the wall when the catalog item's authored hinge side would land on the other jamb — one undo entry, no extra command.
+
+  **BEHAVIOUR FIX — `facing`.** The host placed the swing on the side OPPOSITE the `facing` point (the interactive tool's cursor convention) while the contract said "the room it opens into". The host now matches the contract: the leaf swings open toward `facing`. Callers that passed a point on the room side get the documented result; nothing in the contract changed shape.
+
+  `design.doors.getSwingDirection` is now derived from the placed mesh's orientation (hand as seen standing on the swing side facing the door); it previously read a scaling sign that placement never sets and reported `"left"` for every door. `mirror` axis docs now say what each axis does to a door (`'x'` swing side, `'z'` hinged jamb, `'y'` upside down); behaviour unchanged.
+
+- 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.
+
+## 0.9.10
+
+### Patch Changes
+
+- `core.mode.set("program")` now opens the Program tab (the same path as the top bar's Program button) instead of refusing with `PRECONDITION_FAILED`; it resolves once the tab has connected, and waits for the user to confirm the editor's pop-up modal when the browser blocks the window.
+- `workspace.openProgramMode()` / `closeProgramMode()` — the Program-tab counterpart of `openPresentMode` / `closePresentMode`: open (awaiting the tab's connection) and close the paired Program window.
+
+## 0.9.9
+
+### Patch Changes
+
+- Program-mode additions requested by the healthcare programming pilot (all additive; no signature changes):
+  - `program.metadata` — the Program Data sheet's custom columns and per-space values: `listHeaders`, `createHeader` (reuse-by-name), `get`, `list`, `update`, `updateMany`. Writes are undoable and work with the Program tab closed.
+  - `program.labels` — the program rows (space types) with targets: `list`, `get`, `create` (optionally `createSpaces`), `setTargetArea`, `setTargetCount`. Covers "target area of non-departments": a space inherits its label's target; departments keep `program.departments.setTargetArea`.
+  - `program.spreadsheet` — custom program sheets with a group-by hierarchy: `createCustomSheet`, `updateCustomSheet`, `getCustomSheet`, `listCustomSheets`, `listCustomSheetProperties`.
+  - `core.tags.listForComponents(componentIds?)` — every space's tags + colors in one round-trip.
+  - `program.departments` — `targetCount` on the department record and `setTargetCount(departmentId, targetCount)`, the count twin of `setTargetArea` (the engine stores both on the department, like on labels).
+
+## 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`.
+
+## 0.9.6
+
+### Patch Changes
+
+- Add five APIs the plugin agent repeatedly reached for but that did not exist.
+  - `core.project.getInfo()` — project id, display name, unit type, storey count (scoped to the active building), active storey, and site location in one call. Closes a genuine capability gap: nothing previously returned the current project's identity.
+  - `core.storeys.getActive()` — `setActive` had no getter, unlike `core.buildings`, `core.layers` and `core.proposals`.
+  - `core.camera.getMode()` — `setMode` had no getter, while `getProjection`/`setProjection` on the same class were paired.
+  - `design.visibility.show(components)` — `hide` previously had only `showAll` as its inverse, so specific components could not be revealed.
+  - `design.furniture.listCatalogGroups()` — matches `design.doors` and `design.windows`, so all three catalog surfaces are named alike. `design.furniture.listCategories()` is deprecated but still supported.
+
+## 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.
+
+## 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".
+
+## 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).
+
+## 0.9.1
+
+### Patch Changes
+
+- Plugin API 0.9.1 — strictly additive: the terrain mesh lane and the Present-mode styling/canvas lane. No signatures changed, no behavior of existing methods changed; deployed plugins are unaffected (`versionGate` compares major.minor only).
+  - **`core.io.terrain.replaceMesh(positions, indices, units?, options?)`** — replace the site terrain surface with a caller-supplied triangle mesh. World-space flat arrays (the `getTriangulatedMeshes` frame, so read-modify-write round-trips); `units: "meters"` converts on the way in. Validated before any engine call (finiteness, index bounds, degenerate topology, scene-bound extents, **500k vertex/triangle caps** — the surface's first explicit payload ceiling); a predominantly down-facing mesh is auto-flipped with a warning. Datum, geolocation, opacity, lock state and the elevation/satellite toggles survive; the map texture is re-projected best-effort; cut/fill history resets by contract. One undo step restores the prior surface exactly (buffers, UVs, submesh layout, cut/fill data, volumes). The replacement **persists with the project**: the mesh uploads to bucket storage and reload applies it instead of the heightmap build. The optional `options` mirrors the requester's contract: `coordinateSpace`, `expectedTerrain` (session optimistic check), `expectedModelRevision` (session terrain-mesh revision, returned as `modelRevision` in the result), `baseline: "make-replacement-original"`, `preserve` opt-outs (`datum`/`satellite`/`material` have real opt-out behavior; `geolocation: false` rejects — always preserved), and `clientMutationId` (session-scoped idempotent replay). For projects without terrain, compose `core.io.import.terrain` + `replaceMesh` (a separate `createFromMesh` was deliberately not added).
+  - **`presentation.placedViews` — per-instance styling** (`getStyles` / `updateStyles` / `resetStyles` / `updateFontStyles`): the Present sidebar's full per-category styling surface — 7 line dash styles, line color, dash-length multiplier, **cut vs projection line weights in mm** (plus tree/parking weights), fills (`department`/`texture`/`monochrome`/`tag:<tagCategoryId>`), per-category opacity, category hide (cascades to labels), view-style restyles (block/rounded/bubble with radius + inset), Topography map/building sub-controls, and Text-tab typography per label type (font family incl. Google Fonts, weight, italic, px size, visible label types). Writes are host-validated (typed VALIDATION with the supported-setting list), land as **one undo step per call**, re-render immediately, and fan out across an auto-diagram sheet's set. `getStyles` returns fully-resolved values plus each category's supported setting ids.
+  - **`presentation.placedViews` — labels** (`listLabels` / `moveLabel` / `setLabelHidden`): a placed view's generated labels (space names, departments, areas, dimensions) as addressable shapes — read text/category/position, reposition them, hide/show individually (independent of category-level hides).
+  - **`presentation.placedViews` — generic canvas shapes** (`listShapes` / `getShape` / `moveShape` / `resizeShape` / `deleteShapes` / `setOpacity` / `setMask`): every top-level Present-canvas shape — AI-generated outputs, placed diagram images, plugin shapes, annotations — addressable by id with an `origin` classification. Previously `aiInspiration.generate` and `diagrams.place` returned shape ids nothing could act on. `deleteShapes` is atomic (any rejected id deletes nothing), protects sheets (use `sheets.delete`) and user-drawn annotations, and closes the placed-view no-delete gap. `setOpacity` is the whole-shape slider; `setMask` toggles context-building masking on views.
+  - **`presentation.sheets.setMargin(sheetId, margin)`** — set a sheet's print margin to one of the canonical unit-agnostic presets `0 | 0.25 | 0.5 | 0.75 | 1` (displayed None / 1/4″ / 1/2″ / 3/4″ / 1″ on imperial projects, None / 5mm / 10mm / 15mm / 20mm on metric) — the sheet header's margin dropdown; one undo step. Sheet reads (`list`/`get`) now report `margin` (`null` when absent/unrecognized).
+  - **`presentation.placedViews.setRotation(shapeId, rotation)`** — set a placed view's **absolute** rotation in radians (tldraw convention) about its bounds center (the UI rotation handle's pivot); one undo step. Angles are canonicalized into `[0, 2π)`, so the round-trip with the record's `rotation` read is exact only in that range (`setRotation(-0.1)` reads back `2π − 0.1`). **3D placed views only** — 2D/site-plan views cannot rotate (the canvas reverts any rotation applied to them) and are refused with a typed `PRECONDITION_FAILED`. Joins the absolute-setter family (`setScale`/`setCrop`/`setOpacity`/`setMask`).
+  - **`presentation.placedViews.rotateShape(shapeId, rotation)`** — the same absolute center-pivot rotation for any top-level Present-canvas shape (AI outputs, diagram images, plugin shapes, annotations — placed views too); targets and refusals mirror `moveShape`. Same `[0, 2π)` canonicalization (exact round-trip only in that range), and a placed view passed here falls under the same 3D-only rule — 2D/site-plan views refuse with a typed `PRECONDITION_FAILED`.
+  - **`presentation.tables.place(sheetId, { rows }, options?)`** — new `tables` namespace: place plain string rows as a table shape on a sheet (the same shape the Present canvas creates when a Program-mode / Google Sheets / Excel table is pasted). Rows may be ragged, capped at 10000 cells total; `options.position` is sheet-local like `annotate.*` (default: the paste flow's viewport-center auto-placement); returns the created shape as a canvas-shape record; one undo step.
+  - **`presentation.slideshow`** (`start` / `stop` / `getState`) — new namespace: run the Present-mode slideshow programmatically. The slideshow plays **all** sheets in order; `start` options only pick the opening slide (`startIndex` wins over a single-entry `sheetIds`, clamped into range). Browsers grant fullscreen only on a user gesture, so a plugin-triggered `start` typically runs **non-fullscreen** (the rejection is caught). `start`/`stop` are write-gated; `getState` is a never-throw read (`running` + current `index`, `null` when not running). No `next`/`prev`/`goTo` — slide navigation stays with the user.
+  - **`workspace.openPresentMode()` / `closePresentMode()`** — open/close the Present-mode documentation editor. `openPresentMode` resolves only once the Present canvas has mounted (up to ~15s, then a typed `PRECONDITION_FAILED`), so follow-up `presentation.*` calls find Present mode open; both are idempotent and **write-gated** (a mode switch under the user's feet is approval-controlled by design). Overlaps `core.mode.set("present")`/`set("design")` but adds the mount-await + idempotency contract.
+  - **`presentation.diagrams.generateSite(options?)`** — run the site-diagram auto-generation (location / streetview / climate sheets from the map terrain) and return the created `sheetIds`. `options.types` selects a subset (default all three); generation is tracked per-proposal — already-generated types are **skipped, not duplicated** (mount-time-flow semantics; existing site-diagram sheets are never replaced), so `sheetIds` can be empty. Requires Present mode and a map terrain.
+  - **`presentation.annotate.text` typography** — the existing text args gain optional `fontFamily` (system family or any Google Font, loaded automatically — the Present text panel's loader), `fontWeight` (numeric string like `"400"`/`"700"`, `-italic` suffix allowed; unavailable weights fall back to regular), and `fontSizePx` (exact pixel size overriding the `size` preset — `size` alone keeps working). Existing calls are unaffected.
+  - **`program.site.listEdges()`** — read each site parcel's boundary edges with their **front / side / rear** classification: the exact resolution the buildable-envelope setback pills show on canvas (user per-edge overrides win over the tangent heuristic; `roleSource` says which applied), so a plugin picks up the user's edge tagging without asking them to set it up again. Per edge: canonical `edgeIndex` (the envelope `edgeOverrides` index space), endpoints and length in **world meters** (`lengthUnit: "m"` — unlike `listPolygons`' Snaptrude-unit footprints), and the **effective base setback** (per-edge exception, else the role value; `null` for parcels with no zoning envelope — those still classify by heuristic). Entries also report the linked `buildableEnvelopeId` and whether stale index-misaligned overrides were dropped. Never throws; `"street"` resolves to `front`.
+
+## 0.9.0
+
+### Minor Changes
+
+- Plugin API 0.9.0 — namespace reorganization (deprecate-in-place, nothing breaks), the analysis wave, and the spreadsheet data lane.
+  - **Namespace map** — `entity.*` retired via aliases (storeys → `core.storeys`, reference lines / buildable envelopes → `design.*`), `core.zoom` → `core.camera`, `core.tags.getTagsForComponent` → `core.tags.listForComponent`, new `workspace.*` (projects/teams) and `core.mode` top-levels. Every deprecated path still works and delegates to its canonical implementation.
+  - **Analysis wave** — `analysis.weather.getSeries` (hourly EPW rows + station metadata + quality flags), `analysis.solar.sampleGrid` (per-point GPU-raytraced visibility/shade/SVF/irradiance), `analysis.daylight.compute` (LM-83 numeric ASE + sDA with full provenance — see the sDA entry below), `program.site.getWeather`/`getTimezone`, `.epw` import + project weather override via `core.io.import`.
+  - **sDA (LM-83 Spatial Daylight Autonomy)** — `analysis.daylight` now computes real sDA300/50% with dynamic blind operation (LM-83 2% rule, 5% diffuse closed-blind default) via Radiance. Runs including `"sDA"` are asynchronous: `compute` returns `{ status: "running", runId }` and the new `analysis.daylight.poll({ runId, cursor? })` fetches results; ASE-only runs stay synchronous and unchanged. New optional `optics` arg overrides surface optics per material (keyed by Snaptrude material name) 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`, results gain `runId`, and the ASE fields (`directSunHoursAtOrAbove1000Lux`/`aseFail`/`asePercent`) are now optional — present when ASE is requested.
+  - **Heatmaps** — named overlays (up to 16, `analysis.heatmaps.overlays.*`), `renderField` arbitrary cell geometry, `renderSurfaceGrid` façade grids, discrete/threshold/categorical scales, hover tooltips.
+  - **Geometry reads** — `design.query.geometry.getTriangulatedMeshes` (world-space triangles, optional per-triangle `materialIds` and B-rep `faceIds`), `design.query.spaces.getEnclosure` (geometric v1).
+  - **Spreadsheet data lane** — `program.spreadsheet.datasets.{set, list}` (plugin datasets, upsert + auto-refresh of bound ranges), binding `source` widened to `{ dataset: "takeoff" } | { dataset: "plugin", name }` (takeoff unchanged), `addImage` (data-URI floating pictures, stable-name replace-on-rerun), `addChart` accepts the ratified `"column"`/`"bar"` enum on the wire.
+  - **Presentation** — `presentation.shapes` keyed shape lifecycle on Present sheets (`upsert`/`remove`/`removeAll`/`list`).
+  - **Constructive geometry (brep kernel)** — the full `core.geom.create.brepFrom*` constructor family minting `BrepHandle`s at authored coordinates: `brepFromFaces` (plain face-point loops; host validates welding, planarity, edge coherence and fixes global orientation), `brepFromExtrusion` (prisms along any direction, holes + arc profiles), `brepFromLoft` (tapered solids between two contours; lofts producing non-planar side faces are rejected), `brepFromMesh` (indexed vertex + face-index input), and the OpenCascade booleans `brepFromUnion` / `brepFromSubtraction` (`a` minus `b`) / `brepFromIntersection` (scene-derived `getBrep` handles accepted as read-only inputs; empty/disjoint results throw typed VALIDATION).
+  - **`design.create.massFromBrep(brep, label?)`** — commit a mass from any `core.geom.create` brep constructor's handle (scene-derived breps stay read-only): generic mass at authored coordinates, single undo step, collab-synced.
+  - **`presentation.placedViews`** — layout control over placed views (`list`/`get`/`move`/`scale`/`setScale`/`setCrop`): sheet-local position, size, architectural scale, rotation, crop and link state; uniform corner-drag-equivalent `scale`, Scale-dropdown `setScale` (2D only), native crop fractions with page-anchored visible region — crop survives `sheets.updatePlacedView` refreshes.
+
+## 0.8.0
+
+### Minor Changes
+
+- More additions to the APIs, infra changes.
+- Plugin API 0.8.0 — the 0.8 API wave, handle lifecycle, events, and geometry/data-integrity fixes.
+  - **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, plus completeness widenings across existing families. The discovery manifest grows from 423 to 595 method paths (including the new `core.handles.*` lifecycle below).
+  - **Events** — `model:changed` subscription contract: debounced model-change notifications delivered to the plugin worker for user and plugin edits alike (client API: `PluginWorker.subscribe`). `selection:changed`, `tool:activated`, `project:saved`, `view:changed` are reserved names, not yet emitted.
+  - **BREAKING — `program.site` footprints are world Snaptrude units.** Previously the only plan-geometry read scaled to scene metres (×0.254), so site parcels could not be overlaid on `planPoints`. Now the same world XZ plan space as every other plan read; areas and the geographic reads are unchanged.
+  - **BREAKING — real beam/column geometry.** `design.create.beam` with a horizontal direction (the documented canonical call) used to build a zero-height flat sheet; it now builds a true beam with tool-parity semantics (section X extent = width, Z extent = depth, body hangs below the authoring plane by its depth). `design.create.column` builds exactly the requested height (the silent slab-thickness deduction is gone). Degenerate extrusions (zero/diagonal/in-plane directions, zero height) throw VALIDATION errors instead of silently building corrupt solids; directions are normalized.
+  - **Data integrity** — `design.query.list*` no longer returns engine-internal shells (originals parked by instance copies, disposed phantoms), so one copy no longer doubles `listSpaces`/schedules; `design.delete.entities` orders instance copies before their source meshes so mixed batches cannot fail midway; `design.update.wall` documents that rebuilds replace the wall — re-bind from `affected[0]`.
+  - **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.
+
+## 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.
+
+## 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.
+
+## 0.6.0
+
+### Minor Changes
+
+- 934405e: New `analysis.heatmaps` family — render plugin-computed scalar data as a
+  heatmap: `renderSpaces` (flat colour per space top face), `renderGrid`
+  (coloured grid mesh from world-coordinate samples), `reset`, `isActive`.
+  Single active heatmap (a render replaces the previous one); values outside
+  `[min, max]` clamp to the end colours; ephemeral (auto-cleared on
+  scene-mutating edits, never persisted). The react host has landed, so all
+  members are required `abstract` and in the discovery manifest.
+- 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.
+- New `core.io` namespace — file import, import jobs, and underlay/terrain
+  management:
+  - `core.io.import` — bring external files onto a storey: `image`, `pdf`
+    (page-selectable), `dwg`, `cadJson` (parsed CAD geometry as a sketch),
+    `model` (3D formats), and `terrain` (map snapshot at a lat/lng with
+    optional elevation). Slow formats return an `ImportJobHandle` instead of
+    blocking.
+  - `core.io.job` — poll those imports: `getStatus`, `isComplete`, `getResult`,
+    `getError`.
+  - `core.io.query` — pre-import inspection: `getPdfPageCount`,
+    `listCadLayers`.
+  - `core.io.underlay` — manage imported image/PDF/CAD underlays: `list`,
+    `getBounds`, `getScale`/`setScale`/`resetScale`, `getOpacity`/`setOpacity`,
+    `delete`.
+  - `core.io.terrain` — manage the imported map terrain: `exists`, `get`,
+    `getDatum` (current vertical position, world Y) / `setDatum` (relative
+    datum shift, not an absolute elevation), `delete`, `getReport`, elevation and satellite-imagery toggles
+    (`isElevationEnabled`/`enableElevation`/`disableElevation`,
+    `isSatelliteEnabled`/`enableSatellite`/`disableSatellite`), and
+    `getOpacity`/`setOpacity`.
+
+- New `design.selection.setByFilter(filter)` — the programmatic equivalent of
+  the editor's **Story selection** and **Filter selection** menus. Replaces the
+  selection with every visible entity of the active building matching
+  `{ storeys?: number[], types?: PluginSelectionEntityType[] }` (fields AND,
+  values within a field OR; at least one field required — use `clear()` to
+  deselect). The new `PluginSelectionEntityType` vocabulary covers all 24 menu
+  kinds, including selection-only kinds the query surface can't reach (sites,
+  terrain, CAD/PDF/image imports, dimension lines, 3D models, neighborhood
+  buildings, program blocks). One-shot bulk select, not a persistent mode; not
+  undoable, like the other selection mutators.
+
+## 0.5.0
+
+### Minor Changes
+
+- 7750aa3: Exposed more snaptrude APIs
+
+## 0.4.0
+
+The Plugin API expose initiative. Pre-1.0, breaking changes ship as minor
+version bumps.
+
+### Minor Changes
+
+- **Breaking — positional arguments.** Every API method now takes positional
+  parameters, options-last (required first, then one optional `options`
+  object), replacing the single-args-object transport. Migrate by unwrapping
+  the object into positional args — `foo({ a, b, t })` → `foo(a, b, t)`. E.g.
+  `vec3.lerp(a, b, 0.5)`, `departments.assign(departmentId, spaceIds)`,
+  `design.query.spaces.get(space, ["area", "position"])`.
+- **Breaking — handle-based boundary.** Only JS primitives and enum strings
+  cross the plugin ↔ host boundary by value. Every structured type (vector,
+  curve, profile, BREP topology, scene entity) is now an opaque, kind-tagged
+  string handle; scene-entity references use `ComponentHandle`. Migrate by
+  minting a handle instead of passing a raw object (`vec3.new(x, y, z)`, then
+  pass the handle) and reading values back with a query call
+  (`vec3.components(h)` → `{ x, y, z }`) — reads return primitive records,
+  never handles.
+- **New namespaces.** Reorganized the surface into `core`, `design`, `entity`,
+  `program`, and `presentation`:
+  - `core`: `math` (`vec3`/`quat`), the `geom` geometry kernel, `history`
+    (undo/redo), `units`, `zoom`, `project`, `comment`, and the
+    `groups`/`buildings`/`layers`/`tags` organization families.
+  - `design`: `create`, `query` (+ `geom` query), `selection`, `doors`,
+    `windows`, `furniture`, `materials`, `boolean`, `erase`, `delete`,
+    `transform`, `edit`, `update`, plus top-level `lock`/`unlock`/`isLocked`/
+    `listLocked` verbs.
+  - `entity`: `story`, `referenceLine`, `buildableEnvelope`.
+  - `program`: `areas`, `departments`, `metrics`, `site`, `cores`,
+    `classification`, `adjacency`, and the `spreadsheet` reporting family.
+  - `presentation`: `views`, `sheets`, `diagrams`, `import`.
+- Removed the legacy `entity.space.*` methods from the contract and
+  consolidated departments under `program.departments`. The selective space
+  property read is now `design.query.spaces.get`, and space adjacency is read
+  as an entity property via `design.query.getProperties().adjacency`. (The
+  host keeps a deprecated `entity.space.get` shim, but it is no longer part of
+  the published contract surface.)
+- Added the `overlaps` entity filter to `design.query` list methods — matches
+  entities whose plan footprint has non-zero intersection area with a given
+  space's bottom-face footprint (fully-inside, boundary-nested, and overhanging
+  all match; edge-touching does not; holes respected). Hidden entities are
+  excluded unless `isHidden` is passed explicitly.
+- Removed the never-shipped `computeAdjacencyMatrix`; renamed
+  `buildings.duplicate` → `buildings.copy`; folded `tags.createAndAssign` into
+  `tags.assign` (resolve-or-create, one atomic undo).
+
+## 0.2.8
+
+### Patch Changes
+
+- 445e0b8: Add Present-mode AI Inspiration plugin APIs under `snaptrude.documentation.aiInspiration`.
+
+## 0.2.7
+
+### Patch Changes
+
+- c5afd9a: added adjacecny
+
+## 0.2.6
+
+### Patch Changes
+
+- c17d287: Add bulk space APIs: `space.bulkCreate`, `space.bulkUpdate`, and `space.bulkDelete`. Each batches its work into a single undo/redo step. All items are validated up front and the call throws if any item is invalid (nothing is applied), consistent with the single-item space methods. `bulkCreate` supports `spaceType`/`massType`/`departmentId` per item and returns `{ spaceIds }`; `bulkUpdate` takes geometry (`profile`+`extrudeHeight`) and/or nested `properties` per item and returns `{ spaces }` (one echoed result per item, like `update`); `bulkDelete` returns `{ deletedSpaceIds }`.
+- 0683194: bulk apis
+
+## 0.2.5
+
+### Patch Changes
+
+- Restore declaration files in published plugin packages.
+
+## 0.2.4
+
+### Patch Changes
+
+- Add inner profile hole support to space creation from profiles.
+
+## 0.2.3
+
+### Patch Changes
+
+- 647466b: fixed merge issues
+
+## 0.2.2
+
+### Patch Changes
+
+- 064777a: buildable envelope apis
+
+## 0.2.1
+
+### Patch Changes
+
+- 3b37f4a: added buildable envelop api
+
+## 0.2.0
+
+### Minor Changes
+
+- 4d959a4: Exposed new offset and copy APIs for tools

package/CLAUDE.md

@@ -0,0 +1,11 @@
+# CLAUDE.md
+
+> **All coding standards, checks, and guidance live in [`AGENTS.md`](AGENTS.md).**
+> `CLAUDE.md` is a pointer only — add all new rules, patterns, and instructions to `AGENTS.md`.
+
+See [AGENTS.md](AGENTS.md) for:
+
+- What this package contains and quick commands
+- **Change propagation checklist** — the mandatory downstream sync steps for any API change
+- File mappings to plugin-client, host implementation, docs, and tests
+- End-to-end guide for adding a new API namespace