@snaptrude/plugin-core 0.8.0 → 0.9.0

package/src/api/design/query/geometry/index.ts

@@ -18,6 +18,9 @@ import {
  * {@linkcode ContourHandle} for its footprint outline;
  * {@linkcode PluginDesignQueryGeometryApi.getCenterline} mints a
  * {@linkcode CurveHandle} for a wall's core curve.
+ * {@linkcode PluginDesignQueryGeometryApi.getTriangulatedMeshes} is the
+ * handle-free exception: it returns the triangulated render meshes as plain
+ * world-space arrays.
  *
  * Returned handles are session-ephemeral and go stale on undo/redo/re-topologize
  * — re-fetch a fresh one after edits.
@@ -48,7 +51,7 @@ export abstract class PluginDesignQueryGeometryApi {
    * ```
    */
   public abstract getBrep(
-    component: ComponentHandle
+    component: ComponentHandle,
   ): PluginApiReturn<BrepHandle | null>
 
   /**
@@ -80,7 +83,7 @@ export abstract class PluginDesignQueryGeometryApi {
    * ```
    */
   public abstract getBottomContour(
-    component: ComponentHandle
+    component: ComponentHandle,
   ): PluginApiReturn<ContourHandle | null>
 
   /**
@@ -116,8 +119,67 @@ export abstract class PluginDesignQueryGeometryApi {
    * ```
    */
   public abstract getCenterline(
-    component: ComponentHandle
+    component: ComponentHandle,
   ): PluginApiReturn<CurveHandle | null>
+
+  /**
+   * Get the **triangulated render meshes** of scene components as plain,
+   * serializable arrays — flat world-space vertex `positions` (`[x0, y0, z0,
+   * x1, …]`) and triangle `indices` (three per triangle), one record per
+   * requested component.
+   *
+   * Unlike the other `geometry.*` reads this does NOT mint kernel handles — the
+   * raw arrays cross the boundary directly, ready for export, custom analysis,
+   * or feeding an external renderer. Positions are **always world-space**
+   * (instance/transform baked in; there is no local-coordinates mode) in plan
+   * units — no conversion needed. Raw doubles, unrounded.
+   *
+   * With `includeMaterialIds: true` each record also carries `materialIds`: one
+   * entry **per triangle** (`indices.length / 3` entries), the material *name*
+   * painted on that triangle, or `null` for unpainted/default faces.
+   *
+   * With `includeFaceIndices: true` each record also carries `faceIds`: one
+   * entry **per triangle** (input order), the B-rep face index owning that
+   * triangle (same ids as {@linkcode getBrep} faces), or `null` where there is
+   * no provenance. Non-B-rep meshes (Revit imports, generic models, furniture)
+   * yield all-`null` rather than an error.
+   *
+   * A resolvable component with no readable mesh geometry yields
+   * `{ id, positions: [], indices: [] }` — nothing is silently omitted.
+   *
+   * The call is capped at **500 000 triangles total**; over the cap it throws a
+   * `VALIDATION` error whose message includes the actual total — split the
+   * component list into smaller batches and call again.
+   *
+   * @param components - The scene components to triangulate
+   * @param options - `includeMaterialIds` adds the per-triangle material names;
+   *   `includeFaceIndices` adds the per-triangle B-rep face indices
+   * @returns `{ meshes }` — one {@linkcode PluginTriangulatedMesh} per requested
+   *   component, in input order
+   * @throws `HANDLE_INVALID` if any component handle is gone/forged;
+   *   `VALIDATION` if the combined mesh exceeds 500 000 triangles
+   *
+   * @examplePrompt Export the selected masses as a triangle mesh
+   * @examplePrompt Get the raw vertices and triangles of this wall in world coordinates
+   * @examplePrompt Give me the triangulated geometry of every space with its materials
+   * @examplePrompt Compute the surface area of this roof from its triangles
+   *
+   * @example
+   * ```ts
+   * const spaces = await snaptrude.design.query.listSpaces()
+   * const { meshes } = await snaptrude.design.query.geometry.getTriangulatedMeshes(spaces, {
+   *   includeMaterialIds: true,
+   * })
+   * for (const mesh of meshes) {
+   *   const triangleCount = mesh.indices.length / 3
+   *   console.log(mesh.id, triangleCount, mesh.materialIds?.[0])
+   * }
+   * ```
+   */
+  public abstract getTriangulatedMeshes(
+    components: ComponentHandle[],
+    options?: PluginDesignQueryGeometryGetTriangulatedMeshesArgs["options"],
+  ): PluginApiReturn<PluginDesignQueryGeometryGetTriangulatedMeshesResult>
 }
 
 /**
@@ -164,3 +226,63 @@ export const PluginDesignQueryGeometryGetCenterlineArgs = z.object({
 export type PluginDesignQueryGeometryGetCenterlineArgs = z.infer<
   typeof PluginDesignQueryGeometryGetCenterlineArgs
 >
+
+/**
+ * One component's triangulated world-space mesh, as plain serializable arrays
+ * (no handles).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The component's id (its {@linkcode ComponentHandle} token) |
+ * | `positions` | `number[]` | Flat world-space vertex coordinates `[x0, y0, z0, x1, …]`, plan units, raw doubles |
+ * | `indices` | `number[]` | Triangle vertex indices, three per triangle, into `positions / 3` |
+ * | `materialIds` | `(string \| null)[]` _(optional)_ | One entry per triangle: the painted material's name, `null` for unpainted/default faces. Present only when requested via `includeMaterialIds` |
+ * | `faceIds` | `(number \| null)[]` _(optional)_ | One entry per triangle: the B-rep face index owning it (same ids as {@linkcode PluginDesignQueryGeometryApi.getBrep} faces), `null` where there is no provenance (non-B-rep mesh). Present only when requested via `includeFaceIndices` |
+ */
+export const PluginTriangulatedMesh = z.object({
+  id: z.string(),
+  positions: z.array(z.number()),
+  indices: z.array(z.number()),
+  materialIds: z.array(z.string().nullable()).optional(),
+  faceIds: z.array(z.number().nullable()).optional(),
+})
+
+export type PluginTriangulatedMesh = z.infer<typeof PluginTriangulatedMesh>
+
+/**
+ * Arguments for {@linkcode PluginDesignQueryGeometryApi.getTriangulatedMeshes}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | The scene components to triangulate |
+ * | `options.includeMaterialIds` | `boolean` _(optional)_ | Also return the per-triangle material names |
+ * | `options.includeFaceIndices` | `boolean` _(optional)_ | Also return the per-triangle B-rep face indices |
+ */
+export const PluginDesignQueryGeometryGetTriangulatedMeshesArgs = z.object({
+  components: z.array(ComponentHandle),
+  options: z
+    .object({
+      includeMaterialIds: z.boolean().optional(),
+      includeFaceIndices: z.boolean().optional(),
+    })
+    .optional(),
+})
+
+export type PluginDesignQueryGeometryGetTriangulatedMeshesArgs = z.infer<
+  typeof PluginDesignQueryGeometryGetTriangulatedMeshesArgs
+>
+
+/**
+ * Result of {@linkcode PluginDesignQueryGeometryApi.getTriangulatedMeshes}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `meshes` | {@linkcode PluginTriangulatedMesh}`[]` | One record per requested component, in input order |
+ */
+export const PluginDesignQueryGeometryGetTriangulatedMeshesResult = z.object({
+  meshes: z.array(PluginTriangulatedMesh),
+})
+
+export type PluginDesignQueryGeometryGetTriangulatedMeshesResult = z.infer<
+  typeof PluginDesignQueryGeometryGetTriangulatedMeshesResult
+>

package/src/api/design/query/index.ts

@@ -10,6 +10,7 @@ import {
 import { PluginStaircasePreset } from "../create"
 import { PluginDesignQueryGeometryApi } from "./geometry"
 import { PluginDesignQuerySpacesApi } from "./spaces"
+import { PluginDesignQueryReferenceLinesApi } from "./referenceLines"
 
 // ---------------------------------------------------------------------------
 // Entity type vocabulary
@@ -301,6 +302,8 @@ export abstract class PluginDesignQueryApi {
   public abstract geometry: PluginDesignQueryGeometryApi
   /** Space-specific reads (footprint, …). See {@linkcode PluginDesignQuerySpacesApi}. */
   public abstract spaces: PluginDesignQuerySpacesApi
+  /** Reference-line-specific reads. See {@linkcode PluginDesignQueryReferenceLinesApi}. */
+  public abstract referenceLines: PluginDesignQueryReferenceLinesApi
 
   constructor() {}
 
@@ -1042,3 +1045,4 @@ export abstract class PluginDesignQueryApi {
 
 export * from "./geometry"
 export * from "./spaces"
+export * from "./referenceLines"

package/src/api/design/query/referenceLines.ts

@@ -0,0 +1,52 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import {
+  PluginReferenceLineGetProperty,
+  PluginReferenceLineGetResult,
+} from "../../entity/referenceLine"
+
+/**
+ * `design.query.referenceLines.*` — reference-line-specific reads.
+ *
+ * A **reference line** is a 2D guide line (or arc) in the scene, typically used
+ * for grid lines and alignment guides. Enumerate reference lines with
+ * `design.query.listReferenceLines`; read an individual line's properties here.
+ * This is the canonical home of the read formerly at `entity.referenceLine.get`
+ * (now deprecated).
+ *
+ * Accessed via `snaptrude.design.query.referenceLines`.
+ */
+export abstract class PluginDesignQueryReferenceLinesApi {
+  constructor() {}
+
+  /**
+   * Get properties of a reference line by its ID.
+   *
+   * Only the properties listed in `properties` are returned — unlisted
+   * properties will be `undefined` in the result.
+   *
+   * @param referenceLineId - The unique reference line ID
+   * @param properties - Array of property names to retrieve. See
+   *   {@linkcode PluginReferenceLineGetProperty}.
+   * @returns A partial {@linkcode PluginReferenceLineGetResult} containing only the
+   *   requested properties
+   * @throws If the reference line does not exist
+   *
+   * @examplePrompt Get the curve geometry of this reference line
+   * @examplePrompt Where does this grid line run?
+   * @examplePrompt Read the geometry of a guide line by its id
+   * @examplePrompt Look up the curve of the selected reference line
+   *
+   * # Example
+   * ```ts
+   * const [refLine] = await snaptrude.design.query.listReferenceLines()
+   * const result = await snaptrude.design.query.referenceLines.get(refLine, ["curve"])
+   * // result.curve is an opaque CurveHandle; read its coordinates via
+   * // `snaptrude.core.geom.curve`.
+   * ```
+   */
+  public abstract get(
+    referenceLineId: string,
+    properties: z.infer<typeof PluginReferenceLineGetProperty>[],
+  ): PluginApiReturn<PluginReferenceLineGetResult>
+}

package/src/api/design/query/spaces.ts

@@ -75,6 +75,55 @@ export abstract class PluginDesignQuerySpacesApi {
   public abstract getFootprint(
     space: ComponentHandle,
   ): PluginApiReturn<ContourHandle | null>
+
+  /**
+   * Get the **enclosure** of a space — the floor and ceiling that cap it, the
+   * bounding walls around it (with each wall's door/window openings), and the
+   * neighbouring spaces it shares a boundary with.
+   *
+   * **Geometric v1 — best effort.** The engine has no persisted space→surface
+   * topology, so this read is derived purely from *plan geometry*: the space
+   * footprint is matched against the plan footprints/baselines of the slabs and
+   * walls on the same storey. Consequences a caller must account for:
+   *
+   * - `faceIndices` is **always `[]`**. The triangle→B-rep-face provenance that
+   *   would populate it is a separate engine capability that does not exist yet;
+   *   read a surface's full geometry via
+   *   {@linkcode PluginDesignQueryGeometryApi.getBrep} on its `component` instead.
+   * - After heavy edits (move / stretch / boolean) or on imported models the plan
+   *   match can miss or mis-attribute a surface — treat the result as advisory,
+   *   not authoritative.
+   * - `adjacentSpaces` comes from the same adjacency data as
+   *   {@linkcode PluginProgramAdjacencyApi.getMatrix} (so the two agree on which
+   *   spaces neighbour). `sharedEdgeLength` is `0` because that data exposes no
+   *   edge length, and `sharedSurface` is the common boundary wall only when one
+   *   is found geometrically (else `null`).
+   *
+   * Read-only; never mutates the model.
+   *
+   * @param space - The space (room mass) to read
+   * @returns the {@linkcode PluginSpaceEnclosure}, or `null` when `space` is not a
+   *   space (room mass) or has no extractable plan footprint
+   *
+   * @examplePrompt What walls, floor and ceiling enclose this room?
+   * @examplePrompt Which of this room's walls are external?
+   * @examplePrompt List the doors and windows around the selected space
+   * @examplePrompt Which spaces are adjacent to this room, and through which wall?
+   *
+   * # Example
+   * ```ts
+   * const [space] = await snaptrude.design.query.listSpaces()
+   * const enclosure = await snaptrude.design.query.spaces.getEnclosure(space)
+   * if (enclosure) {
+   *   const walls = enclosure.surfaces.filter((s) => s.role === "wall")
+   *   const external = walls.filter((s) => s.isExternal)
+   *   console.log(`${walls.length} walls, ${external.length} external`)
+   * }
+   * ```
+   */
+  public abstract getEnclosure(
+    space: ComponentHandle,
+  ): PluginApiReturn<PluginSpaceEnclosure | null>
 }
 
 /**
@@ -130,3 +179,97 @@ export const PluginDesignQuerySpacesGetResult = PluginSpaceGetResult.omit({
 export type PluginDesignQuerySpacesGetResult = z.infer<
   typeof PluginDesignQuerySpacesGetResult
 >
+
+/**
+ * Arguments for {@linkcode PluginDesignQuerySpacesApi.getEnclosure}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | The space (room mass) to read |
+ */
+export const PluginDesignQuerySpacesGetEnclosureArgs = z.object({
+  space: ComponentHandle,
+})
+export type PluginDesignQuerySpacesGetEnclosureArgs = z.infer<
+  typeof PluginDesignQuerySpacesGetEnclosureArgs
+>
+
+/**
+ * The role a bounding surface plays in a {@linkcode PluginSpaceEnclosure}:
+ * `"floor"` (slab below), `"ceiling"` (slab/roof above), or `"wall"`.
+ */
+export const PluginEnclosureRole = z.enum(["floor", "ceiling", "wall"])
+export type PluginEnclosureRole = z.infer<typeof PluginEnclosureRole>
+
+/** The kind of opening hosted in a bounding wall. */
+export const PluginEnclosureOpeningKind = z.enum(["door", "window", "void"])
+export type PluginEnclosureOpeningKind = z.infer<
+  typeof PluginEnclosureOpeningKind
+>
+
+/**
+ * One opening (door / window / void) in a bounding wall.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `kind` | {@linkcode PluginEnclosureOpeningKind} | `"door"`, `"window"`, or `"void"` |
+ * | `component` | {@linkcode ComponentHandle} | The opening entity |
+ */
+export const PluginEnclosureOpening = z.object({
+  kind: PluginEnclosureOpeningKind,
+  component: ComponentHandle,
+})
+export type PluginEnclosureOpening = z.infer<typeof PluginEnclosureOpening>
+
+/**
+ * One bounding surface of a space's enclosure.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `role` | {@linkcode PluginEnclosureRole} | `"floor"`, `"ceiling"`, or `"wall"` |
+ * | `component` | {@linkcode ComponentHandle} | The wall / slab / roof entity |
+ * | `faceIndices` | `number[]` | B-rep face indices facing the space. **Always `[]` in geometric v1** (no triangle→face provenance yet) |
+ * | `isExternal` | `boolean` | No space on the other side — for a wall, no other room bounds it; for a floor/ceiling, no room caps the storey below/above |
+ * | `openings` | {@linkcode PluginEnclosureOpening}`[]` | Doors/windows/voids in the surface (walls only; `[]` for floor/ceiling in v1) |
+ */
+export const PluginEnclosureSurface = z.object({
+  role: PluginEnclosureRole,
+  component: ComponentHandle,
+  faceIndices: z.array(z.number()),
+  isExternal: z.boolean(),
+  openings: z.array(PluginEnclosureOpening),
+})
+export type PluginEnclosureSurface = z.infer<typeof PluginEnclosureSurface>
+
+/**
+ * A space that neighbours the queried space.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | The neighbouring space |
+ * | `sharedSurface` | {@linkcode ComponentHandle}` \| null` | The common boundary wall when one is found geometrically, else `null` (e.g. an open-plan or non-physical adjacency) |
+ * | `sharedEdgeLength` | `number` | Plan-unit length of the shared boundary — **always `0` in geometric v1** (the adjacency data exposes no edge length) |
+ */
+export const PluginAdjacentSpace = z.object({
+  space: ComponentHandle,
+  sharedSurface: ComponentHandle.nullable(),
+  sharedEdgeLength: z.number(),
+})
+export type PluginAdjacentSpace = z.infer<typeof PluginAdjacentSpace>
+
+/**
+ * Result of {@linkcode PluginDesignQuerySpacesApi.getEnclosure} — the geometric
+ * v1 enclosure of a space.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | The queried space |
+ * | `surfaces` | {@linkcode PluginEnclosureSurface}`[]` | Floor + ceiling + bounding walls, as a flat list (any of the three may be absent when no plan match is found) |
+ * | `adjacentSpaces` | {@linkcode PluginAdjacentSpace}`[]` | Neighbouring spaces from the adjacency data (`[]` when adjacency was never computed) |
+ */
+export const PluginSpaceEnclosure = z.object({
+  space: ComponentHandle,
+  surfaces: z.array(PluginEnclosureSurface),
+  adjacentSpaces: z.array(PluginAdjacentSpace),
+})
+export type PluginSpaceEnclosure = z.infer<typeof PluginSpaceEnclosure>

package/src/api/design/transform/index.ts

@@ -32,6 +32,9 @@ export abstract class PluginDesignTransformApi {
    * @examplePrompt Translate the furniture block by (10, 0, 5)
    * @examplePrompt Move these masses up one storey
    *
+   * @performance Array API — one host round-trip for the whole set. Pass every target in a
+   *   single call; never loop `design.transform.move` per entity.
+   *
    * # Example
    * ```ts
    * const { vec3 } = snaptrude.core.math
@@ -64,6 +67,9 @@ export abstract class PluginDesignTransformApi {
    * @examplePrompt Rotate these masses 30 degrees around the vertical axis
    * @examplePrompt Rotate these walls 90 degrees about the origin
    *
+   * @performance Array API — one host round-trip for the whole set. Pass every target in a
+   *   single call; never loop `design.transform.rotate` per entity.
+   *
    * # Example
    * ```ts
    * await snaptrude.design.transform.rotate(["space-id"], 90)
@@ -108,6 +114,9 @@ export abstract class PluginDesignTransformApi {
    * @examplePrompt Align all the walls to the left edge of this reference wall
    * @examplePrompt Snap the bottom edges of these spaces together
    *
+   * @performance Array API — one host round-trip for the whole set. Pass every target in a
+   *   single call; never loop `design.transform.align` per entity.
+   *
    * # Example
    * ```ts
    * const rooms = await snaptrude.design.selection.get()
@@ -150,6 +159,9 @@ export abstract class PluginDesignTransformApi {
    * @examplePrompt Flip the selected walls front to back
    * @examplePrompt Create a mirror image of these masses about the z axis
    *
+   * @performance Array API — one host round-trip for the whole set. Pass every target in a
+   *   single call; never loop `design.transform.mirror` per entity.
+   *
    * # Example
    * ```ts
    * const rooms = await snaptrude.design.selection.get()

package/src/api/design/update/index.ts

@@ -9,6 +9,12 @@ import {
   PluginSpaceUpdateResult,
 } from "../../entity/space"
 import { PluginDesignChangeResult } from "../lock"
+import {
+  PluginBuildableEnvelopePolygonVertex,
+  PluginBuildableEnvelopeSetbackTier,
+  PluginBuildableEnvelopeVerticalCap,
+  PluginBuildableEnvelopeUpdateResult,
+} from "../../entity/buildableEnvelope"
 
 /**
  * Sparse property updates for a space. Only provided fields change.
@@ -300,6 +306,9 @@ export abstract class PluginDesignUpdateApi {
    * @examplePrompt Move this space into the Circulation department
    * @examplePrompt Exclude this room from the area calculations
    *
+   * @performance For MORE THAN ONE space, call `design.update.spaces(items[])` — the whole
+   *   batch is one host round-trip. Looping this single-space updater is N round-trips.
+   *
    * # Example
    * ```ts
    * await snaptrude.design.update.space("space-id", { properties: { room_type: "Office" } })
@@ -330,6 +339,9 @@ export abstract class PluginDesignUpdateApi {
    * @examplePrompt Bulk-assign these spaces to the Service department
    * @examplePrompt Mark all of these rooms as excluded from area in one update
    *
+   * @performance Bulk update — the whole batch is ONE host round-trip. Prefer over looping
+   *   `design.update.space`: build the `items[]` array first, then make one call.
+   *
    * # Example
    * ```ts
    * // Re-label every selected room and mark it NET area — one undoable bulk update
@@ -649,7 +661,7 @@ export abstract class PluginDesignUpdateApi {
    * `storey` is an integer storey number in the `entity.story` convention
    * (`1` is the ground storey, `-1` the first basement; `0` does not exist)
    * and **must already exist** in each component's building — this call never
-   * creates storeys (use `entity.story.create` first). Components already on
+   * creates storeys (use `core.storeys.create` first). Components already on
    * the target storey are skipped (no-op) and are not echoed in `affected`.
    *
    * Throws when the target storey does not exist, when any component is
@@ -677,4 +689,57 @@ export abstract class PluginDesignUpdateApi {
     components: ComponentHandle[],
     storey: number,
   ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Update an existing parametric buildable envelope — regenerate the zoning
+   * volume from a revised site polygon, setbacks, vertical cap, or FAR and
+   * lot-coverage limits, keeping the same envelope id. Canonical home of the
+   * update formerly at `entity.buildableEnvelope.update` (now deprecated).
+   *
+   * @param buildableEnvelopeId - Existing envelope ID to update; non-empty and
+   *   must match an existing envelope on the canvas.
+   * @param sitePolygon - Site polygon vertices in `lengthUnit`; minimum 3 vertices.
+   * @param lengthUnit - Unit used by all length fields (`"ft" | "m"`).
+   * @param setbacks - Setback profile, ground tier first; minimum 1 tier.
+   * @param verticalCap - Maximum height or floor count.
+   * @param floorToFloor - Required floor-to-floor height in `lengthUnit`.
+   * @param farRatio - Optional FAR value, positive when provided.
+   * @param lotCoverageMaxPct - Optional lot coverage cap, `0..100`.
+   * @returns A {@linkcode PluginBuildableEnvelopeUpdateResult} with the
+   *   `buildableEnvelopeId` of the updated envelope.
+   * @throws If validation fails, the envelope does not exist, or generation
+   *   produces no renderable geometry.
+   *
+   * @examplePrompt Change the envelope's height limit to 175 feet
+   * @examplePrompt Update the setbacks on the buildable envelope
+   * @examplePrompt Regenerate the zoning envelope with a new site boundary
+   * @examplePrompt Increase the FAR on the buildable volume
+   *
+   * # Example
+   * ```ts
+   * const { buildableEnvelopeId } = await snaptrude.design.update.buildableEnvelope(
+   *   existingId,
+   *   [
+   *     { x: 0, z: 0 },
+   *     { x: 100, z: 0 },
+   *     { x: 100, z: 80 },
+   *     { x: 0, z: 80 },
+   *   ],
+   *   "ft",
+   *   [{ aboveHeight: 0, front: 10, side: 5, rear: 10 }],
+   *   { kind: "max_height", maxHeight: 175 },
+   *   12,
+   * )
+   * ```
+   */
+  public abstract buildableEnvelope(
+    buildableEnvelopeId: string,
+    sitePolygon: PluginBuildableEnvelopePolygonVertex[],
+    lengthUnit: "ft" | "m",
+    setbacks: PluginBuildableEnvelopeSetbackTier[],
+    verticalCap: PluginBuildableEnvelopeVerticalCap,
+    floorToFloor: number,
+    farRatio?: number,
+    lotCoverageMaxPct?: number,
+  ): PluginApiReturn<PluginBuildableEnvelopeUpdateResult>
 }

package/src/api/entity/buildableEnvelope.ts

@@ -54,6 +54,8 @@ export abstract class PluginBuildableEnvelopeApi {
    *   12,
    * )
    * ```
+   *
+   * @deprecated Use `design.create.buildableEnvelope`
    */
   public abstract create(
     sitePolygon: PluginBuildableEnvelopePolygonVertex[],
@@ -106,6 +108,8 @@ export abstract class PluginBuildableEnvelopeApi {
    *   12,
    * )
    * ```
+   *
+   * @deprecated Use `design.update.buildableEnvelope`
    */
   public abstract update(
     buildableEnvelopeId: string,

package/src/api/entity/referenceLine.ts

@@ -49,6 +49,8 @@ export abstract class PluginReferenceLineApi {
    *
    * const { referenceLineIds } = await snaptrude.entity.referenceLine.createMulti(profile)
    * ```
+   *
+   * @deprecated Use `design.create.referenceLines`
    */
   public abstract createMulti(
     profile: ProfileHandle
@@ -78,6 +80,8 @@ export abstract class PluginReferenceLineApi {
    * // result.curve is an opaque CurveHandle; a dedicated curve read API for its
    * // coordinates is exposed separately via `snaptrude.core.geom.curve`.
    * ```
+   *
+   * @deprecated Use `design.query.referenceLines.get`
    */
   public abstract get(
     referenceLineId: string,
@@ -104,6 +108,8 @@ export abstract class PluginReferenceLineApi {
    * const { referenceLineIds } = await snaptrude.entity.referenceLine.getAll()
    * console.log(`Project has ${referenceLineIds.length} reference lines`)
    * ```
+   *
+   * @deprecated Use `design.query.listReferenceLines`
    */
   public abstract getAll(): PluginApiReturn<PluginReferenceLineGetAllResult>
 
@@ -125,6 +131,8 @@ export abstract class PluginReferenceLineApi {
    * ```ts
    * await snaptrude.entity.referenceLine.delete("some-ref-line-id")
    * ```
+   *
+   * @deprecated Use `design.delete.entities`
    */
   public abstract delete(
     referenceLineId: string

package/src/api/entity/story.ts

@@ -41,6 +41,8 @@ export abstract class PluginStoryApi {
    * const info = await snaptrude.entity.story.get(1, ["height", "name", "spacesCount"])
    * console.log(info.name, info.height, info.spacesCount)
    * ```
+   *
+   * @deprecated Use `core.storeys.get`
    */
   public abstract get(
     storyValue: number,
@@ -68,6 +70,8 @@ export abstract class PluginStoryApi {
    *   console.log(`Story ${s.value}: ${s.name} (id: ${s.id})`)
    * }
    * ```
+   *
+   * @deprecated Use `core.storeys.list`
    */
   public abstract getAll(): PluginApiReturn<PluginStoryGetAllResult>
 
@@ -95,6 +99,8 @@ export abstract class PluginStoryApi {
    * // Create a new third floor with custom height
    * const { storyId } = await snaptrude.entity.story.create(3, 4.5)
    * ```
+   *
+   * @deprecated Use `core.storeys.create`
    */
   public abstract create(
     storyValue: number,
@@ -147,6 +153,8 @@ export abstract class PluginStoryApi {
    * // Rename only, leaving the height untouched.
    * await snaptrude.entity.story.update(1, undefined, { name: "Lobby" })
    * ```
+   *
+   * @deprecated Use `core.storeys.update`
    */
   public abstract update(
     storyValue: number,
@@ -174,6 +182,8 @@ export abstract class PluginStoryApi {
    * // Activate story 2, then draw a wall — it lands on story 2.
    * await snaptrude.entity.story.setActive(2)
    * ```
+   *
+   * @deprecated Use `core.storeys.setActive`
    */
   public abstract setActive(
     storyValue: number,
@@ -201,6 +211,8 @@ export abstract class PluginStoryApi {
    * const { newActiveStory } = await snaptrude.entity.story.delete(3)
    * console.log(`Deleted story 3; now on story ${newActiveStory}`)
    * ```
+   *
+   * @deprecated Use `core.storeys.delete`
    */
   public abstract delete(
     storyValue: number,
@@ -240,6 +252,12 @@ export abstract class PluginStoryApi {
    * @examplePrompt Repeat this level upwards with its own independent geometry
    * @examplePrompt Duplicate just the selected walls onto the next floor up
    *
+   * @performance For storeys that share a layout, duplicate the storey instead of recreating
+   *   its contents floor by floor — this copies every eligible element in one call, and the
+   *   default instanced copies keep the floors linked. To stack many identical floors, either
+   *   call this per level or capture the storey's component ids and
+   *   `design.create.copy(ids, oneFloorRise, { count })` to lay them all down in a single call.
+   *
    * # Example
    * ```ts
    * // Duplicate the whole active story one level up (instanced copies).
@@ -248,6 +266,8 @@ export abstract class PluginStoryApi {
    * console.log(`Copied ${created.length} elements onto story ${targetStories}`)
    * if (skipped) console.log(`${skipped} elements were skipped`)
    * ```
+   *
+   * @deprecated Use `core.storeys.copy`
    */
   public abstract duplicate(
     direction: "up" | "down",

package/src/api/index.ts

@@ -4,6 +4,7 @@ import { PluginEntityApi } from "./entity"
 import { PluginProgramApi } from "./program"
 import { PluginPresentationApi } from "./presentation"
 import { PluginAnalysisApi } from "./analysis"
+import { PluginWorkspaceApi } from "./workspace"
 
 /**
  * Root API surface for Snaptrude plugins.
@@ -16,6 +17,7 @@ import { PluginAnalysisApi } from "./analysis"
  * - {@linkcode PluginApi.program} — Program-mode planning reads (departments, metrics)
  * - {@linkcode PluginApi.presentation} — Presentation preparation (views, AI Inspiration)
  * - {@linkcode PluginApi.analysis} — Sustainability analysis (sunpath, shadows, sunlight/illuminance heatmaps)
+ * - {@linkcode PluginApi.workspace} — Dashboard surface: projects and teams
  */
 export abstract class PluginApi {
   /** Core math, geometry, history, and units primitives. See {@linkcode PluginCoreApi}. */
@@ -30,6 +32,8 @@ export abstract class PluginApi {
   public abstract presentation: PluginPresentationApi
   /** Sustainability analysis — sun & daylight studies. See {@linkcode PluginAnalysisApi}. */
   public abstract analysis: PluginAnalysisApi
+  /** Dashboard surface — projects and teams. See {@linkcode PluginWorkspaceApi}. */
+  public abstract workspace: PluginWorkspaceApi
 
   constructor() {}
 }
@@ -40,3 +44,4 @@ export * from "./entity"
 export * from "./program"
 export * from "./presentation"
 export * from "./analysis"
+export * from "./workspace"