@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

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

@@ -0,0 +1,164 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+
+/**
+ * Unit-type queries and conversion.
+ *
+ * Snaptrude stores all geometry in an internal `babylon` unit. These methods
+ * read the available unit types, the internal (`babylon`) type, and the current
+ * project type; set the current project type; and convert values between any two
+ * unit types.
+ *
+ * Accessed via `snaptrude.core.units`.
+ */
+export abstract class PluginUnitsApi {
+  constructor() {}
+
+  /**
+   * List the selectable real-world unit types (excludes the internal `babylon`
+   * storage type, which is read via {@linkcode PluginUnitsApi.getBabylonType}).
+   *
+   * @examplePrompt What units can I use in this project?
+   * @examplePrompt List all the available measurement units
+   * @examplePrompt Which unit systems does Snaptrude support?
+   * @examplePrompt Show the unit options I could switch the model to
+   *
+   * # Example
+   * ```ts
+   * const types = await snaptrude.core.units.listTypes()
+   * console.log(types) // ["meters", "feet-inches", "inches", ...]
+   * ```
+   */
+  public abstract listTypes(): PluginApiReturn<PUnitType[]>
+
+  /**
+   * Get the internal storage unit type that all geometry is kept in — always
+   * `"babylon"` — for use as one side of a {@linkcode PluginUnitsApi.convert} call.
+   *
+   * @examplePrompt What unit does Snaptrude store geometry in internally?
+   * @examplePrompt Get the internal babylon unit type
+   * @examplePrompt Which unit are raw model coordinates saved in?
+   *
+   * # Example
+   * ```ts
+   * const babylon = await snaptrude.core.units.getBabylonType() // "babylon"
+   * const meters = await snaptrude.core.units.convert(10, babylon, "meters")
+   * ```
+   */
+  public abstract getBabylonType(): PluginApiReturn<PUnitType>
+
+  /**
+   * Get the current project's unit type — the unit lengths are displayed and
+   * entered in. Paired with {@linkcode PluginUnitsApi.setType}.
+   *
+   * @examplePrompt What units is this project using?
+   * @examplePrompt Are we working in metric or imperial?
+   * @examplePrompt Check the current measurement unit of the model
+   * @examplePrompt Is the file set to millimetres or feet and inches?
+   *
+   * # Example
+   * ```ts
+   * const type = await snaptrude.core.units.getType()
+   * console.log(type) // e.g. "millimeters"
+   * ```
+   */
+  public abstract getType(): PluginApiReturn<PUnitType>
+
+  /**
+   * Set the current project's unit type. Paired with {@linkcode PluginUnitsApi.getType}.
+   *
+   * @param type - The unit type to set as the project unit.
+   * @returns `true` if applied; `false` if `type` is not a settable project unit
+   *   (e.g. `kilometers`, `miles`, `babylon`).
+   *
+   * @examplePrompt Change the project units to millimeters
+   * @examplePrompt Switch this model to feet and inches
+   * @examplePrompt Set the working units to metric
+   * @examplePrompt Make the drawing use centimetres instead of meters
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.units.setType("meters")
+   * ```
+   */
+  public abstract setType(type: PUnitType): PluginApiReturn<boolean>
+
+  /**
+   * Convert a value between two unit types.
+   *
+   * @param value - The numeric value to convert.
+   * @param from - Source unit type.
+   * @param to - Target unit type.
+   * @param degree - (Optional) 1 = length, 2 = area, 3 = volume. Defaults to 1.
+   * @returns The converted numeric value.
+   *
+   * @examplePrompt Convert 5 meters to feet and inches
+   * @examplePrompt How many millimetres is 12 feet?
+   * @examplePrompt Change this area from internal units to square metres
+   * @examplePrompt Turn 2500 mm into meters
+   * @examplePrompt Convert a volume value from babylon units to cubic feet
+   *
+   * # Example
+   * ```ts
+   * // 5 meters → internal babylon units
+   * const b = await snaptrude.core.units.convert(5, "meters", "babylon")
+   * // an internal area → square metres
+   * const m2 = await snaptrude.core.units.convert(area, "babylon", "meters", 2)
+   * ```
+   */
+  public abstract convert(
+    value: number,
+    from: PUnitType,
+    to: PUnitType,
+    degree?: number,
+  ): PluginApiReturn<number>
+}
+
+/**
+ * Supported unit types. `babylon` is Snaptrude's internal storage unit; the rest
+ * are real-world units. Mirrors the engine `Converter.UNITS` vocabulary.
+ */
+export const PUnitType = z.enum([
+  "meters",
+  "feet-inches",
+  "inches",
+  "centimeters",
+  "millimeters",
+  "kilometers",
+  "miles",
+  "babylon",
+])
+
+export type PUnitType = z.infer<typeof PUnitType>
+
+/**
+ * Arguments for {@linkcode PluginUnitsApi.setType}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `type` | {@linkcode PUnitType} | The unit type to set as the project unit |
+ */
+export const PluginUnitsSetTypeArgs = z.object({
+  type: PUnitType,
+})
+
+export type PluginUnitsSetTypeArgs = z.infer<typeof PluginUnitsSetTypeArgs>
+
+/**
+ * Arguments for {@linkcode PluginUnitsApi.convert}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `value` | `number` | The numeric value to convert |
+ * | `from` | {@linkcode PUnitType} | Source unit type |
+ * | `to` | {@linkcode PUnitType} | Target unit type |
+ * | `degree` | `1 \| 2 \| 3` | (Optional) 1 = length, 2 = area, 3 = volume. Defaults to 1 |
+ */
+export const PluginUnitsConvertArgs = z.object({
+  value: z.number(),
+  from: PUnitType,
+  to: PUnitType,
+  degree: z.number().int().min(1).max(3).optional(),
+})
+
+export type PluginUnitsConvertArgs = z.infer<typeof PluginUnitsConvertArgs>

package/src/api/core/user.ts

@@ -0,0 +1,46 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * User locale.
+ *
+ * Read the viewer's timezone and language — for date/number formatting and
+ * localized labels. This is locale only: NO precise geolocation, no IP, no
+ * account identity. Accessed via `snaptrude.core.user`.
+ */
+export abstract class PluginUserApi {
+  constructor() {}
+
+  /**
+   * Get the viewer's locale: IANA timezone and BCP-47 language tag, resolved
+   * from the browser (`Intl.DateTimeFormat().resolvedOptions().timeZone` and
+   * `navigator.language`). Locale only — no precise location.
+   *
+   * @returns `{ timezone, language }` — e.g. `{ timezone: "Asia/Kolkata", language: "en-US" }`.
+   *
+   * @examplePrompt What timezone is the user in?
+   * @examplePrompt Get the viewer's language for localized labels
+   * @examplePrompt Format the report date in the user's local timezone
+   * @examplePrompt Which locale should I use for this plugin's UI?
+   *
+   * # Example
+   * ```ts
+   * const { timezone, language } = await snaptrude.core.user.getLocale()
+   * ```
+   */
+  public abstract getLocale(): PluginApiReturn<PluginUserLocale>
+}
+
+/**
+ * The viewer's locale.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `timezone` | `string` | IANA timezone id (e.g. `"Asia/Kolkata"`) |
+ * | `language` | `string` | BCP-47 language tag (e.g. `"en-US"`) |
+ */
+export const PluginUserLocale = z.object({
+  timezone: z.string(),
+  language: z.string(),
+})
+export type PluginUserLocale = z.infer<typeof PluginUserLocale>

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

@@ -0,0 +1,51 @@
+import { PluginApiReturn } from "../../../types"
+
+/**
+ * Camera zoom controls.
+ *
+ * Frame the viewport camera onto scene geometry — mirrors the canvas zoom menu
+ * ("Zoom extents" / "Zoom to selection"). Accessed via `snaptrude.core.zoom`.
+ */
+export abstract class PluginZoomApi {
+  constructor() {}
+
+  /**
+   * Zoom (fit) the camera to all geometry in the scene — the "zoom extents" action.
+   *
+   * @returns `true` once the camera has been framed to the scene.
+   *
+   * @examplePrompt Zoom out so I can see the whole model
+   * @examplePrompt Fit everything in the view
+   * @examplePrompt Frame the entire building in the viewport
+   * @examplePrompt Do a zoom extents on the canvas
+   * @examplePrompt Show me the full scene
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.zoom.extents()
+   * ```
+   *
+   * @deprecated Use `core.camera.zoomExtents`
+   */
+  public abstract extents(): PluginApiReturn<boolean>
+
+  /**
+   * Zoom (fit) the camera to the current selection.
+   *
+   * @returns `true` if there was a selection to frame; `false` if nothing is
+   *   selected (no-op).
+   *
+   * @examplePrompt Zoom in on what I have selected
+   * @examplePrompt Frame the selected walls in the view
+   * @examplePrompt Focus the camera on my current selection
+   * @examplePrompt Fit the view to the selected room
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.zoom.selection()
+   * ```
+   *
+   * @deprecated Use `core.camera.zoomSelection`
+   */
+  public abstract selection(): PluginApiReturn<boolean>
+}

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

@@ -0,0 +1,179 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle, Vec3Handle } from "../../../handles"
+import { BooleanOutcome } from "../shared"
+
+/**
+ * `snaptrude.design.boolean` — OpenCascade CSG on scene masses/spaces.
+ *
+ * Every method **commits** the operation as one undoable step (engine `run()`
+ * queues create/delete/group/dimension commands, `execute()` runs them through
+ * `CommandManager`) and returns the committed {@linkcode BooleanOutcome}. Failures
+ * **throw** (RPC rejects) — no `Result<>` monad crosses the boundary.
+ *
+ * Eligibility (all inputs): a `Mass` that is a room OR a DEPARTMENT, has a brep, is
+ * unlocked (mesh + bucket), visible, and NOT in a parametric-copy group; the whole
+ * set must be all-planar OR all-non-planar; **≥2** components; all inputs share one
+ * group or are ungrouped; inputs must be adjacent/overlapping.
+ *
+ * `design.boolean.subtract` is a **CSG geometry delete** — distinct from
+ * `design.delete.entities` (hard entity removal) and `design.erase.edge`
+ * (adjacency-edge topology op).
+ *
+ * TRANSPORT: positional args per method.
+ */
+export abstract class PluginDesignBooleanApi {
+  constructor() {}
+
+  /**
+   * Fuse two or more masses into a single combined mass (`A ∪ B ∪ …`) — a boolean
+   * (CSG) union that merges the adjacent or overlapping inputs into one solid,
+   * committed as a single undoable step. Order-independent.
+   * @param components - The ≥2 entities to fuse (order-independent)
+   * @param options - Optional output offset — {@linkcode BooleanOptions}
+   * @returns The committed CSG delta — {@linkcode BooleanOutcome}
+   * @throws if inputs are ineligible, disjoint, non-manifold when joined, span
+   *   different groups, or the CSG yields no / invalid geometry.
+   *
+   * @examplePrompt Merge these two masses into one
+   * @examplePrompt Union the selected volumes into a single mass
+   * @examplePrompt Combine the overlapping rooms into one shape
+   * @examplePrompt Join the tower and podium blocks together
+   * @examplePrompt Fuse all the selected massing blocks into a single solid
+   *
+   * # Example
+   * ```ts
+   * // Fuse the overlapping massing blocks on the ground storey into one solid
+   * const masses = await snaptrude.design.query.listMasses({ storeys: [1] })
+   * const { created, deleted } = await snaptrude.design.boolean.union(masses)
+   * console.log("created", created.length, "mass; consumed", deleted.length)
+   * ```
+   */
+  public abstract union(
+    components: ComponentHandle[],
+    options?: BooleanOptions,
+  ): PluginApiReturn<BooleanOutcome>
+
+  /**
+   * Cut one or more tool masses out of a target mass (`target − ⋃tools`) — a
+   * boolean (CSG) subtraction that carves the tools' volume out of the target and
+   * commits the remainder as a single undoable step.
+   *
+   * 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).
+   * @param target - The entity subtracted FROM (arg brep)
+   * @param tools - The ≥1 entities subtracted (tool breps)
+   * @param options - Optional output offset — {@linkcode BooleanOptions}
+   * @returns The committed CSG delta — {@linkcode BooleanOutcome}
+   * @throws as {@linkcode union}; a `NoResult` here carries the "select the target
+   *   object first" hint from the engine.
+   *
+   * @examplePrompt Cut this shape out of the bigger mass
+   * @examplePrompt Subtract the cylinder from the building volume
+   * @examplePrompt Punch an opening through this block using the small box
+   * @examplePrompt Carve the courtyard volume out of the main massing
+   * @examplePrompt Remove the overlapping part of mass B from mass A
+   *
+   * # Example
+   * ```ts
+   * // Order matters: the first arg is the target, the array holds the tools
+   * const [building, courtyard] = await snaptrude.design.selection.get()
+   * const { created, deleted } = await snaptrude.design.boolean.subtract(building, [courtyard])
+   * // deleted includes the target AND every tool; created is the remainder
+   * ```
+   */
+  public abstract subtract(
+    target: ComponentHandle,
+    tools: ComponentHandle[],
+    options?: BooleanOptions,
+  ): PluginApiReturn<BooleanOutcome>
+
+  /**
+   * Keep only the overlapping volume of exactly two masses (`A ∩ B`) — a boolean
+   * (CSG) intersection that discards everything outside the shared region and
+   * commits the overlap as a single undoable step. Order-independent.
+   *
+   * HARD constraint: **EXACTLY 2** components (schema `.length(2)`; the engine
+   * also throws `MoreThan2ComponentsForIntersect` on >2).
+   * @param components - **EXACTLY 2** entities to intersect (order-independent)
+   * @param options - Optional output offset — {@linkcode BooleanOptions}
+   * @returns The committed CSG delta — {@linkcode BooleanOutcome}
+   * @throws as {@linkcode union}, plus `MoreThan2ComponentsForIntersect` on >2.
+   *
+   * @examplePrompt Keep only the part where these two masses overlap
+   * @examplePrompt Intersect the two selected volumes
+   * @examplePrompt Give me the common volume between the tower and the zoning envelope
+   * @examplePrompt Trim this mass down to just its overlap with the other one
+   *
+   * # Example
+   * ```ts
+   * // Keep only the overlap of the tower and the zoning envelope (EXACTLY 2 inputs),
+   * // shifting the result mass 10 units in x via the optional offset
+   * const [tower, envelope] = await snaptrude.design.query.listMasses()
+   * const offset = await snaptrude.core.math.vec3.new(10, 0, 0)
+   * const { created } = await snaptrude.design.boolean.intersect([tower, envelope], { offset })
+   * ```
+   */
+  public abstract intersect(
+    components: ComponentHandle[],
+    options?: BooleanOptions,
+  ): PluginApiReturn<BooleanOutcome>
+}
+
+/**
+ * Optional knobs shared by all boolean ops. The only safe one is a world-space
+ * translation applied to the output mass(es) — maps to `Boolean3dOperation.offset`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `offset` | {@linkcode Vec3Handle} | Translation added to the created result mass(es) (default: none) |
+ */
+export const BooleanOptions = z.object({
+  offset: Vec3Handle.optional(),
+})
+export type BooleanOptions = z.infer<typeof BooleanOptions>
+
+/**
+ * Arguments for {@linkcode PluginDesignBooleanApi.union}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | The ≥2 entities to fuse (order-independent) |
+ * | `options` | {@linkcode BooleanOptions} | Optional output offset |
+ */
+export const PluginDesignBooleanUnionArgs = z.object({
+  components: z.array(ComponentHandle).min(2),
+  options: BooleanOptions.optional(),
+})
+export type PluginDesignBooleanUnionArgs = z.infer<typeof PluginDesignBooleanUnionArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignBooleanApi.subtract}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `target` | {@linkcode ComponentHandle} | The entity subtracted FROM (arg brep) |
+ * | `tools` | {@linkcode ComponentHandle}`[]` | The ≥1 entities subtracted (tool breps) |
+ * | `options` | {@linkcode BooleanOptions} | Optional output offset |
+ */
+export const PluginDesignBooleanSubtractArgs = z.object({
+  target: ComponentHandle,
+  tools: z.array(ComponentHandle).min(1),
+  options: BooleanOptions.optional(),
+})
+export type PluginDesignBooleanSubtractArgs = z.infer<typeof PluginDesignBooleanSubtractArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignBooleanApi.intersect}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | **EXACTLY 2** entities to intersect (order-independent) |
+ * | `options` | {@linkcode BooleanOptions} | Optional output offset |
+ */
+export const PluginDesignBooleanIntersectArgs = z.object({
+  components: z.array(ComponentHandle).length(2),
+  options: BooleanOptions.optional(),
+})
+export type PluginDesignBooleanIntersectArgs = z.infer<typeof PluginDesignBooleanIntersectArgs>

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

@@ -0,0 +1,186 @@
+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
+
+// ---------------------------------------------------------------------------
+// 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) |
+ */
+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(),
+})
+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
+>