@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827135706

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

@@ -1,6 +1,7 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
 import {
+  BrepHandle,
   ComponentHandle,
   ContourHandle,
   ProfileHandle,
@@ -11,6 +12,12 @@ import {
   PluginMassType,
   PluginDepartmentId,
 } from "../../entity/space"
+import {
+  PluginBuildableEnvelopePolygonVertex,
+  PluginBuildableEnvelopeSetbackTier,
+  PluginBuildableEnvelopeVerticalCap,
+  PluginBuildableEnvelopeCreateResult,
+} from "../../entity/buildableEnvelope"
 
 /**
  * `design.create.*` — author new scene-committed BIM entities.
@@ -24,6 +31,13 @@ import {
  * Footprint objects take a {@linkcode ContourHandle} (outer profile + holes);
  * build one with `snaptrude.core.geom.create.contourFromProfile(s)`.
  *
+ * `door`/`window` place a catalog item into a host wall (the world point is
+ * projected onto the wall face to locate the opening; the wall is re-cut in one
+ * undo entry) and throw if the point projects outside the wall. `smartLayout` is
+ * the one creator returning a grouped {@linkcode PluginSmartLayoutResult} rather
+ * than a handle — it clones an in-scene template into one or more target spaces,
+ * merging every target into a single undo batch (see its JSDoc).
+ *
  * Accessed via `snaptrude.design.create`.
  */
 export abstract class PluginDesignCreateApi {
@@ -43,14 +57,25 @@ export abstract class PluginDesignCreateApi {
    * @param spaceType - Space-type classification (default `Room`)
    * @param massType - Mass-type classification (default `Room`)
    * @param departmentId - Department assignment (default department)
+   * @param storey - Target storey number to place the space on — the same integer
+   *   `entity.story` uses (`1` ground, `2` first floor, `-1` basement). Default:
+   *   the active storey. Folds a `core.storeys.setActive` call into the create,
+   *   placing the space at that storey's floor elevation (any `position` offset is
+   *   applied on top). Throws if no storey has that value.
    * @returns the {@linkcode ComponentHandle} of the created space
-   * @throws if the contour is invalid or the height is not positive
+   * @throws if the contour is invalid, the height is not positive, or the target
+   *   storey does not exist
    *
    * @examplePrompt Create a room called Living Room that's 3m tall from this outline
    * @examplePrompt Add a new space on the current storey using this footprint
    * @examplePrompt Make a bedroom here and assign it to the Residential department
    * @examplePrompt Extrude this closed outline into a 10 foot high room
    * @examplePrompt Can you create a Kitchen space from the sketch I just drew?
+   * @examplePrompt Create a bedroom on the second floor from this outline
+   *
+   * @performance For MORE THAN ONE space, call `design.create.spaces(items[])` — the whole
+   *   batch is one host round-trip. Looping this single-space creator is N round-trips (slow,
+   *   and a large loop can trip the plugin rate limit).
    *
    * # Example
    * ```ts
@@ -63,6 +88,10 @@ export abstract class PluginDesignCreateApi {
    * ])
    * const contour = await snaptrude.core.geom.create.contourFromProfile(outer)
    * const space = await snaptrude.design.create.space(contour, 3, "Living")
+   * // …place one directly on the second floor (no setActive dance):
+   * const upstairs = await snaptrude.design.create.space(
+   *   contour, 3, "Bedroom", undefined, undefined, undefined, undefined, 2,
+   * )
    * ```
    */
   public abstract space(
@@ -73,6 +102,7 @@ export abstract class PluginDesignCreateApi {
     spaceType?: PluginSpaceType,
     massType?: PluginMassType,
     departmentId?: PluginDepartmentId,
+    storey?: number,
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -107,6 +137,51 @@ export abstract class PluginDesignCreateApi {
     massType?: PluginMassType,
   ): PluginApiReturn<ComponentHandle>
 
+  /**
+   * Create a **mass** from a custom solid built with a `core.geom.create` brep
+   * constructor (`brepFromFaces`, `brepFromExtrusion`, `brepFromLoft`,
+   * `brepFromMesh`, or a brep boolean) — the free-form counterpart of
+   * {@linkcode PluginDesignCreateApi.mass}, for solids that are not simple
+   * footprint extrusions (pyramids, wedges, faceted volumes).
+   *
+   * Only accepts breps **minted by a `core.geom.create` brep constructor** —
+   * scene-derived breps from `design.query.geometry.getBrep` are read-only and
+   * throw. The mass is created as a generic mass (`massType` "Generic mass") at
+   * the exact coordinates the solid was authored in, committed as a single
+   * undo step, and synced to collaborators like any other creator.
+   *
+   * @param brep - A solid from a `core.geom.create` brep constructor
+   * @param label - Label (maps to `room_type`)
+   * @returns the {@linkcode ComponentHandle} of the created mass
+   * @throws if the brep handle is invalid, or the brep was not created by a
+   *   `core.geom.create` brep constructor
+   *
+   * @examplePrompt Create a mass from these faces
+   * @examplePrompt Turn this custom brep into a scene mass
+   * @examplePrompt Add a pyramid-shaped mass to the model
+   *
+   * # Example
+   * ```ts
+   * const apex = { x: 0, y: 4, z: 0 }
+   * const a = { x: -2, y: 0, z: -2 }
+   * const b = { x: 2, y: 0, z: -2 }
+   * const c = { x: 2, y: 0, z: 2 }
+   * const d = { x: -2, y: 0, z: 2 }
+   * const brep = await snaptrude.core.geom.create.brepFromFaces([
+   *   [a, d, c, b],
+   *   [a, b, apex],
+   *   [b, c, apex],
+   *   [c, d, apex],
+   *   [d, a, apex],
+   * ])
+   * const pyramid = await snaptrude.design.create.massFromBrep(brep, "Pavilion")
+   * ```
+   */
+  public abstract massFromBrep(
+    brep: BrepHandle,
+    label?: string,
+  ): PluginApiReturn<ComponentHandle>
+
   /**
    * Create a **slab** by extruding a footprint contour by `thickness`
    * (default direction: down).
@@ -222,14 +297,17 @@ export abstract class PluginDesignCreateApi {
 
   /**
    * Create a **column** by extruding a cross-section contour upward by `height`
-   * from a base `position`.
+   * from a base `position`. The column is built to EXACTLY `height` — unlike
+   * the interactive draw tool, no slab-thickness deduction is applied.
    *
    * @param position - Base point
    * @param crossSection - Column cross-section footprint
-   * @param height - Column height (> 0)
-   * @param directionUp - Up axis (default world up)
+   * @param height - Column height (> 0), built exactly
+   * @param directionUp - Up axis (default world up); normalized by the host, so
+   * magnitude does not scale the height
    * @returns the {@linkcode ComponentHandle} of the created column
-   * @throws if the cross-section is invalid or the height is not positive
+   * @throws if the cross-section is invalid, the height is not positive, or the
+   * direction is zero / lies in the cross-section plane (degenerate extrusion)
    *
    * @examplePrompt Add a 3m tall column at this point
    * @examplePrompt Place a column at the grid intersection
@@ -253,13 +331,30 @@ export abstract class PluginDesignCreateApi {
 
   /**
    * Create a **beam** by extruding a cross-section contour along `direction` by
-   * `length`.
+   * `length`. Matches the Snaptrude beam tool's semantics: the beam body hangs
+   * BELOW the plane the section is authored on.
+   *
+   * For a **horizontal** `direction` (the common spanning beam), author the
+   * section as an axis-aligned plan rectangle: its X extent is the beam's
+   * width, its Z extent is the beam's depth (the vertical drop). The beam runs
+   * `length` along `direction` starting at the section's centre, hanging below
+   * the authoring plane by its depth — exactly like an interactively drawn
+   * beam. Only axis-aligned rectangular sections are supported horizontally.
    *
-   * @param section - Beam cross-section footprint
-   * @param length - Beam length along `direction` (> 0)
-   * @param direction - Extrusion axis (default world up)
+   * For a **vertical** `direction` (the default), the section itself is
+   * extruded by `length`, again hanging below the authoring plane. Diagonal
+   * directions are rejected.
+   *
+   * @param section - Beam cross-section, an axis-aligned rectangle in plan
+   * (X extent = width, Z extent = depth)
+   * @param length - Beam length along `direction` (> 0); direction is
+   * normalized by the host, so magnitude does not scale the length
+   * @param direction - Beam axis: horizontal for a spanning beam, or vertical
+   * (default world up). Diagonal directions throw.
    * @returns the {@linkcode ComponentHandle} of the created beam
-   * @throws if the section is invalid or the length is not positive
+   * @throws if the section is invalid (horizontal beams: not an axis-aligned
+   * plan rectangle), the length is not positive, or the direction is zero or
+   * diagonal
    *
    * @examplePrompt Add a beam spanning 6 metres between the columns
    * @examplePrompt Create a horizontal beam along the X axis
@@ -286,15 +381,31 @@ export abstract class PluginDesignCreateApi {
    *
    * @param profile - Ordered curve chain (wall centerlines)
    * @param height - Wall height (default engine default)
-   * @param thickness - Wall thickness (default engine default)
+   * @param thickness - Wall thickness (default: the `wallType`'s total layer
+   *   thickness when `wallType` is given, else the engine default)
+   * @param wallType - Wall type to build with — the same searchable list the
+   *   Draw tab's Wall Type dropdown offers. Pass a name from
+   *   `design.types.list("wall")` (the summary's `label`, or its `"wall:…"` id).
+   *   Drives the wall's construction layers and default material, and — when
+   *   `thickness` is omitted — its total layer thickness. Default: the engine's
+   *   generic wall.
+   * @param storey - Target storey (integer: `1` ground, `2` first floor, `-1`
+   *   basement — same convention as `design.create.space`). The walls are
+   *   assigned to it and lifted to its base elevation, all inside the same
+   *   single undo entry. The storey must already exist
+   *   (`core.storeys.create` first). Default: geometry-derived — a profile
+   *   drawn at y = 0 lands on storey 1; the ACTIVE storey is NOT consulted.
    * @returns a {@linkcode ComponentHandle}`[]` (one per wall), in profile order
-   * @throws if the profile is empty or wall creation fails
+   * @throws if the profile is empty, `wallType` names no wall type in the
+   *   project, `storey` does not exist, or wall creation fails
    *
    * @examplePrompt Draw walls along this centerline
    * @examplePrompt Create 3m high, 200mm thick walls from these points
    * @examplePrompt Build a wall run around the room outline
    * @examplePrompt Turn this polyline sketch into walls
    * @examplePrompt Add walls with mitred corners along the path
+   * @examplePrompt Draw brick walls with plaster along this outline
+   * @examplePrompt Build the perimeter in exposed concrete walls
    *
    * # Example
    * ```ts
@@ -305,12 +416,19 @@ export abstract class PluginDesignCreateApi {
    *   await v.new(8, 0, 6),
    * ])
    * const walls = await snaptrude.design.create.walls(centerlines, 3, 0.2)
+   * // …built as a specific wall type (layers/material/thickness from the type):
+   * const [brick] = await snaptrude.design.types.list("wall")
+   * const brickWalls = await snaptrude.design.create.walls(
+   *   centerlines, 3, undefined, brick.label,
+   * )
    * ```
    */
   public abstract walls(
     profile: ProfileHandle,
     height?: number,
     thickness?: number,
+    wallType?: string,
+    storey?: number,
   ): PluginApiReturn<ComponentHandle[]>
 
   /**
@@ -318,12 +436,17 @@ export abstract class PluginDesignCreateApi {
    *
    * Geometry is procedurally generated from the chosen `preset`; there is no
    * footprint input. Placed on the active structure/story unless overridden.
+   * The promise resolves only after the staircase's asynchronous geometry union
+   * and creation-command capture settle; a union failure rejects the call.
    *
    * @param preset - The parametric preset to generate
    * @param position - Placement point
    * @param label - Optional label
    * @param structureId - Target structure (default active)
    * @param level - Target level name (default active/`"01"`)
+   * @param dimensions - Optional positive dimension overrides in Snaptrude engine
+   *   units, plus a placement angle in 90-degree increments. Overrides are
+   *   applied to the staircase parameters before the creation command runs.
    * @returns the {@linkcode ComponentHandle} of the created staircase
    * @throws if the preset is unknown or placement fails
    *
@@ -347,6 +470,7 @@ export abstract class PluginDesignCreateApi {
     label?: string,
     structureId?: string,
     level?: string,
+    dimensions?: PluginStaircaseDimensions,
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -401,14 +525,23 @@ export abstract class PluginDesignCreateApi {
    * with {@linkcode PluginDesignFurnitureApi.listCatalog}. Placement is asynchronous
    * (the source mesh is fetched if not cached) and creates one undo entry.
    *
-   * Placed at the item's default rotation; rotate afterward via `design.transform.rotate`
-   * on the returned handle (planned namespace).
+   * Placed at the item's default rotation unless `angleInDegrees` is given, which
+   * rotates it about the vertical axis at creation time (baked into the same undo
+   * entry). To rotate an existing instance instead, use `design.transform.rotate`.
    *
    * @param catalogId - Library id: team `_id` or general `fullName`
-   * @param position - Absolute world placement point
+   * @param position - Absolute world placement point. `position.y` is the REST
+   *   elevation: the item is grounded so its bounding-box base sits exactly at
+   *   `position.y` (the same surface-flush contract as interactive drag-drop) —
+   *   pass the floor/storey elevation to stand furniture on it; never add half
+   *   the item's height yourself.
    * @param options - Optional placement options: `label` — instance name
    *   (default auto `${name}Ins${n}`); `createNewSourceMesh` — emit a
    *   source-mesh creation command (default `true`)
+   * @param angleInDegrees - Optional signed rotation about the vertical axis, in
+   *   degrees (same convention as {@linkcode PluginDesignTransformApi.rotate}).
+   *   Applied at creation time so it is part of the placement's single undo entry.
+   *   Default: the item's own (unrotated) orientation.
    * @returns the {@linkcode ComponentHandle} of the placed furniture instance
    * @throws if the catalog id is unknown, the source mesh fails to load, or placement fails
    *
@@ -417,6 +550,7 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Drop a desk into the scene at 3, 0, 5
    * @examplePrompt Insert the uploaded bed model in the bedroom
    * @examplePrompt Put a table from my project library here and name it Table-01
+   * @examplePrompt Place a chair here rotated 90 degrees
    *
    * # Example
    * ```ts
@@ -425,24 +559,235 @@ export abstract class PluginDesignCreateApi {
    *   await snaptrude.core.math.vec3.new(3, 0, 5),
    *   { label: "Chair-01" },
    * )
+   * // …placed already turned 90° about the vertical axis:
+   * const turned = await snaptrude.design.create.furniture(
+   *   "6620f1a…",
+   *   await snaptrude.core.math.vec3.new(3, 0, 5),
+   *   undefined,
+   *   90,
+   * )
    * ```
    */
   public abstract furniture(
     catalogId: string,
     position: Vec3Handle,
     options?: { label?: string; createNewSourceMesh?: boolean },
+    angleInDegrees?: number,
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * Place a **door** from the catalog into a host wall.
+   *
+   * Identified by a **catalog (library) id** — the team object's stable `_id`
+   * or the general library's `fullName`. Discover ids with
+   * {@linkcode PluginDesignDoorsApi.listCatalog}. The world `position` is
+   * projected onto the host wall's face to locate the opening; the wall is
+   * re-cut and the door hosted in a single undo entry. Placement is
+   * asynchronous (the source mesh is fetched if not cached).
+   *
+   * @param catalogId - Library id: team `_id` or general `fullName`
+   * @param hostWall - The wall to host the door
+   * @param position - World point projected onto the wall to locate the opening
+   * @param options - Optional placement options: `label` — instance name
+   * @param facing - World point selecting which side of the wall the door faces
+   *   (the room it opens into) — the same convention as approaching the wall
+   *   from that side with the cursor in the interactive tool. Any point clearly
+   *   on that side works (e.g. the room's center). Default: the engine picks a
+   *   side (nondeterministic when `position` sits on the wall centerline).
+   * @returns the {@linkcode ComponentHandle} of the placed door
+   * @throws if the catalog id is unknown, the host is not a wall, the source
+   *   mesh fails to load, or the projected point falls **outside** the host wall
+   *
+   * @examplePrompt Add a door to this wall here
+   * @examplePrompt Place a sliding door on the selected wall
+   * @examplePrompt Put a door from the catalog at this point on the wall
+   * @examplePrompt Insert the entrance door into this wall
+   * @examplePrompt Add a door to the wall and call it Entry-01
+   * @examplePrompt Add a door that opens into the living room
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls({ isSelected: true })
+   * const [entry] = await snaptrude.design.doors.listCatalog()
+   * const door = await snaptrude.design.create.door(
+   *   entry.id,
+   *   wall,
+   *   await snaptrude.core.math.vec3.new(3, 0, 5),
+   *   { label: "Entry-01" },
+   * )
+   * // …facing a specific side of the wall (pass a point inside that room):
+   * const intoKitchen = await snaptrude.design.create.door(
+   *   entry.id,
+   *   wall,
+   *   await snaptrude.core.math.vec3.new(3, 0, 5),
+   *   undefined,
+   *   await snaptrude.core.math.vec3.new(3, 0, 9),
+   * )
+   * ```
+   */
+  public abstract door(
+    catalogId: string,
+    hostWall: ComponentHandle,
+    position: Vec3Handle,
+    options?: { label?: string },
+    facing?: Vec3Handle,
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * Place a **window** from the catalog into a host wall.
+   *
+   * Identified by a **catalog (library) id** — the team object's stable `_id`
+   * or the general library's `fullName`. Discover ids with
+   * {@linkcode PluginDesignWindowsApi.listCatalog}. The world `position` is
+   * projected onto the host wall's face to locate the opening; the wall is
+   * re-cut and the window hosted in a single undo entry. Placement is
+   * asynchronous (the source mesh is fetched if not cached).
+   *
+   * @param catalogId - Library id: team `_id` or general `fullName`
+   * @param hostWall - The wall to host the window
+   * @param position - World point projected onto the wall to locate the opening
+   * @param options - Optional placement options: `label` — instance name
+   * @param facing - World point selecting which side of the wall the window
+   *   faces (matters for asymmetric windows, e.g. casement swing) — same
+   *   convention as {@linkcode PluginDesignCreateApi.door}. Default: the engine
+   *   picks a side (nondeterministic when `position` sits on the centerline).
+   * @returns the {@linkcode ComponentHandle} of the placed window
+   * @throws if the catalog id is unknown, the host is not a wall, the source
+   *   mesh fails to load, or the projected point falls **outside** the host wall
+   *
+   * @examplePrompt Add a window to this wall here
+   * @examplePrompt Place a casement window on the selected wall
+   * @examplePrompt Put a window from the catalog at this point on the wall
+   * @examplePrompt Insert a window into the living room wall
+   * @examplePrompt Add a window to the wall and name it Win-01
+   * @examplePrompt Add a casement window opening toward the garden side
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls({ isSelected: true })
+   * const [entry] = await snaptrude.design.windows.listCatalog()
+   * const window = await snaptrude.design.create.window(
+   *   entry.id,
+   *   wall,
+   *   await snaptrude.core.math.vec3.new(3, 0, 5),
+   *   { label: "Win-01" },
+   * )
+   * ```
+   */
+  public abstract window(
+    catalogId: string,
+    hostWall: ComponentHandle,
+    position: Vec3Handle,
+    options?: { label?: string },
+    facing?: Vec3Handle,
   ): PluginApiReturn<ComponentHandle>
 
+  /**
+   * Place a catalog **door or window** into a host wall with optional size overrides.
+   *
+   * The world `position` is projected onto the host wall to locate the opening.
+   * All supplied dimensions use Snaptrude engine units. Window `sillHeight` is
+   * measured from the host wall base to the bottom of the window, not to
+   * its center. Placement is asynchronous and committed as one undoable creation.
+   *
+   * @param options - Opening kind, catalog and host references, placement, and
+   *   optional facing, label, and dimensions
+   * @returns the {@linkcode ComponentHandle} of the placed door or window
+   * @throws if the options are invalid, the catalog id is unknown, the host is
+   *   not a wall, loading fails, or the opening cannot be placed on the host
+   *
+   * @examplePrompt Add a 1m wide door to this wall here
+   * @examplePrompt Place a window with a 0.9m sill height on the selected wall
+   *
+   * @performance Single-opening creator — use it for one hosted opening. A plural
+   *   API is intentionally unavailable until host placement can be atomic.
+   *
+   * # Example
+   * ```ts
+   * const opening = await snaptrude.design.create.opening({
+   *   kind: "window",
+   *   catalogId: windowType.id,
+   *   hostWall: wall,
+   *   position: await snaptrude.core.math.vec3.new(3, 0, 5),
+   *   width: 1.2,
+   *   height: 1.5,
+   *   sillHeight: 0.9,
+   * })
+   * ```
+   */
+  public abstract opening(
+    options: PluginDesignCreateOpeningOptions,
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * Place a **smart layout** — clone an in-scene template cluster (walls,
+   * furniture, doors, windows, floors) into one or more target ROOM/DEPARTMENT
+   * spaces, adapting orientation and fit to each target.
+   *
+   * Supply the template as **exactly one** of `templateGroup` (a group **id**
+   * from `snaptrude.core.groups.list` — groups are string-id entities, not
+   * component handles) or
+   * `templateComponents` (an explicit component set); every target in `targets`
+   * (≥1) receives its own placement. By default the target spaces are hidden
+   * after placement (`hideTargets`, mirroring the product) — pass `false` to keep
+   * them visible.
+   *
+   * The whole operation — every wall/opening/furniture/floor across every target,
+   * plus the target-hide — is committed as a **single undo step**. Because all
+   * targets merge into one creation batch, the created entities are returned
+   * **flat, grouped by kind** ({@linkcode PluginSmartLayoutResult}), NOT attributed
+   * per target (per-target attribution would break the single-undo guarantee).
+   * `skippedWalls` is the interior-optimizer's best-candidate count of walls it
+   * could not place. Synchronous and heavy — many targets can jank the main thread.
+   *
+   * @param options - {@linkcode PluginSmartLayoutArgs}: template source, targets, and `hideTargets`
+   * @returns a {@linkcode PluginSmartLayoutResult} — created entities grouped by kind + `skippedWalls`
+   * @throws if smart layout is not enabled, the template group is invalid, there
+   *   is no template / no targets / no valid mappings, or component creation fails
+   *
+   * @examplePrompt Copy this room's layout into the selected rooms
+   * @examplePrompt Apply this furniture arrangement to the other offices
+   * @examplePrompt Replicate this template into these two spaces
+   * @examplePrompt Place this desk cluster into every meeting room
+   * @examplePrompt Use this room as a template for the rooms I selected but keep them visible
+   *
+   * # Example
+   * ```ts
+   * const [templateRoom, ...targets] = await snaptrude.design.query.listSpaces({ isSelected: true })
+   * const result = await snaptrude.design.create.smartLayout({
+   *   templateComponents: [templateRoom],
+   *   targets,
+   * })
+   * console.log("placed walls:", result.created.walls.length, "skipped:", result.skippedWalls)
+   *
+   * // …or clone a saved group by its id (from core.groups.list)
+   * const { groups } = await snaptrude.core.groups.list()
+   * await snaptrude.design.create.smartLayout({ templateGroup: groups[0].id, targets })
+   * ```
+   */
+  public abstract smartLayout(
+    options: PluginSmartLayoutArgs,
+  ): PluginApiReturn<PluginSmartLayoutResult>
+
   /**
    * **Copy** existing entities, offsetting each copy by `displacement * i` (i = 1…count),
    * source positions preserved. Migrated from the removed `tools.copy`. In `"instance"`
    * mode copies stay in the source's instance family where possible; `"unique"` makes
    * independent geometry. The created copies become the active selection. Undoable.
    *
+   * Runs on the engine's array-copy tool, so its semantics carry over: an
+   * `"instance"` copy of a source that is not yet an instance **replaces that
+   * source** with a fresh instance component — the handle you passed in stops
+   * resolving after the call. Re-query (e.g. `design.query.listSpaces`) to pick
+   * up the replacement before operating on that entity again; copying the stale
+   * handle throws. `"unique"` mode never replaces sources.
+   *
    * @param components - Entities to copy (≥1)
    * @param displacement - Per-copy offset as a {@linkcode Vec3Handle} (copy `i` at `displacement * i`)
    * @param options - `count` (copies per component, default 1), `mode` (`"instance"` | `"unique"`, default `"instance"`)
    * @returns the created copies as {@linkcode ComponentHandle}`[]`
+   * @throws if a component handle is unknown or stale (replaced by an earlier
+   *   `"instance"` copy), `count` is not a positive integer, or the engine fails
    *
    * @examplePrompt Copy this room 3 times spaced 6m apart
    * @examplePrompt Duplicate the selected furniture along the X axis
@@ -450,6 +795,11 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Array these walls with a 3m offset
    * @examplePrompt Clone the desk as a unique copy, not an instance
    *
+   * @performance To place N repeats of the same geometry, bulk-create the seed(s) once then
+   *   call this ONCE with `{ count: N - 1 }` — one host round-trip for all copies. Never
+   *   reproduce geometry by looping `design.create.*` N times. Copy only after the create
+   *   that mints the seed ids.
+   *
    * # Example
    * ```ts
    * const { vec3 } = snaptrude.core.math
@@ -467,15 +817,24 @@ export abstract class PluginDesignCreateApi {
    * Migrated from the removed `entity.space.bulkCreate`. Each item extrudes a contour
    * footprint up `height`. Validate-all-or-throw; one command. For a rectangular
    * (box) space, build the footprint with `core.geom.create.profileRect` →
-   * `contourFromProfile`, then pass it as an item.
+   * `contourFromProfile`, then pass it as an item. Each item may carry its own
+   * `storey` (see {@linkcode PluginCreateSpaceItem}) so a single call can populate
+   * several floors at once.
    *
    * @param items - One {@linkcode PluginCreateSpaceItem} per space to create (≥1)
    * @returns the created spaces as {@linkcode ComponentHandle}`[]`, in input order
+   * @throws if any item's contour is invalid, its height is not positive, or its
+   *   target `storey` does not exist (all-or-nothing — nothing is created)
    *
    * @examplePrompt Create several rooms at once from these footprints
    * @examplePrompt Generate all the bedrooms in one operation
    * @examplePrompt Bulk create the spaces for this floor plan
    * @examplePrompt Add three rooms with different heights in a single undo step
+   * @examplePrompt Create one room on the ground floor and one on the first floor
+   *
+   * @performance Bulk creator — the whole batch is ONE host round-trip. Always prefer this
+   *   over calling `design.create.space` in a loop: build the full `items[]` array first
+   *   (all per-item math and geometry up front), then make one call.
    *
    * # Example
    * ```ts
@@ -487,7 +846,61 @@ export abstract class PluginDesignCreateApi {
    * ])
    * ```
    */
-  public abstract spaces(items: PluginCreateSpaceItem[]): PluginApiReturn<ComponentHandle[]>
+  public abstract spaces(
+    items: PluginCreateSpaceItem[],
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * Create a new parametric buildable envelope — the zoning-regulated volume a
+   * building may occupy — generated from a site polygon, tiered setbacks, a
+   * height or floor-count cap, and optional FAR and lot-coverage limits. The host
+   * mints the envelope id and returns it. Canonical home of the create formerly
+   * at `entity.buildableEnvelope.create` (now deprecated).
+   *
+   * @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 PluginBuildableEnvelopeCreateResult} with the
+   *   `buildableEnvelopeId` of the created envelope.
+   * @throws If validation fails or generation produces no renderable geometry.
+   *
+   * @examplePrompt Create a buildable envelope for my site
+   * @examplePrompt Generate the zoning envelope with 10ft front setbacks
+   * @examplePrompt Show the maximum buildable volume with a 150ft height limit
+   * @examplePrompt Create a zoning envelope capped at 12 floors with FAR 3
+   *
+   * # Example
+   * ```ts
+   * const { buildableEnvelopeId } = await snaptrude.design.create.buildableEnvelope(
+   *   [
+   *     { 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 },
+   *     { aboveHeight: 100, front: 20, side: 10, rear: 20 },
+   *   ],
+   *   { kind: "max_height", maxHeight: 150 },
+   *   12,
+   * )
+   * ```
+   */
+  public abstract buildableEnvelope(
+    sitePolygon: PluginBuildableEnvelopePolygonVertex[],
+    lengthUnit: "ft" | "m",
+    setbacks: PluginBuildableEnvelopeSetbackTier[],
+    verticalCap: PluginBuildableEnvelopeVerticalCap,
+    floorToFloor: number,
+    farRatio?: number,
+    lotCoverageMaxPct?: number,
+  ): PluginApiReturn<PluginBuildableEnvelopeCreateResult>
 }
 
 // ---------------------------------------------------------------------------
@@ -549,6 +962,24 @@ export const PluginStaircasePreset = z.enum([
 ])
 export type PluginStaircasePreset = z.infer<typeof PluginStaircasePreset>
 
+/**
+ * Optional staircase dimension overrides. Lengths use Snaptrude engine units
+ * and must be positive. `angleInDegrees` controls placement about the vertical
+ * axis and must be a multiple of 90 degrees.
+ */
+export const PluginStaircaseDimensions = z
+  .object({
+    width: z.number().finite().positive().optional(),
+    tread: z.number().finite().positive().optional(),
+    riser: z.number().finite().positive().optional(),
+    landingWidth: z.number().finite().positive().optional(),
+    angleInDegrees: z.number().finite().multipleOf(90).optional(),
+  })
+  .strict()
+export type PluginStaircaseDimensions = z.infer<
+  typeof PluginStaircaseDimensions
+>
+
 // ---------------------------------------------------------------------------
 // space
 // ---------------------------------------------------------------------------
@@ -565,6 +996,7 @@ export type PluginStaircasePreset = z.infer<typeof PluginStaircasePreset>
  * | `spaceType` | {@linkcode PluginSpaceType}? | Space-type classification (default `Room`) |
  * | `massType` | {@linkcode PluginMassType}? | Mass-type classification (default `Room`) |
  * | `departmentId` | {@linkcode PluginDepartmentId}? | Department assignment (default department) |
+ * | `storey` | `number`? (int) | Target storey number (default active storey) |
  */
 export const PluginDesignCreateSpaceArgs = z.object({
   contour: ContourHandle,
@@ -574,8 +1006,13 @@ export const PluginDesignCreateSpaceArgs = z.object({
   spaceType: PluginSpaceType.optional(),
   massType: PluginMassType.optional(),
   departmentId: PluginDepartmentId.optional(),
+  storey: z.number().int().optional(),
 })
-export type PluginDesignCreateSpaceArgs = z.infer<typeof PluginDesignCreateSpaceArgs>
+export type PluginDesignCreateSpaceArgs = z.infer<
+  typeof PluginDesignCreateSpaceArgs
+>
+// TRANSPORT: positional signature shipped — storey is the trailing 8th arg:
+//   space(contour, height, label?, position?, spaceType?, massType?, departmentId?, storey?)
 
 // ---------------------------------------------------------------------------
 // mass
@@ -599,7 +1036,29 @@ export const PluginDesignCreateMassArgs = z.object({
   position: Vec3Handle.optional(),
   massType: PluginMassType.optional(),
 })
-export type PluginDesignCreateMassArgs = z.infer<typeof PluginDesignCreateMassArgs>
+export type PluginDesignCreateMassArgs = z.infer<
+  typeof PluginDesignCreateMassArgs
+>
+
+// ---------------------------------------------------------------------------
+// massFromBrep
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.massFromBrep}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `brep` | {@linkcode BrepHandle} | A solid from a `core.geom.create` brep constructor |
+ * | `label` | `string`? | Label (maps to `room_type`) |
+ */
+export const PluginDesignCreateMassFromBrepArgs = z.object({
+  brep: BrepHandle,
+  label: z.string().optional(),
+})
+export type PluginDesignCreateMassFromBrepArgs = z.infer<
+  typeof PluginDesignCreateMassFromBrepArgs
+>
 
 // ---------------------------------------------------------------------------
 // slab
@@ -621,7 +1080,9 @@ export const PluginDesignCreateSlabArgs = z.object({
   direction: z.enum(["up", "down"]).optional(),
   slabType: PluginSlabType.optional(),
 })
-export type PluginDesignCreateSlabArgs = z.infer<typeof PluginDesignCreateSlabArgs>
+export type PluginDesignCreateSlabArgs = z.infer<
+  typeof PluginDesignCreateSlabArgs
+>
 
 // ---------------------------------------------------------------------------
 // floor
@@ -641,7 +1102,9 @@ export const PluginDesignCreateFloorArgs = z.object({
   thickness: z.number(),
   position: Vec3Handle.optional(),
 })
-export type PluginDesignCreateFloorArgs = z.infer<typeof PluginDesignCreateFloorArgs>
+export type PluginDesignCreateFloorArgs = z.infer<
+  typeof PluginDesignCreateFloorArgs
+>
 
 // ---------------------------------------------------------------------------
 // roof
@@ -659,7 +1122,9 @@ export const PluginDesignCreateRoofArgs = z.object({
   contour: ContourHandle,
   thickness: z.number(),
 })
-export type PluginDesignCreateRoofArgs = z.infer<typeof PluginDesignCreateRoofArgs>
+export type PluginDesignCreateRoofArgs = z.infer<
+  typeof PluginDesignCreateRoofArgs
+>
 
 // ---------------------------------------------------------------------------
 // ceiling
@@ -679,7 +1144,9 @@ export const PluginDesignCreateCeilingArgs = z.object({
   thickness: z.number(),
   heightFromFloor: z.number().optional(),
 })
-export type PluginDesignCreateCeilingArgs = z.infer<typeof PluginDesignCreateCeilingArgs>
+export type PluginDesignCreateCeilingArgs = z.infer<
+  typeof PluginDesignCreateCeilingArgs
+>
 
 // ---------------------------------------------------------------------------
 // column
@@ -701,7 +1168,9 @@ export const PluginDesignCreateColumnArgs = z.object({
   height: z.number(),
   directionUp: Vec3Handle.optional(),
 })
-export type PluginDesignCreateColumnArgs = z.infer<typeof PluginDesignCreateColumnArgs>
+export type PluginDesignCreateColumnArgs = z.infer<
+  typeof PluginDesignCreateColumnArgs
+>
 
 // ---------------------------------------------------------------------------
 // beam
@@ -721,7 +1190,9 @@ export const PluginDesignCreateBeamArgs = z.object({
   length: z.number(),
   direction: Vec3Handle.optional(),
 })
-export type PluginDesignCreateBeamArgs = z.infer<typeof PluginDesignCreateBeamArgs>
+export type PluginDesignCreateBeamArgs = z.infer<
+  typeof PluginDesignCreateBeamArgs
+>
 
 // ---------------------------------------------------------------------------
 // walls
@@ -734,14 +1205,22 @@ export type PluginDesignCreateBeamArgs = z.infer<typeof PluginDesignCreateBeamAr
  * |---|---|---|
  * | `profile` | {@linkcode ProfileHandle} | Ordered curve chain (wall centerlines) |
  * | `height` | `number`? | Wall height (default engine default) |
- * | `thickness` | `number`? | Wall thickness (default engine default) |
+ * | `thickness` | `number`? | Wall thickness (default: `wallType`'s total layer thickness when given, else engine default) |
+ * | `wallType` | `string`? | Wall type name from `design.types.list("wall")` — layers/material/thickness defaults (default generic) |
+ * | `storey` | `number`? | Target storey (integer, must exist) — walls assigned + lifted to its base in the same undo entry (default: geometry-derived) |
  */
 export const PluginDesignCreateWallsArgs = z.object({
   profile: ProfileHandle,
   height: z.number().optional(),
   thickness: z.number().optional(),
+  wallType: z.string().min(1).optional(),
+  storey: z.number().int().optional(),
 })
-export type PluginDesignCreateWallsArgs = z.infer<typeof PluginDesignCreateWallsArgs>
+export type PluginDesignCreateWallsArgs = z.infer<
+  typeof PluginDesignCreateWallsArgs
+>
+// TRANSPORT: positional signature shipped — storey is the trailing 5th arg:
+//   walls(profile: ProfileHandle, height?: number, thickness?: number, wallType?: string, storey?: number)
 
 // ---------------------------------------------------------------------------
 // staircase
@@ -757,6 +1236,7 @@ export type PluginDesignCreateWallsArgs = z.infer<typeof PluginDesignCreateWalls
  * | `label` | `string`? | Optional label |
  * | `structureId` | `string`? | Target structure (default active) |
  * | `level` | `string`? | Target level name (default active/`"01"`) |
+ * | `dimensions` | {@linkcode PluginStaircaseDimensions}? | Positive dimension overrides in engine units, applied before creation |
  */
 export const PluginDesignCreateStaircaseArgs = z.object({
   preset: PluginStaircasePreset,
@@ -764,6 +1244,7 @@ export const PluginDesignCreateStaircaseArgs = z.object({
   label: z.string().optional(),
   structureId: z.string().optional(),
   level: z.string().optional(),
+  dimensions: PluginStaircaseDimensions.optional(),
 })
 export type PluginDesignCreateStaircaseArgs = z.infer<
   typeof PluginDesignCreateStaircaseArgs
@@ -782,18 +1263,173 @@ export type PluginDesignCreateStaircaseArgs = z.infer<
  * | `position` | {@linkcode Vec3Handle} | Absolute world placement point |
  * | `label` | `string`? | Instance name (default auto `${name}Ins${n}`) |
  * | `createNewSourceMesh` | `boolean`? | Emit a source-mesh creation command (default `true`) |
+ * | `angleInDegrees` | `number`? | Rotation about the vertical axis, in degrees (default unrotated) |
  */
 export const PluginDesignCreateFurnitureArgs = z.object({
   catalogId: z.string().min(1),
   position: Vec3Handle,
   label: z.string().optional(),
   createNewSourceMesh: z.boolean().optional(),
+  angleInDegrees: z.number().optional(),
 })
 export type PluginDesignCreateFurnitureArgs = z.infer<
   typeof PluginDesignCreateFurnitureArgs
 >
-// TRANSPORT: positional signature shipped —
-//   furniture(catalogId: string, position: Vec3Handle, options?: { label?, createNewSourceMesh? })
+// TRANSPORT: positional signature shipped — angleInDegrees is the trailing 4th arg:
+//   furniture(catalogId: string, position: Vec3Handle, options?: { label?, createNewSourceMesh? }, angleInDegrees?: number)
+
+// ---------------------------------------------------------------------------
+// door
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.door}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the door |
+ * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
+ * | `label` | `string`? | Instance name (optional) |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the door faces (default engine-chosen) |
+ */
+export const PluginDesignCreateDoorArgs = z.object({
+  catalogId: z.string().min(1),
+  hostWall: ComponentHandle,
+  position: Vec3Handle,
+  label: z.string().optional(),
+  facing: Vec3Handle.optional(),
+})
+export type PluginDesignCreateDoorArgs = z.infer<
+  typeof PluginDesignCreateDoorArgs
+>
+// TRANSPORT: positional signature shipped — facing is the trailing 5th arg:
+//   door(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: { label? }, facing?: Vec3Handle)
+
+// ---------------------------------------------------------------------------
+// window
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.window}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the window |
+ * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
+ * | `label` | `string`? | Instance name (optional) |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the window faces (default engine-chosen) |
+ */
+export const PluginDesignCreateWindowArgs = z.object({
+  catalogId: z.string().min(1),
+  hostWall: ComponentHandle,
+  position: Vec3Handle,
+  label: z.string().optional(),
+  facing: Vec3Handle.optional(),
+})
+export type PluginDesignCreateWindowArgs = z.infer<
+  typeof PluginDesignCreateWindowArgs
+>
+// TRANSPORT: positional signature shipped — facing is the trailing 5th arg:
+//   window(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: { label? }, facing?: Vec3Handle)
+
+// ---------------------------------------------------------------------------
+// opening
+// ---------------------------------------------------------------------------
+
+const PluginOpeningBaseOptions = {
+  catalogId: z.string().min(1),
+  hostWall: ComponentHandle,
+  position: Vec3Handle,
+  facing: Vec3Handle.optional(),
+  label: z.string().optional(),
+  width: z.number().finite().positive().optional(),
+  height: z.number().finite().positive().optional(),
+}
+
+/**
+ * Options for {@linkcode PluginDesignCreateApi.opening}, discriminated by
+ * `kind`. Width and height are positive Snaptrude engine-unit values.
+ * `sillHeight` is available only for windows, is nonnegative, and is precisely
+ * the distance from the host wall base to the bottom of the window.
+ */
+export const PluginDesignCreateOpeningOptions = z.discriminatedUnion("kind", [
+  z
+    .object({
+      kind: z.literal("door"),
+      ...PluginOpeningBaseOptions,
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("window"),
+      ...PluginOpeningBaseOptions,
+      sillHeight: z.number().finite().nonnegative().optional(),
+    })
+    .strict(),
+])
+export type PluginDesignCreateOpeningOptions = z.infer<
+  typeof PluginDesignCreateOpeningOptions
+>
+
+// ---------------------------------------------------------------------------
+// smartLayout
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.smartLayout}. Provide **exactly
+ * one** template source: `templateGroup` or a non-empty `templateComponents`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `templateGroup` | `string`? | Id of the group to clone as the template (a group id from `snaptrude.core.groups.list`, NOT a component handle) |
+ * | `templateComponents` | {@linkcode ComponentHandle}`[]`? | Explicit component set to clone as the template |
+ * | `targets` | {@linkcode ComponentHandle}`[]` | ROOM/DEPARTMENT spaces to place into (≥1) |
+ * | `hideTargets` | `boolean`? | Hide the target spaces after placement (default `true`) |
+ */
+export const PluginSmartLayoutArgs = z
+  .object({
+    templateGroup: z.string().min(1).optional(),
+    templateComponents: z.array(ComponentHandle).optional(),
+    targets: z.array(ComponentHandle).min(1),
+    hideTargets: z.boolean().optional(),
+  })
+  .refine(
+    (v) =>
+      (v.templateGroup != null) !== (v.templateComponents?.length ?? 0) > 0,
+    {
+      message:
+        "Provide exactly one template source: templateGroup or a non-empty templateComponents",
+    },
+  )
+export type PluginSmartLayoutArgs = z.infer<typeof PluginSmartLayoutArgs>
+
+/**
+ * Result of {@linkcode PluginDesignCreateApi.smartLayout} — the entities the run
+ * created, grouped by kind (flat across all targets; see the method JSDoc for why
+ * this is not attributed per target).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `created.walls` | {@linkcode ComponentHandle}`[]` | Created walls |
+ * | `created.furniture` | {@linkcode ComponentHandle}`[]` | Created furniture |
+ * | `created.doors` | {@linkcode ComponentHandle}`[]` | Created doors |
+ * | `created.windows` | {@linkcode ComponentHandle}`[]` | Created windows |
+ * | `created.floors` | {@linkcode ComponentHandle}`[]` | Created floors |
+ * | `skippedWalls` | `number` | Walls the interior optimizer could not place |
+ */
+export const PluginSmartLayoutResult = z.object({
+  created: z.object({
+    walls: z.array(ComponentHandle),
+    furniture: z.array(ComponentHandle),
+    doors: z.array(ComponentHandle),
+    windows: z.array(ComponentHandle),
+    floors: z.array(ComponentHandle),
+  }),
+  skippedWalls: z.number(),
+})
+export type PluginSmartLayoutResult = z.infer<typeof PluginSmartLayoutResult>
 
 // ---------------------------------------------------------------------------
 // referenceLines
@@ -852,7 +1488,9 @@ export const PluginDesignCreateCopyArgs = z.object({
   count: z.number().int().positive().optional(),
   mode: PluginCopyMode.optional(),
 })
-export type PluginDesignCreateCopyArgs = z.infer<typeof PluginDesignCreateCopyArgs>
+export type PluginDesignCreateCopyArgs = z.infer<
+  typeof PluginDesignCreateCopyArgs
+>
 // TRANSPORT: positional signature shipped —
 //   copy(components: ComponentHandle[], displacement: Vec3Handle, options?: { count?, mode? })
 
@@ -873,6 +1511,7 @@ export type PluginDesignCreateCopyArgs = z.infer<typeof PluginDesignCreateCopyAr
  * | `spaceType` | `PluginSpaceType`? | Space type |
  * | `massType` | `PluginMassType`? | Mass type |
  * | `departmentId` | `PluginDepartmentId`? | Department |
+ * | `storey` | `number`? (int) | Target storey number (default active storey) |
  */
 export const PluginCreateSpaceItem = z.object({
   contour: ContourHandle,
@@ -882,5 +1521,6 @@ export const PluginCreateSpaceItem = z.object({
   spaceType: PluginSpaceType.optional(),
   massType: PluginMassType.optional(),
   departmentId: PluginDepartmentId.optional(),
+  storey: z.number().int().optional(),
 })
 export type PluginCreateSpaceItem = z.infer<typeof PluginCreateSpaceItem>