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

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

@@ -1,11 +1,13 @@
 import * as z from "zod";
 import { PluginApiReturn } from "../../../types";
-import { BrepHandle, ComponentHandle, ContourHandle, CurveHandle, ProfileHandle, Vec3Handle } from "../../../handles";
+import { BrepHandle, ComponentHandle, ContourHandle, LineHandle, CurveHandle, ProfileHandle, Vec3Handle } from "../../../handles";
 import { PluginGridStyleOptions } from "./grids";
 import { PluginSpaceType, PluginMassType, PluginDepartmentId } from "../../entity/space";
 import { PluginBuildableEnvelopePolygonVertex, PluginBuildableEnvelopeSetbackTier, PluginBuildableEnvelopeVerticalCap, PluginBuildableEnvelopeCreateResult } from "../../entity/buildableEnvelope";
-import type { PluginCreateDoorItem, PluginCreateFloorItem, PluginCreateFurnitureItem, PluginCreateWallRunItem, PluginCreateWindowItem } from "./bulk-items";
+import type { PluginCreateDoorItem, PluginCreateFloorItem, PluginCreateFurnitureItem, PluginCreateVoidItem, PluginCreateWallRunItem, PluginCreateWindowItem } from "./bulk-items";
 import { PluginWallTopProfile } from "./bulk-items";
+import { PluginWallType } from "../types";
+import { PluginFamilyPlacement, PluginFamilyFloorOptions, PluginFamilySlabOptions, PluginFamilyCeilingOptions, PluginFamilyValues } from "../catalog";
 /**
  * `design.create.*` — author new scene-committed BIM entities.
  *
@@ -19,9 +21,17 @@ import { PluginWallTopProfile } from "./bulk-items";
  * Footprint objects take a {@linkcode ContourHandle} (outer profile + holes);
  * build one with `snaptrude.core.geom.create.contourFromProfile(s)`.
  *
- * `door`/`window` place a catalog item into a host wall (the world point is
+ * Family overloads take `{ type, values? }` from `design.catalog`. The family supplies
+ * construction; the contour or axis supplies instance geometry. Geometry uses SU,
+ * while family length overrides use mm and angles use degrees. Omitted parameters
+ * retain family defaults; shared/type, formula and geometry-bound overrides are refused.
+ * Placement never publishes a definition. Unsupported references or geometry fail before mutation.
+ *
+ * `door`/`window` place a parametric family into a host wall (the world point is
  * projected onto the wall face to locate the opening; the wall is re-cut in one
- * undo entry) and throw if the point projects outside the wall. `smartLayout` is
+ * undo entry) and throw if the point projects outside the wall. Voids
+ * (`void`/`voids`) are the third hosted child: holes through slabs, floors,
+ * roofs and ceilings. `smartLayout` is
  * the one creator returning a grouped {@linkcode PluginSmartLayoutResult} rather
  * than a handle — it clones an in-scene template into one or more target spaces,
  * merging every target into a single undo batch (see its JSDoc).
@@ -152,6 +162,9 @@ export declare abstract class PluginDesignCreateApi {
      * Create a **slab** by extruding a footprint contour by `thickness`
      * (default direction: down).
      *
+     * To cut a hole in an EXISTING one, use `design.create.void`; a contour hole
+     * here is baked into the footprint.
+     *
      * @param contour - Footprint (outer + holes)
      * @param thickness - Slab thickness (> 0)
      * @param direction - Extrusion direction (default `"down"`)
@@ -172,15 +185,28 @@ export declare abstract class PluginDesignCreateApi {
      * const slab = await snaptrude.design.create.slab(contour, 0.15, "down", "Plinth")
      * ```
      */
-    abstract slab(contour: ContourHandle, thickness: number, direction?: "up" | "down", slabType?: PluginSlabType): PluginApiReturn<ComponentHandle>;
+    abstract slab(...args: [
+        contour: ContourHandle,
+        thickness: number,
+        direction?: "up" | "down",
+        slabType?: PluginSlabType
+    ] | [contour: ContourHandle, options: PluginFamilySlabOptions]): PluginApiReturn<ComponentHandle>;
     /**
      * Create a **floor** by extruding a footprint contour by `thickness`
      * (extruded upward).
      *
+     * The native family overload takes `{ type, values?, position? }`. Contour
+     * geometry uses SU; family values use mm. The family supplies layer thickness.
+     * PG2 can split or merge the footprint, so both overloads return an array.
+     * A merge into an existing floor can return no newly created handles.
+     *
+     * To cut a hole in an EXISTING one, use `design.create.void`; a contour hole
+     * here is baked into the footprint.
+     *
      * @param contour - Footprint (outer + holes)
      * @param thickness - Floor thickness (> 0)
      * @param position - Offset from origin
-     * @returns the {@linkcode ComponentHandle} of the created floor
+     * @returns Newly created {@linkcode ComponentHandle}s; an empty array after a merge
      * @throws if the contour is invalid or the thickness is not positive
      *
      * @examplePrompt Create a floor from this room outline
@@ -195,11 +221,11 @@ export declare abstract class PluginDesignCreateApi {
      * 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.
+     * @performance For dimensional floors, `design.create.floors(items[])` uses one
+     *   host round-trip and one undo entry. That bulk method does not accept native
+     *   family options; use this method for a family-backed floor.
      */
-    abstract floor(contour: ContourHandle, thickness: number, position?: Vec3Handle): PluginApiReturn<ComponentHandle>;
+    abstract floor(...args: [contour: ContourHandle, thickness: number, position?: Vec3Handle] | [contour: ContourHandle, options: PluginFamilyFloorOptions]): PluginApiReturn<ComponentHandle[]>;
     /**
      * Create **many floors** in one undoable operation (bulk plural of
      * {@linkcode floor}). Each item extrudes its own footprint contour (outer
@@ -241,6 +267,9 @@ export declare abstract class PluginDesignCreateApi {
      * Create a **roof** by extruding a footprint contour by `thickness`. Created
      * flat (extruded downward); pitch/slope is a separate post-creation edit.
      *
+     * To cut a hole in an EXISTING one, use `design.create.void`; a contour hole
+     * here is baked into the footprint.
+     *
      * @param contour - Footprint (outer + holes)
      * @param thickness - Roof-slab thickness (> 0)
      * @returns the {@linkcode ComponentHandle} of the created roof
@@ -258,11 +287,14 @@ export declare abstract class PluginDesignCreateApi {
      * const roof = await snaptrude.design.create.roof(contour, 0.2)
      * ```
      */
-    abstract roof(contour: ContourHandle, thickness: number): PluginApiReturn<ComponentHandle>;
+    abstract roof(contour: ContourHandle, thickness: number | PluginFamilyPlacement): PluginApiReturn<ComponentHandle>;
     /**
      * Create a **ceiling** by extruding a footprint contour by `thickness`, lifted
      * `heightFromFloor` above the floor.
      *
+     * To cut a hole in an EXISTING one, use `design.create.void`; a contour hole
+     * here is baked into the footprint.
+     *
      * @param contour - Footprint (outer + holes)
      * @param thickness - Ceiling thickness (> 0)
      * @param heightFromFloor - Lift above the floor (default 0)
@@ -281,7 +313,7 @@ export declare abstract class PluginDesignCreateApi {
      * const ceiling = await snaptrude.design.create.ceiling(contour, 0.05, 2.8)
      * ```
      */
-    abstract ceiling(contour: ContourHandle, thickness: number, heightFromFloor?: number): PluginApiReturn<ComponentHandle>;
+    abstract ceiling(...args: [contour: ContourHandle, thickness: number, heightFromFloor?: number] | [contour: ContourHandle, options: PluginFamilyCeilingOptions]): PluginApiReturn<ComponentHandle>;
     /**
      * Create a **column** by extruding a cross-section contour upward by `height`
      * from a base `position`. The column is built to EXACTLY `height` — unlike
@@ -309,7 +341,12 @@ export declare abstract class PluginDesignCreateApi {
      * const column = await snaptrude.design.create.column(base, crossSection, 3)
      * ```
      */
-    abstract column(position: Vec3Handle, crossSection: ContourHandle, height: number, directionUp?: Vec3Handle): PluginApiReturn<ComponentHandle>;
+    abstract column(...args: [
+        position: Vec3Handle,
+        crossSection: ContourHandle,
+        height: number,
+        directionUp?: Vec3Handle
+    ] | [axis: LineHandle, options: PluginFamilyPlacement]): PluginApiReturn<ComponentHandle>;
     /**
      * Create a **beam** by extruding a cross-section contour along `direction` by
      * `length`. Matches the Snaptrude beam tool's semantics: the beam body hangs
@@ -350,7 +387,7 @@ export declare abstract class PluginDesignCreateApi {
      * const beam = await snaptrude.design.create.beam(section, 6, alongX)
      * ```
      */
-    abstract beam(section: ContourHandle, length: number, direction?: Vec3Handle): PluginApiReturn<ComponentHandle>;
+    abstract beam(...args: [section: ContourHandle, length: number, direction?: Vec3Handle] | [axis: LineHandle, options: PluginFamilyPlacement]): PluginApiReturn<ComponentHandle>;
     /**
      * Create a connected run of **walls** from a profile — one wall per curve in
      * the profile's chain, with mitred corners at shared endpoints.
@@ -359,12 +396,12 @@ export declare abstract class PluginDesignCreateApi {
      * @param height - Wall height (default engine default)
      * @param thickness - Wall thickness (default: the `wallType`'s total layer
      *   thickness when `wallType` is given, else the engine default)
-     * @param wallType - Wall type to build with — the same searchable list the
-     *   Draw tab's Wall Type dropdown offers. Pass a name from
-     *   `design.types.list("wall")` (the summary's `label`, or its `"wall:…"` id).
-     *   Drives the wall's construction layers and default material, and — when
-     *   `thickness` is omitted — its total layer thickness. Default: the engine's
-     *   generic wall.
+     * @param wallType - Legacy label/`wall:` id, or the exact `nativeFamily`
+     *   `{ id, version }` pin from `design.types.list("wall")`. Native pins are
+     *   authorized on every use; selecting a family in Draw is not registration.
+     *   Native pins support straight horizontal centerlines and flat tops only.
+     *   Omit thickness for native pins; a conflicting explicit thickness rejects.
+     *   Default: the engine's generic wall.
      * @param storey - Target storey (integer: `1` ground, `2` first floor, `-1`
      *   basement — same convention as `design.create.space`). The walls are
      *   assigned to it and lifted to its base elevation, all inside the same
@@ -419,7 +456,7 @@ export declare abstract class PluginDesignCreateApi {
      *   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, topProfiles?: (PluginWallTopProfile | null)[]): PluginApiReturn<ComponentHandle[]>;
+    abstract walls(profile: ProfileHandle, height?: number, thickness?: number, wallType?: PluginWallType, storey?: number, topProfiles?: (PluginWallTopProfile | null)[], values?: PluginFamilyValues): PluginApiReturn<ComponentHandle[]>;
     /**
      * Create **many wall runs** in one undoable operation (bulk plural of
      * {@linkcode walls}). Each item is one full run — a wall per curve in that
@@ -761,30 +798,23 @@ export declare abstract class PluginDesignCreateApi {
      */
     abstract furnitureItems(items: PluginCreateFurnitureItem[]): PluginApiReturn<ComponentHandle[]>;
     /**
-     * Place a **door** from the catalog into a host wall.
+     * Place a parametric **door** family into a host wall.
      *
-     * Identified by a **catalog (library) id** — the team object's stable `_id`
-     * or the general library's `fullName`. Discover ids with
+     * Identified by a saved **family definition id**. Discover ids with
      * {@linkcode PluginDesignDoorsApi.listCatalog}. The world `position` is
      * projected onto the host wall's face to locate the opening; the wall is
      * re-cut and the door hosted in a single undo entry. Placement is
-     * asynchronous (the source mesh is fetched if not cached).
+     * asynchronous. Values and host bindings are evaluated before the first cut.
      *
-     * @param catalogId - Library id: team `_id` or general `fullName`
+     * @param familyId - Hosted door definition ID; legacy mesh catalog IDs are not accepted
      * @param hostWall - The wall to host the door
      * @param position - World point projected onto the wall to locate the opening
-     * @param options - 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).
+     * @param options - `version` pins the definition. `values` sets authored parameters
+     *   (numeric lengths in SU, or unit strings). `label` names the instance.
+     *   `hinge` selects the declared `hand` enum: local -X is left, +X is right.
+     * @param facing - World point selecting local +Z; omitted uses the picked face
      * @returns the {@linkcode ComponentHandle} of the placed door
-     * @throws if the 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
+     * @throws if the family/category/parameters are invalid, or placement or cutting fails
      *
      * @examplePrompt Add a door to this wall here
      * @examplePrompt Place a sliding door on the selected wall
@@ -826,23 +856,22 @@ export declare abstract class PluginDesignCreateApi {
      *   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?: {
+    abstract door(familyId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: {
         label?: string;
         hinge?: Vec3Handle;
+        version?: number;
+        values?: Record<string, number | string>;
     }, facing?: Vec3Handle): PluginApiReturn<ComponentHandle>;
     /**
      * Place **many doors** into host walls in one undoable operation (bulk plural
-     * of {@linkcode door}). Each item carries its own catalog id, host wall,
+     * of {@linkcode door}). Each item carries its own family id, host wall,
      * world position, and optional `facing`, `label`, `width` and `height` — the
      * same fields as a `"door"` {@linkcode PluginDesignCreateOpeningOptions}.
      * Validate-all-or-throw; one command.
      *
-     * 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.
+     * The wall keeps its identity. Several items may use the same host.
+     * Width and height set named recipe parameters, not mesh scale. The recipe's
+     * evaluated hole can include frame allowances. A failed item rolls back the batch.
      *
      * @param items - One {@linkcode PluginCreateDoorItem} per door to place
      *   (≥1, ≤1000)
@@ -850,10 +879,9 @@ export declare abstract class PluginDesignCreateApi {
      * @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
+     *   or released; `PRECONDITION_FAILED` if the family cannot be resolved or saved,
+     *   or a host is locked / is not in the active proposal;
+     *   `OPERATION_FAILED` if placement, containment, overlap checks or cutting fail
      *   (nothing is created — `details.itemIndex` is the failing item);
      *   `METHOD_NOT_PERMITTED` if the plugin may not write.
      *
@@ -864,7 +892,7 @@ export declare abstract class PluginDesignCreateApi {
      * @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
+     *   entry. Always prefer this over
      *   calling `design.create.door` in a loop: build the full `items[]` array first
      *   (all host walls and points up front), then make one call.
      *
@@ -874,38 +902,30 @@ export declare abstract class PluginDesignCreateApi {
      * 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 },
+     *   { familyId: entry.id, hostWall: wall, position: await v.new(2, 0, 5), label: "D-01" },
+     *   { familyId: entry.id, hostWall: wall, position: await v.new(6, 0, 5), values: { width: "1200mm" } },
      * ])
-     * // `wall` was re-cut twice and no longer resolves — ask the opening for its host:
+     * // The host still resolves after both cuts:
      * const currentWall = await snaptrude.design.query.getHost(front)
      * ```
      */
     abstract doors(items: PluginCreateDoorItem[]): PluginApiReturn<ComponentHandle[]>;
     /**
-     * Place a **window** from the catalog into a host wall.
+     * Place a parametric **window** family into a host wall.
      *
-     * Identified by a **catalog (library) id** — the team object's stable `_id`
-     * or the general library's `fullName`. Discover ids with
+     * Identified by a saved **family definition id**. Discover ids with
      * {@linkcode PluginDesignWindowsApi.listCatalog}. The world `position` is
      * projected onto the host wall's face to locate the opening; the wall is
      * re-cut and the window hosted in a single undo entry. Placement is
-     * asynchronous (the source mesh is fetched if not cached).
+     * asynchronous. The sill parameter determines elevation; position Y is ignored.
      *
-     * @param catalogId - Library id: team `_id` or general `fullName`
+     * @param familyId - Hosted window definition ID; legacy mesh catalog IDs are not accepted
      * @param hostWall - The wall to host the window
      * @param position - World point projected onto the wall to locate the opening
-     * @param options - 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).
+     * @param options - `version`, `values`, `label`, and parameter-driven `hinge`, as for door
+     * @param facing - World point selecting local +Z; omitted uses the picked face
      * @returns the {@linkcode ComponentHandle} of the placed window
-     * @throws if the 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
+     * @throws if the family/category/parameters are invalid, or placement or cutting fails
      *
      * @examplePrompt Add a window to this wall here
      * @examplePrompt Place a casement window on the selected wall
@@ -930,25 +950,23 @@ export declare abstract class PluginDesignCreateApi {
      *   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?: {
+    abstract window(familyId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: {
         label?: string;
         hinge?: Vec3Handle;
+        version?: number;
+        values?: Record<string, number | string>;
     }, facing?: Vec3Handle): PluginApiReturn<ComponentHandle>;
     /**
      * Place **many windows** into host walls in one undoable operation (bulk
-     * plural of {@linkcode window}). Each item carries its own catalog id, host
+     * plural of {@linkcode window}). Each item carries its own family id, host
      * wall, world position, and optional `facing`, `label`, `width`, `height` and
      * `sillHeight` — the same fields as a `"window"`
      * {@linkcode PluginDesignCreateOpeningOptions}. `sillHeight` is measured from
      * the host wall base to the BOTTOM of the window. Validate-all-or-throw; one
      * command.
      *
-     * 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.
+     * Hosts keep their identity. Width, height and sillHeight set the declared
+     * width, height and sill parameters before the first cut. No mesh scaling occurs.
      *
      * @param items - One {@linkcode PluginCreateWindowItem} per window to place
      *   (≥1, ≤1000)
@@ -956,10 +974,9 @@ export declare abstract class PluginDesignCreateApi {
      * @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
+     *   handle is unknown or released; `PRECONDITION_FAILED` if the family cannot be
+     *   resolved or saved, or a host is locked / is not in the active proposal;
+     *   `OPERATION_FAILED` if placement, containment, overlap checks or cutting fail
      *   (nothing is created — `details.itemIndex` is the failing item);
      *   `METHOD_NOT_PERMITTED` if the plugin may not write.
      *
@@ -970,7 +987,7 @@ export declare abstract class PluginDesignCreateApi {
      * @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
+     *   entry. Always prefer this over
      *   calling `design.create.window` in a loop: build the full `items[]` array first
      *   (all host walls and points up front), then make one call.
      *
@@ -980,25 +997,161 @@ export declare abstract class PluginDesignCreateApi {
      * 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 },
+     *   { familyId: casement.id, hostWall: wall, position: await v.new(2, 0, 5), values: { sill: "900mm" } },
+     *   { familyId: casement.id, hostWall: wall, position: await v.new(5, 0, 5), values: { sill: "900mm" } },
      * ])
      * const currentWall = await snaptrude.design.query.getHost(placed[0])
      * ```
      */
     abstract windows(items: PluginCreateWindowItem[]): PluginApiReturn<ComponentHandle[]>;
     /**
-     * Place a catalog **door or window** into a host wall with optional size overrides.
+     * Cut a **void** — a hole, opening or shaft — through an existing FLAT slab,
+     * floor, roof or ceiling. The void is a selectable child object of its host
+     * (the "Void" of the Draw Void tool). It always cuts the full host thickness.
+     * It can be moved with `design.transform.move` (a move that would leave the
+     * host is shortened without a report) and removed with
+     * `design.delete.entities`; to resize, delete it and cut a new one
+     * (`design.update.space` refuses a void).
+     *
+     * Give the outline **in plan** (all points at one height): its height is
+     * ignored, and it is dropped straight onto the host's top face, so one outline
+     * works on every storey. Keep it at least 25.4 mm (0.1 SU) inside the host
+     * edge and away from other voids; merge overlapping holes into one outline.
+     * Straight segments and arcs only (no splines).
+     *
+     * **A room has a floor finish AND a structural slab that overlap in plan; a
+     * void in one does not cut the other, so a through-opening needs one void in
+     * each.**
+     *
+     * `getEntityType` reports a void as `"mass"`, and `listMasses` /
+     * `listByType("mass")` include voids: a mass whose `design.query.getHost` is a
+     * slab, floor, roof or ceiling is a void. After its host is copied, a void can
+     * report `null` and be missing from those lists; `listChildren(host)` still
+     * finds it.
+     *
+     * Call it as `snaptrude.design.create.void(...)`; `void` is a reserved word and
+     * cannot be destructured. Voids in walls, on sloped, generated or multi-plane
+     * roofs, and on instanced hosts are not available yet; for a door or window
+     * use `design.create.door` / `window`. To make a NEW slab that already has a
+     * fixed hole, pass a contour with holes to `design.create.slab`; that hole is
+     * part of the footprint, not an object. For a contour's outer loop, pass
+     * `core.geom.query.contour.getOuterProfile(contour)`.
+     *
+     * # Example
+     * ```ts
+     * const m = 1000 / 254 // metres → Snaptrude units (SU)
+     * const [slab] = await snaptrude.design.query.listByType("slab", { isSelected: true })
+     * const center = await snaptrude.core.math.vec3.new(10 * m, 0, 5 * m) // plan point; y is ignored
+     * const outline = await snaptrude.core.geom.create.profileRect(2 * m, 2 * m, center) // 2 m x 2 m
+     * const hole = await snaptrude.design.create.void(slab, outline)
+     * ```
+     *
+     * A round hole is two arcs (a circle handle is not a profile):
+     * ```ts
+     * const m = 1000 / 254
+     * const { vec3 } = snaptrude.core.math
+     * const g = snaptrude.core.geom.create
+     * const r = 0.5 * m // 1 m diameter
+     * const centre = await vec3.new(10 * m, 0, 5 * m)
+     * const axis = await vec3.new(0, -1, 0)
+     * const east = await vec3.new(10 * m + r, 0, 5 * m)
+     * const west = await vec3.new(10 * m - r, 0, 5 * m)
+     * const round = await g.profileFromCurves([await g.arc(east, west, centre, axis), await g.arc(west, east, centre, axis)])
+     * await snaptrude.design.create.void(slab, round) // never destructure `void`
+     * ```
+     *
+     * @param host - The slab, floor, roof or ceiling to cut through
+     * @param outline - Closed, flat plan outline (world SU); its height is ignored
+     * @returns the {@linkcode ComponentHandle} of the new void
+     * @throws `VALIDATION` if the outline is open, crosses itself, is not flat or
+     *   has a spline, or the arguments are the wrong handle kinds or swapped;
+     *   `HANDLE_INVALID` if a handle is unknown or released or the host was
+     *   deleted; `HANDLE_STALE` if the host was rebuilt (re-query it);
+     *   `PRECONDITION_FAILED` if the
+     *   host is a wall or not a slab/floor/roof/ceiling, is sloped, instanced, in
+     *   another building, locked, outside the active proposal, a generated roof or
+     *   not a single plate, or there is no active structure (`engineCode`
+     *   `NO_ACTIVE_STRUCTURE`); `OPERATION_FAILED` with `engineCode`
+     *   `VOID_DOES_NOT_FIT` when the outline crosses the host edge, overlaps a void
+     *   or hole, is closer than 25.4 mm to either, or the fit could not be checked,
+     *   or another `engineCode` when the cut failed (nothing is created, except
+     *   `PUBLISH_FAILED` with a hint that the voids are in the scene: undo, then
+     *   retry); `METHOD_NOT_PERMITTED` if the plugin may not write.
+     *
+     * @examplePrompt Cut a hole in this slab
+     * @examplePrompt Add a 1.2m by 2.4m stair opening in the first-floor slab
+     * @examplePrompt Make a 600 x 600 service penetration in the floor for the riser
+     * @examplePrompt Put a skylight opening through the roof
+     * @examplePrompt Cut a round 1m duct hole in the slab
+     * @examplePrompt Make a cut-out in the ceiling for the light well
+     * @examplePrompt Add a double-height atrium void in the level 2 floor
+     *
+     * @performance Single-void creator. For MORE THAN ONE void, call
+     *   `design.create.voids(items[])`: one host round-trip, ONE undo entry, one cut
+     *   per host.
+     */
+    abstract void(host: ComponentHandle, outline: ProfileHandle): PluginApiReturn<ComponentHandle>;
+    /**
+     * Cut **many voids** (holes, openings, shafts) through slabs, floors, roofs
+     * and ceilings in one undoable operation (bulk plural of {@linkcode void}).
+     * Items may share a host or use different hosts — one shaft outline on every
+     * storey's slab AND floor is one call. Validate-all-or-throw: one item whose
+     * host does not contain the outline rejects the whole batch, so pass only the
+     * hosts that contain it; `details.itemIndex` names the failing item (for two
+     * overlapping items of the batch, the earlier one). At most 50 voids per host
+     * and 200 in all per call. Same outline rules as {@linkcode void}: plan outline, 25.4 mm
+     * (0.1 SU) clearance, floor AND slab are separate hosts. Call it as
+     * `snaptrude.design.create.voids(...)`.
+     *
+     * # Example
+     * ```ts
+     * const m = 1000 / 254
+     * // The user selects the slabs AND floors the shaft passes through; every one must contain the outline.
+     * const hosts = [
+     *   ...(await snaptrude.design.query.listByType("slab", { isSelected: true })),
+     *   ...(await snaptrude.design.query.listByType("floor", { isSelected: true })),
+     * ]
+     * const centre = await snaptrude.core.math.vec3.new(12 * m, 0, -6 * m)
+     * const shaft = await snaptrude.core.geom.create.profileRect(2 * m, 2 * m, centre)
+     * const holes = await snaptrude.design.create.voids(hosts.map((host) => ({ host, outline: shaft })))
+     * ```
+     *
+     * @param items - One {@linkcode PluginCreateVoidItem} per void (≥1, ≤200; ≤50 per host)
+     * @returns the new voids as {@linkcode ComponentHandle}`[]`, in input order
+     * @throws `VALIDATION` if the items fail the schema (empty array, more than
+     *   1000 items, unknown fields), an outline is invalid (as for
+     *   {@linkcode void}), more than 50 items share one host, or there are more
+     *   than 200 items; plus every code {@linkcode void} throws, each with
+     *   `details.itemIndex`. Nothing is created on any failure, except
+     *   `PUBLISH_FAILED` (as for {@linkcode void}).
+     *
+     * @examplePrompt Cut a lift shaft through every floor slab of the core
+     * @examplePrompt Cut a 2m x 2m shaft through all the slabs at this location
+     * @examplePrompt Make stair openings in all the floors above the staircases
+     * @examplePrompt Make holes in the roof for these three skylights
+     * @examplePrompt Cut openings in each storey's slab matching this outline
+     * @examplePrompt Punch the same riser penetration through every floor at once
+     *
+     * @performance ONE host round-trip, ONE undo entry, ONE cut per host. Never call
+     *   `void` in a loop. Runs synchronously on the main thread: 50 voids on one
+     *   host take about 1 s, and the time grows with the number of hosts (caps:
+     *   50 per host, 200 per call).
+     */
+    abstract voids(items: PluginCreateVoidItem[]): PluginApiReturn<ComponentHandle[]>;
+    /**
+     * Place a parametric **door or window** into a host wall with parameter overrides.
      *
      * The world `position` is projected onto the host wall to locate the opening.
      * All supplied dimensions use Snaptrude engine units. Window `sillHeight` is
      * measured from the host wall base to the bottom of the window, not to
      * its center. Placement is asynchronous and committed as one undoable creation.
      *
-     * @param options - Opening kind, catalog and host references, placement, and
+     * Wall only. For a hole in a slab, floor or roof use `design.create.void`.
+     *
+     * @param options - Opening kind, family and host references, placement, and
      *   optional facing (swing side), hinge (hinged jamb), label, and dimensions
      * @returns the {@linkcode ComponentHandle} of the placed door or window
-     * @throws if the options are invalid, the catalog id is unknown, the host is
+     * @throws if the options are invalid, the family id is unknown, the host is
      *   not a wall, loading fails, or the opening cannot be placed on the host
      *
      * @examplePrompt Add a 1m wide door to this wall here
@@ -1012,7 +1165,7 @@ export declare abstract class PluginDesignCreateApi {
      * ```ts
      * const opening = await snaptrude.design.create.opening({
      *   kind: "window",
-     *   catalogId: windowType.id,
+     *   familyId: windowType.id,
      *   hostWall: wall,
      *   position: await snaptrude.core.math.vec3.new(3, 0, 5),
      *   width: 1.2,
@@ -1465,7 +1618,7 @@ 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: `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) |
+ * | `wallType` | {@linkcode PluginWallType}? | Legacy name/id or exact native `{ id, version }` pin from `design.types.list("wall")` (default generic) |
  * | `storey` | `number`? | Target storey (integer, must exist) — walls assigned + lifted to its base in the same undo entry (default: geometry-derived) |
  * | `topProfiles` | ({@linkcode PluginWallTopProfile} \| `null`)[]? | Top edge per curve (same order); `null`/missing = flat at `height`. Straight curves only |
  */
@@ -1473,12 +1626,16 @@ export declare const PluginDesignCreateWallsArgs: z.ZodObject<{
     profile: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<import("../../..").Handle<"profile">, string>>;
     height: z.ZodOptional<z.ZodNumber>;
     thickness: z.ZodOptional<z.ZodNumber>;
-    wallType: z.ZodOptional<z.ZodString>;
+    wallType: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodNumber;
+    }, z.core.$strip>]>>;
     storey: z.ZodOptional<z.ZodNumber>;
     topProfiles: z.ZodOptional<z.ZodArray<z.ZodNullable<z.ZodArray<z.ZodObject<{
         along: z.ZodNumber;
         height: z.ZodNumber;
     }, z.core.$strip>>>>>;
+    values: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodBoolean]>>>;
 }, z.core.$strip>;
 export type PluginDesignCreateWallsArgs = z.infer<typeof PluginDesignCreateWallsArgs>;
 /**
@@ -1549,20 +1706,26 @@ export type PluginDesignCreateFurnitureArgs = z.infer<typeof PluginDesignCreateF
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `familyId` | `string` | Hosted door family definition ID |
+ * | `version` | `number`? | Exact version; newest known by default |
+ * | `values` | `Record<string, number \| string>`? | Parameters; numeric lengths use SU |
  * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the door |
  * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
  * | `label` | `string`? | Instance name (optional) |
  * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the door swings open to (default engine-chosen) |
- * | `hinge` | {@linkcode Vec3Handle}? | World point near the jamb the door is hinged on (default the catalog item's authored side) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the hinged jamb; requires hand control |
  */
 export declare const PluginDesignCreateDoorArgs: z.ZodObject<{
-    catalogId: z.ZodString;
+    familyId: z.ZodString;
+    version: z.ZodOptional<z.ZodNumber>;
+    values: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>;
     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>>;
-    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>>>;
+    label: z.ZodOptional<z.ZodString>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type PluginDesignCreateDoorArgs = z.infer<typeof PluginDesignCreateDoorArgs>;
 /**
@@ -1570,20 +1733,26 @@ export type PluginDesignCreateDoorArgs = z.infer<typeof PluginDesignCreateDoorAr
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `familyId` | `string` | Hosted window family definition ID |
+ * | `version` | `number`? | Exact version; newest known by default |
+ * | `values` | `Record<string, number \| string>`? | Parameters; numeric lengths use SU |
  * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the window |
  * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
  * | `label` | `string`? | Instance name (optional) |
  * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the window opens to (default engine-chosen) |
- * | `hinge` | {@linkcode Vec3Handle}? | World point near the jamb the window is hinged on (default the catalog item's authored side) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the hinged jamb; requires hand control |
  */
 export declare const PluginDesignCreateWindowArgs: z.ZodObject<{
-    catalogId: z.ZodString;
+    familyId: z.ZodString;
+    version: z.ZodOptional<z.ZodNumber>;
+    values: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>;
     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>>;
-    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>>>;
+    label: z.ZodOptional<z.ZodString>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type PluginDesignCreateWindowArgs = z.infer<typeof PluginDesignCreateWindowArgs>;
 /**
@@ -1593,7 +1762,9 @@ export type PluginDesignCreateWindowArgs = z.infer<typeof PluginDesignCreateWind
  * the distance from the host wall base to the bottom of the window.
  */
 export declare const PluginDesignCreateOpeningOptions: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    catalogId: z.ZodString;
+    familyId: z.ZodString;
+    version: z.ZodOptional<z.ZodNumber>;
+    values: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>;
     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>>>;
@@ -1604,7 +1775,9 @@ export declare const PluginDesignCreateOpeningOptions: z.ZodDiscriminatedUnion<[
     kind: z.ZodLiteral<"door">;
 }, z.core.$strict>, z.ZodObject<{
     sillHeight: z.ZodOptional<z.ZodNumber>;
-    catalogId: z.ZodString;
+    familyId: z.ZodString;
+    version: z.ZodOptional<z.ZodNumber>;
+    values: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>;
     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>>>;