@snaptrude/plugin-core 0.9.16 → 0.9.18-edgesetbacks-20261021.1

package/CHANGELOG.md

@@ -1,402 +1,408 @@
-# @snaptrude/plugin-core
-
-## 0.9.16
-
-### Patch Changes
-
-- e8d4ec3: Add camera pose and navigation APIs to `core.camera` (`getPose`, `setPose`, `move`, `rotate`, `getNavigationSettings`, `updateNavigationSettings`) and a new `presentation.walkthroughs` namespace for camera paths: create from keyframes, floor points or camera-move presets; edit walkthroughs and their keyframes; `sample`, `listIssues` and `capture` them; play them with `start`/`stop`/`getState`; and `export` them as a video onto the Present canvas as a job (`getJob`, `cancelJob`, `listJobs`).
-
-## 0.9.15
-
-### Patch Changes
-
-- 4bfe118: `core.layers`: the layers in the Layers panel in the left sidebar. `list()`, `get(layerId)` and `getActive()` read the active design option's layers (default first, with `objectCount`); `create(name)` adds a layer to the active option (undoable, not activated); `rename(layerId, name)` renames (not undoable, default layer refused); `update(layerId, { locked?, hidden? })` locks and hides per-user (undoable; other option keys are rejected); `setActive(layerId)` sets where new objects land; `delete(layerId, { deleteObjects: true } | { targetLayerId })` deletes with an explicit disposition (server-validated; refused for the default, last, locked or shared layer; treat as permanent); `assign(componentIds, layerId)` moves objects onto a layer (undoable, locked objects skipped). Layer ids are the ids `core.proposals` records list as `bucketIds` / `defaultBucketId` (the proposals docs now point there).
-
-  MOVED (compatible at runtime): the former `core.layers` (each storey's sketch surfaces and imported underlays, ids `ly_*`) is now `core.storeys.layers`, with the same methods (`list`, `get`, `getActive`, `setActive`, `update`) and signatures. Plugins that still call the old shape on `core.layers` (`list(storeyId)`, `getActive(storeyId)`, `get` / `setActive` / `update(layerId, hidden)` with a `ly_*` id) keep working: the host routes those calls to `core.storeys.layers`. They are deprecated; new code should call `snaptrude.core.storeys.layers.*` directly. Only the TypeScript names change: `PluginCoreLayersApi` -> `PluginCoreStoreysLayersApi`, `PluginCoreLayer` -> `PluginCoreStoreyLayer`, `PluginCoreLayerType` -> `PluginCoreStoreyLayerType`, and `PluginCoreLayers*Args` / `PluginCoreLayers*Result` -> `PluginCoreStoreysLayers*Args` / `PluginCoreStoreysLayers*Result`; the names `PluginCoreLayersApi`, `PluginCoreLayer` and `PluginCoreLayers*` now describe the Layers panel.
-
-- 80c1a2b: `presentation.camera`: the Present-mode canvas camera. `capture()` screenshots what the Present canvas currently shows (the visible area at the current pan and zoom, as a base64 data URL with its pixel size); `get()` reads pan, zoom, the visible page rectangle and the sheet on screen; `set({ x?, y?, zoom? })` pans and zooms; `zoomToFit()` frames every sheet; `zoomTo(shapeId)` frames one sheet or placed shape. View-state only (not write-gated, not undoable); requires Present mode to be open.
-- 0e3df96: Raked and gabled walls: `design.create.walls` takes a trailing `topProfiles` argument and `design.create.wallRuns` items a `topProfiles` field — one optional `PluginWallTopProfile` per centerline curve (`[{ along, height }, …]`, `along` 0→1, at least two points). The wall is built as a real Wall with the given top edge (two points = single slope, three = gable), mitred at run corners, in the same single undo entry; it is non-parametric (the parametric wall graph does not rebuild it), like a wall whose top edge was dragged by hand.
-- d84ea44: `design.update.setObjectType(components, objectType)`: convert masses into real walls, roofs, slabs or floors (`objectType` uses the `design.query` `type` vocabulary: `"wall" | "roof" | "slab" | "floor"`) — the properties panel's Object Type dropdown, headless, keeping the geometry exactly as built (no flattening to a default thickness) and keeping the component's handle. Instance families convert together. One undoable operation.
-
-## 0.9.14
-
-### Patch Changes
-
-- 22c919b: Curved-geometry contracts — spline curves, primitive solids, curved-surface reads, and the shared mass-parameter record.
-  - **`spline` handle kind** — `SplineHandle` joins `CurveHandle` (`line | arc | spline`), so every `core.geom.query.curve` member and `profileFromCurves` take a spline, and joins `ArenaKind`, so `core.handles.release`, `releaseAll("spline")` and `endScope`'s `retain` list accept one. Closed spline loops never exist as a single handle: a closed run is authored directly as a profile.
-  - **`core.geom.create.splineFromPoints`** — an open NURBS curve passing exactly THROUGH 3..256 ordered points (interpolated, not control points).
-  - **`core.geom.create.profileFromSplinePoints`** — the closed counterpart: a smooth closed profile through the points, ready for `contourFromProfile` → extrude/loft/sweep. No mixed straight/spline input in v1 — compose those with `profileFromCurves`.
-  - **Primitive solids** — `brepFromSphere`, `brepFromCylinder`, `brepFromCone` (optional `topRadius`, default 0 = apex) and `brepFromTorus`. Positional plain `{x, y, z}` args matching the `brepFromRevolution` family; `base` is the bottom-cap centre for cylinder/cone, `centre` for sphere/torus. Each result carries an exact analytic surface and a creation recipe.
-  - **`core.geom.create.brepFromSweep`** — `options.transition` gains `"round"` beside `"miter"` and `{ bevel }`: corners carried around a tangent circular arc, so the corner patch is a real curved surface.
-  - **`core.geom.create.brepFromRevolution`** — JSDoc rewritten to the implemented gate: segments may run at any angle to the axis (an incline revolves into a cone, an arc into a sphere or torus section). Two rules, checked in this order: the axis must lie in the profile's plane or run parallel to it (a parallel axis offset from the plane is judged by its projection into the plane, as 0.9.13 built it; a skew axis is `PRECONDITION_FAILED`), then the whole profile must stay on one side of the axis — touching it is legal (dome poles, cylinder inner edges), crossing it is not (`VALIDATION`).
-  - **`core.geom.query.brep.getEdgeCurve`** — a fourth `"spline"` variant (`degree`, `controlPoints`, expanded `knots`, endpoints, `length`), so reading back a spline edge no longer throws.
-  - **`core.geom.query.brep.getVolume`** — exact enclosed volume integrated from the surfaces, free of tessellation error.
-  - **`core.geom.query.face.getSurfaceKind`** — `"plane" | "cylinder" | "cone" | "sphere" | "torus" | "spline" | null`: the one read that tells a real curved face from a faceted approximation of one.
-  - **`core.geom.query.curve`** — class JSDoc gains the per-member spline support table; unsupported members refuse with `PRECONDITION_FAILED` rather than answering wrongly.
-  - **`design.query.getParameters`** — read a mass's creation-parameter record (`kind` + values, world coordinates), or `null` for geometry with no honest recipe.
-  - **`massParameters`** (new module, exported from the package root) — `MassParametersRecord` / `ContourRecord` / `ProfileRecord` / `CurveRecord` / `XYZ` types and Zod schemas, shared verbatim by plugin-core, the host and the agent runtime. Pure JSON, one `{x, y, z}` point shape, array bounds as contract (through-points ≤ 256, spline poles ≤ 512, sweep path ≤ 512, loft sections ≤ 32, profile curves ≤ 256, contour holes ≤ 64).
-
-  Editing what was made, and rounding it:
-  - **`design.update.parameters(component, patch)`** — the write pair of `design.query.getParameters`: patch a parametric mass's creation recipe and the solid rebuilds in place, keeping its id, storey, materials, position and linked copies. `patch` is a partial of the record's `values` (keys you omit are unchanged; each key you send replaces that value whole — a scalar, a point, a list or a record (`contour`, `profile`, `sections`, `path`, `options`, `operations`) alike — so send the complete value you read) or the whole record read back and edited; `kind` and `version` are immutable; the reply is the complete post-edit record in world coordinates. `PRECONDITION_FAILED` when the component is not a mass (a family instance: use `design.family.setParameters`), when the mass carries no live recipe, when it was scaled (undo the scale and call again), when it or a linked copy is locked (unlock them — the recipe is intact, and `getParameters` cannot see the lock), when a recorded operation's selectors no longer resolve, or when the edit is the first twist or taper, or the straightening, of an extrusion that carries a shell, fillet or chamfer (the faces renumber: send the twist keys with `operations: []` first, then re-apply), `VALIDATION` for argument errors, `OPERATION_FAILED` for a kernel refusal that leaves the model unchanged.
-  - **`core.geom.create.splineFromControlPoints(controlPoints, { degree? })`** — an open NURBS curve DEFINED BY 3..512 control points (pulled toward, not through, the interior ones), degree 2 or 3, clamped uniform knots computed host-side. It is the write pair of a `splinePoles` curve record, so a curve read back off a mass can have its poles moved and be rebuilt.
-  - **`brepFromFillet` / `brepFromChamfer` / `brepFromShell` / `brepFromOffset` accept CURVED solids.** The straight-edges-only and no-shared-vertex rules are gone: edges may be straight, circular or spline, and adjacent edges (corner blends) are allowed. The JSDoc carries the rim-selection recipe — `brep.listEdges` → `edge.listFaces` → `face.getSurfaceKind` on both faces (`listEdgesBetween` takes two VERTEX indices and is not a face-pair lookup) — and the new refusals: `VALIDATION` where there is no crease (a seam, or two patches of one smooth surface), and — for `brepFromFillet` alone, the one operation with a per-edge kernel verdict — `PRECONDITION_FAILED` naming the edge the kernel could not blend. An over-size chamfer, shell or offset is `OPERATION_FAILED` with a hint asking for a smaller distance/thickness and no edge or face named. Selection caps are RECORD caps, not call caps: the wire schemas accept any selection size, exactly as 0.9.x did — a fillet/chamfer of more than 64 edges or a shell opening more than 32 faces still builds, but the result carries no parameter record (the recipe-less fallback).
-  - **`MassParametersRecord` gains an optional `operations` list** (`version` stays 1) — a fillet, chamfer, shell or offset of a recorded solid keeps the record, with `kind` still the base constructor and the operation appended. `OperationRecord`, `EdgeSelector`, `FaceSelector`, `TopologyCounts`, `SurfaceKind`, `CurveKind`, `ParameterPatchValue` and `MassParametersPatch` join the module, with caps `MAX_OPERATIONS` 8, `MAX_OPERATION_EDGES` 64, `MAX_OPERATION_FACES` 32. Selectors are TOPOLOGICAL (edge index + its face pair + curve kind; face index + surface kind + edge count) so they survive a scalar edit of the base and trip on a reorder.
-  - **`design.query.geometry.getBrep`** — additive `options.frame` (`"local"` default, unchanged 0.9.x behaviour; `"world"` places the solid where it sits in the scene, for booleans between scene masses and for fillet/shell/offset/chamfer results committed back beside their source).
-
-  Freeform surfaces, sweeps, patches and variable blends:
-  - **`core.geom.create.brepFromSweepAlongCurve(profile, path, options?)`** — sweeps a cross-section along a SMOOTH path of 1..64 curves (splines, arcs and lines chained end to end), where `brepFromSweep` takes a polyline. `options.orientation` picks how the profile turns: `"upright"` (default) keeps its up aligned with world up, `"frenet"` rolls it with the curvature, `"fixed"` carries the authored frame along unchanged — which is a pure translation, and so is also how a footprint is bent along an arc. `options.rail`, a second guide curve, carries the profile along a second path; a closed rail, or a rail together with `orientation`, is `VALIDATION`, and a railed sweep records nothing (`getParameters` answers `null`). Otherwise it records as the one new kind `sweepAlongCurve` (`{ profile, path: CurveRecord[], options? }`, `version` still 1), so the orientation stays editable through `design.update.parameters`; the shipped `sweep` kind and its `XYZ[]` path are untouched.
-  - **`core.geom.create.brepFromPatch(boundary, thickness, options?)`** — stretches a surface across a closed loop of 3..16 boundary items and thickens it into a SOLID in one call: a roof over four curves, a canopy between two rails, a blend across a gap. A boundary item is a curve or an `OwnedEdge` (`{ edge, brep, face? }` — an edge handle cannot name its own solid, and one patch may meet two of them). `options.continuity: "tangent"` leaves the named face smoothly and then REQUIRES `face` on every item, because a solid edge lies between two faces and only the caller knows which one to continue; `interiorPoints` (≤ 64) pull the surface through them, and `side` picks which way the solid grows. There is no sheet handle and no surface object: only solids reach the canvas. The result carries no recipe — `design.query.getParameters` is `null` and the mass label is its provenance.
-  - **`core.geom.create.brepsFromSplitByFace(brep, toolFace, toolBrep)`** — the curved twin of `brepsFromSplit`, which cuts with a plane: cuts a solid with a FACE of another solid and returns the pieces largest first. Both breps must be in the same frame — read scene masses with `getBrep(x, { frame: "world" })`. A cut that does not pass all the way through is a `VALIDATION`, not a silent single piece.
-  - **`core.geom.create.curvesFromProjection(curve, face, faceBrep)`** — drops a curve onto a face along its normal and returns the runs that land on it, one curve per connected run, or `[]` when the curve misses the face; `VALIDATION` when the curve's midpoint lies on the face's surface (no drop direction).
-  - **`core.geom.query.face.getArea(face, brep)` / `.getCentroid(face, brep)`** — exact area (internal units squared) and centre of area of one face, integrated off its surface rather than its facets. These are the two reads that tell freeform faces apart, where every face answers `"spline"` and a kind census returns nothing. Both take the parent brep, owner last, exactly like `listVertexPositions(face, brep)`.
-  - **`brepFromLoft`** gains `options.smoothing` — `"ruled"` (default) is today's straight-sided loft byte for byte; `"smooth"` lofts every section in ONE pass, so the sides curve continuously through the intermediates. `LoftOptions` carries it into the record.
-  - **`brepFromExtrusion`** gains a trailing `options?: { twistInDegrees?, topScale?, levels? }`, and the shipped `extrusion` record gains the same three optional values (`version` still 1) — a twisted or tapered tower stays the SAME kind, so "twist this tower" is an edit rather than a delete-and-rebuild. `twistInDegrees` is an angle and `topScale` a ratio: neither is ever converted by a unit factor. `levels` is a count (each step may turn at most 22.5°), resolved at create time and written into the record, so an existing mass regenerates from the record and never from a heuristic that may change under it. All three absent is the straight extrusion, byte for byte.
-  - **`brepFromFillet`** gains a trailing `options?: { endRadius?, radii? }` — a VARIABLE blend. `endRadius` interpolates linearly from `radius` along the whole tangent chain the one edge you pass belongs to (an open chain: on a closed rim a law whose two ends differ is refused, for `endRadius` and `radii` alike). `radii` is the sampled form instead: 2..32 rows of `{ position, radius }` with `position` the normalised ARC LENGTH along that contour from the passed edge's start — a ratio, never converted — strictly increasing. Either form takes exactly ONE edge, they are mutually exclusive, and both round-trip on the fillet `OperationRecord`.
-  - **Face and edge selectors gain `at?`** — where the face or edge sits inside its solid, its centroid (an edge's midpoint) over the solid's bounding-box extent, a ratio per axis. It is written only when index, kind and counts cannot tell two of them apart, which on a freeform solid is the common case, and it is verified — never searched — on replay, so a record written without it resolves byte-identically.
-  - **`ParameterPatchValue`** widens with `SweepAlongCurveRecordOptions` and `CurveRecord[]` (the `sweepAlongCurve` path). It only ever widens; every value it took before it still takes.
-  - **`massParameters.ops` — a second record module.** `EdgeSelector`, `FaceSelector`, `TopologyCounts`, `OperationRecord`, `ParameterPatchValue` and the operation caps (plus the new `MAX_FILLET_LAW_SAMPLES` 32) move into `src/massParameters.ops.ts` and are re-exported from `massParameters` and from the package root — no import path changes. The split keeps each module small enough for an agent to read whole. New caps beside the shipped ones: `MAX_PATH_CURVES` 64, `MAX_TWIST_LEVELS` 64, and — on the creator, because a patch has no record — `MAX_PATCH_BOUNDARY_CURVES` 16 and `MAX_PATCH_INTERIOR_POINTS` 64.
-  - **`design.family.getParameters`** gains an optional `parts: PluginFamilyPart[]` — each placed part's `name`, the `engine` that built it (`"kernel"` for a curved sketch built exactly, `"mesh"` otherwise) and, on kernel parts, a read-only part-local `brep` for the face-kind census. `design.query.geometry.getBrep` keeps returning `null` for a family.
-
-## 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.8
-
-### 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.
-
-## 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
+# @snaptrude/plugin-core
+
+## 0.9.17
+
+### Patch Changes
+
+- d63e597: Add a `presentation.sections` namespace for section lines: `list`, `get`, `create` (from two plan points), `update`, `delete`, open or close a section view with `getActive` / `setActive`, and `getCut`, which reports every element a section's cutting plane passes through, with the cut's area, outline length and extent on the plane. Unknown-id reads return `null`; unknown-id writes and `getCut` throw `HANDLE_INVALID`.
+
+## 0.9.16
+
+### Patch Changes
+
+- e8d4ec3: Add camera pose and navigation APIs to `core.camera` (`getPose`, `setPose`, `move`, `rotate`, `getNavigationSettings`, `updateNavigationSettings`) and a new `presentation.walkthroughs` namespace for camera paths: create from keyframes, floor points or camera-move presets; edit walkthroughs and their keyframes; `sample`, `listIssues` and `capture` them; play them with `start`/`stop`/`getState`; and `export` them as a video onto the Present canvas as a job (`getJob`, `cancelJob`, `listJobs`).
+
+## 0.9.15
+
+### Patch Changes
+
+- 4bfe118: `core.layers`: the layers in the Layers panel in the left sidebar. `list()`, `get(layerId)` and `getActive()` read the active design option's layers (default first, with `objectCount`); `create(name)` adds a layer to the active option (undoable, not activated); `rename(layerId, name)` renames (not undoable, default layer refused); `update(layerId, { locked?, hidden? })` locks and hides per-user (undoable; other option keys are rejected); `setActive(layerId)` sets where new objects land; `delete(layerId, { deleteObjects: true } | { targetLayerId })` deletes with an explicit disposition (server-validated; refused for the default, last, locked or shared layer; treat as permanent); `assign(componentIds, layerId)` moves objects onto a layer (undoable, locked objects skipped). Layer ids are the ids `core.proposals` records list as `bucketIds` / `defaultBucketId` (the proposals docs now point there).
+
+  MOVED (compatible at runtime): the former `core.layers` (each storey's sketch surfaces and imported underlays, ids `ly_*`) is now `core.storeys.layers`, with the same methods (`list`, `get`, `getActive`, `setActive`, `update`) and signatures. Plugins that still call the old shape on `core.layers` (`list(storeyId)`, `getActive(storeyId)`, `get` / `setActive` / `update(layerId, hidden)` with a `ly_*` id) keep working: the host routes those calls to `core.storeys.layers`. They are deprecated; new code should call `snaptrude.core.storeys.layers.*` directly. Only the TypeScript names change: `PluginCoreLayersApi` -> `PluginCoreStoreysLayersApi`, `PluginCoreLayer` -> `PluginCoreStoreyLayer`, `PluginCoreLayerType` -> `PluginCoreStoreyLayerType`, and `PluginCoreLayers*Args` / `PluginCoreLayers*Result` -> `PluginCoreStoreysLayers*Args` / `PluginCoreStoreysLayers*Result`; the names `PluginCoreLayersApi`, `PluginCoreLayer` and `PluginCoreLayers*` now describe the Layers panel.
+
+- 80c1a2b: `presentation.camera`: the Present-mode canvas camera. `capture()` screenshots what the Present canvas currently shows (the visible area at the current pan and zoom, as a base64 data URL with its pixel size); `get()` reads pan, zoom, the visible page rectangle and the sheet on screen; `set({ x?, y?, zoom? })` pans and zooms; `zoomToFit()` frames every sheet; `zoomTo(shapeId)` frames one sheet or placed shape. View-state only (not write-gated, not undoable); requires Present mode to be open.
+- 0e3df96: Raked and gabled walls: `design.create.walls` takes a trailing `topProfiles` argument and `design.create.wallRuns` items a `topProfiles` field — one optional `PluginWallTopProfile` per centerline curve (`[{ along, height }, …]`, `along` 0→1, at least two points). The wall is built as a real Wall with the given top edge (two points = single slope, three = gable), mitred at run corners, in the same single undo entry; it is non-parametric (the parametric wall graph does not rebuild it), like a wall whose top edge was dragged by hand.
+- d84ea44: `design.update.setObjectType(components, objectType)`: convert masses into real walls, roofs, slabs or floors (`objectType` uses the `design.query` `type` vocabulary: `"wall" | "roof" | "slab" | "floor"`) — the properties panel's Object Type dropdown, headless, keeping the geometry exactly as built (no flattening to a default thickness) and keeping the component's handle. Instance families convert together. One undoable operation.
+
+## 0.9.14
+
+### Patch Changes
+
+- 22c919b: Curved-geometry contracts — spline curves, primitive solids, curved-surface reads, and the shared mass-parameter record.
+  - **`spline` handle kind** — `SplineHandle` joins `CurveHandle` (`line | arc | spline`), so every `core.geom.query.curve` member and `profileFromCurves` take a spline, and joins `ArenaKind`, so `core.handles.release`, `releaseAll("spline")` and `endScope`'s `retain` list accept one. Closed spline loops never exist as a single handle: a closed run is authored directly as a profile.
+  - **`core.geom.create.splineFromPoints`** — an open NURBS curve passing exactly THROUGH 3..256 ordered points (interpolated, not control points).
+  - **`core.geom.create.profileFromSplinePoints`** — the closed counterpart: a smooth closed profile through the points, ready for `contourFromProfile` → extrude/loft/sweep. No mixed straight/spline input in v1 — compose those with `profileFromCurves`.
+  - **Primitive solids** — `brepFromSphere`, `brepFromCylinder`, `brepFromCone` (optional `topRadius`, default 0 = apex) and `brepFromTorus`. Positional plain `{x, y, z}` args matching the `brepFromRevolution` family; `base` is the bottom-cap centre for cylinder/cone, `centre` for sphere/torus. Each result carries an exact analytic surface and a creation recipe.
+  - **`core.geom.create.brepFromSweep`** — `options.transition` gains `"round"` beside `"miter"` and `{ bevel }`: corners carried around a tangent circular arc, so the corner patch is a real curved surface.
+  - **`core.geom.create.brepFromRevolution`** — JSDoc rewritten to the implemented gate: segments may run at any angle to the axis (an incline revolves into a cone, an arc into a sphere or torus section). Two rules, checked in this order: the axis must lie in the profile's plane or run parallel to it (a parallel axis offset from the plane is judged by its projection into the plane, as 0.9.13 built it; a skew axis is `PRECONDITION_FAILED`), then the whole profile must stay on one side of the axis — touching it is legal (dome poles, cylinder inner edges), crossing it is not (`VALIDATION`).
+  - **`core.geom.query.brep.getEdgeCurve`** — a fourth `"spline"` variant (`degree`, `controlPoints`, expanded `knots`, endpoints, `length`), so reading back a spline edge no longer throws.
+  - **`core.geom.query.brep.getVolume`** — exact enclosed volume integrated from the surfaces, free of tessellation error.
+  - **`core.geom.query.face.getSurfaceKind`** — `"plane" | "cylinder" | "cone" | "sphere" | "torus" | "spline" | null`: the one read that tells a real curved face from a faceted approximation of one.
+  - **`core.geom.query.curve`** — class JSDoc gains the per-member spline support table; unsupported members refuse with `PRECONDITION_FAILED` rather than answering wrongly.
+  - **`design.query.getParameters`** — read a mass's creation-parameter record (`kind` + values, world coordinates), or `null` for geometry with no honest recipe.
+  - **`massParameters`** (new module, exported from the package root) — `MassParametersRecord` / `ContourRecord` / `ProfileRecord` / `CurveRecord` / `XYZ` types and Zod schemas, shared verbatim by plugin-core, the host and the agent runtime. Pure JSON, one `{x, y, z}` point shape, array bounds as contract (through-points ≤ 256, spline poles ≤ 512, sweep path ≤ 512, loft sections ≤ 32, profile curves ≤ 256, contour holes ≤ 64).
+
+  Editing what was made, and rounding it:
+  - **`design.update.parameters(component, patch)`** — the write pair of `design.query.getParameters`: patch a parametric mass's creation recipe and the solid rebuilds in place, keeping its id, storey, materials, position and linked copies. `patch` is a partial of the record's `values` (keys you omit are unchanged; each key you send replaces that value whole — a scalar, a point, a list or a record (`contour`, `profile`, `sections`, `path`, `options`, `operations`) alike — so send the complete value you read) or the whole record read back and edited; `kind` and `version` are immutable; the reply is the complete post-edit record in world coordinates. `PRECONDITION_FAILED` when the component is not a mass (a family instance: use `design.family.setParameters`), when the mass carries no live recipe, when it was scaled (undo the scale and call again), when it or a linked copy is locked (unlock them — the recipe is intact, and `getParameters` cannot see the lock), when a recorded operation's selectors no longer resolve, or when the edit is the first twist or taper, or the straightening, of an extrusion that carries a shell, fillet or chamfer (the faces renumber: send the twist keys with `operations: []` first, then re-apply), `VALIDATION` for argument errors, `OPERATION_FAILED` for a kernel refusal that leaves the model unchanged.
+  - **`core.geom.create.splineFromControlPoints(controlPoints, { degree? })`** — an open NURBS curve DEFINED BY 3..512 control points (pulled toward, not through, the interior ones), degree 2 or 3, clamped uniform knots computed host-side. It is the write pair of a `splinePoles` curve record, so a curve read back off a mass can have its poles moved and be rebuilt.
+  - **`brepFromFillet` / `brepFromChamfer` / `brepFromShell` / `brepFromOffset` accept CURVED solids.** The straight-edges-only and no-shared-vertex rules are gone: edges may be straight, circular or spline, and adjacent edges (corner blends) are allowed. The JSDoc carries the rim-selection recipe — `brep.listEdges` → `edge.listFaces` → `face.getSurfaceKind` on both faces (`listEdgesBetween` takes two VERTEX indices and is not a face-pair lookup) — and the new refusals: `VALIDATION` where there is no crease (a seam, or two patches of one smooth surface), and — for `brepFromFillet` alone, the one operation with a per-edge kernel verdict — `PRECONDITION_FAILED` naming the edge the kernel could not blend. An over-size chamfer, shell or offset is `OPERATION_FAILED` with a hint asking for a smaller distance/thickness and no edge or face named. Selection caps are RECORD caps, not call caps: the wire schemas accept any selection size, exactly as 0.9.x did — a fillet/chamfer of more than 64 edges or a shell opening more than 32 faces still builds, but the result carries no parameter record (the recipe-less fallback).
+  - **`MassParametersRecord` gains an optional `operations` list** (`version` stays 1) — a fillet, chamfer, shell or offset of a recorded solid keeps the record, with `kind` still the base constructor and the operation appended. `OperationRecord`, `EdgeSelector`, `FaceSelector`, `TopologyCounts`, `SurfaceKind`, `CurveKind`, `ParameterPatchValue` and `MassParametersPatch` join the module, with caps `MAX_OPERATIONS` 8, `MAX_OPERATION_EDGES` 64, `MAX_OPERATION_FACES` 32. Selectors are TOPOLOGICAL (edge index + its face pair + curve kind; face index + surface kind + edge count) so they survive a scalar edit of the base and trip on a reorder.
+  - **`design.query.geometry.getBrep`** — additive `options.frame` (`"local"` default, unchanged 0.9.x behaviour; `"world"` places the solid where it sits in the scene, for booleans between scene masses and for fillet/shell/offset/chamfer results committed back beside their source).
+
+  Freeform surfaces, sweeps, patches and variable blends:
+  - **`core.geom.create.brepFromSweepAlongCurve(profile, path, options?)`** — sweeps a cross-section along a SMOOTH path of 1..64 curves (splines, arcs and lines chained end to end), where `brepFromSweep` takes a polyline. `options.orientation` picks how the profile turns: `"upright"` (default) keeps its up aligned with world up, `"frenet"` rolls it with the curvature, `"fixed"` carries the authored frame along unchanged — which is a pure translation, and so is also how a footprint is bent along an arc. `options.rail`, a second guide curve, carries the profile along a second path; a closed rail, or a rail together with `orientation`, is `VALIDATION`, and a railed sweep records nothing (`getParameters` answers `null`). Otherwise it records as the one new kind `sweepAlongCurve` (`{ profile, path: CurveRecord[], options? }`, `version` still 1), so the orientation stays editable through `design.update.parameters`; the shipped `sweep` kind and its `XYZ[]` path are untouched.
+  - **`core.geom.create.brepFromPatch(boundary, thickness, options?)`** — stretches a surface across a closed loop of 3..16 boundary items and thickens it into a SOLID in one call: a roof over four curves, a canopy between two rails, a blend across a gap. A boundary item is a curve or an `OwnedEdge` (`{ edge, brep, face? }` — an edge handle cannot name its own solid, and one patch may meet two of them). `options.continuity: "tangent"` leaves the named face smoothly and then REQUIRES `face` on every item, because a solid edge lies between two faces and only the caller knows which one to continue; `interiorPoints` (≤ 64) pull the surface through them, and `side` picks which way the solid grows. There is no sheet handle and no surface object: only solids reach the canvas. The result carries no recipe — `design.query.getParameters` is `null` and the mass label is its provenance.
+  - **`core.geom.create.brepsFromSplitByFace(brep, toolFace, toolBrep)`** — the curved twin of `brepsFromSplit`, which cuts with a plane: cuts a solid with a FACE of another solid and returns the pieces largest first. Both breps must be in the same frame — read scene masses with `getBrep(x, { frame: "world" })`. A cut that does not pass all the way through is a `VALIDATION`, not a silent single piece.
+  - **`core.geom.create.curvesFromProjection(curve, face, faceBrep)`** — drops a curve onto a face along its normal and returns the runs that land on it, one curve per connected run, or `[]` when the curve misses the face; `VALIDATION` when the curve's midpoint lies on the face's surface (no drop direction).
+  - **`core.geom.query.face.getArea(face, brep)` / `.getCentroid(face, brep)`** — exact area (internal units squared) and centre of area of one face, integrated off its surface rather than its facets. These are the two reads that tell freeform faces apart, where every face answers `"spline"` and a kind census returns nothing. Both take the parent brep, owner last, exactly like `listVertexPositions(face, brep)`.
+  - **`brepFromLoft`** gains `options.smoothing` — `"ruled"` (default) is today's straight-sided loft byte for byte; `"smooth"` lofts every section in ONE pass, so the sides curve continuously through the intermediates. `LoftOptions` carries it into the record.
+  - **`brepFromExtrusion`** gains a trailing `options?: { twistInDegrees?, topScale?, levels? }`, and the shipped `extrusion` record gains the same three optional values (`version` still 1) — a twisted or tapered tower stays the SAME kind, so "twist this tower" is an edit rather than a delete-and-rebuild. `twistInDegrees` is an angle and `topScale` a ratio: neither is ever converted by a unit factor. `levels` is a count (each step may turn at most 22.5°), resolved at create time and written into the record, so an existing mass regenerates from the record and never from a heuristic that may change under it. All three absent is the straight extrusion, byte for byte.
+  - **`brepFromFillet`** gains a trailing `options?: { endRadius?, radii? }` — a VARIABLE blend. `endRadius` interpolates linearly from `radius` along the whole tangent chain the one edge you pass belongs to (an open chain: on a closed rim a law whose two ends differ is refused, for `endRadius` and `radii` alike). `radii` is the sampled form instead: 2..32 rows of `{ position, radius }` with `position` the normalised ARC LENGTH along that contour from the passed edge's start — a ratio, never converted — strictly increasing. Either form takes exactly ONE edge, they are mutually exclusive, and both round-trip on the fillet `OperationRecord`.
+  - **Face and edge selectors gain `at?`** — where the face or edge sits inside its solid, its centroid (an edge's midpoint) over the solid's bounding-box extent, a ratio per axis. It is written only when index, kind and counts cannot tell two of them apart, which on a freeform solid is the common case, and it is verified — never searched — on replay, so a record written without it resolves byte-identically.
+  - **`ParameterPatchValue`** widens with `SweepAlongCurveRecordOptions` and `CurveRecord[]` (the `sweepAlongCurve` path). It only ever widens; every value it took before it still takes.
+  - **`massParameters.ops` — a second record module.** `EdgeSelector`, `FaceSelector`, `TopologyCounts`, `OperationRecord`, `ParameterPatchValue` and the operation caps (plus the new `MAX_FILLET_LAW_SAMPLES` 32) move into `src/massParameters.ops.ts` and are re-exported from `massParameters` and from the package root — no import path changes. The split keeps each module small enough for an agent to read whole. New caps beside the shipped ones: `MAX_PATH_CURVES` 64, `MAX_TWIST_LEVELS` 64, and — on the creator, because a patch has no record — `MAX_PATCH_BOUNDARY_CURVES` 16 and `MAX_PATCH_INTERIOR_POINTS` 64.
+  - **`design.family.getParameters`** gains an optional `parts: PluginFamilyPart[]` — each placed part's `name`, the `engine` that built it (`"kernel"` for a curved sketch built exactly, `"mesh"` otherwise) and, on kernel parts, a read-only part-local `brep` for the face-kind census. `design.query.geometry.getBrep` keeps returning `null` for a family.
+
+## 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.8
+
+### 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.
+
+## 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