@snaptrude/plugin-core 0.7.1 → 0.8.0

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

@@ -50,14 +50,21 @@ export abstract class PluginDesignCreateApi {
    * @param spaceType - Space-type classification (default `Room`)
    * @param massType - Mass-type classification (default `Room`)
    * @param departmentId - Department assignment (default department)
+   * @param storey - Target storey number to place the space on — the same integer
+   *   `entity.story` uses (`1` ground, `2` first floor, `-1` basement). Default:
+   *   the active storey. Folds an `entity.story.setActive` call into the create,
+   *   placing the space at that storey's floor elevation (any `position` offset is
+   *   applied on top). Throws if no storey has that value.
    * @returns the {@linkcode ComponentHandle} of the created space
-   * @throws if the contour is invalid or the height is not positive
+   * @throws if the contour is invalid, the height is not positive, or the target
+   *   storey does not exist
    *
    * @examplePrompt Create a room called Living Room that's 3m tall from this outline
    * @examplePrompt Add a new space on the current storey using this footprint
    * @examplePrompt Make a bedroom here and assign it to the Residential department
    * @examplePrompt Extrude this closed outline into a 10 foot high room
    * @examplePrompt Can you create a Kitchen space from the sketch I just drew?
+   * @examplePrompt Create a bedroom on the second floor from this outline
    *
    * # Example
    * ```ts
@@ -70,6 +77,10 @@ export abstract class PluginDesignCreateApi {
    * ])
    * const contour = await snaptrude.core.geom.create.contourFromProfile(outer)
    * const space = await snaptrude.design.create.space(contour, 3, "Living")
+   * // …place one directly on the second floor (no setActive dance):
+   * const upstairs = await snaptrude.design.create.space(
+   *   contour, 3, "Bedroom", undefined, undefined, undefined, undefined, 2,
+   * )
    * ```
    */
   public abstract space(
@@ -80,6 +91,7 @@ export abstract class PluginDesignCreateApi {
     spaceType?: PluginSpaceType,
     massType?: PluginMassType,
     departmentId?: PluginDepartmentId,
+    storey?: number,
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -229,14 +241,17 @@ export abstract class PluginDesignCreateApi {
 
   /**
    * Create a **column** by extruding a cross-section contour upward by `height`
-   * from a base `position`.
+   * from a base `position`. The column is built to EXACTLY `height` — unlike
+   * the interactive draw tool, no slab-thickness deduction is applied.
    *
    * @param position - Base point
    * @param crossSection - Column cross-section footprint
-   * @param height - Column height (> 0)
-   * @param directionUp - Up axis (default world up)
+   * @param height - Column height (> 0), built exactly
+   * @param directionUp - Up axis (default world up); normalized by the host, so
+   * magnitude does not scale the height
    * @returns the {@linkcode ComponentHandle} of the created column
-   * @throws if the cross-section is invalid or the height is not positive
+   * @throws if the cross-section is invalid, the height is not positive, or the
+   * direction is zero / lies in the cross-section plane (degenerate extrusion)
    *
    * @examplePrompt Add a 3m tall column at this point
    * @examplePrompt Place a column at the grid intersection
@@ -260,13 +275,30 @@ export abstract class PluginDesignCreateApi {
 
   /**
    * Create a **beam** by extruding a cross-section contour along `direction` by
-   * `length`.
+   * `length`. Matches the Snaptrude beam tool's semantics: the beam body hangs
+   * BELOW the plane the section is authored on.
+   *
+   * For a **horizontal** `direction` (the common spanning beam), author the
+   * section as an axis-aligned plan rectangle: its X extent is the beam's
+   * width, its Z extent is the beam's depth (the vertical drop). The beam runs
+   * `length` along `direction` starting at the section's centre, hanging below
+   * the authoring plane by its depth — exactly like an interactively drawn
+   * beam. Only axis-aligned rectangular sections are supported horizontally.
+   *
+   * 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 footprint
-   * @param length - Beam length along `direction` (> 0)
-   * @param direction - Extrusion axis (default world up)
+   * @param section - Beam cross-section, an axis-aligned rectangle in plan
+   * (X extent = width, Z extent = depth)
+   * @param length - Beam length along `direction` (> 0); direction is
+   * normalized by the host, so magnitude does not scale the length
+   * @param direction - Beam axis: horizontal for a spanning beam, or vertical
+   * (default world up). Diagonal directions throw.
    * @returns the {@linkcode ComponentHandle} of the created beam
-   * @throws if the section is invalid or the length is not positive
+   * @throws if the section is invalid (horizontal beams: not an axis-aligned
+   * plan rectangle), the length is not positive, or the direction is zero or
+   * diagonal
    *
    * @examplePrompt Add a beam spanning 6 metres between the columns
    * @examplePrompt Create a horizontal beam along the X axis
@@ -293,15 +325,25 @@ export abstract class PluginDesignCreateApi {
    *
    * @param profile - Ordered curve chain (wall centerlines)
    * @param height - Wall height (default engine default)
-   * @param thickness - Wall thickness (default engine default)
+   * @param thickness - Wall thickness (default: the `wallType`'s total layer
+   *   thickness when `wallType` is given, else the engine default)
+   * @param wallType - Wall type to build with — the same searchable list the
+   *   Draw tab's Wall Type dropdown offers. Pass a name from
+   *   `design.types.list("wall")` (the summary's `label`, or its `"wall:…"` id).
+   *   Drives the wall's construction layers and default material, and — when
+   *   `thickness` is omitted — its total layer thickness. Default: the engine's
+   *   generic wall.
    * @returns a {@linkcode ComponentHandle}`[]` (one per wall), in profile order
-   * @throws if the profile is empty or wall creation fails
+   * @throws if the profile is empty, `wallType` names no wall type in the
+   *   project, or wall creation fails
    *
    * @examplePrompt Draw walls along this centerline
    * @examplePrompt Create 3m high, 200mm thick walls from these points
    * @examplePrompt Build a wall run around the room outline
    * @examplePrompt Turn this polyline sketch into walls
    * @examplePrompt Add walls with mitred corners along the path
+   * @examplePrompt Draw brick walls with plaster along this outline
+   * @examplePrompt Build the perimeter in exposed concrete walls
    *
    * # Example
    * ```ts
@@ -312,12 +354,18 @@ export abstract class PluginDesignCreateApi {
    *   await v.new(8, 0, 6),
    * ])
    * const walls = await snaptrude.design.create.walls(centerlines, 3, 0.2)
+   * // …built as a specific wall type (layers/material/thickness from the type):
+   * const [brick] = await snaptrude.design.types.list("wall")
+   * const brickWalls = await snaptrude.design.create.walls(
+   *   centerlines, 3, undefined, brick.label,
+   * )
    * ```
    */
   public abstract walls(
     profile: ProfileHandle,
     height?: number,
     thickness?: number,
+    wallType?: string,
   ): PluginApiReturn<ComponentHandle[]>
 
   /**
@@ -408,14 +456,19 @@ export abstract class PluginDesignCreateApi {
    * with {@linkcode PluginDesignFurnitureApi.listCatalog}. Placement is asynchronous
    * (the source mesh is fetched if not cached) and creates one undo entry.
    *
-   * Placed at the item's default rotation; rotate afterward via `design.transform.rotate`
-   * on the returned handle (planned namespace).
+   * Placed at the item's default rotation unless `angleInDegrees` is given, which
+   * rotates it about the vertical axis at creation time (baked into the same undo
+   * entry). To rotate an existing instance instead, use `design.transform.rotate`.
    *
    * @param catalogId - Library id: team `_id` or general `fullName`
    * @param position - Absolute world placement point
    * @param options - Optional placement options: `label` — instance name
    *   (default auto `${name}Ins${n}`); `createNewSourceMesh` — emit a
    *   source-mesh creation command (default `true`)
+   * @param angleInDegrees - Optional signed rotation about the vertical axis, in
+   *   degrees (same convention as {@linkcode PluginDesignTransformApi.rotate}).
+   *   Applied at creation time so it is part of the placement's single undo entry.
+   *   Default: the item's own (unrotated) orientation.
    * @returns the {@linkcode ComponentHandle} of the placed furniture instance
    * @throws if the catalog id is unknown, the source mesh fails to load, or placement fails
    *
@@ -424,6 +477,7 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Drop a desk into the scene at 3, 0, 5
    * @examplePrompt Insert the uploaded bed model in the bedroom
    * @examplePrompt Put a table from my project library here and name it Table-01
+   * @examplePrompt Place a chair here rotated 90 degrees
    *
    * # Example
    * ```ts
@@ -432,12 +486,20 @@ export abstract class PluginDesignCreateApi {
    *   await snaptrude.core.math.vec3.new(3, 0, 5),
    *   { label: "Chair-01" },
    * )
+   * // …placed already turned 90° about the vertical axis:
+   * const turned = await snaptrude.design.create.furniture(
+   *   "6620f1a…",
+   *   await snaptrude.core.math.vec3.new(3, 0, 5),
+   *   undefined,
+   *   90,
+   * )
    * ```
    */
   public abstract furniture(
     catalogId: string,
     position: Vec3Handle,
     options?: { label?: string; createNewSourceMesh?: boolean },
+    angleInDegrees?: number,
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -454,6 +516,11 @@ export abstract class PluginDesignCreateApi {
    * @param hostWall - The wall to host the door
    * @param position - World point projected onto the wall to locate the opening
    * @param options - Optional placement options: `label` — instance name
+   * @param facing - World point selecting which side of the wall the door faces
+   *   (the room it opens into) — the same convention as approaching the wall
+   *   from that side with the cursor in the interactive tool. Any point clearly
+   *   on that side works (e.g. the room's center). Default: the engine picks a
+   *   side (nondeterministic when `position` sits on the wall centerline).
    * @returns the {@linkcode ComponentHandle} of the placed door
    * @throws if the catalog id is unknown, the host is not a wall, the source
    *   mesh fails to load, or the projected point falls **outside** the host wall
@@ -463,6 +530,7 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Put a door from the catalog at this point on the wall
    * @examplePrompt Insert the entrance door into this wall
    * @examplePrompt Add a door to the wall and call it Entry-01
+   * @examplePrompt Add a door that opens into the living room
    *
    * # Example
    * ```ts
@@ -474,6 +542,14 @@ export abstract class PluginDesignCreateApi {
    *   await snaptrude.core.math.vec3.new(3, 0, 5),
    *   { label: "Entry-01" },
    * )
+   * // …facing a specific side of the wall (pass a point inside that room):
+   * const intoKitchen = await snaptrude.design.create.door(
+   *   entry.id,
+   *   wall,
+   *   await snaptrude.core.math.vec3.new(3, 0, 5),
+   *   undefined,
+   *   await snaptrude.core.math.vec3.new(3, 0, 9),
+   * )
    * ```
    */
   public abstract door(
@@ -481,6 +557,7 @@ export abstract class PluginDesignCreateApi {
     hostWall: ComponentHandle,
     position: Vec3Handle,
     options?: { label?: string },
+    facing?: Vec3Handle,
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -497,6 +574,10 @@ export abstract class PluginDesignCreateApi {
    * @param hostWall - The wall to host the window
    * @param position - World point projected onto the wall to locate the opening
    * @param options - Optional placement options: `label` — instance name
+   * @param facing - World point selecting which side of the wall the window
+   *   faces (matters for asymmetric windows, e.g. casement swing) — same
+   *   convention as {@linkcode PluginDesignCreateApi.door}. Default: the engine
+   *   picks a side (nondeterministic when `position` sits on the centerline).
    * @returns the {@linkcode ComponentHandle} of the placed window
    * @throws if the catalog id is unknown, the host is not a wall, the source
    *   mesh fails to load, or the projected point falls **outside** the host wall
@@ -506,6 +587,7 @@ export abstract class PluginDesignCreateApi {
    * @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
@@ -524,6 +606,7 @@ export abstract class PluginDesignCreateApi {
     hostWall: ComponentHandle,
     position: Vec3Handle,
     options?: { label?: string },
+    facing?: Vec3Handle,
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -619,15 +702,20 @@ export abstract class PluginDesignCreateApi {
    * Migrated from the removed `entity.space.bulkCreate`. Each item extrudes a contour
    * footprint up `height`. Validate-all-or-throw; one command. For a rectangular
    * (box) space, build the footprint with `core.geom.create.profileRect` →
-   * `contourFromProfile`, then pass it as an item.
+   * `contourFromProfile`, then pass it as an item. Each item may carry its own
+   * `storey` (see {@linkcode PluginCreateSpaceItem}) so a single call can populate
+   * several floors at once.
    *
    * @param items - One {@linkcode PluginCreateSpaceItem} per space to create (≥1)
    * @returns the created spaces as {@linkcode ComponentHandle}`[]`, in input order
+   * @throws if any item's contour is invalid, its height is not positive, or its
+   *   target `storey` does not exist (all-or-nothing — nothing is created)
    *
    * @examplePrompt Create several rooms at once from these footprints
    * @examplePrompt Generate all the bedrooms in one operation
    * @examplePrompt Bulk create the spaces for this floor plan
    * @examplePrompt Add three rooms with different heights in a single undo step
+   * @examplePrompt Create one room on the ground floor and one on the first floor
    *
    * # Example
    * ```ts
@@ -639,7 +727,9 @@ export abstract class PluginDesignCreateApi {
    * ])
    * ```
    */
-  public abstract spaces(items: PluginCreateSpaceItem[]): PluginApiReturn<ComponentHandle[]>
+  public abstract spaces(
+    items: PluginCreateSpaceItem[],
+  ): PluginApiReturn<ComponentHandle[]>
 }
 
 // ---------------------------------------------------------------------------
@@ -717,6 +807,7 @@ export type PluginStaircasePreset = z.infer<typeof PluginStaircasePreset>
  * | `spaceType` | {@linkcode PluginSpaceType}? | Space-type classification (default `Room`) |
  * | `massType` | {@linkcode PluginMassType}? | Mass-type classification (default `Room`) |
  * | `departmentId` | {@linkcode PluginDepartmentId}? | Department assignment (default department) |
+ * | `storey` | `number`? (int) | Target storey number (default active storey) |
  */
 export const PluginDesignCreateSpaceArgs = z.object({
   contour: ContourHandle,
@@ -726,8 +817,13 @@ export const PluginDesignCreateSpaceArgs = z.object({
   spaceType: PluginSpaceType.optional(),
   massType: PluginMassType.optional(),
   departmentId: PluginDepartmentId.optional(),
+  storey: z.number().int().optional(),
 })
-export type PluginDesignCreateSpaceArgs = z.infer<typeof PluginDesignCreateSpaceArgs>
+export type PluginDesignCreateSpaceArgs = z.infer<
+  typeof PluginDesignCreateSpaceArgs
+>
+// TRANSPORT: positional signature shipped — storey is the trailing 8th arg:
+//   space(contour, height, label?, position?, spaceType?, massType?, departmentId?, storey?)
 
 // ---------------------------------------------------------------------------
 // mass
@@ -751,7 +847,9 @@ export const PluginDesignCreateMassArgs = z.object({
   position: Vec3Handle.optional(),
   massType: PluginMassType.optional(),
 })
-export type PluginDesignCreateMassArgs = z.infer<typeof PluginDesignCreateMassArgs>
+export type PluginDesignCreateMassArgs = z.infer<
+  typeof PluginDesignCreateMassArgs
+>
 
 // ---------------------------------------------------------------------------
 // slab
@@ -773,7 +871,9 @@ export const PluginDesignCreateSlabArgs = z.object({
   direction: z.enum(["up", "down"]).optional(),
   slabType: PluginSlabType.optional(),
 })
-export type PluginDesignCreateSlabArgs = z.infer<typeof PluginDesignCreateSlabArgs>
+export type PluginDesignCreateSlabArgs = z.infer<
+  typeof PluginDesignCreateSlabArgs
+>
 
 // ---------------------------------------------------------------------------
 // floor
@@ -793,7 +893,9 @@ export const PluginDesignCreateFloorArgs = z.object({
   thickness: z.number(),
   position: Vec3Handle.optional(),
 })
-export type PluginDesignCreateFloorArgs = z.infer<typeof PluginDesignCreateFloorArgs>
+export type PluginDesignCreateFloorArgs = z.infer<
+  typeof PluginDesignCreateFloorArgs
+>
 
 // ---------------------------------------------------------------------------
 // roof
@@ -811,7 +913,9 @@ export const PluginDesignCreateRoofArgs = z.object({
   contour: ContourHandle,
   thickness: z.number(),
 })
-export type PluginDesignCreateRoofArgs = z.infer<typeof PluginDesignCreateRoofArgs>
+export type PluginDesignCreateRoofArgs = z.infer<
+  typeof PluginDesignCreateRoofArgs
+>
 
 // ---------------------------------------------------------------------------
 // ceiling
@@ -831,7 +935,9 @@ export const PluginDesignCreateCeilingArgs = z.object({
   thickness: z.number(),
   heightFromFloor: z.number().optional(),
 })
-export type PluginDesignCreateCeilingArgs = z.infer<typeof PluginDesignCreateCeilingArgs>
+export type PluginDesignCreateCeilingArgs = z.infer<
+  typeof PluginDesignCreateCeilingArgs
+>
 
 // ---------------------------------------------------------------------------
 // column
@@ -853,7 +959,9 @@ export const PluginDesignCreateColumnArgs = z.object({
   height: z.number(),
   directionUp: Vec3Handle.optional(),
 })
-export type PluginDesignCreateColumnArgs = z.infer<typeof PluginDesignCreateColumnArgs>
+export type PluginDesignCreateColumnArgs = z.infer<
+  typeof PluginDesignCreateColumnArgs
+>
 
 // ---------------------------------------------------------------------------
 // beam
@@ -873,7 +981,9 @@ export const PluginDesignCreateBeamArgs = z.object({
   length: z.number(),
   direction: Vec3Handle.optional(),
 })
-export type PluginDesignCreateBeamArgs = z.infer<typeof PluginDesignCreateBeamArgs>
+export type PluginDesignCreateBeamArgs = z.infer<
+  typeof PluginDesignCreateBeamArgs
+>
 
 // ---------------------------------------------------------------------------
 // walls
@@ -886,14 +996,20 @@ export type PluginDesignCreateBeamArgs = z.infer<typeof PluginDesignCreateBeamAr
  * |---|---|---|
  * | `profile` | {@linkcode ProfileHandle} | Ordered curve chain (wall centerlines) |
  * | `height` | `number`? | Wall height (default engine default) |
- * | `thickness` | `number`? | Wall thickness (default engine default) |
+ * | `thickness` | `number`? | Wall thickness (default: `wallType`'s total layer thickness when given, else engine default) |
+ * | `wallType` | `string`? | Wall type name from `design.types.list("wall")` — layers/material/thickness defaults (default generic) |
  */
 export const PluginDesignCreateWallsArgs = z.object({
   profile: ProfileHandle,
   height: z.number().optional(),
   thickness: z.number().optional(),
+  wallType: z.string().min(1).optional(),
 })
-export type PluginDesignCreateWallsArgs = z.infer<typeof PluginDesignCreateWallsArgs>
+export type PluginDesignCreateWallsArgs = z.infer<
+  typeof PluginDesignCreateWallsArgs
+>
+// TRANSPORT: positional signature shipped — wallType is the trailing 4th arg:
+//   walls(profile: ProfileHandle, height?: number, thickness?: number, wallType?: string)
 
 // ---------------------------------------------------------------------------
 // staircase
@@ -934,18 +1050,20 @@ export type PluginDesignCreateStaircaseArgs = z.infer<
  * | `position` | {@linkcode Vec3Handle} | Absolute world placement point |
  * | `label` | `string`? | Instance name (default auto `${name}Ins${n}`) |
  * | `createNewSourceMesh` | `boolean`? | Emit a source-mesh creation command (default `true`) |
+ * | `angleInDegrees` | `number`? | Rotation about the vertical axis, in degrees (default unrotated) |
  */
 export const PluginDesignCreateFurnitureArgs = z.object({
   catalogId: z.string().min(1),
   position: Vec3Handle,
   label: z.string().optional(),
   createNewSourceMesh: z.boolean().optional(),
+  angleInDegrees: z.number().optional(),
 })
 export type PluginDesignCreateFurnitureArgs = z.infer<
   typeof PluginDesignCreateFurnitureArgs
 >
-// TRANSPORT: positional signature shipped —
-//   furniture(catalogId: string, position: Vec3Handle, options?: { label?, createNewSourceMesh? })
+// TRANSPORT: positional signature shipped — angleInDegrees is the trailing 4th arg:
+//   furniture(catalogId: string, position: Vec3Handle, options?: { label?, createNewSourceMesh? }, angleInDegrees?: number)
 
 // ---------------------------------------------------------------------------
 // door
@@ -960,16 +1078,20 @@ export type PluginDesignCreateFurnitureArgs = z.infer<
  * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the door |
  * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
  * | `label` | `string`? | Instance name (optional) |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the door faces (default engine-chosen) |
  */
 export const PluginDesignCreateDoorArgs = z.object({
   catalogId: z.string().min(1),
   hostWall: ComponentHandle,
   position: Vec3Handle,
   label: z.string().optional(),
+  facing: Vec3Handle.optional(),
 })
-export type PluginDesignCreateDoorArgs = z.infer<typeof PluginDesignCreateDoorArgs>
-// TRANSPORT: positional signature shipped —
-//   door(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: { label? })
+export type PluginDesignCreateDoorArgs = z.infer<
+  typeof PluginDesignCreateDoorArgs
+>
+// TRANSPORT: positional signature shipped — facing is the trailing 5th arg:
+//   door(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: { label? }, facing?: Vec3Handle)
 
 // ---------------------------------------------------------------------------
 // window
@@ -984,16 +1106,20 @@ export type PluginDesignCreateDoorArgs = z.infer<typeof PluginDesignCreateDoorAr
  * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the window |
  * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
  * | `label` | `string`? | Instance name (optional) |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the window faces (default engine-chosen) |
  */
 export const PluginDesignCreateWindowArgs = z.object({
   catalogId: z.string().min(1),
   hostWall: ComponentHandle,
   position: Vec3Handle,
   label: z.string().optional(),
+  facing: Vec3Handle.optional(),
 })
-export type PluginDesignCreateWindowArgs = z.infer<typeof PluginDesignCreateWindowArgs>
-// TRANSPORT: positional signature shipped —
-//   window(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: { label? })
+export type PluginDesignCreateWindowArgs = z.infer<
+  typeof PluginDesignCreateWindowArgs
+>
+// TRANSPORT: positional signature shipped — facing is the trailing 5th arg:
+//   window(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: { label? }, facing?: Vec3Handle)
 
 // ---------------------------------------------------------------------------
 // smartLayout
@@ -1019,7 +1145,7 @@ export const PluginSmartLayoutArgs = z
   })
   .refine(
     (v) =>
-      (v.templateGroup != null) !== ((v.templateComponents?.length ?? 0) > 0),
+      (v.templateGroup != null) !== (v.templateComponents?.length ?? 0) > 0,
     {
       message:
         "Provide exactly one template source: templateGroup or a non-empty templateComponents",
@@ -1110,7 +1236,9 @@ export const PluginDesignCreateCopyArgs = z.object({
   count: z.number().int().positive().optional(),
   mode: PluginCopyMode.optional(),
 })
-export type PluginDesignCreateCopyArgs = z.infer<typeof PluginDesignCreateCopyArgs>
+export type PluginDesignCreateCopyArgs = z.infer<
+  typeof PluginDesignCreateCopyArgs
+>
 // TRANSPORT: positional signature shipped —
 //   copy(components: ComponentHandle[], displacement: Vec3Handle, options?: { count?, mode? })
 
@@ -1131,6 +1259,7 @@ export type PluginDesignCreateCopyArgs = z.infer<typeof PluginDesignCreateCopyAr
  * | `spaceType` | `PluginSpaceType`? | Space type |
  * | `massType` | `PluginMassType`? | Mass type |
  * | `departmentId` | `PluginDepartmentId`? | Department |
+ * | `storey` | `number`? (int) | Target storey number (default active storey) |
  */
 export const PluginCreateSpaceItem = z.object({
   contour: ContourHandle,
@@ -1140,5 +1269,6 @@ export const PluginCreateSpaceItem = z.object({
   spaceType: PluginSpaceType.optional(),
   massType: PluginMassType.optional(),
   departmentId: PluginDepartmentId.optional(),
+  storey: z.number().int().optional(),
 })
 export type PluginCreateSpaceItem = z.infer<typeof PluginCreateSpaceItem>

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

@@ -105,6 +105,30 @@ export abstract class PluginDesignDoorsApi {
    */
   public abstract getHeight(door: ComponentHandle): PluginApiReturn<number | null>
 
+  /**
+   * Get a door's full dimensions in one call — width along the wall, vertical
+   * height, and thickness through the wall — measured in the door's local
+   * oriented space. Parity with {@linkcode PluginDesignWindowsApi.getDimensions}.
+   *
+   * @param door The door to query
+   * @returns The dimensions, or `null`
+   *
+   * @examplePrompt What are the dimensions of this door?
+   * @examplePrompt How big is the selected door?
+   * @examplePrompt Give me the width, height and depth of this door
+   * @examplePrompt Measure the entrance door including its thickness through the wall
+   *
+   * # Example
+   * ```ts
+   * const [door] = await snaptrude.design.query.listDoors({ isSelected: true })
+   * const dims = await snaptrude.design.doors.getDimensions(door)
+   * if (dims) console.log(dims.width, dims.height, dims.thickness)
+   * ```
+   */
+  public abstract getDimensions(
+    door: ComponentHandle
+  ): PluginApiReturn<PluginDoorDimensions | null>
+
   /**
    * Get the floor a door is hosted on — the storey/level component that
    * supports the door.
@@ -329,6 +353,22 @@ export const PluginDesignDoorArgs = z.object({
 })
 export type PluginDesignDoorArgs = z.infer<typeof PluginDesignDoorArgs>
 
+/**
+ * A door's dimensions (engine units), symmetric with {@linkcode PluginWindowDimensions}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `width` | `number` | Along the wall |
+ * | `height` | `number` | Vertical |
+ * | `thickness` | `number` | Through the wall (engine `length` axis) |
+ */
+export const PluginDoorDimensions = z.object({
+  width: z.number(),
+  height: z.number(),
+  thickness: z.number(),
+})
+export type PluginDoorDimensions = z.infer<typeof PluginDoorDimensions>
+
 /** Mirror axis — tokens mirror the engine `FlipDirection` verbatim (§6.1). */
 export const PluginMirrorAxis = z.enum(["x", "y", "z"])
 export type PluginMirrorAxis = z.infer<typeof PluginMirrorAxis>