@metamesh/modeling 0.14.0 → 0.15.0

package/dist/api/index.d.ts

@@ -37,16 +37,14 @@ export declare interface Anchor3 {
   readonly up: Vector3Tuple;
 }
 
-/**
- * Degree-based anchor attachment controls for a scoped solid.
- */
+/** Options controlling how one anchor is attached to another. */
 export declare interface AttachOptions {
   /** Align outward directions face-to-face (`opposed`) or in parallel (`same`). */
   readonly alignment?: "opposed" | "same";
-  /** Separation along the target anchor's outward direction in millimetres. */
+  /** Separation along the target anchor's outward direction in model units. */
   readonly gap?: number;
   /** Additional right-handed roll about the attached direction, in degrees. */
-  readonly spinDegrees?: number;
+  readonly spin?: number;
   /** Optional numeric comparison overrides. */
   readonly tolerance?: GeometryToleranceOptions;
 }
@@ -103,7 +101,7 @@ export declare type BoxEdgeTreatments = Readonly<
 /**
  * Dimensions, placement, and uniform or independently selected finishing for an axis-aligned box.
  */
-export declare interface BoxOptions extends PrimitivePlacement {
+export declare interface BoxOptions extends PrimitiveAttachment {
   /** Explicit sampling ceilings for edge treatments, bounded by the host policy. */
   readonly limits?: Partial<GeometrySamplingLimits>;
   /**
@@ -137,6 +135,13 @@ declare interface ButtressThreadProfileSpec extends ThreadProfileBaseSpec {
   readonly pressureFlankSide?: ButtressPressureFlankSide;
 }
 
+/** Copies intersections along the finite directed origin-to-endpoint segment. */
+export declare function castSegment(
+  solid: Solid,
+  origin: Vector3Input,
+  endpoint: Vector3Input,
+): readonly SolidSegmentHit[];
+
 /**
  * A planar edge or corner chamfer with equal or independent surface setbacks.
  */
@@ -180,7 +185,7 @@ export declare type CircleContourOptions = CircularPrimitiveOptions &
 /**
  * Circular dimensions with exactly one nominal radius or diameter.
  */
-export declare type CircleOptions = CircleContourOptions & PrimitivePlacement;
+export declare type CircleOptions = CircleContourOptions & PrimitiveAttachment;
 
 /**
  * Tessellation controls shared by circular primitives across Geometry entry points.
@@ -200,11 +205,11 @@ export declare interface CircularPrimitiveOptions {
 }
 
 /**
- * Observes a solid's disconnected surface shells as session-restricted solid selections.
+ * Observes disconnected material pieces as session-restricted solid selections.
  *
- * 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.
+ * Each piece retains its enclosed cavities. A sealed hollow box is one component; adding a loose
+ * ball inside its cavity produces two. Recombining the pieces preserves the original material.
+ * This does not cut connected geometry. Containment is bounded to 2,000,000 comparisons.
  * Selection order and cardinality depend on evaluated topology. Results and recipes using them
  * can only be evaluated in this session; composition itself requires no engine.
  *
@@ -280,6 +285,20 @@ export declare type CorrespondingProfileStation = LoftPlacement & {
   readonly profile: CorrespondingProfile;
 };
 
+/**
+ * Explicit physical sampling and allocation policy for reusable curves.
+ */
+declare interface CurveSamplingOptions {
+  /** Exact segment count overrides physical criteria; curve parameters are spaced uniformly. */
+  readonly segments?: number;
+  /** Millimetre sampling policy; circularSegments applies only to arcs. */
+  readonly resolution?: GeometryResolution;
+  /** Output vertex ceiling of at least two; may only lower limits.maxPathPoints. */
+  readonly maxVertices?: number;
+  /** Explicit sampling ceilings; omitted values use package defaults without ambient state. */
+  readonly limits?: Partial<GeometrySamplingLimits>;
+}
+
 /** Caller-defined periodic axial/radial profile in millimetres. */
 declare interface CustomThreadProfileSpec extends ThreadProfileBaseSpec {
   /** Selects a caller-defined periodic profile. */
@@ -311,7 +330,7 @@ export declare function cylinder(options: CylinderOptions): Solid;
  */
 export declare type CylinderOptions = CircularPrimitiveOptions &
   RadialSizingOptions &
-  PrimitivePlacement & {
+  PrimitiveAttachment & {
     /**
      * Centers the solid on the Z origin when `true`; otherwise its bottom is at `Z = 0`.
      * @defaultValue `true`
@@ -400,7 +419,8 @@ export declare type EllipseContourOptions = CircularPrimitiveOptions &
 /**
  * Ellipse dimensions in local XY, with exactly one radii or full-size tuple.
  */
-export declare type EllipseOptions = EllipseContourOptions & PrimitivePlacement;
+export declare type EllipseOptions = EllipseContourOptions &
+  PrimitiveAttachment;
 
 /**
  * Independent inward finishing on primitive or straight convex extrusion ends.
@@ -452,9 +472,9 @@ declare interface ExtrusionSamplingOptions {
   /** Operation-level physical policy over the nearest model scope. */
   readonly resolution?: GeometryResolution;
   /** Finite uniform or XY scale of the top profile; defaults to one. */
-  readonly scaleTop?: number | Vector2Tuple;
+  readonly scaleTop?: number | Vector2Input;
   /** Finite rotation of the top profile about +Z, in degrees; defaults to zero. */
-  readonly twistDegrees?: number;
+  readonly twist?: number;
 }
 
 /** Finalized manufacturing snapshot. Its arrays are independent of all native values. */
@@ -465,19 +485,21 @@ export declare interface FinalizedModel {
   readonly bounds: Bounds3;
   /** Aggregate counts, unique backing storage, volume, and execution timings. */
   readonly stats: {
+    /** Number of declared output parts, including repeated geometry instances. */
+    readonly partCount: number;
     /** Aggregate position-buffer vertex count. */
-    readonly vertices: number;
+    readonly vertexCount: number;
     /** Aggregate indexed triangle count. */
-    readonly triangles: number;
+    readonly triangleCount: number;
     /** Signed enclosed volume of all selected parts in cubic millimetres. */
     readonly volumeMm3: number;
     /** Unique transferable backing-buffer bytes, counted once across all parts. */
-    readonly bytes: number;
+    readonly byteCount: number;
     /** Synchronous callback duration in milliseconds. */
     readonly buildMs: number;
     /** Manufacturing validation and buffer finalization duration in milliseconds. */
     readonly finalizationMs: number;
-    /** Total callback and finalization duration in milliseconds. */
+    /** Total generation duration, including cache retention and native cleanup, in milliseconds. */
     readonly generationMs: number;
   };
 }
@@ -589,9 +611,9 @@ export declare interface GeometryResolution {
   /** Optional maximum sampled edge length in millimetres. */
   readonly maxSegmentLength?: number;
   /** Upper safety bound for a full circle; defaults to the selected maxCircularSegments (512 by default). */
-  readonly maximumSegments?: number;
+  readonly maxSegments?: number;
   /** Lower full-circle segment count; defaults to 16 or a lower selected circular ceiling. */
-  readonly minimumSegments?: number;
+  readonly minSegments?: number;
 }
 
 /** Explicit allocation ceilings for pure sampling and host-owned modeling operations. */
@@ -629,16 +651,17 @@ export declare function gridPattern(
   options: GridPatternOptions,
 ): readonly Solid[];
 
-/** Repeats a filled Section on a grid; placements must preserve its XY plane. */
+/** Repeats a filled Section on an XY grid; any explicit frame must preserve the XY plane. */
 export declare function gridPattern(
   source: PatternSource<Section>,
-  options: GridPatternOptions,
+  options: GridPatternOptions<2>,
 ): readonly Section[];
 
 /**
  * XY or XYZ grid with X varying fastest. The first item starts at the local origin.
+ * Dimension 2 restricts counts and spacing to XY; any frame must preserve the XY plane.
  */
-export declare type GridPatternOptions = {
+export declare type GridPatternOptions<Dimension extends 2 | 3 = 3> = {
   /** Center the complete distribution around its local origin; defaults to false. */
   readonly center?: boolean;
   /** Optional right-handed local axes and origin for the grid. */
@@ -650,12 +673,14 @@ export declare type GridPatternOptions = {
       /** Signed millimetres between adjacent copies on X and Y. */
       readonly spacing: Vector2Tuple;
     }
-  | {
-      /** Positive integer counts on X, Y and Z. */
-      readonly count: Vector3Tuple;
-      /** Signed millimetres between adjacent copies on X, Y and Z. */
-      readonly spacing: Vector3Tuple;
-    }
+  | (Dimension extends 3
+      ? {
+          /** Positive integer counts on X, Y and Z. */
+          readonly count: Vector3Tuple;
+          /** Signed millimetres between adjacent copies on X, Y and Z. */
+          readonly spacing: Vector3Tuple;
+        }
+      : never)
 );
 
 /**
@@ -741,7 +766,7 @@ export declare interface HelicalThreadRidgeMeshOptions {
   /** Nominal major diameter before any caller-owned fit compensation. */
   readonly majorDiameter: number;
   /** Angular offset of the first start in degrees. Default: `0`. */
-  readonly phaseDegrees?: number;
+  readonly phase?: number;
   /** Validated periodic profile repeated around the shaft. */
   readonly profile: ThreadProfile;
   /** Optional circular-resolution policy. */
@@ -783,7 +808,7 @@ export declare function hull(options: SectionHullOptions): Section;
 export declare type HullOptions =
   | {
       /** Finite millimetre XYZ points to include in the convex hull. */
-      readonly points: readonly Vector3Tuple[];
+      readonly points: readonly Vector3Input[];
       /** Point input excludes solid input. */
       readonly solids?: never;
     }
@@ -898,8 +923,8 @@ export declare function inspectSolid(solid: Solid): SolidInspection;
  * @example Internal thread
  * ```ts
  * import { cylinder, internalThreadCutter } from "@metamesh/modeling";
- * import { createThreadProfile } from "@metamesh/modeling/geometry";
- * const profile = createThreadProfile({ kind: "triangular", pitch: 1.75 });
+ * import { threadProfile } from "@metamesh/modeling/geometry";
+ * const profile = threadProfile({ kind: "triangular", pitch: 1.75 });
  * const body = cylinder({ diameter: 20, height: 12, center: false });
  * const cutter = internalThreadCutter({ nominalMajorDiameter: 12, length: 12, profile });
  * body.subtract([cutter]);
@@ -962,18 +987,19 @@ export declare function linearPattern(
   options: LinearPatternOptions,
 ): readonly Solid[];
 
-/** Repeats a filled Section; every placement must preserve its XY plane. */
+/** Repeats a filled Section along an XY direction, defaulting to +X. */
 export declare function linearPattern(
   source: PatternSource<Section>,
-  options: LinearPatternOptions,
+  options: LinearPatternOptions<2>,
 ): readonly Section[];
 
 /**
  * Equal linear intervals determined by exactly two of count, spacing and total length.
+ * Dimension defaults to 3; Section patterns use 2 and accept XY vector directions.
  */
-export declare type LinearPatternOptions = {
+export declare type LinearPatternOptions<Dimension extends 2 | 3 = 3> = {
   /** Direction of repetition; magnitude is ignored. Defaults to +X. */
-  readonly direction?: Vector3Tuple;
+  readonly direction?: Dimension extends 2 ? Vector2Input : Vector3Input;
 } & (
   | {
       /** Positive copy count, including the original. */
@@ -1079,10 +1105,13 @@ export declare type LoftPlacement =
  */
 export declare type LoftStation = LoftPlacement & {
   /** Filled Section recipe or ordered XY boundary point data. */
-  readonly profile: Section | Contour;
+  readonly profile: Section | Path2Input;
 };
 
-/** Explicit family matching on a shared physical span grid using session or operation resolution. */
+/**
+ * Matches a profile family using operation settings over host resolution and limits.
+ * Requires active synchronous model execution. Use Geometry's matchProfiles for standalone preparation.
+ */
 export declare function matchProfiles(
   profiles: readonly Profile[],
   options?: MatchProfilesOptions,
@@ -1138,8 +1167,91 @@ export declare interface PartOptions {
   readonly color?: string;
 }
 
-/** An ordered, open sequence of two-dimensional points. */
-export declare type Path2 = readonly Vector2Tuple[];
+/** Immutable directed XY polyline. Closure is explicit and does not imply a filled Section. */
+export declare interface Path2 {
+  /** Coordinate dimension; identifies planar paths even when empty. */
+  readonly dimension: 2;
+  /** Whether traversal includes the last-to-first edge. */
+  readonly closed: boolean;
+  /** Returns frozen tuple coordinates; closure remains separate metadata. Repeated calls do not allocate. */
+  toArray(): Path2Data;
+  /** Total sampled edge length in model units, including the closing edge when closed. */
+  length(): number;
+  /** Axis-aligned bounds, or undefined for an empty path. */
+  bounds(): Bounds2 | undefined;
+  /** Finds the nearest edge location; requires at least two vertices. */
+  closestPoint(point: Vector2Input): PathLocation<Vector2>;
+  /** Applies an XY placement without reordering traversal, including after reflection. */
+  transform(placement: Transform2Input): Path2;
+  /** Reverses vertex order and traversal; neither the source nor its coordinates are mutated. */
+  reverse(): Path2;
+  /** Returns a path sampled at equal arc lengths. Corners may be bridged; closure is preserved. */
+  resample(options?: PathResamplingOptions): Path2;
+}
+
+/**
+ * Snapshots finite XY coordinates as an immutable sampled path, independent of engine initialization.
+ * Open paths may be empty or have one point; closed paths need three vertices and omit a duplicated
+ * seam. Repeated adjacent vertices are retained. No winding normalization or filling is performed.
+ * Malformed dimensions or topology throw INVALID_ARGUMENT; nonfinite coordinates or measurement
+ * overflow throw NON_FINITE_VALUE; exhausted allocation ceilings throw COMPLEXITY_LIMIT GeometryError.
+ * A path input retains its closure. Limits bound construction only; resampling takes its own limits.
+ */
+export declare function path2(input: Path2Input, options?: PathOptions): Path2;
+
+/** XY point tuples for interchange; closure is supplied by the consuming operation or Path2 value. */
+export declare type Path2Data = readonly Vector2Tuple[];
+
+/** An immutable XY sampled path or a collection of XY tuples and fluent vectors. */
+export declare type Path2Input = Path2 | readonly Vector2Input[];
+
+/** Immutable directed XYZ polyline; it represents sampled edges, not an analytic curve. */
+export declare interface Path3 {
+  /** Coordinate dimension; identifies spatial paths even when empty. */
+  readonly dimension: 3;
+  /** Whether traversal includes the last-to-first edge. */
+  readonly closed: boolean;
+  /** Returns frozen tuple coordinates; closure remains separate metadata. Repeated calls do not allocate. */
+  toArray(): Path3Data;
+  /** Total sampled edge length in model units, including the closing edge when closed. */
+  length(): number;
+  /** Axis-aligned bounds, or undefined for an empty path. */
+  bounds(): Bounds3 | undefined;
+  /** Finds the nearest edge location; requires at least two vertices. */
+  closestPoint(point: Vector3Input): PathLocation<Vector3>;
+  /** Applies an XYZ placement without changing traversal order or closure. */
+  transform(placement: Transform3Input): Path3;
+  /** Reverses vertex order and traversal without mutating the source. */
+  reverse(): Path3;
+  /** Returns a path sampled at equal arc lengths. Corners may be bridged; closure is preserved. */
+  resample(options?: PathResamplingOptions): Path3;
+}
+
+/**
+ * Snapshots finite XYZ coordinates as an immutable sampled path with the same closure, seam,
+ * allocation and error rules as path2. Analytic curves must be sampled explicitly first.
+ */
+export declare function path3(input: Path3Input, options?: PathOptions): Path3;
+
+/**
+ * XYZ point tuples for interchange; closure is supplied by the consuming operation or Path3 value.
+ */
+export declare type Path3Data = readonly Vector3Tuple[];
+
+/** An immutable XYZ sampled path or a collection of XYZ tuples and fluent vectors. */
+export declare type Path3Input = Path3 | readonly Vector3Input[];
+
+/** Nearest location on a sampled boundary, rather than inside a filled shape or on an analytic curve. */
+export declare interface PathLocation<Point extends Vector2 | Vector3> {
+  /** Immutable position on the selected edge. */
+  readonly point: Point;
+  /** Euclidean distance from the query in model units. */
+  readonly distance: number;
+  /** Starting vertex of the selected edge; ties keep the first edge in traversal order. */
+  readonly edgeIndex: number;
+  /** Clamped fraction along that edge, not the whole path's normalized arc length. */
+  readonly fraction: number;
+}
 
 /**
  * Supplies a profile-X orientation guide for each original normalized sweep station.
@@ -1151,7 +1263,15 @@ export declare type Path2 = readonly Vector2Tuple[];
 export declare type PathNormalGuide = (
   point: Vector3Tuple,
   index: number,
-) => Vector3Tuple;
+) => Vector3Input;
+
+/** Topology and allocation ceiling for an immutable sampled path. */
+export declare interface PathOptions {
+  /** Connects the last vertex to the first; closed paths omit the repeated seam. Defaults to false. */
+  readonly closed?: boolean;
+  /** Construction point ceiling; defaults to package sampling limits. Later sampling has its own options. */
+  readonly limits?: Partial<GeometrySamplingLimits>;
+}
 
 /**
  * Physical arc-length copies along a sampled path, with optional tangent orientation.
@@ -1163,17 +1283,17 @@ export declare type PathNormalGuide = (
  */
 export declare function pathPattern(
   source: PatternSource,
-  path: readonly Vector3Tuple[],
+  path: Path3Input,
   options: PathPatternOptions,
 ): readonly Solid[];
 
 /**
- * Repeats a filled Section along a sampled XY path at Z=0. Fixed orientation preserves XY;
- * tangent orientation maps +Z to the tangent and rejects when that leaves the plane.
+ * Repeats a filled Section along a sampled XY path. Tangent orientation maps local +X
+ * to the path tangent counterclockwise, preserving the XY plane.
  */
 export declare function pathPattern(
   source: PatternSource<Section>,
-  path: readonly Vector3Tuple[],
+  path: Path2Input,
   options: PathPatternOptions,
 ): readonly Section[];
 
@@ -1181,12 +1301,18 @@ export declare function pathPattern(
 export declare interface PathPatternOptions {
   /** Positive number of copies; open paths include both endpoints when greater than one. */
   readonly count: number;
-  /** Include the closing edge without duplicating the seam; defaults to false. */
+  /** Raw point closure defaults to false; a path value supplies closure and rejects conflicts. */
   readonly closed?: boolean;
-  /** Preserve the source orientation, or align its +Z to the path tangent; defaults to fixed. */
+  /** Preserve orientation, or align local +X for Sections / +Z for Solids to the tangent. Defaults to fixed. */
   readonly orientation?: "fixed" | "tangent";
 }
 
+/** Equal arc-length sampling; the path itself owns whether its closing edge is included. */
+export declare interface PathResamplingOptions extends CurveSamplingOptions {
+  /** Exact arc-length intervals; closed paths need at least three. Otherwise physical resolution or the effective source edge count controls sampling. */
+  readonly segments?: number;
+}
+
 /**
  * One immutable shape, or a synchronous factory called once per copy in index order.
  */
@@ -1208,7 +1334,7 @@ export declare interface Pivot3Options {
 /** 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: Vector3Tuple;
+  readonly normal: Vector3Input;
   /** Signed millimetre distance from the origin along the unit normal. Defaults to zero. */
   readonly offset?: number;
 }
@@ -1223,7 +1349,7 @@ export declare interface PlaneOptions {
  * polygon([[0, 0], [20, 0], [10, 12]]).extrude({ height: 3 });
  * ```
  */
-export declare function polygon(input: Contour | PolygonOptions): Section;
+export declare function polygon(input: Path2Input | PolygonOptions): Section;
 
 /**
  * One bounded two-dimensional polygon.
@@ -1243,9 +1369,9 @@ export declare interface PolygonData {
 export declare type PolygonOptions =
   | {
       /** One simple exterior boundary, normalized to counterclockwise winding. */
-      readonly outer: Contour;
+      readonly outer: Path2Input;
       /** Disjoint simple holes inside the exterior; normalized to clockwise winding. */
-      readonly holes?: readonly Contour[];
+      readonly holes?: readonly Path2Input[];
       /** Explicit topology excludes compound contours. */
       readonly contours?: never;
       /** Explicit topology determines fill without a winding rule. */
@@ -1255,7 +1381,7 @@ export declare type PolygonOptions =
     }
   | {
       /** Compound boundaries; may overlap or contain holes according to the fill rule. */
-      readonly contours: readonly Contour[];
+      readonly contours: readonly Path2Input[];
       /** Winding interpretation; defaults to nonzero. An empty list creates an empty Section. */
       readonly fillRule?: "nonzero" | "evenodd";
       /** Compound contours exclude explicit topology. */
@@ -1278,41 +1404,33 @@ export declare type PolygonOptions =
       readonly fillRule?: never;
     };
 
-/** Allocation-free internal-thread facts. */
+/** Internal-thread facts using host resolution and limits; requires active synchronous model execution. */
 export declare function preflightInternalThreadCutter(
   options: InternalThreadCutterOptions,
 ): HelicalThreadSolidMeshPreflight;
 
-/** Allocation-free nut/cutter facts. */
+/** Nut/cutter facts using host resolution and limits; requires active synchronous model execution. */
 export declare function preflightThreadedNut(
   options: ThreadedNutOptions,
 ): ThreadedNutPreflight;
 
-/** Allocation-free external-thread facts. */
+/** External-thread facts using host resolution and limits; requires active synchronous model execution. */
 export declare function preflightThreadedRod(
   options: ThreadedRodOptions,
 ): HelicalThreadSolidMeshPreflight;
 
-/** Placement shared by solid and filled-section factories. */
-export declare interface PrimitivePlacement {
-  /** Applied after local construction; Section placement must preserve the XY plane. */
-  readonly placement?: PrimitivePlacementOptions;
+/** Anchor attachment shared by solid and filled-section factories. */
+export declare interface PrimitiveAttachment {
+  /** Applied after local construction; Section attachment must preserve the XY plane. */
+  readonly attachment?: PrimitiveAttachmentOptions;
 }
 
 /** Maps an explicit or named shape-local attachment anchor onto a world-space anchor. */
-export declare interface PrimitivePlacementOptions {
+export declare interface PrimitiveAttachmentOptions extends AttachOptions {
   /** Shape-local source frame or a named primitive anchor such as bottom. */
   readonly source: Anchor3 | string;
   /** World-space target frame in millimetres. */
   readonly target: Anchor3;
-  /** Align outward directions face-to-face or in parallel. Defaults to opposed. */
-  readonly alignment?: "opposed" | "same";
-  /** Finite separation along the target direction in millimetres. Defaults to zero. */
-  readonly gap?: number;
-  /** Finite additional roll around the attached direction in degrees. Defaults to zero. */
-  readonly spinDegrees?: number;
-  /** Explicit numeric comparison overrides for anchor normalization. */
-  readonly tolerance?: GeometryToleranceOptions;
 }
 
 /**
@@ -1397,9 +1515,9 @@ export declare type ProfileSpan2 = {
       /** Circular radius in millimetres. */
       readonly radius: number;
       /** Initial counterclockwise angle in degrees. */
-      readonly startDegrees: number;
+      readonly startAngle: number;
       /** Signed counterclockwise angular sweep in degrees. */
-      readonly sweepDegrees: number;
+      readonly sweepAngle: number;
     }
   | {
       /** Selects a cubic Bézier span with the same coordinates as CubicBezierCurve2. */
@@ -1421,7 +1539,7 @@ export declare type ProfileSpan2 = {
  * @example Six copies around Z
  * ```ts
  * const pin = cylinder({ height: 6, radius: 2 }).translate([12, 0, 0]);
- * radialPattern(pin, { count: 6, axis: [0, 0, 1], angleDegrees: 60 });
+ * radialPattern(pin, { count: 6, axis: [0, 0, 1], angle: 60 });
  * ```
  */
 export declare function radialPattern(
@@ -1429,25 +1547,31 @@ export declare function radialPattern(
   options: RadialPatternOptions,
 ): readonly Solid[];
 
-/** Repeats a filled Section about an axis; placements must preserve its XY plane. */
+/** Repeats a filled Section counterclockwise about a fixed XY pivot, using the implicit +Z axis. */
 export declare function radialPattern(
   source: PatternSource<Section>,
-  options: RadialPatternOptions,
+  options: RadialPatternOptions<2>,
 ): readonly Section[];
 
 /**
- * Options for repeating one solid around an axis through a center point.
+ * Degree rotations about a fixed world-space pivot; XY patterns use the implicit +Z axis.
  */
-export declare interface RadialPatternOptions {
-  /** Number of solids to return, including the original. */
+export declare type RadialPatternOptions<Dimension extends 2 | 3 = 3> = {
+  /** Number of shapes to return, including the original. */
   readonly count: number;
-  /** Axis of the right-handed rotation. Its magnitude is ignored. */
-  readonly axis: Vector3Tuple;
   /** Signed rotation from one copy to the next, in degrees. */
-  readonly angleDegrees: number;
-  /** Rotation center in world coordinates. Defaults to the origin. */
-  readonly center?: Vector3Tuple;
-}
+  readonly angle: number;
+  /** Fixed world-space rotation pivot; defaults to the coordinate origin. */
+  readonly pivot?: Dimension extends 2 ? Vector2Input : Vector3Input;
+} & (Dimension extends 2
+  ? {
+      /** XY rotation uses +Z; an explicit spatial axis is unavailable. */
+      readonly axis?: never;
+    }
+  : {
+      /** Axis of the right-handed rotation. Its nonzero magnitude is ignored. */
+      readonly axis: Vector3Input;
+    });
 
 /** Radial dimensions refer to polygon vertices or compensate faceting to meet polygon faces. */
 export declare type RadialSizing = "vertex" | "face";
@@ -1462,13 +1586,6 @@ export declare interface RadialSizingOptions {
   readonly sizing?: RadialSizing;
 }
 
-/** Copies intersections along the finite directed origin-to-endpoint segment. */
-export declare function rayCast(
-  solid: Solid,
-  origin: Vector3Tuple,
-  endpoint: Vector3Tuple,
-): readonly SolidRayHit[];
-
 /**
  * Filled rectangular section with uniform or independently treated corners.
  *
@@ -1513,7 +1630,7 @@ export declare type RectangleCornerTreatments = readonly [
  * Rectangle dimensions, placement and uniform or per-corner treatment.
  */
 export declare interface RectangleOptions
-  extends RectangleContourOptions, PrimitivePlacement {}
+  extends RectangleContourOptions, PrimitiveAttachment {}
 
 /** A two-dimensional region represented by disjoint filled polygons. */
 export declare type RegionData = readonly PolygonData[];
@@ -1532,13 +1649,13 @@ export declare function regularPolygon(options: RegularPolygonOptions): Section;
  * Regular polygon dimensions, radial convention and degree rotation.
  */
 export declare type RegularPolygonOptions = RadialSizingOptions &
-  PrimitivePlacement & {
+  PrimitiveAttachment & {
     /** Positive nominal radius in millimetres, interpreted according to sizing. */
     readonly radius: number;
     /** Exact integer side count from three through 100000. */
     readonly sides: number;
     /** Counterclockwise rotation in degrees; defaults to zero with a vertex on +X. */
-    readonly rotationDegrees?: number;
+    readonly rotation?: number;
   };
 
 /**
@@ -1552,7 +1669,7 @@ export declare type RegularPolygonOptions = RadialSizingOptions &
  *
  * // Contour coordinates are [radius, Z].
  * const [profile] = matchProfiles([rectangleProfile({ size: [4, 16], center: false })]);
- * revolve(profile!, { revolveDegrees: 270 });
+ * revolve(profile!, { degrees: 270 });
  * ```
  */
 export declare function revolve(
@@ -1565,12 +1682,14 @@ export declare function revolve(
  */
 export declare interface RevolveOptions extends CircularPrimitiveOptions {
   /**
-   * Positive angular sweep no greater than 360 degrees; partial revolutions have end caps.
+   * Positive sweep in degrees, no greater than 360. Defaults to a full revolution;
+   * smaller sweeps form partial revolutions with end caps.
    * Segment counts describe a complete circle and scale to this angular span. Native filled
    * revolutions require at least three sweep intervals: adaptive sampling refines to that floor,
    * while exact counts that imply fewer intervals reject. Pure revolveMesh supports one interval.
+   * @defaultValue `360`
    */
-  readonly revolveDegrees?: number;
+  readonly degrees?: number;
   /** Explicit output and sampling allocation ceilings. */
   readonly limits?: Partial<ModelingLimits>;
 }
@@ -1661,11 +1780,7 @@ export declare interface Section {
   /**
    * Sweeps this filled section using the selected frame policy and degree twist.
    */
-  sweep(
-    this: Section,
-    path: readonly Vector3Tuple[],
-    options?: SweepOptions,
-  ): Solid;
+  sweep(this: Section, path: Path3Input, options?: SweepOptions): Solid;
 }
 
 declare const sectionBrand: unique symbol;
@@ -1674,7 +1789,7 @@ declare const sectionBrand: unique symbol;
 export declare type SectionHullOptions =
   | {
       /** At least three finite millimetre XY points spanning positive area. */
-      readonly points: readonly Vector2Tuple[];
+      readonly points: readonly Vector2Input[];
       /** Point input excludes section input. */
       readonly sections?: never;
     }
@@ -1695,15 +1810,15 @@ export declare interface SectionInspection {
   /** Filled section area in square millimetres. */
   readonly area: number;
   /** Number of extracted outer and hole contours. */
-  readonly contours: number;
+  readonly contourCount: number;
   /** Inclusive maximum coordinates in millimetres. */
   readonly max: Vector2Tuple;
   /** Inclusive minimum coordinates in millimetres. */
   readonly min: Vector2Tuple;
   /** Number of disconnected filled section components. */
-  readonly parts: number;
+  readonly componentCount: number;
   /** Number of native section vertices. */
-  readonly vertices: number;
+  readonly vertexCount: number;
 }
 
 /** Clipper2 join styles accepted by robust region offsets. */
@@ -1777,6 +1892,8 @@ export declare interface Solid {
   mirror(this: Solid, normal: Vector3Input): Solid;
   /** Applies a reusable XYZ placement or canonical row-major matrix. */
   transform(this: Solid, placement: Transform3Input): Solid;
+  /** Copies manufacturing mesh buffers for interchange; requires an active model execution. */
+  toTriangleMesh(this: Solid): TriangleMesh;
   /**
    * Robust difference; an empty cutter array preserves the source.
    */
@@ -1801,8 +1918,8 @@ export declare interface Solid {
     target: Anchor3,
     options?: AttachOptions,
   ): Solid;
-  /** Replaces native tolerance on an immutable copy; zero selects the kernel minimum. */
-  setTolerance(this: Solid, tolerance: number): Solid;
+  /** Returns an immutable copy with this native tolerance; zero selects the kernel minimum. */
+  withTolerance(this: Solid, tolerance: number): Solid;
   /** Projects this solid into a filled XY section. */
   projectSection(this: Solid): Section;
   /** Takes a filled horizontal slice at Z millimetres. */
@@ -1838,8 +1955,8 @@ export declare interface SolidInspection {
   readonly max: Vector3Tuple;
   /** Inclusive minimum coordinates in millimetres. */
   readonly min: Vector3Tuple;
-  /** Number of connected surface shells; inward cavity shells count separately. */
-  readonly parts: number;
+  /** Number of disconnected material components, each retaining enclosed cavities. */
+  readonly componentCount: number;
   /** Enclosed native solid volume in cubic millimetres. */
   readonly volume: number;
   /** Total native surface area in square millimetres. */
@@ -1849,10 +1966,10 @@ export declare interface SolidInspection {
 }
 
 /** Copied surface intersection from a finite directed segment. Distance is in millimetres. */
-export declare interface SolidRayHit {
+export declare interface SolidSegmentHit {
   /** Copied numeric native face identity. */
   readonly faceId: number;
-  /** Distance from the ray origin in millimetres. */
+  /** Distance from the segment origin in millimetres. */
   readonly distance: number;
   /** Intersection position in millimetres. */
   readonly position: Vector3Tuple;
@@ -1874,7 +1991,7 @@ export declare function sphere(options: SphereOptions): Solid;
  * Exactly one radius or diameter, placement, and tessellation for an origin-centered sphere.
  */
 export declare type SphereOptions = CircularPrimitiveOptions &
-  PrimitivePlacement &
+  PrimitiveAttachment &
   (
     | {
         /** Positive radius in millimetres; mutually exclusive with diameter. */
@@ -1960,7 +2077,7 @@ export declare function star(options: StarOptions): Section;
 /**
  * Alternating outer and inner vertices, centered on the XY origin.
  */
-export declare interface StarOptions extends PrimitivePlacement {
+export declare interface StarOptions extends PrimitiveAttachment {
   /** Explicit sampling ceilings, bounded by the host policy. */
   readonly limits?: Partial<GeometrySamplingLimits>;
   /** Positive outer vertex radius in millimetres. */
@@ -1970,13 +2087,13 @@ export declare interface StarOptions extends PrimitivePlacement {
   /** Integer outer point count from three through 50000. */
   readonly points: number;
   /** Initial counterclockwise rotation in degrees; defaults to zero. */
-  readonly rotationDegrees?: number;
+  readonly rotation?: number;
 }
 
 /**
  * Creates a centered-width native Section along a sampled XY path.
  *
- * Shares caps, joins and physical sampling with Geometry's strokePathRegion. Native union
+ * Shares caps, joins and physical sampling with Geometry's strokeRegionData. Native union
  * resolves overlapping stroke primitives. Session resolution and resource ceilings apply;
  * closed paths omit the duplicated seam. Returns an immutable deferred recipe.
  *
@@ -1985,30 +2102,33 @@ export declare interface StarOptions extends PrimitivePlacement {
  * stroke([[0, 0], [20, 0], [20, 10]], { width: 3, join: "round", cap: "round" }).extrude({ height: 2 });
  * ```
  */
-export declare function stroke(path: Path2, options: StrokeOptions): Section;
+export declare function stroke(
+  path: Path2Input,
+  options: StrokeOptions,
+): Section;
+
+/** End-cap treatment for an open stroked path. */
+export declare type StrokeCap = "butt" | "round" | "square";
+
+/** Join treatment where adjacent stroked path segments meet. */
+export declare type StrokeJoin = "bevel" | "miter" | "round";
 
 /** Physical stroke and topology controls shared by pure regions and native Sections. */
 export declare interface StrokeOptions {
   /** Explicit path, circular and expanded-profile allocation ceilings. */
   readonly limits?: Partial<GeometrySamplingLimits>;
-  /** Treat the path as a closed non-duplicated loop. Default: `false`. */
+  /** Raw point closure defaults to false; a Path2 supplies its closure and rejects conflicts. */
   readonly closed?: boolean;
   /** End-cap treatment for an open path. Ignored for closed paths. Default: `butt`. */
-  readonly cap?: StrokePathCap;
+  readonly cap?: StrokeCap;
   /** Corner treatment; miters exceeding SVG's default limit of 4 become bevels. Default: `miter`. */
-  readonly join?: StrokePathJoin;
+  readonly join?: StrokeJoin;
   /** Physical tessellation policy for round caps and joins. */
   readonly resolution?: GeometryResolution;
   /** Positive total stroke width in millimetres, centered on the sampled path. */
   readonly width: number;
 }
 
-/** End-cap treatment for an open stroked path. */
-export declare type StrokePathCap = "butt" | "round" | "square";
-
-/** Join treatment where adjacent stroked path segments meet. */
-export declare type StrokePathJoin = "bevel" | "miter" | "round";
-
 /** Placement of painted SVG geometry after SVG Y-axis inversion. */
 export declare type SvgOrigin = "center" | "document";
 
@@ -2086,7 +2206,7 @@ export declare interface SvgSectionOptions {
  */
 export declare function sweep(
   shape: CorrespondingProfile,
-  path: readonly Vector3Tuple[],
+  path: Path3Input,
   options?: SweepOptions,
 ): Solid;
 
@@ -2094,7 +2214,7 @@ export declare function sweep(
  * 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. */
+  /** Raw point closure defaults to false; a Path3 supplies its closure and rejects conflicts. */
   readonly closed?: boolean;
   /** Explicit output and sampling allocation ceilings. */
   readonly limits?: Partial<ModelingLimits>;
@@ -2103,11 +2223,11 @@ export declare interface SweepOptions {
   /** Physical sampling of nonzero twist; inserted stations retain authored station controls. */
   readonly resolution?: GeometryResolution;
   /** Total additional profile rotation in degrees, with progression selected by twistBy. */
-  readonly twistDegrees?: number;
+  readonly twist?: number;
   /** Twist advances by physical path length (default), or normalized authored station position, including a closed seam gap. */
   readonly twistBy?: "length" | "stations";
   /** Positive uniform/XY scale, or one XY pair per path station. Defaults to one. */
-  readonly scale?: number | Vector2Tuple | readonly Vector2Tuple[];
+  readonly scale?: number | Vector2Input | readonly Vector2Input[];
   /** Corresponding point-index advance at a rotationally equivalent closed seam. */
   readonly seamProfileOffset?: number;
 }
@@ -2120,13 +2240,13 @@ export declare type SweepOrientation =
       /** Minimizes frame rotation by parallel transport. */
       readonly kind: "transport";
       /** Initial profile +X guide, projected perpendicular to the first tangent. */
-      readonly initialNormal?: Vector3Tuple;
+      readonly initialNormal?: Vector3Input;
     }
   | {
       /** Projects one fixed world-space normal at every path station. */
       readonly kind: "fixed-normal";
       /** Directed profile +X guide; must not be parallel to any local tangent. */
-      readonly normal: Vector3Tuple;
+      readonly normal: Vector3Input;
     }
   | {
       /** Uses an explicitly directed normal callback at each original normalized station. */
@@ -2184,9 +2304,9 @@ declare interface ThreadBevelOptions {
  * @example Threaded nut
  * ```ts
  * import { threadedNut } from "@metamesh/modeling";
- * import { createThreadProfile } from "@metamesh/modeling/geometry";
+ * import { threadProfile } from "@metamesh/modeling/geometry";
  *
- * const profile = createThreadProfile({ kind: "triangular", pitch: 1.75 });
+ * const profile = threadProfile({ kind: "triangular", pitch: 1.75 });
  * threadedNut({ nominalMajorDiameter: 12, thickness: 8, width: 20, shape: "hex", profile, fit: "normal" });
  * ```
  */
@@ -2248,9 +2368,9 @@ export declare type ThreadedNutShape = "hex" | "round" | "square";
  * @example Threaded rod
  * ```ts
  * import { threadedRod } from "@metamesh/modeling";
- * import { createThreadProfile } from "@metamesh/modeling/geometry";
+ * import { threadProfile } from "@metamesh/modeling/geometry";
  *
- * const profile = createThreadProfile({ kind: "triangular", pitch: 1.75 });
+ * const profile = threadProfile({ kind: "triangular", pitch: 1.75 });
  * threadedRod({ nominalMajorDiameter: 12, length: 24, profile, fit: "normal" });
  * ```
  */
@@ -2376,7 +2496,7 @@ export declare function torus(options: TorusOptions): Solid;
 /**
  * Dimensions and independent ring/profile tessellation for a torus around the Z axis.
  */
-export declare interface TorusOptions extends PrimitivePlacement {
+export declare interface TorusOptions extends PrimitiveAttachment {
   /** Explicit sampling ceilings, bounded by the host policy. */
   readonly limits?: Partial<GeometrySamplingLimits>;
   /** Radius from the Z axis to the profile center, in millimetres; greater than `minorRadius`. */
@@ -2391,9 +2511,6 @@ export declare interface TorusOptions extends PrimitivePlacement {
   readonly resolution?: GeometryResolution;
 }
 
-/** Copies a handle to manufacturing mesh buffers. */
-export declare function toTriangleMesh(solid: Solid): TriangleMesh;
-
 /** Immutable reusable XY placement. Methods apply in written order; angles are degrees. */
 export declare interface Transform2 {
   /** Applies a translation in model units after this placement. */
@@ -2532,10 +2649,11 @@ declare interface TrapezoidalThreadProfileSpec extends ThreadProfileBaseSpec {
    */
   readonly depth?: number;
   /**
-   * Included flank angle in degrees. Use `90` for printable 45-degree slopes.
+   * Full angle between the flanks in degrees, from `0` inclusive to `180` exclusive.
+   * Each flank uses half this angle from the radial direction; `90` gives 45-degree slopes.
    * @defaultValue `30`
    */
-  readonly threadAngle?: number;
+  readonly includedAngle?: number;
 }
 
 /**
@@ -2552,7 +2670,7 @@ export declare interface TriangleMesh {
  * 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. */
+  /** Number of referenced edge-connected boundary shells when `includeTopology` is requested; cavities count separately. */
   readonly connectedComponentCount?: number;
   /** Number of distinct indexed undirected edges when `includeTopology` is requested. */
   readonly edgeCount?: number;
@@ -2606,7 +2724,7 @@ export declare function tube(options: TubeOptions): Solid;
  * Dimensions, placement, and tessellation for a hollow Z-axis tube.
  */
 export declare interface TubeOptions
-  extends CircularPrimitiveOptions, PrimitivePlacement {
+  extends CircularPrimitiveOptions, PrimitiveAttachment {
   /**
    * Centers the tube on the Z origin when `true`; otherwise its bottom is at `Z = 0`.
    * @defaultValue `true`