@snaptrude/plugin-core 0.3.0 → 0.6.0

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

@@ -0,0 +1,895 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import {
+  ComponentHandle,
+  ContourHandle,
+  ProfileHandle,
+  Vec3Handle,
+} from "../../../handles"
+import {
+  PluginSpaceType,
+  PluginMassType,
+  PluginDepartmentId,
+} from "../../entity/space"
+
+/**
+ * `design.create.*` — author new scene-committed BIM entities.
+ *
+ * Every creator takes geometry handles + scalars and returns a
+ * {@linkcode ComponentHandle} (or `ComponentHandle[]` for plural creators) — the
+ * `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)`.
+ *
+ * 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)
+   * @returns the {@linkcode ComponentHandle} of the created space
+   * @throws if the contour is invalid or the height is not positive
+   *
+   * @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?
+   *
+   * # 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")
+   * ```
+   */
+  public abstract space(
+    contour: ContourHandle,
+    height: number,
+    label?: string,
+    position?: Vec3Handle,
+    spaceType?: PluginSpaceType,
+    massType?: PluginMassType,
+    departmentId?: PluginDepartmentId,
+  ): 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 **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)
+   * ```
+   */
+  public abstract floor(
+    contour: ContourHandle,
+    thickness: number,
+    position?: Vec3Handle,
+  ): 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`.
+   *
+   * @param position - Base point
+   * @param crossSection - Column cross-section footprint
+   * @param height - Column height (> 0)
+   * @param directionUp - Up axis (default world up)
+   * @returns the {@linkcode ComponentHandle} of the created column
+   * @throws if the cross-section is invalid or the height is not positive
+   *
+   * @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`.
+   *
+   * @param section - Beam cross-section footprint
+   * @param length - Beam length along `direction` (> 0)
+   * @param direction - Extrusion axis (default world up)
+   * @returns the {@linkcode ComponentHandle} of the created beam
+   * @throws if the section is invalid or the length is not positive
+   *
+   * @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 engine default)
+   * @returns a {@linkcode ComponentHandle}`[]` (one per wall), in profile order
+   * @throws if the profile is empty 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
+   *
+   * # 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)
+   * ```
+   */
+  public abstract walls(
+    profile: ProfileHandle,
+    height?: number,
+    thickness?: number,
+  ): 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.
+   *
+   * @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"`)
+   * @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,
+  ): 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[]>
+
+  /**
+   * 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; rotate afterward via `design.transform.rotate`
+   * on the returned handle (planned namespace).
+   *
+   * @param catalogId - Library id: team `_id` or general `fullName`
+   * @param position - Absolute world placement point
+   * @param options - Optional placement options: `label` — instance name
+   *   (default auto `${name}Ins${n}`); `createNewSourceMesh` — emit a
+   *   source-mesh creation command (default `true`)
+   * @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
+   *
+   * @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
+   *
+   * # 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" },
+   * )
+   * ```
+   */
+  public abstract furniture(
+    catalogId: string,
+    position: Vec3Handle,
+    options?: { label?: string; createNewSourceMesh?: boolean },
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * **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
+   *
+   * # 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.
+   *
+   * @param items - One {@linkcode PluginCreateSpaceItem} per space to create (≥1)
+   * @returns the created spaces as {@linkcode ComponentHandle}`[]`, in input order
+   *
+   * @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
+   *
+   * # 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[]>
+}
+
+// ---------------------------------------------------------------------------
+// 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>
+
+// ---------------------------------------------------------------------------
+// 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) |
+ */
+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(),
+})
+export type PluginDesignCreateSpaceArgs = z.infer<typeof PluginDesignCreateSpaceArgs>
+
+// ---------------------------------------------------------------------------
+// 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>
+
+// ---------------------------------------------------------------------------
+// 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 engine default) |
+ */
+export const PluginDesignCreateWallsArgs = z.object({
+  profile: ProfileHandle,
+  height: z.number().optional(),
+  thickness: z.number().optional(),
+})
+export type PluginDesignCreateWallsArgs = z.infer<typeof PluginDesignCreateWallsArgs>
+
+// ---------------------------------------------------------------------------
+// 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"`) |
+ */
+export const PluginDesignCreateStaircaseArgs = z.object({
+  preset: PluginStaircasePreset,
+  position: Vec3Handle,
+  label: z.string().optional(),
+  structureId: z.string().optional(),
+  level: z.string().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`? | Emit a source-mesh creation command (default `true`) |
+ */
+export const PluginDesignCreateFurnitureArgs = z.object({
+  catalogId: z.string().min(1),
+  position: Vec3Handle,
+  label: z.string().optional(),
+  createNewSourceMesh: z.boolean().optional(),
+})
+export type PluginDesignCreateFurnitureArgs = z.infer<
+  typeof PluginDesignCreateFurnitureArgs
+>
+// TRANSPORT: positional signature shipped —
+//   furniture(catalogId: string, position: Vec3Handle, options?: { label?, createNewSourceMesh? })
+
+// ---------------------------------------------------------------------------
+// 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 |
+ */
+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(),
+})
+export type PluginCreateSpaceItem = z.infer<typeof PluginCreateSpaceItem>