@snaptrude/plugin-core 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -1,12 +1,46 @@
 # @snaptrude/plugin-core
 
+## 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.