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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.9.16",
+  "version": "0.9.18-voids-20261016.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/scripts/generate-manifest.mjs

@@ -115,6 +115,11 @@ export function buildManifest({ includeOptional = false } = {}) {
     const cls = classes.get(className)
     if (!cls) return
 
+    // Domain network namespaces inherit their transport methods. Include these
+    // leaves so discovery exposes the same API as the generic worker proxy.
+    const base = cls.getExtends()?.getExpression().getText()
+    if (base && classes.has(base)) walk(base, pathPrefix)
+
     // Leaf methods on this namespace.
     for (const method of cls.getMethods()) {
       const name = method.getName()

package/src/api/core/camera/index.ts

@@ -17,6 +17,11 @@ import { Vec3Components, Vec3Handle } from "../../../handles"
  * Positions are world coordinates in internal `babylon` units (1 unit =
  * 0.254 m, Y up); yaw is degrees clockwise from +z seen from above, pitch is
  * degrees above level.
+ *
+ * While Present mode is open these calls set the Design frame a view saved in
+ * Present (`presentation.views.create`) is taken from; they never move the
+ * Present sheet canvas. To pan, zoom or screenshot the Present canvas, use
+ * {@linkcode PluginPresentationCameraApi} (`presentation.camera`).
  */
 export abstract class PluginCameraApi {
   constructor() {}
@@ -25,6 +30,10 @@ export abstract class PluginCameraApi {
    * Point the camera: place its eye at `eye` looking toward `target` (world
    * coordinates, internal `babylon` units). View-state only — not undoable.
    *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @param eye - Camera position as a {@linkcode Vec3Handle}
    * @param target - Point the camera looks at as a {@linkcode Vec3Handle}
    * @returns `true` once the camera has been positioned.
@@ -51,6 +60,10 @@ export abstract class PluginCameraApi {
    * perspective) view. Mirrors the canvas view menu. View-state only — not
    * undoable. The orthographic presets exit 2D mode first if needed.
    *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @param view - The standard view to snap to ({@linkcode PluginStandardView})
    * @returns `true` once the view has been applied.
    *
@@ -91,6 +104,10 @@ export abstract class PluginCameraApi {
    * 2D/3D toggle: `3d` enters the isometric perspective view, `2d` drops to the
    * orthographic plan of the active storey. View-state only — not undoable.
    *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @param mode - `"2d"` or `"3d"` ({@linkcode PluginCameraMode})
    * @returns `true` once the mode switch has been requested.
    *
@@ -135,6 +152,10 @@ export abstract class PluginCameraApi {
    * `"orthographic"` is accepted as a no-op, while `"perspective"` is
    * rejected — switch to 3D first via `setMode("3d")`.
    *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @param projection - `"perspective"` or `"orthographic"` ({@linkcode PluginCameraProjection})
    * @returns `true` once the projection has been applied.
    *
@@ -158,6 +179,10 @@ export abstract class PluginCameraApi {
    * action. View-state only — not undoable. Canonical home of the zoom-extents
    * read (the deprecated `core.zoom.extents`).
    *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @returns `true` once the camera has been framed to the scene.
    *
    * @examplePrompt Zoom out so I can see the whole model
@@ -177,6 +202,10 @@ export abstract class PluginCameraApi {
    * undoable. Canonical home of the zoom-to-selection read (the deprecated
    * `core.zoom.selection`).
    *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @returns `true` if there was a selection to frame; `false` if nothing is
    *   selected (no-op).
    *

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

@@ -317,6 +317,9 @@ export abstract class PluginGeomCreateApi {
    * Create a contour from an outer profile plus zero or more inner profiles (holes).
    * Host API call — returns a handle.
    *
+   * A hole here is part of the footprint and cannot be moved or deleted later;
+   * for an editable hole in a slab use `design.create.void`.
+   *
    * @param outer The outer boundary loop
    * @param holes Optional inner hole loops
    * @returns The new contour as a {@linkcode ContourHandle}
@@ -688,6 +691,9 @@ export abstract class PluginGeomCreateApi {
    * The first boolean call loads the OpenCascade geometry kernel (a wasm of
    * tens of MB — expect a pause of seconds); subsequent calls are fast.
    *
+   * Returns a detached solid; to cut an editable hole in a slab, floor or roof
+   * in the model use `design.create.void`.
+   *
    * @param a The solid to subtract from
    * @param b The solid to remove from `a`
    * @returns `a` minus `b` as a new {@linkcode BrepHandle}
@@ -696,7 +702,7 @@ export abstract class PluginGeomCreateApi {
    *
    * @examplePrompt Subtract the courtyard from the building mass
    * @examplePrompt Cut this solid out of that one
-   * @examplePrompt Punch a hole through the slab with this box
+   * @examplePrompt Subtract this box solid from that solid
    *
    * # Example
    * ```ts

package/src/api/core/geom/update/contour.ts

@@ -156,12 +156,15 @@ export abstract class PluginGeomUpdateContourApi {
    * Add a hole to a contour by appending an inner profile. Immutable — returns a NEW
    * contour and leaves the input unchanged.
    *
+   * Edits a contour value only; for an editable hole in an existing slab, floor
+   * or roof use `design.create.void`.
+   *
    * @param contour The contour to add a hole to
    * @param hole The inner profile to add as a hole
    * @returns The contour with the added hole as a NEW {@linkcode ContourHandle}
    *
    * @examplePrompt Cut a hole in this shape
-   * @examplePrompt Punch an opening through this floor outline
+   * @examplePrompt Punch an opening through this outline
    *
    * # Example
    * ```ts
@@ -181,12 +184,15 @@ export abstract class PluginGeomUpdateContourApi {
    * Remove a hole from a contour by inner-profile index. Immutable — returns a NEW
    * contour and leaves the input unchanged.
    *
+   * Edits a contour value only; for an editable hole in an existing slab, floor
+   * or roof use `design.create.void`.
+   *
    * @param contour The contour to remove a hole from
    * @param index Zero-based index of the inner profile (hole) to remove
    * @returns The contour with the hole removed as a NEW {@linkcode ContourHandle}
    *
    * @examplePrompt Remove the hole from this shape
-   * @examplePrompt Fill in the opening in this floor outline
+   * @examplePrompt Fill in the opening in this outline
    *
    * # Example
    * ```ts

package/src/api/core/zoom/index.ts

@@ -5,6 +5,11 @@ import { PluginApiReturn } from "../../../types"
  *
  * Frame the viewport camera onto scene geometry — mirrors the canvas zoom menu
  * ("Zoom extents" / "Zoom to selection"). Accessed via `snaptrude.core.zoom`.
+ *
+ * While Present mode is open these calls set the Design frame a view saved in
+ * Present (`presentation.views.create`) is taken from; they never move the
+ * Present sheet canvas. To pan, zoom or screenshot the Present canvas, use
+ * {@linkcode PluginPresentationCameraApi} (`presentation.camera`).
  */
 export abstract class PluginZoomApi {
   constructor() {}
@@ -12,6 +17,10 @@ export abstract class PluginZoomApi {
   /**
    * Zoom (fit) the camera to all geometry in the scene — the "zoom extents" action.
    *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @returns `true` once the camera has been framed to the scene.
    *
    * @examplePrompt Zoom out so I can see the whole model
@@ -32,6 +41,10 @@ export abstract class PluginZoomApi {
   /**
    * Zoom (fit) the camera to the current selection.
    *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @returns `true` if there was a selection to frame; `false` if nothing is
    *   selected (no-op).
    *

package/src/api/design/bim.ts

@@ -0,0 +1,121 @@
+import * as z from "zod"
+import { ComponentHandle } from "../../handles"
+import type { PluginApiReturn } from "../../types"
+import { PluginConstructionType, PluginFamilyValues } from "./catalog"
+import { PluginFamilyBundleSchema } from "./family"
+
+const id = z.string().min(1).max(300)
+const spaces = z.array(ComponentHandle).min(1).max(1000)
+
+/** Read scope. Omit spaces to inspect the active proposal's sketch spaces. */
+export const PluginBimContextArgs = z.object({ spaces: spaces.optional() }).strict()
+export type PluginBimContextArgs = z.infer<typeof PluginBimContextArgs>
+
+/** Directed graph edge. Side A lies along world-up × curve-direction; side B is opposite.
+ * Region IDs are snapshot identifiers, not component handles. Null means no adjacent region.
+ */
+export const PluginBimEdge = z.object({
+  id,
+  startMm: z.tuple([z.number(), z.number(), z.number()]),
+  endMm: z.tuple([z.number(), z.number(), z.number()]),
+  lengthMm: z.number(),
+  heightMm: z.number(),
+  sideA: id.nullable(),
+  sideB: id.nullable(),
+  wall: ComponentHandle.nullable(),
+  supported: z.boolean(),
+})
+export type PluginBimEdge = z.infer<typeof PluginBimEdge>
+
+/** Construction context is detached. Revision covers geometry, room metadata and construction state. */
+export const PluginBimContext = z.object({
+  revision: id,
+  proposalId: id,
+  units: z.literal("mm"),
+  spaces: z.array(z.object({
+    component: ComponentHandle,
+    label: z.string(),
+    storey: z.number(),
+    eligible: z.boolean(),
+    reason: z.string().optional(),
+  })),
+  regions: z.array(z.object({ id, spaces: z.array(ComponentHandle) })),
+  edges: z.array(PluginBimEdge),
+})
+export type PluginBimContext = z.infer<typeof PluginBimContext>
+
+/** Plan-local key selects either an existing construction or a new project-only native recipe.
+ * Bundles use the native DSL's SU/unit-expression rules; values overrides use mm/degrees.
+ */
+export const PluginBimConstruction = z.union([
+  z.object({ key: id, reference: PluginConstructionType }).strict(),
+  z.object({ key: id, bundle: PluginFamilyBundleSchema }).strict(),
+])
+export type PluginBimConstruction = z.infer<typeof PluginBimConstruction>
+
+/** Every unwalled edge in the selected scope needs exactly one assignment.
+ * The first authored layer faces sideA unless reversed. Alignment sets the initial core-centre offset.
+ * Later parameter edits preserve the offset and reject invalid core alignment.
+ */
+export const PluginBimWallAssignment = z.object({
+  edgeId: id,
+  construction: id,
+  values: PluginFamilyValues.optional(),
+  reversed: z.boolean(),
+  alignment: z.literal("coreCentre"),
+}).strict()
+export type PluginBimWallAssignment = z.infer<typeof PluginBimWallAssignment>
+
+export const PluginBimPrepareArgs = z.object({
+  revision: id,
+  spaces,
+  constructions: z.array(PluginBimConstruction).max(1000),
+  walls: z.array(PluginBimWallAssignment).max(10000),
+}).strict()
+export type PluginBimPrepareArgs = z.infer<typeof PluginBimPrepareArgs>
+
+/** Expected recipe/plan failures are diagnostics. No scene or library change occurs during prepare. */
+export const PluginBimPreparation = z.object({
+  ok: z.boolean(),
+  preparationId: id.optional(),
+  diagnostics: z.array(z.object({ path: z.string(), message: z.string() })),
+})
+export type PluginBimPreparation = z.infer<typeof PluginBimPreparation>
+export const PluginBimCreateArgs = z.object({ preparationId: id }).strict()
+
+/** Source IDs identify removed sketch spaces, not live handles. Successful storeys share one undo step.
+ * Failed storeys remain spaces. Cancellation rolls back the whole conversion. Persistence is queued
+ * through normal model commands; this result is not a durable server-save acknowledgement.
+ */
+export const PluginBimResult = z.object({
+  status: z.enum(["created", "partial", "cancelled", "unchanged"]),
+  convertedSpaceIds: z.array(z.string()),
+  created: z.array(ComponentHandle),
+  kept: z.array(z.object({ space: ComponentHandle, reason: z.string() })),
+})
+export type PluginBimResult = z.infer<typeof PluginBimResult>
+
+/** Agent-driven Sketch-to-BIM. Uses PG2 topology; never redraws routes or publishes library families. */
+export abstract class PluginDesignBimApi {
+  /** Read room adjacency and native conversion eligibility in the active proposal.
+   * @param options Optional explicit spaces; filters edges but keeps adjacent room metadata.
+   * @returns Rooms, directed boundaries in mm, eligibility and revision.
+   * @examplePrompt Inspect the rooms on each side of these sketch wall boundaries
+   */
+  abstract getContext(options?: PluginBimContextArgs): PluginApiReturn<PluginBimContext>
+
+  /** Stage a complete wall-construction assignment. A new prepare replaces this plugin's prior plan.
+   * @param plan Exact context revision, selected spaces, constructions and edge assignments.
+   * @returns Diagnostics or an opaque preparation ID, scoped to the caller and current project.
+   * @examplePrompt Validate wall layer assignments before converting sketch rooms to BIM
+   */
+  abstract prepare(plan: PluginBimPrepareArgs): PluginApiReturn<PluginBimPreparation>
+
+  /** Execute native Sketch-to-BIM. Revalidates scope, catalogue access and construction before mutation.
+   * Uses native progress/cancel controls and worker cancellation. Floors/roofs retain project defaults.
+   * @param preparationId ID returned by prepare. Consumed once; stale or foreign IDs throw PRECONDITION_FAILED.
+   * @returns Created component handles and explicit converted/kept outcomes, including partial success.
+   * @examplePrompt Convert these sketch rooms to BIM with wall layers chosen for each room boundary
+   */
+  abstract create(preparationId: string): PluginApiReturn<PluginBimResult>
+}

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

@@ -59,6 +59,8 @@ export abstract class PluginDesignBooleanApi {
    * boolean (CSG) subtraction that carves the tools' volume out of the target and
    * commits the remainder as a single undoable step.
    *
+   * Masses only. Slabs, floors and roofs take holes through `design.create.void`.
+   *
    * ORDER-SENSITIVE: the host seeds `[target, ...tools]`; index 0 is the arg brep,
    * the rest are tool breps. `deleted` includes the target AND every tool;
    * `created` is the remainder mass(es).

package/src/api/design/catalog.ts

@@ -0,0 +1,203 @@
+import * as z from "zod"
+import { ContourHandle, LineHandle, Vec3Handle } from "../../handles"
+import type { PluginApiReturn } from "../../types"
+import {
+  PluginFamilyDefinitionParameter,
+  PluginFamilyBundleSchema,
+} from "./family"
+import { NetworkFamilyContract } from "./networks"
+
+/** Exact saved family identity. A label or a selected Draw type is not an identity. */
+export const PluginSavedFamilyReference = z
+  .object({
+    id: z.string().min(1),
+    version: z.number().int().positive(),
+  })
+  .strict()
+export type PluginSavedFamilyReference = z.infer<
+  typeof PluginSavedFamilyReference
+>
+
+/** Public overrides: physical lengths use mm, angles use degrees. Omitted values retain defaults. */
+export const PluginFamilyValues = z.record(
+  z.string(),
+  z.union([z.number().finite(), z.string(), z.boolean()]),
+)
+export type PluginFamilyValues = z.infer<typeof PluginFamilyValues>
+
+/** Native construction uses a saved family or a project assembly token from the catalogue. */
+export const PluginConstructionType = z.union([
+  PluginSavedFamilyReference,
+  z.string().min(1),
+])
+export type PluginConstructionType = z.infer<typeof PluginConstructionType>
+
+/** Family owns its layers/section. Geometry owns the footprint/axis; it is never a values override. */
+export const PluginFamilyPlacement = z
+  .object({
+    type: PluginConstructionType,
+    values: PluginFamilyValues.optional(),
+  })
+  .strict()
+export type PluginFamilyPlacement = z.infer<typeof PluginFamilyPlacement>
+
+/** Sparse native family edit. Omitted type keeps the component's exact saved reference. */
+export const PluginFamilyUpdates = PluginFamilyPlacement.partial().refine(
+  (updates) => updates.type !== undefined || updates.values !== undefined,
+  { message: "Supply a type or parameter values" },
+)
+export type PluginFamilyUpdates = z.infer<typeof PluginFamilyUpdates>
+
+export const PluginFamilyFloorOptions = PluginFamilyPlacement.extend({
+  position: Vec3Handle.optional(),
+})
+export type PluginFamilyFloorOptions = z.infer<typeof PluginFamilyFloorOptions>
+export const PluginFamilySlabOptions = PluginFamilyPlacement.extend({
+  direction: z.enum(["up", "down"]).optional(),
+})
+export type PluginFamilySlabOptions = z.infer<typeof PluginFamilySlabOptions>
+export const PluginFamilyCeilingOptions = PluginFamilyPlacement.extend({
+  heightFromFloor: z.number().finite().optional(),
+})
+export type PluginFamilyCeilingOptions = z.infer<
+  typeof PluginFamilyCeilingOptions
+>
+export const PluginFamilyContourArgs = z.object({
+  contour: ContourHandle,
+  options: PluginFamilyPlacement,
+})
+export const PluginFamilyAxisArgs = z.object({
+  axis: LineHandle,
+  options: PluginFamilyPlacement,
+})
+
+/** Inventory includes architectural recipes, ordinary PCs, and the existing placement libraries. */
+export const PluginCatalogKind = z.enum([
+  "wall",
+  "floor",
+  "slab",
+  "roof",
+  "ceiling",
+  "beam",
+  "column",
+  "component",
+  "door",
+  "window",
+  "furniture",
+])
+export type PluginCatalogKind = z.infer<typeof PluginCatalogKind>
+export const PluginCatalogReference = z.union([
+  PluginSavedFamilyReference,
+  // Project assemblies retain kind:name; asset tokens retain the underlying library identity.
+  z.string().min(1),
+])
+export type PluginCatalogReference = z.infer<typeof PluginCatalogReference>
+
+/** Read-only capability record. Availability is checked again on every mutation. */
+export const PluginCatalogEntry = z.object({
+  reference: PluginCatalogReference,
+  label: z.string(),
+  kind: PluginCatalogKind,
+  source: z.enum(["native", "revit", "project", "asset"]),
+  createMethods: z.array(z.string()),
+  updateMethods: z.array(z.string()),
+  requirements: z.array(z.string()),
+  unsupportedReason: z.string().optional(),
+  parameters: z.array(PluginFamilyDefinitionParameter).optional(),
+  /** Parameter keys owned by native placement geometry, never accepted as values overrides. */
+  geometryParameters: z.array(z.string()),
+  network: NetworkFamilyContract.optional(),
+  /** get() includes the native wall recipe without opening a Family Studio draft.
+   * Bare recipe lengths use SU; parameter metadata and public values overrides use mm.
+   */
+  construction: PluginFamilyBundleSchema.optional(),
+})
+export type PluginCatalogEntry = z.infer<typeof PluginCatalogEntry>
+export const PluginCatalogListArgs = z.object({
+  kind: PluginCatalogKind.optional(),
+})
+export const PluginCatalogGetArgs = z.object({
+  reference: PluginCatalogReference,
+})
+
+/** Search metadata is extensible. A slash separates category path segments. */
+export const PluginCatalogSearchArgs = z
+  .object({
+    query: z.string().trim().max(200).optional(),
+    category: z.string().trim().max(1000).optional(),
+    limit: z.number().int().min(1).max(50).optional(),
+    cursor: z.string().min(1).max(16384).optional(),
+  })
+  .strict()
+export type PluginCatalogSearchArgs = z.infer<typeof PluginCatalogSearchArgs>
+
+/** Browse one hierarchy level without enumerating families or fetching recipe bodies. */
+export const PluginCatalogListCategoriesArgs = z
+  .object({
+    parent: z.string().trim().max(1000).optional(),
+    after: z.string().max(1000).optional(),
+    limit: z.number().int().min(1).max(100).optional(),
+  })
+  .strict()
+export type PluginCatalogListCategoriesArgs = z.infer<
+  typeof PluginCatalogListCategoriesArgs
+>
+
+/** Metadata only: the category does not establish placement capabilities or recipe validity. */
+export const PluginCatalogCategory = z.object({
+  categoryPath: z.array(z.string()).min(1),
+  hasChildren: z.boolean(),
+})
+export type PluginCatalogCategory = z.infer<typeof PluginCatalogCategory>
+
+/** Metadata only. Read get(reference) to validate a selected family and inspect placement methods. */
+export const PluginCatalogSummary = z.object({
+  reference: PluginCatalogReference,
+  label: z.string(),
+  categoryPath: z.array(z.string()),
+  description: z.string(),
+  source: PluginCatalogEntry.shape.source,
+})
+export type PluginCatalogSummary = z.infer<typeof PluginCatalogSummary>
+export const PluginCatalogSearchResult = z.object({
+  items: z.array(PluginCatalogSummary),
+  nextCursor: z.string().nullable(),
+})
+export type PluginCatalogSearchResult = z.infer<
+  typeof PluginCatalogSearchResult
+>
+
+/** Shared read surface over existing libraries. Does not publish, register, or place definitions. */
+export abstract class PluginDesignCatalogApi {
+  /**
+   * Discover categories from accessible saved families and current project constructions.
+   * Omit parent for roots; pass a slash-separated returned path for its direct children.
+   * This metadata read does not fetch recipes, include unsaved drafts or legacy mesh inventories,
+   * or establish capabilities. Use search then get before placement. Names retain their case.
+   * @param args Parent path, exclusive after-name, and page limit (default 50, maximum 100).
+   * For another page at the same parent, pass the last item's final categoryPath segment as after.
+   * @returns Categories in Unicode code-point order, with descendant flags. Stop when a page has
+   * fewer than limit items. Live pagination is not a snapshot. Metadata-service failures reject.
+   */
+  abstract listCategories(
+    args?: PluginCatalogListCategoriesArgs,
+  ): PluginApiReturn<PluginCatalogCategory[]>
+  /**
+   * Search accessible saved-family and project-construction metadata without downloading recipes.
+   * Categories are data, not an SDK enum. Legacy mesh inventories and unsaved drafts are excluded.
+   * Inspect selected references with get before placement; a search match does not prove validity
+   * or supported behavior. Pagination reads live data, not a snapshot. Failures reject.
+   * @param args Text/category filters, page limit (default 20, maximum 50), and opaque cursor.
+   * @returns Compact metadata and continuation. Continue until nextCursor is null or a suitable
+   * family is found. Concurrent changes can leave an empty page with continuation.
+   */
+  abstract search(
+    args?: PluginCatalogSearchArgs,
+  ): PluginApiReturn<PluginCatalogSearchResult>
+  /** @param kind Optional element filter. @returns Accessible entries and their supported API paths. */
+  abstract list(kind?: PluginCatalogKind): PluginApiReturn<PluginCatalogEntry[]>
+  /** @param reference Exact reference from search or list. @returns The current entry, or null when unavailable. */
+  abstract get(
+    reference: PluginCatalogReference,
+  ): PluginApiReturn<PluginCatalogEntry | null>
+}

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

@@ -1,6 +1,13 @@
 import * as z from "zod"
-import { ContourHandle, ProfileHandle, Vec3Handle } from "../../../handles"
+import {
+  ComponentHandle,
+  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 +95,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 +103,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 +152,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 +193,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({
@@ -252,3 +264,31 @@ export const PluginCreateFurnitureItems = z
 export type PluginCreateFurnitureItems = z.infer<
   typeof PluginCreateFurnitureItems
 >
+
+// ---------------------------------------------------------------------------
+// voids
+// ---------------------------------------------------------------------------
+
+/**
+ * One void to cut via {@linkcode PluginDesignCreateApi.voids} — the same fields as
+ * {@linkcode PluginDesignCreateApi.void}. Rejects unknown fields.
+ *
+ * | Property | Type | Description |
+ * | --- | --- | --- |
+ * | `host` | {@linkcode ComponentHandle} | The slab, floor, roof or ceiling to cut through. Not a wall. |
+ * | `outline` | {@linkcode ProfileHandle} | Closed, flat plan outline in world SU (all points at one height). That height is ignored: it is dropped straight onto the host's top face. |
+ */
+export const PluginCreateVoidItem = z
+  .object({
+    host: ComponentHandle,
+    outline: ProfileHandle,
+  })
+  .strict()
+export type PluginCreateVoidItem = z.infer<typeof PluginCreateVoidItem>
+
+/** The `items` array of {@linkcode PluginDesignCreateApi.voids} (1…1000; the host takes at most 200, 50 per host). */
+export const PluginCreateVoidItems = z
+  .array(PluginCreateVoidItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateVoidItems = z.infer<typeof PluginCreateVoidItems>