@snaptrude/plugin-core 0.9.16 → 0.9.18-networks-20261016.1

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

@@ -1,1980 +1,2148 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../types"
-import {
-  BrepHandle,
-  ComponentHandle,
-  ContourHandle,
-  CurveHandle,
-  ProfileHandle,
-  Vec3Handle,
-} from "../../../handles"
-import { PluginGridStyleOptions } from "./grids"
-import {
-  PluginSpaceType,
-  PluginMassType,
-  PluginDepartmentId,
-} from "../../entity/space"
-import {
-  PluginBuildableEnvelopePolygonVertex,
-  PluginBuildableEnvelopeSetbackTier,
-  PluginBuildableEnvelopeVerticalCap,
-  PluginBuildableEnvelopeCreateResult,
-} from "../../entity/buildableEnvelope"
-import { PluginOpeningBaseOptions } from "./opening-fields"
-import type {
-  PluginCreateDoorItem,
-  PluginCreateFloorItem,
-  PluginCreateFurnitureItem,
-  PluginCreateWallRunItem,
-  PluginCreateWindowItem,
-} from "./bulk-items"
-import { PluginWallTopProfile } from "./bulk-items"
-
-/**
- * `design.create.*` — author new scene-committed BIM entities.
- *
- * Every creator takes geometry handles + scalars and returns a
- * {@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.*`).
- *
- * 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 {
-  constructor() {}
-
-  /**
-   * Create a **space** (a room / mass) by extruding a footprint contour upward.
-   *
-   * The `contour` is the bottom footprint (outer profile + optional holes); it
-   * is extruded by `height` along +Y. The space is placed on the active story
-   * and assigned a default department unless overridden.
-   *
-   * @param contour - Bottom footprint (outer + holes)
-   * @param height - Extrusion height (Snaptrude units, > 0)
-   * @param label - Room label (maps to the space's `room_type`)
-   * @param position - Offset from origin (default origin)
-   * @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, 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
-   * const v = snaptrude.core.math.vec3
-   * const outer = await snaptrude.core.geom.create.profileFromLinePoints([
-   *   await v.new(0, 0, 0),
-   *   await v.new(10, 0, 0),
-   *   await v.new(10, 0, 8),
-   *   await v.new(0, 0, 8),
-   * ])
-   * 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(
-    contour: ContourHandle,
-    height: number,
-    label?: string,
-    position?: Vec3Handle,
-    spaceType?: PluginSpaceType,
-    massType?: PluginMassType,
-    departmentId?: PluginDepartmentId,
-    storey?: number,
-  ): PluginApiReturn<ComponentHandle>
-
-  /**
-   * Create a **mass** — a generic extruded prism (default `massType` "Generic mass").
-   * Same footprint-extrude path as {@linkcode PluginDesignCreateApi.space}.
-   *
-   * @param contour - Footprint (outer + holes)
-   * @param height - Extrusion height (> 0)
-   * @param label - Label (maps to `room_type`)
-   * @param position - Offset from origin
-   * @param massType - Mass type (default `Generic mass`)
-   * @returns the {@linkcode ComponentHandle} of the created mass
-   * @throws if the contour is invalid or the height is not positive
-   *
-   * @examplePrompt Create a generic mass 30m tall from this footprint
-   * @examplePrompt Block out a conceptual massing volume for the site
-   * @examplePrompt Extrude this shape into a building mass
-   * @examplePrompt Add a simple study-model volume at the origin
-   *
-   * # Example
-   * ```ts
-   * const rect = await snaptrude.core.geom.create.profileRect(20, 15)
-   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
-   * const tower = await snaptrude.design.create.mass(contour, 30, "Tower A", undefined, "Building")
-   * ```
-   */
-  public abstract mass(
-    contour: ContourHandle,
-    height: number,
-    label?: string,
-    position?: Vec3Handle,
-    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).
-   *
-   * @param contour - Footprint (outer + holes)
-   * @param thickness - Slab thickness (> 0)
-   * @param direction - Extrusion direction (default `"down"`)
-   * @param slabType - Slab-type classification
-   * @returns the {@linkcode ComponentHandle} of the created slab
-   * @throws if the contour is invalid or the thickness is not positive
-   *
-   * @examplePrompt Add a 150mm thick slab under this footprint
-   * @examplePrompt Create a floor slab from this outline
-   * @examplePrompt Pour a plinth slab over the building footprint
-   * @examplePrompt Make a basement slab that extrudes downward
-   * @examplePrompt Give this room outline a 6 inch slab
-   *
-   * # Example
-   * ```ts
-   * const rect = await snaptrude.core.geom.create.profileRect(12, 10)
-   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
-   * const slab = await snaptrude.design.create.slab(contour, 0.15, "down", "Plinth")
-   * ```
-   */
-  public abstract slab(
-    contour: ContourHandle,
-    thickness: number,
-    direction?: "up" | "down",
-    slabType?: PluginSlabType,
-  ): PluginApiReturn<ComponentHandle>
-
-  /**
-   * Create a **floor** by extruding a footprint contour by `thickness`
-   * (extruded upward).
-   *
-   * @param contour - Footprint (outer + holes)
-   * @param thickness - Floor thickness (> 0)
-   * @param position - Offset from origin
-   * @returns the {@linkcode ComponentHandle} of the created floor
-   * @throws if the contour is invalid or the thickness is not positive
-   *
-   * @examplePrompt Create a floor from this room outline
-   * @examplePrompt Add a 100mm thick floor over the footprint
-   * @examplePrompt Lay flooring across the selected outline
-   * @examplePrompt Put a floor at this position with 150mm thickness
-   *
-   * # Example
-   * ```ts
-   * const rect = await snaptrude.core.geom.create.profileRect(5, 4)
-   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
-   * const floor = await snaptrude.design.create.floor(contour, 0.1)
-   * ```
-   *
-   * @performance For MORE THAN ONE floor, call `design.create.floors(items[])` — one
-   *   host round-trip and ONE undo entry for the whole batch. Looping this single-floor
-   *   creator is N round-trips and N undo entries.
-   */
-  public abstract floor(
-    contour: ContourHandle,
-    thickness: number,
-    position?: Vec3Handle,
-  ): 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.
-   *
-   * @param contour - Footprint (outer + holes)
-   * @param thickness - Roof-slab thickness (> 0)
-   * @returns the {@linkcode ComponentHandle} of the created roof
-   * @throws if the contour is invalid or the thickness is not positive
-   *
-   * @examplePrompt Add a flat roof over the building footprint
-   * @examplePrompt Create a roof 200mm thick from this outline
-   * @examplePrompt Cover the top storey with a roof slab
-   * @examplePrompt Put a roof on this building
-   *
-   * # Example
-   * ```ts
-   * const rect = await snaptrude.core.geom.create.profileRect(12, 10)
-   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
-   * const roof = await snaptrude.design.create.roof(contour, 0.2)
-   * ```
-   */
-  public abstract roof(
-    contour: ContourHandle,
-    thickness: number,
-  ): PluginApiReturn<ComponentHandle>
-
-  /**
-   * Create a **ceiling** by extruding a footprint contour by `thickness`, lifted
-   * `heightFromFloor` above the floor.
-   *
-   * @param contour - Footprint (outer + holes)
-   * @param thickness - Ceiling thickness (> 0)
-   * @param heightFromFloor - Lift above the floor (default 0)
-   * @returns the {@linkcode ComponentHandle} of the created ceiling
-   * @throws if the contour is invalid or the thickness is not positive
-   *
-   * @examplePrompt Add a false ceiling 2.7m above the floor
-   * @examplePrompt Create a ceiling over this room footprint
-   * @examplePrompt Put a dropped ceiling in the living room at 3 metres
-   * @examplePrompt Add a 50mm thick ceiling lifted 2800mm from floor level
-   *
-   * # Example
-   * ```ts
-   * const rect = await snaptrude.core.geom.create.profileRect(5, 4)
-   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
-   * const ceiling = await snaptrude.design.create.ceiling(contour, 0.05, 2.8)
-   * ```
-   */
-  public abstract ceiling(
-    contour: ContourHandle,
-    thickness: number,
-    heightFromFloor?: number,
-  ): PluginApiReturn<ComponentHandle>
-
-  /**
-   * Create a **column** by extruding a cross-section contour upward by `height`
-   * 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), 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, 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
-   * @examplePrompt Create a 450mm square concrete column 4 metres high
-   * @examplePrompt Stand a column up from this base point
-   *
-   * # Example
-   * ```ts
-   * const rect = await snaptrude.core.geom.create.profileRect(0.45, 0.45)
-   * const crossSection = await snaptrude.core.geom.create.contourFromProfile(rect)
-   * const base = await snaptrude.core.math.vec3.new(4, 0, 4)
-   * const column = await snaptrude.design.create.column(base, crossSection, 3)
-   * ```
-   */
-  public abstract column(
-    position: Vec3Handle,
-    crossSection: ContourHandle,
-    height: number,
-    directionUp?: Vec3Handle,
-  ): PluginApiReturn<ComponentHandle>
-
-  /**
-   * Create a **beam** by extruding a cross-section contour along `direction` by
-   * `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.
-   *
-   * 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 (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
-   * @examplePrompt Run a 300x600 beam across the room
-   * @examplePrompt Extrude this cross-section into a 5m long beam
-   *
-   * # Example
-   * ```ts
-   * const rect = await snaptrude.core.geom.create.profileRect(0.3, 0.6)
-   * const section = await snaptrude.core.geom.create.contourFromProfile(rect)
-   * const alongX = await snaptrude.core.math.vec3.new(1, 0, 0)
-   * const beam = await snaptrude.design.create.beam(section, 6, alongX)
-   * ```
-   */
-  public abstract beam(
-    section: ContourHandle,
-    length: number,
-    direction?: Vec3Handle,
-  ): PluginApiReturn<ComponentHandle>
-
-  /**
-   * Create a connected run of **walls** from a profile — one wall per curve in
-   * the profile's chain, with mitred corners at shared endpoints.
-   *
-   * @param profile - Ordered curve chain (wall centerlines)
-   * @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 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, `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
-   * @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
-   * @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
-   * const v = snaptrude.core.math.vec3
-   * const centerlines = 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 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,
-   * )
-   * // …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,
-    storey?: number,
-    topProfiles?: (PluginWallTopProfile | null)[],
-  ): 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.
-   *
-   * 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
-   *
-   * @examplePrompt Add a dog-legged staircase at this location
-   * @examplePrompt Place a straight stair on level 01
-   * @examplePrompt Create an L-shaped staircase in the lobby
-   * @examplePrompt Insert a staircase near the entrance
-   * @examplePrompt Put amphitheatre steps at these coordinates
-   *
-   * # Example
-   * ```ts
-   * const stair = await snaptrude.design.create.staircase(
-   *   "dogLegged",
-   *   await snaptrude.core.math.vec3.new(5, 0, 5),
-   * )
-   * ```
-   */
-  public abstract staircase(
-    preset: PluginStaircasePreset,
-    position: Vec3Handle,
-    label?: string,
-    structureId?: string,
-    level?: string,
-    dimensions?: PluginStaircaseDimensions,
-  ): PluginApiReturn<ComponentHandle>
-
-  /**
-   * Create **reference lines** from a profile — one reference line per curve in
-   * the profile's ordered chain. Returns a handle per created line.
-   *
-   * Optional style (`color`, `thickness`, `style`, `gridTag`) applies to
-   * every created line.
-   *
-   * @param profile - Ordered curve chain (centerlines)
-   * @param color - Hex color `"#RRGGBB"` (default white)
-   * @param thickness - 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
-   * @throws if the profile is empty or creation fails
-   *
-   * @examplePrompt Draw a reference line between these two points
-   * @examplePrompt Add dashed guide lines along this path
-   * @examplePrompt Create grid lines tagged A through the plan
-   * @examplePrompt Set up construction lines for the column grid
-   * @examplePrompt Mark a red reference line across the site
-   *
-   * # Example
-   * ```ts
-   * const v = snaptrude.core.math.vec3
-   * const profile = await snaptrude.core.geom.create.profileFromLinePoints([
-   *   await v.new(0, 0, 0),
-   *   await v.new(10, 0, 0),
-   * ])
-   * const lines = await snaptrude.design.create.referenceLines(
-   *   profile,
-   *   undefined,
-   *   undefined,
-   *   "DASHED",
-   * )
-   * ```
-   */
-  public abstract referenceLines(
-    profile: ProfileHandle,
-    color?: string,
-    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.
-   *
-   * Identified by a **catalog (library) id** — the team object's stable `_id` for
-   * project uploads, or the item's `fullName` for the general library. Discover ids
-   * 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 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. `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 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;
-   *   `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
-   * @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
-   * const chair = await snaptrude.design.create.furniture(
-   *   "6620f1a…",             // from design.furniture.listCatalog()
-   *   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,
-   * )
-   * ```
-   *
-   * @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,
-    position: Vec3Handle,
-    options?: { label?: string; createNewSourceMesh?: boolean },
-    angleInDegrees?: number,
-  ): PluginApiReturn<ComponentHandle>
-
-  /**
-   * 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 **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;
-   *   `hinge` — world point near the jamb the door is hinged on (the door is
-   *   reflected along the wall so its hinged jamb is the one nearer this
-   *   point; default the catalog item's authored hinge side)
-   * @param facing - World point on the side of the wall the door swings open
-   *   to (the room it opens into — where the plan symbol draws the swing arc).
-   *   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
-   * @examplePrompt Put a door here hinged on the north jamb
-   *
-   * # 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),
-   * )
-   * // …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,
-    hostWall: ComponentHandle,
-    position: Vec3Handle,
-    options?: { label?: string; hinge?: Vec3Handle },
-    facing?: Vec3Handle,
-  ): PluginApiReturn<ComponentHandle>
-
-  /**
-   * Place **many doors** into host walls in one undoable operation (bulk plural
-   * of {@linkcode door}). Each item carries its own catalog 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.
-   *
-   * As with the singular creator, placing an opening **re-cuts its host wall**:
-   * the wall you passed as `hostWall` stops resolving once the call returns.
-   * Several items MAY name the same original wall handle in one call — the host
-   * chains the re-cuts internally — but after the call recover the surviving
-   * wall with `design.query.getHost(opening)`, never by reusing the handle you
-   * passed in.
-   *
-   * @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 a catalog id is unknown, a `hostWall`
-   *   is not a wall / is locked / is not in the active proposal, the projected
-   *   point falls outside its host wall, or a door tool is active;
-   *   `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 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, and each distinct catalog source loads once. 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.
-   *
-   * # 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([
-   *   { catalogId: entry.id, hostWall: wall, position: await v.new(2, 0, 5), label: "D-01" },
-   *   { catalogId: entry.id, hostWall: wall, position: await v.new(6, 0, 5), width: 1.2 },
-   * ])
-   * // `wall` was re-cut twice and no longer resolves — ask the opening for its host:
-   * const currentWall = await snaptrude.design.query.getHost(front)
-   * ```
-   */
-  public abstract doors(
-    items: PluginCreateDoorItem[],
-  ): 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;
-   *   `hinge` — world point near the jamb the window is hinged on (same rule
-   *   as {@linkcode PluginDesignCreateApi.door}; default the catalog item's
-   *   authored side)
-   * @param facing - World point on the side of the wall the window opens to
-   *   (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" },
-   * )
-   * ```
-   *
-   * @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,
-    hostWall: ComponentHandle,
-    position: Vec3Handle,
-    options?: { label?: string; hinge?: Vec3Handle },
-    facing?: Vec3Handle,
-  ): PluginApiReturn<ComponentHandle>
-
-  /**
-   * Place **many windows** into host walls in one undoable operation (bulk
-   * plural of {@linkcode window}). Each item carries its own catalog 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.
-   *
-   * As with the singular creator, placing an opening **re-cuts its host wall**:
-   * the wall you passed as `hostWall` stops resolving once the call returns.
-   * Several items MAY name the same original wall handle in one call — the host
-   * chains the re-cuts internally — but after the call recover the surviving
-   * wall with `design.query.getHost(opening)`, never by reusing the handle you
-   * passed in.
-   *
-   * @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 a catalog id is unknown, a
-   *   `hostWall` is not a wall / is locked / is not in the active proposal, the
-   *   projected point falls outside its host wall, or a window tool is active;
-   *   `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 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, and each distinct catalog source loads once. 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([
-   *   { catalogId: casement.id, hostWall: wall, position: await v.new(2, 0, 5), sillHeight: 0.9 },
-   *   { catalogId: casement.id, hostWall: wall, position: await v.new(5, 0, 5), sillHeight: 0.9 },
-   * ])
-   * const currentWall = await snaptrude.design.query.getHost(placed[0])
-   * ```
-   */
-  public abstract windows(
-    items: PluginCreateWindowItem[],
-  ): 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 (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
-   *   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. 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,
-   *   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
-   * @examplePrompt Make 5 copies of this column at 4 metre intervals
-   * @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
-   * const copies = await snaptrude.design.create.copy(["space-id"], vec3.new(6, 0, 0), { count: 3 })
-   * ```
-   */
-  public abstract copy(
-    components: ComponentHandle[],
-    displacement: Vec3Handle,
-    options?: { count?: number; mode?: PluginCopyMode },
-  ): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * Create **many spaces** in one undoable operation (bulk plural of {@linkcode space}).
-   * 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. 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
-   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
-   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
-   * const [a, b] = await snaptrude.design.create.spaces([
-   *   { contour, height: 3, label: "R1" },
-   *   { contour, height: 4, label: "R2", position: await vec3.new(10, 0, 0) },
-   * ])
-   * ```
-   */
-  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>
-}
-
-// ---------------------------------------------------------------------------
-// Enums
-// ---------------------------------------------------------------------------
-
-/**
- * Line style of a reference line (mirrors the engine `ReferenceLineMode` verbatim).
- *
- * | Value | Description |
- * |---|---|
- * | `"SOLID"` | Solid line (default) |
- * | `"DASHED"` | Dashed line |
- * | `"DOT_DASH"` | Dot-dash line |
- */
-export const PluginReferenceLineStyle = z.enum(["SOLID", "DASHED", "DOT_DASH"])
-export type PluginReferenceLineStyle = z.infer<typeof PluginReferenceLineStyle>
-
-/**
- * Slab type (mirrors the engine `SLAB_TYPES` values verbatim).
- *
- * | Value | Description |
- * |---|---|
- * | `"Intermediate Slab"` | Intermediate floor slab (default) |
- * | `"Basement Slab"` | Basement slab |
- * | `"Plinth"` | Plinth slab |
- * | `"Roof"` | Roof slab |
- */
-export const PluginSlabType = z.enum([
-  "Intermediate Slab",
-  "Basement Slab",
-  "Plinth",
-  "Roof",
-])
-export type PluginSlabType = z.infer<typeof PluginSlabType>
-
-/**
- * A staircase preset — a base type or a named parametric preset. Mirrors the
- * engine `STAIRCASE_PRESETS` / `StaircaseType`. Use the value that matches the
- * shape you want (e.g. `"straight"`, `"dogLegged"`, `"lShaped"`).
- */
-export const PluginStaircasePreset = z.enum([
-  "straight",
-  "straightWoLanding",
-  "straightFlightWoMidLanding",
-  "dogLegged",
-  "openWell",
-  "lShaped",
-  "3StepLShaped",
-  "square",
-  "singleStep",
-  "plinthLevel",
-  "amphitheatre",
-  "connectingStepsToAmphitheatre",
-  "mezzanineFloorStraight",
-  "mezzanineFloorDogLegged",
-  "mezzanineFloorLShaped",
-  "custom",
-])
-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
-// ---------------------------------------------------------------------------
-
-/**
- * Arguments for {@linkcode PluginDesignCreateApi.space}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `contour` | {@linkcode ContourHandle} | Bottom footprint (outer + holes) |
- * | `height` | `number` | Extrusion height (Snaptrude units, > 0) |
- * | `label` | `string`? | Room label (maps to the space's `room_type`) |
- * | `position` | {@linkcode Vec3Handle}? | Offset from origin (default origin) |
- * | `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,
-  height: z.number(),
-  label: z.string().optional(),
-  position: Vec3Handle.optional(),
-  spaceType: PluginSpaceType.optional(),
-  massType: PluginMassType.optional(),
-  departmentId: PluginDepartmentId.optional(),
-  storey: z.number().int().optional(),
-})
-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
-// ---------------------------------------------------------------------------
-
-/**
- * Arguments for {@linkcode PluginDesignCreateApi.mass}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `contour` | {@linkcode ContourHandle} | Footprint (outer + holes) |
- * | `height` | `number` | Extrusion height (> 0) |
- * | `label` | `string`? | Label (maps to `room_type`) |
- * | `position` | {@linkcode Vec3Handle}? | Offset from origin |
- * | `massType` | {@linkcode PluginMassType}? | Mass type (default `Generic mass`) |
- */
-export const PluginDesignCreateMassArgs = z.object({
-  contour: ContourHandle,
-  height: z.number(),
-  label: z.string().optional(),
-  position: Vec3Handle.optional(),
-  massType: PluginMassType.optional(),
-})
-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
-// ---------------------------------------------------------------------------
-
-/**
- * Arguments for {@linkcode PluginDesignCreateApi.slab}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `contour` | {@linkcode ContourHandle} | Footprint (outer + holes) |
- * | `thickness` | `number` | Slab thickness (> 0) |
- * | `direction` | `"up" \| "down"`? | Extrusion direction (default `"down"`) |
- * | `slabType` | {@linkcode PluginSlabType}? | Slab-type classification |
- */
-export const PluginDesignCreateSlabArgs = z.object({
-  contour: ContourHandle,
-  thickness: z.number(),
-  direction: z.enum(["up", "down"]).optional(),
-  slabType: PluginSlabType.optional(),
-})
-export type PluginDesignCreateSlabArgs = z.infer<
-  typeof PluginDesignCreateSlabArgs
->
-
-// ---------------------------------------------------------------------------
-// floor
-// ---------------------------------------------------------------------------
-
-/**
- * Arguments for {@linkcode PluginDesignCreateApi.floor}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `contour` | {@linkcode ContourHandle} | Footprint (outer + holes) |
- * | `thickness` | `number` | Floor thickness (> 0) |
- * | `position` | {@linkcode Vec3Handle}? | Offset from origin |
- */
-export const PluginDesignCreateFloorArgs = z.object({
-  contour: ContourHandle,
-  thickness: z.number(),
-  position: Vec3Handle.optional(),
-})
-export type PluginDesignCreateFloorArgs = z.infer<
-  typeof PluginDesignCreateFloorArgs
->
-
-// ---------------------------------------------------------------------------
-// roof
-// ---------------------------------------------------------------------------
-
-/**
- * Arguments for {@linkcode PluginDesignCreateApi.roof}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `contour` | {@linkcode ContourHandle} | Footprint (outer + holes) |
- * | `thickness` | `number` | Roof-slab thickness (> 0) |
- */
-export const PluginDesignCreateRoofArgs = z.object({
-  contour: ContourHandle,
-  thickness: z.number(),
-})
-export type PluginDesignCreateRoofArgs = z.infer<
-  typeof PluginDesignCreateRoofArgs
->
-
-// ---------------------------------------------------------------------------
-// ceiling
-// ---------------------------------------------------------------------------
-
-/**
- * Arguments for {@linkcode PluginDesignCreateApi.ceiling}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `contour` | {@linkcode ContourHandle} | Footprint (outer + holes) |
- * | `thickness` | `number` | Ceiling thickness (> 0) |
- * | `heightFromFloor` | `number`? | Lift above the floor (default 0) |
- */
-export const PluginDesignCreateCeilingArgs = z.object({
-  contour: ContourHandle,
-  thickness: z.number(),
-  heightFromFloor: z.number().optional(),
-})
-export type PluginDesignCreateCeilingArgs = z.infer<
-  typeof PluginDesignCreateCeilingArgs
->
-
-// ---------------------------------------------------------------------------
-// column
-// ---------------------------------------------------------------------------
-
-/**
- * Arguments for {@linkcode PluginDesignCreateApi.column}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `position` | {@linkcode Vec3Handle} | Base point |
- * | `crossSection` | {@linkcode ContourHandle} | Column cross-section footprint |
- * | `height` | `number` | Column height (> 0) |
- * | `directionUp` | {@linkcode Vec3Handle}? | Up axis (default world up) |
- */
-export const PluginDesignCreateColumnArgs = z.object({
-  position: Vec3Handle,
-  crossSection: ContourHandle,
-  height: z.number(),
-  directionUp: Vec3Handle.optional(),
-})
-export type PluginDesignCreateColumnArgs = z.infer<
-  typeof PluginDesignCreateColumnArgs
->
-
-// ---------------------------------------------------------------------------
-// beam
-// ---------------------------------------------------------------------------
-
-/**
- * Arguments for {@linkcode PluginDesignCreateApi.beam}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `section` | {@linkcode ContourHandle} | Beam cross-section footprint |
- * | `length` | `number` | Beam length along `direction` (> 0) |
- * | `direction` | {@linkcode Vec3Handle}? | Extrusion axis (default world up) |
- */
-export const PluginDesignCreateBeamArgs = z.object({
-  section: ContourHandle,
-  length: z.number(),
-  direction: Vec3Handle.optional(),
-})
-export type PluginDesignCreateBeamArgs = z.infer<
-  typeof PluginDesignCreateBeamArgs
->
-
-// ---------------------------------------------------------------------------
-// walls
-// ---------------------------------------------------------------------------
-
-/**
- * Arguments for {@linkcode PluginDesignCreateApi.walls}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `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) |
- * | `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(),
-  storey: z.number().int().optional(),
-  topProfiles: z.array(PluginWallTopProfile.nullable()).optional(),
-})
-export type PluginDesignCreateWallsArgs = z.infer<
-  typeof PluginDesignCreateWallsArgs
->
-// 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
-// ---------------------------------------------------------------------------
-
-/**
- * Arguments for {@linkcode PluginDesignCreateApi.staircase}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `preset` | {@linkcode PluginStaircasePreset} | The parametric preset to generate |
- * | `position` | {@linkcode Vec3Handle} | Placement point |
- * | `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,
-  position: Vec3Handle,
-  label: z.string().optional(),
-  structureId: z.string().optional(),
-  level: z.string().optional(),
-  dimensions: PluginStaircaseDimensions.optional(),
-})
-export type PluginDesignCreateStaircaseArgs = z.infer<
-  typeof PluginDesignCreateStaircaseArgs
->
-
-// ---------------------------------------------------------------------------
-// furniture
-// ---------------------------------------------------------------------------
-
-/**
- * Arguments for {@linkcode PluginDesignCreateApi.furniture}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `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`? | 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({
-  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 — 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 swings open to (default engine-chosen) |
- * | `hinge` | {@linkcode Vec3Handle}? | World point near the jamb the door is hinged on (default the catalog item's authored side) |
- */
-export const PluginDesignCreateDoorArgs = z.object({
-  catalogId: z.string().min(1),
-  hostWall: ComponentHandle,
-  position: Vec3Handle,
-  label: z.string().optional(),
-  facing: Vec3Handle.optional(),
-  hinge: Vec3Handle.optional(),
-})
-export type PluginDesignCreateDoorArgs = z.infer<
-  typeof PluginDesignCreateDoorArgs
->
-// TRANSPORT: positional signature shipped — facing is the trailing 5th arg, hinge rides in options:
-//   door(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: { label?, hinge? }, 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 opens to (default engine-chosen) |
- * | `hinge` | {@linkcode Vec3Handle}? | World point near the jamb the window is hinged on (default the catalog item's authored side) |
- */
-export const PluginDesignCreateWindowArgs = z.object({
-  catalogId: z.string().min(1),
-  hostWall: ComponentHandle,
-  position: Vec3Handle,
-  label: z.string().optional(),
-  facing: Vec3Handle.optional(),
-  hinge: Vec3Handle.optional(),
-})
-export type PluginDesignCreateWindowArgs = z.infer<
-  typeof PluginDesignCreateWindowArgs
->
-// TRANSPORT: positional signature shipped — facing is the trailing 5th arg, hinge rides in options:
-//   window(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: { label?, hinge? }, facing?: Vec3Handle)
-
-// ---------------------------------------------------------------------------
-// opening
-// ---------------------------------------------------------------------------
-
-/**
- * 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
-// ---------------------------------------------------------------------------
-
-/**
- * Arguments for {@linkcode PluginDesignCreateApi.referenceLines}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `profile` | {@linkcode ProfileHandle} | Ordered curve chain (centerlines) |
- * | `color` | `string`? | Hex color `"#RRGGBB"` (default white) |
- * | `thickness` | `number`? | Line thickness (default 1) |
- * | `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(),
-})
-export type PluginDesignCreateReferenceLinesArgs = z.infer<
-  typeof PluginDesignCreateReferenceLinesArgs
->
-
-// ---------------------------------------------------------------------------
-// copy
-// ---------------------------------------------------------------------------
-
-/**
- * Copy mode for {@linkcode PluginDesignCreateApi.copy}.
- *
- * | Value | Description |
- * |---|---|
- * | `"instance"` | Keep copies in the source's instance family where possible |
- * | `"unique"` | Independent geometry copies |
- */
-export const PluginCopyMode = z.enum(["instance", "unique"])
-export type PluginCopyMode = z.infer<typeof PluginCopyMode>
-
-/**
- * Arguments for {@linkcode PluginDesignCreateApi.copy} (options flattened).
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `components` | {@linkcode ComponentHandle}`[]` | Entities to copy (≥1) |
- * | `displacement` | {@linkcode Vec3Handle} | Per-copy offset (copy `i` at `displacement * i`) |
- * | `count` | `number`? | Copies per component (default 1) |
- * | `mode` | {@linkcode PluginCopyMode}? | `"instance"` (default) or `"unique"` |
- */
-export const PluginDesignCreateCopyArgs = z.object({
-  components: z.array(ComponentHandle).min(1),
-  displacement: Vec3Handle,
-  count: z.number().int().positive().optional(),
-  mode: PluginCopyMode.optional(),
-})
-export type PluginDesignCreateCopyArgs = z.infer<
-  typeof PluginDesignCreateCopyArgs
->
-// TRANSPORT: positional signature shipped —
-//   copy(components: ComponentHandle[], displacement: Vec3Handle, options?: { count?, mode? })
-
-// ---------------------------------------------------------------------------
-// spaces (bulk)
-// ---------------------------------------------------------------------------
-
-/**
- * One space to create via {@linkcode PluginDesignCreateApi.spaces} — the same
- * footprint-extrude inputs as {@linkcode PluginDesignCreateApi.space}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `contour` | {@linkcode ContourHandle} | Footprint (outer profile + holes) |
- * | `height` | `number` | Extrude height |
- * | `label` | `string`? | Room label |
- * | `position` | {@linkcode Vec3Handle}? | Placement offset |
- * | `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,
-  height: z.number(),
-  label: z.string().optional(),
-  position: Vec3Handle.optional(),
-  spaceType: PluginSpaceType.optional(),
-  massType: PluginMassType.optional(),
-  departmentId: PluginDepartmentId.optional(),
-  storey: z.number().int().optional(),
-})
-export type PluginCreateSpaceItem = z.infer<typeof PluginCreateSpaceItem>
-
-export * from "./opening-fields"
-export * from "./bulk-items"
-export * from "./grids"
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import {
+  BrepHandle,
+  ComponentHandle,
+  ContourHandle,
+  LineHandle,
+  CurveHandle,
+  ProfileHandle,
+  Vec3Handle,
+} from "../../../handles"
+import { PluginGridStyleOptions } from "./grids"
+import {
+  PluginSpaceType,
+  PluginMassType,
+  PluginDepartmentId,
+} from "../../entity/space"
+import {
+  PluginBuildableEnvelopePolygonVertex,
+  PluginBuildableEnvelopeSetbackTier,
+  PluginBuildableEnvelopeVerticalCap,
+  PluginBuildableEnvelopeCreateResult,
+} 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;
+ * `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.*`).
+ *
+ * Footprint objects take a {@linkcode ContourHandle} (outer profile + holes);
+ * build one with `snaptrude.core.geom.create.contourFromProfile(s)`.
+ *
+ * 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. 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).
+ *
+ * Accessed via `snaptrude.design.create`.
+ */
+export abstract class PluginDesignCreateApi {
+  constructor() {}
+
+  /**
+   * Create a **space** (a room / mass) by extruding a footprint contour upward.
+   *
+   * The `contour` is the bottom footprint (outer profile + optional holes); it
+   * is extruded by `height` along +Y. The space is placed on the active story
+   * and assigned a default department unless overridden.
+   *
+   * @param contour - Bottom footprint (outer + holes)
+   * @param height - Extrusion height (Snaptrude units, > 0)
+   * @param label - Room label (maps to the space's `room_type`)
+   * @param position - Offset from origin (default origin)
+   * @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, 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
+   * const v = snaptrude.core.math.vec3
+   * const outer = await snaptrude.core.geom.create.profileFromLinePoints([
+   *   await v.new(0, 0, 0),
+   *   await v.new(10, 0, 0),
+   *   await v.new(10, 0, 8),
+   *   await v.new(0, 0, 8),
+   * ])
+   * 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(
+    contour: ContourHandle,
+    height: number,
+    label?: string,
+    position?: Vec3Handle,
+    spaceType?: PluginSpaceType,
+    massType?: PluginMassType,
+    departmentId?: PluginDepartmentId,
+    storey?: number,
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * Create a **mass** — a generic extruded prism (default `massType` "Generic mass").
+   * Same footprint-extrude path as {@linkcode PluginDesignCreateApi.space}.
+   *
+   * @param contour - Footprint (outer + holes)
+   * @param height - Extrusion height (> 0)
+   * @param label - Label (maps to `room_type`)
+   * @param position - Offset from origin
+   * @param massType - Mass type (default `Generic mass`)
+   * @returns the {@linkcode ComponentHandle} of the created mass
+   * @throws if the contour is invalid or the height is not positive
+   *
+   * @examplePrompt Create a generic mass 30m tall from this footprint
+   * @examplePrompt Block out a conceptual massing volume for the site
+   * @examplePrompt Extrude this shape into a building mass
+   * @examplePrompt Add a simple study-model volume at the origin
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(20, 15)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const tower = await snaptrude.design.create.mass(contour, 30, "Tower A", undefined, "Building")
+   * ```
+   */
+  public abstract mass(
+    contour: ContourHandle,
+    height: number,
+    label?: string,
+    position?: Vec3Handle,
+    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).
+   *
+   * 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"`)
+   * @param slabType - Slab-type classification
+   * @returns the {@linkcode ComponentHandle} of the created slab
+   * @throws if the contour is invalid or the thickness is not positive
+   *
+   * @examplePrompt Add a 150mm thick slab under this footprint
+   * @examplePrompt Create a floor slab from this outline
+   * @examplePrompt Pour a plinth slab over the building footprint
+   * @examplePrompt Make a basement slab that extrudes downward
+   * @examplePrompt Give this room outline a 6 inch slab
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(12, 10)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const slab = await snaptrude.design.create.slab(contour, 0.15, "down", "Plinth")
+   * ```
+   */
+  public abstract slab(
+    ...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 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
+   * @examplePrompt Add a 100mm thick floor over the footprint
+   * @examplePrompt Lay flooring across the selected outline
+   * @examplePrompt Put a floor at this position with 150mm thickness
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(5, 4)
+   * 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(
+    ...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
+   * @throws if the contour is invalid or the thickness is not positive
+   *
+   * @examplePrompt Add a flat roof over the building footprint
+   * @examplePrompt Create a roof 200mm thick from this outline
+   * @examplePrompt Cover the top storey with a roof slab
+   * @examplePrompt Put a roof on this building
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(12, 10)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const roof = await snaptrude.design.create.roof(contour, 0.2)
+   * ```
+   */
+  public abstract roof(
+    contour: ContourHandle,
+    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)
+   * @returns the {@linkcode ComponentHandle} of the created ceiling
+   * @throws if the contour is invalid or the thickness is not positive
+   *
+   * @examplePrompt Add a false ceiling 2.7m above the floor
+   * @examplePrompt Create a ceiling over this room footprint
+   * @examplePrompt Put a dropped ceiling in the living room at 3 metres
+   * @examplePrompt Add a 50mm thick ceiling lifted 2800mm from floor level
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(5, 4)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const ceiling = await snaptrude.design.create.ceiling(contour, 0.05, 2.8)
+   * ```
+   */
+  public abstract ceiling(
+    ...args:
+      | [contour: ContourHandle, thickness: number, heightFromFloor?: number]
+      | [contour: ContourHandle, options: PluginFamilyCeilingOptions]
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * Create a **column** by extruding a cross-section contour upward by `height`
+   * 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), 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, 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
+   * @examplePrompt Create a 450mm square concrete column 4 metres high
+   * @examplePrompt Stand a column up from this base point
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(0.45, 0.45)
+   * const crossSection = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const base = await snaptrude.core.math.vec3.new(4, 0, 4)
+   * const column = await snaptrude.design.create.column(base, crossSection, 3)
+   * ```
+   */
+  public abstract column(
+    ...args:
+      | [
+          position: Vec3Handle,
+          crossSection: ContourHandle,
+          height: number,
+          directionUp?: Vec3Handle,
+        ]
+      | [axis: LineHandle, options: PluginFamilyPlacement]
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * Create a **beam** by extruding a cross-section contour along `direction` by
+   * `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.
+   *
+   * 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 (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
+   * @examplePrompt Run a 300x600 beam across the room
+   * @examplePrompt Extrude this cross-section into a 5m long beam
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(0.3, 0.6)
+   * const section = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const alongX = await snaptrude.core.math.vec3.new(1, 0, 0)
+   * const beam = await snaptrude.design.create.beam(section, 6, alongX)
+   * ```
+   */
+  public abstract beam(
+    ...args:
+      | [section: ContourHandle, length: number, direction?: Vec3Handle]
+      | [axis: LineHandle, options: PluginFamilyPlacement]
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * Create a connected run of **walls** from a profile — one wall per curve in
+   * the profile's chain, with mitred corners at shared endpoints.
+   *
+   * @param profile - Ordered curve chain (wall centerlines)
+   * @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 - 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, `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
+   * @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
+   * @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
+   * const v = snaptrude.core.math.vec3
+   * const centerlines = 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 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,
+   * )
+   * // …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?: 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.
+   *
+   * 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
+   *
+   * @examplePrompt Add a dog-legged staircase at this location
+   * @examplePrompt Place a straight stair on level 01
+   * @examplePrompt Create an L-shaped staircase in the lobby
+   * @examplePrompt Insert a staircase near the entrance
+   * @examplePrompt Put amphitheatre steps at these coordinates
+   *
+   * # Example
+   * ```ts
+   * const stair = await snaptrude.design.create.staircase(
+   *   "dogLegged",
+   *   await snaptrude.core.math.vec3.new(5, 0, 5),
+   * )
+   * ```
+   */
+  public abstract staircase(
+    preset: PluginStaircasePreset,
+    position: Vec3Handle,
+    label?: string,
+    structureId?: string,
+    level?: string,
+    dimensions?: PluginStaircaseDimensions,
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * Create **reference lines** from a profile — one reference line per curve in
+   * the profile's ordered chain. Returns a handle per created line.
+   *
+   * Optional style (`color`, `thickness`, `style`, `gridTag`) applies to
+   * every created line.
+   *
+   * @param profile - Ordered curve chain (centerlines)
+   * @param color - Hex color `"#RRGGBB"` (default white)
+   * @param thickness - 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
+   * @throws if the profile is empty or creation fails
+   *
+   * @examplePrompt Draw a reference line between these two points
+   * @examplePrompt Add dashed guide lines along this path
+   * @examplePrompt Create grid lines tagged A through the plan
+   * @examplePrompt Set up construction lines for the column grid
+   * @examplePrompt Mark a red reference line across the site
+   *
+   * # Example
+   * ```ts
+   * const v = snaptrude.core.math.vec3
+   * const profile = await snaptrude.core.geom.create.profileFromLinePoints([
+   *   await v.new(0, 0, 0),
+   *   await v.new(10, 0, 0),
+   * ])
+   * const lines = await snaptrude.design.create.referenceLines(
+   *   profile,
+   *   undefined,
+   *   undefined,
+   *   "DASHED",
+   * )
+   * ```
+   */
+  public abstract referenceLines(
+    profile: ProfileHandle,
+    color?: string,
+    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.
+   *
+   * Identified by a **catalog (library) id** — the team object's stable `_id` for
+   * project uploads, or the item's `fullName` for the general library. Discover ids
+   * 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 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. `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 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;
+   *   `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
+   * @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
+   * const chair = await snaptrude.design.create.furniture(
+   *   "6620f1a…",             // from design.furniture.listCatalog()
+   *   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,
+   * )
+   * ```
+   *
+   * @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,
+    position: Vec3Handle,
+    options?: { label?: string; createNewSourceMesh?: boolean },
+    angleInDegrees?: number,
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * 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 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. Values and host bindings are evaluated before the first cut.
+   *
+   * @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 - `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 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
+   * @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
+   * @examplePrompt Put a door here hinged on the north jamb
+   *
+   * # 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),
+   * )
+   * // …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(
+    familyId: string,
+    hostWall: ComponentHandle,
+    position: Vec3Handle,
+    options?: {
+      label?: string
+      hinge?: Vec3Handle
+      version?: number
+      values?: Record<string, number | string>
+    },
+    facing?: Vec3Handle,
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * 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.
+   *
+   * # 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 sill parameter determines elevation; position Y is ignored.
+   *
+   * @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 - `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 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
+   * @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" },
+   * )
+   * ```
+   *
+   * @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(
+    familyId: string,
+    hostWall: ComponentHandle,
+    position: Vec3Handle,
+    options?: {
+      label?: string
+      hinge?: Vec3Handle
+      version?: number
+      values?: Record<string, number | string>
+    },
+    facing?: Vec3Handle,
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * 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 `"mass"`, and `listMasses` /
+   * `listByType("mass")` include voids: a mass whose `design.query.getHost` is a
+   * slab, floor, roof or ceiling is a void. After its host is copied, a void can
+   * report `null` and be missing from those lists; `listChildren(host)` still
+   * finds it.
+   *
+   * 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.
+   *
+   * 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 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. 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",
+   *   familyId: 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
+   * @examplePrompt Make 5 copies of this column at 4 metre intervals
+   * @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
+   * const copies = await snaptrude.design.create.copy(["space-id"], vec3.new(6, 0, 0), { count: 3 })
+   * ```
+   */
+  public abstract copy(
+    components: ComponentHandle[],
+    displacement: Vec3Handle,
+    options?: { count?: number; mode?: PluginCopyMode },
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * Create **many spaces** in one undoable operation (bulk plural of {@linkcode space}).
+   * 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. 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
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const [a, b] = await snaptrude.design.create.spaces([
+   *   { contour, height: 3, label: "R1" },
+   *   { contour, height: 4, label: "R2", position: await vec3.new(10, 0, 0) },
+   * ])
+   * ```
+   */
+  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>
+}
+
+// ---------------------------------------------------------------------------
+// Enums
+// ---------------------------------------------------------------------------
+
+/**
+ * Line style of a reference line (mirrors the engine `ReferenceLineMode` verbatim).
+ *
+ * | Value | Description |
+ * |---|---|
+ * | `"SOLID"` | Solid line (default) |
+ * | `"DASHED"` | Dashed line |
+ * | `"DOT_DASH"` | Dot-dash line |
+ */
+export const PluginReferenceLineStyle = z.enum(["SOLID", "DASHED", "DOT_DASH"])
+export type PluginReferenceLineStyle = z.infer<typeof PluginReferenceLineStyle>
+
+/**
+ * Slab type (mirrors the engine `SLAB_TYPES` values verbatim).
+ *
+ * | Value | Description |
+ * |---|---|
+ * | `"Intermediate Slab"` | Intermediate floor slab (default) |
+ * | `"Basement Slab"` | Basement slab |
+ * | `"Plinth"` | Plinth slab |
+ * | `"Roof"` | Roof slab |
+ */
+export const PluginSlabType = z.enum([
+  "Intermediate Slab",
+  "Basement Slab",
+  "Plinth",
+  "Roof",
+])
+export type PluginSlabType = z.infer<typeof PluginSlabType>
+
+/**
+ * A staircase preset — a base type or a named parametric preset. Mirrors the
+ * engine `STAIRCASE_PRESETS` / `StaircaseType`. Use the value that matches the
+ * shape you want (e.g. `"straight"`, `"dogLegged"`, `"lShaped"`).
+ */
+export const PluginStaircasePreset = z.enum([
+  "straight",
+  "straightWoLanding",
+  "straightFlightWoMidLanding",
+  "dogLegged",
+  "openWell",
+  "lShaped",
+  "3StepLShaped",
+  "square",
+  "singleStep",
+  "plinthLevel",
+  "amphitheatre",
+  "connectingStepsToAmphitheatre",
+  "mezzanineFloorStraight",
+  "mezzanineFloorDogLegged",
+  "mezzanineFloorLShaped",
+  "custom",
+])
+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
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.space}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | Bottom footprint (outer + holes) |
+ * | `height` | `number` | Extrusion height (Snaptrude units, > 0) |
+ * | `label` | `string`? | Room label (maps to the space's `room_type`) |
+ * | `position` | {@linkcode Vec3Handle}? | Offset from origin (default origin) |
+ * | `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,
+  height: z.number(),
+  label: z.string().optional(),
+  position: Vec3Handle.optional(),
+  spaceType: PluginSpaceType.optional(),
+  massType: PluginMassType.optional(),
+  departmentId: PluginDepartmentId.optional(),
+  storey: z.number().int().optional(),
+})
+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
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.mass}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | Footprint (outer + holes) |
+ * | `height` | `number` | Extrusion height (> 0) |
+ * | `label` | `string`? | Label (maps to `room_type`) |
+ * | `position` | {@linkcode Vec3Handle}? | Offset from origin |
+ * | `massType` | {@linkcode PluginMassType}? | Mass type (default `Generic mass`) |
+ */
+export const PluginDesignCreateMassArgs = z.object({
+  contour: ContourHandle,
+  height: z.number(),
+  label: z.string().optional(),
+  position: Vec3Handle.optional(),
+  massType: PluginMassType.optional(),
+})
+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
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.slab}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | Footprint (outer + holes) |
+ * | `thickness` | `number` | Slab thickness (> 0) |
+ * | `direction` | `"up" \| "down"`? | Extrusion direction (default `"down"`) |
+ * | `slabType` | {@linkcode PluginSlabType}? | Slab-type classification |
+ */
+export const PluginDesignCreateSlabArgs = z.object({
+  contour: ContourHandle,
+  thickness: z.number(),
+  direction: z.enum(["up", "down"]).optional(),
+  slabType: PluginSlabType.optional(),
+})
+export type PluginDesignCreateSlabArgs = z.infer<
+  typeof PluginDesignCreateSlabArgs
+>
+
+// ---------------------------------------------------------------------------
+// floor
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.floor}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | Footprint (outer + holes) |
+ * | `thickness` | `number` | Floor thickness (> 0) |
+ * | `position` | {@linkcode Vec3Handle}? | Offset from origin |
+ */
+export const PluginDesignCreateFloorArgs = z.object({
+  contour: ContourHandle,
+  thickness: z.number(),
+  position: Vec3Handle.optional(),
+})
+export type PluginDesignCreateFloorArgs = z.infer<
+  typeof PluginDesignCreateFloorArgs
+>
+
+// ---------------------------------------------------------------------------
+// roof
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.roof}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | Footprint (outer + holes) |
+ * | `thickness` | `number` | Roof-slab thickness (> 0) |
+ */
+export const PluginDesignCreateRoofArgs = z.object({
+  contour: ContourHandle,
+  thickness: z.number(),
+})
+export type PluginDesignCreateRoofArgs = z.infer<
+  typeof PluginDesignCreateRoofArgs
+>
+
+// ---------------------------------------------------------------------------
+// ceiling
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.ceiling}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | Footprint (outer + holes) |
+ * | `thickness` | `number` | Ceiling thickness (> 0) |
+ * | `heightFromFloor` | `number`? | Lift above the floor (default 0) |
+ */
+export const PluginDesignCreateCeilingArgs = z.object({
+  contour: ContourHandle,
+  thickness: z.number(),
+  heightFromFloor: z.number().optional(),
+})
+export type PluginDesignCreateCeilingArgs = z.infer<
+  typeof PluginDesignCreateCeilingArgs
+>
+
+// ---------------------------------------------------------------------------
+// column
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.column}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `position` | {@linkcode Vec3Handle} | Base point |
+ * | `crossSection` | {@linkcode ContourHandle} | Column cross-section footprint |
+ * | `height` | `number` | Column height (> 0) |
+ * | `directionUp` | {@linkcode Vec3Handle}? | Up axis (default world up) |
+ */
+export const PluginDesignCreateColumnArgs = z.object({
+  position: Vec3Handle,
+  crossSection: ContourHandle,
+  height: z.number(),
+  directionUp: Vec3Handle.optional(),
+})
+export type PluginDesignCreateColumnArgs = z.infer<
+  typeof PluginDesignCreateColumnArgs
+>
+
+// ---------------------------------------------------------------------------
+// beam
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.beam}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `section` | {@linkcode ContourHandle} | Beam cross-section footprint |
+ * | `length` | `number` | Beam length along `direction` (> 0) |
+ * | `direction` | {@linkcode Vec3Handle}? | Extrusion axis (default world up) |
+ */
+export const PluginDesignCreateBeamArgs = z.object({
+  section: ContourHandle,
+  length: z.number(),
+  direction: Vec3Handle.optional(),
+})
+export type PluginDesignCreateBeamArgs = z.infer<
+  typeof PluginDesignCreateBeamArgs
+>
+
+// ---------------------------------------------------------------------------
+// walls
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.walls}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `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` | {@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: 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 5th arg, topProfiles the trailing 6th:
+//   walls(profile: ProfileHandle, height?: number, thickness?: number, wallType?: string, storey?: number, topProfiles?: (PluginWallTopProfile | null)[])
+
+// ---------------------------------------------------------------------------
+// staircase
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.staircase}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `preset` | {@linkcode PluginStaircasePreset} | The parametric preset to generate |
+ * | `position` | {@linkcode Vec3Handle} | Placement point |
+ * | `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,
+  position: Vec3Handle,
+  label: z.string().optional(),
+  structureId: z.string().optional(),
+  level: z.string().optional(),
+  dimensions: PluginStaircaseDimensions.optional(),
+})
+export type PluginDesignCreateStaircaseArgs = z.infer<
+  typeof PluginDesignCreateStaircaseArgs
+>
+
+// ---------------------------------------------------------------------------
+// furniture
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.furniture}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `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`? | 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({
+  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 — 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 |
+ * |---|---|---|
+ * | `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 swings open to (default engine-chosen) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the hinged jamb; requires hand control |
+ */
+export const PluginDesignCreateDoorArgs = z.object({
+  ...PluginOpeningBaseOptions,
+})
+export type PluginDesignCreateDoorArgs = z.infer<
+  typeof PluginDesignCreateDoorArgs
+>
+// 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
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.window}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `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 opens to (default engine-chosen) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the hinged jamb; requires hand control |
+ */
+export const PluginDesignCreateWindowArgs = z.object({
+  ...PluginOpeningBaseOptions,
+})
+export type PluginDesignCreateWindowArgs = z.infer<
+  typeof PluginDesignCreateWindowArgs
+>
+// 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
+// ---------------------------------------------------------------------------
+
+/**
+ * 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
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.referenceLines}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ProfileHandle} | Ordered curve chain (centerlines) |
+ * | `color` | `string`? | Hex color `"#RRGGBB"` (default white) |
+ * | `thickness` | `number`? | Line thickness (default 1) |
+ * | `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(),
+})
+export type PluginDesignCreateReferenceLinesArgs = z.infer<
+  typeof PluginDesignCreateReferenceLinesArgs
+>
+
+// ---------------------------------------------------------------------------
+// copy
+// ---------------------------------------------------------------------------
+
+/**
+ * Copy mode for {@linkcode PluginDesignCreateApi.copy}.
+ *
+ * | Value | Description |
+ * |---|---|
+ * | `"instance"` | Keep copies in the source's instance family where possible |
+ * | `"unique"` | Independent geometry copies |
+ */
+export const PluginCopyMode = z.enum(["instance", "unique"])
+export type PluginCopyMode = z.infer<typeof PluginCopyMode>
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.copy} (options flattened).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | Entities to copy (≥1) |
+ * | `displacement` | {@linkcode Vec3Handle} | Per-copy offset (copy `i` at `displacement * i`) |
+ * | `count` | `number`? | Copies per component (default 1) |
+ * | `mode` | {@linkcode PluginCopyMode}? | `"instance"` (default) or `"unique"` |
+ */
+export const PluginDesignCreateCopyArgs = z.object({
+  components: z.array(ComponentHandle).min(1),
+  displacement: Vec3Handle,
+  count: z.number().int().positive().optional(),
+  mode: PluginCopyMode.optional(),
+})
+export type PluginDesignCreateCopyArgs = z.infer<
+  typeof PluginDesignCreateCopyArgs
+>
+// TRANSPORT: positional signature shipped —
+//   copy(components: ComponentHandle[], displacement: Vec3Handle, options?: { count?, mode? })
+
+// ---------------------------------------------------------------------------
+// spaces (bulk)
+// ---------------------------------------------------------------------------
+
+/**
+ * One space to create via {@linkcode PluginDesignCreateApi.spaces} — the same
+ * footprint-extrude inputs as {@linkcode PluginDesignCreateApi.space}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | Footprint (outer profile + holes) |
+ * | `height` | `number` | Extrude height |
+ * | `label` | `string`? | Room label |
+ * | `position` | {@linkcode Vec3Handle}? | Placement offset |
+ * | `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,
+  height: z.number(),
+  label: z.string().optional(),
+  position: Vec3Handle.optional(),
+  spaceType: PluginSpaceType.optional(),
+  massType: PluginMassType.optional(),
+  departmentId: PluginDepartmentId.optional(),
+  storey: z.number().int().optional(),
+})
+export type PluginCreateSpaceItem = z.infer<typeof PluginCreateSpaceItem>
+
+export * from "./opening-fields"
+export * from "./bulk-items"
+export * from "./grids"