@metamesh/modeling 0.6.0 → 0.7.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>;
@@ -455,6 +478,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 +500,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 +523,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 +545,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 +600,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 +625,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 +665,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 +684,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 +720,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 +778,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 +817,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 +839,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 +938,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;
@@ -905,6 +986,14 @@ export declare interface ArcCurve3 {
       * 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.
+      *
+      * @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;
 
@@ -1068,6 +1157,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 +1173,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 +1191,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 +1223,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 +1264,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 +1446,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 +1461,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 +1581,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;
@@ -1542,7 +1658,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 +1795,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 +1824,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 +1848,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 +1882,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 +1911,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 +2090,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 +2138,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 +2158,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 +2186,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 +2308,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 +2345,9 @@ export declare interface ArcCurve3 {
                readonly limits?: Partial<GeometrySamplingLimits>;
            }
 
-           /** 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;
@@ -2204,7 +2371,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 +2413,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 +2497,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 +2532,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 +2607,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 +2645,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 +2700,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 +2733,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 +2759,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 +2872,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 +2882,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 +2892,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 +3006,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 +3027,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`.
@@ -2863,7 +3083,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,7 +3093,9 @@ export declare interface ArcCurve3 {
                  readonly metrics: VectorTextMetrics;
              }
 
-             /** Horizontal multiline text, bounded to 512 UTF-16 units and 16 lines without wrapping. */
+             /**
+              * Horizontal multiline text, bounded to 512 UTF-16 units and 16 lines without wrapping.
+              */
              export declare interface VectorTextLayoutOptions extends VectorTextOptions {
                  /** Place each line's advance at the origin; defaults to left. Ink overhang is preserved. */
                  readonly align?: "left" | "center" | "right";