@snaptrude/plugin-core 0.10.0 → 1.0.0

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

@@ -4,9 +4,13 @@ import {
   BrepHandle,
   ComponentHandle,
   ContourHandle,
+  LineHandle,
+  CurveHandle,
   ProfileHandle,
   Vec3Handle,
 } from "../../../handles"
+import { PluginGridStyleOptions } from "./grids"
+import { PluginGraphicsLineStyleId } from "../../presentation/graphics"
 import {
   PluginSpaceType,
   PluginMassType,
@@ -17,13 +21,33 @@ import {
   PluginBuildableEnvelopeSetbackTier,
   PluginBuildableEnvelopeVerticalCap,
   PluginBuildableEnvelopeCreateResult,
+  PluginDesignCreateBuildableEnvelopeFromSiteResult,
 } from "../../entity/buildableEnvelope"
+import { PluginOpeningBaseOptions } from "./opening-fields"
+import type {
+  PluginCreateDoorItem,
+  PluginCreateFloorItem,
+  PluginCreateFurnitureItem,
+  PluginCreateVoidItem,
+  PluginCreateWallRunItem,
+  PluginCreateWindowItem,
+} from "./bulk-items"
+import { PluginWallTopProfile } from "./bulk-items"
+import { PluginWallType } from "../types"
+import {
+  PluginFamilyPlacement,
+  PluginFamilyFloorOptions,
+  PluginFamilySlabOptions,
+  PluginFamilyCeilingOptions,
+  PluginFamilyValues,
+} from "../catalog"
 
 /**
  * `design.create.*` — author new scene-committed BIM entities.
  *
  * Every creator takes geometry handles + scalars and returns a
- * {@linkcode ComponentHandle} (or `ComponentHandle[]` for plural creators) — the
+ * {@linkcode ComponentHandle} (or `ComponentHandle[]` for plural creators;
+ * `wallRuns` returns one `ComponentHandle[]` per run) — the
  * `Component.id` of the created entity, resolvable across the rest of the
  * `design.*` surface. Creation is an undoable host call; it **throws** on failure
  * (no `Result` wrapper — consistent with `core.geom.create.*`).
@@ -31,9 +55,17 @@ 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
+ * Family overloads take `{ type, values? }` from `design.catalog`. The family supplies
+ * construction; the contour or axis supplies instance geometry. Geometry uses SU,
+ * while family length overrides use mm and angles use degrees. Omitted parameters
+ * retain family defaults; shared/type, formula and geometry-bound overrides are refused.
+ * Placement never publishes a definition. Unsupported references or geometry fail before mutation.
+ *
+ * `door`/`window` place a parametric family 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
+ * undo entry) and throw if the point projects outside the wall. Voids
+ * (`void`/`voids`) are the third hosted child: holes through slabs, floors,
+ * roofs and ceilings. `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).
@@ -186,6 +218,9 @@ export abstract class PluginDesignCreateApi {
    * Create a **slab** by extruding a footprint contour by `thickness`
    * (default direction: down).
    *
+   * To cut a hole in an EXISTING one, use `design.create.void`; a contour hole
+   * here is baked into the footprint.
+   *
    * @param contour - Footprint (outer + holes)
    * @param thickness - Slab thickness (> 0)
    * @param direction - Extrusion direction (default `"down"`)
@@ -207,20 +242,32 @@ export abstract class PluginDesignCreateApi {
    * ```
    */
   public abstract slab(
-    contour: ContourHandle,
-    thickness: number,
-    direction?: "up" | "down",
-    slabType?: PluginSlabType,
+    ...args:
+      | [
+          contour: ContourHandle,
+          thickness: number,
+          direction?: "up" | "down",
+          slabType?: PluginSlabType,
+        ]
+      | [contour: ContourHandle, options: PluginFamilySlabOptions]
   ): PluginApiReturn<ComponentHandle>
 
   /**
    * Create a **floor** by extruding a footprint contour by `thickness`
    * (extruded upward).
    *
+   * The native family overload takes `{ type, values?, position? }`. Contour
+   * geometry uses SU; family values use mm. The family supplies layer thickness.
+   * PG2 can split or merge the footprint, so both overloads return an array.
+   * A merge into an existing floor can return no newly created handles.
+   *
+   * To cut a hole in an EXISTING one, use `design.create.void`; a contour hole
+   * here is baked into the footprint.
+   *
    * @param contour - Footprint (outer + holes)
    * @param thickness - Floor thickness (> 0)
    * @param position - Offset from origin
-   * @returns the {@linkcode ComponentHandle} of the created floor
+   * @returns Newly created {@linkcode ComponentHandle}s; an empty array after a merge
    * @throws if the contour is invalid or the thickness is not positive
    *
    * @examplePrompt Create a floor from this room outline
@@ -234,17 +281,64 @@ export abstract class PluginDesignCreateApi {
    * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
    * const floor = await snaptrude.design.create.floor(contour, 0.1)
    * ```
+   *
+   * @performance For dimensional floors, `design.create.floors(items[])` uses one
+   *   host round-trip and one undo entry. That bulk method does not accept native
+   *   family options; use this method for a family-backed floor.
    */
   public abstract floor(
-    contour: ContourHandle,
-    thickness: number,
-    position?: Vec3Handle,
-  ): PluginApiReturn<ComponentHandle>
+    ...args:
+      | [contour: ContourHandle, thickness: number, position?: Vec3Handle]
+      | [contour: ContourHandle, options: PluginFamilyFloorOptions]
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * Create **many floors** in one undoable operation (bulk plural of
+   * {@linkcode floor}). Each item extrudes its own footprint contour (outer
+   * profile + holes) upward by its own `thickness`, at its own optional
+   * position offset. Validate-all-or-throw; one command.
+   *
+   * @param items - One {@linkcode PluginCreateFloorItem} per floor to create
+   *   (≥1, ≤1000)
+   * @returns the created floors as {@linkcode ComponentHandle}`[]`, in input order
+   * @throws `VALIDATION` if the items fail the schema (empty array, more than
+   *   1000 items, a non-positive thickness) or a contour is degenerate;
+   *   `HANDLE_INVALID` if a `contour` or `position` handle is unknown or
+   *   released; `OPERATION_FAILED` if extrusion fails (nothing is created —
+   *   `details.itemIndex` is the failing item); `METHOD_NOT_PERMITTED` if the
+   *   plugin may not write.
+   *
+   * @examplePrompt Create floors for all these room outlines at once
+   * @examplePrompt Add a floor to every space in one operation
+   * @examplePrompt Bulk create the floor plates for this building
+   * @examplePrompt Lay 100mm floors across these five footprints in one undo step
+   * @examplePrompt Create the ground and first floor slabs together
+   *
+   * @performance Bulk creator — the whole batch is ONE host round-trip and ONE undo
+   *   entry. Always prefer this over calling `design.create.floor` in a loop: build the
+   *   full `items[]` array first (all contours and offsets up front), then make one call.
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(5, 4)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const [ground, upper] = await snaptrude.design.create.floors([
+   *   { contour, thickness: 0.1 },
+   *   { contour, thickness: 0.1, position: await snaptrude.core.math.vec3.new(0, 3, 0) },
+   * ])
+   * ```
+   */
+  public abstract floors(
+    items: PluginCreateFloorItem[],
+  ): PluginApiReturn<ComponentHandle[]>
 
   /**
    * Create a **roof** by extruding a footprint contour by `thickness`. Created
    * flat (extruded downward); pitch/slope is a separate post-creation edit.
    *
+   * To cut a hole in an EXISTING one, use `design.create.void`; a contour hole
+   * here is baked into the footprint.
+   *
    * @param contour - Footprint (outer + holes)
    * @param thickness - Roof-slab thickness (> 0)
    * @returns the {@linkcode ComponentHandle} of the created roof
@@ -264,13 +358,16 @@ export abstract class PluginDesignCreateApi {
    */
   public abstract roof(
     contour: ContourHandle,
-    thickness: number,
+    thickness: number | PluginFamilyPlacement,
   ): PluginApiReturn<ComponentHandle>
 
   /**
    * Create a **ceiling** by extruding a footprint contour by `thickness`, lifted
    * `heightFromFloor` above the floor.
    *
+   * To cut a hole in an EXISTING one, use `design.create.void`; a contour hole
+   * here is baked into the footprint.
+   *
    * @param contour - Footprint (outer + holes)
    * @param thickness - Ceiling thickness (> 0)
    * @param heightFromFloor - Lift above the floor (default 0)
@@ -290,9 +387,9 @@ export abstract class PluginDesignCreateApi {
    * ```
    */
   public abstract ceiling(
-    contour: ContourHandle,
-    thickness: number,
-    heightFromFloor?: number,
+    ...args:
+      | [contour: ContourHandle, thickness: number, heightFromFloor?: number]
+      | [contour: ContourHandle, options: PluginFamilyCeilingOptions]
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -323,10 +420,14 @@ export abstract class PluginDesignCreateApi {
    * ```
    */
   public abstract column(
-    position: Vec3Handle,
-    crossSection: ContourHandle,
-    height: number,
-    directionUp?: Vec3Handle,
+    ...args:
+      | [
+          position: Vec3Handle,
+          crossSection: ContourHandle,
+          height: number,
+          directionUp?: Vec3Handle,
+        ]
+      | [axis: LineHandle, options: PluginFamilyPlacement]
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -370,9 +471,9 @@ export abstract class PluginDesignCreateApi {
    * ```
    */
   public abstract beam(
-    section: ContourHandle,
-    length: number,
-    direction?: Vec3Handle,
+    ...args:
+      | [section: ContourHandle, length: number, direction?: Vec3Handle]
+      | [axis: LineHandle, options: PluginFamilyPlacement]
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -383,21 +484,27 @@ export abstract class PluginDesignCreateApi {
    * @param height - Wall height (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 wallType - Legacy label/`wall:` id, or the exact `nativeFamily`
+   *   `{ id, version }` pin from `design.types.list("wall")`. Native pins are
+   *   authorized on every use; selecting a family in Draw is not registration.
+   *   Native pins support straight horizontal centerlines and flat tops only.
+   *   Omit thickness for native pins; a conflicting explicit thickness rejects.
+   *   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.
+   * @param topProfiles - Optional top edge per curve of `profile` (same order):
+   *   a {@linkcode PluginWallTopProfile} makes that wall raked / gabled; `null`
+   *   or a missing entry keeps it flat at `height`. Straight curves only. Such
+   *   walls are non-parametric (see {@linkcode PluginWallTopProfile}).
    * @returns a {@linkcode ComponentHandle}`[]` (one per wall), in profile order
    * @throws if the profile is empty, `wallType` names no wall type in the
-   *   project, `storey` does not exist, or wall creation fails
+   *   project, `storey` does not exist, `topProfiles` has more entries than the
+   *   profile has curves or names an arc curve, a top profile drops to the wall
+   *   base at a mitred corner, or wall creation fails
    *
    * @examplePrompt Draw walls along this centerline
    * @examplePrompt Create 3m high, 200mm thick walls from these points
@@ -406,6 +513,9 @@ export abstract class PluginDesignCreateApi {
    * @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
+   * @examplePrompt Create a raked wall that slopes from 3m to 5m
+   * @examplePrompt Build a gable end wall with the ridge in the middle
+   * @examplePrompt Draw a wall with a sloped top edge
    *
    * # Example
    * ```ts
@@ -421,16 +531,89 @@ export abstract class PluginDesignCreateApi {
    * const brickWalls = await snaptrude.design.create.walls(
    *   centerlines, 3, undefined, brick.label,
    * )
+   * // …a raked wall (3m at the start, 5m at the end) on a single centerline:
+   * const run = await snaptrude.core.geom.create.profileFromCurves([
+   *   await snaptrude.core.geom.create.line(await v.new(0, 0, 10), await v.new(8, 0, 10)),
+   * ])
+   * const [raked] = await snaptrude.design.create.walls(run, undefined, 0.2, undefined, undefined, [
+   *   [{ along: 0, height: 3 }, { along: 1, height: 5 }],
+   * ])
    * ```
+   *
+   * @performance For MORE THAN ONE run, call `design.create.wallRuns(items[])` — one
+   *   host round-trip and ONE undo entry for every run in the batch. Looping this
+   *   single-run creator is N round-trips and N undo entries.
    */
   public abstract walls(
     profile: ProfileHandle,
     height?: number,
     thickness?: number,
-    wallType?: string,
+    wallType?: PluginWallType,
     storey?: number,
+    topProfiles?: (PluginWallTopProfile | null)[],
+    values?: PluginFamilyValues,
   ): PluginApiReturn<ComponentHandle[]>
 
+  /**
+   * Create **many wall runs** in one undoable operation (bulk plural of
+   * {@linkcode walls}). Each item is one full run — a wall per curve in that
+   * item's profile chain, mitred at shared endpoints. Junctions resolve within a
+   * run, not between runs. Each item carries its own
+   * dimensions, `wallType` and `storey`, so a single call can build a whole
+   * floor plate or several storeys at once. Per-curve `topProfiles` make raked
+   * or gabled walls (see {@linkcode PluginWallTopProfile}). Validate-all-or-throw;
+   * one command.
+   *
+   * @param items - One {@linkcode PluginCreateWallRunItem} per run to create
+   *   (≥1, ≤1000)
+   * @returns one {@linkcode ComponentHandle}`[]` per item, in input order —
+   *   each inner array holding that run's walls in profile-curve order
+   * @throws `VALIDATION` if the items fail the schema (empty array, more than
+   *   1000 items, a non-positive height or thickness, a zero-length curve);
+   *   `HANDLE_INVALID` if a `profile` handle is unknown or released;
+   *   `PRECONDITION_FAILED` if a profile has no curves, `wallType` names no
+   *   wall type in the project, or `storey` does not exist;
+   *   `OPERATION_FAILED` if wall creation fails (nothing is created —
+   *   `details.itemIndex` is the failing item); `METHOD_NOT_PERMITTED` if the
+   *   plugin may not write.
+   *
+   * @examplePrompt Draw all the walls of this floor plan at once
+   * @examplePrompt Build every room's perimeter in one operation
+   * @examplePrompt Bulk create wall runs from these centerlines
+   * @examplePrompt Create the walls for both storeys in a single undo step
+   * @examplePrompt Turn these polylines into 200mm brick walls together
+   * @examplePrompt Import these raked walls with their top profiles in one go
+   *
+   * @performance Bulk creator — the whole batch is ONE host round-trip and ONE undo
+   *   entry. Always prefer this over calling `design.create.walls` in a loop: build the
+   *   full `items[]` array first (all profiles up front), then make one call.
+   *
+   * # Example
+   * ```ts
+   * const v = snaptrude.core.math.vec3
+   * const ground = await snaptrude.core.geom.create.profileFromLinePoints([
+   *   await v.new(0, 0, 0),
+   *   await v.new(8, 0, 0),
+   *   await v.new(8, 0, 6),
+   * ])
+   * const upper = await snaptrude.core.geom.create.profileFromLinePoints([
+   *   await v.new(0, 0, 0),
+   *   await v.new(8, 0, 0),
+   * ])
+   * const [groundWalls, upperWalls] = await snaptrude.design.create.wallRuns([
+   *   { profile: ground, height: 3, thickness: 0.2 },
+   *   { profile: upper, height: 3, storey: 2 },
+   *   // one gable wall: 3m at both ends, 5m ridge in the middle
+   *   { profile: upper, thickness: 0.2, storey: 3,
+   *     topProfiles: [[{ along: 0, height: 3 }, { along: 0.5, height: 5 }, { along: 1, height: 3 }]] },
+   * ])
+   * console.log(groundWalls.length, "walls on the ground floor")
+   * ```
+   */
+  public abstract wallRuns(
+    items: PluginCreateWallRunItem[],
+  ): PluginApiReturn<ComponentHandle[][]>
+
   /**
    * Create a **staircase** from a parametric preset, placed at a point.
    *
@@ -481,8 +664,14 @@ export abstract class PluginDesignCreateApi {
    * every created line.
    *
    * @param profile - Ordered curve chain (centerlines)
-   * @param color - Hex color `"#RRGGBB"` (default white)
-   * @param thickness - Line thickness (default 1)
+   * Prefer `{ styleId: "wide" }`: the project style's pen/pattern and native
+   * legacy mirror are saved in the creation command, as one undo step. styleId
+   * requires Paper Pens; unstyled legacy creation works with the feature off.
+   * Do not mix options with trailing positional arguments, or styleId with
+   * legacy thickness/style. The old positional signature remains supported.
+   *
+   * @param colorOrOptions - Options, or legacy hex color `"#RRGGBB"`.
+   * @param thickness - Legacy line thickness (default 1)
    * @param style - Line style (default `SOLID`)
    * @param gridTag - Grid tag label (default `"A"`)
    * @returns a {@linkcode ComponentHandle}`[]` (one per curve), in profile order
@@ -511,12 +700,140 @@ export abstract class PluginDesignCreateApi {
    */
   public abstract referenceLines(
     profile: ProfileHandle,
-    color?: string,
+    colorOrOptions?: string | PluginReferenceLineOptions,
     thickness?: number,
     style?: PluginReferenceLineStyle,
     gridTag?: string,
   ): PluginApiReturn<ComponentHandle[]>
 
+  /**
+   * Create a free rectangular **structural grid** — one grid group with two
+   * perpendicular line families (`linesX` lines spaced `spacingX` apart, and
+   * `linesY` lines spaced `spacingY` apart) on the active storey. One undoable
+   * creation.
+   *
+   * Units: spacings in Snaptrude units; `angle` in degrees (CCW about +Y,
+   * default 0). Without `center` the grid is centred on the current viewport
+   * (the native tool's behavior) — pass `center` for deterministic placement.
+   *
+   * @param linesX - Line count of the first family (integer ≥ 1)
+   * @param linesY - Line count of the second family (integer ≥ 1)
+   * @param spacingX - First-family spacing (Snaptrude units, > 0)
+   * @param spacingY - Second-family spacing (Snaptrude units, > 0)
+   * @param options - `angle`, `center`, and {@linkcode PluginGridStyleOptions}
+   * @returns the created grid group's {@linkcode ComponentHandle}
+   *
+   * @examplePrompt Create a 5 by 8 structural grid with 6 metre spacing
+   * @examplePrompt Add a column grid rotated 30 degrees
+   * @examplePrompt Set up a structural grid at the site origin
+   *
+   * # Example
+   * ```ts
+   * const centre = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const grid = await snaptrude.design.create.grid(5, 8, 6, 6, { center: centre })
+   * ```
+   */
+  public abstract grid(
+    linesX: number,
+    linesY: number,
+    spacingX: number,
+    spacingY: number,
+    options?: {
+      angle?: number
+      center?: Vec3Handle
+    } & PluginGridStyleOptions,
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * Create a **structural grid from a single curve** — one grid group holding
+   * one wing with one line (the draw tool's output). The curve may be a line
+   * or an arc; circles are rejected with `VALIDATION`. Undoable.
+   *
+   * @param curve - The grid line's geometry ({@linkcode CurveHandle}, world space)
+   * @param options - `tag` (defaults to the draw tool's next tag) and
+   *   {@linkcode PluginGridStyleOptions}
+   * @returns the created grid group's {@linkcode ComponentHandle}
+   *
+   * @examplePrompt Draw a grid line from A to B
+   * @examplePrompt Add a curved grid line through these points
+   * @examplePrompt Create grid line "C" along this wall
+   *
+   * # Example
+   * ```ts
+   * const { vec3 } = snaptrude.core.math
+   * const from = await vec3.new(0, 0, 0)
+   * const to = await vec3.new(30, 0, 0)
+   * const curve = await snaptrude.core.geom.create.line(from, to)
+   * const grid = await snaptrude.design.create.gridFromCurve(curve, { tag: "A" })
+   * ```
+   */
+  public abstract gridFromCurve(
+    curve: CurveHandle,
+    options?: {
+      tag?: string
+    } & PluginGridStyleOptions,
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * Generate **structural grids fitted to mass footprints** — one grid group
+   * per footprint cluster, with counts and orientation derived from each
+   * footprint's geometry and the given spacings. All created groups commit as
+   * ONE undoable unit.
+   *
+   * Lenient like the native tool: masses without an extractable footprint
+   * (no B-rep, degenerate top face) are skipped; throws `VALIDATION` only when
+   * NONE of the given masses yields a footprint.
+   *
+   * @param masses - Masses whose footprints seat the grids
+   * @param spacingX - First-family spacing (Snaptrude units, > 0)
+   * @param spacingY - Second-family spacing (Snaptrude units, > 0)
+   * @param options - {@linkcode PluginGridStyleOptions}
+   * @returns the created grid groups' {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt Generate grids for the selected masses
+   * @examplePrompt Auto-generate a 6m structural grid on this building
+   * @examplePrompt Fit column grids to every mass on this storey
+   *
+   * # Example
+   * ```ts
+   * const masses = await snaptrude.design.query.listMasses({ storeys: [1] })
+   * const grids = await snaptrude.design.create.gridsFromMasses(masses, 6, 6)
+   * ```
+   */
+  public abstract gridsFromMasses(
+    masses: ComponentHandle[],
+    spacingX: number,
+    spacingY: number,
+    options?: PluginGridStyleOptions,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * Create **columns at every grid-line intersection** of the given grid
+   * groups, sized `width` × `depth` and oriented to the grid axes, on the
+   * grids' storey. All columns commit as ONE undoable unit.
+   *
+   * @param grids - Grid groups whose intersections seat the columns
+   * @param width - Column width (Snaptrude units, > 0)
+   * @param depth - Column depth (Snaptrude units, > 0)
+   * @returns the created columns' {@linkcode ComponentHandle}`[]`
+   * @throws `VALIDATION` when an id does not resolve to a grid group;
+   *   `OPERATION_FAILED` when the grids have no line intersections
+   *
+   * @examplePrompt Generate columns on this grid
+   * @examplePrompt Place 450mm square columns at every grid intersection
+   *
+   * # Example
+   * ```ts
+   * const grids = await snaptrude.design.query.listGrids()
+   * const columns = await snaptrude.design.create.columnsFromGrids(grids, 0.45, 0.45)
+   * ```
+   */
+  public abstract columnsFromGrids(
+    grids: ComponentHandle[],
+    width: number,
+    depth: number,
+  ): PluginApiReturn<ComponentHandle[]>
+
   /**
    * Place a **furniture** item from the project library at a world position.
    *
@@ -535,15 +852,19 @@ export abstract class PluginDesignCreateApi {
    *   `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 options - Optional placement options: `label` — instance name and
+   *   readable label (`design.query.getLabel`; default auto `${name}Ins${n}`);
+   *   `createNewSourceMesh` — legacy flag, kept for compatibility. The host owns
+   *   source-mesh persistence: a catalog source is recorded exactly once, by the
+   *   first placement that brings it in, and this flag cannot skip that record.
    * @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
+   * @throws if the catalog id is unknown, the source mesh fails to load, or placement fails;
+   *   `PRECONDITION_FAILED` (`details.engineCode: "TOOL_ACTIVE"`) while the interactive
+   *   furniture tool is active — finish or cancel it first
    *
    * @examplePrompt Place a chair from the library at this spot
    * @examplePrompt Add a sofa from the furniture catalog to the living room
@@ -567,6 +888,10 @@ export abstract class PluginDesignCreateApi {
    *   90,
    * )
    * ```
+   *
+   * @performance For MORE THAN ONE item, call `design.create.furnitureItems(items[])` —
+   *   one host round-trip and ONE undo entry, and a catalog source shared by several
+   *   items is fetched once. Looping this single-item creator is N round-trips.
    */
   public abstract furniture(
     catalogId: string,
@@ -576,27 +901,69 @@ export abstract class PluginDesignCreateApi {
   ): PluginApiReturn<ComponentHandle>
 
   /**
-   * Place a **door** from the catalog into a host wall.
+   * Place **many furniture items** in one undoable operation (bulk plural of
+   * {@linkcode furniture}). Each item names a catalog id and an absolute world
+   * position (`position.y` is the REST elevation — the same grounding contract
+   * as the singular creator), with optional label and rotation. A catalog
+   * source shared by several items is fetched and recorded once for the whole
+   * batch, so the host — not the caller — owns source persistence (there is no
+   * per-item `createNewSourceMesh`). Validate-all-or-throw; one command.
+   *
+   * @param items - One {@linkcode PluginCreateFurnitureItem} per instance to
+   *   place (≥1, ≤1000)
+   * @returns the placed instances as {@linkcode ComponentHandle}`[]`, in input order
+   * @throws `VALIDATION` if the items fail the schema (empty array, more than
+   *   1000 items); `HANDLE_INVALID` if a `position` handle is unknown or
+   *   released; `PRECONDITION_FAILED` if a catalog id is unknown, a furniture
+   *   tool is active, or a parametric group is active (exit it first, or place
+   *   items one at a time with `furniture`); `OPERATION_FAILED` if a source
+   *   mesh fails to load or placement fails (nothing is created —
+   *   `details.itemIndex` is the failing item); `METHOD_NOT_PERMITTED` if the plugin may not write.
+   *
+   * @examplePrompt Place all the desks for this office at once
+   * @examplePrompt Furnish every bedroom in one operation
+   * @examplePrompt Bulk place these chairs around the table
+   * @examplePrompt Add the whole furniture layout in a single undo step
+   * @examplePrompt Drop twenty copies of this chair at these positions
+   *
+   * @performance Bulk creator — the whole batch is ONE host round-trip and ONE undo
+   *   entry, and each distinct catalog source loads once. Always prefer this over
+   *   calling `design.create.furniture` in a loop: build the full `items[]` array
+   *   first (all positions and angles up front), then make one call.
+   *
+   * # Example
+   * ```ts
+   * const v = snaptrude.core.math.vec3
+   * const [chair] = await snaptrude.design.furniture.listCatalog()
+   * const placed = await snaptrude.design.create.furnitureItems([
+   *   { catalogId: chair.id, position: await v.new(3, 0, 5), label: "Chair-01" },
+   *   { catalogId: chair.id, position: await v.new(4, 0, 5), angleInDegrees: 90 },
+   *   { catalogId: chair.id, position: await v.new(5, 0, 5), angleInDegrees: 180 },
+   * ])
+   * ```
+   */
+  public abstract furnitureItems(
+    items: PluginCreateFurnitureItem[],
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * Place a parametric **door** family 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
+   * Identified by a saved **family definition id**. 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).
+   * asynchronous. Values and host bindings are evaluated before the first cut.
    *
-   * @param catalogId - Library id: team `_id` or general `fullName`
+   * @param familyId - Hosted door definition ID; legacy mesh catalog IDs are not accepted
    * @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).
+   * @param options - `version` pins the definition. `values` sets authored parameters
+   *   (numeric lengths in SU, or unit strings). `label` names the instance.
+   *   `hinge` selects the declared `hand` enum: local -X is left, +X is right.
+   * @param facing - World point selecting local +Z; omitted uses the picked face
    * @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
+   * @throws if the family/category/parameters are invalid, or placement or cutting fails
    *
    * @examplePrompt Add a door to this wall here
    * @examplePrompt Place a sliding door on the selected wall
@@ -604,6 +971,7 @@ export abstract class PluginDesignCreateApi {
    * @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
+   * @examplePrompt Put a door here hinged on the north jamb
    *
    * # Example
    * ```ts
@@ -623,37 +991,100 @@ export abstract class PluginDesignCreateApi {
    *   undefined,
    *   await snaptrude.core.math.vec3.new(3, 0, 9),
    * )
+   * // …and hinged on the jamb nearest a point (here the +x end of the opening):
+   * const hingedRight = await snaptrude.design.create.door(
+   *   entry.id,
+   *   wall,
+   *   await snaptrude.core.math.vec3.new(3, 0, 5),
+   *   { hinge: await snaptrude.core.math.vec3.new(3.5, 0, 5) },
+   *   await snaptrude.core.math.vec3.new(3, 0, 9),
+   * )
    * ```
+   *
+   * @performance For MORE THAN ONE door, call `design.create.doors(items[])` — one host
+   *   round-trip and ONE undo entry, with each host wall re-cut once per opening inside
+   *   that single call. Looping this single-door creator is N round-trips.
    */
   public abstract door(
-    catalogId: string,
+    familyId: string,
     hostWall: ComponentHandle,
     position: Vec3Handle,
-    options?: { label?: string },
+    options?: {
+      label?: string
+      hinge?: Vec3Handle
+      version?: number
+      values?: Record<string, number | string>
+    },
     facing?: Vec3Handle,
   ): PluginApiReturn<ComponentHandle>
 
   /**
-   * Place a **window** from the catalog into a host wall.
+   * Place **many doors** into host walls in one undoable operation (bulk plural
+   * of {@linkcode door}). Each item carries its own family id, host wall,
+   * world position, and optional `facing`, `label`, `width` and `height` — the
+   * same fields as a `"door"` {@linkcode PluginDesignCreateOpeningOptions}.
+   * Validate-all-or-throw; one command.
+   *
+   * The wall keeps its identity. Several items may use the same host.
+   * Width and height set named recipe parameters, not mesh scale. The recipe's
+   * evaluated hole can include frame allowances. A failed item rolls back the batch.
+   *
+   * @param items - One {@linkcode PluginCreateDoorItem} per door to place
+   *   (≥1, ≤1000)
+   * @returns the placed doors as {@linkcode ComponentHandle}`[]`, in input order
+   * @throws `VALIDATION` if the items fail the schema (empty array, more than
+   *   1000 items, unknown fields, a non-positive `width`/`height`);
+   *   `HANDLE_INVALID` if a `position`, `facing` or `hinge` handle is unknown
+   *   or released; `PRECONDITION_FAILED` if the family cannot be resolved or saved,
+   *   or a host is locked / is not in the active proposal;
+   *   `OPERATION_FAILED` if placement, containment, overlap checks or cutting fail
+   *   (nothing is created — `details.itemIndex` is the failing item);
+   *   `METHOD_NOT_PERMITTED` if the plugin may not write.
+   *
+   * @examplePrompt Add doors to all of these walls at once
+   * @examplePrompt Place a door in every room in one operation
+   * @examplePrompt Bulk add the entrance doors from this schedule
+   * @examplePrompt Put three doors on this wall in a single undo step
+   * @examplePrompt Add all the doors for this floor plan together
+   *
+   * @performance Bulk creator — the whole batch is ONE host round-trip and ONE undo
+   *   entry. Always prefer this over
+   *   calling `design.create.door` in a loop: build the full `items[]` array first
+   *   (all host walls and points up front), then make one call.
    *
-   * Identified by a **catalog (library) id** — the team object's stable `_id`
-   * or the general library's `fullName`. Discover ids with
+   * # Example
+   * ```ts
+   * const v = snaptrude.core.math.vec3
+   * const [wall] = await snaptrude.design.query.listWalls({ isSelected: true })
+   * const [entry] = await snaptrude.design.doors.listCatalog()
+   * const [front, side] = await snaptrude.design.create.doors([
+   *   { familyId: entry.id, hostWall: wall, position: await v.new(2, 0, 5), label: "D-01" },
+   *   { familyId: entry.id, hostWall: wall, position: await v.new(6, 0, 5), values: { width: "1200mm" } },
+   * ])
+   * // The host still resolves after both cuts:
+   * const currentWall = await snaptrude.design.query.getHost(front)
+   * ```
+   */
+  public abstract doors(
+    items: PluginCreateDoorItem[],
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * Place a parametric **window** family into a host wall.
+   *
+   * Identified by a saved **family definition id**. 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).
+   * asynchronous. The sill parameter determines elevation; position Y is ignored.
    *
-   * @param catalogId - Library id: team `_id` or general `fullName`
+   * @param familyId - Hosted window definition ID; legacy mesh catalog IDs are not accepted
    * @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).
+   * @param options - `version`, `values`, `label`, and parameter-driven `hinge`, as for door
+   * @param facing - World point selecting local +Z; omitted uses the picked face
    * @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
+   * @throws if the family/category/parameters are invalid, or placement or cutting fails
    *
    * @examplePrompt Add a window to this wall here
    * @examplePrompt Place a casement window on the selected wall
@@ -673,40 +1104,244 @@ export abstract class PluginDesignCreateApi {
    *   { label: "Win-01" },
    * )
    * ```
+   *
+   * @performance For MORE THAN ONE window, call `design.create.windows(items[])` — one
+   *   host round-trip and ONE undo entry, with each host wall re-cut once per opening
+   *   inside that single call. Looping this single-window creator is N round-trips.
    */
   public abstract window(
-    catalogId: string,
+    familyId: string,
     hostWall: ComponentHandle,
     position: Vec3Handle,
-    options?: { label?: string },
+    options?: {
+      label?: string
+      hinge?: Vec3Handle
+      version?: number
+      values?: Record<string, number | string>
+    },
     facing?: Vec3Handle,
   ): PluginApiReturn<ComponentHandle>
 
   /**
-   * Place a catalog **door or window** into a host wall with optional size overrides.
+   * Place **many windows** into host walls in one undoable operation (bulk
+   * plural of {@linkcode window}). Each item carries its own family id, host
+   * wall, world position, and optional `facing`, `label`, `width`, `height` and
+   * `sillHeight` — the same fields as a `"window"`
+   * {@linkcode PluginDesignCreateOpeningOptions}. `sillHeight` is measured from
+   * the host wall base to the BOTTOM of the window. Validate-all-or-throw; one
+   * command.
+   *
+   * Hosts keep their identity. Width, height and sillHeight set the declared
+   * width, height and sill parameters before the first cut. No mesh scaling occurs.
+   *
+   * @param items - One {@linkcode PluginCreateWindowItem} per window to place
+   *   (≥1, ≤1000)
+   * @returns the placed windows as {@linkcode ComponentHandle}`[]`, in input order
+   * @throws `VALIDATION` if the items fail the schema (empty array, more than
+   *   1000 items, unknown fields, a non-positive `width`/`height`, a negative
+   *   `sillHeight`); `HANDLE_INVALID` if a `position`, `facing` or `hinge`
+   *   handle is unknown or released; `PRECONDITION_FAILED` if the family cannot be
+   *   resolved or saved, or a host is locked / is not in the active proposal;
+   *   `OPERATION_FAILED` if placement, containment, overlap checks or cutting fail
+   *   (nothing is created — `details.itemIndex` is the failing item);
+   *   `METHOD_NOT_PERMITTED` if the plugin may not write.
+   *
+   * @examplePrompt Add windows along this whole facade at once
+   * @examplePrompt Place a window in every bedroom in one operation
+   * @examplePrompt Bulk add the windows from this schedule
+   * @examplePrompt Put four windows on this wall in a single undo step
+   * @examplePrompt Add all the windows with a 0.9m sill height together
+   *
+   * @performance Bulk creator — the whole batch is ONE host round-trip and ONE undo
+   *   entry. Always prefer this over
+   *   calling `design.create.window` in a loop: build the full `items[]` array first
+   *   (all host walls and points up front), then make one call.
+   *
+   * # Example
+   * ```ts
+   * const v = snaptrude.core.math.vec3
+   * const [wall] = await snaptrude.design.query.listWalls({ isSelected: true })
+   * const [casement] = await snaptrude.design.windows.listCatalog()
+   * const placed = await snaptrude.design.create.windows([
+   *   { familyId: casement.id, hostWall: wall, position: await v.new(2, 0, 5), values: { sill: "900mm" } },
+   *   { familyId: casement.id, hostWall: wall, position: await v.new(5, 0, 5), values: { sill: "900mm" } },
+   * ])
+   * const currentWall = await snaptrude.design.query.getHost(placed[0])
+   * ```
+   */
+  public abstract windows(
+    items: PluginCreateWindowItem[],
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * Cut a **void** — a hole, opening or shaft — through an existing FLAT slab,
+   * floor, roof or ceiling. The void is a selectable child object of its host
+   * (the "Void" of the Draw Void tool). It always cuts the full host thickness.
+   * It can be moved with `design.transform.move` (a move that would leave the
+   * host is shortened without a report) and removed with
+   * `design.delete.entities`; to resize, delete it and cut a new one
+   * (`design.update.space` refuses a void).
+   *
+   * Give the outline **in plan** (all points at one height): its height is
+   * ignored, and it is dropped straight onto the host's top face, so one outline
+   * works on every storey. Keep it at least 25.4 mm (0.1 SU) inside the host
+   * edge and away from other voids; merge overlapping holes into one outline.
+   * Straight segments and arcs only (no splines).
+   *
+   * **A room has a floor finish AND a structural slab that overlap in plan; a
+   * void in one does not cut the other, so a through-opening needs one void in
+   * each.**
+   *
+   * `getEntityType` reports a void as `"void"`. Use `design.query.listVoids`
+   * or `listByType("void")`; `listMasses` excludes voids. `getHost` and
+   * `listChildren(host)` expose the host relationship, including after a copy.
+   * Authored parametric families with a cut relationship keep their family
+   * identity; discover those through family queries instead.
+   *
+   * Call it as `snaptrude.design.create.void(...)`; `void` is a reserved word and
+   * cannot be destructured. Voids in walls, on sloped, generated or multi-plane
+   * roofs, and on instanced hosts are not available yet; for a door or window
+   * use `design.create.door` / `window`. To make a NEW slab that already has a
+   * fixed hole, pass a contour with holes to `design.create.slab`; that hole is
+   * part of the footprint, not an object. For a contour's outer loop, pass
+   * `core.geom.query.contour.getOuterProfile(contour)`.
+   *
+   * # Example
+   * ```ts
+   * const m = 1000 / 254 // metres → Snaptrude units (SU)
+   * const [slab] = await snaptrude.design.query.listByType("slab", { isSelected: true })
+   * const center = await snaptrude.core.math.vec3.new(10 * m, 0, 5 * m) // plan point; y is ignored
+   * const outline = await snaptrude.core.geom.create.profileRect(2 * m, 2 * m, center) // 2 m x 2 m
+   * const hole = await snaptrude.design.create.void(slab, outline)
+   * ```
+   *
+   * A round hole is two arcs (a circle handle is not a profile):
+   * ```ts
+   * const m = 1000 / 254
+   * const { vec3 } = snaptrude.core.math
+   * const g = snaptrude.core.geom.create
+   * const r = 0.5 * m // 1 m diameter
+   * const centre = await vec3.new(10 * m, 0, 5 * m)
+   * const axis = await vec3.new(0, -1, 0)
+   * const east = await vec3.new(10 * m + r, 0, 5 * m)
+   * const west = await vec3.new(10 * m - r, 0, 5 * m)
+   * const round = await g.profileFromCurves([await g.arc(east, west, centre, axis), await g.arc(west, east, centre, axis)])
+   * await snaptrude.design.create.void(slab, round) // never destructure `void`
+   * ```
+   *
+   * @param host - The slab, floor, roof or ceiling to cut through
+   * @param outline - Closed, flat plan outline (world SU); its height is ignored
+   * @returns the {@linkcode ComponentHandle} of the new void
+   * @throws `VALIDATION` if the outline is open, crosses itself, is not flat or
+   *   has a spline, or the arguments are the wrong handle kinds or swapped;
+   *   `HANDLE_INVALID` if a handle is unknown or released or the host was
+   *   deleted; `HANDLE_STALE` if the host was rebuilt (re-query it);
+   *   `PRECONDITION_FAILED` if the
+   *   host is a wall or not a slab/floor/roof/ceiling, is sloped, instanced, in
+   *   another building, locked, outside the active proposal, a generated roof or
+   *   not a single plate, or there is no active structure (`engineCode`
+   *   `NO_ACTIVE_STRUCTURE`); `OPERATION_FAILED` with `engineCode`
+   *   `VOID_DOES_NOT_FIT` when the outline crosses the host edge, overlaps a void
+   *   or hole, is closer than 25.4 mm to either, or the fit could not be checked,
+   *   or another `engineCode` when the cut failed (nothing is created, except
+   *   `PUBLISH_FAILED` with a hint that the voids are in the scene: undo, then
+   *   retry); `METHOD_NOT_PERMITTED` if the plugin may not write.
+   *
+   * @examplePrompt Cut a hole in this slab
+   * @examplePrompt Add a 1.2m by 2.4m stair opening in the first-floor slab
+   * @examplePrompt Make a 600 x 600 service penetration in the floor for the riser
+   * @examplePrompt Put a skylight opening through the roof
+   * @examplePrompt Cut a round 1m duct hole in the slab
+   * @examplePrompt Make a cut-out in the ceiling for the light well
+   * @examplePrompt Add a double-height atrium void in the level 2 floor
+   *
+   * @performance Single-void creator. For MORE THAN ONE void, call
+   *   `design.create.voids(items[])`: one host round-trip, ONE undo entry, one cut
+   *   per host.
+   */
+  public abstract void(
+    host: ComponentHandle,
+    outline: ProfileHandle,
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * Cut **many voids** (holes, openings, shafts) through slabs, floors, roofs
+   * and ceilings in one undoable operation (bulk plural of {@linkcode void}).
+   * Items may share a host or use different hosts — one shaft outline on every
+   * storey's slab AND floor is one call. Validate-all-or-throw: one item whose
+   * host does not contain the outline rejects the whole batch, so pass only the
+   * hosts that contain it; `details.itemIndex` names the failing item (for two
+   * overlapping items of the batch, the earlier one). At most 50 voids per host
+   * and 200 in all per call. Same outline rules as {@linkcode void}: plan outline, 25.4 mm
+   * (0.1 SU) clearance, floor AND slab are separate hosts. Call it as
+   * `snaptrude.design.create.voids(...)`.
+   *
+   * # Example
+   * ```ts
+   * const m = 1000 / 254
+   * // The user selects the slabs AND floors the shaft passes through; every one must contain the outline.
+   * const hosts = [
+   *   ...(await snaptrude.design.query.listByType("slab", { isSelected: true })),
+   *   ...(await snaptrude.design.query.listByType("floor", { isSelected: true })),
+   * ]
+   * const centre = await snaptrude.core.math.vec3.new(12 * m, 0, -6 * m)
+   * const shaft = await snaptrude.core.geom.create.profileRect(2 * m, 2 * m, centre)
+   * const holes = await snaptrude.design.create.voids(hosts.map((host) => ({ host, outline: shaft })))
+   * ```
+   *
+   * @param items - One {@linkcode PluginCreateVoidItem} per void (≥1, ≤200; ≤50 per host)
+   * @returns the new voids as {@linkcode ComponentHandle}`[]`, in input order
+   * @throws `VALIDATION` if the items fail the schema (empty array, more than
+   *   1000 items, unknown fields), an outline is invalid (as for
+   *   {@linkcode void}), more than 50 items share one host, or there are more
+   *   than 200 items; plus every code {@linkcode void} throws, each with
+   *   `details.itemIndex`. Nothing is created on any failure, except
+   *   `PUBLISH_FAILED` (as for {@linkcode void}).
+   *
+   * @examplePrompt Cut a lift shaft through every floor slab of the core
+   * @examplePrompt Cut a 2m x 2m shaft through all the slabs at this location
+   * @examplePrompt Make stair openings in all the floors above the staircases
+   * @examplePrompt Make holes in the roof for these three skylights
+   * @examplePrompt Cut openings in each storey's slab matching this outline
+   * @examplePrompt Punch the same riser penetration through every floor at once
+   *
+   * @performance ONE host round-trip, ONE undo entry, ONE cut per host. Never call
+   *   `void` in a loop. Runs synchronously on the main thread: 50 voids on one
+   *   host take about 1 s, and the time grows with the number of hosts (caps:
+   *   50 per host, 200 per call).
+   */
+  public abstract voids(
+    items: PluginCreateVoidItem[],
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * Place a parametric **door or window** into a host wall with parameter 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
+   * Wall only. For a hole in a slab, floor or roof use `design.create.void`.
+   *
+   * @param options - Opening kind, family and host references, placement, and
+   *   optional facing (swing side), hinge (hinged jamb), 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
+   * @throws if the options are invalid, the family 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.
+   * @performance Single-opening creator — use it for one hosted opening. For MORE
+   *   THAN ONE, call `design.create.doors(items[])` / `design.create.windows(items[])`:
+   *   the same per-item fields, one host round-trip, ONE undo entry.
    *
    * # Example
    * ```ts
    * const opening = await snaptrude.design.create.opening({
    *   kind: "window",
-   *   catalogId: windowType.id,
+   *   familyId: windowType.id,
    *   hostWall: wall,
    *   position: await snaptrude.core.math.vec3.new(3, 0, 5),
    *   width: 1.2,
@@ -901,6 +1536,35 @@ export abstract class PluginDesignCreateApi {
     farRatio?: number,
     lotCoverageMaxPct?: number,
   ): PluginApiReturn<PluginBuildableEnvelopeCreateResult>
+
+  /**
+   * Create a default buildable envelope for an existing site — the same as the
+   * right panel's "Create Buildable Envelope" button. Front, side and rear
+   * distances are seeded from Site Analysis or the Program sheet, with a 10 ft
+   * fallback, and the envelope is linked to the site. Call it only after the
+   * user agrees (for example when `design.update.siteEdge` throws
+   * `NO_BUILDABLE_ENVELOPE`).
+   *
+   * @param siteId - Site component id, from `program.site.listEdges()`.
+   * @returns A {@linkcode PluginDesignCreateBuildableEnvelopeFromSiteResult}
+   *   with the `buildableEnvelopeId` of the created envelope.
+   * @throws `HANDLE_INVALID` for an unknown `siteId`. `PRECONDITION_FAILED`
+   *   (`details.reason: "SITE_HAS_ENVELOPE"`) when the site already has an
+   *   envelope.
+   *
+   * @examplePrompt Create a buildable envelope for this site with default setbacks
+   * @examplePrompt Add the zoning envelope to my site
+   *
+   * # Example
+   * ```ts
+   * const [{ siteId }] = (await snaptrude.program.site.listEdges()).sites
+   * const { buildableEnvelopeId } =
+   *   await snaptrude.design.create.buildableEnvelopeFromSite(siteId)
+   * ```
+   */
+  public abstract buildableEnvelopeFromSite(
+    siteId: string,
+  ): PluginApiReturn<PluginDesignCreateBuildableEnvelopeFromSiteResult>
 }
 
 // ---------------------------------------------------------------------------
@@ -1206,21 +1870,24 @@ export type PluginDesignCreateBeamArgs = z.infer<
  * | `profile` | {@linkcode ProfileHandle} | Ordered curve chain (wall centerlines) |
  * | `height` | `number`? | Wall height (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) |
+ * | `wallType` | {@linkcode PluginWallType}? | Legacy name/id or exact native `{ id, version }` pin from `design.types.list("wall")` (default generic) |
  * | `storey` | `number`? | Target storey (integer, must exist) — walls assigned + lifted to its base in the same undo entry (default: geometry-derived) |
+ * | `topProfiles` | ({@linkcode PluginWallTopProfile} \| `null`)[]? | Top edge per curve (same order); `null`/missing = flat at `height`. Straight curves only |
  */
 export const PluginDesignCreateWallsArgs = z.object({
   profile: ProfileHandle,
   height: z.number().optional(),
   thickness: z.number().optional(),
-  wallType: z.string().min(1).optional(),
+  wallType: PluginWallType.optional(),
   storey: z.number().int().optional(),
+  topProfiles: z.array(PluginWallTopProfile.nullable()).optional(),
+  values: PluginFamilyValues.optional(),
 })
 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)
+// TRANSPORT: positional signature shipped — storey is the 5th arg, topProfiles the trailing 6th:
+//   walls(profile: ProfileHandle, height?: number, thickness?: number, wallType?: string, storey?: number, topProfiles?: (PluginWallTopProfile | null)[])
 
 // ---------------------------------------------------------------------------
 // staircase
@@ -1262,7 +1929,7 @@ export type PluginDesignCreateStaircaseArgs = z.infer<
  * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
  * | `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`) |
+ * | `createNewSourceMesh` | `boolean`? | Legacy, kept for compatibility; the host records a catalog source exactly once and this flag cannot skip it |
  * | `angleInDegrees` | `number`? | Rotation about the vertical axis, in degrees (default unrotated) |
  */
 export const PluginDesignCreateFurnitureArgs = z.object({
@@ -1287,24 +1954,23 @@ export type PluginDesignCreateFurnitureArgs = z.infer<
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `familyId` | `string` | Hosted door family definition ID |
+ * | `version` | `number`? | Exact version; newest known by default |
+ * | `values` | `Record<string, number \| string>`? | Parameters; numeric lengths use SU |
  * | `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) |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the door swings open to (default engine-chosen) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the hinged jamb; requires hand control |
  */
 export const PluginDesignCreateDoorArgs = z.object({
-  catalogId: z.string().min(1),
-  hostWall: ComponentHandle,
-  position: Vec3Handle,
-  label: z.string().optional(),
-  facing: Vec3Handle.optional(),
+  ...PluginOpeningBaseOptions,
 })
 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)
+// TRANSPORT: positional signature shipped — facing is the trailing 5th arg, hinge rides in options:
+//   door(familyId, hostWall, position, options?: { label?, hinge?, version?, values? }, facing?)
 
 // ---------------------------------------------------------------------------
 // window
@@ -1315,39 +1981,28 @@ export type PluginDesignCreateDoorArgs = z.infer<
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `familyId` | `string` | Hosted window family definition ID |
+ * | `version` | `number`? | Exact version; newest known by default |
+ * | `values` | `Record<string, number \| string>`? | Parameters; numeric lengths use SU |
  * | `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) |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the window opens to (default engine-chosen) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the hinged jamb; requires hand control |
  */
 export const PluginDesignCreateWindowArgs = z.object({
-  catalogId: z.string().min(1),
-  hostWall: ComponentHandle,
-  position: Vec3Handle,
-  label: z.string().optional(),
-  facing: Vec3Handle.optional(),
+  ...PluginOpeningBaseOptions,
 })
 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)
+// TRANSPORT: positional signature shipped — facing is the trailing 5th arg, hinge rides in options:
+//   window(familyId, hostWall, position, options?: { label?, hinge?, version?, values? }, facing?)
 
 // ---------------------------------------------------------------------------
 // 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.
@@ -1446,13 +2101,63 @@ export type PluginSmartLayoutResult = z.infer<typeof PluginSmartLayoutResult>
  * | `style` | {@linkcode PluginReferenceLineStyle}? | Line style (default `SOLID`) |
  * | `gridTag` | `string`? | Grid tag label (default `"A"`) |
  */
-export const PluginDesignCreateReferenceLinesArgs = z.object({
-  profile: ProfileHandle,
-  color: z.string().optional(),
-  thickness: z.number().optional(),
-  style: PluginReferenceLineStyle.optional(),
-  gridTag: z.string().optional(),
-})
+/**
+ * Reference-line creation options. styleId selects a project pen/pattern; its
+ * native legacy mirror is saved too. Omitted options preserve tool defaults.
+ */
+export const PluginReferenceLineOptions = z
+  .object({
+    styleId: PluginGraphicsLineStyleId.optional(),
+    color: z
+      .string()
+      .regex(/^#[0-9a-f]{6}$/i)
+      .optional(),
+    thickness: z.number().finite().positive().optional(),
+    style: PluginReferenceLineStyle.optional(),
+  })
+  .strict()
+  .superRefine((options, ctx) => {
+    if (
+      options.styleId !== undefined &&
+      (options.thickness !== undefined || options.style !== undefined)
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        message: "styleId cannot be combined with legacy thickness or style",
+      })
+    }
+  })
+export type PluginReferenceLineOptions = z.infer<
+  typeof PluginReferenceLineOptions
+>
+
+/**
+ * Normalized arguments. The host maps the second positional argument to either
+ * the legacy color field or options; mixing those forms is rejected atomically.
+ */
+export const PluginDesignCreateReferenceLinesArgs = z
+  .object({
+    profile: ProfileHandle,
+    options: PluginReferenceLineOptions.optional(),
+    color: z.string().optional(),
+    thickness: z.number().finite().optional(),
+    style: PluginReferenceLineStyle.optional(),
+    gridTag: z.string().optional(),
+  })
+  .strict()
+  .superRefine((args, ctx) => {
+    if (
+      args.options !== undefined &&
+      [args.color, args.thickness, args.style, args.gridTag].some(
+        (v) => v !== undefined,
+      )
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        message: "Options cannot be combined with legacy positional arguments",
+      })
+    }
+  })
 export type PluginDesignCreateReferenceLinesArgs = z.infer<
   typeof PluginDesignCreateReferenceLinesArgs
 >
@@ -1524,3 +2229,7 @@ export const PluginCreateSpaceItem = z.object({
   storey: z.number().int().optional(),
 })
 export type PluginCreateSpaceItem = z.infer<typeof PluginCreateSpaceItem>
+
+export * from "./opening-fields"
+export * from "./bulk-items"
+export * from "./grids"