@snaptrude/plugin-core 0.9.13 → 0.9.14

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

@@ -1,15 +1,46 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../../types"
-import { Vec3Handle, LineHandle, ArcHandle, CircleHandle, CurveHandle, ProfileHandle, ContourHandle, BrepHandle, FaceHandle, EdgeHandle, Vec3Components } from "../../../../handles"
+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} or {@linkcode ArcHandle}) that you pass to
- * query, update, or entity-creation methods. Read geometry back as plain values
- * via the `snaptrude.core.geom.query.*` methods.
+ * 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`.
  */
@@ -83,6 +114,97 @@ export abstract class PluginGeomCreateApi {
     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.
@@ -117,8 +239,42 @@ export abstract class PluginGeomCreateApi {
   public abstract profileFromCurves(curves: CurveHandle[]): PluginApiReturn<ProfileHandle>
 
   /**
-   * Create an axis-aligned **rectangle** profile (XZ plane) of `width` × `depth`,
-   * centred at `center` (defaults to the origin). Host API call — returns a handle.
+   * 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
@@ -237,15 +393,34 @@ export abstract class PluginGeomCreateApi {
    *
    * @param contour The cross-section to extrude (outer profile + optional holes)
    * @param direction Extrusion direction as plain `{x, y, z}` components (non-zero, normalised by the host)
-   * @param amount Extrusion distance (non-zero; negative extrudes opposite to `direction`)
+   * @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 contour plane) or the contour cannot be extruded
-   *   into a valid solid
+   *   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
@@ -259,6 +434,81 @@ export abstract class PluginGeomCreateApi {
     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>
 
   /**
@@ -274,8 +524,8 @@ export abstract class PluginGeomCreateApi {
    * unchanged. A pair whose side faces would be non-planar under every
    * correspondence still builds for hole-free straight-edged pairs — planar
    * side quads stay quads and warped ones split into planar triangles (the
-   * triangulated lane); arc-bearing or holed twisted pairs are rejected, as is
-   * auto-matching that would pair an arc with a straight edge. Matching hole
+   * 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
@@ -289,7 +539,9 @@ export abstract class PluginGeomCreateApi {
    *   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)
+   *   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,
@@ -297,9 +549,13 @@ export abstract class PluginGeomCreateApi {
    *   `"auto"` (default) searches seam rotations on straight-edge sections to
    *   avoid a twist; `"authored"` keeps the authored start-vertex
    *   correspondence unchanged (a twisted correspondence then builds through
-   *   the triangulated lane for hole-free straight-edged pairs).
+   *   the triangulated fallback for hole-free straight-edged pairs).
    *   `{ compatibility: "strict", seamAlignment: "authored" }` reproduces
-   *   pre-0.9.4 lofting exactly.
+   *   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
@@ -321,6 +577,7 @@ export abstract class PluginGeomCreateApi {
    * @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
@@ -338,7 +595,11 @@ export abstract class PluginGeomCreateApi {
     bottomContour: ContourHandle,
     topContour: ContourHandle,
     intermediateContours?: ContourHandle[],
-    options?: { compatibility?: "strict" | "auto"; seamAlignment?: "authored" | "auto" },
+    options?: {
+      compatibility?: "strict" | "auto"
+      seamAlignment?: "authored" | "auto"
+      smoothing?: "ruled" | "smooth"
+    },
   ): PluginApiReturn<BrepHandle>
 
   /**
@@ -474,44 +735,95 @@ export abstract class PluginGeomCreateApi {
   public abstract brepFromIntersection(a: BrepHandle, b: BrepHandle): PluginApiReturn<BrepHandle>
 
   /**
-   * Rounds the given straight edges of a solid with a constant radius. Host
-   * API call — returns a new {@linkcode BrepHandle}; the input brep is
-   * read-only.
-   *
-   * v1 fillets straight edges only, and no two filleted edges may share a
-   * vertex — corner blends produce spherical patches Snaptrude cannot
-   * represent. Runs on the OpenCascade kernel (the first kernel call loads a
-   * wasm of tens of MB — expect a pause of seconds).
+   * 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 straight edges to fillet (≥1, all on `brep`, no two sharing a vertex)
-   * @param radius Fillet radius (positive, finite)
+   * @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, `radius` is not a positive finite
-   *   number, an edge is not on `brep`, an edge is an arc (v1 fillets straight
-   *   edges only), or two edges share a vertex (fillet non-adjacent edges)
-   * @throws OPERATION_FAILED if the kernel cannot build the fillet (the radius
-   *   likely exceeds the adjacent face size — reduce it) or the result
-   *   contains curved surfaces Snaptrude cannot represent
-   *
-   * @examplePrompt Round the edges of this mass
+   * @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
-   * const brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)
-   * const edges = await snaptrude.core.geom.query.brep.listEdges(brep)
-   * const rounded = await snaptrude.core.geom.create.brepFromFillet(brep, [edges[0]], 0.3)
+   * // 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>
 
   /**
@@ -519,6 +831,14 @@ export abstract class PluginGeomCreateApi {
    * 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).
    *
@@ -530,9 +850,15 @@ export abstract class PluginGeomCreateApi {
    * @returns The offset solid as a new {@linkcode BrepHandle}
    * @throws VALIDATION if `distance` is not finite, is too small to offset
    *   anything, or an inward distance consumes the solid entirely
-   * @throws OPERATION_FAILED if the kernel cannot build the offset or the
-   *   result contains curved surfaces Snaptrude cannot represent
-   *
+   * @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
@@ -551,6 +877,18 @@ export abstract class PluginGeomCreateApi {
    * 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).
    *
@@ -558,24 +896,36 @@ export abstract class PluginGeomCreateApi {
    * with `design.create.massFromBrep`.
    *
    * @param brep The solid to hollow
-   * @param openFaces The faces to remove as openings (≥1, all on `brep`)
+   * @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, a face is not on `brep`,
-   *   `thickness` is not a positive finite number, or the thickness is too
-   *   large (it must be smaller than half the solid's smallest span)
-   * @throws OPERATION_FAILED if the kernel cannot build the shell or the
-   *   result contains curved surfaces Snaptrude cannot represent
-   *
+   * @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
-   * const brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)
-   * const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
-   * const hollow = await snaptrude.core.geom.create.brepFromShell(brep, [faces[0]], 0.2)
+   * // 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(
@@ -625,28 +975,89 @@ export abstract class PluginGeomCreateApi {
   ): PluginApiReturn<BrepHandle[]>
 
   /**
-   * Bevels the given straight edges of a solid with a symmetric planar cut.
-   * Host API call — returns a new {@linkcode BrepHandle}; the input brep is
-   * read-only.
+   * 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
    *
-   * v1 chamfers straight edges only, and no two chamfered edges may share a
-   * vertex. Runs on the OpenCascade kernel (the first kernel call loads a
-   * wasm of tens of MB — expect a pause of seconds).
+   * # 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 straight edges to chamfer (≥1, all on `brep`, no two sharing a vertex)
+   * @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, `distance` is not a positive
-   *   finite number, an edge is not on `brep`, an edge is an arc (v1 chamfers
-   *   straight edges only), or two edges share a vertex (chamfer non-adjacent
-   *   edges)
-   * @throws OPERATION_FAILED if the kernel cannot build the chamfer (the
-   *   distance likely exceeds the adjacent face size — reduce it)
-   *
+   * @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
@@ -682,11 +1093,16 @@ export abstract class PluginGeomCreateApi {
    * tapering across a bend or along an arc edge would create faces Snaptrude
    * cannot represent and throws (sweep each straight run separately and union
    * the results instead). An optional `transition` picks the corner
-   * treatment: `"miter"` (default) is today's sharp mitred bend;
+   * 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 the
-   * varying-scale lane takes straight paths, so it never sees a corner.
+   * 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
@@ -696,19 +1112,22 @@ export abstract class PluginGeomCreateApi {
    * with `design.create.massFromBrep`.
    *
    * @param profile The cross-section to sweep (hole-free contour)
-   * @param path The polyline path as plain `{x, y, z}` points (≥2; repeat the
-   *   first point as the last to close the path into a ring)
+   * @param 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) or
-   *   `{ bevel: b }` (chamfered corners, `b` finite within 1e-3..1e3; open
-   *   and closed paths)
+   *   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
+   *   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
@@ -716,11 +1135,14 @@ export abstract class PluginGeomCreateApi {
    *   is combined with `startScale`/`endScale`, `scales` does not match the
    *   path length, or a varying scale is used on a bent or closed path or
    *   with an arc-edged profile; for `{ bevel }`, if a leg is too short for
-   *   the cuts its beveled corners take from it or a corner nearly doubles
-   *   back so its chamfer collapses (the errors name the corner)
+   *   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 or a transition patch is a curved surface Snaptrude cannot
-   *   represent
+   *   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
@@ -729,6 +1151,7 @@ export abstract class PluginGeomCreateApi {
    * @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
@@ -767,17 +1190,76 @@ export abstract class PluginGeomCreateApi {
       startScale?: number
       endScale?: number
       scales?: number[]
-      transition?: "miter" | { bevel: 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. Profile segments must stay parallel or perpendicular
-   * to the axis — inclined or arc segments would revolve into surfaces
-   * Snaptrude cannot represent.
+   * 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).
@@ -791,19 +1273,25 @@ export abstract class PluginGeomCreateApi {
    * @param angleInDegrees Optional revolution angle in degrees (0 < angle ≤ 360; default 360)
    * @returns The revolved solid as a new {@linkcode BrepHandle}
    * @throws VALIDATION if `axisDirection` is zero-length, `angleInDegrees` is
-   *   not in (0, 360], the axis passes through the profile interior, or a
-   *   coordinate is not finite
-   * @throws OPERATION_FAILED if the kernel cannot revolve the profile or the
-   *   result contains curved surfaces Snaptrude cannot represent (keep
-   *   profile segments parallel or perpendicular to the axis)
+   *   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
+   * // 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),
@@ -824,6 +1312,159 @@ export abstract class PluginGeomCreateApi {
     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>
 }
 
 /**
@@ -877,6 +1518,38 @@ export const PluginGeomCreateCircleArgs = z.object({
 
 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}.
  *
@@ -907,6 +1580,21 @@ 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}.
  *
@@ -962,6 +1650,7 @@ export type PluginGeomCreateBrepFromFacesArgs = z.infer<
  * | `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,
@@ -974,6 +1663,13 @@ export const PluginGeomCreateBrepFromExtrusionArgs = z.object({
     .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<
@@ -987,8 +1683,8 @@ export type PluginGeomCreateBrepFromExtrusionArgs = z.infer<
  * |---|---|---|
  * | `bottomContour` | {@linkcode ContourHandle} | The bottom cross-section |
  * | `topContour` | {@linkcode ContourHandle} | The top cross-section |
- * | `intermediateContours` | {@linkcode ContourHandle}`[]`? | Optional in-between cross-sections, ordered bottom to top |
- * | `options` | `object`? | Optional behavior switches: `compatibility` (`"strict"` throws on mismatched edge counts instead of auto-matching; default `"auto"`) and `seamAlignment` (`"authored"` keeps the authored correspondence instead of searching seam rotations; default `"auto"`) |
+ * | `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,
@@ -998,6 +1694,7 @@ export const PluginGeomCreateBrepFromLoftArgs = z.object({
     .object({
       compatibility: z.enum(["strict", "auto"]).optional(),
       seamAlignment: z.enum(["authored", "auto"]).optional(),
+      smoothing: z.enum(["ruled", "smooth"]).optional(),
     })
     .optional(),
 })
@@ -1050,16 +1747,99 @@ const FiniteVec3Components = z.object({
  * | Property | Type | Description |
  * |---|---|---|
  * | `brep` | {@linkcode BrepHandle} | The solid whose edges to round |
- * | `edges` | {@linkcode EdgeHandle}`[]` | The straight edges to fillet (≥1) |
- * | `radius` | `number` | Fillet radius (positive, finite) |
+ * | `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({
+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,
-  edges: z.array(EdgeHandle).min(1),
-  radius: z.number().finite().positive(),
+  face: FaceHandle.optional(),
 })
 
-export type PluginGeomCreateBrepFromFilletArgs = z.infer<typeof PluginGeomCreateBrepFromFilletArgs>
+/**
+ * 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}.
@@ -1085,7 +1865,7 @@ export type PluginGeomCreateBrepFromOffsetArgs = z.infer<typeof PluginGeomCreate
  * | Property | Type | Description |
  * |---|---|---|
  * | `brep` | {@linkcode BrepHandle} | The solid to hollow |
- * | `openFaces` | {@linkcode FaceHandle}`[]` | The faces to remove as openings (≥1) |
+ * | `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({
@@ -1113,13 +1893,51 @@ export const PluginGeomCreateBrepsFromSplitArgs = z.object({
 
 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 straight edges to chamfer (≥1) |
+ * | `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({
@@ -1142,8 +1960,8 @@ const SweepScaleFactor = z.number().finite().min(1e-3).max(1e3)
  * | Property | Type | Description |
  * |---|---|---|
  * | `profile` | {@linkcode ContourHandle} | The cross-section to sweep (hole-free) |
- * | `path` | {@linkcode Vec3Components}`[]` | The polyline path (≥2 points, finite components; repeating the first point as the last closes it into a ring — closed paths must be flat and straight-segmented and take a straight-edged profile) |
- * | `options` | `object`? | Optional scale law: `startScale`/`endScale` (linear taper by arc length) or per-point `scales` (mutually exclusive; factors finite, 1e-3..1e3; `scales.length` must equal `path.length`). Optional corner `transition`: `"miter"` (default) or `{ bevel }` (chamfered corners; finite, 1e-3..1e3) |
+ * | `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({
@@ -1157,6 +1975,7 @@ export const PluginGeomCreateBrepFromSweepArgs = z
         transition: z
           .union([
             z.literal("miter"),
+            z.literal("round"),
             z.object({ bevel: z.number().finite().min(1e-3).max(1e3) }),
           ])
           .optional(),
@@ -1182,14 +2001,38 @@ export const PluginGeomCreateBrepFromSweepArgs = z
 
 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) |
- * | `axisDirection` | {@linkcode Vec3Components} | The axis direction (non-zero, finite components) |
+ * | `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({
@@ -1202,3 +2045,89 @@ export const PluginGeomCreateBrepFromRevolutionArgs = z.object({
 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>