@snaptrude/plugin-core 0.0.0-dev-20260911064951 → 0.0.0-surfaces-20260921090636

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

@@ -18,21 +18,12 @@ 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;
- * `wallRuns` returns one `ComponentHandle[]` per run) — the
+ * {@linkcode ComponentHandle} (or `ComponentHandle[]` for plural creators) — the
  * `Component.id` of the created entity, resolvable across the rest of the
  * `design.*` surface. Creation is an undoable host call; it **throws** on failure
  * (no `Result` wrapper — consistent with `core.geom.create.*`).
@@ -243,10 +234,6 @@ 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,
@@ -254,46 +241,6 @@ 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.
@@ -475,10 +422,6 @@ 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,
@@ -488,60 +431,6 @@ 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.
    *
@@ -646,19 +535,15 @@ 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 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 options - Optional placement options: `label` — instance name
+   *   (default auto `${name}Ins${n}`); `createNewSourceMesh` — emit a
+   *   source-mesh creation command (default `true`)
    * @param angleInDegrees - Optional signed rotation about the vertical axis, in
    *   degrees (same convention as {@linkcode PluginDesignTransformApi.rotate}).
    *   Applied at creation time so it is part of the placement's single undo entry.
    *   Default: the item's own (unrotated) orientation.
    * @returns the {@linkcode ComponentHandle} of the placed furniture instance
-   * @throws if the catalog id is unknown, the source mesh fails to load, or placement fails;
-   *   `PRECONDITION_FAILED` (`details.engineCode: "TOOL_ACTIVE"`) while the interactive
-   *   furniture tool is active — finish or cancel it first
+   * @throws if the catalog id is unknown, the source mesh fails to load, or placement fails
    *
    * @examplePrompt Place a chair from the library at this spot
    * @examplePrompt Add a sofa from the furniture catalog to the living room
@@ -682,10 +567,6 @@ 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,
@@ -694,52 +575,6 @@ 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.
    *
@@ -753,15 +588,12 @@ export 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;
-   *   `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 - Optional placement options: `label` — instance name
+   * @param facing - World point selecting which side of the wall the door faces
+   *   (the room it opens into) — the same convention as approaching the wall
+   *   from that side with the cursor in the interactive tool. Any point clearly
+   *   on that side works (e.g. the room's center). Default: the engine picks a
+   *   side (nondeterministic when `position` sits on the wall centerline).
    * @returns the {@linkcode ComponentHandle} of the placed door
    * @throws if the catalog id is unknown, the host is not a wall, the source
    *   mesh fails to load, or the projected point falls **outside** the host wall
@@ -772,7 +604,6 @@ export 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
@@ -792,83 +623,16 @@ export 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.
    */
   public abstract door(
     catalogId: string,
     hostWall: ComponentHandle,
     position: Vec3Handle,
-    options?: { label?: string; hinge?: Vec3Handle },
+    options?: { label?: 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,
-   * 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)
-   * ```
-   */
-  public abstract doors(
-    items: PluginCreateDoorItem[],
-  ): PluginApiReturn<ComponentHandle[]>
-
   /**
    * Place a **window** from the catalog into a host wall.
    *
@@ -882,14 +646,11 @@ export 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;
-   *   `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 - Optional placement options: `label` — instance name
+   * @param facing - World point selecting which side of the wall the window
+   *   faces (matters for asymmetric windows, e.g. casement swing) — same
+   *   convention as {@linkcode PluginDesignCreateApi.door}. Default: the engine
+   *   picks a side (nondeterministic when `position` sits on the centerline).
    * @returns the {@linkcode ComponentHandle} of the placed window
    * @throws if the catalog id is unknown, the host is not a wall, the source
    *   mesh fails to load, or the projected point falls **outside** the host wall
@@ -912,75 +673,15 @@ 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,
     hostWall: ComponentHandle,
     position: Vec3Handle,
-    options?: { label?: string; hinge?: Vec3Handle },
+    options?: { label?: 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
-   * 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])
-   * ```
-   */
-  public abstract windows(
-    items: PluginCreateWindowItem[],
-  ): PluginApiReturn<ComponentHandle[]>
-
   /**
    * Place a catalog **door or window** into a host wall with optional size overrides.
    *
@@ -990,7 +691,7 @@ export 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 (swing side), hinge (hinged jamb), label, and dimensions
+   *   optional facing, 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
@@ -998,9 +699,8 @@ 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. 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.
+   * @performance Single-opening creator — use it for one hosted opening. A plural
+   *   API is intentionally unavailable until host placement can be atomic.
    *
    * # Example
    * ```ts
@@ -1562,7 +1262,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`? | Legacy, kept for compatibility; the host records a catalog source exactly once and this flag cannot skip it |
+ * | `createNewSourceMesh` | `boolean`? | Emit a source-mesh creation command (default `true`) |
  * | `angleInDegrees` | `number`? | Rotation about the vertical axis, in degrees (default unrotated) |
  */
 export const PluginDesignCreateFurnitureArgs = z.object({
@@ -1591,8 +1291,7 @@ export type PluginDesignCreateFurnitureArgs = z.infer<
  * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the door |
  * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
  * | `label` | `string`? | Instance name (optional) |
- * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the door 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) |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the door faces (default engine-chosen) |
  */
 export const PluginDesignCreateDoorArgs = z.object({
   catalogId: z.string().min(1),
@@ -1600,13 +1299,12 @@ export const PluginDesignCreateDoorArgs = z.object({
   position: Vec3Handle,
   label: z.string().optional(),
   facing: Vec3Handle.optional(),
-  hinge: Vec3Handle.optional(),
 })
 export type PluginDesignCreateDoorArgs = z.infer<
   typeof PluginDesignCreateDoorArgs
 >
-// TRANSPORT: positional signature shipped — facing is the trailing 5th arg, hinge rides in options:
-//   door(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: { label?, hinge? }, facing?: Vec3Handle)
+// TRANSPORT: positional signature shipped — facing is the trailing 5th arg:
+//   door(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: { label? }, facing?: Vec3Handle)
 
 // ---------------------------------------------------------------------------
 // window
@@ -1621,8 +1319,7 @@ export type PluginDesignCreateDoorArgs = z.infer<
  * | `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) |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the window faces (default engine-chosen) |
  */
 export const PluginDesignCreateWindowArgs = z.object({
   catalogId: z.string().min(1),
@@ -1630,18 +1327,27 @@ export const PluginDesignCreateWindowArgs = z.object({
   position: Vec3Handle,
   label: z.string().optional(),
   facing: Vec3Handle.optional(),
-  hinge: Vec3Handle.optional(),
 })
 export type PluginDesignCreateWindowArgs = z.infer<
   typeof PluginDesignCreateWindowArgs
 >
-// TRANSPORT: positional signature shipped — facing is the trailing 5th arg, hinge rides in options:
-//   window(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: { label?, hinge? }, facing?: Vec3Handle)
+// TRANSPORT: positional signature shipped — facing is the trailing 5th arg:
+//   window(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: { label? }, facing?: Vec3Handle)
 
 // ---------------------------------------------------------------------------
 // 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.
@@ -1818,6 +1524,3 @@ 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"

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

@@ -39,10 +39,6 @@ export abstract class PluginDesignDeleteApi {
    * children are removed and linked-list neighbours are fixed up — not caller-tunable
    * in v1. Undoable — commits as a **single** undo entry.
    *
-   * Dimension lines anchored to a deleted entity are removed with it, in the same undo
-   * entry, exactly as the editor's Delete key does — see `design.dimensions`. They are
-   * NOT listed in `affected`, which reports component handles only.
-   *
    * @param components - Entities to delete. Unknown/forged handles reject the whole call (fail-fast).
    * @returns The entities that were deleted, as {@linkcode ComponentHandle}`[]`
    *   (echoed host-side from the resolved+deleted set — the engine returns no ids).

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

@@ -8,11 +8,9 @@ import { PluginDesignChangeResult } from "../lock"
  * `design.create.door`; generic reads (`listDoors`/`getHost`/`getProperties`) live at
  * `design.query.*`. Door targets are {@linkcode ComponentHandle}s.
  *
- * `getSwingDirection` is a DERIVED read (no persisted field) — computed from the placed
- * mesh's orientation: stand on the side the door swings open to, facing it; `'left'`
- * when the hinged jamb is on your left. `mirror` reflects the door about one of its own
- * axes (undoable, one command): `'x'` flips the swing side, `'z'` swaps the hinged jamb;
- * `setType` is intentionally absent (the engine has no in-place re-type —
+ * `getSwingDirection` is a DERIVED read (no persisted field) — computed from the door
+ * mesh reflection state. `mirror` reflects the door across an axis (undoable, one
+ * command); `setType` is intentionally absent (the engine has no in-place re-type —
  * it would require delete+recreate).
  *
  * The **catalog** reads (`listCatalogGroups`/`listCatalog`/`getCatalogItem`/`exists`)
@@ -156,11 +154,9 @@ export abstract class PluginDesignDoorsApi {
   public abstract getSupportFloor(door: ComponentHandle): PluginApiReturn<ComponentHandle | null>
 
   /**
-   * Get a door's swing (hinge) handedness. Stand on the side the door swings
-   * open to, facing the door: `'left'` when the hinged jamb is on your left,
-   * `'right'` when it is on your right. Derived from the placed mesh's
-   * orientation (the same reflection `mirror` and the `hinge` placement option
-   * apply), not a persisted field.
+   * Get a door's swing (hinge) handedness — whether it opens as a left-hand or
+   * right-hand door. Derived from the door mesh's reflection state, not a
+   * persisted field.
    *
    * @param door The door to query
    * @returns `'left'` / `'right'`, or `null` if indeterminate
@@ -182,13 +178,11 @@ export abstract class PluginDesignDoorsApi {
   ): PluginApiReturn<"left" | "right" | null>
 
   /**
-   * Mirror a door about its own axes. `'x'` (default) flips the swing side —
-   * the door opens to the other side of the wall; `'z'` swaps the hinged jamb
-   * (left-hand ↔ right-hand, same swing side); `'y'` turns it upside down.
-   * Undoable as a single command.
+   * Mirror a door across an axis, flipping its swing so it opens from the
+   * other side. Undoable as a single command.
    *
    * @param door The door to mirror
-   * @param axis Reflection axis (optional; default `'x'` — the swing-flip axis; `'z'` — the hinge-jamb axis)
+   * @param axis Reflection axis (optional; default `'x'` — the swing-flip axis)
    * @returns The affected door(s)
    *
    * @examplePrompt Flip this door's swing
@@ -199,11 +193,10 @@ export abstract class PluginDesignDoorsApi {
    *
    * # Example
    * ```ts
-   * // Flip the selected door's swing side — axis defaults to "x"
+   * // Flip the selected door's swing — axis defaults to "x" (the swing-flip
+   * // axis); pass "y" or "z" to reflect across a different axis
    * const [door] = await snaptrude.design.query.listDoors({ isSelected: true })
    * const { affected } = await snaptrude.design.doors.mirror(door)
-   * // …or swap the hinged jamb instead (keeps the swing side)
-   * await snaptrude.design.doors.mirror(door, "z")
    * ```
    */
   public abstract mirror(
@@ -376,7 +369,7 @@ export const PluginDoorDimensions = z.object({
 })
 export type PluginDoorDimensions = z.infer<typeof PluginDoorDimensions>
 
-/** Mirror axis — tokens mirror the engine `FlipDirection` verbatim: `'x'` flips the swing side, `'z'` swaps the hinged jamb, `'y'` turns the door upside down. */
+/** Mirror axis — tokens mirror the engine `FlipDirection` verbatim (§6.1). */
 export const PluginMirrorAxis = z.enum(["x", "y", "z"])
 export type PluginMirrorAxis = z.infer<typeof PluginMirrorAxis>
 
@@ -386,7 +379,7 @@ export type PluginMirrorAxis = z.infer<typeof PluginMirrorAxis>
  * | Property | Type | Description |
  * |---|---|---|
  * | `door` | {@linkcode ComponentHandle} | The door to mirror |
- * | `axis` | {@linkcode PluginMirrorAxis} | Reflection axis (optional; default `'x'` — the swing-flip axis; `'z'` — the hinge-jamb axis) |
+ * | `axis` | {@linkcode PluginMirrorAxis} | Reflection axis (optional; default `'x'` — the swing-flip axis) |
  */
 export const PluginDesignDoorMirrorArgs = z.object({
   door: ComponentHandle,