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

package/AGENTS.md

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