@snaptrude/plugin-core 0.9.15 → 0.9.16-networks-20261009.1

package/src/api/design/create/bulk-items.ts

@@ -1,6 +1,8 @@
 import * as z from "zod"
 import { ContourHandle, ProfileHandle, Vec3Handle } from "../../../handles"
 import { PluginOpeningBaseOptions } from "./opening-fields"
+import { PluginWallType } from "../types"
+import { PluginFamilyValues } from "../catalog"
 
 /**
  * Maximum items per bulk `design.create.*` call. A bounded request keeps
@@ -88,7 +90,7 @@ export type PluginWallTopProfile = z.infer<typeof PluginWallTopProfile>
  * | `profile` | {@linkcode ProfileHandle} | Ordered curve chain (wall centerlines) |
  * | `height` | `number`? | Wall height (Snaptrude units, > 0; default engine default) |
  * | `thickness` | `number`? | Wall thickness (Snaptrude units, > 0; default: `wallType`'s total layer thickness when given, else engine default) |
- * | `wallType` | `string`? | Wall type name from `design.types.list("wall")` — layers/material/thickness defaults (default generic) |
+ * | `wallType` | {@linkcode PluginWallType}? | Legacy name/id or exact native `{ id, version }` pin from `design.types.list("wall")` (default generic) |
  * | `storey` | `number`? (int) | Target storey (must exist) — the run's walls are assigned + lifted to its base in the same undo entry (default: geometry-derived) |
  * | `topProfiles` | ({@linkcode PluginWallTopProfile} \| `null`)[]? | Top edge per curve of `profile`, same order; a `null` or missing entry keeps that wall flat at `height`. Raked / gabled walls (straight curves only) |
  */
@@ -96,9 +98,11 @@ export const PluginCreateWallRunItem = z.object({
   profile: ProfileHandle,
   height: z.number().optional(),
   thickness: z.number().optional(),
-  wallType: z.string().min(1).optional(),
+  wallType: PluginWallType.optional(),
   storey: z.number().int().optional(),
   topProfiles: z.array(PluginWallTopProfile.nullable()).optional(),
+  /** Optional family overrides in mm/degrees. Host length/height stay geometry inputs. */
+  values: PluginFamilyValues.optional(),
 })
 export type PluginCreateWallRunItem = z.infer<typeof PluginCreateWallRunItem>
 
@@ -143,22 +147,23 @@ export type PluginCreateFloorItems = z.infer<typeof PluginCreateFloorItems>
 
 /**
  * One door to place via {@linkcode PluginDesignCreateApi.doors} — the same
- * fields as a `"door"` {@linkcode PluginDesignCreateOpeningOptions}, so the
- * size overrides singular {@linkcode PluginDesignCreateApi.door} lacks are
- * available per item. `facing` and `hinge` are WORLD POINTS, not directions:
- * `facing` on the side of the wall the door swings open to, `hinge` near the
- * jamb it is hinged on. Rejects unknown fields.
+ * fields as a `"door"` {@linkcode PluginDesignCreateOpeningOptions}.
+ * Values are evaluated before cutting. Numeric lengths use SU; unit strings
+ * are accepted in values. `facing` selects local +Z; `hinge` sets the declared
+ * hand enum (left = local -X, right = +X). Both are world points.
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `familyId` | `string` | Hosted door family definition ID |
+ * | `version` | `number`? | Exact version; newest known by default |
+ * | `values` | `Record<string, number \| string>`? | Authored parameter overrides |
  * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the door |
  * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
  * | `facing` | {@linkcode Vec3Handle}? | World point on the side the door swings open to (default engine-chosen) |
- * | `hinge` | {@linkcode Vec3Handle}? | World point near the jamb the door is hinged on (default the catalog item's authored side) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the hinged jamb; requires hand control |
  * | `label` | `string`? | Instance name (optional) |
- * | `width` | `number`? | Width override (Snaptrude units, > 0; default the catalog item's) |
- * | `height` | `number`? | Height override (Snaptrude units, > 0; default the catalog item's) |
+ * | `width` | `number`? | Declared width parameter (SU, > 0), not evaluated hole width |
+ * | `height` | `number`? | Declared height parameter (SU, > 0) |
  */
 export const PluginCreateDoorItem = z
   .object({ ...PluginOpeningBaseOptions })
@@ -183,15 +188,17 @@ export type PluginCreateDoorItems = z.infer<typeof PluginCreateDoorItems>
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `familyId` | `string` | Hosted window family definition ID |
+ * | `version` | `number`? | Exact version; newest known by default |
+ * | `values` | `Record<string, number \| string>`? | Authored parameter overrides; numeric lengths use SU |
  * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the window |
  * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
  * | `facing` | {@linkcode Vec3Handle}? | World point on the side the window opens to (default engine-chosen) |
- * | `hinge` | {@linkcode Vec3Handle}? | World point near the jamb the window is hinged on (default the catalog item's authored side) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the hinged jamb; requires hand control |
  * | `label` | `string`? | Instance name (optional) |
- * | `width` | `number`? | Width override (Snaptrude units, > 0; default the catalog item's) |
- * | `height` | `number`? | Height override (Snaptrude units, > 0; default the catalog item's) |
- * | `sillHeight` | `number`? | Wall base to window bottom (Snaptrude units, ≥ 0; default the catalog item's) |
+ * | `width` | `number`? | Declared width parameter (SU, > 0), not evaluated hole width |
+ * | `height` | `number`? | Declared height parameter (SU, > 0) |
+ * | `sillHeight` | `number`? | Declared sill parameter (SU, ≥ 0); position Y is ignored |
  */
 export const PluginCreateWindowItem = z
   .object({

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

@@ -4,6 +4,7 @@ import {
   BrepHandle,
   ComponentHandle,
   ContourHandle,
+  LineHandle,
   CurveHandle,
   ProfileHandle,
   Vec3Handle,
@@ -29,6 +30,14 @@ import type {
   PluginCreateWindowItem,
 } from "./bulk-items"
 import { PluginWallTopProfile } from "./bulk-items"
+import { PluginWallType } from "../types"
+import {
+  PluginFamilyPlacement,
+  PluginFamilyFloorOptions,
+  PluginFamilySlabOptions,
+  PluginFamilyCeilingOptions,
+  PluginFamilyValues,
+} from "../catalog"
 
 /**
  * `design.create.*` — author new scene-committed BIM entities.
@@ -43,7 +52,13 @@ import { PluginWallTopProfile } from "./bulk-items"
  * Footprint objects take a {@linkcode ContourHandle} (outer profile + holes);
  * build one with `snaptrude.core.geom.create.contourFromProfile(s)`.
  *
- * `door`/`window` place a catalog item into a host wall (the world point is
+ * Family overloads take `{ type, values? }` from `design.catalog`. The family supplies
+ * construction; the contour or axis supplies instance geometry. Geometry uses SU,
+ * while family length overrides use mm and angles use degrees. Omitted parameters
+ * retain family defaults; shared/type, formula and geometry-bound overrides are refused.
+ * Placement never publishes a definition. Unsupported references or geometry fail before mutation.
+ *
+ * `door`/`window` place a parametric family into a host wall (the world point is
  * projected onto the wall face to locate the opening; the wall is re-cut in one
  * undo entry) and throw if the point projects outside the wall. `smartLayout` is
  * the one creator returning a grouped {@linkcode PluginSmartLayoutResult} rather
@@ -219,20 +234,29 @@ export abstract class PluginDesignCreateApi {
    * ```
    */
   public abstract slab(
-    contour: ContourHandle,
-    thickness: number,
-    direction?: "up" | "down",
-    slabType?: PluginSlabType,
+    ...args:
+      | [
+          contour: ContourHandle,
+          thickness: number,
+          direction?: "up" | "down",
+          slabType?: PluginSlabType,
+        ]
+      | [contour: ContourHandle, options: PluginFamilySlabOptions]
   ): PluginApiReturn<ComponentHandle>
 
   /**
    * Create a **floor** by extruding a footprint contour by `thickness`
    * (extruded upward).
    *
+   * The native family overload takes `{ type, values?, position? }`. Contour
+   * geometry uses SU; family values use mm. The family supplies layer thickness.
+   * PG2 can split or merge the footprint, so both overloads return an array.
+   * A merge into an existing floor can return no newly created handles.
+   *
    * @param contour - Footprint (outer + holes)
    * @param thickness - Floor thickness (> 0)
    * @param position - Offset from origin
-   * @returns the {@linkcode ComponentHandle} of the created floor
+   * @returns Newly created {@linkcode ComponentHandle}s; an empty array after a merge
    * @throws if the contour is invalid or the thickness is not positive
    *
    * @examplePrompt Create a floor from this room outline
@@ -247,15 +271,15 @@ export abstract class PluginDesignCreateApi {
    * const floor = await snaptrude.design.create.floor(contour, 0.1)
    * ```
    *
-   * @performance For MORE THAN ONE floor, call `design.create.floors(items[])` — one
-   *   host round-trip and ONE undo entry for the whole batch. Looping this single-floor
-   *   creator is N round-trips and N undo entries.
+   * @performance For dimensional floors, `design.create.floors(items[])` uses one
+   *   host round-trip and one undo entry. That bulk method does not accept native
+   *   family options; use this method for a family-backed floor.
    */
   public abstract floor(
-    contour: ContourHandle,
-    thickness: number,
-    position?: Vec3Handle,
-  ): PluginApiReturn<ComponentHandle>
+    ...args:
+      | [contour: ContourHandle, thickness: number, position?: Vec3Handle]
+      | [contour: ContourHandle, options: PluginFamilyFloorOptions]
+  ): PluginApiReturn<ComponentHandle[]>
 
   /**
    * Create **many floors** in one undoable operation (bulk plural of
@@ -320,7 +344,7 @@ export abstract class PluginDesignCreateApi {
    */
   public abstract roof(
     contour: ContourHandle,
-    thickness: number,
+    thickness: number | PluginFamilyPlacement,
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -346,9 +370,9 @@ export abstract class PluginDesignCreateApi {
    * ```
    */
   public abstract ceiling(
-    contour: ContourHandle,
-    thickness: number,
-    heightFromFloor?: number,
+    ...args:
+      | [contour: ContourHandle, thickness: number, heightFromFloor?: number]
+      | [contour: ContourHandle, options: PluginFamilyCeilingOptions]
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -379,10 +403,14 @@ export abstract class PluginDesignCreateApi {
    * ```
    */
   public abstract column(
-    position: Vec3Handle,
-    crossSection: ContourHandle,
-    height: number,
-    directionUp?: Vec3Handle,
+    ...args:
+      | [
+          position: Vec3Handle,
+          crossSection: ContourHandle,
+          height: number,
+          directionUp?: Vec3Handle,
+        ]
+      | [axis: LineHandle, options: PluginFamilyPlacement]
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -426,9 +454,9 @@ export abstract class PluginDesignCreateApi {
    * ```
    */
   public abstract beam(
-    section: ContourHandle,
-    length: number,
-    direction?: Vec3Handle,
+    ...args:
+      | [section: ContourHandle, length: number, direction?: Vec3Handle]
+      | [axis: LineHandle, options: PluginFamilyPlacement]
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -439,12 +467,12 @@ export abstract class PluginDesignCreateApi {
    * @param height - Wall height (default engine default)
    * @param thickness - Wall thickness (default: the `wallType`'s total layer
    *   thickness when `wallType` is given, else the engine default)
-   * @param wallType - Wall type to build with — the same searchable list the
-   *   Draw tab's Wall Type dropdown offers. Pass a name from
-   *   `design.types.list("wall")` (the summary's `label`, or its `"wall:…"` id).
-   *   Drives the wall's construction layers and default material, and — when
-   *   `thickness` is omitted — its total layer thickness. Default: the engine's
-   *   generic wall.
+   * @param wallType - Legacy label/`wall:` id, or the exact `nativeFamily`
+   *   `{ id, version }` pin from `design.types.list("wall")`. Native pins are
+   *   authorized on every use; selecting a family in Draw is not registration.
+   *   Native pins support straight horizontal centerlines and flat tops only.
+   *   Omit thickness for native pins; a conflicting explicit thickness rejects.
+   *   Default: the engine's generic wall.
    * @param storey - Target storey (integer: `1` ground, `2` first floor, `-1`
    *   basement — same convention as `design.create.space`). The walls are
    *   assigned to it and lifted to its base elevation, all inside the same
@@ -503,9 +531,10 @@ export abstract class PluginDesignCreateApi {
     profile: ProfileHandle,
     height?: number,
     thickness?: number,
-    wallType?: string,
+    wallType?: PluginWallType,
     storey?: number,
     topProfiles?: (PluginWallTopProfile | null)[],
+    values?: PluginFamilyValues,
   ): PluginApiReturn<ComponentHandle[]>
 
   /**
@@ -895,30 +924,23 @@ export abstract class PluginDesignCreateApi {
   ): PluginApiReturn<ComponentHandle[]>
 
   /**
-   * Place a **door** from the catalog into a host wall.
+   * Place a parametric **door** family into a host wall.
    *
-   * Identified by a **catalog (library) id** — the team object's stable `_id`
-   * or the general library's `fullName`. Discover ids with
+   * Identified by a saved **family definition id**. Discover ids with
    * {@linkcode PluginDesignDoorsApi.listCatalog}. The world `position` is
    * projected onto the host wall's face to locate the opening; the wall is
    * re-cut and the door hosted in a single undo entry. Placement is
-   * asynchronous (the source mesh is fetched if not cached).
+   * asynchronous. Values and host bindings are evaluated before the first cut.
    *
-   * @param catalogId - Library id: team `_id` or general `fullName`
+   * @param familyId - Hosted door definition ID; legacy mesh catalog IDs are not accepted
    * @param hostWall - The wall to host the door
    * @param position - World point projected onto the wall to locate the opening
-   * @param options - Optional placement options: `label` — instance name;
-   *   `hinge` — world point near the jamb the door is hinged on (the door is
-   *   reflected along the wall so its hinged jamb is the one nearer this
-   *   point; default the catalog item's authored hinge side)
-   * @param facing - World point on the side of the wall the door swings open
-   *   to (the room it opens into — where the plan symbol draws the swing arc).
-   *   Any point clearly on that side works (e.g. the room's center). Default:
-   *   the engine picks a side (nondeterministic when `position` sits on the
-   *   wall centerline).
+   * @param options - `version` pins the definition. `values` sets authored parameters
+   *   (numeric lengths in SU, or unit strings). `label` names the instance.
+   *   `hinge` selects the declared `hand` enum: local -X is left, +X is right.
+   * @param facing - World point selecting local +Z; omitted uses the picked face
    * @returns the {@linkcode ComponentHandle} of the placed door
-   * @throws if the catalog id is unknown, the host is not a wall, the source
-   *   mesh fails to load, or the projected point falls **outside** the host wall
+   * @throws if the family/category/parameters are invalid, or placement or cutting fails
    *
    * @examplePrompt Add a door to this wall here
    * @examplePrompt Place a sliding door on the selected wall
@@ -961,26 +983,28 @@ export abstract class PluginDesignCreateApi {
    *   that single call. Looping this single-door creator is N round-trips.
    */
   public abstract door(
-    catalogId: string,
+    familyId: string,
     hostWall: ComponentHandle,
     position: Vec3Handle,
-    options?: { label?: string; hinge?: Vec3Handle },
+    options?: {
+      label?: string
+      hinge?: Vec3Handle
+      version?: number
+      values?: Record<string, number | string>
+    },
     facing?: Vec3Handle,
   ): PluginApiReturn<ComponentHandle>
 
   /**
    * Place **many doors** into host walls in one undoable operation (bulk plural
-   * of {@linkcode door}). Each item carries its own catalog id, host wall,
+   * of {@linkcode door}). Each item carries its own family id, host wall,
    * world position, and optional `facing`, `label`, `width` and `height` — the
    * same fields as a `"door"` {@linkcode PluginDesignCreateOpeningOptions}.
    * Validate-all-or-throw; one command.
    *
-   * As with the singular creator, placing an opening **re-cuts its host wall**:
-   * the wall you passed as `hostWall` stops resolving once the call returns.
-   * Several items MAY name the same original wall handle in one call — the host
-   * chains the re-cuts internally — but after the call recover the surviving
-   * wall with `design.query.getHost(opening)`, never by reusing the handle you
-   * passed in.
+   * The wall keeps its identity. Several items may use the same host.
+   * Width and height set named recipe parameters, not mesh scale. The recipe's
+   * evaluated hole can include frame allowances. A failed item rolls back the batch.
    *
    * @param items - One {@linkcode PluginCreateDoorItem} per door to place
    *   (≥1, ≤1000)
@@ -988,10 +1012,9 @@ export abstract class PluginDesignCreateApi {
    * @throws `VALIDATION` if the items fail the schema (empty array, more than
    *   1000 items, unknown fields, a non-positive `width`/`height`);
    *   `HANDLE_INVALID` if a `position`, `facing` or `hinge` handle is unknown
-   *   or released; `PRECONDITION_FAILED` if a catalog id is unknown, a `hostWall`
-   *   is not a wall / is locked / is not in the active proposal, the projected
-   *   point falls outside its host wall, or a door tool is active;
-   *   `OPERATION_FAILED` if a source mesh fails to load or placement fails
+   *   or released; `PRECONDITION_FAILED` if the family cannot be resolved or saved,
+   *   or a host is locked / is not in the active proposal;
+   *   `OPERATION_FAILED` if placement, containment, overlap checks or cutting fail
    *   (nothing is created — `details.itemIndex` is the failing item);
    *   `METHOD_NOT_PERMITTED` if the plugin may not write.
    *
@@ -1002,7 +1025,7 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Add all the doors for this floor plan together
    *
    * @performance Bulk creator — the whole batch is ONE host round-trip and ONE undo
-   *   entry, and each distinct catalog source loads once. Always prefer this over
+   *   entry. Always prefer this over
    *   calling `design.create.door` in a loop: build the full `items[]` array first
    *   (all host walls and points up front), then make one call.
    *
@@ -1012,10 +1035,10 @@ export abstract class PluginDesignCreateApi {
    * const [wall] = await snaptrude.design.query.listWalls({ isSelected: true })
    * const [entry] = await snaptrude.design.doors.listCatalog()
    * const [front, side] = await snaptrude.design.create.doors([
-   *   { catalogId: entry.id, hostWall: wall, position: await v.new(2, 0, 5), label: "D-01" },
-   *   { catalogId: entry.id, hostWall: wall, position: await v.new(6, 0, 5), width: 1.2 },
+   *   { familyId: entry.id, hostWall: wall, position: await v.new(2, 0, 5), label: "D-01" },
+   *   { familyId: entry.id, hostWall: wall, position: await v.new(6, 0, 5), values: { width: "1200mm" } },
    * ])
-   * // `wall` was re-cut twice and no longer resolves — ask the opening for its host:
+   * // The host still resolves after both cuts:
    * const currentWall = await snaptrude.design.query.getHost(front)
    * ```
    */
@@ -1024,29 +1047,21 @@ export abstract class PluginDesignCreateApi {
   ): PluginApiReturn<ComponentHandle[]>
 
   /**
-   * Place a **window** from the catalog into a host wall.
+   * Place a parametric **window** family into a host wall.
    *
-   * Identified by a **catalog (library) id** — the team object's stable `_id`
-   * or the general library's `fullName`. Discover ids with
+   * Identified by a saved **family definition id**. Discover ids with
    * {@linkcode PluginDesignWindowsApi.listCatalog}. The world `position` is
    * projected onto the host wall's face to locate the opening; the wall is
    * re-cut and the window hosted in a single undo entry. Placement is
-   * asynchronous (the source mesh is fetched if not cached).
+   * asynchronous. The sill parameter determines elevation; position Y is ignored.
    *
-   * @param catalogId - Library id: team `_id` or general `fullName`
+   * @param familyId - Hosted window definition ID; legacy mesh catalog IDs are not accepted
    * @param hostWall - The wall to host the window
    * @param position - World point projected onto the wall to locate the opening
-   * @param options - Optional placement options: `label` — instance name;
-   *   `hinge` — world point near the jamb the window is hinged on (same rule
-   *   as {@linkcode PluginDesignCreateApi.door}; default the catalog item's
-   *   authored side)
-   * @param facing - World point on the side of the wall the window opens to
-   *   (matters for asymmetric windows, e.g. casement swing) — same convention
-   *   as {@linkcode PluginDesignCreateApi.door}. Default: the engine picks a
-   *   side (nondeterministic when `position` sits on the centerline).
+   * @param options - `version`, `values`, `label`, and parameter-driven `hinge`, as for door
+   * @param facing - World point selecting local +Z; omitted uses the picked face
    * @returns the {@linkcode ComponentHandle} of the placed window
-   * @throws if the catalog id is unknown, the host is not a wall, the source
-   *   mesh fails to load, or the projected point falls **outside** the host wall
+   * @throws if the family/category/parameters are invalid, or placement or cutting fails
    *
    * @examplePrompt Add a window to this wall here
    * @examplePrompt Place a casement window on the selected wall
@@ -1072,28 +1087,29 @@ export abstract class PluginDesignCreateApi {
    *   inside that single call. Looping this single-window creator is N round-trips.
    */
   public abstract window(
-    catalogId: string,
+    familyId: string,
     hostWall: ComponentHandle,
     position: Vec3Handle,
-    options?: { label?: string; hinge?: Vec3Handle },
+    options?: {
+      label?: string
+      hinge?: Vec3Handle
+      version?: number
+      values?: Record<string, number | string>
+    },
     facing?: Vec3Handle,
   ): PluginApiReturn<ComponentHandle>
 
   /**
    * Place **many windows** into host walls in one undoable operation (bulk
-   * plural of {@linkcode window}). Each item carries its own catalog id, host
+   * plural of {@linkcode window}). Each item carries its own family id, host
    * wall, world position, and optional `facing`, `label`, `width`, `height` and
    * `sillHeight` — the same fields as a `"window"`
    * {@linkcode PluginDesignCreateOpeningOptions}. `sillHeight` is measured from
    * the host wall base to the BOTTOM of the window. Validate-all-or-throw; one
    * command.
    *
-   * As with the singular creator, placing an opening **re-cuts its host wall**:
-   * the wall you passed as `hostWall` stops resolving once the call returns.
-   * Several items MAY name the same original wall handle in one call — the host
-   * chains the re-cuts internally — but after the call recover the surviving
-   * wall with `design.query.getHost(opening)`, never by reusing the handle you
-   * passed in.
+   * Hosts keep their identity. Width, height and sillHeight set the declared
+   * width, height and sill parameters before the first cut. No mesh scaling occurs.
    *
    * @param items - One {@linkcode PluginCreateWindowItem} per window to place
    *   (≥1, ≤1000)
@@ -1101,10 +1117,9 @@ export abstract class PluginDesignCreateApi {
    * @throws `VALIDATION` if the items fail the schema (empty array, more than
    *   1000 items, unknown fields, a non-positive `width`/`height`, a negative
    *   `sillHeight`); `HANDLE_INVALID` if a `position`, `facing` or `hinge`
-   *   handle is unknown or released; `PRECONDITION_FAILED` if a catalog id is unknown, a
-   *   `hostWall` is not a wall / is locked / is not in the active proposal, the
-   *   projected point falls outside its host wall, or a window tool is active;
-   *   `OPERATION_FAILED` if a source mesh fails to load or placement fails
+   *   handle is unknown or released; `PRECONDITION_FAILED` if the family cannot be
+   *   resolved or saved, or a host is locked / is not in the active proposal;
+   *   `OPERATION_FAILED` if placement, containment, overlap checks or cutting fail
    *   (nothing is created — `details.itemIndex` is the failing item);
    *   `METHOD_NOT_PERMITTED` if the plugin may not write.
    *
@@ -1115,7 +1130,7 @@ export abstract class PluginDesignCreateApi {
    * @examplePrompt Add all the windows with a 0.9m sill height together
    *
    * @performance Bulk creator — the whole batch is ONE host round-trip and ONE undo
-   *   entry, and each distinct catalog source loads once. Always prefer this over
+   *   entry. Always prefer this over
    *   calling `design.create.window` in a loop: build the full `items[]` array first
    *   (all host walls and points up front), then make one call.
    *
@@ -1125,8 +1140,8 @@ export abstract class PluginDesignCreateApi {
    * const [wall] = await snaptrude.design.query.listWalls({ isSelected: true })
    * const [casement] = await snaptrude.design.windows.listCatalog()
    * const placed = await snaptrude.design.create.windows([
-   *   { catalogId: casement.id, hostWall: wall, position: await v.new(2, 0, 5), sillHeight: 0.9 },
-   *   { catalogId: casement.id, hostWall: wall, position: await v.new(5, 0, 5), sillHeight: 0.9 },
+   *   { familyId: casement.id, hostWall: wall, position: await v.new(2, 0, 5), values: { sill: "900mm" } },
+   *   { familyId: casement.id, hostWall: wall, position: await v.new(5, 0, 5), values: { sill: "900mm" } },
    * ])
    * const currentWall = await snaptrude.design.query.getHost(placed[0])
    * ```
@@ -1136,17 +1151,17 @@ export abstract class PluginDesignCreateApi {
   ): PluginApiReturn<ComponentHandle[]>
 
   /**
-   * Place a catalog **door or window** into a host wall with optional size overrides.
+   * Place a parametric **door or window** into a host wall with parameter overrides.
    *
    * The world `position` is projected onto the host wall to locate the opening.
    * All supplied dimensions use Snaptrude engine units. Window `sillHeight` is
    * measured from the host wall base to the bottom of the window, not to
    * its center. Placement is asynchronous and committed as one undoable creation.
    *
-   * @param options - Opening kind, catalog and host references, placement, and
+   * @param options - Opening kind, family and host references, placement, and
    *   optional facing (swing side), hinge (hinged jamb), label, and dimensions
    * @returns the {@linkcode ComponentHandle} of the placed door or window
-   * @throws if the options are invalid, the catalog id is unknown, the host is
+   * @throws if the options are invalid, the family id is unknown, the host is
    *   not a wall, loading fails, or the opening cannot be placed on the host
    *
    * @examplePrompt Add a 1m wide door to this wall here
@@ -1160,7 +1175,7 @@ export abstract class PluginDesignCreateApi {
    * ```ts
    * const opening = await snaptrude.design.create.opening({
    *   kind: "window",
-   *   catalogId: windowType.id,
+   *   familyId: windowType.id,
    *   hostWall: wall,
    *   position: await snaptrude.core.math.vec3.new(3, 0, 5),
    *   width: 1.2,
@@ -1660,7 +1675,7 @@ export type PluginDesignCreateBeamArgs = z.infer<
  * | `profile` | {@linkcode ProfileHandle} | Ordered curve chain (wall centerlines) |
  * | `height` | `number`? | Wall height (default engine default) |
  * | `thickness` | `number`? | Wall thickness (default: `wallType`'s total layer thickness when given, else engine default) |
- * | `wallType` | `string`? | Wall type name from `design.types.list("wall")` — layers/material/thickness defaults (default generic) |
+ * | `wallType` | {@linkcode PluginWallType}? | Legacy name/id or exact native `{ id, version }` pin from `design.types.list("wall")` (default generic) |
  * | `storey` | `number`? | Target storey (integer, must exist) — walls assigned + lifted to its base in the same undo entry (default: geometry-derived) |
  * | `topProfiles` | ({@linkcode PluginWallTopProfile} \| `null`)[]? | Top edge per curve (same order); `null`/missing = flat at `height`. Straight curves only |
  */
@@ -1668,9 +1683,10 @@ export const PluginDesignCreateWallsArgs = z.object({
   profile: ProfileHandle,
   height: z.number().optional(),
   thickness: z.number().optional(),
-  wallType: z.string().min(1).optional(),
+  wallType: PluginWallType.optional(),
   storey: z.number().int().optional(),
   topProfiles: z.array(PluginWallTopProfile.nullable()).optional(),
+  values: PluginFamilyValues.optional(),
 })
 export type PluginDesignCreateWallsArgs = z.infer<
   typeof PluginDesignCreateWallsArgs
@@ -1743,26 +1759,23 @@ export type PluginDesignCreateFurnitureArgs = z.infer<
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `familyId` | `string` | Hosted door family definition ID |
+ * | `version` | `number`? | Exact version; newest known by default |
+ * | `values` | `Record<string, number \| string>`? | Parameters; numeric lengths use SU |
  * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the door |
  * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
  * | `label` | `string`? | Instance name (optional) |
  * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the door swings open to (default engine-chosen) |
- * | `hinge` | {@linkcode Vec3Handle}? | World point near the jamb the door is hinged on (default the catalog item's authored side) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the hinged jamb; requires hand control |
  */
 export const PluginDesignCreateDoorArgs = z.object({
-  catalogId: z.string().min(1),
-  hostWall: ComponentHandle,
-  position: Vec3Handle,
-  label: z.string().optional(),
-  facing: Vec3Handle.optional(),
-  hinge: Vec3Handle.optional(),
+  ...PluginOpeningBaseOptions,
 })
 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)
+//   door(familyId, hostWall, position, options?: { label?, hinge?, version?, values? }, facing?)
 
 // ---------------------------------------------------------------------------
 // window
@@ -1773,26 +1786,23 @@ export type PluginDesignCreateDoorArgs = z.infer<
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `familyId` | `string` | Hosted window family definition ID |
+ * | `version` | `number`? | Exact version; newest known by default |
+ * | `values` | `Record<string, number \| string>`? | Parameters; numeric lengths use SU |
  * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the window |
  * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
  * | `label` | `string`? | Instance name (optional) |
  * | `facing` | {@linkcode Vec3Handle}? | World point on the side of the wall the window opens to (default engine-chosen) |
- * | `hinge` | {@linkcode Vec3Handle}? | World point near the jamb the window is hinged on (default the catalog item's authored side) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the hinged jamb; requires hand control |
  */
 export const PluginDesignCreateWindowArgs = z.object({
-  catalogId: z.string().min(1),
-  hostWall: ComponentHandle,
-  position: Vec3Handle,
-  label: z.string().optional(),
-  facing: Vec3Handle.optional(),
-  hinge: Vec3Handle.optional(),
+  ...PluginOpeningBaseOptions,
 })
 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)
+//   window(familyId, hostWall, position, options?: { label?, hinge?, version?, values? }, facing?)
 
 // ---------------------------------------------------------------------------
 // opening