@snaptrude/plugin-core 0.0.0-dev-20260908074328 → 0.0.0-dev-20260921132444

package/dist/api/design/create/index.d.ts

@@ -1,13 +1,16 @@
 import * as z from "zod";
 import { PluginApiReturn } from "../../../types";
-import { BrepHandle, ComponentHandle, ContourHandle, ProfileHandle, Vec3Handle } from "../../../handles";
+import { BrepHandle, ComponentHandle, ContourHandle, CurveHandle, ProfileHandle, Vec3Handle } from "../../../handles";
+import { PluginGridStyleOptions } from "./grids";
 import { PluginSpaceType, PluginMassType, PluginDepartmentId } from "../../entity/space";
 import { PluginBuildableEnvelopePolygonVertex, PluginBuildableEnvelopeSetbackTier, PluginBuildableEnvelopeVerticalCap, PluginBuildableEnvelopeCreateResult } from "../../entity/buildableEnvelope";
+import 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.*`).
@@ -173,26 +176,11 @@ export declare abstract class PluginDesignCreateApi {
      * Create a **floor** by extruding a footprint contour by `thickness`
      * (extruded upward).
      *
-     * The parametric engine owns floor topology and may resolve the request
-     * differently than asked: drawing against existing floors can **split** the
-     * footprint into several floors, or **merge** it into a pre-existing
-     * neighbour (that floor's region grows; nothing new is created). The call
-     * honors the engine's resolution and returns **every floor that covers the
-     * requested footprint after the operation** — the newly created floor(s),
-     * and/or the pre-existing floor that absorbed it. The array is never empty
-     * on success; a lone independently-created floor comes back as `[floor]`.
-     *
-     * **Breaking change in 0.11.0** — previously returned a single
-     * {@linkcode ComponentHandle}; callers must switch to the array (the first
-     * element preserves the old single-floor behavior for simple creates).
-     *
      * @param contour - Footprint (outer + holes)
      * @param thickness - Floor thickness (> 0)
      * @param position - Offset from origin
-     * @returns the {@linkcode ComponentHandle}s of every floor covering the
-     *   requested footprint after parametric resolution (created and/or absorbing)
-     * @throws if the contour is invalid, the thickness is not positive, or the
-     *   engine rejected the operation (nothing covers the footprint)
+     * @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
@@ -203,10 +191,51 @@ export declare abstract class PluginDesignCreateApi {
      * ```ts
      * const rect = await snaptrude.core.geom.create.profileRect(5, 4)
      * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
-     * const [floor, ...siblings] = await snaptrude.design.create.floor(contour, 0.1)
+     * 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.
+     */
+    abstract floor(contour: ContourHandle, thickness: number, position?: Vec3Handle): PluginApiReturn<ComponentHandle>;
+    /**
+     * Create **many floors** in one undoable operation (bulk plural of
+     * {@linkcode floor}). Each item extrudes its own footprint contour (outer
+     * profile + holes) upward by its own `thickness`, at its own optional
+     * position offset. Validate-all-or-throw; one command.
+     *
+     * @param items - One {@linkcode PluginCreateFloorItem} per floor to create
+     *   (≥1, ≤1000)
+     * @returns the created floors as {@linkcode ComponentHandle}`[]`, in input order
+     * @throws `VALIDATION` if the items fail the schema (empty array, more than
+     *   1000 items, a non-positive thickness) or a contour is degenerate;
+     *   `HANDLE_INVALID` if a `contour` or `position` handle is unknown or
+     *   released; `OPERATION_FAILED` if extrusion fails (nothing is created —
+     *   `details.itemIndex` is the failing item); `METHOD_NOT_PERMITTED` if the
+     *   plugin may not write.
+     *
+     * @examplePrompt Create floors for all these room outlines at once
+     * @examplePrompt Add a floor to every space in one operation
+     * @examplePrompt Bulk create the floor plates for this building
+     * @examplePrompt Lay 100mm floors across these five footprints in one undo step
+     * @examplePrompt Create the ground and first floor slabs together
+     *
+     * @performance Bulk creator — the whole batch is ONE host round-trip and ONE undo
+     *   entry. Always prefer this over calling `design.create.floor` in a loop: build the
+     *   full `items[]` array first (all contours and offsets up front), then make one call.
+     *
+     * # Example
+     * ```ts
+     * const rect = await snaptrude.core.geom.create.profileRect(5, 4)
+     * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+     * const [ground, upper] = await snaptrude.design.create.floors([
+     *   { contour, thickness: 0.1 },
+     *   { contour, thickness: 0.1, position: await snaptrude.core.math.vec3.new(0, 3, 0) },
+     * ])
      * ```
      */
-    abstract floor(contour: ContourHandle, thickness: number, position?: Vec3Handle): PluginApiReturn<ComponentHandle[]>;
+    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.
@@ -341,13 +370,7 @@ export declare abstract class PluginDesignCreateApi {
      *   single undo entry. The storey must already exist
      *   (`core.storeys.create` first). Default: geometry-derived — a profile
      *   drawn at y = 0 lands on storey 1; the ACTIVE storey is NOT consulted.
-     * @returns the actually-created wall {@linkcode ComponentHandle}s. The
-     *   parametric engine owns wall topology — curves touching existing walls
-     *   may merge into or split against them, so the returned count can differ
-     *   from the input curve count. Profile-ordered 1:1 matches come first,
-     *   then the remaining merged/split products in creation order. Re-query
-     *   (e.g. `design.query.spaces.listGeneratedBim`) rather than assuming a
-     *   wall per input curve.
+     * @returns a {@linkcode ComponentHandle}`[]` (one per wall), in profile order
      * @throws if the profile is empty, `wallType` names no wall type in the
      *   project, `storey` does not exist, or wall creation fails
      *
@@ -374,8 +397,63 @@ export declare 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.
      */
     abstract walls(profile: ProfileHandle, height?: number, thickness?: number, wallType?: string, 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")
+     * ```
+     */
+    abstract wallRuns(items: PluginCreateWallRunItem[]): PluginApiReturn<ComponentHandle[][]>;
     /**
      * Create a **staircase** from a parametric preset, placed at a point.
      *
@@ -447,6 +525,112 @@ export declare abstract class PluginDesignCreateApi {
      * ```
      */
     abstract referenceLines(profile: ProfileHandle, color?: string, thickness?: number, style?: PluginReferenceLineStyle, gridTag?: string): PluginApiReturn<ComponentHandle[]>;
+    /**
+     * Create a free rectangular **structural grid** — one grid group with two
+     * perpendicular line families (`linesX` lines spaced `spacingX` apart, and
+     * `linesY` lines spaced `spacingY` apart) on the active storey. One undoable
+     * creation.
+     *
+     * Units: spacings in Snaptrude units; `angle` in degrees (CCW about +Y,
+     * default 0). Without `center` the grid is centred on the current viewport
+     * (the native tool's behavior) — pass `center` for deterministic placement.
+     *
+     * @param linesX - Line count of the first family (integer ≥ 1)
+     * @param linesY - Line count of the second family (integer ≥ 1)
+     * @param spacingX - First-family spacing (Snaptrude units, > 0)
+     * @param spacingY - Second-family spacing (Snaptrude units, > 0)
+     * @param options - `angle`, `center`, and {@linkcode PluginGridStyleOptions}
+     * @returns the created grid group's {@linkcode ComponentHandle}
+     *
+     * @examplePrompt Create a 5 by 8 structural grid with 6 metre spacing
+     * @examplePrompt Add a column grid rotated 30 degrees
+     * @examplePrompt Set up a structural grid at the site origin
+     *
+     * # Example
+     * ```ts
+     * const centre = await snaptrude.core.math.vec3.new(0, 0, 0)
+     * const grid = await snaptrude.design.create.grid(5, 8, 6, 6, { center: centre })
+     * ```
+     */
+    abstract grid(linesX: number, linesY: number, spacingX: number, spacingY: number, options?: {
+        angle?: number;
+        center?: Vec3Handle;
+    } & PluginGridStyleOptions): PluginApiReturn<ComponentHandle>;
+    /**
+     * Create a **structural grid from a single curve** — one grid group holding
+     * one wing with one line (the draw tool's output). The curve may be a line
+     * or an arc; circles are rejected with `VALIDATION`. Undoable.
+     *
+     * @param curve - The grid line's geometry ({@linkcode CurveHandle}, world space)
+     * @param options - `tag` (defaults to the draw tool's next tag) and
+     *   {@linkcode PluginGridStyleOptions}
+     * @returns the created grid group's {@linkcode ComponentHandle}
+     *
+     * @examplePrompt Draw a grid line from A to B
+     * @examplePrompt Add a curved grid line through these points
+     * @examplePrompt Create grid line "C" along this wall
+     *
+     * # Example
+     * ```ts
+     * const { vec3 } = snaptrude.core.math
+     * const from = await vec3.new(0, 0, 0)
+     * const to = await vec3.new(30, 0, 0)
+     * const curve = await snaptrude.core.geom.create.line(from, to)
+     * const grid = await snaptrude.design.create.gridFromCurve(curve, { tag: "A" })
+     * ```
+     */
+    abstract gridFromCurve(curve: CurveHandle, options?: {
+        tag?: string;
+    } & PluginGridStyleOptions): PluginApiReturn<ComponentHandle>;
+    /**
+     * Generate **structural grids fitted to mass footprints** — one grid group
+     * per footprint cluster, with counts and orientation derived from each
+     * footprint's geometry and the given spacings. All created groups commit as
+     * ONE undoable unit.
+     *
+     * Lenient like the native tool: masses without an extractable footprint
+     * (no B-rep, degenerate top face) are skipped; throws `VALIDATION` only when
+     * NONE of the given masses yields a footprint.
+     *
+     * @param masses - Masses whose footprints seat the grids
+     * @param spacingX - First-family spacing (Snaptrude units, > 0)
+     * @param spacingY - Second-family spacing (Snaptrude units, > 0)
+     * @param options - {@linkcode PluginGridStyleOptions}
+     * @returns the created grid groups' {@linkcode ComponentHandle}`[]`
+     *
+     * @examplePrompt Generate grids for the selected masses
+     * @examplePrompt Auto-generate a 6m structural grid on this building
+     * @examplePrompt Fit column grids to every mass on this storey
+     *
+     * # Example
+     * ```ts
+     * const masses = await snaptrude.design.query.listMasses({ storeys: [1] })
+     * const grids = await snaptrude.design.create.gridsFromMasses(masses, 6, 6)
+     * ```
+     */
+    abstract gridsFromMasses(masses: ComponentHandle[], spacingX: number, spacingY: number, options?: PluginGridStyleOptions): PluginApiReturn<ComponentHandle[]>;
+    /**
+     * Create **columns at every grid-line intersection** of the given grid
+     * groups, sized `width` × `depth` and oriented to the grid axes, on the
+     * grids' storey. All columns commit as ONE undoable unit.
+     *
+     * @param grids - Grid groups whose intersections seat the columns
+     * @param width - Column width (Snaptrude units, > 0)
+     * @param depth - Column depth (Snaptrude units, > 0)
+     * @returns the created columns' {@linkcode ComponentHandle}`[]`
+     * @throws `VALIDATION` when an id does not resolve to a grid group;
+     *   `OPERATION_FAILED` when the grids have no line intersections
+     *
+     * @examplePrompt Generate columns on this grid
+     * @examplePrompt Place 450mm square columns at every grid intersection
+     *
+     * # Example
+     * ```ts
+     * const grids = await snaptrude.design.query.listGrids()
+     * const columns = await snaptrude.design.create.columnsFromGrids(grids, 0.45, 0.45)
+     * ```
+     */
+    abstract columnsFromGrids(grids: ComponentHandle[], width: number, depth: number): PluginApiReturn<ComponentHandle[]>;
     /**
      * Place a **furniture** item from the project library at a world position.
      *
@@ -465,17 +649,19 @@ export declare 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`). `position.y` is always
-     *   grounded: the placed instance's bounding-box bottom rests at it (the
-     *   surface-flush grounding described above)
+     * @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
@@ -499,11 +685,58 @@ export declare 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.
      */
     abstract furniture(catalogId: string, position: Vec3Handle, options?: {
         label?: string;
         createNewSourceMesh?: boolean;
     }, angleInDegrees?: number): PluginApiReturn<ComponentHandle>;
+    /**
+     * Place **many furniture items** in one undoable operation (bulk plural of
+     * {@linkcode furniture}). Each item names a catalog id and an absolute world
+     * position (`position.y` is the REST elevation — the same grounding contract
+     * as the singular creator), with optional label and rotation. A catalog
+     * source shared by several items is fetched and recorded once for the whole
+     * batch, so the host — not the caller — owns source persistence (there is no
+     * per-item `createNewSourceMesh`). Validate-all-or-throw; one command.
+     *
+     * @param items - One {@linkcode PluginCreateFurnitureItem} per instance to
+     *   place (≥1, ≤1000)
+     * @returns the placed instances as {@linkcode ComponentHandle}`[]`, in input order
+     * @throws `VALIDATION` if the items fail the schema (empty array, more than
+     *   1000 items); `HANDLE_INVALID` if a `position` handle is unknown or
+     *   released; `PRECONDITION_FAILED` if a catalog id is unknown, a furniture
+     *   tool is active, or a parametric group is active (exit it first, or place
+     *   items one at a time with `furniture`); `OPERATION_FAILED` if a source
+     *   mesh fails to load or placement fails (nothing is created —
+     *   `details.itemIndex` is the failing item); `METHOD_NOT_PERMITTED` if the plugin may not write.
+     *
+     * @examplePrompt Place all the desks for this office at once
+     * @examplePrompt Furnish every bedroom in one operation
+     * @examplePrompt Bulk place these chairs around the table
+     * @examplePrompt Add the whole furniture layout in a single undo step
+     * @examplePrompt Drop twenty copies of this chair at these positions
+     *
+     * @performance Bulk creator — the whole batch is ONE host round-trip and ONE undo
+     *   entry, and each distinct catalog source loads once. Always prefer this over
+     *   calling `design.create.furniture` in a loop: build the full `items[]` array
+     *   first (all positions and angles up front), then make one call.
+     *
+     * # Example
+     * ```ts
+     * const v = snaptrude.core.math.vec3
+     * const [chair] = await snaptrude.design.furniture.listCatalog()
+     * const placed = await snaptrude.design.create.furnitureItems([
+     *   { catalogId: chair.id, position: await v.new(3, 0, 5), label: "Chair-01" },
+     *   { catalogId: chair.id, position: await v.new(4, 0, 5), angleInDegrees: 90 },
+     *   { catalogId: chair.id, position: await v.new(5, 0, 5), angleInDegrees: 180 },
+     * ])
+     * ```
+     */
+    abstract furnitureItems(items: PluginCreateFurnitureItem[]): PluginApiReturn<ComponentHandle[]>;
     /**
      * Place a **door** from the catalog into a host wall.
      *
@@ -517,12 +750,15 @@ export declare abstract class PluginDesignCreateApi {
      * @param catalogId - Library id: team `_id` or general `fullName`
      * @param hostWall - The wall to host the door
      * @param position - World point projected onto the wall to locate the opening
-     * @param options - Optional placement options: `label` — instance name
-     * @param facing - World point selecting which side of the wall the door faces
-     *   (the room it opens into) — the same convention as approaching the wall
-     *   from that side with the cursor in the interactive tool. Any point clearly
-     *   on that side works (e.g. the room's center). Default: the engine picks a
-     *   side (nondeterministic when `position` sits on the wall centerline).
+     * @param options - Optional placement options: `label` — instance name;
+     *   `hinge` — world point near the jamb the door is hinged on (the door is
+     *   reflected along the wall so its hinged jamb is the one nearer this
+     *   point; default the catalog item's authored hinge side)
+     * @param facing - World point on the side of the wall the door swings open
+     *   to (the room it opens into — where the plan symbol draws the swing arc).
+     *   Any point clearly on that side works (e.g. the room's center). Default:
+     *   the engine picks a side (nondeterministic when `position` sits on the
+     *   wall centerline).
      * @returns the {@linkcode ComponentHandle} of the placed door
      * @throws if the catalog id is unknown, the host is not a wall, the source
      *   mesh fails to load, or the projected point falls **outside** the host wall
@@ -533,6 +769,7 @@ export declare abstract class PluginDesignCreateApi {
      * @examplePrompt Insert the entrance door into this wall
      * @examplePrompt Add a door to the wall and call it Entry-01
      * @examplePrompt Add a door that opens into the living room
+     * @examplePrompt Put a door here hinged on the north jamb
      *
      * # Example
      * ```ts
@@ -552,11 +789,76 @@ export declare abstract class PluginDesignCreateApi {
      *   undefined,
      *   await snaptrude.core.math.vec3.new(3, 0, 9),
      * )
+     * // …and hinged on the jamb nearest a point (here the +x end of the opening):
+     * const hingedRight = await snaptrude.design.create.door(
+     *   entry.id,
+     *   wall,
+     *   await snaptrude.core.math.vec3.new(3, 0, 5),
+     *   { hinge: await snaptrude.core.math.vec3.new(3.5, 0, 5) },
+     *   await snaptrude.core.math.vec3.new(3, 0, 9),
+     * )
      * ```
+     *
+     * @performance For MORE THAN ONE door, call `design.create.doors(items[])` — one host
+     *   round-trip and ONE undo entry, with each host wall re-cut once per opening inside
+     *   that single call. Looping this single-door creator is N round-trips.
      */
     abstract door(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: {
         label?: string;
+        hinge?: Vec3Handle;
     }, facing?: Vec3Handle): PluginApiReturn<ComponentHandle>;
+    /**
+     * Place **many doors** into host walls in one undoable operation (bulk plural
+     * of {@linkcode door}). Each item carries its own catalog id, host wall,
+     * world position, and optional `facing`, `label`, `width` and `height` — the
+     * same fields as a `"door"` {@linkcode PluginDesignCreateOpeningOptions}.
+     * Validate-all-or-throw; one command.
+     *
+     * As with the singular creator, placing an opening **re-cuts its host wall**:
+     * the wall you passed as `hostWall` stops resolving once the call returns.
+     * Several items MAY name the same original wall handle in one call — the host
+     * chains the re-cuts internally — but after the call recover the surviving
+     * wall with `design.query.getHost(opening)`, never by reusing the handle you
+     * passed in.
+     *
+     * @param items - One {@linkcode PluginCreateDoorItem} per door to place
+     *   (≥1, ≤1000)
+     * @returns the placed doors as {@linkcode ComponentHandle}`[]`, in input order
+     * @throws `VALIDATION` if the items fail the schema (empty array, more than
+     *   1000 items, unknown fields, a non-positive `width`/`height`);
+     *   `HANDLE_INVALID` if a `position`, `facing` or `hinge` handle is unknown
+     *   or released; `PRECONDITION_FAILED` if a catalog id is unknown, a `hostWall`
+     *   is not a wall / is locked / is not in the active proposal, the projected
+     *   point falls outside its host wall, or a door tool is active;
+     *   `OPERATION_FAILED` if a source mesh fails to load or placement fails
+     *   (nothing is created — `details.itemIndex` is the failing item);
+     *   `METHOD_NOT_PERMITTED` if the plugin may not write.
+     *
+     * @examplePrompt Add doors to all of these walls at once
+     * @examplePrompt Place a door in every room in one operation
+     * @examplePrompt Bulk add the entrance doors from this schedule
+     * @examplePrompt Put three doors on this wall in a single undo step
+     * @examplePrompt Add all the doors for this floor plan together
+     *
+     * @performance Bulk creator — the whole batch is ONE host round-trip and ONE undo
+     *   entry, and each distinct catalog source loads once. Always prefer this over
+     *   calling `design.create.door` in a loop: build the full `items[]` array first
+     *   (all host walls and points up front), then make one call.
+     *
+     * # Example
+     * ```ts
+     * const v = snaptrude.core.math.vec3
+     * const [wall] = await snaptrude.design.query.listWalls({ isSelected: true })
+     * const [entry] = await snaptrude.design.doors.listCatalog()
+     * const [front, side] = await snaptrude.design.create.doors([
+     *   { catalogId: entry.id, hostWall: wall, position: await v.new(2, 0, 5), label: "D-01" },
+     *   { catalogId: entry.id, hostWall: wall, position: await v.new(6, 0, 5), width: 1.2 },
+     * ])
+     * // `wall` was re-cut twice and no longer resolves — ask the opening for its host:
+     * const currentWall = await snaptrude.design.query.getHost(front)
+     * ```
+     */
+    abstract doors(items: PluginCreateDoorItem[]): PluginApiReturn<ComponentHandle[]>;
     /**
      * Place a **window** from the catalog into a host wall.
      *
@@ -570,11 +872,14 @@ export declare abstract class PluginDesignCreateApi {
      * @param catalogId - Library id: team `_id` or general `fullName`
      * @param hostWall - The wall to host the window
      * @param position - World point projected onto the wall to locate the opening
-     * @param options - Optional placement options: `label` — instance name
-     * @param facing - World point selecting which side of the wall the window
-     *   faces (matters for asymmetric windows, e.g. casement swing) — same
-     *   convention as {@linkcode PluginDesignCreateApi.door}. Default: the engine
-     *   picks a side (nondeterministic when `position` sits on the centerline).
+     * @param options - Optional placement options: `label` — instance name;
+     *   `hinge` — world point near the jamb the window is hinged on (same rule
+     *   as {@linkcode PluginDesignCreateApi.door}; default the catalog item's
+     *   authored side)
+     * @param facing - World point on the side of the wall the window opens to
+     *   (matters for asymmetric windows, e.g. casement swing) — same convention
+     *   as {@linkcode PluginDesignCreateApi.door}. Default: the engine picks a
+     *   side (nondeterministic when `position` sits on the centerline).
      * @returns the {@linkcode ComponentHandle} of the placed window
      * @throws if the catalog id is unknown, the host is not a wall, the source
      *   mesh fails to load, or the projected point falls **outside** the host wall
@@ -597,10 +902,68 @@ export declare 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.
      */
     abstract window(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: {
         label?: string;
+        hinge?: Vec3Handle;
     }, facing?: Vec3Handle): PluginApiReturn<ComponentHandle>;
+    /**
+     * Place **many windows** into host walls in one undoable operation (bulk
+     * plural of {@linkcode window}). Each item carries its own catalog id, host
+     * wall, world position, and optional `facing`, `label`, `width`, `height` and
+     * `sillHeight` — the same fields as a `"window"`
+     * {@linkcode PluginDesignCreateOpeningOptions}. `sillHeight` is measured from
+     * the host wall base to the BOTTOM of the window. Validate-all-or-throw; one
+     * command.
+     *
+     * As with the singular creator, placing an opening **re-cuts its host wall**:
+     * the wall you passed as `hostWall` stops resolving once the call returns.
+     * Several items MAY name the same original wall handle in one call — the host
+     * chains the re-cuts internally — but after the call recover the surviving
+     * wall with `design.query.getHost(opening)`, never by reusing the handle you
+     * passed in.
+     *
+     * @param items - One {@linkcode PluginCreateWindowItem} per window to place
+     *   (≥1, ≤1000)
+     * @returns the placed windows as {@linkcode ComponentHandle}`[]`, in input order
+     * @throws `VALIDATION` if the items fail the schema (empty array, more than
+     *   1000 items, unknown fields, a non-positive `width`/`height`, a negative
+     *   `sillHeight`); `HANDLE_INVALID` if a `position`, `facing` or `hinge`
+     *   handle is unknown or released; `PRECONDITION_FAILED` if a catalog id is unknown, a
+     *   `hostWall` is not a wall / is locked / is not in the active proposal, the
+     *   projected point falls outside its host wall, or a window tool is active;
+     *   `OPERATION_FAILED` if a source mesh fails to load or placement fails
+     *   (nothing is created — `details.itemIndex` is the failing item);
+     *   `METHOD_NOT_PERMITTED` if the plugin may not write.
+     *
+     * @examplePrompt Add windows along this whole facade at once
+     * @examplePrompt Place a window in every bedroom in one operation
+     * @examplePrompt Bulk add the windows from this schedule
+     * @examplePrompt Put four windows on this wall in a single undo step
+     * @examplePrompt Add all the windows with a 0.9m sill height together
+     *
+     * @performance Bulk creator — the whole batch is ONE host round-trip and ONE undo
+     *   entry, and each distinct catalog source loads once. Always prefer this over
+     *   calling `design.create.window` in a loop: build the full `items[]` array first
+     *   (all host walls and points up front), then make one call.
+     *
+     * # Example
+     * ```ts
+     * const v = snaptrude.core.math.vec3
+     * const [wall] = await snaptrude.design.query.listWalls({ isSelected: true })
+     * const [casement] = await snaptrude.design.windows.listCatalog()
+     * const placed = await snaptrude.design.create.windows([
+     *   { catalogId: casement.id, hostWall: wall, position: await v.new(2, 0, 5), sillHeight: 0.9 },
+     *   { catalogId: casement.id, hostWall: wall, position: await v.new(5, 0, 5), sillHeight: 0.9 },
+     * ])
+     * const currentWall = await snaptrude.design.query.getHost(placed[0])
+     * ```
+     */
+    abstract windows(items: PluginCreateWindowItem[]): PluginApiReturn<ComponentHandle[]>;
     /**
      * Place a catalog **door or window** into a host wall with optional size overrides.
      *
@@ -610,7 +973,7 @@ export declare abstract class PluginDesignCreateApi {
      * its center. Placement is asynchronous and committed as one undoable creation.
      *
      * @param options - Opening kind, catalog and host references, placement, and
-     *   optional facing, label, and dimensions
+     *   optional facing (swing side), hinge (hinged jamb), label, and dimensions
      * @returns the {@linkcode ComponentHandle} of the placed door or window
      * @throws if the options are invalid, the catalog id is unknown, the host is
      *   not a wall, loading fails, or the opening cannot be placed on the host
@@ -618,8 +981,9 @@ export declare 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
@@ -1141,7 +1505,7 @@ export type PluginDesignCreateStaircaseArgs = z.infer<typeof PluginDesignCreateS
  * | `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 declare const PluginDesignCreateFurnitureArgs: z.ZodObject<{
@@ -1161,7 +1525,8 @@ export type PluginDesignCreateFurnitureArgs = z.infer<typeof PluginDesignCreateF
  * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the door |
  * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
  * | `label` | `string`? | Instance name (optional) |
- * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the door faces (default engine-chosen) |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the door swings open to (default engine-chosen) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the jamb the door is hinged on (default the catalog item's authored side) |
  */
 export declare const PluginDesignCreateDoorArgs: z.ZodObject<{
     catalogId: z.ZodString;
@@ -1169,6 +1534,7 @@ export declare const PluginDesignCreateDoorArgs: z.ZodObject<{
     position: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"vec3">, string>>;
     label: z.ZodOptional<z.ZodString>;
     facing: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"vec3">, string>>>;
+    hinge: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"vec3">, string>>>;
 }, z.core.$strip>;
 export type PluginDesignCreateDoorArgs = z.infer<typeof PluginDesignCreateDoorArgs>;
 /**
@@ -1180,7 +1546,8 @@ 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) |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the window opens to (default engine-chosen) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the jamb the window is hinged on (default the catalog item's authored side) |
  */
 export declare const PluginDesignCreateWindowArgs: z.ZodObject<{
     catalogId: z.ZodString;
@@ -1188,6 +1555,7 @@ export declare const PluginDesignCreateWindowArgs: z.ZodObject<{
     position: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"vec3">, string>>;
     label: z.ZodOptional<z.ZodString>;
     facing: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"vec3">, string>>>;
+    hinge: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"vec3">, string>>>;
 }, z.core.$strip>;
 export type PluginDesignCreateWindowArgs = z.infer<typeof PluginDesignCreateWindowArgs>;
 /**
@@ -1201,6 +1569,7 @@ export declare const PluginDesignCreateOpeningOptions: z.ZodDiscriminatedUnion<[
     hostWall: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
     position: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"vec3">, string>>;
     facing: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"vec3">, string>>>;
+    hinge: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"vec3">, string>>>;
     label: z.ZodOptional<z.ZodString>;
     width: z.ZodOptional<z.ZodNumber>;
     height: z.ZodOptional<z.ZodNumber>;
@@ -1211,6 +1580,7 @@ export declare const PluginDesignCreateOpeningOptions: z.ZodDiscriminatedUnion<[
     hostWall: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
     position: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"vec3">, string>>;
     facing: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"vec3">, string>>>;
+    hinge: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"vec3">, string>>>;
     label: z.ZodOptional<z.ZodString>;
     width: z.ZodOptional<z.ZodNumber>;
     height: z.ZodOptional<z.ZodNumber>;
@@ -1371,4 +1741,7 @@ export declare const PluginCreateSpaceItem: z.ZodObject<{
     storey: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type PluginCreateSpaceItem = z.infer<typeof PluginCreateSpaceItem>;
+export * from "./opening-fields";
+export * from "./bulk-items";
+export * from "./grids";
 //# sourceMappingURL=index.d.ts.map