@snaptrude/plugin-core 0.9.0 → 0.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

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

@@ -1,6 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../../types"
-import { Vec3Handle, LineHandle, ArcHandle, CircleHandle, CurveHandle, ProfileHandle, ContourHandle, BrepHandle, Vec3Components } from "../../../../handles"
+import { Vec3Handle, LineHandle, ArcHandle, CircleHandle, CurveHandle, ProfileHandle, ContourHandle, BrepHandle, FaceHandle, EdgeHandle, Vec3Components } from "../../../../handles"
 
 /**
  * Curve creation — construct new geometric curves from point handles (all-handle
@@ -263,25 +263,36 @@ export abstract class PluginGeomCreateApi {
 
   /**
    * Create a closed solid **B-rep** by lofting between a bottom and a top
-   * contour. Host API call — returns a {@linkcode BrepHandle}. Both contours
-   * must have the same number of edges (and matching hole counts); side faces
-   * connect corresponding edges by authored index. Corresponding edges must
-   * stay coplanar — a twisted loft would produce non-planar side faces and is
-   * rejected. The contours are copied — the input handles are never mutated.
+   * contour, optionally through intermediate cross-sections. Host API call —
+   * returns a {@linkcode BrepHandle}. All sections must have the same number
+   * of edges; side faces connect corresponding edges by authored index.
+   * Corresponding edges must stay coplanar segment to segment (matching hole
+   * counts allowed in the two-section form) — a twisted loft would produce
+   * non-planar side faces and is rejected. With intermediates the loft is a
+   * chain of ruled segments folded into one solid: sections must be planar
+   * and hole-free, ordered bottom → intermediates → top. The contours are
+   * copied — the input handles are never mutated.
    *
    * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
    * with `design.create.massFromBrep`.
    *
    * @param bottomContour The bottom cross-section
-   * @param topContour The top cross-section (same edge and hole counts as the bottom)
+   * @param topContour The top cross-section (same edge count as the bottom)
+   * @param intermediateContours Optional in-between cross-sections, ordered
+   *   bottom to top (hole-free, same edge count as the bottom and top)
    * @returns The new solid as a {@linkcode BrepHandle}
-   * @throws if the contours are coincident, their edge or hole counts differ,
-   *   a side face between corresponding edges would be non-planar, or the
-   *   contours cannot be lofted into a valid solid
+   * @throws VALIDATION if the contours are coincident, their edge or hole
+   *   counts differ, any section has holes when intermediates are present
+   *   (multi-section lofts take hole-free sections), a section is non-planar,
+   *   or a side face between corresponding edges would be non-planar (a
+   *   twisted section pair — the error names the offending sections)
+   * @throws OPERATION_FAILED if the lofted segments cannot be joined into a
+   *   valid solid
    *
    * @examplePrompt Make a tapered tower from these two outlines
    * @examplePrompt Loft between a large base and a smaller top
    * @examplePrompt Create a frustum from two squares
+   * @examplePrompt Loft the tower through these three floor outlines
    *
    * # Example
    * ```ts
@@ -298,6 +309,7 @@ export abstract class PluginGeomCreateApi {
   public abstract brepFromLoft(
     bottomContour: ContourHandle,
     topContour: ContourHandle,
+    intermediateContours?: ContourHandle[],
   ): PluginApiReturn<BrepHandle>
 
   /**
@@ -431,6 +443,296 @@ export abstract class PluginGeomCreateApi {
    * ```
    */
   public abstract brepFromIntersection(a: BrepHandle, b: BrepHandle): PluginApiReturn<BrepHandle>
+
+  /**
+   * Rounds the given straight edges of a solid with a constant radius. Host
+   * API call — returns a new {@linkcode BrepHandle}; the input brep is
+   * read-only.
+   *
+   * v1 fillets straight edges only, and no two filleted edges may share a
+   * vertex — corner blends produce spherical patches Snaptrude cannot
+   * represent. Runs on the OpenCascade kernel (the first kernel call loads a
+   * wasm of tens of MB — expect a pause of seconds).
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param brep The solid whose edges to round
+   * @param edges The straight edges to fillet (≥1, all on `brep`, no two sharing a vertex)
+   * @param radius Fillet radius (positive, finite)
+   * @returns The filleted solid as a new {@linkcode BrepHandle}
+   * @throws VALIDATION if `edges` is empty, `radius` is not a positive finite
+   *   number, an edge is not on `brep`, an edge is an arc (v1 fillets straight
+   *   edges only), or two edges share a vertex (fillet non-adjacent edges)
+   * @throws OPERATION_FAILED if the kernel cannot build the fillet (the radius
+   *   likely exceeds the adjacent face size — reduce it) or the result
+   *   contains curved surfaces Snaptrude cannot represent
+   *
+   * @examplePrompt Round the edges of this mass
+   * @examplePrompt Fillet the corners of the podium with a 0.5m radius
+   * @examplePrompt Soften the vertical edges of this tower
+   *
+   * # Example
+   * ```ts
+   * const brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)
+   * const edges = await snaptrude.core.geom.query.brep.listEdges(brep)
+   * const rounded = await snaptrude.core.geom.create.brepFromFillet(brep, [edges[0]], 0.3)
+   * ```
+   */
+  public abstract brepFromFillet(
+    brep: BrepHandle,
+    edges: EdgeHandle[],
+    radius: number,
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Grows or shrinks a solid by offsetting every face — positive distance
+   * moves faces outward, negative moves them inward. Host API call — returns
+   * a new {@linkcode BrepHandle}; the input brep is read-only.
+   *
+   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of
+   * tens of MB — expect a pause of seconds).
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param brep The solid to offset
+   * @param distance Offset distance (finite, non-zero; positive grows, negative shrinks)
+   * @returns The offset solid as a new {@linkcode BrepHandle}
+   * @throws VALIDATION if `distance` is not finite, is too small to offset
+   *   anything, or an inward distance consumes the solid entirely
+   * @throws OPERATION_FAILED if the kernel cannot build the offset or the
+   *   result contains curved surfaces Snaptrude cannot represent
+   *
+   * @examplePrompt Grow this solid by 0.5m in every direction
+   * @examplePrompt Shrink this mass by 200mm
+   * @examplePrompt Offset the building envelope outward by 1m
+   *
+   * # Example
+   * ```ts
+   * const brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)
+   * const grown = await snaptrude.core.geom.create.brepFromOffset(brep, 0.5)
+   * ```
+   */
+  public abstract brepFromOffset(brep: BrepHandle, distance: number): PluginApiReturn<BrepHandle>
+
+  /**
+   * Hollows a solid into constant-thickness walls, removing the given faces
+   * as openings. Host API call — returns a new {@linkcode BrepHandle}; the
+   * input brep is read-only. The outer surface is kept and the walls grow
+   * inward.
+   *
+   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of
+   * tens of MB — expect a pause of seconds).
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param brep The solid to hollow
+   * @param openFaces The faces to remove as openings (≥1, all on `brep`)
+   * @param thickness Wall thickness (positive, finite, smaller than half the solid's smallest span)
+   * @returns The hollowed solid as a new {@linkcode BrepHandle}
+   * @throws VALIDATION if `openFaces` is empty, a face is not on `brep`,
+   *   `thickness` is not a positive finite number, or the thickness is too
+   *   large (it must be smaller than half the solid's smallest span)
+   * @throws OPERATION_FAILED if the kernel cannot build the shell or the
+   *   result contains curved surfaces Snaptrude cannot represent
+   *
+   * @examplePrompt Hollow this mass into 200mm walls
+   * @examplePrompt Shell this form with the top face open
+   * @examplePrompt Turn this solid tower into a tube open at both ends
+   *
+   * # Example
+   * ```ts
+   * const brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)
+   * const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
+   * const hollow = await snaptrude.core.geom.create.brepFromShell(brep, [faces[0]], 0.2)
+   * ```
+   */
+  public abstract brepFromShell(
+    brep: BrepHandle,
+    openFaces: FaceHandle[],
+    thickness: number,
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Cuts a solid by an infinite plane and returns one brep per resulting
+   * piece — a single piece if the plane misses the solid. Host API call —
+   * returns new {@linkcode BrepHandle}s; the input brep is read-only. The
+   * plane is defined by a point on it and its normal direction.
+   *
+   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of
+   * tens of MB — expect a pause of seconds).
+   *
+   * Inspect each result via `core.geom.query.brep.*`, or commit them to the
+   * scene with `design.create.massFromBrep`.
+   *
+   * @param brep The solid to split
+   * @param planeOrigin A point on the cutting plane as plain `{x, y, z}` components
+   * @param planeNormal The plane normal as plain `{x, y, z}` components (non-zero)
+   * @returns The resulting pieces as {@linkcode BrepHandle}`[]` (one per solid)
+   * @throws VALIDATION if `planeNormal` is zero-length or the origin/normal
+   *   components are not finite
+   * @throws OPERATION_FAILED if the kernel cannot split the solid
+   *
+   * @examplePrompt Cut this building at 12m height
+   * @examplePrompt Split the tower from the podium with a horizontal plane
+   * @examplePrompt Slice this mass along a vertical plane
+   *
+   * # Example
+   * ```ts
+   * const pieces = await snaptrude.core.geom.create.brepsFromSplit(
+   *   towerBrep,
+   *   { x: 0, y: 12, z: 0 },
+   *   { x: 0, y: 1, z: 0 },
+   * )
+   * console.log("pieces:", pieces.length)
+   * ```
+   */
+  public abstract brepsFromSplit(
+    brep: BrepHandle,
+    planeOrigin: Vec3Components,
+    planeNormal: Vec3Components,
+  ): PluginApiReturn<BrepHandle[]>
+
+  /**
+   * Bevels the given straight edges of a solid with a symmetric planar cut.
+   * Host API call — returns a new {@linkcode BrepHandle}; the input brep is
+   * read-only.
+   *
+   * v1 chamfers straight edges only, and no two chamfered edges may share a
+   * vertex. Runs on the OpenCascade kernel (the first kernel call loads a
+   * wasm of tens of MB — expect a pause of seconds).
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param brep The solid whose edges to bevel
+   * @param edges The straight edges to chamfer (≥1, all on `brep`, no two sharing a vertex)
+   * @param distance Chamfer distance from the edge on each adjacent face (positive, finite)
+   * @returns The chamfered solid as a new {@linkcode BrepHandle}
+   * @throws VALIDATION if `edges` is empty, `distance` is not a positive
+   *   finite number, an edge is not on `brep`, an edge is an arc (v1 chamfers
+   *   straight edges only), or two edges share a vertex (chamfer non-adjacent
+   *   edges)
+   * @throws OPERATION_FAILED if the kernel cannot build the chamfer (the
+   *   distance likely exceeds the adjacent face size — reduce it)
+   *
+   * @examplePrompt Bevel these edges by 100mm
+   * @examplePrompt Chamfer the top edges of the plinth
+   * @examplePrompt Cut a 45-degree flat along the corners of this mass
+   *
+   * # Example
+   * ```ts
+   * const brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)
+   * const edges = await snaptrude.core.geom.query.brep.listEdges(brep)
+   * const beveled = await snaptrude.core.geom.create.brepFromChamfer(brep, [edges[0]], 0.1)
+   * ```
+   */
+  public abstract brepFromChamfer(
+    brep: BrepHandle,
+    edges: EdgeHandle[],
+    distance: number,
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Sweeps a planar profile along an open polyline path, with mitred corners
+   * at each bend. Host API call — returns a new {@linkcode BrepHandle}; the
+   * input contour is read-only. The profile must be hole-free and must not
+   * lie in a plane containing the first path segment's direction.
+   *
+   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of
+   * tens of MB — expect a pause of seconds).
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param profile The cross-section to sweep (hole-free contour)
+   * @param path The polyline path as plain `{x, y, z}` points (≥2, open — first ≠ last)
+   * @returns The swept solid as a new {@linkcode BrepHandle}
+   * @throws VALIDATION if the profile has holes, the path has fewer than 2
+   *   points, consecutive path points coincide, the path is closed (open
+   *   paths only in v1), a coordinate is not finite, or the profile plane
+   *   contains the first path segment's direction (degenerate sweep)
+   * @throws OPERATION_FAILED if the kernel cannot sweep the profile into a
+   *   valid solid or a transition patch is a curved surface Snaptrude cannot
+   *   represent
+   *
+   * @examplePrompt Sweep this profile along the corridor path
+   * @examplePrompt Extrude the railing section along this route
+   * @examplePrompt Run a duct profile through these points
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(0.4, 0.4)
+   * const profile = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * // profileRect lies in the XZ plane, so the path must START out of that
+   * // plane (here: straight up), then it can run horizontally.
+   * const duct = await snaptrude.core.geom.create.brepFromSweep(profile, [
+   *   { x: 0, y: 0, z: 0 },
+   *   { x: 0, y: 2.8, z: 0 },
+   *   { x: 10, y: 2.8, z: 0 },
+   * ])
+   * ```
+   */
+  public abstract brepFromSweep(
+    profile: ContourHandle,
+    path: Vec3Components[],
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Revolves a planar profile about an axis to make a solid of revolution — a
+   * full turn by default. Host API call — returns a new
+   * {@linkcode BrepHandle}; the input contour is read-only. Holes in the
+   * profile are allowed. Profile segments must stay parallel or perpendicular
+   * to the axis — inclined or arc segments would revolve into surfaces
+   * Snaptrude cannot represent.
+   *
+   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of
+   * tens of MB — expect a pause of seconds).
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param profile The cross-section to revolve (planar contour, holes allowed)
+   * @param axisOrigin A point on the revolution axis as plain `{x, y, z}` components
+   * @param axisDirection The axis direction as plain `{x, y, z}` components (non-zero)
+   * @param angleInDegrees Optional revolution angle in degrees (0 < angle ≤ 360; default 360)
+   * @returns The revolved solid as a new {@linkcode BrepHandle}
+   * @throws VALIDATION if `axisDirection` is zero-length, `angleInDegrees` is
+   *   not in (0, 360], the axis passes through the profile interior, or a
+   *   coordinate is not finite
+   * @throws OPERATION_FAILED if the kernel cannot revolve the profile or the
+   *   result contains curved surfaces Snaptrude cannot represent (keep
+   *   profile segments parallel or perpendicular to the axis)
+   *
+   * @examplePrompt Create a dome from this section
+   * @examplePrompt Revolve this profile 360 degrees around the vertical axis
+   * @examplePrompt Build a rotunda by revolving this wall section
+   *
+   * # Example
+   * ```ts
+   * // A cylinder: revolve a 2m-wide, 3m-tall rectangle about the Y axis at its edge
+   * const rect = await snaptrude.core.geom.create.profileFromLinePoints([
+   *   await snaptrude.core.math.vec3.new(0, 0, 0),
+   *   await snaptrude.core.math.vec3.new(2, 0, 0),
+   *   await snaptrude.core.math.vec3.new(2, 3, 0),
+   *   await snaptrude.core.math.vec3.new(0, 3, 0),
+   * ])
+   * const profile = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const cylinder = await snaptrude.core.geom.create.brepFromRevolution(
+   *   profile,
+   *   { x: 0, y: 0, z: 0 },
+   *   { x: 0, y: 1, z: 0 },
+   * )
+   * ```
+   */
+  public abstract brepFromRevolution(
+    profile: ContourHandle,
+    axisOrigin: Vec3Components,
+    axisDirection: Vec3Components,
+    angleInDegrees?: number,
+  ): PluginApiReturn<BrepHandle>
 }
 
 /**
@@ -594,10 +896,12 @@ export type PluginGeomCreateBrepFromExtrusionArgs = z.infer<
  * |---|---|---|
  * | `bottomContour` | {@linkcode ContourHandle} | The bottom cross-section |
  * | `topContour` | {@linkcode ContourHandle} | The top cross-section |
+ * | `intermediateContours` | {@linkcode ContourHandle}`[]`? | Optional in-between cross-sections, ordered bottom to top |
  */
 export const PluginGeomCreateBrepFromLoftArgs = z.object({
   bottomContour: ContourHandle,
   topContour: ContourHandle,
+  intermediateContours: z.array(ContourHandle).optional(),
 })
 
 export type PluginGeomCreateBrepFromLoftArgs = z.infer<typeof PluginGeomCreateBrepFromLoftArgs>
@@ -634,3 +938,134 @@ export const PluginGeomCreateBrepBooleanArgs = z.object({
 })
 
 export type PluginGeomCreateBrepBooleanArgs = z.infer<typeof PluginGeomCreateBrepBooleanArgs>
+
+// Plain {x, y, z} record with finite components (brepFromExtrusion `direction` pattern).
+const FiniteVec3Components = z.object({
+  x: z.number().finite(),
+  y: z.number().finite(),
+  z: z.number().finite(),
+})
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromFillet}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `brep` | {@linkcode BrepHandle} | The solid whose edges to round |
+ * | `edges` | {@linkcode EdgeHandle}`[]` | The straight edges to fillet (≥1) |
+ * | `radius` | `number` | Fillet radius (positive, finite) |
+ */
+export const PluginGeomCreateBrepFromFilletArgs = z.object({
+  brep: BrepHandle,
+  edges: z.array(EdgeHandle).min(1),
+  radius: z.number().finite().positive(),
+})
+
+export type PluginGeomCreateBrepFromFilletArgs = z.infer<typeof PluginGeomCreateBrepFromFilletArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromOffset}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `brep` | {@linkcode BrepHandle} | The solid to offset |
+ * | `distance` | `number` | Offset distance (finite, non-zero; positive grows, negative shrinks) |
+ */
+export const PluginGeomCreateBrepFromOffsetArgs = z.object({
+  brep: BrepHandle,
+  distance: z
+    .number()
+    .finite()
+    .refine((value) => value !== 0, { message: "distance must be non-zero" }),
+})
+
+export type PluginGeomCreateBrepFromOffsetArgs = z.infer<typeof PluginGeomCreateBrepFromOffsetArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromShell}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `brep` | {@linkcode BrepHandle} | The solid to hollow |
+ * | `openFaces` | {@linkcode FaceHandle}`[]` | The faces to remove as openings (≥1) |
+ * | `thickness` | `number` | Wall thickness (positive, finite) |
+ */
+export const PluginGeomCreateBrepFromShellArgs = z.object({
+  brep: BrepHandle,
+  openFaces: z.array(FaceHandle).min(1),
+  thickness: z.number().finite().positive(),
+})
+
+export type PluginGeomCreateBrepFromShellArgs = z.infer<typeof PluginGeomCreateBrepFromShellArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepsFromSplit}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `brep` | {@linkcode BrepHandle} | The solid to split |
+ * | `planeOrigin` | {@linkcode Vec3Components} | A point on the cutting plane (finite components) |
+ * | `planeNormal` | {@linkcode Vec3Components} | The plane normal (non-zero, finite components) |
+ */
+export const PluginGeomCreateBrepsFromSplitArgs = z.object({
+  brep: BrepHandle,
+  planeOrigin: FiniteVec3Components,
+  planeNormal: FiniteVec3Components,
+})
+
+export type PluginGeomCreateBrepsFromSplitArgs = z.infer<typeof PluginGeomCreateBrepsFromSplitArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromChamfer}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `brep` | {@linkcode BrepHandle} | The solid whose edges to bevel |
+ * | `edges` | {@linkcode EdgeHandle}`[]` | The straight edges to chamfer (≥1) |
+ * | `distance` | `number` | Chamfer distance from the edge on each adjacent face (positive, finite) |
+ */
+export const PluginGeomCreateBrepFromChamferArgs = z.object({
+  brep: BrepHandle,
+  edges: z.array(EdgeHandle).min(1),
+  distance: z.number().finite().positive(),
+})
+
+export type PluginGeomCreateBrepFromChamferArgs = z.infer<
+  typeof PluginGeomCreateBrepFromChamferArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromSweep}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ContourHandle} | The cross-section to sweep (hole-free) |
+ * | `path` | {@linkcode Vec3Components}`[]` | The open polyline path (≥2 points, finite components) |
+ */
+export const PluginGeomCreateBrepFromSweepArgs = z.object({
+  profile: ContourHandle,
+  path: z.array(FiniteVec3Components).min(2),
+})
+
+export type PluginGeomCreateBrepFromSweepArgs = z.infer<typeof PluginGeomCreateBrepFromSweepArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromRevolution}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ContourHandle} | The cross-section to revolve (holes allowed) |
+ * | `axisOrigin` | {@linkcode Vec3Components} | A point on the revolution axis (finite components) |
+ * | `axisDirection` | {@linkcode Vec3Components} | The axis direction (non-zero, finite components) |
+ * | `angleInDegrees` | `number`? | Revolution angle in degrees (0 < angle ≤ 360; default 360) |
+ */
+export const PluginGeomCreateBrepFromRevolutionArgs = z.object({
+  profile: ContourHandle,
+  axisOrigin: FiniteVec3Components,
+  axisDirection: FiniteVec3Components,
+  angleInDegrees: z.number().finite().positive().max(360).optional(),
+})
+
+export type PluginGeomCreateBrepFromRevolutionArgs = z.infer<
+  typeof PluginGeomCreateBrepFromRevolutionArgs
+>

package/src/api/core/geom/query/brep.ts

@@ -328,6 +328,37 @@ export abstract class PluginGeomQueryBrepApi {
    * ```
    */
   public abstract isEqual(brepA: BrepHandle, brepB: BrepHandle): PluginApiReturn<boolean>
+
+  /**
+   * Measures the minimum distance between two solids, with the closest witness
+   * point on each. Touching or overlapping solids report a distance of 0 with
+   * contact points.
+   *
+   * @param brepA First solid
+   * @param brepB Second solid
+   * @returns `{ distance, pointA, pointB }` — the minimum distance and the
+   *   closest points on `brepA` and `brepB` as {@linkcode Vec3Components}
+   * @throws OPERATION_FAILED if the kernel cannot compute the distance
+   *
+   * @examplePrompt What is the clearance between these two masses?
+   * @examplePrompt How far apart are the tower and the neighbouring building?
+   * @examplePrompt Find the closest points between these two solids
+   *
+   * # Example
+   * ```ts
+   * const [a, b] = await snaptrude.design.query.listMasses()
+   * const brepA = await snaptrude.design.query.geometry.getBrep(a)
+   * const brepB = await snaptrude.design.query.geometry.getBrep(b)
+   * if (brepA && brepB) {
+   *   const { distance, pointA, pointB } = await snaptrude.core.geom.query.brep.getDistance(brepA, brepB)
+   *   console.log("clearance:", distance)
+   * }
+   * ```
+   */
+  public abstract getDistance(
+    brepA: BrepHandle,
+    brepB: BrepHandle
+  ): PluginApiReturn<{ distance: number; pointA: Vec3Components; pointB: Vec3Components }>
 }
 
 const brepArg = z.object({ brep: BrepHandle })
@@ -442,3 +473,17 @@ export const PluginGeomQueryBrepIsEqualArgs = z.object({
   brepB: BrepHandle,
 })
 export type PluginGeomQueryBrepIsEqualArgs = z.infer<typeof PluginGeomQueryBrepIsEqualArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomQueryBrepApi.getDistance}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `brepA` | {@linkcode BrepHandle} | First solid |
+ * | `brepB` | {@linkcode BrepHandle} | Second solid |
+ */
+export const PluginGeomQueryBrepGetDistanceArgs = z.object({
+  brepA: BrepHandle,
+  brepB: BrepHandle,
+})
+export type PluginGeomQueryBrepGetDistanceArgs = z.infer<typeof PluginGeomQueryBrepGetDistanceArgs>