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

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

@@ -1,2133 +1,2139 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../../types"
-import {
-  MAX_SPLINE_THROUGH_POINTS,
-  MAX_SPLINE_POLES,
-  MAX_PATH_CURVES,
-  MAX_TWIST_LEVELS,
-  MAX_FILLET_LAW_SAMPLES,
-} from "../../../../massParameters"
-import type { SweepAlongCurveRecordOptions } from "../../../../massParameters"
-import { Vec3Handle, LineHandle, ArcHandle, SplineHandle, CircleHandle, CurveHandle, ProfileHandle, ContourHandle, BrepHandle, FaceHandle, EdgeHandle, Vec3Components } from "../../../../handles"
-
-/** Maximum boundary items one patch may span. */
-export const MAX_PATCH_BOUNDARY_CURVES = 16
-/** Maximum interior points one patch may be pulled through. */
-export const MAX_PATCH_INTERIOR_POINTS = 64
-
-/**
- * An edge named together with the solid it belongs to — an edge handle cannot
- * name its own solid, and one patch may meet two solids. `face` is the adjacent
- * face a tangent patch continues: REQUIRED under `continuity: "tangent"`
- * (a solid edge has two faces — the wall or the top of a rim — and only the
- * caller knows which), ignored otherwise. Owner LAST, like every read that
- * takes `(face, brep)`.
- */
-export type OwnedEdge = { edge: EdgeHandle; brep: BrepHandle; face?: FaceHandle }
-
-/**
- * The trailing bag of {@linkcode PluginGeomCreateApi.brepFromSweepAlongCurve}:
- * the recorded switches plus `rail`, a live curve handle that never enters a
- * record (a record is pure JSON, and a dead handle would not regenerate).
- */
-export type SweepAlongCurveOptions = SweepAlongCurveRecordOptions & { rail?: CurveHandle }
-
-/**
- * Curve creation — construct new geometric curves from point handles (all-handle
- * model, §11).
- *
- * Each method takes point handles ({@linkcode Vec3Handle}) and returns an opaque
- * curve handle ({@linkcode LineHandle}, {@linkcode ArcHandle}, or
- * {@linkcode SplineHandle}) that you pass to query, update, or entity-creation
- * methods. Read geometry back as plain values via the
- * `snaptrude.core.geom.query.*` methods.
- *
- * Accessed via `snaptrude.core.geom.create`.
- */
-export abstract class PluginGeomCreateApi {
-  constructor() {}
-
-  /**
-   * Create a straight line segment between two point handles. Host API call —
-   * returns a handle.
-   *
-   * @param startPoint Start point of the line segment
-   * @param endPoint End point of the line segment
-   * @returns The new line as a {@linkcode LineHandle}
-   *
-   * @examplePrompt Draw a line from point A to point B
-   * @examplePrompt Draw a straight edge between these two points
-   *
-   * @example
-   * ```ts
-   * const line = snaptrude.core.geom.create.line(startPoint, endPoint)
-   * ```
-   */
-  public abstract line(startPoint: Vec3Handle, endPoint: Vec3Handle): PluginApiReturn<LineHandle>
-
-  /**
-   * Create a circular arc from its start, end, centre, and axis point handles.
-   * Host API call — returns a handle.
-   *
-   * @param startPoint Start point of the arc
-   * @param endPoint End point of the arc
-   * @param centrePoint Centre point of the arc
-   * @param axis Axis direction of the arc
-   * @returns The new arc as an {@linkcode ArcHandle}
-   *
-   * @examplePrompt Draw an arc between these two points around a centre
-   * @examplePrompt Add a curved segment from A to B
-   *
-   * @example
-   * ```ts
-   * const arc = snaptrude.core.geom.create.arc(startPoint, endPoint, centrePoint, axis)
-   * ```
-   */
-  public abstract arc(
-    startPoint: Vec3Handle,
-    endPoint: Vec3Handle,
-    centrePoint: Vec3Handle,
-    axis: Vec3Handle,
-  ): PluginApiReturn<ArcHandle>
-
-  /**
-   * Create a circle from a centre point, an axis (plane normal), and a radius.
-   * Host API call — returns a handle. A circle is a closed curve; read it back via
-   * `snaptrude.core.geom.query.circle.*`.
-   *
-   * @param centrePoint Centre point of the circle
-   * @param axis Axis direction (plane normal) of the circle
-   * @param radius Radius of the circle
-   * @returns The new circle as a {@linkcode CircleHandle}
-   *
-   * @examplePrompt Make a circle of radius 2 at this point
-   * @examplePrompt Draw a circular outline 5m across
-   *
-   * @example
-   * ```ts
-   * const circle = snaptrude.core.geom.create.circle(centrePoint, axis, 2)
-   * ```
-   */
-  public abstract circle(
-    centrePoint: Vec3Handle,
-    axis: Vec3Handle,
-    radius: number,
-  ): PluginApiReturn<CircleHandle>
-
-  /**
-   * Create an open NURBS curve passing exactly THROUGH each point, in order
-   * (centripetal Catmull-Rom fit → clamped cubic B-spline; C1-smooth, no cusps
-   * on uneven spacing). Host API call — returns a handle. The points are
-   * interpolated, NOT control points. For a CLOSED smooth loop use
-   * {@linkcode PluginGeomCreateApi.profileFromSplinePoints} — closed splines
-   * exist only as profiles, never as a single curve handle.
-   *
-   * Pure host-side math — the geometry kernel is not loaded. The result is a
-   * {@linkcode CurveHandle}: pass it to `profileFromCurves` alongside lines and
-   * arcs, or read it back via `core.geom.query.curve.*`.
-   *
-   * @param points 3..256 ordered through-points; consecutive points must be distinct
-   * @returns The new open curve as a {@linkcode SplineHandle}
-   * @throws VALIDATION if fewer than 3 points (2 points are a straight line —
-   *   use {@linkcode PluginGeomCreateApi.line}), more than 256 points, or two
-   *   consecutive points coincide
-   *
-   * @examplePrompt Draw a smooth curve through these points
-   * @examplePrompt Make a wavy edge that passes through A, B, C and D
-   * @examplePrompt Freeform curved wall path through these clicks
-   *
-   * # Example
-   * ```ts
-   * const spline = await snaptrude.core.geom.create.splineFromPoints([p0, p1, p2, p3])
-   * // Mixed profile: smooth top, straight closing base
-   * const base = await snaptrude.core.geom.create.line(p3, p0)
-   * const profile = await snaptrude.core.geom.create.profileFromCurves([spline, base])
-   * ```
-   */
-  public abstract splineFromPoints(points: Vec3Handle[]): PluginApiReturn<SplineHandle>
-
-  /**
-   * Create an open NURBS curve DEFINED BY control points — the curve is pulled
-   * TOWARD the interior points, not through them; it starts at the first point
-   * and ends at the last. Knots are computed for you (clamped, uniform) —
-   * there is no knot-vector argument. For a curve that must pass THROUGH given
-   * points use {@linkcode PluginGeomCreateApi.splineFromPoints}.
-   *
-   * A curve made here records as `splinePoles` in a mass recipe and is
-   * re-minted verbatim on edit — so an agent that read a `splinePoles` curve
-   * back off a mass can move its poles and rebuild the mass with
-   * `design.update.parameters`. Pure host-side math — the geometry kernel is
-   * not loaded, and nothing is created in the scene. An edge's control points
-   * rebuild the same curve here only when its knots are clamped uniform.
-   *
-   * @param controlPoints 3..512 control points ({@linkcode Vec3Handle}s), in order
-   * @param options.degree 2 or 3; default `min(3, controlPoints.length - 1)`
-   * @returns The new open curve as a {@linkcode SplineHandle}
-   * @throws VALIDATION when fewer than `degree + 1` points are given, two
-   *   consecutive points coincide, or `degree` is not 2 or 3
-   *
-   * @examplePrompt Draw a smooth curve controlled by these four points
-   *
-   * # Example
-   * ```ts
-   * const curve = await snaptrude.core.geom.create.splineFromControlPoints([p0, p1, p2, p3])
-   * // Quadratic instead of the default cubic
-   * const tighter = await snaptrude.core.geom.create.splineFromControlPoints(
-   *   [p0, p1, p2, p3],
-   *   { degree: 2 },
-   * )
-   * ```
-   */
-  public abstract splineFromControlPoints(
-    controlPoints: Vec3Handle[],
-    options?: { degree?: number },
-  ): PluginApiReturn<SplineHandle>
-
-  /**
-   * Drops a curve onto a face along the face's normal and returns the curves it
-   * lands on — one per connected run, empty when the curve misses the face
-   * entirely. Host API call — returns new curve handles; the inputs are
-   * read-only. No lengths are involved: the result is a curve in the same
-   * internal length units as its inputs.
-   *
-   * @param curve The curve to project
-   * @param face The face to project onto
-   * @param faceBrep The solid `face` belongs to — a face handle cannot name its
-   *   own solid
-   * @returns The projected curves as {@linkcode CurveHandle}`[]`
-   * @throws VALIDATION if `face` is not a face of `faceBrep`, or the curve's
-   *   midpoint lies on the face's surface (there is no drop direction there)
-   * @throws OPERATION_FAILED if the kernel could not project the curve
-   */
-  public abstract curvesFromProjection(
-    curve: CurveHandle,
-    face: FaceHandle,
-    faceBrep: BrepHandle,
-  ): PluginApiReturn<CurveHandle[]>
-
-  /**
-   * Create a closed profile from an ordered list of point handles connected by
-   * line segments (last auto-connected to first). Host API call — returns a handle.
-   *
-   * @param points Ordered vertex handles of the profile
-   * @returns The new profile as a {@linkcode ProfileHandle}
-   *
-   * @examplePrompt Draw a closed polygon through these corner points
-   * @examplePrompt Create an L-shaped outline from a list of points
-   *
-   * @example
-   * ```ts
-   * const profile = snaptrude.core.geom.create.profileFromLinePoints(points)
-   * ```
-   */
-  public abstract profileFromLinePoints(points: Vec3Handle[]): PluginApiReturn<ProfileHandle>
-
-  /**
-   * Create a profile from an ordered list of curve handles forming a closed loop.
-   * Host API call — returns a handle.
-   *
-   * @param curves Ordered curve handles forming a closed loop
-   * @returns The new profile as a {@linkcode ProfileHandle}
-   *
-   * @examplePrompt Join these lines and arcs into one closed shape
-   *
-   * @example
-   * ```ts
-   * const profile = snaptrude.core.geom.create.profileFromCurves([line, arc])
-   * ```
-   */
-  public abstract profileFromCurves(curves: CurveHandle[]): PluginApiReturn<ProfileHandle>
-
-  /**
-   * Create a CLOSED smooth profile passing through each point, in order, with
-   * the loop closed smoothly back from the last point to the first (do NOT
-   * repeat the first point). Host API call — returns a handle. This is the
-   * closed counterpart of {@linkcode PluginGeomCreateApi.splineFromPoints} and
-   * the one-call route from points to an extrudable outline: wrap in
-   * `contourFromProfile` and extrude/loft/sweep as usual.
-   *
-   * The whole loop is smooth — this call takes no mixed straight/spline input.
-   * For a profile that is part curve and part straight, build the pieces with
-   * `splineFromPoints` + `line` and join them with
-   * {@linkcode PluginGeomCreateApi.profileFromCurves}.
-   *
-   * @param points 3..256 ordered through-points of the loop (first point NOT repeated)
-   * @returns The new closed profile as a {@linkcode ProfileHandle}
-   * @throws VALIDATION if fewer than 3 points, more than 256 points,
-   *   consecutive points coincide (including last→first), or the loop
-   *   self-intersects
-   *
-   * @examplePrompt Make a blob-shaped floor plate through these points
-   * @examplePrompt Organic curved outline through these corners
-   * @examplePrompt Freeform podium profile
-   *
-   * # Example
-   * ```ts
-   * const profile = await snaptrude.core.geom.create.profileFromSplinePoints([p0, p1, p2, p3, p4])
-   * const contour = await snaptrude.core.geom.create.contourFromProfile(profile)
-   * const brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)
-   * const podium = await snaptrude.design.create.massFromBrep(brep, "Podium")
-   * ```
-   */
-  public abstract profileFromSplinePoints(points: Vec3Handle[]): PluginApiReturn<ProfileHandle>
-
-  /**
-   * Create an axis-aligned **rectangle** profile in the XZ plane,
-   * `width` × `depth`, centred at `center` (defaults to the origin). Host API
-   * call — returns a handle.
-   *
-   * Pair with `design.create.space` / `design.create.spaces` to author a rectangular
-   * (box) space — there is no dedicated rectangular-space creator; build the profile
-   * here, then extrude it.
-   *
-   * @param width Extent along X
-   * @param depth Extent along Z
-   * @param center Optional centre point (default origin)
-   * @returns The new rectangle profile as a {@linkcode ProfileHandle}
-   *
-   * @examplePrompt Draw a 4m by 3m rectangle
-   * @examplePrompt Make a rectangular outline for a room footprint
-   *
-   * @example
-   * ```ts
-   * const rect = snaptrude.core.geom.create.profileRect(4, 3)
-   * const contour = snaptrude.core.geom.create.contourFromProfile(rect)
-   * const space = snaptrude.design.create.space(contour, 3)
-   * ```
-   */
-  public abstract profileRect(
-    width: number,
-    depth: number,
-    center?: Vec3Handle,
-  ): PluginApiReturn<ProfileHandle>
-
-  /**
-   * Create a contour (an outer profile loop, no holes). Host API call — returns a handle.
-   *
-   * @param outer The outer boundary loop
-   * @returns The new contour as a {@linkcode ContourHandle}
-   * @example
-   * ```ts
-   * const contour = snaptrude.core.geom.create.contourFromProfile(outer)
-   * ```
-   */
-  public abstract contourFromProfile(outer: ProfileHandle): PluginApiReturn<ContourHandle>
-
-  /**
-   * Create a contour from an outer profile plus zero or more inner profiles (holes).
-   * Host API call — returns a handle.
-   *
-   * @param outer The outer boundary loop
-   * @param holes Optional inner hole loops
-   * @returns The new contour as a {@linkcode ContourHandle}
-   *
-   * @examplePrompt Make a shape with a hole in the middle
-   * @examplePrompt Cut a courtyard opening out of this floor outline
-   *
-   * @example
-   * ```ts
-   * const contour = snaptrude.core.geom.create.contourFromProfiles(outer, [hole])
-   * ```
-   */
-  public abstract contourFromProfiles(
-    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 in internal length units (non-zero; negative extrudes opposite to `direction`)
-   * @param options Optional twist and taper, both about `direction` through the
-   *   base contour's centroid. `twistInDegrees` — total rotation base → top in
-   *   DEGREES (an angle: never scaled by the project's length unit), positive
-   *   turning the top CLOCKWISE seen from the far end of `direction` looking
-   *   back at the base — for the usual upward extrusion, the plan view;
-   *   `topScale` — the top outline's scale, a ratio (1 = no taper); `levels` —
-   *   how many sections to build through, a count (2..64; each step may turn
-   *   at most 22.5°). Leave `levels` out
-   *   and the host resolves one and writes it into the record, so the mass
-   *   regenerates identically ever after. An extrusion without twist or
-   *   taper (no `options`, or zero twist and a `topScale` of 1) is
-   *   built exactly as before these options existed.
-   * @returns The new solid as a {@linkcode BrepHandle}
-   * @throws if the extrusion is degenerate (zero amount, zero direction, or a
-   *   direction lying in the plane of the contour) or the contour cannot be
-   *   extruded into a valid solid
-   * @throws VALIDATION if `twistInDegrees` is not finite or turns more than
-   *   1440°, `topScale` is not a positive finite ratio, `levels` is outside
-   *   2..64 or too few for the twist (more than 22.5° per step), a twist is
-   *   asked of a `direction` that is not the contour's normal, the contour has
-   *   holes under a twist or taper, or a scaled section self-intersects
-   *
-   * @examplePrompt Extrude this profile 3 metres up
-   * @examplePrompt Make a solid by extruding this outline
-   * @examplePrompt Create a cylinder from a circle profile
-   * @examplePrompt Extrude this floor plate 40m up with a 90 degree twist
-   * @examplePrompt Taper this tower to 60 percent of its footprint at the top
-   *
-   * # 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,
-    options?: { twistInDegrees?: number; topScale?: number; levels?: number },
-  ): PluginApiReturn<BrepHandle>
-
-  /**
-   * Stretches a surface across a closed loop of boundary curves and thickens it
-   * into a SOLID in one call — a roof over four curves, a canopy between two
-   * rails, a blend across a gap. `thickness` is in internal length units and is
-   * required: only solids reach the canvas, and there is no separate surface
-   * object to keep. Pass edges as `{ edge, brep, face }` with
-   * `continuity: "tangent"` to leave the named face smoothly. The result carries
-   * NO recipe (`design.query.getParameters` returns `null`) — label it when you
-   * commit it, because the label is all the provenance there is.
-   *
-   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
-   * of MB — expect a pause of seconds).
-   *
-   * @param boundary 3..16 items forming ONE closed loop (ends meeting within
-   *   tolerance): a curve, or an edge named WITH the solid it belongs to
-   *   ({@linkcode OwnedEdge}) — an edge handle cannot name its own solid, and
-   *   one patch may meet two solids. Read scene breps with
-   *   `design.query.geometry.getBrep(x, { frame: "world" })` so every item is in
-   *   one frame.
-   * @param thickness Solid thickness in internal length units (> 0)
-   * @param options `interiorPoints` pull the surface through them (≤ 64, plain
-   *   `{x, y, z}` in the same frame as the boundary). `continuity` —
-   *   `"position"` (default) or `"tangent"`: every boundary item must then be an
-   *   edge item that also names the `face` to continue (a solid edge has two
-   *   faces — the wall or the top of a rim). `side` — `"below"` (default) or
-   *   `"above"`: which side of the boundary the solid grows to.
-   * @returns The thickened patch as a new {@linkcode BrepHandle}
-   * @throws VALIDATION if the boundary is not one closed loop (the message names
-   *   the gap and its size), a count cap is exceeded, `thickness` is not
-   *   positive, `continuity: "tangent"` is used with a curve item or with an
-   *   edge item that names no `face` (the message names the edge's two candidate
-   *   faces), or a `face` is not adjacent to its `edge`
-   * @throws OPERATION_FAILED if the kernel could not fill the boundary, the
-   *   filled surface misses its own boundary by more than 0.254 mm (the message
-   *   carries the measured gap), or the thicken produced no solid
-   *
-   * @examplePrompt Patch a roof over these four boundary curves, 250 mm thick
-   * @examplePrompt Span a canopy between these two curved rails, 300 mm thick
-   *
-   * # Example
-   * ```ts
-   * // A roof over four curves
-   * const roof = await snaptrude.core.geom.create.brepFromPatch(
-   *   [curveA, curveB, curveC, curveD],
-   *   0.984, // 250 mm
-   * )
-   * const mass = await snaptrude.design.create.massFromBrep(roof, "Roof patch")
-   * ```
-   *
-   * ```ts
-   * // A canopy between two towers' rims, leaving every wall it meets smoothly:
-   * // with `continuity: "tangent"` EVERY item is an edge naming its face.
-   * const canopy = await snaptrude.core.geom.create.brepFromPatch(
-   *   [
-   *     { edge: rimA, brep: towerA, face: wallA },
-   *     { edge: sideA, brep: towerA, face: endA },
-   *     { edge: rimB, brep: towerB, face: wallB },
-   *     { edge: sideB, brep: towerB, face: endB },
-   *   ],
-   *   1.181, // 300 mm
-   *   { continuity: "tangent" },
-   * )
-   * ```
-   */
-  public abstract brepFromPatch(
-    boundary: (CurveHandle | OwnedEdge)[],
-    thickness: number,
-    options?: {
-      interiorPoints?: Vec3Components[]
-      continuity?: "position" | "tangent"
-      side?: "below" | "above"
-    },
-  ): 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 fallback); 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). Any count is accepted; a loft of more
-   *   than 32 sections counting the bottom and the top still builds but
-   *   carries no parameter record (records are capped, calls are not)
-   * @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 fallback for hole-free straight-edged pairs).
-   *   `{ compatibility: "strict", seamAlignment: "authored" }` reproduces
-   *   pre-0.9.4 lofting exactly. `smoothing` — `"ruled"` (default) keeps the
-   *   straight-sided behaviour described above; `"smooth"` lofts every
-   *   section in ONE kernel pass, so the sides curve continuously through the
-   *   intermediates instead of creasing at each one (a vase, a curved tower —
-   *   the sections must still be planar and hole-free).
-   * @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
-   * @examplePrompt Loft these three outlines with smoothly curving sides
-   *
-   * # 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"
-      smoothing?: "ruled" | "smooth"
-    },
-  ): 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 edges of a solid with a constant radius. Host API call —
-   * returns a new {@linkcode BrepHandle}; the input brep is read-only.
-   *
-   * Works on curved solids: edges may be straight, circular or spline, and
-   * adjacent edges (corner blends) are allowed. To pick a **rim** — the circle
-   * where a cylinder meets a flat cap — walk the edges and keep the ones whose
-   * two faces are a `cylinder` and a `plane`:
-   * `core.geom.query.brep.listEdges(brep)` → per edge
-   * `core.geom.query.edge.listFaces(edge)` → `core.geom.query.face.getSurfaceKind`
-   * on both faces. (`core.geom.query.brep.listEdgesBetween` takes two VERTEX
-   * indices — it is NOT a face-pair lookup.) For one cap's rim only, the
-   * shorter walk is: find the cap (call `getSurfaceKind` on each face from
-   * `brep.listFaces`), then `core.geom.query.face.listEdges(capFace)`.
-   *
-   * When the input brep carries a creation recipe, the result carries it too,
-   * with this operation appended to `operations`; `design.create.massFromBrep`
-   * then keeps the mass editable through `design.update.parameters`.
-   *
-   * 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 edges to fillet (one or more, all on `brep`, no
-   *   duplicates; more than 64 still fillets but the result carries no
-   *   parameter record)
-   * @param radius Fillet radius in internal length units (positive, finite) —
-   *   the radius at the START of the blend with `endRadius`; unused with
-   *   `radii` (the table is the whole law — pass its first row's radius)
-   * @param options Optional VARIABLE blend, in one of two forms, each naming
-   *   exactly ONE edge: the law belongs to the whole tangent chain that edge
-   *   lies on, and it is measured from that edge's start. `endRadius` —
-   *   the radius at the far end, in internal length units, interpolated
-   *   linearly along the chain; on a closed rim it must equal `radius` (0 and
-   *   1 are the same point) — use `radii` there. `radii` — a sampled law instead:
-   *   `position` is normalised ARC LENGTH along the chain (a ratio 0..1, never
-   *   converted), `radius` is internal length units; 2..32 rows with strictly
-   *   increasing `position`; before the first row and after the last the
-   *   radius is held constant. On a closed rim 0 and 1 are the same point, so
-   *   give them the same radius and put the variation in the interior rows. The two
-   *   forms are mutually exclusive; without either, the fillet has one constant
-   *   radius.
-   * @returns The filleted solid as a new {@linkcode BrepHandle}
-   * @throws VALIDATION if `edges` is empty or holds a duplicate, `radius` is
-   *   not a positive finite number, an edge is not on `brep`, or an edge has no
-   *   crease to round — it is a seam of a closed face, or it lies between two
-   *   patches of one smooth surface; for a variable blend, if `endRadius` and
-   *   `radii` are both given, more than one edge is passed, a `radii` table is
-   *   outside 2..32 rows or its positions do not strictly increase within
-   *   0..1, or the law's two ends differ on a closed rim (an `endRadius`
-   *   other than `radius`, or a `radii` table whose first and last radii
-   *   differ)
-   * @throws PRECONDITION_FAILED if an edge could not be located on the kernel
-   *   solid after healing (select a different edge, or fillet before the
-   *   operation that curved the solid), or the kernel could not blend the edge
-   *   named in the message (reduce the radius or drop that edge)
-   * @throws OPERATION_FAILED if the kernel or the translation fails, or the
-   *   result is non-manifold, splits into several solids, or contains a surface
-   *   Snaptrude cannot represent
-   *
-   * @examplePrompt Round the rim of the column with 200 mm
-   * @examplePrompt Soften where the dome meets the wall
-   * @examplePrompt Fillet the corners of the podium with a 0.5m radius
-   * @examplePrompt Soften the vertical edges of this tower
-   * @examplePrompt Blend this edge from 200mm at one end to 600mm at the other
-   * @examplePrompt Round this rim wider at the back than at the front
-   *
-   * # Example
-   * ```ts
-   * // Rim = every edge between the cylinder side and a plane cap
-   * const edges = await snaptrude.core.geom.query.brep.listEdges(column)
-   * const rim = []
-   * for (const edge of edges) {
-   *   const faces = await snaptrude.core.geom.query.edge.listFaces(edge)
-   *   const kinds = await Promise.all(
-   *     faces.map((f) => snaptrude.core.geom.query.face.getSurfaceKind(f)),
-   *   )
-   *   if (kinds.includes("cylinder") && kinds.includes("plane")) rim.push(edge)
-   * }
-   * const rounded = await snaptrude.core.geom.create.brepFromFillet(column, rim, 0.787) // 200 mm
-   * ```
-   */
-  public abstract brepFromFillet(
-    brep: BrepHandle,
-    edges: EdgeHandle[],
-    radius: number,
-    options?: { endRadius?: number; radii?: { position: number; 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.
-   *
-   * Works on curved solids: a sphere offsets to a sphere, a torus to a torus,
-   * a cylinder to a cylinder. There is nothing to select — the whole solid is
-   * offset.
-   *
-   * When the input brep carries a creation recipe, the result carries it too,
-   * with this operation appended to `operations`; `design.create.massFromBrep`
-   * then keeps the mass editable through `design.update.parameters`.
-   *
-   * 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 or the translation fails, or the
-   *   result is non-manifold, splits into several solids, or contains a surface
-   *   Snaptrude cannot represent (an offset free-form NURBS surface may have no
-   *   exact representation — the model is left unchanged). A distance too
-   *   large for the solid is reported here, with a hint asking for a smaller
-   *   one. There is no per-face refusal: the whole call fails, and the error
-   *   names no face
-   *
-   * @examplePrompt Thicken the torus ring by 100 mm
-   * @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.
-   *
-   * Works on curved solids: the open faces may be spherical, cylindrical,
-   * conical, toroidal or free-form patches, not only flat ones. To open the
-   * flat base of a dome, check every face first —
-   * `core.geom.query.brep.listFaces` then
-   * `core.geom.query.face.getSurfaceKind` on each — and keep the `"plane"`
-   * one. A closed curved surface is stored as several patches (a sphere as
-   * lunes), so opening "the sphere" may mean passing several faces.
-   *
-   * When the input brep carries a creation recipe, the result carries it too,
-   * with this operation appended to `operations`; `design.create.massFromBrep`
-   * then keeps the mass editable through `design.update.parameters`.
-   *
-   * 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 (one or more, all on
-   *   `brep`, no duplicates; more than 32 still shells but the result carries
-   *   no parameter record)
-   * @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 or holds a duplicate, 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 or the translation fails, or the
-   *   result is non-manifold, splits into several solids, or contains a surface
-   *   Snaptrude cannot represent. A thickness too large for the solid is
-   *   reported here, with a hint asking for one below half the smallest span.
-   *   There is no per-face refusal: the whole call fails, and the error
-   *   names no face
-   *
-   * @examplePrompt Hollow the dome into a 300 mm shell, open at the base
-   * @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
-   * // Open the dome at its flat base: the one face whose surface is a plane
-   * const faces = await snaptrude.core.geom.query.brep.listFaces(dome)
-   * const base = []
-   * for (const face of faces) {
-   *   if ((await snaptrude.core.geom.query.face.getSurfaceKind(face)) === "plane") base.push(face)
-   * }
-   * const hollow = await snaptrude.core.geom.create.brepFromShell(dome, base, 1.181) // 300 mm
-   * ```
-   */
-  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[]>
-
-  /**
-   * Cuts a solid with a FACE of another solid — the curved twin of
-   * {@linkcode PluginGeomCreateApi.brepsFromSplit}, which cuts with a plane.
-   * Host API call — returns new {@linkcode BrepHandle}s; both inputs are
-   * read-only. BOTH breps must be in the same frame: read scene masses with
-   * `design.query.geometry.getBrep(x, { frame: "world" })` (the default is each
-   * mass's own local frame, and two masses have two). The pieces come back in
-   * DESCENDING volume order; pick the one you want with
-   * `core.geom.query.brep.getCentroid` or `getVolume` and commit it. A piece
-   * carries no recipe — label it.
-   *
-   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
-   * of MB — expect a pause of seconds).
-   *
-   * @param brep The solid to cut
-   * @param toolFace The cutting face, read-only
-   * @param toolBrep The solid `toolFace` belongs to — a face handle cannot name
-   *   its own solid
-   * @returns The resulting pieces as {@linkcode BrepHandle}`[]`, largest first
-   * @throws VALIDATION if `toolFace` is not a face of `toolBrep`, `toolBrep` IS
-   *   `brep`, or the cut produced a single part — the surface does not pass all
-   *   the way through (extend it past the mass on every side, and check both
-   *   breps were read in the same frame)
-   * @throws OPERATION_FAILED if the kernel could not split the solid
-   *
-   * @examplePrompt Cut this mass with the curved roof surface and keep the lower part
-   *
-   * # Example
-   * ```ts
-   * const target = await snaptrude.design.query.geometry.getBrep(tower, { frame: "world" })
-   * const tool = await snaptrude.design.query.geometry.getBrep(roof, { frame: "world" })
-   * const [toolFace] = await snaptrude.core.geom.query.brep.listFaces(tool)
-   * const pieces = await snaptrude.core.geom.create.brepsFromSplitByFace(target, toolFace, tool)
-   * ```
-   */
-  public abstract brepsFromSplitByFace(
-    brep: BrepHandle,
-    toolFace: FaceHandle,
-    toolBrep: BrepHandle,
-  ): PluginApiReturn<BrepHandle[]>
-
-  /**
-   * Bevels the given edges of a solid with a symmetric planar cut. Host API
-   * call — returns a new {@linkcode BrepHandle}; the input brep is read-only.
-   *
-   * Works on curved solids: edges may be straight, circular or spline, and
-   * adjacent edges are allowed. Pick edges the same way as for
-   * {@linkcode PluginGeomCreateApi.brepFromFillet} — `brep.listEdges`, then
-   * `core.geom.query.edge.listFaces` and `core.geom.query.face.getSurfaceKind`
-   * on both faces of each edge. (`core.geom.query.brep.listEdgesBetween` takes
-   * two VERTEX indices — it is NOT a face-pair lookup.) Chamfering a cylinder's
-   * rim yields a cone patch where a fillet would yield a torus patch.
-   *
-   * When the input brep carries a creation recipe, the result carries it too,
-   * with this operation appended to `operations`; `design.create.massFromBrep`
-   * then keeps the mass editable through `design.update.parameters`.
-   *
-   * 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 edges to chamfer (one or more, all on `brep`, no
-   *   duplicates; more than 64 still chamfers but the result carries no
-   *   parameter record)
-   * @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 or holds a duplicate, `distance` is
-   *   not a positive finite number, an edge is not on `brep`, or an edge has no
-   *   crease to cut — it is a seam of a closed face, or it lies between two
-   *   patches of one smooth surface
-   * @throws PRECONDITION_FAILED if an edge could not be located on the kernel
-   *   solid after healing (select a different edge, or chamfer before the
-   *   operation that curved the solid)
-   * @throws OPERATION_FAILED if the kernel or the translation fails, or the
-   *   result is non-manifold, splits into several solids, or contains a surface
-   *   Snaptrude cannot represent. A distance larger than an adjacent face
-   *   is reported here, with a hint asking for a smaller one. Unlike
-   *   {@linkcode PluginGeomCreateApi.brepFromFillet}, the kernel does not say
-   *   which edge failed a chamfer, so the error names no edge
-   *
-   * @examplePrompt Chamfer the top edge of the cylinder
-   * @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 a sharp mitred bend; `"round"`
-   * carries the section around each turning corner on a tangent circular arc,
-   * so the corner patch is a real curved surface (geometrically cylindrical;
-   * `getSurfaceKind` reports it as `"spline"`) rather than a
-   * flat cut (open paths only — `"round"` on a closed ring path is refused);
-   * `{ 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 a varying scale only accepts straight paths, so it never meets
-   * 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 or more;
-   *   repeat the first point as the last to close the path into a ring; more
-   *   than 512 points still sweeps but the result carries no parameter record)
-   * @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),
-   *   `"round"` (arc-carried corners — curved corner patches; open paths
-   *   only) 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 bevelled corners take from it or a corner nearly doubles
-   *   back so its bevel collapses (the errors name the corner)
-   * @throws PRECONDITION_FAILED if `transition` is `"round"` and the path is
-   *   closed — round corners work on open paths only; use `"miter"` or
-   *   `{ bevel }` on a ring
-   * @throws OPERATION_FAILED if the kernel cannot sweep the profile into a
-   *   valid solid — including a `"round"` corner whose arc does not fit its
-   *   legs, which is not pre-checked and so is not named per corner
-   *
-   * @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
-   * @examplePrompt Sweep this handrail with rounded corners at the bends
-   *
-   * # 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" | "round" | { bevel: number }
-    },
-  ): PluginApiReturn<BrepHandle>
-
-  /**
-   * Sweeps a cross-section along a SMOOTH path — splines, arcs and lines chained
-   * end to end — with control of how the profile turns.
-   * {@linkcode PluginGeomCreateApi.brepFromSweep} takes a polyline path; this
-   * takes curves. Host API call — returns a new {@linkcode BrepHandle}; the
-   * inputs are read-only. Records as `sweepAlongCurve`, so the orientation stays
-   * editable through `design.update.parameters`. The properties panel shows it
-   * read-only, because it is a text value, not a number. A railed sweep records
-   * nothing (`getParameters` answers `null`).
-   *
-   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
-   * of MB — expect a pause of seconds).
-   *
-   * @param profile Hole-free cross-section contour; placed at the first curve's start
-   * @param path 1..64 curves, ordered, meeting end to end within tolerance
-   * @param options `orientation` — `"upright"` (default) keeps the profile's up
-   *   aligned with world up (ducts, handrails, ribbons that must not roll);
-   *   `"frenet"` lets it roll with the path's curvature; `"fixed"` carries the
-   *   authored frame along unchanged, which is a pure translation — use it to
-   *   bend a footprint along an arc. `rail` is a second guide curve.
-   * @returns The swept solid as a new {@linkcode BrepHandle}
-   * @throws VALIDATION if the path curves are not connected, the path is closed,
-   *   the profile has holes, the first tangent lies in the profile plane, the
-   *   path runs vertically under `"upright"` (that frame is undefined there —
-   *   the message names the run and points at `"frenet"`), the path turns
-   *   parallel to the profile under `"fixed"`, `rail` is closed, or `rail` and
-   *   `orientation` are both given
-   * @throws OPERATION_FAILED if the kernel could not sweep the profile — a
-   *   self-intersection on a tight bend
-   *
-   * @examplePrompt Sweep a 600x400 duct along this curved route and keep it upright
-   * @examplePrompt Run this handrail along the curved stair edge
-   * @examplePrompt Bend this footprint along the arc
-   *
-   * # Example
-   * ```ts
-   * const route = await snaptrude.core.geom.create.splineFromPoints(points)
-   * const duct = await snaptrude.core.geom.create.brepFromSweepAlongCurve(profile, [route], {
-   *   orientation: "upright",
-   * })
-   * ```
-   */
-  public abstract brepFromSweepAlongCurve(
-    profile: ContourHandle,
-    path: CurveHandle[],
-    options?: SweepAlongCurveOptions,
-  ): 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, and segments may run at any angle to the axis: an
-   * inclined segment revolves into a cone, an arc into a sphere or torus
-   * section. This is the general route to domes, vases, columns and rotundas.
-   *
-   * Two rules bind the axis to the profile. First, the axis line must lie IN
-   * the profile's plane or run parallel to it — a revolution turns a planar
-   * section about a line drawn in that same plane; a parallel axis offset out
-   * of the plane is judged by its projection into the plane (the result is a
-   * hollow ring). A skew axis is refused: move the axis into the profile's
-   * plane. Second, within that plane the whole profile stays on ONE side of
-   * the axis.
-   * Vertices and whole segments may lie ON the axis — that is how a dome's
-   * pole and a cylinder's inner edge are authored — but no part of the profile
-   * may cross to the other side, which would sweep a self-intersecting solid.
-   *
-   * 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], a coordinate is not finite, or the profile crosses the
-   *   axis (the message names the offending segment — keep the whole profile
-   *   on one side; points may touch the axis but not cross it)
-   * @throws PRECONDITION_FAILED if the axis is skew to the profile's plane
-   *   (neither in it nor parallel to it; the message asks you to move the axis
-   *   into the plane of the profile)
-   * @throws OPERATION_FAILED if the kernel cannot revolve the profile into a
-   *   valid solid
-   *
-   * @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
-   * @examplePrompt Make a dome by revolving a quarter-circle about the vertical axis
-   * @examplePrompt Turn this curved outline into a vase
-   *
-   * # Example
-   * ```ts
-   * // A cylinder: revolve a 2m-wide, 3m-tall rectangle about the Y axis at
-   * // its edge — the left edge sits ON the axis, which is legal.
-   * 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>
-
-  /**
-   * Create a solid **sphere** B-rep (boundary representation: the solid's
-   * exact faces, edges and vertices) from a centre and radius. Host API call
-   * — returns a {@linkcode BrepHandle}; commit it to the scene with
-   * `design.create.massFromBrep`. The result carries an exact spherical
-   * surface (not a faceted approximation) and a creation recipe — read the
-   * committed mass's parameters back with `design.query.getParameters` and edit
-   * them with `design.update.parameters`.
-   *
-   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
-   * of MB — expect a pause of seconds).
-   *
-   * @param centre Sphere centre as plain `{x, y, z}` components (internal length units)
-   * @param radius Sphere radius (> 0, internal length units)
-   * @returns The new solid as a {@linkcode BrepHandle}
-   * @throws VALIDATION if `radius` is not a positive finite number or a
-   *   coordinate is not finite
-   *
-   * @examplePrompt Create a sphere of radius 5 at the origin
-   * @examplePrompt Add a 3m ball on top of the tower
-   *
-   * # Example
-   * ```ts
-   * const brep = await snaptrude.core.geom.create.brepFromSphere({ x: 0, y: 5, z: 0 }, 5)
-   * const mass = await snaptrude.design.create.massFromBrep(brep, "Sphere")
-   * ```
-   */
-  public abstract brepFromSphere(
-    centre: Vec3Components,
-    radius: number,
-  ): PluginApiReturn<BrepHandle>
-
-  /**
-   * Create a solid **cylinder** B-rep from its bottom-cap centre, axis
-   * direction, radius and height. Host API call — returns a
-   * {@linkcode BrepHandle}; commit with `design.create.massFromBrep`. The
-   * bottom cap sits AT `base` and the solid extends `height` along `axis` —
-   * place `base` on the floor and use axis `{x: 0, y: 1, z: 0}` for an upright
-   * column. Carries a creation recipe (radius, height), editable through
-   * `design.update.parameters`.
-   *
-   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
-   * of MB — expect a pause of seconds).
-   *
-   * @param base Centre of the bottom cap as plain `{x, y, z}` components
-   * @param axis Axis direction as plain `{x, y, z}` components (non-zero, normalised by the host)
-   * @param radius Cylinder radius (> 0)
-   * @param height Cylinder height along `axis` (> 0)
-   * @returns The new solid as a {@linkcode BrepHandle}
-   * @throws VALIDATION if `radius`/`height` are not positive finite numbers or
-   *   `axis` is zero-length
-   *
-   * @examplePrompt Create a cylinder 2m across and 4m tall
-   * @examplePrompt Add a circular column here
-   *
-   * # Example
-   * ```ts
-   * const brep = await snaptrude.core.geom.create.brepFromCylinder(
-   *   { x: 0, y: 0, z: 0 },
-   *   { x: 0, y: 1, z: 0 },
-   *   1,
-   *   4,
-   * )
-   * const column = await snaptrude.design.create.massFromBrep(brep, "Column")
-   * ```
-   */
-  public abstract brepFromCylinder(
-    base: Vec3Components,
-    axis: Vec3Components,
-    radius: number,
-    height: number,
-  ): PluginApiReturn<BrepHandle>
-
-  /**
-   * Create a solid **cone or frustum** B-rep: bottom-cap centre, axis, base
-   * radius, height, and an optional top radius (default 0 — a full cone to a
-   * point; > 0 — a frustum / tapered column). Host API call — returns a
-   * {@linkcode BrepHandle}; commit with `design.create.massFromBrep`. Carries
-   * a creation recipe (radii + height), editable through `design.update.parameters`.
-   *
-   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
-   * of MB — expect a pause of seconds).
-   *
-   * @param base Centre of the bottom cap as plain `{x, y, z}` components
-   * @param axis Axis direction as plain `{x, y, z}` components (non-zero, normalised by the host)
-   * @param baseRadius Radius at the base (> 0)
-   * @param height Height along `axis` (> 0)
-   * @param topRadius Optional radius at the top (≥ 0, ≠ `baseRadius`; default 0 = apex)
-   * @returns The new solid as a {@linkcode BrepHandle}
-   * @throws VALIDATION if radii/height are invalid, `topRadius === baseRadius`
-   *   (that is a cylinder — use {@linkcode PluginGeomCreateApi.brepFromCylinder}),
-   *   or `axis` is zero-length
-   *
-   * @examplePrompt Create a cone roof 4m wide and 3m tall
-   * @examplePrompt Make a tapered column narrowing from 1m to 0.6m
-   *
-   * # Example
-   * ```ts
-   * const roof = await snaptrude.core.geom.create.brepFromCone(
-   *   { x: 0, y: 9, z: 0 },
-   *   { x: 0, y: 1, z: 0 },
-   *   2,
-   *   3,
-   * )
-   * ```
-   */
-  public abstract brepFromCone(
-    base: Vec3Components,
-    axis: Vec3Components,
-    baseRadius: number,
-    height: number,
-    topRadius?: number,
-  ): PluginApiReturn<BrepHandle>
-
-  /**
-   * Create a solid **torus** (ring / donut) B-rep from its centre, plane
-   * normal, ring radius and tube radius. Host API call — returns a
-   * {@linkcode BrepHandle}; commit with `design.create.massFromBrep`.
-   * `majorRadius` is centre-to-tube-centre; `minorRadius` is the tube's own
-   * radius and must be strictly smaller. Carries a creation recipe, editable
-   * through `design.update.parameters`.
-   *
-   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
-   * of MB — expect a pause of seconds).
-   *
-   * @param centre Torus centre as plain `{x, y, z}` components
-   * @param axis Plane normal of the ring as plain `{x, y, z}` components (non-zero)
-   * @param majorRadius Ring radius, centre to tube centre (> 0)
-   * @param minorRadius Tube radius (> 0 and < `majorRadius` — a self-intersecting torus is rejected)
-   * @returns The new solid as a {@linkcode BrepHandle}
-   * @throws VALIDATION if a radius is invalid, `minorRadius >= majorRadius`,
-   *   or `axis` is zero-length
-   *
-   * @examplePrompt Create a donut-shaped ring 10m across with a 1m tube
-   * @examplePrompt Add a torus canopy around the tower
-   *
-   * # Example
-   * ```ts
-   * const ring = await snaptrude.core.geom.create.brepFromTorus(
-   *   { x: 0, y: 6, z: 0 },
-   *   { x: 0, y: 1, z: 0 },
-   *   5,
-   *   1,
-   * )
-   * ```
-   */
-  public abstract brepFromTorus(
-    centre: Vec3Components,
-    axis: Vec3Components,
-    majorRadius: number,
-    minorRadius: number,
-  ): PluginApiReturn<BrepHandle>
-}
-
-/**
- * Arguments for {@linkcode PluginGeomCreateApi.line}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `startPoint` | {@linkcode Vec3Handle} | Start point of the line segment |
- * | `endPoint` | {@linkcode Vec3Handle} | End point of the line segment |
- */
-export const PluginGeomCreateLineArgs = z.object({
-  startPoint: Vec3Handle,
-  endPoint: Vec3Handle,
-})
-
-export type PluginGeomCreateLineArgs = z.infer<typeof PluginGeomCreateLineArgs>
-
-/**
- * Arguments for {@linkcode PluginGeomCreateApi.arc}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `startPoint` | {@linkcode Vec3Handle} | Start point of the arc |
- * | `endPoint` | {@linkcode Vec3Handle} | End point of the arc |
- * | `centrePoint` | {@linkcode Vec3Handle} | Centre point of the arc |
- * | `axis` | {@linkcode Vec3Handle} | Axis direction of the arc |
- */
-export const PluginGeomCreateArcArgs = z.object({
-  startPoint: Vec3Handle,
-  endPoint: Vec3Handle,
-  centrePoint: Vec3Handle,
-  axis: Vec3Handle,
-})
-
-export type PluginGeomCreateArcArgs = z.infer<typeof PluginGeomCreateArcArgs>
-
-/**
- * Arguments for {@linkcode PluginGeomCreateApi.circle}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `centrePoint` | {@linkcode Vec3Handle} | Centre point of the circle |
- * | `axis` | {@linkcode Vec3Handle} | Axis direction (plane normal) of the circle |
- * | `radius` | `number` | Radius of the circle |
- */
-export const PluginGeomCreateCircleArgs = z.object({
-  centrePoint: Vec3Handle,
-  axis: Vec3Handle,
-  radius: z.number(),
-})
-
-export type PluginGeomCreateCircleArgs = z.infer<typeof PluginGeomCreateCircleArgs>
-
-/**
- * Arguments for {@linkcode PluginGeomCreateApi.splineFromPoints}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `points` | {@linkcode Vec3Handle}`[]` | 3..256 ordered through-points of the curve |
- */
-export const PluginGeomCreateSplineFromPointsArgs = z.object({
-  points: z.array(Vec3Handle).min(3).max(MAX_SPLINE_THROUGH_POINTS),
-})
-
-export type PluginGeomCreateSplineFromPointsArgs = z.infer<
-  typeof PluginGeomCreateSplineFromPointsArgs
->
-
-/**
- * Arguments for {@linkcode PluginGeomCreateApi.splineFromControlPoints}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `controlPoints` | {@linkcode Vec3Handle}`[]` | 3..512 control points of the curve, in order |
- * | `options` | `object`? | `degree`: 2 or 3 (default `min(3, controlPoints.length - 1)`) |
- */
-export const PluginGeomCreateSplineFromControlPointsArgs = z.object({
-  controlPoints: z.array(Vec3Handle).min(3).max(MAX_SPLINE_POLES),
-  options: z.object({ degree: z.number().int().min(2).max(3).optional() }).optional(),
-})
-
-export type PluginGeomCreateSplineFromControlPointsArgs = z.infer<
-  typeof PluginGeomCreateSplineFromControlPointsArgs
->
-
-/**
- * Arguments for {@linkcode PluginGeomCreateApi.profileFromLinePoints}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `points` | {@linkcode Vec3Handle}`[]` | Ordered vertex handles of the profile |
- */
-export const PluginGeomCreateProfileFromLinePointsArgs = z.object({
-  points: z.array(Vec3Handle),
-})
-
-export type PluginGeomCreateProfileFromLinePointsArgs = z.infer<
-  typeof PluginGeomCreateProfileFromLinePointsArgs
->
-
-/**
- * Arguments for {@linkcode PluginGeomCreateApi.profileFromCurves}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `curves` | {@linkcode CurveHandle}`[]` | Ordered curve handles forming a closed loop |
- */
-export const PluginGeomCreateProfileFromCurvesArgs = z.object({
-  curves: z.array(CurveHandle),
-})
-
-export type PluginGeomCreateProfileFromCurvesArgs = z.infer<
-  typeof PluginGeomCreateProfileFromCurvesArgs
->
-
-/**
- * Arguments for {@linkcode PluginGeomCreateApi.profileFromSplinePoints}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `points` | {@linkcode Vec3Handle}`[]` | 3..256 ordered through-points of the closed loop (first point NOT repeated) |
- */
-export const PluginGeomCreateProfileFromSplinePointsArgs = z.object({
-  points: z.array(Vec3Handle).min(3).max(MAX_SPLINE_THROUGH_POINTS),
-})
-
-export type PluginGeomCreateProfileFromSplinePointsArgs = z.infer<
-  typeof PluginGeomCreateProfileFromSplinePointsArgs
->
-
-/**
- * Arguments for {@linkcode PluginGeomCreateApi.contourFromProfile}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `outer` | {@linkcode ProfileHandle} | The outer boundary loop |
- */
-export const PluginGeomCreateContourFromProfileArgs = z.object({
-  outer: ProfileHandle,
-})
-
-export type PluginGeomCreateContourFromProfileArgs = z.infer<
-  typeof PluginGeomCreateContourFromProfileArgs
->
-
-/**
- * Arguments for {@linkcode PluginGeomCreateApi.contourFromProfiles}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `outer` | {@linkcode ProfileHandle} | The outer boundary loop |
- * | `holes` | {@linkcode ProfileHandle}`[]` | Optional inner hole loops |
- */
-export const PluginGeomCreateContourFromProfilesArgs = z.object({
-  outer: ProfileHandle,
-  holes: z.array(ProfileHandle).optional(),
-})
-
-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) |
- * | `options` | `object`? | Optional twist and taper: `twistInDegrees` (an angle, finite), `topScale` (a ratio, finite and positive) and `levels` (a count, 2..64) |
- */
-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" }),
-  options: z
-    .object({
-      twistInDegrees: z.number().finite().optional(),
-      topScale: z.number().finite().positive().optional(),
-      levels: z.number().int().min(2).max(MAX_TWIST_LEVELS).optional(),
-    })
-    .optional(),
-})
-
-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 (any count; more than 32 sections in all builds but carries no parameter record) |
- * | `options` | `object`? | Optional behavior switches: `compatibility` (`"strict"` throws on mismatched edge counts instead of auto-matching; default `"auto"`), `seamAlignment` (`"authored"` keeps the authored correspondence instead of searching seam rotations; default `"auto"`) and `smoothing` (`"smooth"` lofts every section in one pass, so the sides curve through the intermediates; default `"ruled"`) |
- */
-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(),
-      smoothing: z.enum(["ruled", "smooth"]).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 edges to fillet (one or more; more than 64 builds but carries no parameter record) |
- * | `radius` | `number` | Fillet radius (positive, finite); the start radius with `endRadius`, unused with `radii` |
- * | `options` | `object`? | Optional variable blend: `endRadius` (positive, finite) or `radii` (2..32 rows of `{ position, radius }`, `position` a ratio 0..1 strictly increasing). Mutually exclusive, and either one takes exactly ONE edge |
- */
-export const PluginGeomCreateBrepFromFilletArgs = z
-  .object({
-    brep: BrepHandle,
-    edges: z.array(EdgeHandle).min(1),
-    radius: z.number().finite().positive(),
-    options: z
-      .object({
-        endRadius: z.number().finite().positive().optional(),
-        radii: z
-          .array(
-            z.object({
-              position: z.number().finite().min(0).max(1),
-              radius: z.number().finite().positive(),
-            }),
-          )
-          .min(2)
-          .max(MAX_FILLET_LAW_SAMPLES)
-          .optional(),
-      })
-      .optional(),
-  })
-  .superRefine((a, ctx) => {
-    const { endRadius, radii } = a.options ?? {}
-    if (endRadius === undefined && radii === undefined) return
-    if (endRadius !== undefined && radii !== undefined) {
-      ctx.addIssue({ code: "custom", message: "endRadius is mutually exclusive with radii" })
-    }
-    // The law belongs to the blend contour the one edge lies on, and `position`
-    // is measured from that edge's start: a second edge would have no origin.
-    if (a.edges.length !== 1) {
-      ctx.addIssue({
-        code: "custom",
-        message: "a variable fillet takes exactly one edge — the blend contour it runs along",
-      })
-    }
-    if (radii?.some((row, i) => i > 0 && row.position <= radii[i - 1].position)) {
-      ctx.addIssue({ code: "custom", message: "radii positions must strictly increase" })
-    }
-  })
-
-export type PluginGeomCreateBrepFromFilletArgs = z.infer<typeof PluginGeomCreateBrepFromFilletArgs>
-
-/** An edge with the solid it belongs to. See {@linkcode OwnedEdge}. */
-export const OwnedEdge = z.object({
-  edge: EdgeHandle,
-  brep: BrepHandle,
-  face: FaceHandle.optional(),
-})
-
-/**
- * Arguments for {@linkcode PluginGeomCreateApi.brepFromPatch}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `boundary` | ({@linkcode CurveHandle} \| {@linkcode OwnedEdge})`[]` | 3..16 items forming one closed loop |
- * | `thickness` | `number` | Solid thickness in internal length units (positive, finite) |
- * | `options` | `object`? | `interiorPoints` (≤ 64 plain `{x, y, z}` the surface is pulled through), `continuity` (`"position"` default, or `"tangent"` — every item must then be an edge item naming its `face`), `side` (`"below"` default, or `"above"`) |
- */
-export const PluginGeomCreateBrepFromPatchArgs = z
-  .object({
-    boundary: z
-      .array(z.union([CurveHandle, OwnedEdge]))
-      .min(3)
-      .max(MAX_PATCH_BOUNDARY_CURVES),
-    thickness: z.number().finite().positive(),
-    options: z
-      .object({
-        interiorPoints: z.array(FiniteVec3Components).max(MAX_PATCH_INTERIOR_POINTS).optional(),
-        continuity: z.enum(["position", "tangent"]).optional(),
-        side: z.enum(["below", "above"]).optional(),
-      })
-      .optional(),
-  })
-  .superRefine((a, ctx) => {
-    if (a.options?.continuity !== "tangent") return
-    // The kernel's filling call (`Add_2`) follows exactly ONE support face per
-    // edge, but a solid edge touches two faces. So a tangent patch must say
-    // which face to follow, for every item, and this is checked before the host
-    // runs.
-    if (a.boundary.some((item) => !("edge" in item) || item.face === undefined)) {
-      ctx.addIssue({
-        code: "custom",
-        message:
-          'continuity: "tangent" needs every boundary item to be an edge with its brep and the face to continue',
-      })
-    }
-  })
-
-export type PluginGeomCreateBrepFromPatchArgs = z.infer<typeof PluginGeomCreateBrepFromPatchArgs>
-
-/**
- * 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 (one or more; more than 32 builds but carries no parameter record) |
- * | `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.brepsFromSplitByFace}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `brep` | {@linkcode BrepHandle} | The solid to cut |
- * | `toolFace` | {@linkcode FaceHandle} | The cutting face (read-only) |
- * | `toolBrep` | {@linkcode BrepHandle} | The solid `toolFace` belongs to (owner last) |
- */
-export const PluginGeomCreateBrepsFromSplitByFaceArgs = z.object({
-  brep: BrepHandle,
-  toolFace: FaceHandle,
-  toolBrep: BrepHandle,
-})
-
-export type PluginGeomCreateBrepsFromSplitByFaceArgs = z.infer<
-  typeof PluginGeomCreateBrepsFromSplitByFaceArgs
->
-
-/**
- * Arguments for {@linkcode PluginGeomCreateApi.curvesFromProjection}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `curve` | {@linkcode CurveHandle} | The curve to project |
- * | `face` | {@linkcode FaceHandle} | The face to project onto |
- * | `faceBrep` | {@linkcode BrepHandle} | The solid `face` belongs to (owner last) |
- */
-export const PluginGeomCreateCurvesFromProjectionArgs = z.object({
-  curve: CurveHandle,
-  face: FaceHandle,
-  faceBrep: BrepHandle,
-})
-
-export type PluginGeomCreateCurvesFromProjectionArgs = z.infer<
-  typeof PluginGeomCreateCurvesFromProjectionArgs
->
-
-/**
- * Arguments for {@linkcode PluginGeomCreateApi.brepFromChamfer}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `brep` | {@linkcode BrepHandle} | The solid whose edges to bevel |
- * | `edges` | {@linkcode EdgeHandle}`[]` | The edges to chamfer (one or more; more than 64 builds but carries no parameter record) |
- * | `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 or more points, finite components — more than 512 builds but carries no parameter record; 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), `"round"` (arc-carried corners) 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.literal("round"),
-            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.brepFromSweepAlongCurve}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `profile` | {@linkcode ContourHandle} | The cross-section to sweep (hole-free) |
- * | `path` | {@linkcode CurveHandle}`[]` | 1..64 curves, ordered, meeting end to end |
- * | `options` | `object`? | `orientation` — `"upright"` (default), `"frenet"` or `"fixed"`; `rail` — a second guide {@linkcode CurveHandle} |
- */
-export const PluginGeomCreateBrepFromSweepAlongCurveArgs = z.object({
-  profile: ContourHandle,
-  path: z.array(CurveHandle).min(1).max(MAX_PATH_CURVES),
-  options: z
-    .object({
-      orientation: z.enum(["frenet", "fixed", "upright"]).optional(),
-      rail: CurveHandle.optional(),
-    })
-    .optional(),
-})
-
-export type PluginGeomCreateBrepFromSweepAlongCurveArgs = z.infer<
-  typeof PluginGeomCreateBrepFromSweepAlongCurveArgs
->
-
-/**
- * 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; the axis must lie in the plane of the profile) |
- * | `axisDirection` | {@linkcode Vec3Components} | The axis direction (non-zero, finite components; the axis must lie in the plane of the profile) |
- * | `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
->
-
-/**
- * Arguments for {@linkcode PluginGeomCreateApi.brepFromSphere}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `centre` | {@linkcode Vec3Components} | Sphere centre (finite components) |
- * | `radius` | `number` | Sphere radius (finite; positivity is checked host-side so the error names the parameter) |
- */
-export const PluginGeomCreateBrepFromSphereArgs = z.object({
-  centre: FiniteVec3Components,
-  radius: z.number().finite(),
-})
-
-export type PluginGeomCreateBrepFromSphereArgs = z.infer<
-  typeof PluginGeomCreateBrepFromSphereArgs
->
-
-/**
- * Arguments for {@linkcode PluginGeomCreateApi.brepFromCylinder}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `base` | {@linkcode Vec3Components} | Centre of the bottom cap (finite components) |
- * | `axis` | {@linkcode Vec3Components} | Axis direction (non-zero, finite components) |
- * | `radius` | `number` | Cylinder radius (finite, positive) |
- * | `height` | `number` | Height along `axis` (finite, positive) |
- */
-export const PluginGeomCreateBrepFromCylinderArgs = z.object({
-  base: FiniteVec3Components,
-  axis: FiniteVec3Components,
-  radius: z.number().finite(),
-  height: z.number().finite(),
-})
-
-export type PluginGeomCreateBrepFromCylinderArgs = z.infer<
-  typeof PluginGeomCreateBrepFromCylinderArgs
->
-
-/**
- * Arguments for {@linkcode PluginGeomCreateApi.brepFromCone}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `base` | {@linkcode Vec3Components} | Centre of the bottom cap (finite components) |
- * | `axis` | {@linkcode Vec3Components} | Axis direction (non-zero, finite components) |
- * | `baseRadius` | `number` | Radius at the base (finite, positive) |
- * | `height` | `number` | Height along `axis` (finite, positive) |
- * | `topRadius` | `number`? | Radius at the top (finite, ≥ 0, ≠ `baseRadius`; default 0 = apex) |
- */
-export const PluginGeomCreateBrepFromConeArgs = z
-  .object({
-    base: FiniteVec3Components,
-    axis: FiniteVec3Components,
-    baseRadius: z.number().finite(),
-    height: z.number().finite(),
-    topRadius: z.number().finite().optional(),
-  })
-  .refine((a) => (a.topRadius ?? 0) !== a.baseRadius, {
-    message: "topRadius must differ from baseRadius — equal radii are a cylinder",
-  })
-
-export type PluginGeomCreateBrepFromConeArgs = z.infer<typeof PluginGeomCreateBrepFromConeArgs>
-
-/**
- * Arguments for {@linkcode PluginGeomCreateApi.brepFromTorus}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `centre` | {@linkcode Vec3Components} | Torus centre (finite components) |
- * | `axis` | {@linkcode Vec3Components} | Plane normal of the ring (non-zero, finite components) |
- * | `majorRadius` | `number` | Ring radius, centre to tube centre (finite, positive) |
- * | `minorRadius` | `number` | Tube radius (finite, positive, strictly less than `majorRadius`) |
- */
-export const PluginGeomCreateBrepFromTorusArgs = z
-  .object({
-    centre: FiniteVec3Components,
-    axis: FiniteVec3Components,
-    majorRadius: z.number().finite(),
-    minorRadius: z.number().finite(),
-  })
-  .refine((a) => a.minorRadius < a.majorRadius, {
-    message: "minorRadius must be smaller than majorRadius — the torus would self-intersect",
-  })
-
-export type PluginGeomCreateBrepFromTorusArgs = z.infer<typeof PluginGeomCreateBrepFromTorusArgs>
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import {
+  MAX_SPLINE_THROUGH_POINTS,
+  MAX_SPLINE_POLES,
+  MAX_PATH_CURVES,
+  MAX_TWIST_LEVELS,
+  MAX_FILLET_LAW_SAMPLES,
+} from "../../../../massParameters"
+import type { SweepAlongCurveRecordOptions } from "../../../../massParameters"
+import { Vec3Handle, LineHandle, ArcHandle, SplineHandle, CircleHandle, CurveHandle, ProfileHandle, ContourHandle, BrepHandle, FaceHandle, EdgeHandle, Vec3Components } from "../../../../handles"
+
+/** Maximum boundary items one patch may span. */
+export const MAX_PATCH_BOUNDARY_CURVES = 16
+/** Maximum interior points one patch may be pulled through. */
+export const MAX_PATCH_INTERIOR_POINTS = 64
+
+/**
+ * An edge named together with the solid it belongs to — an edge handle cannot
+ * name its own solid, and one patch may meet two solids. `face` is the adjacent
+ * face a tangent patch continues: REQUIRED under `continuity: "tangent"`
+ * (a solid edge has two faces — the wall or the top of a rim — and only the
+ * caller knows which), ignored otherwise. Owner LAST, like every read that
+ * takes `(face, brep)`.
+ */
+export type OwnedEdge = { edge: EdgeHandle; brep: BrepHandle; face?: FaceHandle }
+
+/**
+ * The trailing bag of {@linkcode PluginGeomCreateApi.brepFromSweepAlongCurve}:
+ * the recorded switches plus `rail`, a live curve handle that never enters a
+ * record (a record is pure JSON, and a dead handle would not regenerate).
+ */
+export type SweepAlongCurveOptions = SweepAlongCurveRecordOptions & { rail?: CurveHandle }
+
+/**
+ * Curve creation — construct new geometric curves from point handles (all-handle
+ * model, §11).
+ *
+ * Each method takes point handles ({@linkcode Vec3Handle}) and returns an opaque
+ * curve handle ({@linkcode LineHandle}, {@linkcode ArcHandle}, or
+ * {@linkcode SplineHandle}) that you pass to query, update, or entity-creation
+ * methods. Read geometry back as plain values via the
+ * `snaptrude.core.geom.query.*` methods.
+ *
+ * Accessed via `snaptrude.core.geom.create`.
+ */
+export abstract class PluginGeomCreateApi {
+  constructor() {}
+
+  /**
+   * Create a straight line segment between two point handles. Host API call —
+   * returns a handle.
+   *
+   * @param startPoint Start point of the line segment
+   * @param endPoint End point of the line segment
+   * @returns The new line as a {@linkcode LineHandle}
+   *
+   * @examplePrompt Draw a line from point A to point B
+   * @examplePrompt Draw a straight edge between these two points
+   *
+   * @example
+   * ```ts
+   * const line = snaptrude.core.geom.create.line(startPoint, endPoint)
+   * ```
+   */
+  public abstract line(startPoint: Vec3Handle, endPoint: Vec3Handle): PluginApiReturn<LineHandle>
+
+  /**
+   * Create a circular arc from its start, end, centre, and axis point handles.
+   * Host API call — returns a handle.
+   *
+   * @param startPoint Start point of the arc
+   * @param endPoint End point of the arc
+   * @param centrePoint Centre point of the arc
+   * @param axis Axis direction of the arc
+   * @returns The new arc as an {@linkcode ArcHandle}
+   *
+   * @examplePrompt Draw an arc between these two points around a centre
+   * @examplePrompt Add a curved segment from A to B
+   *
+   * @example
+   * ```ts
+   * const arc = snaptrude.core.geom.create.arc(startPoint, endPoint, centrePoint, axis)
+   * ```
+   */
+  public abstract arc(
+    startPoint: Vec3Handle,
+    endPoint: Vec3Handle,
+    centrePoint: Vec3Handle,
+    axis: Vec3Handle,
+  ): PluginApiReturn<ArcHandle>
+
+  /**
+   * Create a circle from a centre point, an axis (plane normal), and a radius.
+   * Host API call — returns a handle. A circle is a closed curve; read it back via
+   * `snaptrude.core.geom.query.circle.*`.
+   *
+   * @param centrePoint Centre point of the circle
+   * @param axis Axis direction (plane normal) of the circle
+   * @param radius Radius of the circle
+   * @returns The new circle as a {@linkcode CircleHandle}
+   *
+   * @examplePrompt Make a circle of radius 2 at this point
+   * @examplePrompt Draw a circular outline 5m across
+   *
+   * @example
+   * ```ts
+   * const circle = snaptrude.core.geom.create.circle(centrePoint, axis, 2)
+   * ```
+   */
+  public abstract circle(
+    centrePoint: Vec3Handle,
+    axis: Vec3Handle,
+    radius: number,
+  ): PluginApiReturn<CircleHandle>
+
+  /**
+   * Create an open NURBS curve passing exactly THROUGH each point, in order
+   * (centripetal Catmull-Rom fit → clamped cubic B-spline; C1-smooth, no cusps
+   * on uneven spacing). Host API call — returns a handle. The points are
+   * interpolated, NOT control points. For a CLOSED smooth loop use
+   * {@linkcode PluginGeomCreateApi.profileFromSplinePoints} — closed splines
+   * exist only as profiles, never as a single curve handle.
+   *
+   * Pure host-side math — the geometry kernel is not loaded. The result is a
+   * {@linkcode CurveHandle}: pass it to `profileFromCurves` alongside lines and
+   * arcs, or read it back via `core.geom.query.curve.*`.
+   *
+   * @param points 3..256 ordered through-points; consecutive points must be distinct
+   * @returns The new open curve as a {@linkcode SplineHandle}
+   * @throws VALIDATION if fewer than 3 points (2 points are a straight line —
+   *   use {@linkcode PluginGeomCreateApi.line}), more than 256 points, or two
+   *   consecutive points coincide
+   *
+   * @examplePrompt Draw a smooth curve through these points
+   * @examplePrompt Make a wavy edge that passes through A, B, C and D
+   * @examplePrompt Freeform curved wall path through these clicks
+   *
+   * # Example
+   * ```ts
+   * const spline = await snaptrude.core.geom.create.splineFromPoints([p0, p1, p2, p3])
+   * // Mixed profile: smooth top, straight closing base
+   * const base = await snaptrude.core.geom.create.line(p3, p0)
+   * const profile = await snaptrude.core.geom.create.profileFromCurves([spline, base])
+   * ```
+   */
+  public abstract splineFromPoints(points: Vec3Handle[]): PluginApiReturn<SplineHandle>
+
+  /**
+   * Create an open NURBS curve DEFINED BY control points — the curve is pulled
+   * TOWARD the interior points, not through them; it starts at the first point
+   * and ends at the last. Knots are computed for you (clamped, uniform) —
+   * there is no knot-vector argument. For a curve that must pass THROUGH given
+   * points use {@linkcode PluginGeomCreateApi.splineFromPoints}.
+   *
+   * A curve made here records as `splinePoles` in a mass recipe and is
+   * re-minted verbatim on edit — so an agent that read a `splinePoles` curve
+   * back off a mass can move its poles and rebuild the mass with
+   * `design.update.parameters`. Pure host-side math — the geometry kernel is
+   * not loaded, and nothing is created in the scene. An edge's control points
+   * rebuild the same curve here only when its knots are clamped uniform.
+   *
+   * @param controlPoints 3..512 control points ({@linkcode Vec3Handle}s), in order
+   * @param options.degree 2 or 3; default `min(3, controlPoints.length - 1)`
+   * @returns The new open curve as a {@linkcode SplineHandle}
+   * @throws VALIDATION when fewer than `degree + 1` points are given, two
+   *   consecutive points coincide, or `degree` is not 2 or 3
+   *
+   * @examplePrompt Draw a smooth curve controlled by these four points
+   *
+   * # Example
+   * ```ts
+   * const curve = await snaptrude.core.geom.create.splineFromControlPoints([p0, p1, p2, p3])
+   * // Quadratic instead of the default cubic
+   * const tighter = await snaptrude.core.geom.create.splineFromControlPoints(
+   *   [p0, p1, p2, p3],
+   *   { degree: 2 },
+   * )
+   * ```
+   */
+  public abstract splineFromControlPoints(
+    controlPoints: Vec3Handle[],
+    options?: { degree?: number },
+  ): PluginApiReturn<SplineHandle>
+
+  /**
+   * Drops a curve onto a face along the face's normal and returns the curves it
+   * lands on — one per connected run, empty when the curve misses the face
+   * entirely. Host API call — returns new curve handles; the inputs are
+   * read-only. No lengths are involved: the result is a curve in the same
+   * internal length units as its inputs.
+   *
+   * @param curve The curve to project
+   * @param face The face to project onto
+   * @param faceBrep The solid `face` belongs to — a face handle cannot name its
+   *   own solid
+   * @returns The projected curves as {@linkcode CurveHandle}`[]`
+   * @throws VALIDATION if `face` is not a face of `faceBrep`, or the curve's
+   *   midpoint lies on the face's surface (there is no drop direction there)
+   * @throws OPERATION_FAILED if the kernel could not project the curve
+   */
+  public abstract curvesFromProjection(
+    curve: CurveHandle,
+    face: FaceHandle,
+    faceBrep: BrepHandle,
+  ): PluginApiReturn<CurveHandle[]>
+
+  /**
+   * Create a closed profile from an ordered list of point handles connected by
+   * line segments (last auto-connected to first). Host API call — returns a handle.
+   *
+   * @param points Ordered vertex handles of the profile
+   * @returns The new profile as a {@linkcode ProfileHandle}
+   *
+   * @examplePrompt Draw a closed polygon through these corner points
+   * @examplePrompt Create an L-shaped outline from a list of points
+   *
+   * @example
+   * ```ts
+   * const profile = snaptrude.core.geom.create.profileFromLinePoints(points)
+   * ```
+   */
+  public abstract profileFromLinePoints(points: Vec3Handle[]): PluginApiReturn<ProfileHandle>
+
+  /**
+   * Create a profile from an ordered list of curve handles forming a closed loop.
+   * Host API call — returns a handle.
+   *
+   * @param curves Ordered curve handles forming a closed loop
+   * @returns The new profile as a {@linkcode ProfileHandle}
+   *
+   * @examplePrompt Join these lines and arcs into one closed shape
+   *
+   * @example
+   * ```ts
+   * const profile = snaptrude.core.geom.create.profileFromCurves([line, arc])
+   * ```
+   */
+  public abstract profileFromCurves(curves: CurveHandle[]): PluginApiReturn<ProfileHandle>
+
+  /**
+   * Create a CLOSED smooth profile passing through each point, in order, with
+   * the loop closed smoothly back from the last point to the first (do NOT
+   * repeat the first point). Host API call — returns a handle. This is the
+   * closed counterpart of {@linkcode PluginGeomCreateApi.splineFromPoints} and
+   * the one-call route from points to an extrudable outline: wrap in
+   * `contourFromProfile` and extrude/loft/sweep as usual.
+   *
+   * The whole loop is smooth — this call takes no mixed straight/spline input.
+   * For a profile that is part curve and part straight, build the pieces with
+   * `splineFromPoints` + `line` and join them with
+   * {@linkcode PluginGeomCreateApi.profileFromCurves}.
+   *
+   * @param points 3..256 ordered through-points of the loop (first point NOT repeated)
+   * @returns The new closed profile as a {@linkcode ProfileHandle}
+   * @throws VALIDATION if fewer than 3 points, more than 256 points,
+   *   consecutive points coincide (including last→first), or the loop
+   *   self-intersects
+   *
+   * @examplePrompt Make a blob-shaped floor plate through these points
+   * @examplePrompt Organic curved outline through these corners
+   * @examplePrompt Freeform podium profile
+   *
+   * # Example
+   * ```ts
+   * const profile = await snaptrude.core.geom.create.profileFromSplinePoints([p0, p1, p2, p3, p4])
+   * const contour = await snaptrude.core.geom.create.contourFromProfile(profile)
+   * const brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)
+   * const podium = await snaptrude.design.create.massFromBrep(brep, "Podium")
+   * ```
+   */
+  public abstract profileFromSplinePoints(points: Vec3Handle[]): PluginApiReturn<ProfileHandle>
+
+  /**
+   * Create an axis-aligned **rectangle** profile in the XZ plane,
+   * `width` × `depth`, centred at `center` (defaults to the origin). Host API
+   * call — returns a handle.
+   *
+   * Pair with `design.create.space` / `design.create.spaces` to author a rectangular
+   * (box) space — there is no dedicated rectangular-space creator; build the profile
+   * here, then extrude it.
+   *
+   * @param width Extent along X
+   * @param depth Extent along Z
+   * @param center Optional centre point (default origin)
+   * @returns The new rectangle profile as a {@linkcode ProfileHandle}
+   *
+   * @examplePrompt Draw a 4m by 3m rectangle
+   * @examplePrompt Make a rectangular outline for a room footprint
+   *
+   * @example
+   * ```ts
+   * const rect = snaptrude.core.geom.create.profileRect(4, 3)
+   * const contour = snaptrude.core.geom.create.contourFromProfile(rect)
+   * const space = snaptrude.design.create.space(contour, 3)
+   * ```
+   */
+  public abstract profileRect(
+    width: number,
+    depth: number,
+    center?: Vec3Handle,
+  ): PluginApiReturn<ProfileHandle>
+
+  /**
+   * Create a contour (an outer profile loop, no holes). Host API call — returns a handle.
+   *
+   * @param outer The outer boundary loop
+   * @returns The new contour as a {@linkcode ContourHandle}
+   * @example
+   * ```ts
+   * const contour = snaptrude.core.geom.create.contourFromProfile(outer)
+   * ```
+   */
+  public abstract contourFromProfile(outer: ProfileHandle): PluginApiReturn<ContourHandle>
+
+  /**
+   * Create a contour from an outer profile plus zero or more inner profiles (holes).
+   * Host API call — returns a handle.
+   *
+   * A hole here is part of the footprint and cannot be moved or deleted later;
+   * for an editable hole in a slab use `design.create.void`.
+   *
+   * @param outer The outer boundary loop
+   * @param holes Optional inner hole loops
+   * @returns The new contour as a {@linkcode ContourHandle}
+   *
+   * @examplePrompt Make a shape with a hole in the middle
+   * @examplePrompt Cut a courtyard opening out of this floor outline
+   *
+   * @example
+   * ```ts
+   * const contour = snaptrude.core.geom.create.contourFromProfiles(outer, [hole])
+   * ```
+   */
+  public abstract contourFromProfiles(
+    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 in internal length units (non-zero; negative extrudes opposite to `direction`)
+   * @param options Optional twist and taper, both about `direction` through the
+   *   base contour's centroid. `twistInDegrees` — total rotation base → top in
+   *   DEGREES (an angle: never scaled by the project's length unit), positive
+   *   turning the top CLOCKWISE seen from the far end of `direction` looking
+   *   back at the base — for the usual upward extrusion, the plan view;
+   *   `topScale` — the top outline's scale, a ratio (1 = no taper); `levels` —
+   *   how many sections to build through, a count (2..64; each step may turn
+   *   at most 22.5°). Leave `levels` out
+   *   and the host resolves one and writes it into the record, so the mass
+   *   regenerates identically ever after. An extrusion without twist or
+   *   taper (no `options`, or zero twist and a `topScale` of 1) is
+   *   built exactly as before these options existed.
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws if the extrusion is degenerate (zero amount, zero direction, or a
+   *   direction lying in the plane of the contour) or the contour cannot be
+   *   extruded into a valid solid
+   * @throws VALIDATION if `twistInDegrees` is not finite or turns more than
+   *   1440°, `topScale` is not a positive finite ratio, `levels` is outside
+   *   2..64 or too few for the twist (more than 22.5° per step), a twist is
+   *   asked of a `direction` that is not the contour's normal, the contour has
+   *   holes under a twist or taper, or a scaled section self-intersects
+   *
+   * @examplePrompt Extrude this profile 3 metres up
+   * @examplePrompt Make a solid by extruding this outline
+   * @examplePrompt Create a cylinder from a circle profile
+   * @examplePrompt Extrude this floor plate 40m up with a 90 degree twist
+   * @examplePrompt Taper this tower to 60 percent of its footprint at the top
+   *
+   * # 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,
+    options?: { twistInDegrees?: number; topScale?: number; levels?: number },
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Stretches a surface across a closed loop of boundary curves and thickens it
+   * into a SOLID in one call — a roof over four curves, a canopy between two
+   * rails, a blend across a gap. `thickness` is in internal length units and is
+   * required: only solids reach the canvas, and there is no separate surface
+   * object to keep. Pass edges as `{ edge, brep, face }` with
+   * `continuity: "tangent"` to leave the named face smoothly. The result carries
+   * NO recipe (`design.query.getParameters` returns `null`) — label it when you
+   * commit it, because the label is all the provenance there is.
+   *
+   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
+   * of MB — expect a pause of seconds).
+   *
+   * @param boundary 3..16 items forming ONE closed loop (ends meeting within
+   *   tolerance): a curve, or an edge named WITH the solid it belongs to
+   *   ({@linkcode OwnedEdge}) — an edge handle cannot name its own solid, and
+   *   one patch may meet two solids. Read scene breps with
+   *   `design.query.geometry.getBrep(x, { frame: "world" })` so every item is in
+   *   one frame.
+   * @param thickness Solid thickness in internal length units (> 0)
+   * @param options `interiorPoints` pull the surface through them (≤ 64, plain
+   *   `{x, y, z}` in the same frame as the boundary). `continuity` —
+   *   `"position"` (default) or `"tangent"`: every boundary item must then be an
+   *   edge item that also names the `face` to continue (a solid edge has two
+   *   faces — the wall or the top of a rim). `side` — `"below"` (default) or
+   *   `"above"`: which side of the boundary the solid grows to.
+   * @returns The thickened patch as a new {@linkcode BrepHandle}
+   * @throws VALIDATION if the boundary is not one closed loop (the message names
+   *   the gap and its size), a count cap is exceeded, `thickness` is not
+   *   positive, `continuity: "tangent"` is used with a curve item or with an
+   *   edge item that names no `face` (the message names the edge's two candidate
+   *   faces), or a `face` is not adjacent to its `edge`
+   * @throws OPERATION_FAILED if the kernel could not fill the boundary, the
+   *   filled surface misses its own boundary by more than 0.254 mm (the message
+   *   carries the measured gap), or the thicken produced no solid
+   *
+   * @examplePrompt Patch a roof over these four boundary curves, 250 mm thick
+   * @examplePrompt Span a canopy between these two curved rails, 300 mm thick
+   *
+   * # Example
+   * ```ts
+   * // A roof over four curves
+   * const roof = await snaptrude.core.geom.create.brepFromPatch(
+   *   [curveA, curveB, curveC, curveD],
+   *   0.984, // 250 mm
+   * )
+   * const mass = await snaptrude.design.create.massFromBrep(roof, "Roof patch")
+   * ```
+   *
+   * ```ts
+   * // A canopy between two towers' rims, leaving every wall it meets smoothly:
+   * // with `continuity: "tangent"` EVERY item is an edge naming its face.
+   * const canopy = await snaptrude.core.geom.create.brepFromPatch(
+   *   [
+   *     { edge: rimA, brep: towerA, face: wallA },
+   *     { edge: sideA, brep: towerA, face: endA },
+   *     { edge: rimB, brep: towerB, face: wallB },
+   *     { edge: sideB, brep: towerB, face: endB },
+   *   ],
+   *   1.181, // 300 mm
+   *   { continuity: "tangent" },
+   * )
+   * ```
+   */
+  public abstract brepFromPatch(
+    boundary: (CurveHandle | OwnedEdge)[],
+    thickness: number,
+    options?: {
+      interiorPoints?: Vec3Components[]
+      continuity?: "position" | "tangent"
+      side?: "below" | "above"
+    },
+  ): 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 fallback); 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). Any count is accepted; a loft of more
+   *   than 32 sections counting the bottom and the top still builds but
+   *   carries no parameter record (records are capped, calls are not)
+   * @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 fallback for hole-free straight-edged pairs).
+   *   `{ compatibility: "strict", seamAlignment: "authored" }` reproduces
+   *   pre-0.9.4 lofting exactly. `smoothing` — `"ruled"` (default) keeps the
+   *   straight-sided behaviour described above; `"smooth"` lofts every
+   *   section in ONE kernel pass, so the sides curve continuously through the
+   *   intermediates instead of creasing at each one (a vase, a curved tower —
+   *   the sections must still be planar and hole-free).
+   * @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
+   * @examplePrompt Loft these three outlines with smoothly curving sides
+   *
+   * # 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"
+      smoothing?: "ruled" | "smooth"
+    },
+  ): 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.
+   *
+   * Returns a detached solid; to cut an editable hole in a slab, floor or roof
+   * in the model use `design.create.void`.
+   *
+   * @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 Subtract this box solid from that solid
+   *
+   * # 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 edges of a solid with a constant radius. Host API call —
+   * returns a new {@linkcode BrepHandle}; the input brep is read-only.
+   *
+   * Works on curved solids: edges may be straight, circular or spline, and
+   * adjacent edges (corner blends) are allowed. To pick a **rim** — the circle
+   * where a cylinder meets a flat cap — walk the edges and keep the ones whose
+   * two faces are a `cylinder` and a `plane`:
+   * `core.geom.query.brep.listEdges(brep)` → per edge
+   * `core.geom.query.edge.listFaces(edge)` → `core.geom.query.face.getSurfaceKind`
+   * on both faces. (`core.geom.query.brep.listEdgesBetween` takes two VERTEX
+   * indices — it is NOT a face-pair lookup.) For one cap's rim only, the
+   * shorter walk is: find the cap (call `getSurfaceKind` on each face from
+   * `brep.listFaces`), then `core.geom.query.face.listEdges(capFace)`.
+   *
+   * When the input brep carries a creation recipe, the result carries it too,
+   * with this operation appended to `operations`; `design.create.massFromBrep`
+   * then keeps the mass editable through `design.update.parameters`.
+   *
+   * 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 edges to fillet (one or more, all on `brep`, no
+   *   duplicates; more than 64 still fillets but the result carries no
+   *   parameter record)
+   * @param radius Fillet radius in internal length units (positive, finite) —
+   *   the radius at the START of the blend with `endRadius`; unused with
+   *   `radii` (the table is the whole law — pass its first row's radius)
+   * @param options Optional VARIABLE blend, in one of two forms, each naming
+   *   exactly ONE edge: the law belongs to the whole tangent chain that edge
+   *   lies on, and it is measured from that edge's start. `endRadius` —
+   *   the radius at the far end, in internal length units, interpolated
+   *   linearly along the chain; on a closed rim it must equal `radius` (0 and
+   *   1 are the same point) — use `radii` there. `radii` — a sampled law instead:
+   *   `position` is normalised ARC LENGTH along the chain (a ratio 0..1, never
+   *   converted), `radius` is internal length units; 2..32 rows with strictly
+   *   increasing `position`; before the first row and after the last the
+   *   radius is held constant. On a closed rim 0 and 1 are the same point, so
+   *   give them the same radius and put the variation in the interior rows. The two
+   *   forms are mutually exclusive; without either, the fillet has one constant
+   *   radius.
+   * @returns The filleted solid as a new {@linkcode BrepHandle}
+   * @throws VALIDATION if `edges` is empty or holds a duplicate, `radius` is
+   *   not a positive finite number, an edge is not on `brep`, or an edge has no
+   *   crease to round — it is a seam of a closed face, or it lies between two
+   *   patches of one smooth surface; for a variable blend, if `endRadius` and
+   *   `radii` are both given, more than one edge is passed, a `radii` table is
+   *   outside 2..32 rows or its positions do not strictly increase within
+   *   0..1, or the law's two ends differ on a closed rim (an `endRadius`
+   *   other than `radius`, or a `radii` table whose first and last radii
+   *   differ)
+   * @throws PRECONDITION_FAILED if an edge could not be located on the kernel
+   *   solid after healing (select a different edge, or fillet before the
+   *   operation that curved the solid), or the kernel could not blend the edge
+   *   named in the message (reduce the radius or drop that edge)
+   * @throws OPERATION_FAILED if the kernel or the translation fails, or the
+   *   result is non-manifold, splits into several solids, or contains a surface
+   *   Snaptrude cannot represent
+   *
+   * @examplePrompt Round the rim of the column with 200 mm
+   * @examplePrompt Soften where the dome meets the wall
+   * @examplePrompt Fillet the corners of the podium with a 0.5m radius
+   * @examplePrompt Soften the vertical edges of this tower
+   * @examplePrompt Blend this edge from 200mm at one end to 600mm at the other
+   * @examplePrompt Round this rim wider at the back than at the front
+   *
+   * # Example
+   * ```ts
+   * // Rim = every edge between the cylinder side and a plane cap
+   * const edges = await snaptrude.core.geom.query.brep.listEdges(column)
+   * const rim = []
+   * for (const edge of edges) {
+   *   const faces = await snaptrude.core.geom.query.edge.listFaces(edge)
+   *   const kinds = await Promise.all(
+   *     faces.map((f) => snaptrude.core.geom.query.face.getSurfaceKind(f)),
+   *   )
+   *   if (kinds.includes("cylinder") && kinds.includes("plane")) rim.push(edge)
+   * }
+   * const rounded = await snaptrude.core.geom.create.brepFromFillet(column, rim, 0.787) // 200 mm
+   * ```
+   */
+  public abstract brepFromFillet(
+    brep: BrepHandle,
+    edges: EdgeHandle[],
+    radius: number,
+    options?: { endRadius?: number; radii?: { position: number; 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.
+   *
+   * Works on curved solids: a sphere offsets to a sphere, a torus to a torus,
+   * a cylinder to a cylinder. There is nothing to select — the whole solid is
+   * offset.
+   *
+   * When the input brep carries a creation recipe, the result carries it too,
+   * with this operation appended to `operations`; `design.create.massFromBrep`
+   * then keeps the mass editable through `design.update.parameters`.
+   *
+   * 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 or the translation fails, or the
+   *   result is non-manifold, splits into several solids, or contains a surface
+   *   Snaptrude cannot represent (an offset free-form NURBS surface may have no
+   *   exact representation — the model is left unchanged). A distance too
+   *   large for the solid is reported here, with a hint asking for a smaller
+   *   one. There is no per-face refusal: the whole call fails, and the error
+   *   names no face
+   *
+   * @examplePrompt Thicken the torus ring by 100 mm
+   * @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.
+   *
+   * Works on curved solids: the open faces may be spherical, cylindrical,
+   * conical, toroidal or free-form patches, not only flat ones. To open the
+   * flat base of a dome, check every face first —
+   * `core.geom.query.brep.listFaces` then
+   * `core.geom.query.face.getSurfaceKind` on each — and keep the `"plane"`
+   * one. A closed curved surface is stored as several patches (a sphere as
+   * lunes), so opening "the sphere" may mean passing several faces.
+   *
+   * When the input brep carries a creation recipe, the result carries it too,
+   * with this operation appended to `operations`; `design.create.massFromBrep`
+   * then keeps the mass editable through `design.update.parameters`.
+   *
+   * 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 (one or more, all on
+   *   `brep`, no duplicates; more than 32 still shells but the result carries
+   *   no parameter record)
+   * @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 or holds a duplicate, 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 or the translation fails, or the
+   *   result is non-manifold, splits into several solids, or contains a surface
+   *   Snaptrude cannot represent. A thickness too large for the solid is
+   *   reported here, with a hint asking for one below half the smallest span.
+   *   There is no per-face refusal: the whole call fails, and the error
+   *   names no face
+   *
+   * @examplePrompt Hollow the dome into a 300 mm shell, open at the base
+   * @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
+   * // Open the dome at its flat base: the one face whose surface is a plane
+   * const faces = await snaptrude.core.geom.query.brep.listFaces(dome)
+   * const base = []
+   * for (const face of faces) {
+   *   if ((await snaptrude.core.geom.query.face.getSurfaceKind(face)) === "plane") base.push(face)
+   * }
+   * const hollow = await snaptrude.core.geom.create.brepFromShell(dome, base, 1.181) // 300 mm
+   * ```
+   */
+  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[]>
+
+  /**
+   * Cuts a solid with a FACE of another solid — the curved twin of
+   * {@linkcode PluginGeomCreateApi.brepsFromSplit}, which cuts with a plane.
+   * Host API call — returns new {@linkcode BrepHandle}s; both inputs are
+   * read-only. BOTH breps must be in the same frame: read scene masses with
+   * `design.query.geometry.getBrep(x, { frame: "world" })` (the default is each
+   * mass's own local frame, and two masses have two). The pieces come back in
+   * DESCENDING volume order; pick the one you want with
+   * `core.geom.query.brep.getCentroid` or `getVolume` and commit it. A piece
+   * carries no recipe — label it.
+   *
+   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
+   * of MB — expect a pause of seconds).
+   *
+   * @param brep The solid to cut
+   * @param toolFace The cutting face, read-only
+   * @param toolBrep The solid `toolFace` belongs to — a face handle cannot name
+   *   its own solid
+   * @returns The resulting pieces as {@linkcode BrepHandle}`[]`, largest first
+   * @throws VALIDATION if `toolFace` is not a face of `toolBrep`, `toolBrep` IS
+   *   `brep`, or the cut produced a single part — the surface does not pass all
+   *   the way through (extend it past the mass on every side, and check both
+   *   breps were read in the same frame)
+   * @throws OPERATION_FAILED if the kernel could not split the solid
+   *
+   * @examplePrompt Cut this mass with the curved roof surface and keep the lower part
+   *
+   * # Example
+   * ```ts
+   * const target = await snaptrude.design.query.geometry.getBrep(tower, { frame: "world" })
+   * const tool = await snaptrude.design.query.geometry.getBrep(roof, { frame: "world" })
+   * const [toolFace] = await snaptrude.core.geom.query.brep.listFaces(tool)
+   * const pieces = await snaptrude.core.geom.create.brepsFromSplitByFace(target, toolFace, tool)
+   * ```
+   */
+  public abstract brepsFromSplitByFace(
+    brep: BrepHandle,
+    toolFace: FaceHandle,
+    toolBrep: BrepHandle,
+  ): PluginApiReturn<BrepHandle[]>
+
+  /**
+   * Bevels the given edges of a solid with a symmetric planar cut. Host API
+   * call — returns a new {@linkcode BrepHandle}; the input brep is read-only.
+   *
+   * Works on curved solids: edges may be straight, circular or spline, and
+   * adjacent edges are allowed. Pick edges the same way as for
+   * {@linkcode PluginGeomCreateApi.brepFromFillet} — `brep.listEdges`, then
+   * `core.geom.query.edge.listFaces` and `core.geom.query.face.getSurfaceKind`
+   * on both faces of each edge. (`core.geom.query.brep.listEdgesBetween` takes
+   * two VERTEX indices — it is NOT a face-pair lookup.) Chamfering a cylinder's
+   * rim yields a cone patch where a fillet would yield a torus patch.
+   *
+   * When the input brep carries a creation recipe, the result carries it too,
+   * with this operation appended to `operations`; `design.create.massFromBrep`
+   * then keeps the mass editable through `design.update.parameters`.
+   *
+   * 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 edges to chamfer (one or more, all on `brep`, no
+   *   duplicates; more than 64 still chamfers but the result carries no
+   *   parameter record)
+   * @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 or holds a duplicate, `distance` is
+   *   not a positive finite number, an edge is not on `brep`, or an edge has no
+   *   crease to cut — it is a seam of a closed face, or it lies between two
+   *   patches of one smooth surface
+   * @throws PRECONDITION_FAILED if an edge could not be located on the kernel
+   *   solid after healing (select a different edge, or chamfer before the
+   *   operation that curved the solid)
+   * @throws OPERATION_FAILED if the kernel or the translation fails, or the
+   *   result is non-manifold, splits into several solids, or contains a surface
+   *   Snaptrude cannot represent. A distance larger than an adjacent face
+   *   is reported here, with a hint asking for a smaller one. Unlike
+   *   {@linkcode PluginGeomCreateApi.brepFromFillet}, the kernel does not say
+   *   which edge failed a chamfer, so the error names no edge
+   *
+   * @examplePrompt Chamfer the top edge of the cylinder
+   * @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 a sharp mitred bend; `"round"`
+   * carries the section around each turning corner on a tangent circular arc,
+   * so the corner patch is a real curved surface (geometrically cylindrical;
+   * `getSurfaceKind` reports it as `"spline"`) rather than a
+   * flat cut (open paths only — `"round"` on a closed ring path is refused);
+   * `{ 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 a varying scale only accepts straight paths, so it never meets
+   * 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 or more;
+   *   repeat the first point as the last to close the path into a ring; more
+   *   than 512 points still sweeps but the result carries no parameter record)
+   * @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),
+   *   `"round"` (arc-carried corners — curved corner patches; open paths
+   *   only) 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 bevelled corners take from it or a corner nearly doubles
+   *   back so its bevel collapses (the errors name the corner)
+   * @throws PRECONDITION_FAILED if `transition` is `"round"` and the path is
+   *   closed — round corners work on open paths only; use `"miter"` or
+   *   `{ bevel }` on a ring
+   * @throws OPERATION_FAILED if the kernel cannot sweep the profile into a
+   *   valid solid — including a `"round"` corner whose arc does not fit its
+   *   legs, which is not pre-checked and so is not named per corner
+   *
+   * @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
+   * @examplePrompt Sweep this handrail with rounded corners at the bends
+   *
+   * # 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" | "round" | { bevel: number }
+    },
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Sweeps a cross-section along a SMOOTH path — splines, arcs and lines chained
+   * end to end — with control of how the profile turns.
+   * {@linkcode PluginGeomCreateApi.brepFromSweep} takes a polyline path; this
+   * takes curves. Host API call — returns a new {@linkcode BrepHandle}; the
+   * inputs are read-only. Records as `sweepAlongCurve`, so the orientation stays
+   * editable through `design.update.parameters`. The properties panel shows it
+   * read-only, because it is a text value, not a number. A railed sweep records
+   * nothing (`getParameters` answers `null`).
+   *
+   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
+   * of MB — expect a pause of seconds).
+   *
+   * @param profile Hole-free cross-section contour; placed at the first curve's start
+   * @param path 1..64 curves, ordered, meeting end to end within tolerance
+   * @param options `orientation` — `"upright"` (default) keeps the profile's up
+   *   aligned with world up (ducts, handrails, ribbons that must not roll);
+   *   `"frenet"` lets it roll with the path's curvature; `"fixed"` carries the
+   *   authored frame along unchanged, which is a pure translation — use it to
+   *   bend a footprint along an arc. `rail` is a second guide curve.
+   * @returns The swept solid as a new {@linkcode BrepHandle}
+   * @throws VALIDATION if the path curves are not connected, the path is closed,
+   *   the profile has holes, the first tangent lies in the profile plane, the
+   *   path runs vertically under `"upright"` (that frame is undefined there —
+   *   the message names the run and points at `"frenet"`), the path turns
+   *   parallel to the profile under `"fixed"`, `rail` is closed, or `rail` and
+   *   `orientation` are both given
+   * @throws OPERATION_FAILED if the kernel could not sweep the profile — a
+   *   self-intersection on a tight bend
+   *
+   * @examplePrompt Sweep a 600x400 duct along this curved route and keep it upright
+   * @examplePrompt Run this handrail along the curved stair edge
+   * @examplePrompt Bend this footprint along the arc
+   *
+   * # Example
+   * ```ts
+   * const route = await snaptrude.core.geom.create.splineFromPoints(points)
+   * const duct = await snaptrude.core.geom.create.brepFromSweepAlongCurve(profile, [route], {
+   *   orientation: "upright",
+   * })
+   * ```
+   */
+  public abstract brepFromSweepAlongCurve(
+    profile: ContourHandle,
+    path: CurveHandle[],
+    options?: SweepAlongCurveOptions,
+  ): 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, and segments may run at any angle to the axis: an
+   * inclined segment revolves into a cone, an arc into a sphere or torus
+   * section. This is the general route to domes, vases, columns and rotundas.
+   *
+   * Two rules bind the axis to the profile. First, the axis line must lie IN
+   * the profile's plane or run parallel to it — a revolution turns a planar
+   * section about a line drawn in that same plane; a parallel axis offset out
+   * of the plane is judged by its projection into the plane (the result is a
+   * hollow ring). A skew axis is refused: move the axis into the profile's
+   * plane. Second, within that plane the whole profile stays on ONE side of
+   * the axis.
+   * Vertices and whole segments may lie ON the axis — that is how a dome's
+   * pole and a cylinder's inner edge are authored — but no part of the profile
+   * may cross to the other side, which would sweep a self-intersecting solid.
+   *
+   * 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], a coordinate is not finite, or the profile crosses the
+   *   axis (the message names the offending segment — keep the whole profile
+   *   on one side; points may touch the axis but not cross it)
+   * @throws PRECONDITION_FAILED if the axis is skew to the profile's plane
+   *   (neither in it nor parallel to it; the message asks you to move the axis
+   *   into the plane of the profile)
+   * @throws OPERATION_FAILED if the kernel cannot revolve the profile into a
+   *   valid solid
+   *
+   * @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
+   * @examplePrompt Make a dome by revolving a quarter-circle about the vertical axis
+   * @examplePrompt Turn this curved outline into a vase
+   *
+   * # Example
+   * ```ts
+   * // A cylinder: revolve a 2m-wide, 3m-tall rectangle about the Y axis at
+   * // its edge — the left edge sits ON the axis, which is legal.
+   * 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>
+
+  /**
+   * Create a solid **sphere** B-rep (boundary representation: the solid's
+   * exact faces, edges and vertices) from a centre and radius. Host API call
+   * — returns a {@linkcode BrepHandle}; commit it to the scene with
+   * `design.create.massFromBrep`. The result carries an exact spherical
+   * surface (not a faceted approximation) and a creation recipe — read the
+   * committed mass's parameters back with `design.query.getParameters` and edit
+   * them with `design.update.parameters`.
+   *
+   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
+   * of MB — expect a pause of seconds).
+   *
+   * @param centre Sphere centre as plain `{x, y, z}` components (internal length units)
+   * @param radius Sphere radius (> 0, internal length units)
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws VALIDATION if `radius` is not a positive finite number or a
+   *   coordinate is not finite
+   *
+   * @examplePrompt Create a sphere of radius 5 at the origin
+   * @examplePrompt Add a 3m ball on top of the tower
+   *
+   * # Example
+   * ```ts
+   * const brep = await snaptrude.core.geom.create.brepFromSphere({ x: 0, y: 5, z: 0 }, 5)
+   * const mass = await snaptrude.design.create.massFromBrep(brep, "Sphere")
+   * ```
+   */
+  public abstract brepFromSphere(
+    centre: Vec3Components,
+    radius: number,
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a solid **cylinder** B-rep from its bottom-cap centre, axis
+   * direction, radius and height. Host API call — returns a
+   * {@linkcode BrepHandle}; commit with `design.create.massFromBrep`. The
+   * bottom cap sits AT `base` and the solid extends `height` along `axis` —
+   * place `base` on the floor and use axis `{x: 0, y: 1, z: 0}` for an upright
+   * column. Carries a creation recipe (radius, height), editable through
+   * `design.update.parameters`.
+   *
+   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
+   * of MB — expect a pause of seconds).
+   *
+   * @param base Centre of the bottom cap as plain `{x, y, z}` components
+   * @param axis Axis direction as plain `{x, y, z}` components (non-zero, normalised by the host)
+   * @param radius Cylinder radius (> 0)
+   * @param height Cylinder height along `axis` (> 0)
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws VALIDATION if `radius`/`height` are not positive finite numbers or
+   *   `axis` is zero-length
+   *
+   * @examplePrompt Create a cylinder 2m across and 4m tall
+   * @examplePrompt Add a circular column here
+   *
+   * # Example
+   * ```ts
+   * const brep = await snaptrude.core.geom.create.brepFromCylinder(
+   *   { x: 0, y: 0, z: 0 },
+   *   { x: 0, y: 1, z: 0 },
+   *   1,
+   *   4,
+   * )
+   * const column = await snaptrude.design.create.massFromBrep(brep, "Column")
+   * ```
+   */
+  public abstract brepFromCylinder(
+    base: Vec3Components,
+    axis: Vec3Components,
+    radius: number,
+    height: number,
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a solid **cone or frustum** B-rep: bottom-cap centre, axis, base
+   * radius, height, and an optional top radius (default 0 — a full cone to a
+   * point; > 0 — a frustum / tapered column). Host API call — returns a
+   * {@linkcode BrepHandle}; commit with `design.create.massFromBrep`. Carries
+   * a creation recipe (radii + height), editable through `design.update.parameters`.
+   *
+   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
+   * of MB — expect a pause of seconds).
+   *
+   * @param base Centre of the bottom cap as plain `{x, y, z}` components
+   * @param axis Axis direction as plain `{x, y, z}` components (non-zero, normalised by the host)
+   * @param baseRadius Radius at the base (> 0)
+   * @param height Height along `axis` (> 0)
+   * @param topRadius Optional radius at the top (≥ 0, ≠ `baseRadius`; default 0 = apex)
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws VALIDATION if radii/height are invalid, `topRadius === baseRadius`
+   *   (that is a cylinder — use {@linkcode PluginGeomCreateApi.brepFromCylinder}),
+   *   or `axis` is zero-length
+   *
+   * @examplePrompt Create a cone roof 4m wide and 3m tall
+   * @examplePrompt Make a tapered column narrowing from 1m to 0.6m
+   *
+   * # Example
+   * ```ts
+   * const roof = await snaptrude.core.geom.create.brepFromCone(
+   *   { x: 0, y: 9, z: 0 },
+   *   { x: 0, y: 1, z: 0 },
+   *   2,
+   *   3,
+   * )
+   * ```
+   */
+  public abstract brepFromCone(
+    base: Vec3Components,
+    axis: Vec3Components,
+    baseRadius: number,
+    height: number,
+    topRadius?: number,
+  ): PluginApiReturn<BrepHandle>
+
+  /**
+   * Create a solid **torus** (ring / donut) B-rep from its centre, plane
+   * normal, ring radius and tube radius. Host API call — returns a
+   * {@linkcode BrepHandle}; commit with `design.create.massFromBrep`.
+   * `majorRadius` is centre-to-tube-centre; `minorRadius` is the tube's own
+   * radius and must be strictly smaller. Carries a creation recipe, editable
+   * through `design.update.parameters`.
+   *
+   * Runs on the OpenCascade kernel (the first kernel call loads a wasm of tens
+   * of MB — expect a pause of seconds).
+   *
+   * @param centre Torus centre as plain `{x, y, z}` components
+   * @param axis Plane normal of the ring as plain `{x, y, z}` components (non-zero)
+   * @param majorRadius Ring radius, centre to tube centre (> 0)
+   * @param minorRadius Tube radius (> 0 and < `majorRadius` — a self-intersecting torus is rejected)
+   * @returns The new solid as a {@linkcode BrepHandle}
+   * @throws VALIDATION if a radius is invalid, `minorRadius >= majorRadius`,
+   *   or `axis` is zero-length
+   *
+   * @examplePrompt Create a donut-shaped ring 10m across with a 1m tube
+   * @examplePrompt Add a torus canopy around the tower
+   *
+   * # Example
+   * ```ts
+   * const ring = await snaptrude.core.geom.create.brepFromTorus(
+   *   { x: 0, y: 6, z: 0 },
+   *   { x: 0, y: 1, z: 0 },
+   *   5,
+   *   1,
+   * )
+   * ```
+   */
+  public abstract brepFromTorus(
+    centre: Vec3Components,
+    axis: Vec3Components,
+    majorRadius: number,
+    minorRadius: number,
+  ): PluginApiReturn<BrepHandle>
+}
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.line}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `startPoint` | {@linkcode Vec3Handle} | Start point of the line segment |
+ * | `endPoint` | {@linkcode Vec3Handle} | End point of the line segment |
+ */
+export const PluginGeomCreateLineArgs = z.object({
+  startPoint: Vec3Handle,
+  endPoint: Vec3Handle,
+})
+
+export type PluginGeomCreateLineArgs = z.infer<typeof PluginGeomCreateLineArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.arc}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `startPoint` | {@linkcode Vec3Handle} | Start point of the arc |
+ * | `endPoint` | {@linkcode Vec3Handle} | End point of the arc |
+ * | `centrePoint` | {@linkcode Vec3Handle} | Centre point of the arc |
+ * | `axis` | {@linkcode Vec3Handle} | Axis direction of the arc |
+ */
+export const PluginGeomCreateArcArgs = z.object({
+  startPoint: Vec3Handle,
+  endPoint: Vec3Handle,
+  centrePoint: Vec3Handle,
+  axis: Vec3Handle,
+})
+
+export type PluginGeomCreateArcArgs = z.infer<typeof PluginGeomCreateArcArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.circle}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `centrePoint` | {@linkcode Vec3Handle} | Centre point of the circle |
+ * | `axis` | {@linkcode Vec3Handle} | Axis direction (plane normal) of the circle |
+ * | `radius` | `number` | Radius of the circle |
+ */
+export const PluginGeomCreateCircleArgs = z.object({
+  centrePoint: Vec3Handle,
+  axis: Vec3Handle,
+  radius: z.number(),
+})
+
+export type PluginGeomCreateCircleArgs = z.infer<typeof PluginGeomCreateCircleArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.splineFromPoints}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `points` | {@linkcode Vec3Handle}`[]` | 3..256 ordered through-points of the curve |
+ */
+export const PluginGeomCreateSplineFromPointsArgs = z.object({
+  points: z.array(Vec3Handle).min(3).max(MAX_SPLINE_THROUGH_POINTS),
+})
+
+export type PluginGeomCreateSplineFromPointsArgs = z.infer<
+  typeof PluginGeomCreateSplineFromPointsArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.splineFromControlPoints}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `controlPoints` | {@linkcode Vec3Handle}`[]` | 3..512 control points of the curve, in order |
+ * | `options` | `object`? | `degree`: 2 or 3 (default `min(3, controlPoints.length - 1)`) |
+ */
+export const PluginGeomCreateSplineFromControlPointsArgs = z.object({
+  controlPoints: z.array(Vec3Handle).min(3).max(MAX_SPLINE_POLES),
+  options: z.object({ degree: z.number().int().min(2).max(3).optional() }).optional(),
+})
+
+export type PluginGeomCreateSplineFromControlPointsArgs = z.infer<
+  typeof PluginGeomCreateSplineFromControlPointsArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.profileFromLinePoints}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `points` | {@linkcode Vec3Handle}`[]` | Ordered vertex handles of the profile |
+ */
+export const PluginGeomCreateProfileFromLinePointsArgs = z.object({
+  points: z.array(Vec3Handle),
+})
+
+export type PluginGeomCreateProfileFromLinePointsArgs = z.infer<
+  typeof PluginGeomCreateProfileFromLinePointsArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.profileFromCurves}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curves` | {@linkcode CurveHandle}`[]` | Ordered curve handles forming a closed loop |
+ */
+export const PluginGeomCreateProfileFromCurvesArgs = z.object({
+  curves: z.array(CurveHandle),
+})
+
+export type PluginGeomCreateProfileFromCurvesArgs = z.infer<
+  typeof PluginGeomCreateProfileFromCurvesArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.profileFromSplinePoints}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `points` | {@linkcode Vec3Handle}`[]` | 3..256 ordered through-points of the closed loop (first point NOT repeated) |
+ */
+export const PluginGeomCreateProfileFromSplinePointsArgs = z.object({
+  points: z.array(Vec3Handle).min(3).max(MAX_SPLINE_THROUGH_POINTS),
+})
+
+export type PluginGeomCreateProfileFromSplinePointsArgs = z.infer<
+  typeof PluginGeomCreateProfileFromSplinePointsArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.contourFromProfile}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `outer` | {@linkcode ProfileHandle} | The outer boundary loop |
+ */
+export const PluginGeomCreateContourFromProfileArgs = z.object({
+  outer: ProfileHandle,
+})
+
+export type PluginGeomCreateContourFromProfileArgs = z.infer<
+  typeof PluginGeomCreateContourFromProfileArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.contourFromProfiles}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `outer` | {@linkcode ProfileHandle} | The outer boundary loop |
+ * | `holes` | {@linkcode ProfileHandle}`[]` | Optional inner hole loops |
+ */
+export const PluginGeomCreateContourFromProfilesArgs = z.object({
+  outer: ProfileHandle,
+  holes: z.array(ProfileHandle).optional(),
+})
+
+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) |
+ * | `options` | `object`? | Optional twist and taper: `twistInDegrees` (an angle, finite), `topScale` (a ratio, finite and positive) and `levels` (a count, 2..64) |
+ */
+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" }),
+  options: z
+    .object({
+      twistInDegrees: z.number().finite().optional(),
+      topScale: z.number().finite().positive().optional(),
+      levels: z.number().int().min(2).max(MAX_TWIST_LEVELS).optional(),
+    })
+    .optional(),
+})
+
+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 (any count; more than 32 sections in all builds but carries no parameter record) |
+ * | `options` | `object`? | Optional behavior switches: `compatibility` (`"strict"` throws on mismatched edge counts instead of auto-matching; default `"auto"`), `seamAlignment` (`"authored"` keeps the authored correspondence instead of searching seam rotations; default `"auto"`) and `smoothing` (`"smooth"` lofts every section in one pass, so the sides curve through the intermediates; default `"ruled"`) |
+ */
+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(),
+      smoothing: z.enum(["ruled", "smooth"]).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 edges to fillet (one or more; more than 64 builds but carries no parameter record) |
+ * | `radius` | `number` | Fillet radius (positive, finite); the start radius with `endRadius`, unused with `radii` |
+ * | `options` | `object`? | Optional variable blend: `endRadius` (positive, finite) or `radii` (2..32 rows of `{ position, radius }`, `position` a ratio 0..1 strictly increasing). Mutually exclusive, and either one takes exactly ONE edge |
+ */
+export const PluginGeomCreateBrepFromFilletArgs = z
+  .object({
+    brep: BrepHandle,
+    edges: z.array(EdgeHandle).min(1),
+    radius: z.number().finite().positive(),
+    options: z
+      .object({
+        endRadius: z.number().finite().positive().optional(),
+        radii: z
+          .array(
+            z.object({
+              position: z.number().finite().min(0).max(1),
+              radius: z.number().finite().positive(),
+            }),
+          )
+          .min(2)
+          .max(MAX_FILLET_LAW_SAMPLES)
+          .optional(),
+      })
+      .optional(),
+  })
+  .superRefine((a, ctx) => {
+    const { endRadius, radii } = a.options ?? {}
+    if (endRadius === undefined && radii === undefined) return
+    if (endRadius !== undefined && radii !== undefined) {
+      ctx.addIssue({ code: "custom", message: "endRadius is mutually exclusive with radii" })
+    }
+    // The law belongs to the blend contour the one edge lies on, and `position`
+    // is measured from that edge's start: a second edge would have no origin.
+    if (a.edges.length !== 1) {
+      ctx.addIssue({
+        code: "custom",
+        message: "a variable fillet takes exactly one edge — the blend contour it runs along",
+      })
+    }
+    if (radii?.some((row, i) => i > 0 && row.position <= radii[i - 1].position)) {
+      ctx.addIssue({ code: "custom", message: "radii positions must strictly increase" })
+    }
+  })
+
+export type PluginGeomCreateBrepFromFilletArgs = z.infer<typeof PluginGeomCreateBrepFromFilletArgs>
+
+/** An edge with the solid it belongs to. See {@linkcode OwnedEdge}. */
+export const OwnedEdge = z.object({
+  edge: EdgeHandle,
+  brep: BrepHandle,
+  face: FaceHandle.optional(),
+})
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromPatch}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `boundary` | ({@linkcode CurveHandle} \| {@linkcode OwnedEdge})`[]` | 3..16 items forming one closed loop |
+ * | `thickness` | `number` | Solid thickness in internal length units (positive, finite) |
+ * | `options` | `object`? | `interiorPoints` (≤ 64 plain `{x, y, z}` the surface is pulled through), `continuity` (`"position"` default, or `"tangent"` — every item must then be an edge item naming its `face`), `side` (`"below"` default, or `"above"`) |
+ */
+export const PluginGeomCreateBrepFromPatchArgs = z
+  .object({
+    boundary: z
+      .array(z.union([CurveHandle, OwnedEdge]))
+      .min(3)
+      .max(MAX_PATCH_BOUNDARY_CURVES),
+    thickness: z.number().finite().positive(),
+    options: z
+      .object({
+        interiorPoints: z.array(FiniteVec3Components).max(MAX_PATCH_INTERIOR_POINTS).optional(),
+        continuity: z.enum(["position", "tangent"]).optional(),
+        side: z.enum(["below", "above"]).optional(),
+      })
+      .optional(),
+  })
+  .superRefine((a, ctx) => {
+    if (a.options?.continuity !== "tangent") return
+    // The kernel's filling call (`Add_2`) follows exactly ONE support face per
+    // edge, but a solid edge touches two faces. So a tangent patch must say
+    // which face to follow, for every item, and this is checked before the host
+    // runs.
+    if (a.boundary.some((item) => !("edge" in item) || item.face === undefined)) {
+      ctx.addIssue({
+        code: "custom",
+        message:
+          'continuity: "tangent" needs every boundary item to be an edge with its brep and the face to continue',
+      })
+    }
+  })
+
+export type PluginGeomCreateBrepFromPatchArgs = z.infer<typeof PluginGeomCreateBrepFromPatchArgs>
+
+/**
+ * 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 (one or more; more than 32 builds but carries no parameter record) |
+ * | `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.brepsFromSplitByFace}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `brep` | {@linkcode BrepHandle} | The solid to cut |
+ * | `toolFace` | {@linkcode FaceHandle} | The cutting face (read-only) |
+ * | `toolBrep` | {@linkcode BrepHandle} | The solid `toolFace` belongs to (owner last) |
+ */
+export const PluginGeomCreateBrepsFromSplitByFaceArgs = z.object({
+  brep: BrepHandle,
+  toolFace: FaceHandle,
+  toolBrep: BrepHandle,
+})
+
+export type PluginGeomCreateBrepsFromSplitByFaceArgs = z.infer<
+  typeof PluginGeomCreateBrepsFromSplitByFaceArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.curvesFromProjection}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The curve to project |
+ * | `face` | {@linkcode FaceHandle} | The face to project onto |
+ * | `faceBrep` | {@linkcode BrepHandle} | The solid `face` belongs to (owner last) |
+ */
+export const PluginGeomCreateCurvesFromProjectionArgs = z.object({
+  curve: CurveHandle,
+  face: FaceHandle,
+  faceBrep: BrepHandle,
+})
+
+export type PluginGeomCreateCurvesFromProjectionArgs = z.infer<
+  typeof PluginGeomCreateCurvesFromProjectionArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromChamfer}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `brep` | {@linkcode BrepHandle} | The solid whose edges to bevel |
+ * | `edges` | {@linkcode EdgeHandle}`[]` | The edges to chamfer (one or more; more than 64 builds but carries no parameter record) |
+ * | `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 or more points, finite components — more than 512 builds but carries no parameter record; 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), `"round"` (arc-carried corners) 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.literal("round"),
+            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.brepFromSweepAlongCurve}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode ContourHandle} | The cross-section to sweep (hole-free) |
+ * | `path` | {@linkcode CurveHandle}`[]` | 1..64 curves, ordered, meeting end to end |
+ * | `options` | `object`? | `orientation` — `"upright"` (default), `"frenet"` or `"fixed"`; `rail` — a second guide {@linkcode CurveHandle} |
+ */
+export const PluginGeomCreateBrepFromSweepAlongCurveArgs = z.object({
+  profile: ContourHandle,
+  path: z.array(CurveHandle).min(1).max(MAX_PATH_CURVES),
+  options: z
+    .object({
+      orientation: z.enum(["frenet", "fixed", "upright"]).optional(),
+      rail: CurveHandle.optional(),
+    })
+    .optional(),
+})
+
+export type PluginGeomCreateBrepFromSweepAlongCurveArgs = z.infer<
+  typeof PluginGeomCreateBrepFromSweepAlongCurveArgs
+>
+
+/**
+ * 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; the axis must lie in the plane of the profile) |
+ * | `axisDirection` | {@linkcode Vec3Components} | The axis direction (non-zero, finite components; the axis must lie in the plane of the profile) |
+ * | `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
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromSphere}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `centre` | {@linkcode Vec3Components} | Sphere centre (finite components) |
+ * | `radius` | `number` | Sphere radius (finite; positivity is checked host-side so the error names the parameter) |
+ */
+export const PluginGeomCreateBrepFromSphereArgs = z.object({
+  centre: FiniteVec3Components,
+  radius: z.number().finite(),
+})
+
+export type PluginGeomCreateBrepFromSphereArgs = z.infer<
+  typeof PluginGeomCreateBrepFromSphereArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromCylinder}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `base` | {@linkcode Vec3Components} | Centre of the bottom cap (finite components) |
+ * | `axis` | {@linkcode Vec3Components} | Axis direction (non-zero, finite components) |
+ * | `radius` | `number` | Cylinder radius (finite, positive) |
+ * | `height` | `number` | Height along `axis` (finite, positive) |
+ */
+export const PluginGeomCreateBrepFromCylinderArgs = z.object({
+  base: FiniteVec3Components,
+  axis: FiniteVec3Components,
+  radius: z.number().finite(),
+  height: z.number().finite(),
+})
+
+export type PluginGeomCreateBrepFromCylinderArgs = z.infer<
+  typeof PluginGeomCreateBrepFromCylinderArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromCone}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `base` | {@linkcode Vec3Components} | Centre of the bottom cap (finite components) |
+ * | `axis` | {@linkcode Vec3Components} | Axis direction (non-zero, finite components) |
+ * | `baseRadius` | `number` | Radius at the base (finite, positive) |
+ * | `height` | `number` | Height along `axis` (finite, positive) |
+ * | `topRadius` | `number`? | Radius at the top (finite, ≥ 0, ≠ `baseRadius`; default 0 = apex) |
+ */
+export const PluginGeomCreateBrepFromConeArgs = z
+  .object({
+    base: FiniteVec3Components,
+    axis: FiniteVec3Components,
+    baseRadius: z.number().finite(),
+    height: z.number().finite(),
+    topRadius: z.number().finite().optional(),
+  })
+  .refine((a) => (a.topRadius ?? 0) !== a.baseRadius, {
+    message: "topRadius must differ from baseRadius — equal radii are a cylinder",
+  })
+
+export type PluginGeomCreateBrepFromConeArgs = z.infer<typeof PluginGeomCreateBrepFromConeArgs>
+
+/**
+ * Arguments for {@linkcode PluginGeomCreateApi.brepFromTorus}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `centre` | {@linkcode Vec3Components} | Torus centre (finite components) |
+ * | `axis` | {@linkcode Vec3Components} | Plane normal of the ring (non-zero, finite components) |
+ * | `majorRadius` | `number` | Ring radius, centre to tube centre (finite, positive) |
+ * | `minorRadius` | `number` | Tube radius (finite, positive, strictly less than `majorRadius`) |
+ */
+export const PluginGeomCreateBrepFromTorusArgs = z
+  .object({
+    centre: FiniteVec3Components,
+    axis: FiniteVec3Components,
+    majorRadius: z.number().finite(),
+    minorRadius: z.number().finite(),
+  })
+  .refine((a) => a.minorRadius < a.majorRadius, {
+    message: "minorRadius must be smaller than majorRadius — the torus would self-intersect",
+  })
+
+export type PluginGeomCreateBrepFromTorusArgs = z.infer<typeof PluginGeomCreateBrepFromTorusArgs>