@snaptrude/plugin-core 0.3.0 → 0.6.0

package/AGENTS.md

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

package/CHANGELOG.md

@@ -0,0 +1,163 @@
+# @snaptrude/plugin-core
+
+## 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