@metamesh/modeling 0.6.0 → 0.8.0

package/dist/api/geometry.d.ts

@@ -11,7 +11,13 @@ export declare interface AcmeThreadProfileSpec extends ThreadProfileBaseSpec {
     readonly depth?: number;
 }
 
-/** Adds two finite XYZ vectors component-wise. @example `add3([1, 2, 3], [4, 5, 6])` */
+/**
+ * Adds two finite XYZ vectors component-wise.
+ * @example
+ * ```ts
+ * add3([1, 2, 3], [4, 5, 6]); // [5, 7, 9]
+ * ```
+ */
 export declare const add3: (a: Vec3, b: Vec3) => Vec3;
 
 /** Controls full-circle sampling that must satisfy one or more topology alignments. */
@@ -168,7 +174,9 @@ export declare interface ArcCurve3 {
      readonly tolerance?: GeometryToleranceOptions;
  }
 
- /** One explicitly unit-labelled right-handed axis-angle rotation. */
+ /**
+  * One explicitly unit-labelled right-handed axis-angle rotation.
+  */
  export declare type AxisAngleRotation3 = {
      /** Finite right-handed angle in degrees. */
      readonly degrees: number;
@@ -227,7 +235,9 @@ export declare interface ArcCurve3 {
  /** 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>;
@@ -280,7 +290,9 @@ export declare interface ArcCurve3 {
      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";
@@ -288,10 +300,19 @@ export declare interface ArcCurve3 {
      readonly distance: number | readonly [first: number, second: number];
  }
 
- /** Creates an immutable centered CCW circle with +X seam and vertex or face radial sizing. */
+ /**
+  * Creates an immutable centered CCW circle with +X seam and vertex or face radial sizing.
+  *
+  * @example Explicit circular point data
+  * ```ts
+  * circleLoop({ diameter: 20, segments: 32 });
+  * ```
+  */
  export declare const circleLoop: (options: CircleLoopOptions) => Loop2;
 
- /** 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;
@@ -304,7 +325,9 @@ export declare interface ArcCurve3 {
      readonly radius?: never;
  });
 
- /** 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>;
@@ -402,6 +425,17 @@ export declare interface ArcCurve3 {
   */
  export declare const computeParallelTransportFrames: (path: readonly Vec3[], initialNormal?: Vec3, normalGuide?: PathNormalGuide, limits?: Partial<GeometrySamplingLimits>) => readonly PathFrame[];
 
+ /**
+  * Computes the uniform-density volume centroid of an oriented closed solid, including cavity shells.
+  * Coordinates are millimetres. Indexed closure and positive aggregate volume are required; callers
+  * may use validateSolidMesh first when geometric intersections and shell orientation are untrusted.
+  * Fresh mutable input is inspected on every call, and buffers are never changed.
+  *
+  * @param mesh - Consistently oriented closed mesh with positive enclosed volume.
+  * @returns A fresh immutable XYZ volume centroid.
+  */
+ export declare function computeTriangleMeshCentroid(mesh: TriangleMesh): Vec3;
+
  /** One sampled component retaining contour identities and logical point correspondence. */
  export declare interface CorrespondingComponent {
      /** Stable canonical lowercase identity; unique within the containing topology or output. */
@@ -455,6 +489,11 @@ export declare interface ArcCurve3 {
    * The open path spans one pitch. Radial zero is the major envelope; negative
    * values point toward the shaft. Custom paths must be finite, axially
    * non-decreasing, periodic at their endpoints, and reach radial zero.
+   *
+   * @example Printable triangular thread profile
+   * ```ts
+   * createThreadProfile({ kind: "triangular", pitch: 1.75 });
+   * ```
    */
   export declare function createThreadProfile(spec: ThreadProfileSpec): ThreadProfile;
 
@@ -472,7 +511,13 @@ export declare interface ArcCurve3 {
        */
    export declare function createTriangleMeshSignature(mesh: TriangleMesh, options?: TriangleMeshSignatureOptions): TriangleMeshSignature;
 
-   /** Returns the right-handed cross product. @example `cross3([1, 0, 0], [0, 1, 0])` */
+   /**
+    * Returns the right-handed cross product.
+    * @example
+    * ```ts
+    * cross3([1, 0, 0], [0, 1, 0]); // [0, 0, 1]
+    * ```
+    */
    export declare const cross3: (a: Vec3, b: Vec3) => Vec3;
 
    /** Planar cubic Bézier with explicit endpoint and control coordinates. */
@@ -489,7 +534,9 @@ export declare interface ArcCurve3 {
        readonly end: Vec2;
    }
 
-   /** Spatial cubic Bézier with explicit endpoint and control coordinates. */
+   /**
+    * Spatial cubic Bézier with explicit endpoint and control coordinates.
+    */
    export declare interface CubicBezierCurve3 {
        /** Selects a cubic Bézier through two endpoints and two controls. */
        readonly kind: "cubic";
@@ -509,10 +556,14 @@ export declare interface ArcCurve3 {
    /** Reusable planar curve definition. */
    export declare type Curve2 = LineCurve2 | ArcCurve2 | CubicBezierCurve2;
 
-   /** Reusable spatial curve definition. */
+   /**
+    * Reusable spatial curve definition.
+    */
    export declare type Curve3 = LineCurve3 | ArcCurve3 | CubicBezierCurve3;
 
-   /** Explicit physical sampling and allocation policy for reusable curves. */
+   /**
+    * Explicit physical sampling and allocation policy for reusable curves.
+    */
    export declare interface CurveSamplingOptions {
        /** Exact segment count overrides physical criteria; curve parameters are spaced uniformly. */
        readonly segments?: number;
@@ -560,7 +611,9 @@ export declare interface ArcCurve3 {
        readonly origin?: Vec3;
    }
 
-   /** 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`.
@@ -583,7 +636,9 @@ export declare interface ArcCurve3 {
        readonly radius?: never;
    });
 
-   /** Resolved transverse pitch-plane dimensions for one cylindrical gear. */
+   /**
+    * Resolved transverse pitch-plane dimensions for one cylindrical gear.
+    */
    export declare interface CylindricalGearDimensions {
        /** Addendum above the pitch circle, in millimetres. */
        readonly addendum: number;
@@ -621,7 +676,9 @@ export declare interface ArcCurve3 {
        readonly virtualToothCount: number;
    }
 
-   /** Whether two cylindrical gears mesh on their outside teeth or as a pinion inside a ring. */
+   /**
+    * Whether two cylindrical gears mesh on their outside teeth or as a pinion inside a ring.
+    */
    export declare type CylindricalGearMeshKind = "external" | "internal";
 
    /** Sampling controls for a complete non-duplicated gear outline. */
@@ -638,7 +695,9 @@ export declare interface ArcCurve3 {
        readonly tipArcSamples?: number;
    }
 
-   /** Pitch solution for a coordinated cylindrical gear pair. */
+   /**
+    * Pitch solution for a coordinated cylindrical gear pair.
+    */
    export declare interface CylindricalGearPairDimensions {
        /** Nominal distance between the two +Z gear axes, in millimetres. */
        readonly centerDistance: number;
@@ -672,7 +731,9 @@ export declare interface ArcCurve3 {
        readonly samples: number;
    }
 
-   /** Inputs for resolving a coordinated cylindrical gear pair. */
+   /**
+    * Inputs for resolving a coordinated cylindrical gear pair.
+    */
    export declare interface CylindricalGearPairSpec {
        /** Driving gear or pinion. */
        readonly driver: CylindricalGearSpec;
@@ -728,16 +789,33 @@ export declare interface ArcCurve3 {
     */
    export declare const distributeAlongPath: (path: readonly Vec3[], count: number, closed: boolean, limits?: Partial<GeometrySamplingLimits>) => readonly PathPlacement[];
 
-   /** Returns the scalar dot product. @example `dot3([1, 0, 0], [0, 1, 0])` */
+   /**
+    * Returns the scalar dot product.
+    * @example
+    * ```ts
+    * dot3([1, 0, 0], [0, 1, 0]); // 0
+    * ```
+    */
    export declare const dot3: (a: Vec3, b: Vec3) => number;
 
-   /** Uniform finishing vocabulary shared by applicable solid edges and profile corners. */
+   /**
+    * Uniform finishing vocabulary shared by applicable solid edges and profile corners.
+    */
    export declare type EdgeTreatment = ChamferedEdgeTreatment | RoundedEdgeTreatment | SmoothEdgeTreatment | ProfiledEdgeTreatment;
 
-   /** Creates an immutable centered CCW ellipse with +X seam within the selected sampling ceiling. */
+   /**
+    * Creates an immutable centered CCW ellipse with +X seam within the selected sampling ceiling.
+    *
+    * @example Ellipse by full dimensions
+    * ```ts
+    * ellipseLoop({ size: [30, 20] });
+    * ```
+    */
    export declare function ellipseLoop(options: EllipseLoopOptions): Loop2;
 
-   /** 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;
@@ -750,7 +828,9 @@ export declare interface ArcCurve3 {
        readonly radius?: never;
    });
 
-   /** 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;
@@ -770,10 +850,20 @@ export declare interface ArcCurve3 {
         */
     export declare function eulerTransform3(rotationDegrees: Vec3): Transform3;
 
-    /** Linearly extrudes one simple profile along +Z with robust ear-clipped caps. */
+    /**
+     * Linearly extrudes one simple profile along +Z with robust ear-clipped caps.
+     *
+     * @example Extrude point data without an engine
+     * ```ts
+     * const outline = rectangleLoop({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
+     * extrudeMesh(outline, { height: 8 });
+     * ```
+     */
     export declare function extrudeMesh(profile: Loop2, options: ExtrudeOptions): TriangleMesh;
 
-    /** 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;
@@ -859,7 +949,9 @@ export declare interface ArcCurve3 {
          readonly operation: string;
      }
 
-     /** 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;
@@ -902,32 +994,76 @@ export declare interface ArcCurve3 {
      export declare function getMetricFastenerStandard(size: MetricFastenerSize): MetricFastenerStandard;
 
      /**
-      * Builds a closed indexed solid from a regularly sampled top, matched boundary walls, and flat base.
-      * Heights are evaluated once per grid point after allocation preflight. Physical XY sizes and all
-      * output coordinates must fit Float32 storage. Shared wall vertices prevent cracks at the base.
+      * Builds a closed indexed mesh from a rectilinear top, matched boundary walls, and flat base.
+      * Heights run once per grid point after preflight; center-error adds one evaluation per cell.
+      * Top winding is +Z, the base is -Z, and sides face outward. Coordinates and heights must fit
+      * Float32 storage. Explicit axes are captured before sampling; shared wall vertices prevent cracks.
+      *
+      * @example Sample a closed wavy mesh
+      * ```ts
+      * heightfieldMesh({
+      *   size: [30, 20], segments: [24, 16],
+      *   height: ([x, y]) => 3 + Math.cos(x / 5) * Math.cos(y / 5),
+      * });
+      * ```
       */
      export declare function heightfieldMesh(options: HeightfieldOptions, limits?: HeightfieldMeshLimits): TriangleMesh;
 
      /** Trusted output ceilings for pure construction; omitted fields use engine defaults. */
      export declare type HeightfieldMeshLimits = Partial<Pick<ModelingLimits, "maxVertices" | "maxTriangles" | "maxBytes">>;
 
-     /** 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;
-     }
-
-     /** Predictable regular-grid allocation facts; this does not evaluate the height callback. */
+         /** 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;
+     });
+
+     /** Predictable rectilinear-grid allocation facts; this does not evaluate the height callback. */
      export declare interface HeightfieldPreflight {
-         /** Number of grid points and height callback evaluations. */
+         /** Number of top grid points; center-error also evaluates one height per cell. */
          readonly sampleCount: number;
          /** Number of allocated XYZ vertices. */
          readonly vertexCount: number;
@@ -1068,6 +1204,13 @@ export declare interface ArcCurve3 {
        * Both ends use ear-clipped caps, supporting concave profiles without center fans.
        * Intermediate slices interpolate placed world vertices, never frame axes.
        * Transformed coordinates must fit finite Float32 mesh storage.
+       *
+       * @example Loft with explicit point correspondence
+       * ```ts
+       * const bottom = rectangleLoop({ size: [20, 12] });
+       * const top = rectangleLoop({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
+       * loftMesh([{ profile: bottom, z: 0 }, { profile: top, z: 30 }], { correspondence: "reindex" });
+       * ```
        */
       export declare function loftMesh(stations: readonly LoftMeshStation[], options: LoftOptions): TriangleMesh;
 
@@ -1077,7 +1220,9 @@ export declare interface ArcCurve3 {
           readonly profile: Loop2;
       };
 
-      /** 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[];
@@ -1093,7 +1238,9 @@ export declare interface ArcCurve3 {
           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;
@@ -1123,6 +1270,14 @@ export declare interface ArcCurve3 {
        * Cubics share a checked uniform parameter grid, including grids selected by exact paired requests.
        * Input order and winding are preserved. Collapsed spans retain repeated logical slots, which
        * the engine maps to shared physical vertices while omitting degenerate faces.
+       *
+       * @example Match named rectangle landmarks
+       * ```ts
+       * matchProfiles([
+       *   rectangleProfile({ size: [20, 12] }),
+       *   rectangleProfile({ size: [30, 20], treatment: { kind: "round", radius: 3 } }),
+       * ]);
+       * ```
        */
       export declare function matchProfiles(profiles: readonly Profile[], options?: MatchProfilesOptions): readonly CorrespondingProfile[];
 
@@ -1156,7 +1311,9 @@ export declare interface ArcCurve3 {
        */
       export declare function measureTriangleMesh(mesh: TriangleMesh, options?: TriangleMeshValidationOptions): TriangleMeshMeasurements;
 
-      /** 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;
@@ -1336,7 +1493,9 @@ export declare interface ArcCurve3 {
       /** An ordered, open sequence of two-dimensional points. */
       export declare type Path2 = readonly Vec2[];
 
-      /** An ordered, open sequence of three-dimensional points. */
+      /**
+       * An ordered, open sequence of three-dimensional points.
+       */
       export declare type Path3 = readonly Vec3[];
 
       /** Orthonormal right-handed frame sampled along a path. */
@@ -1349,7 +1508,9 @@ export declare interface ArcCurve3 {
           readonly binormal: Vec3;
       }
 
-      /** Returns total sampled 3D path length, or zero for an empty path. */
+      /**
+       * Returns total sampled 3D path length, or zero for an empty path.
+       */
       export declare const pathLength: (path: readonly Vec3[], limits?: Partial<GeometrySamplingLimits>) => number;
 
       /**
@@ -1467,7 +1628,9 @@ export declare interface ArcCurve3 {
           readonly outer: Loop2;
       }
 
-      /** Equal arc-length sampling of an open path or an implicitly closed loop. */
+      /**
+       * Equal arc-length sampling of an open path or an implicitly closed loop.
+       */
       export declare interface PolylineResamplingOptions extends CurveSamplingOptions {
           /** Exact equal arc-length intervals; closed paths require at least three. */
           readonly segments?: number;
@@ -1475,7 +1638,7 @@ export declare interface ArcCurve3 {
           readonly closed?: boolean;
       }
 
-      /** Checks regular-grid dimensions and bounds allocation before evaluating any height samples. */
+      /** Checks grid dimensions, coordinate precision, and allocation bounds before evaluating heights. */
       export declare function preflightHeightfield(options: HeightfieldOptions, limits?: HeightfieldMeshLimits): HeightfieldPreflight;
 
       /**
@@ -1542,7 +1705,9 @@ export declare interface ArcCurve3 {
           loose: PrintableThreadFitPolicy;
       }>;
 
-      /** 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";
 
       /**
@@ -1677,10 +1842,14 @@ export declare interface ArcCurve3 {
           readonly toothCount: number;
       }
 
-      /** 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>;
@@ -1702,10 +1871,19 @@ export declare interface ArcCurve3 {
       bottomRight: RectangleCornerTreatment
       ];
 
-      /** Creates an immutable CCW rectangle loop. Round radius zero is square; tangent saturated endpoints occur once. */
+      /**
+       * Creates an immutable CCW rectangle loop. Round radius zero is square; tangent saturated endpoints occur once.
+       *
+       * @example Rounded rectangle outline
+       * ```ts
+       * rectangleLoop({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
+       * ```
+       */
       export declare function rectangleLoop(options: RectangleLoopOptions): Loop2;
 
-      /** 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;
@@ -1717,7 +1895,14 @@ export declare interface ArcCurve3 {
           readonly limits?: Partial<GeometrySamplingLimits>;
       }
 
-      /** Creates an identified rectangle whose edge/corner spans survive zero and saturated round radii. Outer winding is CCW. */
+      /**
+       * Creates an identified rectangle whose edge/corner spans survive zero and saturated round radii. Outer winding is CCW.
+       *
+       * @example Retain rectangle landmarks
+       * ```ts
+       * rectangleProfile({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
+       * ```
+       */
       export declare function rectangleProfile(options: RectangleProfileOptions): Profile;
 
       /** Shared rectangle options with an identified component for explicit profile families. */
@@ -1744,7 +1929,14 @@ export declare interface ArcCurve3 {
       /** Returns finite axis-aligned bounds for a non-empty region. */
       export declare function regionBounds(region: Region2): Bounds2;
 
-      /** Creates a centered CCW point loop with vertex or face radial sizing and an implicit seam. */
+      /**
+       * Creates a centered CCW point loop with vertex or face radial sizing and an implicit seam.
+       *
+       * @example Hexagon sized to its faces
+       * ```ts
+       * regularPolygonLoop({ radius: 10, sides: 6, sizing: "face" });
+       * ```
+       */
       export declare const regularPolygonLoop: (options: RegularPolygonLoopOptions) => readonly Vec2[];
 
       /** Exact regular polygon dimensions and counterclockwise degree rotation. */
@@ -1766,7 +1958,8 @@ export declare interface ArcCurve3 {
        */
       export declare function resamplePolyline2(path: readonly Vec2[], options?: PolylineResamplingOptions): SampledCurve2;
 
-      /** Resamples a spatial polyline at equal arc lengths with directed outgoing tangents.
+      /**
+       * Resamples a spatial polyline at equal arc lengths with directed outgoing tangents.
        * @remarks Open paths retain both endpoints; closed paths include the closing edge and omit the
        * repeated seam. Repeated adjacent inputs and explicit closing duplicates are removed. Physical
        * maxSegmentLength bounds arc-length intervals; exact counts override that policy. Output edges
@@ -1944,10 +2137,18 @@ export declare interface ArcCurve3 {
            * @param profile - Closed CCW `[radius, z]` profile without a duplicated seam point.
            * @param options - Optional physical or exact circumferential sampling controls. Defaults to `{}`.
            * @returns A closed indexed triangle mesh revolved counter-clockwise around +Z.
+           *
+           * @example Partial revolution with end caps
+           * ```ts
+           * // Each point is [radius, Z]; the profile seam is implicit.
+           * revolveMesh([[0, 0], [12, 0], [8, 20], [0, 20]], { revolveDegrees: 270 });
+           * ```
            */
           export declare const revolveMesh: (profile: readonly Vec2[], options?: RevolveOptions) => TriangleMesh;
 
-          /** 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.
@@ -1984,7 +2185,9 @@ export declare interface ArcCurve3 {
            */
           export declare const roundClosedPolylinePath: (points: readonly Vec3[], radius: number, segmentsPerCorner: number, limits?: Partial<GeometrySamplingLimits>) => readonly Vec3[];
 
-          /** 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";
@@ -2002,7 +2205,8 @@ export declare interface ArcCurve3 {
            */
           export declare function sampleCurve2(curve: Curve2, options?: CurveSamplingOptions): SampledCurve2;
 
-          /** Samples a spatial curve, preserving endpoints and directed unit tangents.
+          /**
+           * Samples a spatial curve, preserving endpoints and directed unit tangents.
            * @remarks Exact counts use uniform curve parameters, not equal physical distances. Adaptive cubics
            * bound the full control hull. Full-circle arcs repeat their endpoint; closed polylines do not.
            * @example
@@ -2029,7 +2233,9 @@ export declare interface ArcCurve3 {
               readonly tangents: readonly Vec2[];
           }
 
-          /** Immutable spatial points and corresponding directed unit tangents. */
+          /**
+           * Immutable spatial points and corresponding directed unit tangents.
+           */
           export declare interface SampledCurve3 {
               /** Curves retain both endpoints, including full-circle seams; closed resampling omits its seam. */
               readonly points: readonly Vec3[];
@@ -2149,7 +2355,13 @@ export declare interface ArcCurve3 {
             */
            export declare function sampleThreadHelices(options: ThreadHelixOptions): SampledThreadHelices;
 
-           /** Multiplies a vector by a dimensionless scalar. @example `scale3([1, 2, 3], 2)` */
+           /**
+            * Multiplies a vector by a dimensionless scalar.
+            * @example
+            * ```ts
+            * scale3([1, 2, 3], 2); // [2, 4, 6]
+            * ```
+            */
            export declare const scale3: (vector: Vec3, scale: number) => Vec3;
 
            /**
@@ -2180,7 +2392,17 @@ export declare interface ArcCurve3 {
                readonly limits?: Partial<GeometrySamplingLimits>;
            }
 
-           /** Exactly one radius or diameter, placement, and tessellation for an origin-centered sphere. */
+           /** Bounded floating-point intersection and shell-orientation validation settings. */
+           export declare interface SolidMeshValidationOptions {
+               /** Work ceiling for spatial comparisons and containment tests; defaults to 2,000,000 and may only lower it. */
+               readonly maximumTests?: number;
+               /** Distance comparison policy in millimetres; near contacts reject conservatively. */
+               readonly tolerance?: GeometryToleranceOptions;
+           }
+
+           /**
+            * 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;
@@ -2204,7 +2426,14 @@ export declare interface ArcCurve3 {
                readonly depth?: number;
            }
 
-           /** Creates a centered CCW alternating-radius star within the selected profile sampling ceiling. */
+           /**
+            * Creates a centered CCW alternating-radius star within the selected profile sampling ceiling.
+            *
+            * @example Five-point outline
+            * ```ts
+            * starLoop(12, 5, 6);
+            * ```
+            */
            export declare const starLoop: (outerRadius: number, points: number, innerRadius?: number, limits?: Partial<GeometrySamplingLimits>) => readonly Vec2[];
 
            /** End-cap treatment for an open stroked path. */
@@ -2239,7 +2468,13 @@ export declare interface ArcCurve3 {
                readonly width: number;
            }
 
-           /** Subtracts `b` from `a`. @example `subtract3([4, 5, 6], [1, 2, 3])` */
+           /**
+            * Subtracts `b` from `a`.
+            * @example
+            * ```ts
+            * subtract3([4, 5, 6], [1, 2, 3]); // [3, 3, 3]
+            * ```
+            */
            export declare const subtract3: (a: Vec3, b: Vec3) => Vec3;
 
            /** Sampling controls for deterministic SVG-to-region conversion. */
@@ -2317,10 +2552,22 @@ export declare interface ArcCurve3 {
                readonly parsedVertices: number;
            }
 
-           /** Sweeps one explicitly ordered point loop, with caps or a geometrically matching closed seam. */
+           /**
+            * Sweeps one explicitly ordered point loop, with caps or a geometrically matching closed seam.
+            *
+            * @example Sweep point data along a bent path
+            * ```ts
+            * const profile = rectangleLoop({ size: [6, 3] });
+            * sweepMesh(profile, [[0, 0, 0], [0, 0, 15], [10, 0, 25]], {
+            *   orientation: { kind: "transport", initialNormal: [0, 1, 0] },
+            * });
+            * ```
+            */
            export declare function sweepMesh(profile: Loop2, path: readonly Vec3[], options?: SweepOptions): TriangleMesh;
 
-           /** 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;
@@ -2340,7 +2587,9 @@ export declare interface ArcCurve3 {
                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";
@@ -2413,7 +2662,9 @@ export declare interface ArcCurve3 {
            /** 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;
@@ -2449,10 +2700,14 @@ export declare interface ArcCurve3 {
                readonly threadCircularSegments: number;
            }
 
-           /** Supported printable nut body shapes. */
+           /**
+            * Supported printable nut body shapes.
+            */
            export declare type ThreadedNutShape = "hex" | "round" | "square";
 
-           /** 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;
@@ -2500,7 +2755,9 @@ export declare interface ArcCurve3 {
                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";
 
            /** Conventional helix options: `pitch` is adjacent spacing and lead is `pitch * starts`. */
@@ -2531,7 +2788,9 @@ export declare interface ArcCurve3 {
            /** 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;
@@ -2555,13 +2814,17 @@ export declare interface ArcCurve3 {
                readonly tolerance?: GeometryToleranceOptions;
            }
 
-           /** Supported built-in and caller-defined thread profiles. */
+           /**
+            * Supported built-in and caller-defined thread profiles.
+            */
            export declare type ThreadProfileSpec = AcmeThreadProfileSpec | ButtressThreadProfileSpec | CustomThreadProfileSpec | SquareThreadProfileSpec | TrapezoidalThreadProfileSpec | TriangularThreadProfileSpec;
 
            /** Whether compensation is being applied to an external or internal thread. */
            export declare type ThreadRole = "male" | "female";
 
-           /** 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>;
@@ -2664,7 +2927,9 @@ export declare interface ArcCurve3 {
                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;
@@ -2672,7 +2937,9 @@ export declare interface ArcCurve3 {
                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;
@@ -2680,13 +2947,17 @@ export declare interface ArcCurve3 {
                readonly edgeCount?: number;
            }
 
-           /** Validation and optional connectivity controls for a shared mesh analysis. */
+           /**
+            * Validation and optional connectivity controls for a shared mesh analysis.
+            */
            export declare interface TriangleMeshAnalysisOptions extends TriangleMeshValidationOptions {
                /** Compute indexed edge/component counts and reject unreferenced vertices; defaults to false. */
                readonly includeTopology?: boolean;
            }
 
-           /** 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;
@@ -2790,7 +3061,9 @@ export declare interface ArcCurve3 {
                readonly tolerance?: GeometryToleranceOptions;
            }
 
-           /** ISO/UTS-like 60-degree truncated triangular profile. */
+           /**
+            * ISO/UTS-like 60-degree truncated triangular profile.
+            */
            export declare interface TriangularThreadProfileSpec extends ThreadProfileBaseSpec {
                /** Selects the 60-degree triangular profile family. */
                readonly kind: "triangular";
@@ -2809,7 +3082,9 @@ export declare interface ArcCurve3 {
            /** Ear-clips one normalized simple CCW loop into stable local vertex indices. */
            export declare function triangulateLoop2(loop: Loop2): Uint32Array;
 
-           /** 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`.
@@ -2824,6 +3099,22 @@ export declare interface ArcCurve3 {
                readonly outerRadius: number;
            }
 
+           /**
+            * Checks closed indexed topology, triangle intersections, and alternating nested shell orientation.
+            * Outward exterior shells and inward cavity shells are accepted. Separate shells must not touch,
+            * intersect, or overlap as material. Indexed neighbours may share their own vertex or edge.
+            *
+            * Uses bounded floating-point tests, not exact predicates or repair. Contacts within the selected
+            * tolerance reject conservatively. At most 200,000 triangles and 2,000,000 spatial/containment tests
+            * are supported; exhausting a ceiling throws COMPLEXITY_LIMIT rather than claiming validity.
+            * Input buffers are freshly inspected and never modified; units are millimetres.
+            *
+            * @param mesh - Closed triangle mesh to inspect.
+            * @param options - Optional lower work ceiling and numeric comparison policy.
+            * @returns The original mesh after every requested check succeeds.
+            */
+           export declare function validateSolidMesh(mesh: TriangleMesh, options?: SolidMeshValidationOptions): TriangleMesh;
+
            /**
             * Validates that a transform is finite, affine, and non-singular.
             *
@@ -2855,6 +3146,18 @@ export declare interface ArcCurve3 {
              /** A three-dimensional Cartesian vector or point. */
              export declare type Vec3 = readonly [x: number, y: number, z: number];
 
+             /** A circular baseline centered at the XY origin, with rigid shaped glyph groups. */
+             export declare interface VectorTextArcBaseline {
+                 /** Selects a circular baseline; glyph outlines rotate without bending or stretching. */
+                 readonly kind: "arc";
+                 /** Baseline radius in millimetres, greater than zero and at most 10000. */
+                 readonly radius: number;
+                 /** Alignment datum in degrees counterclockwise from +X; defaults to 90. */
+                 readonly centerAngleDegrees?: number;
+                 /** Reading direction around the circle; defaults to clockwise. */
+                 readonly direction?: "clockwise" | "counterclockwise";
+             }
+
              /** Exact curve bounds in millimetres; positive Y points upward. */
              export declare interface VectorTextBounds {
                  /** Minimum X and Y of visible outlines, including accents, descenders, and overhangs. */
@@ -2863,7 +3166,9 @@ export declare interface ArcCurve3 {
                  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[];
@@ -2871,13 +3176,17 @@ export declare interface ArcCurve3 {
                  readonly metrics: VectorTextMetrics;
              }
 
-             /** Horizontal multiline text, bounded to 512 UTF-16 units and 16 lines without wrapping. */
+             /**
+              * Text bounded to 512 UTF-16 units: horizontal lines or one circular line without wrapping.
+              */
              export declare interface VectorTextLayoutOptions extends VectorTextOptions {
-                 /** Place each line's advance at the origin; defaults to left. Ink overhang is preserved. */
+                 /** Place the advance's start, midpoint or end at the datum; defaults to center on arcs, otherwise left. */
                  readonly align?: "left" | "center" | "right";
+                 /** Omitted uses horizontal lines. Arcs require one line and baseline vertical alignment. */
+                 readonly baseline?: VectorTextArcBaseline;
                  /** Baseline spacing in ems, 0.5–5; omitted uses the selected face's natural vertical metrics. */
                  readonly lineHeight?: number;
-                 /** Place the first baseline or the complete ink bounds at Y=0; defaults to baseline. */
+                 /** Place the first baseline or complete ink bounds at Y=0; arcs only accept baseline. */
                  readonly verticalAlign?: "baseline" | "top" | "center" | "bottom";
              }
 
@@ -2885,9 +3194,9 @@ export declare interface ArcCurve3 {
              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;