@snaptrude/plugin-core 0.9.16 → 0.9.18-edgesetbacks-20261021.1

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

@@ -1,254 +1,294 @@
-import * as z from "zod"
-import { ContourHandle, ProfileHandle, Vec3Handle } from "../../../handles"
-import { PluginOpeningBaseOptions } from "./opening-fields"
-
-/**
- * Maximum items per bulk `design.create.*` call. A bounded request keeps
- * validation, command capture and rollback work finite; split a larger import
- * into separate awaited batches, each with its own undo entry.
- */
-export const PLUGIN_CREATE_BATCH_LIMIT = 1000
-
-// ---------------------------------------------------------------------------
-// wall top profile (raked / gabled walls)
-// ---------------------------------------------------------------------------
-
-/**
- * One break point of a wall's top edge — see {@linkcode PluginWallTopProfile}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `along` | `number` | Position along the wall centerline as a fraction: `0` = start of the curve, `1` = end |
- * | `height` | `number` | Top height above the wall base at that point (Snaptrude units, > 0) |
- */
-export const PluginWallTopProfilePoint = z.object({
-  along: z.number().min(0).max(1),
-  height: z.number().positive(),
-})
-export type PluginWallTopProfilePoint = z.infer<
-  typeof PluginWallTopProfilePoint
->
-
-/**
- * The top edge of ONE wall as a polyline over its centerline: at least two
- * points, `along` strictly increasing from `0` (curve start) to `1` (curve end),
- * straight segments between them. Two points give a single slope (a raked
- * wall), three give a gable, more give any stepped or folded ridge. Heights are
- * measured from the wall base, like `height`. Both long faces follow the same
- * profile, so the top stays a set of flat faces and the wall keeps its thickness
- * end to end.
- *
- * Only straight centerlines take a top profile (an arc curve with one is
- * rejected). A wall built this way is a real Wall — doors and windows host on
- * it, corners mitre, quantities and Revit export read its geometry — but it is
- * **non-parametric**: the parametric wall graph does not rebuild it, so a later
- * move of a neighbour does not re-mitre its corner, exactly like a wall whose
- * top edge was dragged by hand. `design.update.wall({ height })` scales it
- * proportionally.
- */
-export const PluginWallTopProfile = z
-  .array(PluginWallTopProfilePoint)
-  .min(2)
-  .superRefine((points, ctx) => {
-    if (points[0].along !== 0) {
-      ctx.addIssue({
-        code: "custom",
-        message: "topProfile must start at along = 0",
-      })
-    }
-    if (points[points.length - 1].along !== 1) {
-      ctx.addIssue({
-        code: "custom",
-        message: "topProfile must end at along = 1",
-      })
-    }
-    for (let i = 1; i < points.length; i++) {
-      if (points[i].along <= points[i - 1].along) {
-        ctx.addIssue({
-          code: "custom",
-          message:
-            "topProfile points must be in strictly increasing `along` order",
-        })
-        break
-      }
-    }
-  })
-export type PluginWallTopProfile = z.infer<typeof PluginWallTopProfile>
-
-// ---------------------------------------------------------------------------
-// wallRuns
-// ---------------------------------------------------------------------------
-
-/**
- * One wall run to create via {@linkcode PluginDesignCreateApi.wallRuns} — the
- * same inputs as {@linkcode PluginDesignCreateApi.walls}, one run per item.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `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) |
- * | `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) |
- */
-export const PluginCreateWallRunItem = z.object({
-  profile: ProfileHandle,
-  height: z.number().optional(),
-  thickness: z.number().optional(),
-  wallType: z.string().min(1).optional(),
-  storey: z.number().int().optional(),
-  topProfiles: z.array(PluginWallTopProfile.nullable()).optional(),
-})
-export type PluginCreateWallRunItem = z.infer<typeof PluginCreateWallRunItem>
-
-/** The `items` array of {@linkcode PluginDesignCreateApi.wallRuns} (1…1000). */
-export const PluginCreateWallRunItems = z
-  .array(PluginCreateWallRunItem)
-  .min(1)
-  .max(PLUGIN_CREATE_BATCH_LIMIT)
-export type PluginCreateWallRunItems = z.infer<typeof PluginCreateWallRunItems>
-
-// ---------------------------------------------------------------------------
-// floors
-// ---------------------------------------------------------------------------
-
-/**
- * One floor to create via {@linkcode PluginDesignCreateApi.floors} — the same
- * footprint-extrude inputs as {@linkcode PluginDesignCreateApi.floor}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `contour` | {@linkcode ContourHandle} | Footprint (outer profile + holes) |
- * | `thickness` | `number` | Floor thickness (Snaptrude units, > 0) |
- * | `position` | {@linkcode Vec3Handle}? | Offset from origin (default origin) |
- */
-export const PluginCreateFloorItem = z.object({
-  contour: ContourHandle,
-  thickness: z.number(),
-  position: Vec3Handle.optional(),
-})
-export type PluginCreateFloorItem = z.infer<typeof PluginCreateFloorItem>
-
-/** The `items` array of {@linkcode PluginDesignCreateApi.floors} (1…1000). */
-export const PluginCreateFloorItems = z
-  .array(PluginCreateFloorItem)
-  .min(1)
-  .max(PLUGIN_CREATE_BATCH_LIMIT)
-export type PluginCreateFloorItems = z.infer<typeof PluginCreateFloorItems>
-
-// ---------------------------------------------------------------------------
-// doors / windows
-// ---------------------------------------------------------------------------
-
-/**
- * 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.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
- * | `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) |
- * | `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) |
- */
-export const PluginCreateDoorItem = z
-  .object({ ...PluginOpeningBaseOptions })
-  .strict()
-export type PluginCreateDoorItem = z.infer<typeof PluginCreateDoorItem>
-
-/** The `items` array of {@linkcode PluginDesignCreateApi.doors} (1…1000). */
-export const PluginCreateDoorItems = z
-  .array(PluginCreateDoorItem)
-  .min(1)
-  .max(PLUGIN_CREATE_BATCH_LIMIT)
-export type PluginCreateDoorItems = z.infer<typeof PluginCreateDoorItems>
-
-/**
- * One window to place via {@linkcode PluginDesignCreateApi.windows} — the same
- * fields as a `"window"` {@linkcode PluginDesignCreateOpeningOptions}.
- * `sillHeight` is a nonnegative Snaptrude-unit distance from the host wall's
- * base to the BOTTOM of the window, not to its center. `facing` and `hinge`
- * are WORLD POINTS, not directions: `facing` on the side of the wall the
- * window opens to, `hinge` near the jamb it is hinged on. Rejects unknown
- * fields.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
- * | `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) |
- * | `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) |
- */
-export const PluginCreateWindowItem = z
-  .object({
-    ...PluginOpeningBaseOptions,
-    sillHeight: z.number().finite().nonnegative().optional(),
-  })
-  .strict()
-export type PluginCreateWindowItem = z.infer<typeof PluginCreateWindowItem>
-
-/** The `items` array of {@linkcode PluginDesignCreateApi.windows} (1…1000). */
-export const PluginCreateWindowItems = z
-  .array(PluginCreateWindowItem)
-  .min(1)
-  .max(PLUGIN_CREATE_BATCH_LIMIT)
-export type PluginCreateWindowItems = z.infer<typeof PluginCreateWindowItems>
-
-// ---------------------------------------------------------------------------
-// furnitureItems
-// ---------------------------------------------------------------------------
-
-/**
- * One furniture instance to place via
- * {@linkcode PluginDesignCreateApi.furnitureItems} — the same inputs as
- * {@linkcode PluginDesignCreateApi.furniture} minus `createNewSourceMesh`: in a
- * batch the host owns source-mesh persistence (a source is recorded once per
- * call, however many items reuse it).
- *
- * `position.y` is the REST elevation: the item is grounded so its bounding-box
- * base sits exactly at `position.y` (the same surface-flush contract as
- * interactive drag-drop) — pass the floor/storey elevation to stand furniture
- * on it; never add half the item's height yourself.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
- * | `position` | {@linkcode Vec3Handle} | Absolute world placement point (`y` = rest elevation) |
- * | `label` | `string`? | Instance name and readable label (default auto `${name}Ins${n}`) |
- * | `angleInDegrees` | `number`? | Rotation about the vertical axis, in degrees (default unrotated) |
- */
-export const PluginCreateFurnitureItem = z.object({
-  catalogId: z.string().min(1),
-  position: Vec3Handle,
-  label: z.string().optional(),
-  angleInDegrees: z.number().optional(),
-})
-export type PluginCreateFurnitureItem = z.infer<
-  typeof PluginCreateFurnitureItem
->
-
-/**
- * The `items` array of {@linkcode PluginDesignCreateApi.furnitureItems}
- * (1…1000).
- */
-export const PluginCreateFurnitureItems = z
-  .array(PluginCreateFurnitureItem)
-  .min(1)
-  .max(PLUGIN_CREATE_BATCH_LIMIT)
-export type PluginCreateFurnitureItems = z.infer<
-  typeof PluginCreateFurnitureItems
->
+import * as z from "zod"
+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
+ * validation, command capture and rollback work finite; split a larger import
+ * into separate awaited batches, each with its own undo entry.
+ */
+export const PLUGIN_CREATE_BATCH_LIMIT = 1000
+
+// ---------------------------------------------------------------------------
+// wall top profile (raked / gabled walls)
+// ---------------------------------------------------------------------------
+
+/**
+ * One break point of a wall's top edge — see {@linkcode PluginWallTopProfile}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `along` | `number` | Position along the wall centerline as a fraction: `0` = start of the curve, `1` = end |
+ * | `height` | `number` | Top height above the wall base at that point (Snaptrude units, > 0) |
+ */
+export const PluginWallTopProfilePoint = z.object({
+  along: z.number().min(0).max(1),
+  height: z.number().positive(),
+})
+export type PluginWallTopProfilePoint = z.infer<
+  typeof PluginWallTopProfilePoint
+>
+
+/**
+ * The top edge of ONE wall as a polyline over its centerline: at least two
+ * points, `along` strictly increasing from `0` (curve start) to `1` (curve end),
+ * straight segments between them. Two points give a single slope (a raked
+ * wall), three give a gable, more give any stepped or folded ridge. Heights are
+ * measured from the wall base, like `height`. Both long faces follow the same
+ * profile, so the top stays a set of flat faces and the wall keeps its thickness
+ * end to end.
+ *
+ * Only straight centerlines take a top profile (an arc curve with one is
+ * rejected). A wall built this way is a real Wall — doors and windows host on
+ * it, corners mitre, quantities and Revit export read its geometry — but it is
+ * **non-parametric**: the parametric wall graph does not rebuild it, so a later
+ * move of a neighbour does not re-mitre its corner, exactly like a wall whose
+ * top edge was dragged by hand. `design.update.wall({ height })` scales it
+ * proportionally.
+ */
+export const PluginWallTopProfile = z
+  .array(PluginWallTopProfilePoint)
+  .min(2)
+  .superRefine((points, ctx) => {
+    if (points[0].along !== 0) {
+      ctx.addIssue({
+        code: "custom",
+        message: "topProfile must start at along = 0",
+      })
+    }
+    if (points[points.length - 1].along !== 1) {
+      ctx.addIssue({
+        code: "custom",
+        message: "topProfile must end at along = 1",
+      })
+    }
+    for (let i = 1; i < points.length; i++) {
+      if (points[i].along <= points[i - 1].along) {
+        ctx.addIssue({
+          code: "custom",
+          message:
+            "topProfile points must be in strictly increasing `along` order",
+        })
+        break
+      }
+    }
+  })
+export type PluginWallTopProfile = z.infer<typeof PluginWallTopProfile>
+
+// ---------------------------------------------------------------------------
+// wallRuns
+// ---------------------------------------------------------------------------
+
+/**
+ * One wall run to create via {@linkcode PluginDesignCreateApi.wallRuns} — the
+ * same inputs as {@linkcode PluginDesignCreateApi.walls}, one run per item.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `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` | {@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) |
+ */
+export const PluginCreateWallRunItem = z.object({
+  profile: ProfileHandle,
+  height: z.number().optional(),
+  thickness: z.number().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>
+
+/** The `items` array of {@linkcode PluginDesignCreateApi.wallRuns} (1…1000). */
+export const PluginCreateWallRunItems = z
+  .array(PluginCreateWallRunItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateWallRunItems = z.infer<typeof PluginCreateWallRunItems>
+
+// ---------------------------------------------------------------------------
+// floors
+// ---------------------------------------------------------------------------
+
+/**
+ * One floor to create via {@linkcode PluginDesignCreateApi.floors} — the same
+ * footprint-extrude inputs as {@linkcode PluginDesignCreateApi.floor}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | Footprint (outer profile + holes) |
+ * | `thickness` | `number` | Floor thickness (Snaptrude units, > 0) |
+ * | `position` | {@linkcode Vec3Handle}? | Offset from origin (default origin) |
+ */
+export const PluginCreateFloorItem = z.object({
+  contour: ContourHandle,
+  thickness: z.number(),
+  position: Vec3Handle.optional(),
+})
+export type PluginCreateFloorItem = z.infer<typeof PluginCreateFloorItem>
+
+/** The `items` array of {@linkcode PluginDesignCreateApi.floors} (1…1000). */
+export const PluginCreateFloorItems = z
+  .array(PluginCreateFloorItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateFloorItems = z.infer<typeof PluginCreateFloorItems>
+
+// ---------------------------------------------------------------------------
+// doors / windows
+// ---------------------------------------------------------------------------
+
+/**
+ * One door to place via {@linkcode PluginDesignCreateApi.doors} — the same
+ * 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 |
+ * |---|---|---|
+ * | `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 hinged jamb; requires hand control |
+ * | `label` | `string`? | Instance name (optional) |
+ * | `width` | `number`? | Declared width parameter (SU, > 0), not evaluated hole width |
+ * | `height` | `number`? | Declared height parameter (SU, > 0) |
+ */
+export const PluginCreateDoorItem = z
+  .object({ ...PluginOpeningBaseOptions })
+  .strict()
+export type PluginCreateDoorItem = z.infer<typeof PluginCreateDoorItem>
+
+/** The `items` array of {@linkcode PluginDesignCreateApi.doors} (1…1000). */
+export const PluginCreateDoorItems = z
+  .array(PluginCreateDoorItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateDoorItems = z.infer<typeof PluginCreateDoorItems>
+
+/**
+ * One window to place via {@linkcode PluginDesignCreateApi.windows} — the same
+ * fields as a `"window"` {@linkcode PluginDesignCreateOpeningOptions}.
+ * `sillHeight` is a nonnegative Snaptrude-unit distance from the host wall's
+ * base to the BOTTOM of the window, not to its center. `facing` and `hinge`
+ * are WORLD POINTS, not directions: `facing` on the side of the wall the
+ * window opens to, `hinge` near the jamb it is hinged on. Rejects unknown
+ * fields.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `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 hinged jamb; requires hand control |
+ * | `label` | `string`? | Instance name (optional) |
+ * | `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({
+    ...PluginOpeningBaseOptions,
+    sillHeight: z.number().finite().nonnegative().optional(),
+  })
+  .strict()
+export type PluginCreateWindowItem = z.infer<typeof PluginCreateWindowItem>
+
+/** The `items` array of {@linkcode PluginDesignCreateApi.windows} (1…1000). */
+export const PluginCreateWindowItems = z
+  .array(PluginCreateWindowItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateWindowItems = z.infer<typeof PluginCreateWindowItems>
+
+// ---------------------------------------------------------------------------
+// furnitureItems
+// ---------------------------------------------------------------------------
+
+/**
+ * One furniture instance to place via
+ * {@linkcode PluginDesignCreateApi.furnitureItems} — the same inputs as
+ * {@linkcode PluginDesignCreateApi.furniture} minus `createNewSourceMesh`: in a
+ * batch the host owns source-mesh persistence (a source is recorded once per
+ * call, however many items reuse it).
+ *
+ * `position.y` is the REST elevation: the item is grounded so its bounding-box
+ * base sits exactly at `position.y` (the same surface-flush contract as
+ * interactive drag-drop) — pass the floor/storey elevation to stand furniture
+ * on it; never add half the item's height yourself.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `position` | {@linkcode Vec3Handle} | Absolute world placement point (`y` = rest elevation) |
+ * | `label` | `string`? | Instance name and readable label (default auto `${name}Ins${n}`) |
+ * | `angleInDegrees` | `number`? | Rotation about the vertical axis, in degrees (default unrotated) |
+ */
+export const PluginCreateFurnitureItem = z.object({
+  catalogId: z.string().min(1),
+  position: Vec3Handle,
+  label: z.string().optional(),
+  angleInDegrees: z.number().optional(),
+})
+export type PluginCreateFurnitureItem = z.infer<
+  typeof PluginCreateFurnitureItem
+>
+
+/**
+ * The `items` array of {@linkcode PluginDesignCreateApi.furnitureItems}
+ * (1…1000).
+ */
+export const PluginCreateFurnitureItems = z
+  .array(PluginCreateFurnitureItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+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>