@snaptrude/plugin-core 1.0.2-plainpoint-20261102.2 → 1.0.3

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

@@ -8,7 +8,6 @@ import {
   CurveHandle,
   ProfileHandle,
   Vec3Handle,
-  Vec3Input,
 } from "../../../handles"
 import { PluginGridStyleOptions } from "./grids"
 import { PluginGraphicsLineStyleId } from "../../presentation/graphics"
@@ -131,7 +130,7 @@ export abstract class PluginDesignCreateApi {
     contour: ContourHandle,
     height: number,
     label?: string,
-    position?: Vec3Input,
+    position?: Vec3Handle,
     spaceType?: PluginSpaceType,
     massType?: PluginMassType,
     departmentId?: PluginDepartmentId,
@@ -166,7 +165,7 @@ export abstract class PluginDesignCreateApi {
     contour: ContourHandle,
     height: number,
     label?: string,
-    position?: Vec3Input,
+    position?: Vec3Handle,
     massType?: PluginMassType,
   ): PluginApiReturn<ComponentHandle>
 
@@ -289,7 +288,7 @@ export abstract class PluginDesignCreateApi {
    */
   public abstract floor(
     ...args:
-      | [contour: ContourHandle, thickness: number, position?: Vec3Input]
+      | [contour: ContourHandle, thickness: number, position?: Vec3Handle]
       | [contour: ContourHandle, options: PluginFamilyFloorOptions]
   ): PluginApiReturn<ComponentHandle[]>
 
@@ -423,10 +422,10 @@ export abstract class PluginDesignCreateApi {
   public abstract column(
     ...args:
       | [
-          position: Vec3Input,
+          position: Vec3Handle,
           crossSection: ContourHandle,
           height: number,
-          directionUp?: Vec3Input,
+          directionUp?: Vec3Handle,
         ]
       | [axis: LineHandle, options: PluginFamilyPlacement]
   ): PluginApiReturn<ComponentHandle>
@@ -473,7 +472,7 @@ export abstract class PluginDesignCreateApi {
    */
   public abstract beam(
     ...args:
-      | [section: ContourHandle, length: number, direction?: Vec3Input]
+      | [section: ContourHandle, length: number, direction?: Vec3Handle]
       | [axis: LineHandle, options: PluginFamilyPlacement]
   ): PluginApiReturn<ComponentHandle>
 
@@ -497,10 +496,10 @@ export abstract class PluginDesignCreateApi {
    *   single undo entry. The storey must already exist
    *   (`core.storeys.create` first). Default: geometry-derived — a profile
    *   drawn at y = 0 lands on storey 1; the ACTIVE storey is NOT consulted.
-   * @param topProfiles - Top edge per curve of `profile` (same order). Current
-   *   hosts build walls with one height: any non-null entry is refused with
-   *   `PRECONDITION_FAILED` ("sloped or stepped tops are not supported") and
-   *   nothing is created. Pass `null` entries or omit it.
+   * @param topProfiles - Optional top edge per curve of `profile` (same order):
+   *   a {@linkcode PluginWallTopProfile} makes that wall raked / gabled; `null`
+   *   or a missing entry keeps it flat at `height`. Straight curves only. Such
+   *   walls are non-parametric (see {@linkcode PluginWallTopProfile}).
    * @returns a {@linkcode ComponentHandle}`[]` (one per wall), in profile order
    * @throws if the profile is empty, `wallType` names no wall type in the
    *   project, `storey` does not exist, `topProfiles` has more entries than the
@@ -514,6 +513,9 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Add walls with mitred corners along the path
    * @examplePrompt Draw brick walls with plaster along this outline
    * @examplePrompt Build the perimeter in exposed concrete walls
+   * @examplePrompt Create a raked wall that slopes from 3m to 5m
+   * @examplePrompt Build a gable end wall with the ridge in the middle
+   * @examplePrompt Draw a wall with a sloped top edge
    *
    * # Example
    * ```ts
@@ -529,6 +531,13 @@ export abstract class PluginDesignCreateApi {
    * const brickWalls = await snaptrude.design.create.walls(
    *   centerlines, 3, undefined, brick.label,
    * )
+   * // …a raked wall (3m at the start, 5m at the end) on a single centerline:
+   * const run = await snaptrude.core.geom.create.profileFromCurves([
+   *   await snaptrude.core.geom.create.line(await v.new(0, 0, 10), await v.new(8, 0, 10)),
+   * ])
+   * const [raked] = await snaptrude.design.create.walls(run, undefined, 0.2, undefined, undefined, [
+   *   [{ along: 0, height: 3 }, { along: 1, height: 5 }],
+   * ])
    * ```
    *
    * @performance For MORE THAN ONE run, call `design.create.wallRuns(items[])` — one
@@ -551,9 +560,8 @@ export abstract class PluginDesignCreateApi {
    * 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. Walls have one height: a non-null
-   * `topProfiles` entry is refused with `PRECONDITION_FAILED` (`details.itemIndex`
-   * names the item) and nothing is created. Validate-all-or-throw;
+   * floor plate or several storeys at once. Per-curve `topProfiles` make raked
+   * or gabled walls (see {@linkcode PluginWallTopProfile}). Validate-all-or-throw;
    * one command.
    *
    * @param items - One {@linkcode PluginCreateWallRunItem} per run to create
@@ -574,6 +582,7 @@ export abstract class PluginDesignCreateApi {
    * @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
+   * @examplePrompt Import these raked walls with their top profiles in one go
    *
    * @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
@@ -594,6 +603,9 @@ export abstract class PluginDesignCreateApi {
    * const [groundWalls, upperWalls] = await snaptrude.design.create.wallRuns([
    *   { profile: ground, height: 3, thickness: 0.2 },
    *   { profile: upper, height: 3, storey: 2 },
+   *   // one gable wall: 3m at both ends, 5m ridge in the middle
+   *   { profile: upper, thickness: 0.2, storey: 3,
+   *     topProfiles: [[{ along: 0, height: 3 }, { along: 0.5, height: 5 }, { along: 1, height: 3 }]] },
    * ])
    * console.log(groundWalls.length, "walls on the ground floor")
    * ```
@@ -637,7 +649,7 @@ export abstract class PluginDesignCreateApi {
    */
   public abstract staircase(
     preset: PluginStaircasePreset,
-    position: Vec3Input,
+    position: Vec3Handle,
     label?: string,
     structureId?: string,
     level?: string,
@@ -728,7 +740,7 @@ export abstract class PluginDesignCreateApi {
     spacingY: number,
     options?: {
       angle?: number
-      center?: Vec3Input
+      center?: Vec3Handle
     } & PluginGridStyleOptions,
   ): PluginApiReturn<ComponentHandle>
 
@@ -883,7 +895,7 @@ export abstract class PluginDesignCreateApi {
    */
   public abstract furniture(
     catalogId: string,
-    position: Vec3Input,
+    position: Vec3Handle,
     options?: { label?: string; createNewSourceMesh?: boolean },
     angleInDegrees?: number,
   ): PluginApiReturn<ComponentHandle>
@@ -996,14 +1008,14 @@ export abstract class PluginDesignCreateApi {
   public abstract door(
     familyId: string,
     hostWall: ComponentHandle,
-    position: Vec3Input,
+    position: Vec3Handle,
     options?: {
       label?: string
-      hinge?: Vec3Input
+      hinge?: Vec3Handle
       version?: number
       values?: Record<string, number | string>
     },
-    facing?: Vec3Input,
+    facing?: Vec3Handle,
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -1035,6 +1047,12 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Put three doors on this wall in a single undo step
    * @examplePrompt Add all the doors for this floor plan together
    *
+   * A width/height (top-level, or under the family's own keys in `values`) on a family that
+   * takes its size from its Type while Custom Sizes is off is never dropped: the Type within
+   * 25 mm is chosen, else Custom Sizes is turned on and that size is built, leaving the Type
+   * label stale. `design.doors.checkPlacement` reports which as `sizing`; `customSizes: "No"`
+   * with a size no Type matches is refused.
+   *
    * @performance Bulk creator — the whole batch is ONE host round-trip and ONE undo
    *   entry. Always prefer this over
    *   calling `design.create.door` in a loop: build the full `items[]` array first
@@ -1100,14 +1118,14 @@ export abstract class PluginDesignCreateApi {
   public abstract window(
     familyId: string,
     hostWall: ComponentHandle,
-    position: Vec3Input,
+    position: Vec3Handle,
     options?: {
       label?: string
-      hinge?: Vec3Input
+      hinge?: Vec3Handle
       version?: number
       values?: Record<string, number | string>
     },
-    facing?: Vec3Input,
+    facing?: Vec3Handle,
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -1140,6 +1158,12 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Put four windows on this wall in a single undo step
    * @examplePrompt Add all the windows with a 0.9m sill height together
    *
+   * A width/height (top-level, or under the family's own keys in `values`) on a family that
+   * takes its size from its Type while Custom Sizes is off is never dropped: the Type within
+   * 25 mm is chosen, else Custom Sizes is turned on and that size is built, leaving the Type
+   * label stale. `design.windows.checkPlacement` reports which as `sizing`; `customSizes: "No"`
+   * with a size no Type matches is refused.
+   *
    * @performance Bulk creator — the whole batch is ONE host round-trip and ONE undo
    *   entry. Always prefer this over
    *   calling `design.create.window` in a loop: build the full `items[]` array first
@@ -1434,7 +1458,7 @@ export abstract class PluginDesignCreateApi {
    */
   public abstract copy(
     components: ComponentHandle[],
-    displacement: Vec3Input,
+    displacement: Vec3Handle,
     options?: { count?: number; mode?: PluginCopyMode },
   ): PluginApiReturn<ComponentHandle[]>
 
@@ -1657,7 +1681,7 @@ export const PluginDesignCreateSpaceArgs = z.object({
   contour: ContourHandle,
   height: z.number(),
   label: z.string().optional(),
-  position: Vec3Input.optional(),
+  position: Vec3Handle.optional(),
   spaceType: PluginSpaceType.optional(),
   massType: PluginMassType.optional(),
   departmentId: PluginDepartmentId.optional(),
@@ -1688,7 +1712,7 @@ export const PluginDesignCreateMassArgs = z.object({
   contour: ContourHandle,
   height: z.number(),
   label: z.string().optional(),
-  position: Vec3Input.optional(),
+  position: Vec3Handle.optional(),
   massType: PluginMassType.optional(),
 })
 export type PluginDesignCreateMassArgs = z.infer<
@@ -1755,7 +1779,7 @@ export type PluginDesignCreateSlabArgs = z.infer<
 export const PluginDesignCreateFloorArgs = z.object({
   contour: ContourHandle,
   thickness: z.number(),
-  position: Vec3Input.optional(),
+  position: Vec3Handle.optional(),
 })
 export type PluginDesignCreateFloorArgs = z.infer<
   typeof PluginDesignCreateFloorArgs
@@ -1818,10 +1842,10 @@ export type PluginDesignCreateCeilingArgs = z.infer<
  * | `directionUp` | {@linkcode Vec3Handle}? | Up axis (default world up) |
  */
 export const PluginDesignCreateColumnArgs = z.object({
-  position: Vec3Input,
+  position: Vec3Handle,
   crossSection: ContourHandle,
   height: z.number(),
-  directionUp: Vec3Input.optional(),
+  directionUp: Vec3Handle.optional(),
 })
 export type PluginDesignCreateColumnArgs = z.infer<
   typeof PluginDesignCreateColumnArgs
@@ -1843,7 +1867,7 @@ export type PluginDesignCreateColumnArgs = z.infer<
 export const PluginDesignCreateBeamArgs = z.object({
   section: ContourHandle,
   length: z.number(),
-  direction: Vec3Input.optional(),
+  direction: Vec3Handle.optional(),
 })
 export type PluginDesignCreateBeamArgs = z.infer<
   typeof PluginDesignCreateBeamArgs
@@ -1898,7 +1922,7 @@ export type PluginDesignCreateWallsArgs = z.infer<
  */
 export const PluginDesignCreateStaircaseArgs = z.object({
   preset: PluginStaircasePreset,
-  position: Vec3Input,
+  position: Vec3Handle,
   label: z.string().optional(),
   structureId: z.string().optional(),
   level: z.string().optional(),
@@ -1925,7 +1949,7 @@ export type PluginDesignCreateStaircaseArgs = z.infer<
  */
 export const PluginDesignCreateFurnitureArgs = z.object({
   catalogId: z.string().min(1),
-  position: Vec3Input,
+  position: Vec3Handle,
   label: z.string().optional(),
   createNewSourceMesh: z.boolean().optional(),
   angleInDegrees: z.number().optional(),
@@ -2183,7 +2207,7 @@ export type PluginCopyMode = z.infer<typeof PluginCopyMode>
  */
 export const PluginDesignCreateCopyArgs = z.object({
   components: z.array(ComponentHandle).min(1),
-  displacement: Vec3Input,
+  displacement: Vec3Handle,
   count: z.number().int().positive().optional(),
   mode: PluginCopyMode.optional(),
 })
@@ -2216,7 +2240,7 @@ export const PluginCreateSpaceItem = z.object({
   contour: ContourHandle,
   height: z.number(),
   label: z.string().optional(),
-  position: Vec3Input.optional(),
+  position: Vec3Handle.optional(),
   spaceType: PluginSpaceType.optional(),
   massType: PluginMassType.optional(),
   departmentId: PluginDepartmentId.optional(),

package/src/api/design/create/opening-fields.ts

@@ -1,5 +1,5 @@
 import * as z from "zod"
-import { ComponentHandle, Vec3Input } from "../../../handles"
+import { ComponentHandle, Vec3Handle } from "../../../handles"
 
 /**
  * The shared field bag every hosted opening (door / window) carries — used by
@@ -17,9 +17,9 @@ import { ComponentHandle, Vec3Input } from "../../../handles"
  * | `version` | `number`? | Exact family version; newest known by default |
  * | `values` | `Record<string, number \| string>`? | Authored instance parameters; numeric lengths use Snaptrude units |
  * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the opening |
- * | `position` | {@linkcode Vec3Input} | World point projected onto the wall (a vec3 handle or a plain `{ x, y, z }`) |
- * | `facing` | {@linkcode Vec3Input}? | World point on the side of the wall the opening swings open to (default engine-chosen) |
- * | `hinge` | {@linkcode Vec3Input}? | World point near the hinged jamb; requires the recipe's hand parameter |
+ * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
+ * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the opening swings open to (default engine-chosen) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the hinged jamb; requires the recipe's hand parameter |
  * | `label` | `string`? | Instance name (optional) |
  * | `width` | `number`? | Sets the declared width parameter, not the opening's evaluated envelope |
  * | `height` | `number`? | Sets the declared height parameter |
@@ -31,9 +31,9 @@ export const PluginOpeningBaseOptions = {
     .record(z.string(), z.union([z.number().finite(), z.string()]))
     .optional(),
   hostWall: ComponentHandle,
-  position: Vec3Input,
-  facing: Vec3Input.optional(),
-  hinge: Vec3Input.optional(),
+  position: Vec3Handle,
+  facing: Vec3Handle.optional(),
+  hinge: Vec3Handle.optional(),
   label: z.string().optional(),
   width: z.number().finite().positive().optional(),
   height: z.number().finite().positive().optional(),

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

@@ -8,7 +8,7 @@ import { PluginDesignChangeResult } from "../lock"
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `components` | {@linkcode ComponentHandle}`[]` | Entities to delete. Handles that no longer resolve are skipped and returned as `missing`; the call rejects only when none resolve. |
+ * | `components` | {@linkcode ComponentHandle}`[]` | Entities to delete. Unknown/forged handles reject the whole call (fail-fast). |
  *
  * `.min(1)` is deliberately stricter than the shipped `PluginDesignLockArgs`
  * (which allows an empty array) — an empty delete is a caller error, not a no-op.
@@ -43,19 +43,12 @@ export abstract class PluginDesignDeleteApi {
    * 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. A handle that no longer resolves (already
-   *   removed by an earlier edit — a door deleted with its wall, a wall replaced by an
-   *   opening's re-cut) is skipped, not fatal.
-   * @returns `{ affected, cascaded?, missing?, rejected? }`: the entities you asked to delete
-   *   (echoed host-side — the engine returns no ids); `cascaded`, the derived walls/floors/slabs
-   *   the parametric graph removed with a deleted space; `missing`, handles that no longer
-   *   resolved and were skipped; `rejected`, handles the engine accepted but left standing
-   *   (delete them again, one at a time, or report them). Deleted handles are **stale**
-   *   afterwards: re-resolving one throws `HANDLE_STALE`.
-   * @throws `HANDLE_INVALID` when NONE of the supplied handles resolve (nothing is deleted);
-   *   hosts before Oct 2026 reject the whole call when any handle is gone. `OPERATION_FAILED`
-   *   when the parametric engine rejects the deletion — the batch is rolled back.
-   *   `HANDLE_STALE` for a handle the caller held that has since been retired.
+   * @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).
+   *   Deleted handles are **stale** afterwards: re-resolving one throws `HANDLE_INVALID`.
+   * @throws If any supplied handle is unknown/forged (`HANDLE_INVALID`) — the whole
+   *   call rejects before anything is deleted (all-or-nothing resolution).
    *
    * @examplePrompt Delete the selected objects
    * @examplePrompt Remove these walls from the model

package/src/api/design/dimensions.ts

@@ -5,7 +5,6 @@ import {
   DimensionHandle,
   Vec3Components,
   Vec3Handle,
-  Vec3Input,
 } from "../../handles"
 
 /**
@@ -95,8 +94,8 @@ export abstract class PluginDesignDimensionsApi {
    * ```
    */
   public abstract create(
-    from: Vec3Input,
-    to: Vec3Input,
+    from: Vec3Handle,
+    to: Vec3Handle,
     anchor: ComponentHandle,
     options?: { anchorTo?: ComponentHandle; offset?: number },
   ): PluginApiReturn<DimensionHandle>
@@ -363,8 +362,8 @@ export type PluginDimensionsChangeResult = z.infer<
  * TRANSPORT: positional args — validated host-side as this object.
  */
 export const PluginDesignDimensionsCreateArgs = z.object({
-  from: Vec3Input,
-  to: Vec3Input,
+  from: Vec3Handle,
+  to: Vec3Handle,
   anchor: ComponentHandle,
   anchorTo: ComponentHandle.optional(),
   offset: z.number().finite().optional(),

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

@@ -2,6 +2,10 @@ import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
 import { ComponentHandle } from "../../../handles"
 import { PluginDesignChangeResult } from "../lock"
+import type {
+  PluginOpeningPlacementArgs,
+  PluginOpeningPlacementResult,
+} from "../opening-placement"
 
 /**
  * `snaptrude.design.doors` — door-specific reads + edits. Creation lives at
@@ -22,6 +26,33 @@ import { PluginDesignChangeResult } from "../lock"
 export abstract class PluginDesignDoorsApi {
   constructor() {}
 
+  /**
+   * Trial the native host fit and geometry rebuild, then restore the model without publishing commands.
+   * The first result uses the creation options; subsequent results use candidateWidths in input order.
+   * Widths are authored parameters, not physical envelopes or a guaranteed maximum width.
+   * No catalog save, history entry or model persistence occurs. Rerun after model edits.
+   * A failed fit leaves cut unverified. Family-host cuts are also unverified: their rebuild
+   * cannot supply a reversible, authoritative trial result. Material clearance checks evaluated
+   * parts against physical neighbours across hosts. The intended host uses native fit/cut checks.
+   * Creation repeats clearance immediately before placement; this report grants no later approval.
+   * Editing permission is required; locked hosts and an active opening tool reject.
+   * It does not say which room the door opens into: read `opensInto` from
+   * `design.validation.access()` after placement (see {@linkcode getSwingDirection}).
+   * A requested width/height on a family sized by its Type (Custom Sizes off) picks the Type
+   * within 25 mm, else turns Custom Sizes on; each result's `sizing` says which. Creation
+   * (`design.create.door(s)`) applies the same rule, so the size you pass is the size built.
+   * @param options Door creation options and up to 12 alternative widths; numeric lengths use SU.
+   * @returns Separate fit/cut/clearance evidence, evaluated bounds and explicit limitations.
+   * @examplePrompt Check which door widths fit this host without placing a door
+   * @example
+   * const result = await snaptrude.design.doors.checkPlacement({
+   *   familyId, version, hostWall, position, width: 3.5, candidateWidths: [3, 2.5],
+   * })
+   */
+  public abstract checkPlacement(
+    options: PluginOpeningPlacementArgs,
+  ): PluginApiReturn<PluginOpeningPlacementResult>
+
   /**
    * Get the type name of a door — the label that identifies which kind of door
    * the instance is, as shown in its properties.
@@ -163,6 +194,12 @@ export abstract class PluginDesignDoorsApi {
    * Read the saved hand parameter. left means local -X; right means local +X.
    * Returns null when the recipe does not declare that control.
    *
+   * Hand is the hinge side, not the room the leaf swings into. For that, read
+   * `(await design.validation.access()).topology.rooms[].doors[].opensInto`: a
+   * converted room or `"outside"`. A door whose wall is not a room edge is listed
+   * in `topology.unresolvedDoors` instead. To make it open into the other room,
+   * call {@linkcode mirror} (axis `x`) and read access again.
+   *
    * @param door The door to query
    * @returns `'left'` / `'right'`, or `null` if indeterminate
    *
@@ -170,12 +207,16 @@ export abstract class PluginDesignDoorsApi {
    * @examplePrompt Is the selected door left-handed or right-handed?
    * @examplePrompt Check the hinge side of this door
    * @examplePrompt Does the entrance door open to the left or the right?
+   * @examplePrompt Which room does this door open into?
    *
    * # Example
    * ```ts
    * const [door] = await snaptrude.design.query.listDoors({ isSelected: true })
    * const swing = await snaptrude.design.doors.getSwingDirection(door)
    * if (swing) console.log("opens as a", swing, "hand door")
+   * // Which room it opens into
+   * const { topology } = await snaptrude.design.validation.access()
+   * const side = topology.rooms.flatMap((r) => r.doors).find((d) => d.door === door)?.opensInto
    * ```
    */
   public abstract getSwingDirection(
@@ -188,6 +229,8 @@ export abstract class PluginDesignDoorsApi {
    * Axis y rejects. No mesh reflection occurs. Recipes use outputs.swingSide
    * (1 or -1) for the adjoining room's floor ownership. A door between two
    * room floors requires this output; a missing or invalid report rejects the cut.
+   * The same side decides `opensInto` in `design.validation.access()`; read it
+   * there to confirm which room the door now opens into.
    *
    * @param door The door to mirror
    * @param axis Reflection axis (optional; default `'x'` — the swing-flip axis; `'z'` — the hinge-jamb axis)

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

@@ -1,6 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
-import { ComponentHandle, Vec3Input } from "../../../handles"
+import { ComponentHandle, Vec3Handle } from "../../../handles"
 import { OffsetSplitOutcome } from "../shared"
 
 /**
@@ -41,7 +41,7 @@ export abstract class PluginDesignEditApi {
   public abstract offsetSplit(
     component: ComponentHandle,
     offsetDistance: number,
-    options?: { profilePickPoint?: Vec3Input },
+    options?: { profilePickPoint?: Vec3Handle },
   ): PluginApiReturn<OffsetSplitOutcome>
 }
 
@@ -49,6 +49,6 @@ export abstract class PluginDesignEditApi {
 export const PluginDesignOffsetSplitArgs = z.object({
   component: ComponentHandle,
   offsetDistance: z.number(),
-  profilePickPoint: Vec3Input.optional(),
+  profilePickPoint: Vec3Handle.optional(),
 })
 export type PluginDesignOffsetSplitArgs = z.infer<typeof PluginDesignOffsetSplitArgs>

package/src/api/design/family.ts

@@ -5,7 +5,6 @@ import {
   ComponentHandle,
   Vec3Components,
   Vec3Handle,
-  Vec3Input,
 } from "../../handles"
 import { NetworkFamilyContract } from "./networks"
 
@@ -1320,7 +1319,7 @@ export type PluginDesignFamilyDeleteArgs = z.infer<
 export const PluginDesignFamilyPlaceArgs = z.object({
   id: z.string().optional(),
   version: z.number().int().positive().optional(),
-  position: z.union([Vec3Input, Vec3Components]).optional(),
+  position: z.union([Vec3Handle, Vec3Components]).optional(),
   rotation: z.number().optional(),
   values: z.record(z.string(), z.union([z.number(), z.string()])).optional(),
   storey: z.number().int().optional(),

package/src/api/design/index.ts

@@ -288,6 +288,7 @@ export * from "./query"
 export * from "./selection"
 export * from "./doors"
 export * from "./windows"
+export * from "./opening-placement"
 export * from "./furniture"
 export * from "./materials"
 export * from "./lock"

package/src/api/design/lock.ts

@@ -9,12 +9,6 @@ import { ComponentHandle } from "../../handles"
  */
 export const PluginDesignChangeResult = z.object({
   affected: z.array(ComponentHandle),
-  /** Derived BIM (walls/floors/slabs) the parametric engine removed with its host. Delete only. */
-  cascaded: z.array(ComponentHandle).optional(),
-  /** Handles that no longer resolved when the call ran and were skipped. Delete only. */
-  missing: z.array(ComponentHandle).optional(),
-  /** Handles the engine accepted but left standing; delete them again or report them. Delete only. */
-  rejected: z.array(ComponentHandle).optional(),
 })
 export type PluginDesignChangeResult = z.infer<typeof PluginDesignChangeResult>
 

package/src/api/design/opening-placement.ts

@@ -0,0 +1,79 @@
+import * as z from "zod"
+import { PluginOpeningBaseOptions } from "./create/opening-fields"
+
+/** Creation options plus bounded alternative widths. Each trial starts from the same model. */
+export const PluginOpeningPlacementArgs = z.object({
+  ...PluginOpeningBaseOptions,
+  sillHeight: z.number().finite().nonnegative().optional(),
+  candidateWidths: z.array(z.number().finite().positive()).max(12).optional(),
+})
+export type PluginOpeningPlacementArgs = z.infer<
+  typeof PluginOpeningPlacementArgs
+>
+
+/** A failed fit leaves the cut unverified: no geometry trial was attempted. */
+export const PluginOpeningPlacementCheck = z.object({
+  status: z.enum(["pass", "fail", "unverified"]),
+  reason: z.string(),
+})
+
+const bounds = z.object({
+  min: z.object({ x: z.number().finite(), y: z.number().finite(), z: z.number().finite() }),
+  max: z.object({ x: z.number().finite(), y: z.number().finite(), z: z.number().finite() }),
+})
+
+/** Fit, cut and material clearance are independent checks, not an accessibility certificate. */
+export const PluginOpeningPlacementResult = z.object({
+  units: z.literal("SU"),
+  results: z.array(
+    z.object({
+      requestedWidth: z.number().finite().positive().optional(),
+      requestedHeight: z.number().finite().positive().optional(),
+      /** Original parameter overrides. Evaluated bounds can differ from these values. */
+      requestedValues: z.record(z.string(), z.union([z.number().finite(), z.string()])).optional(),
+      /**
+       * Present when the family sizes itself from a Type unless Custom Sizes is on, and a width
+       * or height was requested. `type`: the Type within 25 mm was chosen (its label stays true).
+       * `custom`: none matched, so Custom Sizes was turned on and the requested size is built;
+       * `type` then names the Type that no longer describes it. Creation applies the same rule.
+       */
+      sizing: z
+        .object({
+          mode: z.enum(["type", "custom"]),
+          typeKey: z.string(),
+          type: z.string(),
+          note: z.string(),
+        })
+        .optional(),
+      /** World-space bounds of evaluated material parts, never the opening proxy. */
+      physicalBounds: bounds.optional(),
+      /** Only present when the recipe declares semantic frame anatomy. */
+      frameBounds: bounds.optional(),
+      /** World enclosure of the authored cut envelope; not frame or clear passage width. */
+      roughOpeningBounds: bounds.optional(),
+      dimensions: z
+        .object({
+          width: z.number().finite().positive(),
+          height: z.number().finite().positive(),
+          thickness: z.number().finite().nonnegative(),
+        })
+        .optional(),
+      fit: PluginOpeningPlacementCheck,
+      cut: PluginOpeningPlacementCheck,
+      clearance: PluginOpeningPlacementCheck.extend({
+        candidatePairs: z.number().int().nonnegative(),
+        checkedPairs: z.number().int().nonnegative(),
+        obstructions: z.array(z.object({
+          entity: z.string(),
+          status: z.enum(["fail", "unverified"]),
+          reason: z.string(),
+          intersectionVolume: z.number().finite().nonnegative().optional(),
+        })),
+      }),
+    }),
+  ),
+  limitations: z.array(z.string()),
+})
+export type PluginOpeningPlacementResult = z.infer<
+  typeof PluginOpeningPlacementResult
+>