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

package/src/api/design/bim.ts

@@ -0,0 +1,210 @@
+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)
+const pointMm = z.tuple([
+  z.number().finite(),
+  z.number().finite(),
+  z.number().finite(),
+])
+
+/** 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,
+  startNodeId: id.nullable(),
+  endNodeId: id.nullable(),
+  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) })),
+  nodes: z.array(z.object({ id, positionMm: pointMm })),
+  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>
+
+/** Plan-local vertex. Attach to a context node or to a fraction of a directed straight edge.
+ * New positions use world mm, Y-up. Attachments resolve on graph axes, not visible wall faces.
+ */
+export const PluginBimUpdateNode = z.union([
+  z.object({ id, positionMm: pointMm }).strict(),
+  z.object({ id, attach: z.object({ nodeId: id }).strict() }).strict(),
+  z
+    .object({
+      id,
+      attach: z
+        .object({ edgeId: id, t: z.number().finite().min(0).max(1) })
+        .strict(),
+    })
+    .strict(),
+])
+export type PluginBimUpdateNode = z.infer<typeof PluginBimUpdateNode>
+
+/** Additive partition graph, not replacement or raw PG2 CRUD. Endpoints reference plan-local nodes.
+ * Each free node must meet at least two planned walls; an open end requires an explicit attachment.
+ * Heights and positions use mm. All recipes, endpoints and revisions resolve before any mutation.
+ */
+export const PluginBimUpdateGraph = z
+  .object({
+    revision: id,
+    proposalId: id,
+    nodes: z.array(PluginBimUpdateNode).min(2).max(1000),
+    walls: z
+      .array(
+        z
+          .object({
+            id,
+            start: id,
+            end: id,
+            family: PluginConstructionType,
+            values: PluginFamilyValues.optional(),
+            heightMm: z.number().finite().positive(),
+            reversed: z.boolean(),
+            alignment: z.literal("coreCentre"),
+          })
+          .strict(),
+      )
+      .min(1)
+      .max(1000),
+  })
+  .strict()
+export type PluginBimUpdateGraph = z.infer<typeof PluginBimUpdateGraph>
+
+/** One native transaction. Regions are the final active-proposal regions, not predicted contours.
+ * Commands queue persistence; success is not a durable server-save acknowledgement.
+ */
+export const PluginBimUpdateResult = z.object({
+  created: z.array(ComponentHandle),
+  updated: z.array(ComponentHandle),
+  removed: z.array(ComponentHandle),
+  walls: z.array(z.object({ id, components: z.array(ComponentHandle) })),
+  regions: z.array(z.object({ id, floor: ComponentHandle.nullable() })),
+})
+export type PluginBimUpdateResult = z.infer<typeof PluginBimUpdateResult>
+
+/** Agent-driven BIM construction and partition updates through native PG2 topology. */
+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>
+
+  /** Add a partition graph with explicit connectivity and chosen wall families in one undo step.
+   * Validation is part of this call. PG2 splits intersections and generates floors with native lineage.
+   * Does not move/delete existing edges, infer face snapping, or change catalogue definitions.
+   * @param graphJson JSON-encoded PluginBimUpdateGraph from the latest getContext revision.
+   * @returns Created/updated/removed components, wall mappings and resulting regions. Invalid or stale
+   * plans throw before mutation; failed construction rolls back. Read context after an unknown result.
+   * @examplePrompt Add bathroom partitions attached to these existing graph boundaries
+   */
+  abstract update(graphJson: string): PluginApiReturn<PluginBimUpdateResult>
+}

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

@@ -1,179 +1,181 @@
-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>
+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.
+   *
+   * 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).
+   * @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>