@metamesh/modeling 0.6.0 → 0.8.0

package/dist/api/index.d.ts

@@ -32,7 +32,9 @@ export declare interface Anchor3 {
 /** Host-bound attach operation. Valid only during a synchronous build. */
 export declare const attach: ModelingContext["attach"];
 
-/** Degree-based anchor attachment controls for a scoped solid. */
+/**
+ * Degree-based anchor attachment controls for a scoped solid.
+ */
 export declare interface AttachOptions {
     /** Align outward directions face-to-face (`opposed`) or in parallel (`same`). */
     readonly alignment?: "opposed" | "same";
@@ -56,7 +58,9 @@ export declare type BoxEdgeSelection = BoxEdge | "top" | "bottom" | "vertical";
 /** Independent treatments for disjoint named edge selections; overlapping selections fail. */
 export declare type BoxEdgeTreatments = Readonly<Partial<Record<BoxEdgeSelection, EdgeTreatment>>>;
 
-/** Dimensions, placement, and uniform or independently selected finishing for an axis-aligned box. */
+/**
+ * Dimensions, placement, and uniform or independently selected finishing for an axis-aligned box.
+ */
 export declare interface BoxOptions extends PrimitivePlacement {
     /** Explicit sampling ceilings for edge treatments, bounded by the host policy. */
     readonly limits?: Partial<GeometrySamplingLimits>;
@@ -94,7 +98,9 @@ declare interface ButtressThreadProfileSpec extends ThreadProfileBaseSpec {
     readonly pressureFlankSide?: ButtressPressureFlankSide;
 }
 
-/** A planar edge or corner chamfer with equal or independent surface setbacks. */
+/**
+ * A planar edge or corner chamfer with equal or independent surface setbacks.
+ */
 export declare interface ChamferedEdgeTreatment {
     /** Selects a straight bevel between adjoining surfaces. */
     readonly kind: "chamfer";
@@ -105,7 +111,9 @@ export declare interface ChamferedEdgeTreatment {
 /** Host-bound circle operation. Valid only during a synchronous build. */
 export declare const circle: ModelingContext["circle"];
 
-/** Circular profile dimensions with exactly one radius or diameter and explicit sampling. */
+/**
+ * Circular profile dimensions with exactly one radius or diameter and explicit sampling.
+ */
 export declare type CircleLoopOptions = CircularPrimitiveOptions & RadialSizingOptions & ({
     /** Positive nominal radius in millimetres; mutually exclusive with diameter. */
     readonly radius: number;
@@ -118,10 +126,14 @@ export declare type CircleLoopOptions = CircularPrimitiveOptions & RadialSizingO
     readonly radius?: never;
 });
 
-/** Circular dimensions with exactly one nominal radius or diameter. */
+/**
+ * Circular dimensions with exactly one nominal radius or diameter.
+ */
 export declare type CircleOptions = CircleLoopOptions & PrimitivePlacement;
 
-/** Tessellation controls shared by circular primitives across Geometry entry points. */
+/**
+ * Tessellation controls shared by circular primitives across Geometry entry points.
+ */
 export declare interface CircularPrimitiveOptions {
     /** Explicit sampling ceilings; bound modeling operations may only lower the host policy. */
     readonly limits?: Partial<GeometrySamplingLimits>;
@@ -188,7 +200,9 @@ declare interface CustomThreadProfileSpec extends ThreadProfileBaseSpec {
 /** Host-bound cylinder operation. Valid only during a synchronous build. */
 export declare const cylinder: ModelingContext["cylinder"];
 
-/** Dimensions, placement, independent end finishing, and tessellation for a Z-axis cylinder or frustum. */
+/**
+ * Dimensions, placement, independent end finishing, and tessellation for a Z-axis cylinder or frustum.
+ */
 export declare type CylinderOptions = CircularPrimitiveOptions & RadialSizingOptions & PrimitivePlacement & {
     /**
      * Centers the solid on the Z origin when `true`; otherwise its bottom is at `Z = 0`.
@@ -211,13 +225,20 @@ export declare type CylinderOptions = CircularPrimitiveOptions & RadialSizingOpt
     readonly radius?: never;
 });
 
-/** Uniform finishing vocabulary shared by applicable solid edges and profile corners. */
+/** Measures the minimum separation between two nonempty solids in millimetres. */
+export declare const distance: ModelingContext["distance"];
+
+/**
+ * Uniform finishing vocabulary shared by applicable solid edges and profile corners.
+ */
 export declare type EdgeTreatment = ChamferedEdgeTreatment | RoundedEdgeTreatment | SmoothEdgeTreatment | ProfiledEdgeTreatment;
 
 /** Host-bound ellipse operation. Valid only during a synchronous build. */
 export declare const ellipse: ModelingContext["ellipse"];
 
-/** Ellipse dimensions with exactly one XY radii or full-size tuple and explicit sampling. */
+/**
+ * Ellipse dimensions with exactly one XY radii or full-size tuple and explicit sampling.
+ */
 export declare type EllipseLoopOptions = CircularPrimitiveOptions & ({
     /** Positive XY radii in millimetres; mutually exclusive with size. */
     readonly radius: Vec2;
@@ -230,10 +251,14 @@ export declare type EllipseLoopOptions = CircularPrimitiveOptions & ({
     readonly radius?: never;
 });
 
-/** Ellipse dimensions in local XY, with exactly one radii or full-size tuple. */
+/**
+ * Ellipse dimensions in local XY, with exactly one radii or full-size tuple.
+ */
 export declare type EllipseOptions = EllipseLoopOptions & PrimitivePlacement;
 
-/** Independent inward finishing on primitive or straight convex extrusion ends. */
+/**
+ * Independent inward finishing on primitive or straight convex extrusion ends.
+ */
 export declare interface EndTreatments {
     /** Bottom cap and adjoining side; omitted leaves the end untreated. */
     readonly bottom?: EdgeTreatment;
@@ -244,7 +269,9 @@ export declare interface EndTreatments {
 /** Host-bound extrude operation. Valid only during a synchronous build. */
 export declare const extrude: ModelingContext["extrude"];
 
-/** Dimensions and sampling shared by native and pure +Z extrusion. */
+/**
+ * Dimensions and sampling shared by native and pure +Z extrusion.
+ */
 export declare interface ExtrudeOptions extends ExtrusionSamplingOptions {
     /** Positive extrusion height in millimetres. */
     readonly height: number;
@@ -318,7 +345,9 @@ export declare interface Frame3 {
 /** Host-bound fromRegion operation. Valid only during a synchronous build. */
 export declare const fromRegion: ModelingContext["fromRegion"];
 
-/** Tessellation policy for sampled geometry measured in millimetres. */
+/**
+ * Tessellation policy for sampled geometry measured in millimetres.
+ */
 export declare interface GeometryResolution {
     /** Optional exact full-circle segment count, of at least three, bounded by the selected circular ceiling. */
     readonly circularSegments?: number;
@@ -357,7 +386,9 @@ export declare interface GeometryToleranceOptions {
 /** Host-bound gridPattern operation. Valid only during a synchronous build. */
 export declare const gridPattern: ModelingContext["gridPattern"];
 
-/** XY or XYZ grid with X varying fastest. The first item starts at the local origin. */
+/**
+ * XY or XYZ grid with X varying fastest. The first item starts at the local origin.
+ */
 export declare type GridPatternOptions = {
     /** Center the complete distribution around its local origin; defaults to false. */
     readonly center?: boolean;
@@ -375,22 +406,57 @@ export declare type GridPatternOptions = {
     readonly spacing: Vec3;
 });
 
-/** Constructs a closed regularly sampled heightfield during the active synchronous build. */
+/** Constructs a closed rectilinear heightfield during the active synchronous build. */
 export declare const heightfield: ModelingContext["heightfield"];
 
-/** A regularly sampled, closed heightfield above a flat base, in millimetres. */
-export declare interface HeightfieldOptions {
-    /** Positive XY footprint. */
-    readonly size: Vec2;
-    /** Exact positive integer X/Y interval counts. */
-    readonly segments: readonly [x: number, y: number];
+/**
+ * A closed rectilinear heightfield above a flat base, with uniform or explicit XY samples in millimetres.
+ *
+ * Uniform sampling requires positive `size: [width, depth]` and positive integer `segments: [x, y]`.
+ * Optional `origin` sets the lower-left XY corner; omitting it centres the footprint on XY.
+ * Alternatively, supply `coordinates: { x, y }` with at least two strictly increasing finite
+ * absolute samples per axis, distinct in Float32. This infers the footprint and interval counts;
+ * `size`, `segments`, and `origin` cannot be combined with explicit coordinates.
+ */
+export declare type HeightfieldOptions = {
     /** Absolute top Z at the supplied XY point. Every sample must be above baseZ. */
     readonly height: (point: Vec2) => number;
     /** Flat bottom Z. Defaults to zero. */
     readonly baseZ?: number;
+    /**
+     * Top-cell diagonal policy. Defaults to fixed (lower-left to upper-right).
+     * min-edge selects the shorter 3D diagonal; center-error selects the diagonal whose endpoint
+     * average is closest to one extra height sample at the physical cell centre. Ties use fixed.
+     * All policies retain two triangles per cell; neither estimates error elsewhere in the cell.
+     */
+    readonly triangulation?: "fixed" | "min-edge" | "center-error";
+} & ({
+    /** Positive XY footprint for uniform sampling. */
+    readonly size: Vec2;
+    /** Exact positive integer X/Y interval counts. */
+    readonly segments: readonly [x: number, y: number];
     /** Lower-left footprint XY. Omitted centers the footprint on XY. */
     readonly origin?: Vec2;
-}
+    /** Explicit coordinates cannot be combined with uniform sampling. */
+    readonly coordinates?: never;
+} | {
+    /**
+     * Absolute XY coordinates, each with at least two strictly increasing finite values that
+     * remain distinct in Float32. Uneven spacing permits caller-owned local refinement.
+     */
+    readonly coordinates: {
+        /** Absolute X samples in ascending order. */
+        readonly x: readonly number[];
+        /** Absolute Y samples in ascending order. */
+        readonly y: readonly number[];
+    };
+    /** The footprint is inferred from explicit coordinates. */
+    readonly size?: never;
+    /** Interval counts are inferred from explicit coordinates. */
+    readonly segments?: never;
+    /** Explicit coordinates already include their origin. */
+    readonly origin?: never;
+});
 
 /** Runtime-neutral options for the dedicated helical ridge mesher. */
 export declare interface HelicalThreadRidgeMeshOptions {
@@ -460,7 +526,7 @@ export declare interface ImplicitOptions {
     readonly edgeLength: number;
     /** Field isosurface value; defaults to zero. */
     readonly level?: number;
-    /** Explicit nonnegative native geometric tolerance in millimetres. */
+    /** Positive native geometric tolerance in millimetres; omitted uses interpolated grid crossings. */
     readonly tolerance?: number;
 }
 
@@ -484,10 +550,15 @@ export declare interface InternalThreadCutterOptions extends Omit<HelicalThreadR
 /** Host-bound intersect operation. Valid only during a synchronous build. */
 export declare const intersect: ModelingContext["intersect"];
 
+/** Tests a solid or filled section in the active build, including expected empty Boolean results. */
+export declare const isEmpty: ModelingContext["isEmpty"];
+
 /** Host-bound linearPattern operation. Valid only during a synchronous build. */
 export declare const linearPattern: ModelingContext["linearPattern"];
 
-/** Equal linear intervals determined by exactly two of count, spacing and total length. */
+/**
+ * Equal linear intervals determined by exactly two of count, spacing and total length.
+ */
 export declare type LinearPatternOptions = {
     /** Direction of repetition; magnitude is ignored. Defaults to +X. */
     readonly direction?: Vec3;
@@ -520,7 +591,9 @@ export declare const loft: ModelingContext["loft"];
 /** Deterministic ordered edge subdivision or bounded geometric vertex association. */
 export declare type LoftCorrespondence = "direct" | "reindex" | "fast-distance" | "distance";
 
-/** Shared controls for native and pure lofts. Point data and arbitrary Sections require explicit correspondence. */
+/**
+ * Shared controls for native and pure lofts. Point data and arbitrary Sections require explicit correspondence.
+ */
 export declare interface LoftOptions {
     /** One method or one per consecutive station gap. Omitted preserves known landmarks, including circle/ellipse-to-rectangle corners, or maps other unlike primitive seams directly. */
     readonly correspondence?: LoftCorrespondence | readonly LoftCorrespondence[];
@@ -536,7 +609,9 @@ export declare interface LoftOptions {
     readonly limits?: Partial<ModelingLimits>;
 }
 
-/** A horizontal XY station height, or an explicit right-handed spatial frame, never both. */
+/**
+ * A horizontal XY station height, or an explicit right-handed spatial frame, never both.
+ */
 export declare type LoftPlacement = {
     /** Horizontal XY station height in millimetres. */
     readonly z: number;
@@ -549,7 +624,9 @@ export declare type LoftPlacement = {
     readonly z?: never;
 };
 
-/** A Section or point loop at an explicit height or frame. */
+/**
+ * A Section or point loop at an explicit height or frame.
+ */
 export declare type LoftStation = LoftPlacement & {
     /** Same-build filled Section or ordered XY boundary point data. */
     readonly profile: Section | Loop2;
@@ -574,7 +651,9 @@ export declare interface MatchProfilesOptions {
     readonly limits?: Partial<GeometrySamplingLimits>;
 }
 
-/** Axis-aligned bounds of a non-empty triangle mesh. */
+/**
+ * Axis-aligned bounds of a non-empty triangle mesh.
+ */
 export declare interface MeshBounds {
     /** Inclusive minimum XYZ coordinates. */
     readonly min: Vec3;
@@ -607,129 +686,544 @@ export declare const mirror: ModelingContext["mirror"];
 export declare interface ModelingContext {
     /** Derives a context with explicit physical sampling defaults in the same execution. */
     withResolution(this: void, resolution: GeometryResolution): ModelingContext;
-    /** Axis-aligned box with uniform or disjoint named edge/group treatments. */
+    /**
+     * Axis-aligned box with uniform or disjoint named edge/group treatments.
+     *
+     * @example Rounded box
+     * ```ts
+     * box({ size: [30, 20, 8], treatment: { kind: "round", radius: 2 } });
+     * ```
+     */
     box(this: void, options: BoxOptions): Solid;
-    /** +Z cylinder or frustum. Face sizing compensates polygon faceting. */
+    /**
+     * +Z cylinder or frustum. Face sizing compensates polygon faceting.
+     *
+     * @example Cylinder
+     * ```ts
+     * cylinder({ height: 20, radius: 10 });
+     * ```
+     *
+     * @example Cone
+     * ```ts
+     * cylinder({ height: 20, radius: [10, 0] });
+     * ```
+     */
     cylinder(this: void, options: CylinderOptions): Solid;
-    /** Hollow +Z tube. */
+    /**
+     * Hollow +Z tube.
+     *
+     * @example Tube
+     * ```ts
+     * tube({ height: 20, outerRadius: 10, innerRadius: 6 });
+     * ```
+     */
     tube(this: void, options: TubeOptions): Solid;
-    /** Origin-centered sphere. */
+    /**
+     * Origin-centered sphere.
+     *
+     * @example Sphere
+     * ```ts
+     * sphere({ diameter: 20 });
+     * ```
+     */
     sphere(this: void, options: SphereOptions): Solid;
-    /** Torus around +Z. */
+    /**
+     * Torus around +Z.
+     *
+     * @example Torus
+     * ```ts
+     * torus({ majorRadius: 12, minorRadius: 3 });
+     * ```
+     */
     torus(this: void, options: TorusOptions): Solid;
-    /** Robust union. */
+    /**
+     * Robust union.
+     *
+     * @example Union
+     * ```ts
+     * const block = box({ size: 20 });
+     * const cap = translate(sphere({ radius: 10 }), [0, 0, 10]);
+     * union([block, cap]);
+     * ```
+     */
     union(this: void, solids: readonly Solid[]): Solid;
     /** Native filled section union; dimensions cannot be mixed. */
     union(this: void, sections: readonly Section[]): Section;
-    /** Robust difference; an empty cutter array preserves the source. */
+    /**
+     * Robust difference; an empty cutter array preserves the source.
+     *
+     * @example Subtract
+     * ```ts
+     * const plate = box({ size: [30, 20, 6] });
+     * // Extend the cutter beyond both faces.
+     * const bore = cylinder({ height: 8, radius: 3, sizing: "face" });
+     * subtract(plate, [bore]);
+     * ```
+     */
     subtract(this: void, solid: Solid, cutters: readonly Solid[]): Solid;
     /** Native section difference; an empty cutter array preserves the source. */
     subtract(this: void, section: Section, cutters: readonly Section[]): Section;
-    /** Robust intersection. */
+    /**
+     * Robust intersection.
+     *
+     * @example Intersect
+     * ```ts
+     * intersect([box({ size: 20 }), sphere({ radius: 12 })]);
+     * ```
+     */
     intersect(this: void, solids: readonly Solid[]): Solid;
     /** Native filled section intersection; dimensions cannot be mixed. */
     intersect(this: void, sections: readonly Section[]): Section;
+    /**
+     * Splits a solid into [inside the cutter, outside the cutter].
+     *
+     * The first result is the intersection; the second is the subtraction. The cutter itself
+     * is not returned. Either result may be empty or contain multiple disconnected components.
+     *
+     * @example Keep the plug and the surrounding body
+     * ```ts
+     * const body = box({ size: [30, 20, 8] });
+     * const cutter = cylinder({ height: 10, diameter: 8 });
+     * const [plug, remainder] = split(body, cutter);
+     * // Move the plug beside the body to show both results.
+     * union([translate(plug, [0, -20, 0]), remainder]);
+     * ```
+     */
+    split(this: void, solid: Solid, cutter: Solid): readonly [Solid, Solid];
+    /**
+     * Splits a solid into [positive-normal side, negative side] at a world-space plane.
+     *
+     * The nonzero normal is normalized; offset is the signed distance from the origin in
+     * millimetres, defaulting to zero. Both cut faces are closed. Select either tuple result
+     * to retain one side; either result may be empty.
+     *
+     * @example Separate two halves at X = 0
+     * ```ts
+     * const body = box({ size: [30, 20, 8] });
+     * const [right, left] = splitByPlane(body, { normal: [1, 0, 0] });
+     * // The gap is only for display; the cut itself removes no material.
+     * union([translate(right, [4, 0, 0]), translate(left, [-4, 0, 0])]);
+     * ```
+     *
+     * @example Keep only the positive half
+     * ```ts
+     * const [right] = splitByPlane(box({ size: [30, 20, 8] }), { normal: [1, 0, 0] });
+     * right;
+     * ```
+     */
+    splitByPlane(this: void, solid: Solid, plane: PlaneOptions): readonly [Solid, Solid];
     /** Combines disjoint components without resolving overlap. */
     compose(this: void, solids: readonly Solid[]): Solid;
-    /** Convex hull of points or solids. */
+    /**
+     * Convex hull of points or solids.
+     *
+     * @example Hull
+     * ```ts
+     * const left = translate(sphere({ radius: 5 }), [-10, 0, 0]);
+     * const right = translate(sphere({ radius: 5 }), [10, 0, 0]);
+     * hull({ solids: [left, right] });
+     * ```
+     */
     hull(this: void, options: HullOptions): Solid;
+    /** Convex filled XY hull of finite points or same-build sections. */
+    hull(this: void, options: SectionHullOptions): Section;
     /** Three-dimensional Minkowski sum. */
     minkowskiSum(this: void, a: Solid, b: Solid): Solid;
-    /** Imports a bounded closed indexed mesh. */
+    /**
+     * Imports a bounded closed indexed mesh.
+     *
+     * @example Mesh import
+     * ```ts
+     * import { solidFromMesh } from "@metamesh/modeling";
+     * import { extrudeMesh, rectangleLoop } from "@metamesh/modeling/geometry";
+     *
+     * const mesh = extrudeMesh(rectangleLoop({ size: [20, 12] }), { height: 6 });
+     * solidFromMesh(mesh);
+     * ```
+     */
     solidFromMesh(this: void, mesh: TriangleMesh): Solid;
     /** Copies a handle to manufacturing mesh buffers. */
     toTriangleMesh(this: void, solid: Solid): TriangleMesh;
     /** Translation preserving dimensionality. */
     translate(this: void, section: Section, offset: Vec2): Section;
-    /** Translation preserving dimensionality. */
+    /**
+     * Translation preserving dimensionality.
+     *
+     * @example Translate
+     * ```ts
+     * translate(box({ size: [12, 8, 4] }), [15, 0, 0]);
+     * ```
+     */
     translate(this: void, solid: Solid, offset: Vec3): Solid;
     /** Degree rotation; scalar XY rotation or XYZ solid Euler angles. */
     rotate(this: void, section: Section, degrees: number): Section;
-    /** Degree rotation; scalar XY rotation or XYZ solid Euler angles. */
+    /**
+     * Degree rotation; scalar XY rotation or XYZ solid Euler angles.
+     *
+     * @example Rotate
+     * ```ts
+     * rotate(box({ size: [20, 10, 6] }), [0, 0, 30]);
+     * ```
+     */
     rotate(this: void, solid: Solid, degrees: Vec3): Solid;
-    /** Nonsingular scaling about the origin. */
+    /**
+     * Nonsingular scaling about the origin.
+     */
     scale(this: void, section: Section, factors: number | Vec2): Section;
-    /** Nonsingular scaling about the origin. */
+    /**
+     * Nonsingular scaling about the origin.
+     *
+     * @example Scale
+     * ```ts
+     * scale(sphere({ radius: 8 }), [2, 1, 1]);
+     * ```
+     */
     scale(this: void, solid: Solid, factors: number | Vec3): Solid;
     /** Reflection across an origin line/plane. */
     mirror(this: void, section: Section, normal: Vec2): Section;
-    /** Reflection across an origin line/plane. */
+    /**
+     * Reflection across an origin line/plane.
+     *
+     * @example Mirror
+     * ```ts
+     * const block = translate(box({ size: [12, 8, 4] }), [10, 0, 0]);
+     * mirror(block, [1, 0, 0]);
+     * ```
+     */
     mirror(this: void, solid: Solid, normal: Vec3): Solid;
     /** Row-major affine transform preserving dimensionality. */
     transform(this: void, section: Section, matrix: Transform2): Section;
     /** Row-major affine transform preserving dimensionality. */
     transform(this: void, solid: Solid, matrix: Transform3): Solid;
-    /** Reads a copied, immutable named anchor from this exact active build. */
+    /**
+     * Reads a copied, immutable named anchor from this exact active build.
+     *
+     * @example Read the top datum
+     * ```ts
+     * const plate = box({ size: [30, 20, 6] });
+     * anchor(plate, "top"); // position [0, 0, 3], direction [0, 0, 1]
+     * ```
+     */
     anchor(this: void, shape: Solid | Section, name: string): Anchor3;
-    /** Returns a new same-build handle with copied named anchors; existing names may be replaced. */
+    /**
+     * Returns a new same-build handle with copied named anchors; existing names may be replaced.
+     */
     withAnchors<T extends Solid | Section>(this: void, shape: T, anchors: Readonly<Record<string, Anchor3>>): T;
-    /** Places an explicit or named source anchor against an explicit target anchor. */
+    /**
+     * Places an explicit or named source anchor against an explicit target anchor.
+     *
+     * @example Anchor attachment
+     * ```ts
+     * const plate = box({ size: [30, 20, 6] });
+     * const pin = cylinder({ height: 12, radius: 3 });
+     * attach(pin, "bottom", anchor(plate, "top"), { gap: 1 });
+     * ```
+     */
     attach(this: void, solid: Solid, source: Anchor3 | string, target: Anchor3, options?: AttachOptions): Solid;
-    /** Creates a native filled section without an intermediate Region2 conversion. */
+    /**
+     * Creates a native filled section without an intermediate Region2 conversion.
+     */
     sectionFromContours(this: void, contours: readonly Loop2[], options?: SectionFromContoursOptions): Section;
     /** Imports explicit region topology once. */
     fromRegion(this: void, region: Region2): Section;
     /** Explicit copied topology inspection; not needed for section operations. */
     toRegion(this: void, section: Section): Region2;
-    /** Filled rectangular section with uniform or independently treated corners. */
+    /**
+     * Filled rectangular section with uniform or independently treated corners.
+     *
+     * @example Round the corners
+     * ```ts
+     * rectangle({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
+     * ```
+     */
     rectangle(this: void, options: RectangleOptions): Section;
-    /** Centered circular section. */
+    /**
+     * Centered circular section.
+     *
+     * @example Size to polygon faces
+     * ```ts
+     * circle({ diameter: 12, sizing: "face" });
+     * ```
+     */
     circle(this: void, options: CircleOptions): Section;
-    /** Centered elliptical section. */
+    /**
+     * Centered elliptical section.
+     *
+     * @example Ellipse by full dimensions
+     * ```ts
+     * ellipse({ size: [30, 20] });
+     * ```
+     */
     ellipse(this: void, options: EllipseOptions): Section;
-    /** Regular polygon with a vertex on +X. */
+    /**
+     * Regular polygon with a vertex on +X.
+     *
+     * @example Hexagonal section
+     * ```ts
+     * regularPolygon({ radius: 10, sides: 6, sizing: "face" });
+     * ```
+     */
     regularPolygon(this: void, options: RegularPolygonOptions): Section;
-    /** Alternating outer/inner star vertices. */
+    /**
+     * Alternating outer/inner star vertices.
+     *
+     * @example Five-point section
+     * ```ts
+     * star({ outerRadius: 12, innerRadius: 6, points: 5 });
+     * ```
+     */
     star(this: void, options: StarOptions): Section;
-    /** Native millimetre offset preserving holes. */
+    /**
+     * Native millimetre offset preserving holes.
+     *
+     * @example Add a 2 mm margin
+     * ```ts
+     * const outline = rectangle({ size: [20, 12] });
+     * offset(outline, 2, { join: "round" });
+     * ```
+     */
     offset(this: void, section: Section, distance: number, options?: RegionOffsetOptions): Section;
-    /** Extrudes along +Z with degree twist and top scaling. */
+    /**
+     * Extrudes along +Z with degree twist and top scaling.
+     *
+     * @example Extrude
+     * ```ts
+     * const outline = rectangle({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
+     * extrude(outline, { height: 8 });
+     * ```
+     */
     extrude(this: void, shape: ModelingShape, options: ExtrudeOptions): Solid;
-    /** Revolves a filled radial/Z shape around +Z, with caps for partial sweeps. */
+    /**
+     * Revolves a filled radial/Z shape around +Z, with caps for partial sweeps.
+     *
+     * @example Revolve
+     * ```ts
+     * // Contour coordinates are [radius, Z].
+     * const profile = sectionFromContours([[[8, 0], [12, 0], [12, 16], [8, 16]]]);
+     * revolve(profile, { revolveDegrees: 270 });
+     * ```
+     */
     revolve(this: void, shape: ModelingShape, options?: RevolveOptions): Solid;
     /** Filled XY projection. */
     projectSection(this: void, solid: Solid): Section;
     /** Horizontal filled slice. */
     sliceSection(this: void, solid: Solid, z: number): Section;
-    /** Lofts primitive Sections at z heights or frames; arbitrary Sections and loops require an explicit correspondence method. */
+    /**
+     * Lofts primitive Sections at z heights or frames; arbitrary Sections and loops require an explicit correspondence method.
+     *
+     * @example Loft
+     * ```ts
+     * loft([
+     *   { profile: circle({ diameter: 16 }), z: 0 },
+     *   { profile: rectangle({ size: [30, 20], treatment: { kind: "round", radius: 3 } }), z: 30 },
+     * ]);
+     * ```
+     */
     loft(this: void, stations: readonly LoftStation[], options?: LoftOptions): Solid;
     /** Lofts explicit corresponding contours, including holes and collapsed logical slots. */
     loft(this: void, stations: readonly CorrespondingProfileStation[], options?: LoftOptions): Solid;
     /** Explicit family matching on a shared physical span grid using context resolution. */
     matchProfiles(this: void, profiles: readonly Profile[], options?: MatchProfilesOptions): readonly CorrespondingProfile[];
-    /** Sweeps filled or explicitly corresponding contours using the selected frame policy. */
+    /**
+     * Sweeps filled or explicitly corresponding contours using the selected frame policy.
+     *
+     * @example Sweep
+     * ```ts
+     * const profile = rectangle({ size: [6, 3], treatment: { kind: "round", radius: 1 } });
+     * sweep(profile, [[0, 0, 0], [0, 0, 15], [10, 0, 25]], {
+     *   orientation: { kind: "transport", initialNormal: [0, 1, 0] },
+     * });
+     * ```
+     */
     sweep(this: void, shape: ModelingShape, path: readonly Vec3[], options?: SweepOptions): Solid;
-    /** Copies lightweight section measurements. */
+    /**
+     * Copies lightweight section measurements.
+     *
+     * @example Check filled area
+     * ```ts
+     * const facts = inspectSection(rectangle({ size: [20, 10] }));
+     * facts.area; // 200 mm²
+     * ```
+     */
     inspectSection(this: void, section: Section): SectionInspection;
-    /** Copies solid bounds and volume; temporary components are owned by the build. */
+    /**
+     * Reads immutable native facts once per solid; temporary components are owned by the build.
+     *
+     * @example Check dimensions and volume
+     * ```ts
+     * const facts = inspectSolid(box({ size: [30, 20, 6] }));
+     * facts.volume; // 3600 mm³
+     * ```
+     */
     inspectSolid(this: void, solid: Solid): SolidInspection;
+    /**
+     * Checks whether a same-build solid or filled section contains no geometry.
+     *
+     * Accepts a 3D Solid or 2D Section handle, not a finalized model or raw triangle mesh.
+     * Useful after a Boolean operation whose inputs may not overlap; no mesh is extracted.
+     *
+     * @example Check a missed intersection
+     * ```ts
+     * const body = box({ size: 10 });
+     * const distant = translate(box({ size: 10 }), [30, 0, 0]);
+     * const empty = intersect([body, distant]);
+     * const missed = isEmpty(empty); // true
+     * ```
+     */
+    isEmpty(this: void, shape: Solid | Section): boolean;
+    /**
+     * Measures the minimum separation between two nonempty solids in millimetres.
+     *
+     * Uses actual geometry, not bounding-box separation or distance between object origins.
+     * Contact or overlapping material returns zero, including one solid inside another.
+     * The kernel's search range is managed internally; the result is not capped at a caller limit.
+     * Empty, expired or foreign-build handles reject. Results follow native numeric precision.
+     *
+     * @example Measure the gap between two blocks
+     * ```ts
+     * const left = box({ size: 10 });
+     * const right = translate(box({ size: 10 }), [13, 0, 0]);
+     * const gap = distance(left, right); // 3 mm
+     * ```
+     */
+    distance(this: void, solid: Solid, other: Solid): number;
     /** Copies intersections along the finite directed origin-to-endpoint segment. */
     rayCast(this: void, solid: Solid, origin: Vec3, endpoint: Vec3): readonly SolidRayHit[];
-    /** Returns same-build disconnected solid handles. */
+    /**
+     * Separates a solid's disconnected surface shells into same-build solid handles.
+     *
+     * For solids without enclosed cavities, these shells are the disconnected material islands.
+     * Enclosed cavities produce separate inward shells with negative signed volume; these cannot
+     * be finalized alone as manufacturing parts. This does not cut connected geometry.
+     *
+     * @example Move disconnected pieces independently
+     * ```ts
+     * const islands = union([box({ size: 8 }), translate(box({ size: 8 }), [12, 0, 0])]);
+     * const pieces = components(islands);
+     * // Component order is unspecified; the index only sets a display height here.
+     * union(pieces.map((piece, index) => translate(piece, [0, 0, index * 6])));
+     * ```
+     */
     components(this: void, solid: Solid): readonly Solid[];
-    /** Removes features within the explicit millimetre tolerance. */
+    /** Separates filled 2D islands into sections, retaining each island's holes; empty gives []. */
+    components(this: void, section: Section): readonly Section[];
+    /**
+     * Simplifies a solid using an explicit positive millimetre tolerance.
+     *
+     * Removes redundant vertices while keeping surfaces within the greater of this tolerance
+     * and the solid's existing native tolerance. Choose it from the detail you can afford to lose.
+     */
     simplify(this: void, solid: Solid, tolerance: number): Solid;
+    /**
+     * Simplifies filled 2D contours using an explicit positive millimetre tolerance.
+     *
+     * Useful for dense imported outlines before extrusion. This changes the outline rather
+     * than selecting a lower rendering quality; fine features may be removed.
+     *
+     * @example Clean a dense outline before extrusion
+     * ```ts
+     * const outline = circle({ diameter: 20, segments: 256 });
+     * const cleaned = simplify(outline, 0.05); // 0.05 mm cleanup tolerance
+     * const body = extrude(cleaned, { height: 3 });
+     * ```
+     */
+    simplify(this: void, section: Section, tolerance: number): Section;
     /** Bounded positive-inside implicit field constructor. */
     implicit(this: void, options: ImplicitOptions): Solid;
     /** Replaces native tolerance on an immutable copy; zero selects the kernel minimum. */
     setTolerance(this: void, solid: Solid, tolerance: number): Solid;
-    /** Closed regular-grid top above a flat base; every height is sampled once. */
+    /**
+     * Closed rectilinear top above a flat base, with uniform or explicit XY coordinates.
+     * Samples each grid height once; center-error triangulation also samples each cell centre.
+     *
+     * @example Heightfield
+     * ```ts
+     * heightfield({
+     *   size: [30, 20], segments: [24, 16],
+     *   height: ([x, y]) => 3 + Math.cos(x / 5) * Math.cos(y / 5),
+     * });
+     * ```
+     */
     heightfield(this: void, options: HeightfieldOptions): Solid;
-    /** Repeats one solid along a normalized direction. */
+    /**
+     * Repeats one solid along a normalized direction.
+     *
+     * @example Three copies along X
+     * ```ts
+     * linearPattern(box({ size: 4 }), { count: 3, spacing: 10 });
+     * ```
+     */
     linearPattern(this: void, source: PatternSource, options: LinearPatternOptions): readonly Solid[];
-    /** Repeats one solid about an axis. */
+    /**
+     * Repeats one solid about an axis.
+     *
+     * @example Six copies around Z
+     * ```ts
+     * const pin = translate(cylinder({ height: 6, radius: 2 }), [12, 0, 0]);
+     * radialPattern(pin, { count: 6, axis: [0, 0, 1], angleDegrees: 60 });
+     * ```
+     */
     radialPattern(this: void, source: PatternSource, options: RadialPatternOptions): readonly Solid[];
-    /** XY or XYZ copies, optionally centered or placed in an explicit frame. */
+    /**
+     * XY or XYZ copies, optionally centered or placed in an explicit frame.
+     *
+     * @example Centered XY grid
+     * ```ts
+     * gridPattern(box({ size: 4 }), { count: [3, 2], spacing: [10, 10], center: true });
+     * ```
+     */
     gridPattern(this: void, source: PatternSource, options: GridPatternOptions): readonly Solid[];
-    /** Physical arc-length copies along a sampled path, with optional tangent orientation. */
+    /**
+     * Physical arc-length copies along a sampled path, with optional tangent orientation.
+     *
+     * @example Copies along a bent path
+     * ```ts
+     * pathPattern(box({ size: 4 }), [[0, 0, 0], [20, 0, 0], [20, 20, 0]], { count: 5 });
+     * ```
+     */
     pathPattern(this: void, source: PatternSource, path: readonly Vec3[], options: PathPatternOptions): readonly Solid[];
     /** Helical ridge mesh construction. */
     threadRidge(this: void, options: ThreadRidgeOptions): Solid;
-    /** Compensated external threaded rod. */
+    /**
+     * Compensated external threaded rod.
+     *
+     * @example Threaded rod
+     * ```ts
+     * import { threadedRod } from "@metamesh/modeling";
+     * import { createThreadProfile } from "@metamesh/modeling/geometry";
+     *
+     * const profile = createThreadProfile({ kind: "triangular", pitch: 1.75 });
+     * threadedRod({ nominalMajorDiameter: 12, length: 24, profile, fit: "normal" });
+     * ```
+     */
     threadedRod(this: void, options: ThreadedRodOptions): Solid;
-    /** Compensated internal threaded cutter. */
+    /**
+     * Compensated internal threaded cutter.
+     *
+     * @example Internal thread
+     * ```ts
+     * import { cylinder, internalThreadCutter, subtract } from "@metamesh/modeling";
+     * import { createThreadProfile } from "@metamesh/modeling/geometry";
+     *
+     * const profile = createThreadProfile({ kind: "triangular", pitch: 1.75 });
+     * const body = cylinder({ diameter: 20, height: 12, center: false });
+     * const cutter = internalThreadCutter({ nominalMajorDiameter: 12, length: 12, profile });
+     * subtract(body, [cutter]);
+     * ```
+     */
     internalThreadCutter(this: void, options: InternalThreadCutterOptions): Solid;
-    /** Compensated threaded nut. */
+    /**
+     * Compensated threaded nut.
+     *
+     * @example Threaded nut
+     * ```ts
+     * import { threadedNut } from "@metamesh/modeling";
+     * import { createThreadProfile } from "@metamesh/modeling/geometry";
+     *
+     * const profile = createThreadProfile({ kind: "triangular", pitch: 1.75 });
+     * threadedNut({ nominalMajorDiameter: 12, thickness: 8, width: 20, shape: "hex", profile, fit: "normal" });
+     * ```
+     */
     threadedNut(this: void, options: ThreadedNutOptions): Solid;
     /** Allocation-free external-thread facts. */
     preflightThreadedRod(this: void, options: ThreadedRodOptions): HelicalThreadSolidMeshPreflight;
@@ -737,15 +1231,44 @@ export declare interface ModelingContext {
     preflightInternalThreadCutter(this: void, options: InternalThreadCutterOptions): HelicalThreadSolidMeshPreflight;
     /** Allocation-free nut/cutter facts. */
     preflightThreadedNut(this: void, options: ThreadedNutOptions): ThreadedNutPreflight;
-    /** Consumes a previously prepared layout; never shapes or fetches a font. */
+    /**
+     * Consumes a previously prepared layout; never shapes or fetches a font.
+     *
+     * @example Use a prepared text layout
+     * ```ts
+     * // Prepare the exact font and layout before entering build.
+     * function labelSection(layout: VectorTextLayout) {
+     *   return textSection(layout);
+     * }
+     * ```
+     */
     textSection(this: void, layout: VectorTextLayout, options?: TextSectionOptions): Section;
-    /** Imports bounded painted SVG document geometry. */
+    /**
+     * Imports bounded painted SVG document geometry.
+     *
+     * @example Import a physical SVG rectangle
+     * ```ts
+     * svgSection(
+     *   '<svg xmlns="http://www.w3.org/2000/svg" width="30mm" height="20mm" viewBox="0 0 30 20"><rect width="30" height="20"/></svg>',
+     *   { origin: "center" },
+     * );
+     * ```
+     */
     svgSection(this: void, svg: string, options?: SvgSectionOptions): Section;
-    /** Imports bounded filled SVG path data. */
+    /**
+     * Imports bounded filled SVG path data.
+     *
+     * @example Fill an SVG path in millimetres
+     * ```ts
+     * svgPathSection("M0 0H20V12H0Z", { origin: "center", scale: 1 });
+     * ```
+     */
     svgPathSection(this: void, path: string, options?: SvgPathSectionOptions): Section;
 }
 
-/** Returns bound local operations, optionally with derived resolution, without changing imported operations. */
+/**
+ * Returns bound local operations, optionally with derived resolution, without changing imported operations.
+ */
 export declare function modelingFunctions(resolution?: GeometryResolution): ModelingContext;
 
 /** Aggregate manufacturing output ceilings selected by a trusted host. */
@@ -791,9 +1314,19 @@ export declare interface PathPatternOptions {
     readonly orientation?: "fixed" | "tangent";
 }
 
-/** One same-build shape, or a synchronous factory called once per copy in index order. */
+/**
+ * One same-build shape, or a synchronous factory called once per copy in index order.
+ */
 export declare type PatternSource = Solid | ((index: number) => Solid);
 
+/** A world-space cutting plane, retaining the half-space in the normal's direction. */
+export declare interface PlaneOptions {
+    /** Finite nonzero plane normal; magnitude does not affect the plane. */
+    readonly normal: Vec3;
+    /** Signed millimetre distance from the origin along the unit normal. Defaults to zero. */
+    readonly offset?: number;
+}
+
 /**
  * One bounded two-dimensional polygon.
  *
@@ -839,7 +1372,9 @@ export declare interface PrimitivePlacementOptions {
     readonly tolerance?: GeometryToleranceOptions;
 }
 
-/** Named baseline fit policies for calibrated FDM-style printed threads. */
+/**
+ * Named baseline fit policies for calibrated FDM-style printed threads.
+ */
 export declare type PrintableThreadFit = "tight" | "normal" | "loose";
 
 /**
@@ -939,7 +1474,9 @@ export declare const projectSection: ModelingContext["projectSection"];
 /** Host-bound radialPattern operation. Valid only during a synchronous build. */
 export declare const radialPattern: ModelingContext["radialPattern"];
 
-/** Options for repeating one solid around an axis through a center point. */
+/**
+ * Options for repeating one solid around an axis through a center point.
+ */
 export declare interface RadialPatternOptions {
     /** Number of solids to return, including the original. */
     readonly count: number;
@@ -951,10 +1488,14 @@ export declare interface RadialPatternOptions {
     readonly center?: Vec3;
 }
 
-/** Radial dimensions refer to polygon vertices or compensate faceting to meet polygon faces. */
+/**
+ * Radial dimensions refer to polygon vertices or compensate faceting to meet polygon faces.
+ */
 export declare type RadialSizing = "vertex" | "face";
 
-/** Nominal radial sizing shared by circular and regular polygon construction. */
+/**
+ * Nominal radial sizing shared by circular and regular polygon construction.
+ */
 export declare interface RadialSizingOptions {
     /** Explicit sampling ceilings; bound modeling operations may only lower the host policy. */
     readonly limits?: Partial<GeometrySamplingLimits>;
@@ -982,7 +1523,9 @@ bottomLeft: RectangleCornerTreatment,
 bottomRight: RectangleCornerTreatment
 ];
 
-/** Shared rectangle dimensions, origin and uniform or per-corner treatment. */
+/**
+ * Shared rectangle dimensions, origin and uniform or per-corner treatment.
+ */
 export declare interface RectangleLoopOptions {
     /** Positive uniform size or explicit XY extents in millimetres. */
     readonly size: number | Vec2;
@@ -994,7 +1537,9 @@ export declare interface RectangleLoopOptions {
     readonly limits?: Partial<GeometrySamplingLimits>;
 }
 
-/** Rectangle dimensions, placement and uniform or per-corner treatment. */
+/**
+ * Rectangle dimensions, placement and uniform or per-corner treatment.
+ */
 export declare interface RectangleOptions extends RectangleLoopOptions, PrimitivePlacement {
 }
 
@@ -1019,7 +1564,9 @@ export declare interface RegionOffsetOptions {
 /** Host-bound regularPolygon operation. Valid only during a synchronous build. */
 export declare const regularPolygon: ModelingContext["regularPolygon"];
 
-/** Regular polygon dimensions, radial convention and degree rotation. */
+/**
+ * Regular polygon dimensions, radial convention and degree rotation.
+ */
 export declare type RegularPolygonOptions = RadialSizingOptions & PrimitivePlacement & {
     /** Positive nominal radius in millimetres, interpreted according to sizing. */
     readonly radius: number;
@@ -1032,7 +1579,9 @@ export declare type RegularPolygonOptions = RadialSizingOptions & PrimitivePlace
 /** Host-bound revolve operation. Valid only during a synchronous build. */
 export declare const revolve: ModelingContext["revolve"];
 
-/** Circumferential sampling and degree sweep shared by pure and filled revolution. */
+/**
+ * Circumferential sampling and degree sweep shared by pure and filled revolution.
+ */
 export declare interface RevolveOptions extends CircularPrimitiveOptions {
     /**
      * Positive angular sweep no greater than 360 degrees; partial revolutions have end caps.
@@ -1048,7 +1597,9 @@ export declare interface RevolveOptions extends CircularPrimitiveOptions {
 /** Host-bound rotate operation. Valid only during a synchronous build. */
 export declare const rotate: ModelingContext["rotate"];
 
-/** A circular edge or corner roundover with explicit physical sampling. */
+/**
+ * A circular edge or corner roundover with explicit physical sampling.
+ */
 export declare interface RoundedEdgeTreatment extends CircularPrimitiveOptions {
     /** Selects circular corners or spherical all-edge roundovers. */
     readonly kind: "round";
@@ -1070,14 +1621,34 @@ declare const sectionBrand: unique symbol;
 /** Host-bound sectionFromContours operation. Valid only during a synchronous build. */
 export declare const sectionFromContours: ModelingContext["sectionFromContours"];
 
-/** Filled-contour resolution. Closing vertices are implicit. */
+/**
+ * Filled-contour resolution. Closing vertices are implicit.
+ */
 export declare interface SectionFromContoursOptions {
     /** Nonzero or even-odd filled-contour rule; defaults to nonzero. */
     readonly fillRule?: "nonzero" | "evenodd";
 }
 
-/** Copied native filled section facts in millimetres and square millimetres. */
+/** Planar convex hull inputs are finite XY points or same-build filled sections. */
+export declare type SectionHullOptions = {
+    /** At least three finite millimetre XY points spanning positive area. */
+    readonly points: readonly Vec2[];
+    /** Point input excludes section input. */
+    readonly sections?: never;
+} | {
+    /** One through 1000 same-build sections to include in the convex hull. */
+    readonly sections: readonly Section[];
+    /** Section input excludes point input. */
+    readonly points?: never;
+};
+
+/**
+ * Immutable native filled section facts in millimetres and square millimetres.
+ * Repeated inspections of the same native shape share these facts within one build.
+ */
 export declare interface SectionInspection {
+    /** Whether this filled section has no area or boundary. */
+    readonly isEmpty: boolean;
     /** Filled section area in square millimetres. */
     readonly area: number;
     /** Number of extracted outer and hole contours. */
@@ -1126,16 +1697,25 @@ declare const solidBrand: unique symbol;
 /** Host-bound solidFromMesh operation. Valid only during a synchronous build. */
 export declare const solidFromMesh: ModelingContext["solidFromMesh"];
 
-/** Copied solid bounds, connected component count, and cubic millimetre volume. */
+/**
+ * Immutable solid bounds, emptiness, component count, volume, surface area and native tolerance.
+ * Repeated inspections of the same native shape share these facts within one build.
+ */
 export declare interface SolidInspection {
+    /** Whether this native solid contains no material. */
+    readonly isEmpty: boolean;
     /** Inclusive maximum coordinates in millimetres. */
     readonly max: Vec3;
     /** Inclusive minimum coordinates in millimetres. */
     readonly min: Vec3;
-    /** Number of connected native solid components. */
+    /** Number of connected surface shells; inward cavity shells count separately. */
     readonly parts: number;
     /** Enclosed native solid volume in cubic millimetres. */
     readonly volume: number;
+    /** Total native surface area in square millimetres. */
+    readonly surfaceArea: number;
+    /** Effective native geometric tolerance in millimetres. */
+    readonly tolerance: number;
 }
 
 /** Named same-build solid manufacturing part. */
@@ -1165,7 +1745,9 @@ export declare interface SolidRayHit {
 /** Host-bound sphere operation. Valid only during a synchronous build. */
 export declare const sphere: ModelingContext["sphere"];
 
-/** Exactly one radius or diameter, placement, and tessellation for an origin-centered sphere. */
+/**
+ * Exactly one radius or diameter, placement, and tessellation for an origin-centered sphere.
+ */
 export declare type SphereOptions = CircularPrimitiveOptions & PrimitivePlacement & ({
     /** Positive radius in millimetres; mutually exclusive with diameter. */
     readonly radius: number;
@@ -1178,6 +1760,12 @@ export declare type SphereOptions = CircularPrimitiveOptions & PrimitivePlacemen
     readonly radius?: never;
 });
 
+/** Returns intersection and difference with a same-build cutter, including empty results. */
+export declare const split: ModelingContext["split"];
+
+/** Splits a solid into the normal-side and opposite-side halves of a world-space plane. */
+export declare const splitByPlane: ModelingContext["splitByPlane"];
+
 /** Square profile with equal crest and root widths. */
 declare interface SquareThreadProfileSpec extends ThreadProfileBaseSpec {
     /** Selects the square profile family. */
@@ -1192,7 +1780,9 @@ declare interface SquareThreadProfileSpec extends ThreadProfileBaseSpec {
 /** Host-bound star operation. Valid only during a synchronous build. */
 export declare const star: ModelingContext["star"];
 
-/** Alternating outer and inner vertices, centered on the XY origin. */
+/**
+ * Alternating outer and inner vertices, centered on the XY origin.
+ */
 export declare interface StarOptions extends PrimitivePlacement {
     /** Explicit sampling ceilings, bounded by the host policy. */
     readonly limits?: Partial<GeometrySamplingLimits>;
@@ -1232,7 +1822,9 @@ export declare interface SvgPathSectionOptions {
 /** Host-bound svgSection operation. Valid only during a synchronous build. */
 export declare const svgSection: ModelingContext["svgSection"];
 
-/** Bounded SVG document sampling. Center origin uses the final painted bounds. */
+/**
+ * Bounded SVG document sampling. Center origin uses the final painted bounds.
+ */
 export declare interface SvgSectionOptions {
     /** Local allocation ceilings may only lower the configured engine policy. */
     readonly limits?: Partial<GeometrySamplingLimits>;
@@ -1247,7 +1839,9 @@ export declare interface SvgSectionOptions {
 /** Host-bound sweep operation. Valid only during a synchronous build. */
 export declare const sweep: ModelingContext["sweep"];
 
-/** Controls shared by pure mesh construction and filled modeling sweeps. */
+/**
+ * Controls shared by pure mesh construction and filled modeling sweeps.
+ */
 export declare interface SweepOptions {
     /** Join the path's last station to its first. Open paths retain watertight end caps. */
     readonly closed?: boolean;
@@ -1267,7 +1861,9 @@ export declare interface SweepOptions {
     readonly seamProfileOffset?: number;
 }
 
-/** Explicit profile-X frame policy; all normals are directed, and selected singular policies reject. */
+/**
+ * Explicit profile-X frame policy; all normals are directed, and selected singular policies reject.
+ */
 export declare type SweepOrientation = {
     /** Minimizes frame rotation by parallel transport. */
     readonly kind: "transport";
@@ -1291,7 +1887,9 @@ export declare type SweepOrientation = {
 /** Host-bound textSection operation. Valid only during a synchronous build. */
 export declare const textSection: ModelingContext["textSection"];
 
-/** Physical curve sampling applied to already prepared vector text. */
+/**
+ * Physical curve sampling applied to already prepared vector text.
+ */
 export declare interface TextSectionOptions {
     /** Local allocation ceilings may only lower the configured engine policy. */
     readonly limits?: Partial<GeometrySamplingLimits>;
@@ -1318,7 +1916,9 @@ export declare const threadedNut: ModelingContext["threadedNut"];
 /** Nut-edge bevel selection. */
 export declare type ThreadedNutBevel = "automatic" | "both" | "inside" | "none" | "outside";
 
-/** Options for a compensated nut with an internal thread. */
+/**
+ * Options for a compensated nut with an internal thread.
+ */
 export declare interface ThreadedNutOptions extends Omit<InternalThreadCutterOptions, "bevelBottom" | "bevelSize" | "bevelTop" | "length"> {
     /** Nut body bevel selection. Default: `automatic`. */
     readonly bevel?: ThreadedNutBevel;
@@ -1354,13 +1954,17 @@ export declare interface ThreadedNutPreflight {
     readonly threadCircularSegments: number;
 }
 
-/** Supported printable nut body shapes. */
+/**
+ * Supported printable nut body shapes.
+ */
 export declare type ThreadedNutShape = "hex" | "round" | "square";
 
 /** Host-bound threadedRod operation. Valid only during a synchronous build. */
 export declare const threadedRod: ModelingContext["threadedRod"];
 
-/** Options for a compensated external threaded rod along +Z. */
+/**
+ * Options for a compensated external threaded rod along +Z.
+ */
 export declare interface ThreadedRodOptions extends Omit<HelicalThreadRidgeMeshOptions, "majorDiameter">, ThreadBevelOptions {
     /** Printable fit or caller-calibrated allowances. Default: `normal`. */
     readonly fit?: PrintableThreadFit | PrintableThreadFitPolicy;
@@ -1408,7 +2012,9 @@ export declare interface ThreadEndTreatmentOptions {
     readonly top?: ThreadEndStyle;
 }
 
-/** Direction in which a conventional helical thread advances around +Z. */
+/**
+ * Direction in which a conventional helical thread advances around +Z.
+ */
 export declare type ThreadHandedness = "left" | "right";
 
 /** Radial envelope toward which a blunt lead-in collapses. */
@@ -1417,7 +2023,9 @@ export declare type ThreadLeadInEnvelope = "major" | "minor";
 /** BOSL2-compatible cross-section scaling curve for a blunt thread lead-in. */
 export declare type ThreadLeadInShape = "cut" | "linear" | "smooth" | "sqrt";
 
-/** A validated immutable periodic thread profile in `[axial, radial]` millimetres. */
+/**
+ * A validated immutable periodic thread profile in `[axial, radial]` millimetres.
+ */
 export declare interface ThreadProfile {
     /** Axial width of the flat at the major envelope. */
     readonly crestFlatWidth: number;
@@ -1441,7 +2049,9 @@ declare interface ThreadProfileBaseSpec {
     readonly tolerance?: GeometryToleranceOptions;
 }
 
-/** Supported built-in and caller-defined thread profiles. */
+/**
+ * Supported built-in and caller-defined thread profiles.
+ */
 declare type ThreadProfileSpec = AcmeThreadProfileSpec | ButtressThreadProfileSpec | CustomThreadProfileSpec | SquareThreadProfileSpec | TrapezoidalThreadProfileSpec | TriangularThreadProfileSpec;
 
 /** Host-bound threadRidge operation. Valid only during a synchronous build. */
@@ -1456,7 +2066,9 @@ export declare const toRegion: ModelingContext["toRegion"];
 /** Host-bound torus operation. Valid only during a synchronous build. */
 export declare const torus: ModelingContext["torus"];
 
-/** Dimensions and independent ring/profile tessellation for a torus around the Z axis. */
+/**
+ * Dimensions and independent ring/profile tessellation for a torus around the Z axis.
+ */
 export declare interface TorusOptions extends PrimitivePlacement {
     /** Explicit sampling ceilings, bounded by the host policy. */
     readonly limits?: Partial<GeometrySamplingLimits>;
@@ -1535,7 +2147,9 @@ declare interface TrapezoidalThreadProfileSpec extends ThreadProfileBaseSpec {
     readonly threadAngle?: number;
 }
 
-/** A topology-preserving indexed triangle mesh with XYZ vertex positions. */
+/**
+ * A topology-preserving indexed triangle mesh with XYZ vertex positions.
+ */
 export declare interface TriangleMesh {
     /** Three unsigned vertex indices per triangle. */
     readonly indices: Uint32Array;
@@ -1543,7 +2157,9 @@ export declare interface TriangleMesh {
     readonly positions: Float32Array;
 }
 
-/** Measurements and optional edge-connected topology from one validated mesh traversal. */
+/**
+ * Measurements and optional edge-connected topology from one validated mesh traversal.
+ */
 export declare interface TriangleMeshAnalysis extends TriangleMeshMeasurements {
     /** Number of referenced edge-connected components when `includeTopology` is requested. */
     readonly connectedComponentCount?: number;
@@ -1551,7 +2167,9 @@ export declare interface TriangleMeshAnalysis extends TriangleMeshMeasurements {
     readonly edgeCount?: number;
 }
 
-/** Geometric measurements derived from a validated, non-empty triangle mesh. */
+/**
+ * Geometric measurements derived from a validated, non-empty triangle mesh.
+ */
 export declare interface TriangleMeshMeasurements {
     /** Axis-aligned bounds. */
     readonly bounds: MeshBounds;
@@ -1565,7 +2183,9 @@ export declare interface TriangleMeshMeasurements {
     readonly vertexCount: number;
 }
 
-/** ISO/UTS-like 60-degree truncated triangular profile. */
+/**
+ * ISO/UTS-like 60-degree truncated triangular profile.
+ */
 declare interface TriangularThreadProfileSpec extends ThreadProfileBaseSpec {
     /** Selects the 60-degree triangular profile family. */
     readonly kind: "triangular";
@@ -1584,7 +2204,9 @@ declare interface TriangularThreadProfileSpec extends ThreadProfileBaseSpec {
 /** Host-bound tube operation. Valid only during a synchronous build. */
 export declare const tube: ModelingContext["tube"];
 
-/** Dimensions, placement, and tessellation for a hollow Z-axis tube. */
+/**
+ * Dimensions, placement, and tessellation for a hollow Z-axis tube.
+ */
 export declare interface TubeOptions extends CircularPrimitiveOptions, PrimitivePlacement {
     /**
      * Centers the tube on the Z origin when `true`; otherwise its bottom is at `Z = 0`.
@@ -1616,7 +2238,9 @@ export declare interface VectorTextBounds {
     readonly max: readonly [number, number];
 }
 
-/** Immutable vector layout with no browser, font parser, or kernel ownership. */
+/**
+ * Immutable vector layout with no browser, font parser, or kernel ownership.
+ */
 export declare interface VectorTextLayout {
     /** Nonzero-filled path data in millimetres, positive Y upward; empty for text with no ink. */
     readonly paths: readonly string[];
@@ -1628,9 +2252,9 @@ export declare interface VectorTextLayout {
 export declare interface VectorTextMetrics {
     /** Visible curve bounds after alignment, or null when the text has no ink. */
     readonly bounds: VectorTextBounds | null;
-    /** Unaligned pen displacement: final line advance and negative baseline displacement, in mm. */
+    /** Unaligned logical advance and negative baseline displacement in mm; arcs retain [arc length, 0]. */
     readonly advance: readonly [number, number];
-    /** Maximum line advance in millimetres, including spaces; distinct from visible ink width. */
+    /** Maximum logical line advance in millimetres, including spaces; arc length on circular baselines. */
     readonly logicalWidth: number;
     /** Selected font's ascender distance above a baseline in millimetres, independent of the text. */
     readonly ascent: number;