@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827194031

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 } 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
@@ -177,6 +177,653 @@ export abstract class PluginGeomCreateApi {
     outer: ProfileHandle,
     holes?: ProfileHandle[],
   ): PluginApiReturn<ContourHandle>
+
+  /**
+   * Create a closed solid **B-rep** from explicit face loops. Host API call —
+   * returns a {@linkcode BrepHandle}. Faces are plain arrays of `{x, y, z}`
+   * point components, NOT point handles (bulk-data precedent:
+   * `design.query.geometry.getTriangulatedMeshes`), in raw Babylon units.
+   *
+   * Each face is one planar loop of at least 3 points; at least 4 faces are
+   * required. Loops may be authored in any consistent winding — the host
+   * validates edge coherence (every edge shared by exactly two faces, in
+   * opposite directions) and fixes the global orientation so faces point
+   * outward. Faces must be planar and the solid must be closed; holes in faces
+   * are not supported (v1).
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param faces Face loops — each an ordered array of `{x, y, z}` points (≥3 points per face, ≥4 faces)
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws if a face is degenerate or non-planar, an edge is not shared by
+   *   exactly two faces (open shell, non-manifold, or inconsistent winding), or
+   *   the faces do not form a valid closed solid
+   *
+   * @examplePrompt Create a brep from faces
+   * @examplePrompt Build a custom solid from a set of faces
+   * @examplePrompt Make a pyramid from triangular faces
+   *
+   * # Example
+   * ```ts
+   * // A pyramid: square base + 4 triangular sides
+   * const apex = { x: 0, y: 4, z: 0 }
+   * const a = { x: -2, y: 0, z: -2 }
+   * const b = { x: 2, y: 0, z: -2 }
+   * const c = { x: 2, y: 0, z: 2 }
+   * const d = { x: -2, y: 0, z: 2 }
+   * const brep = await snaptrude.core.geom.create.brepFromFaces([
+   *   [a, d, c, b], // base
+   *   [a, b, apex],
+   *   [b, c, apex],
+   *   [c, d, apex],
+   *   [d, a, apex],
+   * ])
+   * const faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep) // 5
+   * ```
+   */
+  public abstract brepFromFaces(faces: Vec3Components[][]): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** by extruding a contour along a direction.
+   * Host API call — returns a {@linkcode BrepHandle}. The direction is
+   * normalised by the host, so `amount` is the extrusion distance in raw
+   * Babylon units (negative extrudes the opposite way). The contour is copied —
+   * the input handle is never mutated. Holes and arc/circle profiles extrude
+   * natively (a circle profile yields a cylinder).
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param contour The cross-section to extrude (outer profile + optional holes)
+   * @param direction Extrusion direction as plain `{x, y, z}` components (non-zero, normalised by the host)
+   * @param amount Extrusion distance (non-zero; negative extrudes opposite to `direction`)
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws if the extrusion is degenerate (zero amount, zero direction, or a
+   *   direction lying in the contour plane) or the contour cannot be extruded
+   *   into a valid solid
+   *
+   * @examplePrompt Extrude this profile 3 metres up
+   * @examplePrompt Make a solid by extruding this outline
+   * @examplePrompt Create a cylinder from a circle profile
+   *
+   * # Example
+   * ```ts
+   * const rect = await snaptrude.core.geom.create.profileRect(4, 3)
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(rect)
+   * const brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)
+   * const faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep) // 6
+   * ```
+   */
+  public abstract brepFromExtrusion(
+    contour: ContourHandle,
+    direction: Vec3Components,
+    amount: number,
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** by lofting between a bottom and a top
+   * contour, optionally through intermediate cross-sections. Host API call —
+   * returns a {@linkcode BrepHandle}. Sections with different edge counts are
+   * auto-matched: vertices are deterministically inserted on the smaller
+   * sections at the larger section's perimeter positions, so the same input
+   * always yields the same solid. For straight-edge (all-line) sections the
+   * seam is auto-aligned too — winding and start-vertex correspondence are
+   * chosen to avoid a twist, so outlines authored from any starting corner
+   * loft cleanly; arc-bearing sections keep the authored correspondence
+   * unchanged. A pair whose side faces would be non-planar under every
+   * correspondence still builds for hole-free straight-edged pairs — planar
+   * side quads stay quads and warped ones split into planar triangles (the
+   * triangulated lane); arc-bearing or holed twisted pairs are rejected, as is
+   * auto-matching that would pair an arc with a straight edge. Matching hole
+   * counts are allowed in the two-section form. 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 (edge count may differ from the
+   *   bottom — sections are auto-matched)
+   * @param intermediateContours Optional in-between cross-sections, ordered
+   *   bottom to top (hole-free; edge counts may differ — every section is
+   *   normalized to the largest)
+   * @param options Optional behavior switches. `compatibility` — `"auto"`
+   *   (default) inserts vertices to match differing edge counts; `"strict"`
+   *   skips normalization and throws VALIDATION when outer edge counts (or,
+   *   in the two-section form, hole-pair counts) differ. `seamAlignment` —
+   *   `"auto"` (default) searches seam rotations on straight-edge sections to
+   *   avoid a twist; `"authored"` keeps the authored start-vertex
+   *   correspondence unchanged (a twisted correspondence then builds through
+   *   the triangulated lane for hole-free straight-edged pairs).
+   *   `{ compatibility: "strict", seamAlignment: "authored" }` reproduces
+   *   pre-0.9.4 lofting exactly.
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws VALIDATION if the contours are coincident, their hole counts
+   *   differ, any section has holes when intermediates are present
+   *   (multi-section lofts take hole-free sections), a section is non-planar,
+   *   sections are too dissimilar to auto-match, auto-matching would pair an
+   *   arc with a straight edge, or — for arc-bearing or holed pairs only — no vertex correspondence avoids a twist (a
+   *   side face between corresponding edges would be non-planar — the error
+   *   names the offending sections); with `compatibility: "strict"`, if
+   *   section edge counts (or hole-pair counts) differ — the error names the
+   *   sections and counts and points at `compatibility: "auto"`
+   * @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
+   * @examplePrompt Loft a four-sided base to a five-sided top
+   * @examplePrompt Loft these outlines even though their corners don't line up
+   * @examplePrompt Loft these outlines exactly as authored, corner to corner
+   * @examplePrompt Fail the loft if my sections don't have matching edge counts
+   *
+   * # Example
+   * ```ts
+   * // A square frustum: 4m base lofted to a 2m top, 3m up
+   * const base = await snaptrude.core.geom.create.profileRect(4, 4)
+   * const top = await snaptrude.core.geom.create.profileRect(2, 2, await snaptrude.core.math.vec3.new(0, 3, 0))
+   * const brep = await snaptrude.core.geom.create.brepFromLoft(
+   *   await snaptrude.core.geom.create.contourFromProfile(base),
+   *   await snaptrude.core.geom.create.contourFromProfile(top),
+   * )
+   * const faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep) // 6
+   * ```
+   */
+  public abstract brepFromLoft(
+    bottomContour: ContourHandle,
+    topContour: ContourHandle,
+    intermediateContours?: ContourHandle[],
+    options?: { compatibility?: "strict" | "auto"; seamAlignment?: "authored" | "auto" },
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** from indexed mesh data: a vertex position
+   * array plus face loops of indices into it. Host API call — returns a
+   * {@linkcode BrepHandle}. The indexed form of
+   * {@linkcode PluginGeomCreateApi.brepFromFaces} — same validation (planar
+   * faces, closed manifold solid, every edge shared by exactly two faces) after
+   * the indices are expanded to point loops.
+   *
+   * Inspect the result via `core.geom.query.brep.*`, or commit it to the scene
+   * with `design.create.massFromBrep`.
+   *
+   * @param positions Vertex positions as plain `{x, y, z}` components (≥4)
+   * @param faces Face loops — each an ordered array of indices into `positions` (≥3 indices per face, ≥4 faces)
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws if an index is not an integer within `positions` bounds, a face is
+   *   degenerate or non-planar, or the faces do not form a valid closed solid
+   *
+   * @examplePrompt Create a brep from mesh vertices and indices
+   * @examplePrompt Turn this indexed mesh into a solid
+   * @examplePrompt Build a solid from vertex positions and face indices
+   *
+   * # Example
+   * ```ts
+   * // A tetrahedron from 4 vertices and 4 triangular faces
+   * const positions = [
+   *   { x: 0, y: 0, z: 0 },
+   *   { x: 4, y: 0, z: 0 },
+   *   { x: 2, y: 0, z: 4 },
+   *   { x: 2, y: 3, z: 1.5 },
+   * ]
+   * const brep = await snaptrude.core.geom.create.brepFromMesh(positions, [
+   *   [0, 2, 1], // base
+   *   [0, 1, 3],
+   *   [1, 2, 3],
+   *   [2, 0, 3],
+   * ])
+   * const vertexCount = await snaptrude.core.geom.query.brep.getVertexCount(brep) // 4
+   * ```
+   */
+  public abstract brepFromMesh(
+    positions: Vec3Components[],
+    faces: number[][],
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** as the boolean **union** of two breps
+   * (`a ∪ b`). Host API call — returns a new {@linkcode BrepHandle}. Inputs are
+   * read-only and may be authored breps (any `core.geom.create` brep
+   * constructor) or scene-derived breps from `design.query.geometry.getBrep`;
+   * coordinates are combined as-is, so both inputs must share a frame. The
+   * result must be a single solid — disjoint inputs are rejected.
+   *
+   * The first boolean call loads the OpenCascade geometry kernel (a wasm of
+   * tens of MB — expect a pause of seconds); subsequent calls are fast.
+   *
+   * @param a First solid
+   * @param b Second solid
+   * @returns The union as a new {@linkcode BrepHandle}
+   * @throws if the inputs do not overlap or touch (the union would be disjoint
+   *   solids) or the result cannot be built as a valid single solid
+   *
+   * @examplePrompt Union these two solids
+   * @examplePrompt Merge these breps into one mass
+   * @examplePrompt Combine the tower and the podium into a single solid
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.geom.create.brepFromExtrusion(baseContour, { x: 0, y: 1, z: 0 }, 3)
+   * const b = await snaptrude.core.geom.create.brepFromExtrusion(overlappingContour, { x: 0, y: 1, z: 0 }, 5)
+   * const merged = await snaptrude.core.geom.create.brepFromUnion(a, b)
+   * ```
+   */
+  public abstract brepFromUnion(a: BrepHandle, b: BrepHandle): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** as the boolean **subtraction** of two
+   * breps: **`a` minus `b`** — `b` is cut away from `a`. Host API call —
+   * returns a new {@linkcode BrepHandle}. Argument order matters:
+   * `brepFromSubtraction(a, b)` removes `b`'s volume from `a`. Inputs are
+   * read-only and may be authored or scene-derived breps (see
+   * {@linkcode PluginGeomCreateApi.brepFromUnion}); coordinates are combined
+   * as-is.
+   *
+   * The first boolean call loads the OpenCascade geometry kernel (a wasm of
+   * tens of MB — expect a pause of seconds); subsequent calls are fast.
+   *
+   * @param a The solid to subtract from
+   * @param b The solid to remove from `a`
+   * @returns `a` minus `b` as a new {@linkcode BrepHandle}
+   * @throws if `b` consumes `a` entirely (empty result), the result splits into
+   *   disjoint solids, or it cannot be built as a valid single solid
+   *
+   * @examplePrompt Subtract the courtyard from the building mass
+   * @examplePrompt Cut this solid out of that one
+   * @examplePrompt Punch a hole through the slab with this box
+   *
+   * # Example
+   * ```ts
+   * // buildingBrep minus courtyardBrep — order matters
+   * const carved = await snaptrude.core.geom.create.brepFromSubtraction(buildingBrep, courtyardBrep)
+   * ```
+   */
+  public abstract brepFromSubtraction(a: BrepHandle, b: BrepHandle): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a closed solid **B-rep** as the boolean **intersection** of two
+   * breps (`a ∩ b` — the shared volume only). Host API call — returns a new
+   * {@linkcode BrepHandle}. Inputs are read-only and may be authored or
+   * scene-derived breps (see {@linkcode PluginGeomCreateApi.brepFromUnion});
+   * coordinates are combined as-is.
+   *
+   * The first boolean call loads the OpenCascade geometry kernel (a wasm of
+   * tens of MB — expect a pause of seconds); subsequent calls are fast.
+   *
+   * @param a First solid
+   * @param b Second solid
+   * @returns The shared volume as a new {@linkcode BrepHandle}
+   * @throws if the inputs do not overlap (empty intersection), the result
+   *   splits into disjoint solids, or it cannot be built as a valid single
+   *   solid
+   *
+   * @examplePrompt Keep only the overlap of these two solids
+   * @examplePrompt Intersect these two masses
+   * @examplePrompt Clip the tower to the zoning envelope
+   *
+   * # Example
+   * ```ts
+   * const overlap = await snaptrude.core.geom.create.brepFromIntersection(towerBrep, envelopeBrep)
+   * ```
+   */
+  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 a 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. Repeating
+   * the first point as the last closes the path into a ring solid (a picture
+   * frame): closed paths must be flat and straight-segmented and take a
+   * straight-edged (arc-free) profile — the ring's cross-section is the
+   * authored profile projected along the first leg onto the first mitre
+   * plane, so a profile not perpendicular to the first leg appears sheared.
+   * An optional scale law tapers the sweep: `startScale`/`endScale`
+   * interpolate linearly by arc length, or `scales` gives one factor per path
+   * point (scaling is about the profile centroid). A uniform scale (all
+   * factors equal) works on any path today's sweep accepts; a varying scale
+   * takes straight (collinear) open paths with straight-edged profiles —
+   * tapering across a bend or along an arc edge would create faces Snaptrude
+   * cannot represent and throws (sweep each straight run separately and union
+   * the results instead). An optional `transition` picks the corner
+   * treatment: `"miter"` (default) is today's sharp mitred bend;
+   * `{ bevel: b }` chamfers each turning corner by cutting `b` back along
+   * both adjacent legs (works on open and closed paths — each leg must be
+   * long enough for its cuts). On a corner-less path `transition` has no effect, and the
+   * varying-scale lane takes straight paths, so it never sees a corner.
+   *
+   * Open paths run on the OpenCascade kernel (the first kernel call loads a
+   * wasm of tens of MB — expect a pause of seconds); closed paths are
+   * computed host-side and never load the kernel.
+   *
+   * 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; repeat the
+   *   first point as the last to close the path into a ring)
+   * @param options Optional scale law and corner transition. Scale law:
+   *   `startScale`/`endScale` (linear taper by arc length) or `scales` (one
+   *   factor per path point; mutually exclusive with
+   *   `startScale`/`endScale`); every factor must be finite and within
+   *   1e-3..1e3. `transition`: `"miter"` (default, sharp corners) or
+   *   `{ bevel: b }` (chamfered corners, `b` finite within 1e-3..1e3; open
+   *   and closed paths)
+   * @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, a coordinate is not finite,
+   *   or the profile plane contains the first path segment's direction
+   *   (degenerate sweep); for closed paths, if the ring has fewer than 3
+   *   distinct corners, the path is non-planar, a corner doubles back, the
+   *   profile has an arc edge, or the profile is too large for a mitred
+   *   corner; for scale options, if a factor is outside 1e-3..1e3, `scales`
+   *   is combined with `startScale`/`endScale`, `scales` does not match the
+   *   path length, or a varying scale is used on a bent or closed path or
+   *   with an arc-edged profile; for `{ bevel }`, if a leg is too short for
+   *   the cuts its beveled corners take from it or a corner nearly doubles
+   *   back so its chamfer collapses (the errors name the corner)
+   * @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
+   * @examplePrompt Sweep a frame profile around a closed rectangular loop
+   * @examplePrompt Taper this duct from 1x1 to 2x2 along its run
+   * @examplePrompt Sweep a column section that narrows toward the top
+   * @examplePrompt Chamfer the corners of this swept frame by 200mm
+   *
+   * # 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 },
+   * ])
+   * // A closed ring (picture frame): repeat the first point as the last
+   * const frame = await snaptrude.core.geom.create.brepFromSweep(profile, [
+   *   { x: 0, y: 0, z: 0 },
+   *   { x: 0, y: 3, z: 0 },
+   *   { x: 4, y: 3, z: 0 },
+   *   { x: 4, y: 0, z: 0 },
+   *   { x: 0, y: 0, z: 0 },
+   * ])
+   * // A tapered straight run: 0.4x0.4 at the start, 0.8x0.8 at the end
+   * const flue = await snaptrude.core.geom.create.brepFromSweep(
+   *   profile,
+   *   [
+   *     { x: 0, y: 0, z: 0 },
+   *     { x: 0, y: 10, z: 0 },
+   *   ],
+   *   { startScale: 1, endScale: 2 },
+   * )
+   * ```
+   */
+  public abstract brepFromSweep(
+    profile: ContourHandle,
+    path: Vec3Components[],
+    options?: {
+      startScale?: number
+      endScale?: number
+      scales?: number[]
+      transition?: "miter" | { bevel: number }
+    },
+  ): 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>
 }
 
 /**
@@ -291,3 +938,267 @@ export const PluginGeomCreateContourFromProfilesArgs = z.object({
 export type PluginGeomCreateContourFromProfilesArgs = z.infer<
   typeof PluginGeomCreateContourFromProfilesArgs
 >
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromFaces}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `faces` | {@linkcode Vec3Components}`[][]` | Face loops — each an ordered array of `{x, y, z}` points (≥3 points per face, ≥4 faces) |
+ */
+export const PluginGeomCreateBrepFromFacesArgs = z.object({
+  faces: z.array(z.array(Vec3Components).min(3)).min(4),
+})
+
+export type PluginGeomCreateBrepFromFacesArgs = z.infer<
+  typeof PluginGeomCreateBrepFromFacesArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromExtrusion}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | The cross-section to extrude |
+ * | `direction` | {@linkcode Vec3Components} | Extrusion direction (non-zero, finite components) |
+ * | `amount` | `number` | Extrusion distance (finite, non-zero) |
+ */
+export const PluginGeomCreateBrepFromExtrusionArgs = z.object({
+  contour: ContourHandle,
+  direction: z.object({
+    x: z.number().finite(),
+    y: z.number().finite(),
+    z: z.number().finite(),
+  }),
+  amount: z
+    .number()
+    .finite()
+    .refine((value) => value !== 0, { message: "amount must be non-zero" }),
+})
+
+export type PluginGeomCreateBrepFromExtrusionArgs = z.infer<
+  typeof PluginGeomCreateBrepFromExtrusionArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromLoft}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `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 |
+ * | `options` | `object`? | Optional behavior switches: `compatibility` (`"strict"` throws on mismatched edge counts instead of auto-matching; default `"auto"`) and `seamAlignment` (`"authored"` keeps the authored correspondence instead of searching seam rotations; default `"auto"`) |
+ */
+export const PluginGeomCreateBrepFromLoftArgs = z.object({
+  bottomContour: ContourHandle,
+  topContour: ContourHandle,
+  intermediateContours: z.array(ContourHandle).optional(),
+  options: z
+    .object({
+      compatibility: z.enum(["strict", "auto"]).optional(),
+      seamAlignment: z.enum(["authored", "auto"]).optional(),
+    })
+    .optional(),
+})
+
+export type PluginGeomCreateBrepFromLoftArgs = z.infer<typeof PluginGeomCreateBrepFromLoftArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromMesh}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `positions` | {@linkcode Vec3Components}`[]` | Vertex positions (≥4) |
+ * | `faces` | `number[][]` | Face loops of indices into `positions` (≥3 indices per face, ≥4 faces) |
+ */
+export const PluginGeomCreateBrepFromMeshArgs = z.object({
+  positions: z.array(Vec3Components).min(4),
+  faces: z.array(z.array(z.number()).min(3)).min(4),
+})
+
+export type PluginGeomCreateBrepFromMeshArgs = z.infer<typeof PluginGeomCreateBrepFromMeshArgs>
+
+/**
+ * Arguments for the brep boolean constructors —
+ * {@linkcode PluginGeomCreateApi.brepFromUnion},
+ * {@linkcode PluginGeomCreateApi.brepFromSubtraction} (`a` minus `b`), and
+ * {@linkcode PluginGeomCreateApi.brepFromIntersection}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `a` | {@linkcode BrepHandle} | First solid (the subtraction target) |
+ * | `b` | {@linkcode BrepHandle} | Second solid (the subtraction tool) |
+ */
+export const PluginGeomCreateBrepBooleanArgs = z.object({
+  a: BrepHandle,
+  b: BrepHandle,
+})
+
+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
+>
+
+// Taper scale factor — bounded so a near-zero scale cannot pinch a section
+// into a degenerate sliver the downstream planarity gates would miss.
+const SweepScaleFactor = z.number().finite().min(1e-3).max(1e3)
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromSweep}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ContourHandle} | The cross-section to sweep (hole-free) |
+ * | `path` | {@linkcode Vec3Components}`[]` | The polyline path (≥2 points, finite components; repeating the first point as the last closes it into a ring — closed paths must be flat and straight-segmented and take a straight-edged profile) |
+ * | `options` | `object`? | Optional scale law: `startScale`/`endScale` (linear taper by arc length) or per-point `scales` (mutually exclusive; factors finite, 1e-3..1e3; `scales.length` must equal `path.length`). Optional corner `transition`: `"miter"` (default) or `{ bevel }` (chamfered corners; finite, 1e-3..1e3) |
+ */
+export const PluginGeomCreateBrepFromSweepArgs = z
+  .object({
+    profile: ContourHandle,
+    path: z.array(FiniteVec3Components).min(2),
+    options: z
+      .object({
+        startScale: SweepScaleFactor.optional(),
+        endScale: SweepScaleFactor.optional(),
+        scales: z.array(SweepScaleFactor).optional(),
+        transition: z
+          .union([
+            z.literal("miter"),
+            z.object({ bevel: z.number().finite().min(1e-3).max(1e3) }),
+          ])
+          .optional(),
+      })
+      .optional(),
+  })
+  .superRefine((a, ctx) => {
+    const options = a.options
+    if (!options || options.scales === undefined) return
+    if (options.startScale !== undefined || options.endScale !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "scales is mutually exclusive with startScale/endScale",
+      })
+    }
+    if (options.scales.length !== a.path.length) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "scales must have exactly one entry per path point",
+      })
+    }
+  })
+
+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
+>