@snaptrude/plugin-core 0.9.6 → 0.9.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/api/core/io/import/index.ts

@@ -183,7 +183,10 @@ export abstract class PluginCoreIoImportApi {
    * if (cad) console.log("DWG imported as CAD underlay:", cad)
    * ```
    */
-  public abstract dwg(source: string, storey?: number): PluginApiReturn<ImportJobHandle>
+  public abstract dwg(
+    source: string,
+    storey?: number,
+  ): PluginApiReturn<ImportJobHandle>
 
   /**
    * Sketch a CAD underlay from **already-parsed CAD JSON** — synchronous, with no
@@ -214,7 +217,10 @@ export abstract class PluginCoreIoImportApi {
    * )
    * ```
    */
-  public abstract cadJson(cad: CadJsonInput, storey?: number): PluginApiReturn<UnderlayHandle>
+  public abstract cadJson(
+    cad: CadJsonInput,
+    storey?: number,
+  ): PluginApiReturn<UnderlayHandle>
 
   /**
    * Import a **3D model** file and place it in the scene as a component.
@@ -239,7 +245,9 @@ export abstract class PluginCoreIoImportApi {
    * @returns the placed {@linkcode ComponentHandle}.
    * @throws if writes are disabled, the source can't be loaded, the format is
    *   unsupported, conversion/placement fails, or the converted model cannot be
-   *   found in the library after upload.
+   *   found in the library after upload; `PRECONDITION_FAILED`
+   *   (`details.engineCode: "TOOL_ACTIVE"`) while the interactive furniture tool is
+   *   active — finish or cancel it first.
    *
    * @examplePrompt Import this SketchUp model onto storey 1
    * @examplePrompt Bring in this OBJ file and place it at the origin

package/src/api/design/create/bulk-items.ts

@@ -0,0 +1,182 @@
+import * as z from "zod"
+import { ContourHandle, ProfileHandle, Vec3Handle } from "../../../handles"
+import { PluginOpeningBaseOptions } from "./opening-fields"
+
+/**
+ * Maximum items per bulk `design.create.*` call. A bounded request keeps
+ * validation, command capture and rollback work finite; split a larger import
+ * into separate awaited batches, each with its own undo entry.
+ */
+export const PLUGIN_CREATE_BATCH_LIMIT = 1000
+
+// ---------------------------------------------------------------------------
+// wallRuns
+// ---------------------------------------------------------------------------
+
+/**
+ * One wall run to create via {@linkcode PluginDesignCreateApi.wallRuns} — the
+ * same inputs as {@linkcode PluginDesignCreateApi.walls}, one run per item.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ProfileHandle} | Ordered curve chain (wall centerlines) |
+ * | `height` | `number`? | Wall height (Snaptrude units, > 0; default engine default) |
+ * | `thickness` | `number`? | Wall thickness (Snaptrude units, > 0; 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`? (int) | Target storey (must exist) — the run's walls are assigned + lifted to its base in the same undo entry (default: geometry-derived) |
+ */
+export const PluginCreateWallRunItem = z.object({
+  profile: ProfileHandle,
+  height: z.number().optional(),
+  thickness: z.number().optional(),
+  wallType: z.string().min(1).optional(),
+  storey: z.number().int().optional(),
+})
+export type PluginCreateWallRunItem = z.infer<typeof PluginCreateWallRunItem>
+
+/** The `items` array of {@linkcode PluginDesignCreateApi.wallRuns} (1…1000). */
+export const PluginCreateWallRunItems = z
+  .array(PluginCreateWallRunItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateWallRunItems = z.infer<typeof PluginCreateWallRunItems>
+
+// ---------------------------------------------------------------------------
+// floors
+// ---------------------------------------------------------------------------
+
+/**
+ * One floor to create via {@linkcode PluginDesignCreateApi.floors} — the same
+ * footprint-extrude inputs as {@linkcode PluginDesignCreateApi.floor}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | Footprint (outer profile + holes) |
+ * | `thickness` | `number` | Floor thickness (Snaptrude units, > 0) |
+ * | `position` | {@linkcode Vec3Handle}? | Offset from origin (default origin) |
+ */
+export const PluginCreateFloorItem = z.object({
+  contour: ContourHandle,
+  thickness: z.number(),
+  position: Vec3Handle.optional(),
+})
+export type PluginCreateFloorItem = z.infer<typeof PluginCreateFloorItem>
+
+/** The `items` array of {@linkcode PluginDesignCreateApi.floors} (1…1000). */
+export const PluginCreateFloorItems = z
+  .array(PluginCreateFloorItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateFloorItems = z.infer<typeof PluginCreateFloorItems>
+
+// ---------------------------------------------------------------------------
+// doors / windows
+// ---------------------------------------------------------------------------
+
+/**
+ * One door to place via {@linkcode PluginDesignCreateApi.doors} — the same
+ * fields as a `"door"` {@linkcode PluginDesignCreateOpeningOptions}, so the
+ * size overrides singular {@linkcode PluginDesignCreateApi.door} lacks are
+ * available per item. `facing` is a WORLD POINT on the side of the wall the
+ * door opens into, not a direction. Rejects unknown fields.
+ *
+ * | 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 |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side the door faces (default engine-chosen) |
+ * | `label` | `string`? | Instance name (optional) |
+ * | `width` | `number`? | Width override (Snaptrude units, > 0; default the catalog item's) |
+ * | `height` | `number`? | Height override (Snaptrude units, > 0; default the catalog item's) |
+ */
+export const PluginCreateDoorItem = z
+  .object({ ...PluginOpeningBaseOptions })
+  .strict()
+export type PluginCreateDoorItem = z.infer<typeof PluginCreateDoorItem>
+
+/** The `items` array of {@linkcode PluginDesignCreateApi.doors} (1…1000). */
+export const PluginCreateDoorItems = z
+  .array(PluginCreateDoorItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateDoorItems = z.infer<typeof PluginCreateDoorItems>
+
+/**
+ * One window to place via {@linkcode PluginDesignCreateApi.windows} — the same
+ * fields as a `"window"` {@linkcode PluginDesignCreateOpeningOptions}.
+ * `sillHeight` is a nonnegative Snaptrude-unit distance from the host wall's
+ * base to the BOTTOM of the window, not to its center. `facing` is a WORLD
+ * POINT on the desired side of the wall, not a direction. Rejects unknown
+ * fields.
+ *
+ * | 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 |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side the window faces (default engine-chosen) |
+ * | `label` | `string`? | Instance name (optional) |
+ * | `width` | `number`? | Width override (Snaptrude units, > 0; default the catalog item's) |
+ * | `height` | `number`? | Height override (Snaptrude units, > 0; default the catalog item's) |
+ * | `sillHeight` | `number`? | Wall base to window bottom (Snaptrude units, ≥ 0; default the catalog item's) |
+ */
+export const PluginCreateWindowItem = z
+  .object({
+    ...PluginOpeningBaseOptions,
+    sillHeight: z.number().finite().nonnegative().optional(),
+  })
+  .strict()
+export type PluginCreateWindowItem = z.infer<typeof PluginCreateWindowItem>
+
+/** The `items` array of {@linkcode PluginDesignCreateApi.windows} (1…1000). */
+export const PluginCreateWindowItems = z
+  .array(PluginCreateWindowItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateWindowItems = z.infer<typeof PluginCreateWindowItems>
+
+// ---------------------------------------------------------------------------
+// furnitureItems
+// ---------------------------------------------------------------------------
+
+/**
+ * One furniture instance to place via
+ * {@linkcode PluginDesignCreateApi.furnitureItems} — the same inputs as
+ * {@linkcode PluginDesignCreateApi.furniture} minus `createNewSourceMesh`: in a
+ * batch the host owns source-mesh persistence (a source is recorded once per
+ * call, however many items reuse it).
+ *
+ * `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.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `position` | {@linkcode Vec3Handle} | Absolute world placement point (`y` = rest elevation) |
+ * | `label` | `string`? | Instance name and readable label (default auto `${name}Ins${n}`) |
+ * | `angleInDegrees` | `number`? | Rotation about the vertical axis, in degrees (default unrotated) |
+ */
+export const PluginCreateFurnitureItem = z.object({
+  catalogId: z.string().min(1),
+  position: Vec3Handle,
+  label: z.string().optional(),
+  angleInDegrees: z.number().optional(),
+})
+export type PluginCreateFurnitureItem = z.infer<
+  typeof PluginCreateFurnitureItem
+>
+
+/**
+ * The `items` array of {@linkcode PluginDesignCreateApi.furnitureItems}
+ * (1…1000).
+ */
+export const PluginCreateFurnitureItems = z
+  .array(PluginCreateFurnitureItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateFurnitureItems = z.infer<
+  typeof PluginCreateFurnitureItems
+>

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

@@ -18,12 +18,21 @@ import {
   PluginBuildableEnvelopeVerticalCap,
   PluginBuildableEnvelopeCreateResult,
 } from "../../entity/buildableEnvelope"
+import { PluginOpeningBaseOptions } from "./opening-fields"
+import type {
+  PluginCreateDoorItem,
+  PluginCreateFloorItem,
+  PluginCreateFurnitureItem,
+  PluginCreateWallRunItem,
+  PluginCreateWindowItem,
+} 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) — the
+ * {@linkcode ComponentHandle} (or `ComponentHandle[]` for plural creators;
+ * `wallRuns` returns one `ComponentHandle[]` per run) — the
  * `Component.id` of the created entity, resolvable across the rest of the
  * `design.*` surface. Creation is an undoable host call; it **throws** on failure
  * (no `Result` wrapper — consistent with `core.geom.create.*`).
@@ -234,6 +243,10 @@ export abstract class PluginDesignCreateApi {
    * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
    * const floor = await snaptrude.design.create.floor(contour, 0.1)
    * ```
+   *
+   * @performance For 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,
@@ -241,6 +254,46 @@ export abstract class PluginDesignCreateApi {
     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.
@@ -422,6 +475,10 @@ export abstract class PluginDesignCreateApi {
    *   centerlines, 3, undefined, brick.label,
    * )
    * ```
+   *
+   * @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,
@@ -431,6 +488,60 @@ export abstract class PluginDesignCreateApi {
     storey?: number,
   ): 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. 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
+   *
+   * @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 },
+   * ])
+   * 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.
    *
@@ -535,15 +646,19 @@ export abstract class PluginDesignCreateApi {
    *   `position.y` (the same surface-flush contract as interactive drag-drop) —
    *   pass the floor/storey elevation to stand furniture on it; never add half
    *   the item's height yourself.
-   * @param options - Optional placement options: `label` — instance name
-   *   (default auto `${name}Ins${n}`); `createNewSourceMesh` — emit a
-   *   source-mesh creation command (default `true`)
+   * @param options - Optional placement options: `label` — instance name and
+   *   readable label (`design.query.getLabel`; default auto `${name}Ins${n}`);
+   *   `createNewSourceMesh` — legacy flag, kept for compatibility. The host owns
+   *   source-mesh persistence: a catalog source is recorded exactly once, by the
+   *   first placement that brings it in, and this flag cannot skip that record.
    * @param angleInDegrees - Optional signed rotation about the vertical axis, in
    *   degrees (same convention as {@linkcode PluginDesignTransformApi.rotate}).
    *   Applied at creation time so it is part of the placement's single undo entry.
    *   Default: the item's own (unrotated) orientation.
    * @returns the {@linkcode ComponentHandle} of the placed furniture instance
-   * @throws if the catalog id is unknown, the source mesh fails to load, or placement fails
+   * @throws if the catalog id is unknown, the source mesh fails to load, or placement fails;
+   *   `PRECONDITION_FAILED` (`details.engineCode: "TOOL_ACTIVE"`) while the interactive
+   *   furniture tool is active — finish or cancel it first
    *
    * @examplePrompt Place a chair from the library at this spot
    * @examplePrompt Add a sofa from the furniture catalog to the living room
@@ -567,6 +682,10 @@ export abstract class PluginDesignCreateApi {
    *   90,
    * )
    * ```
+   *
+   * @performance For MORE THAN ONE item, call `design.create.furnitureItems(items[])` —
+   *   one host round-trip and ONE undo entry, and a catalog source shared by several
+   *   items is fetched once. Looping this single-item creator is N round-trips.
    */
   public abstract furniture(
     catalogId: string,
@@ -575,6 +694,52 @@ export abstract class PluginDesignCreateApi {
     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.
    *
@@ -624,6 +789,10 @@ export abstract class PluginDesignCreateApi {
    *   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,
@@ -633,6 +802,61 @@ export abstract class PluginDesignCreateApi {
     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` or `facing` 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.
    *
@@ -673,6 +897,10 @@ export abstract class PluginDesignCreateApi {
    *   { label: "Win-01" },
    * )
    * ```
+   *
+   * @performance For MORE THAN ONE window, call `design.create.windows(items[])` — one
+   *   host round-trip and ONE undo entry, with each host wall re-cut once per opening
+   *   inside that single call. Looping this single-window creator is N round-trips.
    */
   public abstract window(
     catalogId: string,
@@ -682,6 +910,62 @@ export abstract class PluginDesignCreateApi {
     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` or `facing` 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.
    *
@@ -699,8 +983,9 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Add a 1m wide door to this wall here
    * @examplePrompt Place a window with a 0.9m sill height on the selected wall
    *
-   * @performance Single-opening creator — use it for one hosted opening. A plural
-   *   API is intentionally unavailable until host placement can be atomic.
+   * @performance Single-opening creator — use it for one hosted opening. For MORE
+   *   THAN ONE, call `design.create.doors(items[])` / `design.create.windows(items[])`:
+   *   the same per-item fields, one host round-trip, ONE undo entry.
    *
    * # Example
    * ```ts
@@ -1262,7 +1547,7 @@ export type PluginDesignCreateStaircaseArgs = z.infer<
  * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
  * | `position` | {@linkcode Vec3Handle} | Absolute world placement point |
  * | `label` | `string`? | Instance name (default auto `${name}Ins${n}`) |
- * | `createNewSourceMesh` | `boolean`? | Emit a source-mesh creation command (default `true`) |
+ * | `createNewSourceMesh` | `boolean`? | Legacy, kept for compatibility; the host records a catalog source exactly once and this flag cannot skip it |
  * | `angleInDegrees` | `number`? | Rotation about the vertical axis, in degrees (default unrotated) |
  */
 export const PluginDesignCreateFurnitureArgs = z.object({
@@ -1338,16 +1623,6 @@ export type PluginDesignCreateWindowArgs = z.infer<
 // opening
 // ---------------------------------------------------------------------------
 
-const PluginOpeningBaseOptions = {
-  catalogId: z.string().min(1),
-  hostWall: ComponentHandle,
-  position: Vec3Handle,
-  facing: Vec3Handle.optional(),
-  label: z.string().optional(),
-  width: z.number().finite().positive().optional(),
-  height: z.number().finite().positive().optional(),
-}
-
 /**
  * Options for {@linkcode PluginDesignCreateApi.opening}, discriminated by
  * `kind`. Width and height are positive Snaptrude engine-unit values.
@@ -1524,3 +1799,6 @@ export const PluginCreateSpaceItem = z.object({
   storey: z.number().int().optional(),
 })
 export type PluginCreateSpaceItem = z.infer<typeof PluginCreateSpaceItem>
+
+export * from "./opening-fields"
+export * from "./bulk-items"