@snaptrude/plugin-core 0.9.2 → 0.9.4

package/package.json

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

package/src/api/core/geom/create/index.ts

@@ -264,28 +264,52 @@ export abstract class PluginGeomCreateApi {
   /**
    * Create a closed solid **B-rep** by lofting between a bottom and a top
    * contour, optionally through intermediate cross-sections. Host API call —
-   * returns a {@linkcode BrepHandle}. All sections must have the same number
-   * of edges; side faces connect corresponding edges by authored index.
-   * Corresponding edges must stay coplanar segment to segment (matching hole
-   * counts allowed in the two-section form) — a twisted loft would produce
-   * non-planar side faces and is rejected. With intermediates the loft is a
-   * chain of ruled segments folded into one solid: sections must be planar
-   * and hole-free, ordered bottom → intermediates → top. The contours are
-   * copied — the input handles are never mutated.
+   * returns a {@linkcode BrepHandle}. Sections with different edge counts are
+   * auto-matched: vertices are deterministically inserted on the smaller
+   * sections at the larger section's perimeter positions, so the same input
+   * always yields the same solid. For straight-edge (all-line) sections the
+   * seam is auto-aligned too — winding and start-vertex correspondence are
+   * chosen to avoid a twist, so outlines authored from any starting corner
+   * loft cleanly; arc-bearing sections keep the authored correspondence
+   * unchanged. A pair whose side faces would be non-planar under every
+   * correspondence still builds for hole-free straight-edged pairs — planar
+   * side quads stay quads and warped ones split into planar triangles (the
+   * triangulated lane); arc-bearing or holed twisted pairs are rejected, as is
+   * auto-matching that would pair an arc with a straight edge. Matching hole
+   * counts are allowed in the two-section form. With intermediates the loft
+   * is a chain of ruled segments folded into one solid: sections must be
+   * planar and hole-free, ordered bottom → intermediates → top. The contours
+   * are copied — the input handles are never mutated.
    *
    * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
    * with `design.create.massFromBrep`.
    *
    * @param bottomContour The bottom cross-section
-   * @param topContour The top cross-section (same edge count as the bottom)
+   * @param topContour The top cross-section (edge count may differ from the
+   *   bottom — sections are auto-matched)
    * @param intermediateContours Optional in-between cross-sections, ordered
-   *   bottom to top (hole-free, same edge count as the bottom and top)
+   *   bottom to top (hole-free; edge counts may differ — every section is
+   *   normalized to the largest)
+   * @param options Optional behavior switches. `compatibility` — `"auto"`
+   *   (default) inserts vertices to match differing edge counts; `"strict"`
+   *   skips normalization and throws VALIDATION when outer edge counts (or,
+   *   in the two-section form, hole-pair counts) differ. `seamAlignment` —
+   *   `"auto"` (default) searches seam rotations on straight-edge sections to
+   *   avoid a twist; `"authored"` keeps the authored start-vertex
+   *   correspondence unchanged (a twisted correspondence then builds through
+   *   the triangulated lane for hole-free straight-edged pairs).
+   *   `{ compatibility: "strict", seamAlignment: "authored" }` reproduces
+   *   pre-0.9.4 lofting exactly.
    * @returns The new solid as a {@linkcode BrepHandle}
-   * @throws VALIDATION if the contours are coincident, their edge or hole
-   *   counts differ, any section has holes when intermediates are present
+   * @throws VALIDATION if the contours are coincident, their hole counts
+   *   differ, any section has holes when intermediates are present
    *   (multi-section lofts take hole-free sections), a section is non-planar,
-   *   or a side face between corresponding edges would be non-planar (a
-   *   twisted section pair — the error names the offending sections)
+   *   sections are too dissimilar to auto-match, auto-matching would pair an
+   *   arc with a straight edge, or — for arc-bearing or holed pairs only — no vertex correspondence avoids a twist (a
+   *   side face between corresponding edges would be non-planar — the error
+   *   names the offending sections); with `compatibility: "strict"`, if
+   *   section edge counts (or hole-pair counts) differ — the error names the
+   *   sections and counts and points at `compatibility: "auto"`
    * @throws OPERATION_FAILED if the lofted segments cannot be joined into a
    *   valid solid
    *
@@ -293,6 +317,10 @@ export abstract class PluginGeomCreateApi {
    * @examplePrompt Loft between a large base and a smaller top
    * @examplePrompt Create a frustum from two squares
    * @examplePrompt Loft the tower through these three floor outlines
+   * @examplePrompt Loft a four-sided base to a five-sided top
+   * @examplePrompt Loft these outlines even though their corners don't line up
+   * @examplePrompt Loft these outlines exactly as authored, corner to corner
+   * @examplePrompt Fail the loft if my sections don't have matching edge counts
    *
    * # Example
    * ```ts
@@ -310,6 +338,7 @@ export abstract class PluginGeomCreateApi {
     bottomContour: ContourHandle,
     topContour: ContourHandle,
     intermediateContours?: ContourHandle[],
+    options?: { compatibility?: "strict" | "auto"; seamAlignment?: "authored" | "auto" },
   ): PluginApiReturn<BrepHandle>
 
   /**
@@ -636,24 +665,59 @@ export abstract class PluginGeomCreateApi {
   ): PluginApiReturn<BrepHandle>
 
   /**
-   * Sweeps a planar profile along an open polyline path, with mitred corners
-   * at each bend. Host API call — returns a new {@linkcode BrepHandle}; the
+   * Sweeps a planar profile along a polyline path, with mitred corners at
+   * each bend. Host API call — returns a new {@linkcode BrepHandle}; the
    * input contour is read-only. The profile must be hole-free and must not
-   * lie in a plane containing the first path segment's direction.
-   *
-   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of
-   * tens of MB — expect a pause of seconds).
+   * lie in a plane containing the first path segment's direction. Repeating
+   * the first point as the last closes the path into a ring solid (a picture
+   * frame): closed paths must be flat and straight-segmented and take a
+   * straight-edged (arc-free) profile — the ring's cross-section is the
+   * authored profile projected along the first leg onto the first mitre
+   * plane, so a profile not perpendicular to the first leg appears sheared.
+   * An optional scale law tapers the sweep: `startScale`/`endScale`
+   * interpolate linearly by arc length, or `scales` gives one factor per path
+   * point (scaling is about the profile centroid). A uniform scale (all
+   * factors equal) works on any path today's sweep accepts; a varying scale
+   * takes straight (collinear) open paths with straight-edged profiles —
+   * tapering across a bend or along an arc edge would create faces Snaptrude
+   * cannot represent and throws (sweep each straight run separately and union
+   * the results instead). An optional `transition` picks the corner
+   * treatment: `"miter"` (default) is today's sharp mitred bend;
+   * `{ bevel: b }` chamfers each turning corner by cutting `b` back along
+   * both adjacent legs (works on open and closed paths — each leg must be
+   * long enough for its cuts). On a corner-less path `transition` has no effect, and the
+   * varying-scale lane takes straight paths, so it never sees a corner.
+   *
+   * Open paths run on the OpenCascade kernel (the first kernel call loads a
+   * wasm of tens of MB — expect a pause of seconds); closed paths are
+   * computed host-side and never load the kernel.
    *
    * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
    * with `design.create.massFromBrep`.
    *
    * @param profile The cross-section to sweep (hole-free contour)
-   * @param path The polyline path as plain `{x, y, z}` points (≥2, open — first ≠ last)
+   * @param path The polyline path as plain `{x, y, z}` points (≥2; repeat the
+   *   first point as the last to close the path into a ring)
+   * @param options Optional scale law and corner transition. Scale law:
+   *   `startScale`/`endScale` (linear taper by arc length) or `scales` (one
+   *   factor per path point; mutually exclusive with
+   *   `startScale`/`endScale`); every factor must be finite and within
+   *   1e-3..1e3. `transition`: `"miter"` (default, sharp corners) or
+   *   `{ bevel: b }` (chamfered corners, `b` finite within 1e-3..1e3; open
+   *   and closed paths)
    * @returns The swept solid as a new {@linkcode BrepHandle}
    * @throws VALIDATION if the profile has holes, the path has fewer than 2
-   *   points, consecutive path points coincide, the path is closed (open
-   *   paths only in v1), a coordinate is not finite, or the profile plane
-   *   contains the first path segment's direction (degenerate sweep)
+   *   points, consecutive path points coincide, a coordinate is not finite,
+   *   or the profile plane contains the first path segment's direction
+   *   (degenerate sweep); for closed paths, if the ring has fewer than 3
+   *   distinct corners, the path is non-planar, a corner doubles back, the
+   *   profile has an arc edge, or the profile is too large for a mitred
+   *   corner; for scale options, if a factor is outside 1e-3..1e3, `scales`
+   *   is combined with `startScale`/`endScale`, `scales` does not match the
+   *   path length, or a varying scale is used on a bent or closed path or
+   *   with an arc-edged profile; for `{ bevel }`, if a leg is too short for
+   *   the cuts its beveled corners take from it or a corner nearly doubles
+   *   back so its chamfer collapses (the errors name the corner)
    * @throws OPERATION_FAILED if the kernel cannot sweep the profile into a
    *   valid solid or a transition patch is a curved surface Snaptrude cannot
    *   represent
@@ -661,6 +725,10 @@ export abstract class PluginGeomCreateApi {
    * @examplePrompt Sweep this profile along the corridor path
    * @examplePrompt Extrude the railing section along this route
    * @examplePrompt Run a duct profile through these points
+   * @examplePrompt Sweep a frame profile around a closed rectangular loop
+   * @examplePrompt Taper this duct from 1x1 to 2x2 along its run
+   * @examplePrompt Sweep a column section that narrows toward the top
+   * @examplePrompt Chamfer the corners of this swept frame by 200mm
    *
    * # Example
    * ```ts
@@ -673,11 +741,34 @@ export abstract class PluginGeomCreateApi {
    *   { x: 0, y: 2.8, z: 0 },
    *   { x: 10, y: 2.8, z: 0 },
    * ])
+   * // A closed ring (picture frame): repeat the first point as the last
+   * const frame = await snaptrude.core.geom.create.brepFromSweep(profile, [
+   *   { x: 0, y: 0, z: 0 },
+   *   { x: 0, y: 3, z: 0 },
+   *   { x: 4, y: 3, z: 0 },
+   *   { x: 4, y: 0, z: 0 },
+   *   { x: 0, y: 0, z: 0 },
+   * ])
+   * // A tapered straight run: 0.4x0.4 at the start, 0.8x0.8 at the end
+   * const flue = await snaptrude.core.geom.create.brepFromSweep(
+   *   profile,
+   *   [
+   *     { x: 0, y: 0, z: 0 },
+   *     { x: 0, y: 10, z: 0 },
+   *   ],
+   *   { startScale: 1, endScale: 2 },
+   * )
    * ```
    */
   public abstract brepFromSweep(
     profile: ContourHandle,
     path: Vec3Components[],
+    options?: {
+      startScale?: number
+      endScale?: number
+      scales?: number[]
+      transition?: "miter" | { bevel: number }
+    },
   ): PluginApiReturn<BrepHandle>
 
   /**
@@ -897,11 +988,18 @@ export type PluginGeomCreateBrepFromExtrusionArgs = z.infer<
  * | `bottomContour` | {@linkcode ContourHandle} | The bottom cross-section |
  * | `topContour` | {@linkcode ContourHandle} | The top cross-section |
  * | `intermediateContours` | {@linkcode ContourHandle}`[]`? | Optional in-between cross-sections, ordered bottom to top |
+ * | `options` | `object`? | Optional behavior switches: `compatibility` (`"strict"` throws on mismatched edge counts instead of auto-matching; default `"auto"`) and `seamAlignment` (`"authored"` keeps the authored correspondence instead of searching seam rotations; default `"auto"`) |
  */
 export const PluginGeomCreateBrepFromLoftArgs = z.object({
   bottomContour: ContourHandle,
   topContour: ContourHandle,
   intermediateContours: z.array(ContourHandle).optional(),
+  options: z
+    .object({
+      compatibility: z.enum(["strict", "auto"]).optional(),
+      seamAlignment: z.enum(["authored", "auto"]).optional(),
+    })
+    .optional(),
 })
 
 export type PluginGeomCreateBrepFromLoftArgs = z.infer<typeof PluginGeomCreateBrepFromLoftArgs>
@@ -1034,18 +1132,53 @@ export type PluginGeomCreateBrepFromChamferArgs = z.infer<
   typeof PluginGeomCreateBrepFromChamferArgs
 >
 
+// Taper scale factor — bounded so a near-zero scale cannot pinch a section
+// into a degenerate sliver the downstream planarity gates would miss.
+const SweepScaleFactor = z.number().finite().min(1e-3).max(1e3)
+
 /**
  * Arguments for {@linkcode PluginGeomCreateApi.brepFromSweep}.
  *
  * | Property | Type | Description |
  * |---|---|---|
  * | `profile` | {@linkcode ContourHandle} | The cross-section to sweep (hole-free) |
- * | `path` | {@linkcode Vec3Components}`[]` | The open polyline path (≥2 points, finite components) |
+ * | `path` | {@linkcode Vec3Components}`[]` | The polyline path (≥2 points, finite components; repeating the first point as the last closes it into a ring — closed paths must be flat and straight-segmented and take a straight-edged profile) |
+ * | `options` | `object`? | Optional scale law: `startScale`/`endScale` (linear taper by arc length) or per-point `scales` (mutually exclusive; factors finite, 1e-3..1e3; `scales.length` must equal `path.length`). Optional corner `transition`: `"miter"` (default) or `{ bevel }` (chamfered corners; finite, 1e-3..1e3) |
  */
-export const PluginGeomCreateBrepFromSweepArgs = z.object({
-  profile: ContourHandle,
-  path: z.array(FiniteVec3Components).min(2),
-})
+export const PluginGeomCreateBrepFromSweepArgs = z
+  .object({
+    profile: ContourHandle,
+    path: z.array(FiniteVec3Components).min(2),
+    options: z
+      .object({
+        startScale: SweepScaleFactor.optional(),
+        endScale: SweepScaleFactor.optional(),
+        scales: z.array(SweepScaleFactor).optional(),
+        transition: z
+          .union([
+            z.literal("miter"),
+            z.object({ bevel: z.number().finite().min(1e-3).max(1e3) }),
+          ])
+          .optional(),
+      })
+      .optional(),
+  })
+  .superRefine((a, ctx) => {
+    const options = a.options
+    if (!options || options.scales === undefined) return
+    if (options.startScale !== undefined || options.endScale !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "scales is mutually exclusive with startScale/endScale",
+      })
+    }
+    if (options.scales.length !== a.path.length) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "scales must have exactly one entry per path point",
+      })
+    }
+  })
 
 export type PluginGeomCreateBrepFromSweepArgs = z.infer<typeof PluginGeomCreateBrepFromSweepArgs>
 

package/src/api/core/geom/query/brep.ts

@@ -163,6 +163,64 @@ export abstract class PluginGeomQueryBrepApi {
     vertexIndexB: number
   ): PluginApiReturn<EdgeHandle[]>
 
+  /**
+   * Read the exact curve of a brep edge as plain values — a discriminated
+   * union on `type`. Pure read: no geometry kernel is loaded. Points and
+   * directions are {@linkcode Vec3Components}; lengths and radii are raw
+   * Babylon units.
+   *
+   * | `type` | Fields |
+   * |---|---|
+   * | `"line"` | `startPoint`, `endPoint`, `length` |
+   * | `"arc"` | `startPoint`, `endPoint`, `centre`, `axis`, `radius`, `length` |
+   * | `"circle"` | `centre`, `axis`, `radius`, `length` — a full-circle edge (e.g. a cylinder cap rim) |
+   *
+   * @param brep The brep the edge belongs to
+   * @param edge The edge whose curve to read
+   * @returns The curve data as a discriminated union on `type` (see table above)
+   * @throws VALIDATION if the edge is not on `brep`
+   *
+   * @examplePrompt Read the radius of this curved edge
+   * @examplePrompt Is this edge straight or an arc?
+   * @examplePrompt Get the exact start and end points of this edge
+   * @examplePrompt Measure the length of each edge of this mass
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const brep = await snaptrude.design.query.geometry.getBrep(mass)
+   * if (brep) {
+   *   const edges = await snaptrude.core.geom.query.brep.listEdges(brep)
+   *   for (const edge of edges) {
+   *     const curve = await snaptrude.core.geom.query.brep.getEdgeCurve(brep, edge)
+   *     if (curve.type === "arc") console.log("arc radius:", curve.radius)
+   *   }
+   * }
+   * ```
+   */
+  public abstract getEdgeCurve(
+    brep: BrepHandle,
+    edge: EdgeHandle
+  ): PluginApiReturn<
+    | { type: "line"; startPoint: Vec3Components; endPoint: Vec3Components; length: number }
+    | {
+        type: "arc"
+        startPoint: Vec3Components
+        endPoint: Vec3Components
+        centre: Vec3Components
+        axis: Vec3Components
+        radius: number
+        length: number
+      }
+    | {
+        type: "circle"
+        centre: Vec3Components
+        axis: Vec3Components
+        radius: number
+        length: number
+      }
+  >
+
   /**
    * Get the position of a vertex within a brep.
    * @param brep The brep to query
@@ -408,6 +466,22 @@ export type PluginGeomQueryBrepListEdgesBetweenArgs = z.infer<
   typeof PluginGeomQueryBrepListEdgesBetweenArgs
 >
 
+/**
+ * Arguments for {@linkcode PluginGeomQueryBrepApi.getEdgeCurve}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `brep` | {@linkcode BrepHandle} | The brep the edge belongs to |
+ * | `edge` | {@linkcode EdgeHandle} | The edge whose curve to read |
+ */
+export const PluginGeomQueryBrepGetEdgeCurveArgs = z.object({
+  brep: BrepHandle,
+  edge: EdgeHandle,
+})
+export type PluginGeomQueryBrepGetEdgeCurveArgs = z.infer<
+  typeof PluginGeomQueryBrepGetEdgeCurveArgs
+>
+
 /**
  * Arguments for {@linkcode PluginGeomQueryBrepApi.getVertexPosition}.
  *

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

@@ -389,9 +389,15 @@ export abstract class PluginDesignCreateApi {
    *   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 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
+   *   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 a {@linkcode ComponentHandle}`[]` (one per wall), in profile order
    * @throws if the profile is empty, `wallType` names no wall type in the
-   *   project, or wall creation fails
+   *   project, `storey` does not exist, or wall creation fails
    *
    * @examplePrompt Draw walls along this centerline
    * @examplePrompt Create 3m high, 200mm thick walls from these points
@@ -422,6 +428,7 @@ export abstract class PluginDesignCreateApi {
     height?: number,
     thickness?: number,
     wallType?: string,
+    storey?: number,
   ): PluginApiReturn<ComponentHandle[]>
 
   /**
@@ -429,12 +436,17 @@ export abstract class PluginDesignCreateApi {
    *
    * Geometry is procedurally generated from the chosen `preset`; there is no
    * footprint input. Placed on the active structure/story unless overridden.
+   * The promise resolves only after the staircase's asynchronous geometry union
+   * and creation-command capture settle; a union failure rejects the call.
    *
    * @param preset - The parametric preset to generate
    * @param position - Placement point
    * @param label - Optional label
    * @param structureId - Target structure (default active)
    * @param level - Target level name (default active/`"01"`)
+   * @param dimensions - Optional positive dimension overrides in Snaptrude engine
+   *   units, plus a placement angle in 90-degree increments. Overrides are
+   *   applied to the staircase parameters before the creation command runs.
    * @returns the {@linkcode ComponentHandle} of the created staircase
    * @throws if the preset is unknown or placement fails
    *
@@ -458,6 +470,7 @@ export abstract class PluginDesignCreateApi {
     label?: string,
     structureId?: string,
     level?: string,
+    dimensions?: PluginStaircaseDimensions,
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -517,7 +530,11 @@ export abstract class PluginDesignCreateApi {
    * entry). To rotate an existing instance instead, use `design.transform.rotate`.
    *
    * @param catalogId - Library id: team `_id` or general `fullName`
-   * @param position - Absolute world placement point
+   * @param position - Absolute world placement point. `position.y` is the REST
+   *   elevation: the item is grounded so its bounding-box base sits exactly at
+   *   `position.y` (the same surface-flush contract as interactive drag-drop) —
+   *   pass the floor/storey elevation to stand furniture on it; never add half
+   *   the item's height yourself.
    * @param options - Optional placement options: `label` — instance name
    *   (default auto `${name}Ins${n}`); `createNewSourceMesh` — emit a
    *   source-mesh creation command (default `true`)
@@ -665,6 +682,43 @@ export abstract class PluginDesignCreateApi {
     facing?: Vec3Handle,
   ): PluginApiReturn<ComponentHandle>
 
+  /**
+   * Place a catalog **door or window** into a host wall with optional size 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
+   *   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
+   *
+   * @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.
+   *
+   * # Example
+   * ```ts
+   * const opening = await snaptrude.design.create.opening({
+   *   kind: "window",
+   *   catalogId: windowType.id,
+   *   hostWall: wall,
+   *   position: await snaptrude.core.math.vec3.new(3, 0, 5),
+   *   width: 1.2,
+   *   height: 1.5,
+   *   sillHeight: 0.9,
+   * })
+   * ```
+   */
+  public abstract opening(
+    options: PluginDesignCreateOpeningOptions,
+  ): PluginApiReturn<ComponentHandle>
+
   /**
    * Place a **smart layout** — clone an in-scene template cluster (walls,
    * furniture, doors, windows, floors) into one or more target ROOM/DEPARTMENT
@@ -908,6 +962,24 @@ export const PluginStaircasePreset = z.enum([
 ])
 export type PluginStaircasePreset = z.infer<typeof PluginStaircasePreset>
 
+/**
+ * Optional staircase dimension overrides. Lengths use Snaptrude engine units
+ * and must be positive. `angleInDegrees` controls placement about the vertical
+ * axis and must be a multiple of 90 degrees.
+ */
+export const PluginStaircaseDimensions = z
+  .object({
+    width: z.number().finite().positive().optional(),
+    tread: z.number().finite().positive().optional(),
+    riser: z.number().finite().positive().optional(),
+    landingWidth: z.number().finite().positive().optional(),
+    angleInDegrees: z.number().finite().multipleOf(90).optional(),
+  })
+  .strict()
+export type PluginStaircaseDimensions = z.infer<
+  typeof PluginStaircaseDimensions
+>
+
 // ---------------------------------------------------------------------------
 // space
 // ---------------------------------------------------------------------------
@@ -1135,18 +1207,20 @@ export type PluginDesignCreateBeamArgs = z.infer<
  * | `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) |
+ * | `storey` | `number`? | Target storey (integer, must exist) — walls assigned + lifted to its base in the same undo entry (default: geometry-derived) |
  */
 export const PluginDesignCreateWallsArgs = z.object({
   profile: ProfileHandle,
   height: z.number().optional(),
   thickness: z.number().optional(),
   wallType: z.string().min(1).optional(),
+  storey: z.number().int().optional(),
 })
 export type PluginDesignCreateWallsArgs = z.infer<
   typeof PluginDesignCreateWallsArgs
 >
-// TRANSPORT: positional signature shipped — wallType is the trailing 4th arg:
-//   walls(profile: ProfileHandle, height?: number, thickness?: number, wallType?: string)
+// TRANSPORT: positional signature shipped — storey is the trailing 5th arg:
+//   walls(profile: ProfileHandle, height?: number, thickness?: number, wallType?: string, storey?: number)
 
 // ---------------------------------------------------------------------------
 // staircase
@@ -1162,6 +1236,7 @@ export type PluginDesignCreateWallsArgs = z.infer<
  * | `label` | `string`? | Optional label |
  * | `structureId` | `string`? | Target structure (default active) |
  * | `level` | `string`? | Target level name (default active/`"01"`) |
+ * | `dimensions` | {@linkcode PluginStaircaseDimensions}? | Positive dimension overrides in engine units, applied before creation |
  */
 export const PluginDesignCreateStaircaseArgs = z.object({
   preset: PluginStaircasePreset,
@@ -1169,6 +1244,7 @@ export const PluginDesignCreateStaircaseArgs = z.object({
   label: z.string().optional(),
   structureId: z.string().optional(),
   level: z.string().optional(),
+  dimensions: PluginStaircaseDimensions.optional(),
 })
 export type PluginDesignCreateStaircaseArgs = z.infer<
   typeof PluginDesignCreateStaircaseArgs
@@ -1258,6 +1334,45 @@ export type PluginDesignCreateWindowArgs = z.infer<
 // 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.
+ * `sillHeight` is available only for windows, is nonnegative, and is precisely
+ * the distance from the host wall base to the bottom of the window.
+ */
+export const PluginDesignCreateOpeningOptions = z.discriminatedUnion("kind", [
+  z
+    .object({
+      kind: z.literal("door"),
+      ...PluginOpeningBaseOptions,
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("window"),
+      ...PluginOpeningBaseOptions,
+      sillHeight: z.number().finite().nonnegative().optional(),
+    })
+    .strict(),
+])
+export type PluginDesignCreateOpeningOptions = z.infer<
+  typeof PluginDesignCreateOpeningOptions
+>
+
 // ---------------------------------------------------------------------------
 // smartLayout
 // ---------------------------------------------------------------------------

package/src/api/program/index.ts

@@ -23,7 +23,7 @@ import { PluginProgramAreasApi } from "./areas"
  * - {@linkcode PluginProgramApi.metrics} — Read the area-program summary
  * - {@linkcode PluginProgramApi.areas} — FAR / built-up-area rollup and groupings
  * - {@linkcode PluginProgramApi.spreadsheet} — Render program data to sheets and read it back
- * - {@linkcode PluginProgramApi.site} — Read the site/plot planning context
+ * - {@linkcode PluginProgramApi.site} — Read site/plot context and read/update Site Analysis
  * - {@linkcode PluginProgramApi.cores} — Read & predicate vertical-circulation cores (reads only)
  * - {@linkcode PluginProgramApi.classification} — Classification catalog + display tags
  *
@@ -42,7 +42,7 @@ export abstract class PluginProgramApi {
   public abstract areas: PluginProgramAreasApi
   /** Spreadsheet reports — render tables to sheets, export, list, read back. See {@linkcode PluginProgramSpreadsheetApi}. */
   public abstract spreadsheet: PluginProgramSpreadsheetApi
-  /** Site/plot planning context — total area, parcel footprints, geo rings. See {@linkcode PluginProgramSiteApi}. */
+  /** Site/plot context and persisted Site Analysis. See {@linkcode PluginProgramSiteApi}. */
   public abstract site: PluginProgramSiteApi
   /** Vertical-circulation cores — read & predicate (reads only). See {@linkcode PluginProgramCoresApi}. */
   public abstract cores: PluginProgramCoresApi