@metamesh/modeling 0.15.0 → 0.16.0

package/dist/api/index.d.ts

@@ -30,11 +30,11 @@ export declare function anchor(shape: Solid | Section, name: string): Anchor3;
  */
 export declare interface Anchor3 {
   /** Unit outward normal used as the anchor's local +Z direction. */
-  readonly direction: Vector3Tuple;
+  readonly direction: Vector3Data;
   /** World-space attachment position. */
-  readonly position: Vector3Tuple;
+  readonly position: Vector3Data;
   /** Roll guide projected into the plane perpendicular to `direction`. */
-  readonly up: Vector3Tuple;
+  readonly up: Vector3Data;
 }
 
 /** Options controlling how one anchor is attached to another. */
@@ -49,22 +49,72 @@ export declare interface AttachOptions {
   readonly tolerance?: GeometryToleranceOptions;
 }
 
-/** Axis-aligned bounds in two-dimensional model space. */
-export declare interface Bounds2 {
+/** Immutable finite XY bounds in millimetres, with tuple coordinates for data interoperability. */
+export declare interface Bounds2 extends Bounds2Data {
+  /** Returns nonnegative X/Y dimensions in millimetres, including zero extents. */
+  size(): Vector2;
+  /** Returns the midpoint in millimetres. */
+  center(): Vector2;
+  /** Tests positioned XY containment, including touching boundaries. */
+  containsBounds(other: Bounds2Input): boolean;
+  /** Returns this value's frozen plain record; repeated calls do not allocate. */
+  toData(): Bounds2Data;
+}
+
+/**
+ * Snapshots finite ordered XY bounds in millimetres as an immutable fluent value.
+ *
+ * Zero extents are valid. Invalid dimensions, nonfinite coordinates, reversed bounds and
+ * overflowing extents throw `INVALID_ARGUMENT` GeometryError. Use `toData()` for plain records.
+ * Compiled Generator packages passing these values to host recipes or computed data require
+ * runtime 8.0.0 or newer in major 8.
+ */
+export declare function bounds2(input: Bounds2Input): Bounds2;
+
+/** Plain axis-aligned XY bounds for interchange; use bounds2 for immutable measurement methods. */
+export declare interface Bounds2Data {
   /** Inclusive maximum X/Y coordinates. */
-  readonly max: Vector2Tuple;
+  readonly max: Vector2Data;
   /** Inclusive minimum X/Y coordinates. */
-  readonly min: Vector2Tuple;
+  readonly min: Vector2Data;
+}
+
+/** An immutable XY bounds value or its plain min/max representation. */
+export declare type Bounds2Input = Bounds2 | Bounds2Data;
+
+/** Immutable finite XYZ bounds in millimetres, with tuple coordinates for data interoperability. */
+export declare interface Bounds3 extends Bounds3Data {
+  /** Returns nonnegative X/Y/Z dimensions in millimetres, including zero extents. */
+  size(): Vector3;
+  /** Returns the midpoint in millimetres. */
+  center(): Vector3;
+  /** Tests positioned XYZ containment, including touching boundaries. */
+  containsBounds(other: Bounds3Input): boolean;
+  /** Returns this value's frozen plain record; repeated calls do not allocate. */
+  toData(): Bounds3Data;
 }
 
-/** Axis-aligned bounds in three-dimensional model space. */
-export declare interface Bounds3 {
+/**
+ * Snapshots finite ordered XYZ bounds in millimetres as an immutable fluent value.
+ *
+ * Zero extents are valid. Invalid dimensions, nonfinite coordinates, reversed bounds and
+ * overflowing extents throw `INVALID_ARGUMENT` GeometryError. Use `toData()` for plain records.
+ * Compiled Generator packages passing these values to host recipes or computed data require
+ * runtime 8.0.0 or newer in major 8.
+ */
+export declare function bounds3(input: Bounds3Input): Bounds3;
+
+/** Plain axis-aligned XYZ bounds for interchange; use bounds3 for immutable measurement methods. */
+export declare interface Bounds3Data {
   /** Inclusive maximum X/Y/Z coordinates. */
-  readonly max: Vector3Tuple;
+  readonly max: Vector3Data;
   /** Inclusive minimum X/Y/Z coordinates. */
-  readonly min: Vector3Tuple;
+  readonly min: Vector3Data;
 }
 
+/** An immutable XYZ bounds value or its plain min/max representation. */
+export declare type Bounds3Input = Bounds3 | Bounds3Data;
+
 /**
  * Axis-aligned box with uniform or disjoint named edge/group treatments.
  *
@@ -110,7 +160,7 @@ export declare interface BoxOptions extends PrimitiveAttachment {
    */
   readonly center?: boolean;
   /** Positive uniform size or explicit `[X, Y, Z]` extents in millimetres. */
-  readonly size: number | Vector3Tuple;
+  readonly size: number | Vector3Data;
   /** Uniform treatment or independent disjoint nominal edge/group treatments. */
   readonly treatment?: EdgeTreatment | BoxEdgeTreatments;
 }
@@ -246,12 +296,16 @@ declare const computedBrand: unique symbol;
 export declare type ComputedValue<T> = T | Computed<T>;
 
 /**
- * A closed two-dimensional boundary whose first point is not repeated at the end.
+ * A sampled closed two-dimensional boundary whose first point is not repeated at the end.
  *
  * Polygon exteriors are counter-clockwise and holes are clockwise. Algorithms
  * may reject duplicate adjacent points or fewer than three effective vertices.
+ * Use PolygonData to assign an exterior and its holes, or ProfileContour2 for identified curve spans.
+ *
+ * @see {@link PolygonData}
+ * @see [ProfileContour2](/docs/reference/geometry/ProfileContour2)
  */
-export declare type Contour = readonly Vector2Tuple[];
+export declare type Contour = readonly Vector2Data[];
 
 /** One sampled component retaining contour identities and logical point correspondence. */
 export declare interface CorrespondingComponent {
@@ -307,7 +361,7 @@ declare interface CustomThreadProfileSpec extends ThreadProfileBaseSpec {
    * Open path spanning exactly `[-pitch/2, pitch/2]`, with both endpoints on the minor envelope,
    * one connected ridge, one contiguous crest, and radial zero at the major envelope.
    */
-  readonly points: readonly Vector2Tuple[];
+  readonly points: readonly Vector2Data[];
 }
 
 /**
@@ -404,13 +458,13 @@ export declare type EllipseContourOptions = CircularPrimitiveOptions &
   (
     | {
         /** Positive XY radii in millimetres; mutually exclusive with size. */
-        readonly radius: Vector2Tuple;
+        readonly radius: Vector2Data;
         /** Full XY extents are unavailable when radius is supplied. */
         readonly size?: never;
       }
     | {
         /** Positive full XY extents in millimetres; mutually exclusive with radius. */
-        readonly size: Vector2Tuple;
+        readonly size: Vector2Data;
         /** XY radii are unavailable when size is supplied. */
         readonly radius?: never;
       }
@@ -482,7 +536,7 @@ export declare interface FinalizedModel {
   /** Ordered finalized manufacturing parts with copied transferable arrays. */
   readonly parts: readonly FinalizedPart[];
   /** Axis-aligned XYZ bounds in millimetres. */
-  readonly bounds: Bounds3;
+  readonly bounds: Bounds3Data;
   /** Aggregate counts, unique backing storage, volume, and execution timings. */
   readonly stats: {
     /** Number of declared output parts, including repeated geometry instances. */
@@ -517,13 +571,13 @@ export declare interface FinalizedPart extends TriangleMesh {
 /** A right-handed orthonormal coordinate frame expressed in world coordinates. */
 export declare interface Frame3 {
   /** World-space origin of the local frame. */
-  readonly origin: Vector3Tuple;
+  readonly origin: Vector3Data;
   /** Unit vector defining the local +X axis. */
-  readonly xAxis: Vector3Tuple;
+  readonly xAxis: Vector3Data;
   /** Unit vector defining the local +Y axis. */
-  readonly yAxis: Vector3Tuple;
+  readonly yAxis: Vector3Data;
   /** Unit vector defining the local +Z axis. */
-  readonly zAxis: Vector3Tuple;
+  readonly zAxis: Vector3Data;
 }
 
 /**
@@ -669,22 +723,23 @@ export declare type GridPatternOptions<Dimension extends 2 | 3 = 3> = {
 } & (
   | {
       /** Positive integer counts on X and Y. */
-      readonly count: Vector2Tuple;
+      readonly count: Vector2Data;
       /** Signed millimetres between adjacent copies on X and Y. */
-      readonly spacing: Vector2Tuple;
+      readonly spacing: Vector2Data;
     }
   | (Dimension extends 3
       ? {
           /** Positive integer counts on X, Y and Z. */
-          readonly count: Vector3Tuple;
+          readonly count: Vector3Data;
           /** Signed millimetres between adjacent copies on X, Y and Z. */
-          readonly spacing: Vector3Tuple;
+          readonly spacing: Vector3Data;
         }
       : never)
 );
 
 /**
  * Closed rectilinear top above a flat base, with uniform or explicit XY coordinates.
+ *
  * Samples each grid height once; center-error triangulation also samples each cell centre.
  * The retained callback must capture independent immutable inputs, not live session readers or parameters.
  *
@@ -709,7 +764,7 @@ export declare function heightfield(options: HeightfieldOptions): Solid;
  */
 export declare type HeightfieldOptions = {
   /** Absolute top Z at the supplied XY point. Every sample must be above baseZ. */
-  readonly height: (point: Vector2Tuple) => number;
+  readonly height: (point: Vector2Data) => number;
   /** Flat bottom Z. Defaults to zero. */
   readonly baseZ?: number;
   /**
@@ -722,11 +777,11 @@ export declare type HeightfieldOptions = {
 } & (
   | {
       /** Positive XY footprint for uniform sampling. */
-      readonly size: Vector2Tuple;
+      readonly size: Vector2Data;
       /** 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?: Vector2Tuple;
+      readonly origin?: Vector2Data;
       /** Explicit coordinates cannot be combined with uniform sampling. */
       readonly coordinates?: never;
     }
@@ -777,7 +832,7 @@ export declare interface HelicalThreadRidgeMeshOptions {
   readonly tolerance?: GeometryToleranceOptions;
 }
 
-/** Conservative allocation facts resolved before constructing a direct thread solid mesh. */
+/** Selected sampling counts and conservative allocation estimates, before thread mesh construction. */
 export declare interface HelicalThreadSolidMeshPreflight {
   /** Uniform axial intervals required only by a requested physical segment-length limit. */
   readonly axialIntervals: number;
@@ -884,9 +939,9 @@ export declare function implicit(options: ImplicitOptions): Solid;
 /** Positive-inside sampling, bounded to 4M native BCC grid slots and 8M field calls. */
 export declare interface ImplicitOptions {
   /** Positive-inside scalar field evaluated at finite XYZ points. */
-  readonly field: (point: Vector3Tuple) => number;
+  readonly field: (point: Vector3Data) => number;
   /** Axis-aligned XYZ bounds in millimetres. */
-  readonly bounds: Bounds3;
+  readonly bounds: Bounds3Data;
   /** Positive sampling edge length in millimetres. */
   readonly edgeLength: number;
   /** Field isosurface value; defaults to zero. */
@@ -974,6 +1029,122 @@ export declare function intersect(sections: readonly Section[]): Section;
  */
 export declare function isEmpty(shape: Solid | Section): boolean;
 
+/** Portable local geometry; consumers own plates, holes, part declarations, and final placement. */
+export declare interface KnuckleHinge {
+  /** Alternating A intervals, including the integral shaft in print-in-place and lift-off modes. */
+  readonly halfA: Solid;
+  /** Alternating B intervals with a face-sized running bore. */
+  readonly halfB: Solid;
+  /** Centered +X pin axis with +Z roll guide; opening and lift-off withdrawal are caller transforms. */
+  readonly axis: Anchor3;
+}
+
+/**
+ * Declares separate knuckle-joint halves along the centered +X pin axis, in millimetres.
+ *
+ * A starts at negative X. Attach independent webs or use barrels only; caller geometry connects
+ * otherwise disconnected intervals. Returns portable recipes without initializing the engine.
+ * Unspecified resolution inherits the evaluating session. Axis direction is +X with +Z up.
+ *
+ * Barrel end chamfers affect outer rims only; webs have square edges. Consumers own plates, screw holes,
+ * pin retention, fit policy, and part placement. Added mounting material must preserve the bores.
+ * No opening range or collision freedom is implied for arbitrary caller attachments.
+ * Compiled Generator packages using this operation require runtime 8.0.0 or newer in major 8.
+ *
+ * @example Integral-pin hinge with two mounting webs
+ * ```ts
+ * const joint = knuckleHinge({
+ *   mode: "print-in-place", length: 30, knuckleCount: 3,
+ *   barrelDiameter: 10, pinDiameter: 3, radialClearance: 0.3, axialGap: 0.4,
+ *   halfA: { web: { direction: "positive-y", reach: 8, zMin: -5, thickness: 2 } },
+ *   halfB: { web: { direction: "negative-y", reach: 8, zMin: -5, thickness: 2 } },
+ * });
+ * ```
+ */
+export declare function knuckleHinge(
+  options: KnuckleHingeOptions,
+): KnuckleHinge;
+
+/** Shared knuckle-joint dimensions in millimetres, independent of mounting geometry. */
+export declare interface KnuckleHingeBaseSpec {
+  /** Total extent along the +X pin axis, centered at the origin. */
+  readonly length: number;
+  /** Number of equal alternating intervals, starting with half A. */
+  readonly knuckleCount: number;
+  /** Outside vertex-sized barrel diameter. */
+  readonly barrelDiameter: number;
+  /** Vertex-sized shaft diameter, including an externally supplied shaft. */
+  readonly pinDiameter: number;
+  /** Nonnegative per-side radial allowance; bores circumscribe this running envelope. */
+  readonly radialClearance: number;
+  /** Nonnegative total air gap between each neighboring pair of knuckle ends. */
+  readonly axialGap: number;
+}
+
+/** Optional mounting and outer-rim treatment for one knuckle owner. */
+export declare interface KnuckleHingeHalfOptions {
+  /** Omit for barrels only. Each interval receives one web; disconnected intervals need caller geometry. */
+  readonly web?: KnuckleHingeWeb;
+  /** 45° setback in millimetres at both ends of every barrel; defaults to 0. */
+  readonly barrelChamfer?: number;
+}
+
+/** Joint declaration with independent attachments; unspecified sampling inherits the evaluating host. */
+export declare type KnuckleHingeOptions = KnuckleHingeSpec &
+  KnuckleHingeSamplingOptions & {
+    /** Optional attachment and rim treatment for A, which owns an integral pin when present. */
+    readonly halfA?: KnuckleHingeHalfOptions;
+    /** Optional attachment and rim treatment for B, which always carries a running bore. */
+    readonly halfB?: KnuckleHingeHalfOptions;
+  };
+
+/** Shared circular sampling for barrels, shafts, and bores. */
+export declare interface KnuckleHingeSamplingOptions {
+  /** Exact full-circle count, divisible by four and at least four; overrides adaptive sampling. */
+  readonly segments?: number;
+  /** Physical tessellation policy. Exact circular counts must also be divisible by four. */
+  readonly resolution?: GeometryResolution;
+  /** Explicit allocation ceilings; defaults to the pure geometry sampling limits. */
+  readonly limits?: Partial<GeometrySamplingLimits>;
+}
+
+/**
+ * Knuckle-joint construction modes and interval ownership.
+ *
+ * Print-in-place requires an odd count of at least three: A owns both
+ * end anchors and the entire shaft. Inserted-pin bores both halves and supplies no shaft.
+ * Lift-off requires exactly two intervals; A's integral pin enters B without a far anchor.
+ */
+export declare type KnuckleHingeSpec = KnuckleHingeBaseSpec &
+  (
+    | {
+        /** Captive integral shaft or bores for an externally supplied pin. */
+        readonly mode: "print-in-place" | "inserted-pin";
+        /** Engagement applies only to lift-off construction. */
+        readonly pinEngagement?: never;
+      }
+    | {
+        /** Detachable socket on a finite integral pin. */
+        readonly mode: "lift-off";
+        /** Lift-off has one fixed interval and one removable interval. */
+        readonly knuckleCount: 2;
+        /** Positive axial engagement into B, no greater than its knuckle length. */
+        readonly pinEngagement: number;
+      }
+  );
+
+/** Rectangular connection from the axis into a caller-owned mounting body, in millimetres. */
+export declare interface KnuckleHingeWeb {
+  /** Direction from the pin axis; independently chosen for each half. */
+  readonly direction: "positive-y" | "negative-y";
+  /** Positive distance from the axis to the web's far edge. Overlap into the mounting body. */
+  readonly reach: number;
+  /** Lower-face Z coordinate in the pin-centered frame, in millimetres. Must overlap the barrel's interior. */
+  readonly zMin: number;
+  /** Positive thickness along +Z. Webs have square edges and span their own barrel intervals. */
+  readonly thickness: number;
+}
+
 /**
  * Repeats one solid along a normalized direction.
  *
@@ -1173,11 +1344,11 @@ export declare interface Path2 {
   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;
+  /** Returns complete deeply frozen path data, including dimension and closure. Repeated calls do not allocate. */
+  toData(): 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. */
+  /** Immutable 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>;
@@ -1191,19 +1362,29 @@ export declare interface 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.
+ *
+ * Use `toData()` for a frozen record that restores coordinates, closure, and dimension together.
  */
 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[];
+/** Complete plain XY path representation, including topology and empty-path dimensional identity. */
+export declare interface Path2Data {
+  /** Coordinate dimension, retained even when points is empty. */
+  readonly dimension: 2;
+  /** Frozen or caller-owned XY coordinates; closed paths omit a duplicated seam. */
+  readonly points: readonly Vector2Data[];
+  /** Whether traversal includes the last-to-first edge. */
+  readonly closed: boolean;
+}
 
-/** An immutable XY sampled path or a collection of XY tuples and fluent vectors. */
-export declare type Path2Input = Path2 | readonly Vector2Input[];
+/** A matching path value, complete plain path data, or a collection of vectors. */
+export declare type Path2Input = Path2 | Path2Data | readonly Vector2Input[];
 
 /** Immutable directed XYZ polyline; it represents sampled edges, not an analytic curve. */
 export declare interface Path3 {
@@ -1211,11 +1392,11 @@ export declare interface Path3 {
   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;
+  /** Returns complete deeply frozen path data, including dimension and closure. Repeated calls do not allocate. */
+  toData(): 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. */
+  /** Immutable 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>;
@@ -1230,16 +1411,25 @@ export declare interface 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.
+ *
+ * Use `toData()` for a frozen record that restores coordinates, closure, and dimension together.
+ *
+ * @see {@link path2} for shared construction rules.
  */
 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[];
+/** Complete plain XYZ path representation, including topology and empty-path dimensional identity. */
+export declare interface Path3Data {
+  /** Coordinate dimension, retained even when points is empty. */
+  readonly dimension: 3;
+  /** Frozen or caller-owned XYZ coordinates; closed paths omit a duplicated seam. */
+  readonly points: readonly Vector3Data[];
+  /** Whether traversal includes the last-to-first edge. */
+  readonly closed: boolean;
+}
 
-/** An immutable XYZ sampled path or a collection of XYZ tuples and fluent vectors. */
-export declare type Path3Input = Path3 | readonly Vector3Input[];
+/** A matching path value, complete plain path data, or a collection of vectors. */
+export declare type Path3Input = Path3 | Path3Data | 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> {
@@ -1261,7 +1451,7 @@ export declare interface PathLocation<Point extends Vector2 | Vector3> {
  * @returns A finite guide vector that is not parallel to the local path tangent.
  */
 export declare type PathNormalGuide = (
-  point: Vector3Tuple,
+  point: Vector3Data,
   index: number,
 ) => Vector3Input;
 
@@ -1341,6 +1531,7 @@ export declare interface PlaneOptions {
 
 /**
  * Fills one closed millimetre XY outline, explicit outer/hole topology, or compound contours.
+ *
  * Closing edges are implicit. Compound contours use nonzero fill unless selected otherwise.
  * Explicit topology must be simple and disjoint; compound winding may resolve overlaps.
  *
@@ -1352,11 +1543,14 @@ export declare interface PlaneOptions {
 export declare function polygon(input: Path2Input | PolygonOptions): Section;
 
 /**
- * One bounded two-dimensional polygon.
+ * One filled two-dimensional polygon with an exterior and optional holes.
  *
  * `outer` is counter-clockwise and each hole is clockwise. Boundary arrays omit
  * their duplicated closing point. Holes must lie inside `outer` and must not
  * intersect each other or the exterior.
+ *
+ * @see {@link Contour}
+ * @see {@link RegionData}
  */
 export declare interface PolygonData {
   /** Clockwise interior boundaries, each omitting its duplicated closing point. */
@@ -1404,17 +1598,41 @@ export declare type PolygonOptions =
       readonly fillRule?: never;
     };
 
-/** Internal-thread facts using host resolution and limits; requires active synchronous model execution. */
+/**
+ * Checks compensated cutter dimensions and conservative mesh estimates against host output limits.
+ *
+ * Requires active synchronous model execution and uses its resolution and limits. Estimates include
+ * the one-pitch extension beyond each requested face, without mesh buffers or native objects.
+ * Mesh validity, native construction, and aggregate output limits are checked later.
+ *
+ * @see {@link internalThreadCutter}
+ */
 export declare function preflightInternalThreadCutter(
   options: InternalThreadCutterOptions,
 ): HelicalThreadSolidMeshPreflight;
 
-/** Nut/cutter facts using host resolution and limits; requires active synchronous model execution. */
+/**
+ * Checks nut dimensions, chamfers, end-face wall, and the extended compensated cutter's allocation plan.
+ *
+ * Requires active synchronous model execution and uses its resolution and limits, without mesh
+ * buffers or native objects. Returned thread estimates cover the cutter, excluding the body and
+ * Boolean result. Mesh validity, native construction, and aggregate output limits are checked later.
+ *
+ * @see {@link threadedNut}
+ */
 export declare function preflightThreadedNut(
   options: ThreadedNutOptions,
 ): ThreadedNutPreflight;
 
-/** External-thread facts using host resolution and limits; requires active synchronous model execution. */
+/**
+ * Checks compensated rod dimensions and conservative mesh estimates against host output limits.
+ *
+ * Requires active synchronous model execution and uses its resolution and limits. Returns selected
+ * sampling and conservative row/triangle estimates without mesh buffers or native objects.
+ * Mesh validity, native construction, and aggregate output limits are checked later.
+ *
+ * @see {@link threadedRod}
+ */
 export declare function preflightThreadedRod(
   options: ThreadedRodOptions,
 ): HelicalThreadSolidMeshPreflight;
@@ -1454,7 +1672,13 @@ export declare interface PrintableThreadFitPolicy {
   readonly maleRadialInset: number;
 }
 
-/** An explicit component/contour/span topology, before shared family sampling. */
+/**
+ * An explicit component/contour/span topology, before shared family sampling with matchProfiles.
+ * Component, contour and span identities establish correspondence across a loft or sweep family.
+ *
+ * @see {@link CorrespondingProfile}
+ * @see {@link matchProfiles}
+ */
 export declare interface Profile {
   /** Ordered components with explicit contour identities. */
   readonly components: readonly ProfileComponent2[];
@@ -1470,7 +1694,13 @@ export declare interface ProfileComponent2 {
   readonly holes: readonly ProfileContour2[];
 }
 
-/** Ordered, closed spans. Outer winding is CCW and hole winding is CW. */
+/**
+ * An identified closed boundary of curve spans, before shared family sampling.
+ * Outer winding is CCW and hole winding is CW. matchProfiles retains span identities in sampled contours.
+ *
+ * @see {@link Contour} for sampled point coordinates.
+ * @see {@link CorrespondingContour} for sampled coordinates with correspondence metadata.
+ */
 export declare interface ProfileContour2 {
   /** Stable canonical lowercase identity; unique within the containing topology or output. */
   readonly id: string;
@@ -1487,7 +1717,7 @@ export declare interface ProfiledEdgeTreatment {
    * First coordinates decrease and second coordinates increase. Cylinder/extrusion ends use
    * cap inset first, side setback second; planar corners use incoming then outgoing edges.
    */
-  readonly profile: readonly Vector2Tuple[];
+  readonly profile: readonly Vector2Data[];
 }
 
 /** An identified line, circular arc, or cubic Bézier between corresponding landmarks. */
@@ -1503,15 +1733,15 @@ export declare type ProfileSpan2 = {
       /** Selects a straight span. */
       readonly kind: "line";
       /** Start point in millimetres. */
-      readonly start: Vector2Tuple;
+      readonly start: Vector2Data;
       /** End point in millimetres. */
-      readonly end: Vector2Tuple;
+      readonly end: Vector2Data;
     }
   | {
       /** Selects the geometric curve or span family. */
       readonly kind: "arc";
       /** Center point in millimetres. */
-      readonly center: Vector2Tuple;
+      readonly center: Vector2Data;
       /** Circular radius in millimetres. */
       readonly radius: number;
       /** Initial counterclockwise angle in degrees. */
@@ -1523,13 +1753,13 @@ export declare type ProfileSpan2 = {
       /** Selects a cubic Bézier span with the same coordinates as CubicBezierCurve2. */
       readonly kind: "cubic";
       /** Start point in millimetres. */
-      readonly start: Vector2Tuple;
+      readonly start: Vector2Data;
       /** First control point in millimetres. */
-      readonly control1: Vector2Tuple;
+      readonly control1: Vector2Data;
       /** Second control point in millimetres. */
-      readonly control2: Vector2Tuple;
+      readonly control2: Vector2Data;
       /** End point in millimetres. */
-      readonly end: Vector2Tuple;
+      readonly end: Vector2Data;
     }
 );
 
@@ -1589,6 +1819,9 @@ export declare interface RadialSizingOptions {
 /**
  * Filled rectangular section with uniform or independently treated corners.
  *
+ * Use [rectangleContour](/docs/reference/geometry/rectangleContour) for sampled boundary coordinates,
+ * or [rectangleProfile](/docs/reference/geometry/rectangleProfile) to retain identified loft landmarks.
+ *
  * @example Round the corners
  * ```ts
  * rectangle({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
@@ -1601,7 +1834,7 @@ export declare function rectangle(options: RectangleOptions): Section;
  */
 export declare interface RectangleContourOptions {
   /** Positive uniform size or explicit XY extents in millimetres. */
-  readonly size: number | Vector2Tuple;
+  readonly size: number | Vector2Data;
   /** Center on XY; otherwise the minimum corner is the origin. Defaults to true. */
   readonly center?: boolean;
   /** Uniform treatment or four corner treatments. Exact round segments describe a complete circle and must divide by four. */
@@ -1632,7 +1865,12 @@ export declare type RectangleCornerTreatments = readonly [
 export declare interface RectangleOptions
   extends RectangleContourOptions, PrimitiveAttachment {}
 
-/** A two-dimensional region represented by disjoint filled polygons. */
+/**
+ * A two-dimensional region represented by disjoint filled polygons.
+ * Each PolygonData owns one exterior and its holes; an empty region contains no material.
+ *
+ * @see {@link PolygonData}
+ */
 export declare type RegionData = readonly PolygonData[];
 
 /**
@@ -1705,7 +1943,9 @@ export declare interface RoundedEdgeTreatment extends CircularPrimitiveOptions {
 }
 
 /**
- * Immutable deferred filled XY section recipe. Construction and composition require no engine.
+ * Immutable deferred filled XY section recipe.
+ *
+ * Construction and composition require no engine.
  * Ordinary recipes may be reused across sessions regardless of where constructed.
  * Observed components and recipes using them can only be evaluated in their originating session.
  * Methods leave the source unchanged; observations require a synchronous model execution.
@@ -1812,9 +2052,9 @@ export declare interface SectionInspection {
   /** Number of extracted outer and hole contours. */
   readonly contourCount: number;
   /** Inclusive maximum coordinates in millimetres. */
-  readonly max: Vector2Tuple;
+  readonly max: Vector2Data;
   /** Inclusive minimum coordinates in millimetres. */
-  readonly min: Vector2Tuple;
+  readonly min: Vector2Data;
   /** Number of disconnected filled section components. */
   readonly componentCount: number;
   /** Number of native section vertices. */
@@ -1851,7 +2091,9 @@ export declare interface SmoothEdgeTreatment {
 }
 
 /**
- * Immutable deferred solid recipe. Construction and composition require no engine.
+ * Immutable deferred solid recipe.
+ *
+ * Construction and composition require no engine.
  * Ordinary recipes may be reused across sessions regardless of where constructed.
  * Explicit resolution settings are captured; unspecified settings inherit the evaluating host's defaults.
  * Observed components and recipes using them can only be evaluated in their originating session.
@@ -1952,9 +2194,9 @@ export declare interface SolidInspection {
   /** Whether this native solid contains no material. */
   readonly isEmpty: boolean;
   /** Inclusive maximum coordinates in millimetres. */
-  readonly max: Vector3Tuple;
+  readonly max: Vector3Data;
   /** Inclusive minimum coordinates in millimetres. */
-  readonly min: Vector3Tuple;
+  readonly min: Vector3Data;
   /** Number of disconnected material components, each retaining enclosed cavities. */
   readonly componentCount: number;
   /** Enclosed native solid volume in cubic millimetres. */
@@ -1972,9 +2214,9 @@ export declare interface SolidSegmentHit {
   /** Distance from the segment origin in millimetres. */
   readonly distance: number;
   /** Intersection position in millimetres. */
-  readonly position: Vector3Tuple;
+  readonly position: Vector3Data;
   /** Outward unit surface normal at the intersection. */
-  readonly normal: Vector3Tuple;
+  readonly normal: Vector3Data;
 }
 
 /**
@@ -2339,7 +2581,7 @@ export declare interface ThreadedNutOptions extends Omit<
   readonly width: number;
 }
 
-/** Allocation-free body, cutter, and end-face facts resolved for a threaded nut. */
+/** Resolved body and end-face dimensions plus conservative allocation estimates for the thread cutter. */
 export declare interface ThreadedNutPreflight {
   /** Polygon segment count used by the nut body. */
   readonly bodySegments: number;
@@ -2351,7 +2593,7 @@ export declare interface ThreadedNutPreflight {
   readonly minimumBodyFaceInradius: number;
   /** Smallest radial wall left between the body and cutter at either requested face. */
   readonly minimumFaceWall: number;
-  /** Conservative allocation facts for the exact extended internal-thread cutter mesh. */
+  /** Conservative allocation estimates for the extended cutter; excludes the body and Boolean result. */
   readonly thread: HelicalThreadSolidMeshPreflight;
   /** Start-aligned circular facet count used by the compensated thread cutter. */
   readonly threadCircularSegments: number;
@@ -2453,7 +2695,7 @@ export declare interface ThreadProfile {
   /** Adjacent axial thread spacing in millimetres. */
   readonly pitch: number;
   /** Immutable open `[axial, radial]` path spanning one pitch. */
-  readonly points: readonly Vector2Tuple[];
+  readonly points: readonly Vector2Data[];
   /** Axial width of the flat at the minor envelope. */
   readonly rootFlatWidth: number;
 }
@@ -2530,32 +2772,33 @@ export declare interface Transform2 {
   /** Applies the inverse transpose and normalizes. Ignores translation; rejects zero normals. */
   applyNormal(normal: Vector2Input): Vector2;
   /** Returns the frozen canonical row-major 3x3 matrix for interchange. */
-  toMatrix(): Transform2Matrix;
+  toData(): Transform2Data;
   /** Embeds this placement in XYZ, leaving Z unchanged, for solids and 3D paths. */
   to3D(): Transform3;
 }
 
 /**
- * Creates an immutable XY transform, identity by default. Matrices are copied and validated.
+ * Creates an immutable XY transform, identity by default.
+ *
+ * Values and data are copied and validated.
  * Pass it directly to Section.transform() and planar data helpers; to3D() explicitly crosses into XYZ.
  * Zero scales and singular matrices throw GeometryError; negative scales reflect.
  *
+ * Use `toData()` for frozen matrix interchange.
+ *
  * @example
  * ```ts
  * const placement = transform2().rotate(90).translate([10, 0]);
- * placement.applyPoint([1, 0]).toArray(); // approximately [10, 1]
+ * placement.applyPoint([1, 0]).toData(); // approximately [10, 1]
  * ```
  */
-export declare function transform2(matrix?: Transform2Matrix): Transform2;
-
-/** An immutable XY transform or its canonical row-major matrix for interchange. */
-export declare type Transform2Input = Transform2 | Transform2Matrix;
+export declare function transform2(input?: Transform2Input): Transform2;
 
 /**
  * A row-major affine 3x3 XY matrix applied to column vectors.
  * Translation occupies indices 2 and 5; the final row is `[0, 0, 1]`.
  */
-export declare type Transform2Matrix = readonly [
+export declare type Transform2Data = readonly [
   m00: number,
   m01: number,
   m02: number,
@@ -2567,6 +2810,9 @@ export declare type Transform2Matrix = readonly [
   m22: number,
 ];
 
+/** An immutable XY transform or its canonical row-major matrix for interchange. */
+export declare type Transform2Input = Transform2 | Transform2Data;
+
 /** Immutable reusable XYZ placement. Methods apply in written order; angles are degrees. */
 export declare interface Transform3 {
   /** Applies a translation in model units after this placement. */
@@ -2592,27 +2838,29 @@ export declare interface Transform3 {
   /** Applies the inverse transpose and normalizes. Ignores translation; rejects zero normals. */
   applyNormal(normal: Vector3Input): Vector3;
   /** Returns the frozen canonical row-major 4x4 matrix for interchange. */
-  toMatrix(): Transform3Matrix;
+  toData(): Transform3Data;
   /** Restricts to XY; throws GeometryError for a plane change or singular XY restriction. */
   to2D(): Transform2;
 }
 
 /**
- * Creates an immutable XYZ transform, identity by default. Matrices are copied and validated.
+ * Creates an immutable XYZ transform, identity by default.
+ *
+ * Values and data are copied and validated.
  * Calls apply in written order; rotations use degrees and pivots use current world coordinates.
  * Zero scales, singular matrices, nonfinite inputs and zero rotation axes throw GeometryError.
  * Use frameTransform3(frame) as the input for existing orthonormal frame placement.
  *
+ * Use `toData()` for frozen matrix interchange.
+ * [composeTransform3](/docs/reference/geometry/composeTransform3) takes matrices in after, before order.
+ *
  * @example
  * ```ts
  * const placement = transform3().rotate([0, 0, 90]).translate([10, 0, 0]);
- * placement.applyPoint([1, 0, 0]).toArray(); // approximately [10, 1, 0]
+ * placement.applyPoint([1, 0, 0]).toData(); // approximately [10, 1, 0]
  * ```
  */
-export declare function transform3(matrix?: Transform3Matrix): Transform3;
-
-/** An immutable XYZ transform or its canonical row-major matrix for interchange. */
-export declare type Transform3Input = Transform3 | Transform3Matrix;
+export declare function transform3(input?: Transform3Input): Transform3;
 
 /**
  * A row-major affine 4x4 matrix applied to column vectors.
@@ -2620,7 +2868,7 @@ export declare type Transform3Input = Transform3 | Transform3Matrix;
  * Translation occupies indices 3, 7, and 11. The final row must be
  * `[0, 0, 0, 1]` within the active geometry tolerance.
  */
-export declare type Transform3Matrix = readonly [
+export declare type Transform3Data = readonly [
   m00: number,
   m01: number,
   m02: number,
@@ -2639,6 +2887,9 @@ export declare type Transform3Matrix = readonly [
   m33: number,
 ];
 
+/** An immutable XYZ transform or its canonical row-major matrix for interchange. */
+export declare type Transform3Input = Transform3 | Transform3Data;
+
 /** Trapezoidal thread profile with a configurable included angle. */
 declare interface TrapezoidalThreadProfileSpec extends ThreadProfileBaseSpec {
   /** Selects the trapezoidal profile family. */
@@ -2681,7 +2932,7 @@ export declare interface TriangleMeshAnalysis extends TriangleMeshMeasurements {
  */
 export declare interface TriangleMeshMeasurements {
   /** Axis-aligned bounds. */
-  readonly bounds: Bounds3;
+  readonly bounds: Bounds3Data;
   /** Signed enclosed volume; positive values correspond to outward winding. */
   readonly signedVolume: number;
   /** Sum of all triangle areas in squared model units. */
@@ -2778,22 +3029,26 @@ export declare interface Vector2 {
   /** Returns Euclidean distance to another vector in the same coordinate units. */
   distance(other: Vector2Input): number;
   /** Returns this value's frozen readonly tuple for interchange; repeated calls do not allocate. */
-  toArray(): Vector2Tuple;
+  toData(): Vector2Data;
 }
 
 /**
  * Creates immutable XY arithmetic from a finite tuple or vector, snapshotting the coordinates.
+ *
  * Values and results are finite. Invalid dimensions throw `INVALID_ARGUMENT`; nonfinite coordinates
  * and overflow throw `NON_FINITE_VALUE` GeometryError.
  * Use transform2().applyDirection(value) for rotations and nonuniform scaling.
+ *
+ * Use `toData()` for frozen tuple interchange, or
+ * [normalize2](/docs/reference/geometry/normalize2) for tuple-based normalization in numerical loops.
  */
 export declare function vector2(input: Vector2Input): Vector2;
 
-/** An XY tuple or immutable fluent vector accepted by vector operations. */
-export declare type Vector2Input = Vector2Tuple | Vector2;
-
 /** A two-dimensional Cartesian vector or point. */
-export declare type Vector2Tuple = readonly [x: number, y: number];
+export declare type Vector2Data = readonly [x: number, y: number];
+
+/** An XY tuple or immutable fluent vector accepted by vector operations. */
+export declare type Vector2Input = Vector2Data | Vector2;
 
 /** Immutable XYZ arithmetic; vector operations return new values and measurements return numbers. */
 export declare interface Vector3 {
@@ -2822,15 +3077,19 @@ export declare interface Vector3 {
   /** Returns Euclidean distance to another vector in the same coordinate units. */
   distance(other: Vector3Input): number;
   /** Returns this value's frozen readonly tuple for interchange; repeated calls do not allocate. */
-  toArray(): Vector3Tuple;
+  toData(): Vector3Data;
 }
 
 /**
  * Creates immutable XYZ arithmetic from a finite tuple or vector, snapshotting the coordinates.
+ *
  * Values and results are finite. Invalid dimensions throw `INVALID_ARGUMENT`; nonfinite coordinates
  * and overflow throw `NON_FINITE_VALUE` GeometryError.
  * Use transform3().applyDirection(value) for rotations and nonuniform scaling.
  *
+ * Use `toData()` for frozen tuple interchange, or
+ * [normalize3](/docs/reference/geometry/normalize3) for tuple-based normalization in numerical loops.
+ *
  * @example
  * ```ts
  * const direction = vector3([1, 2, 3]).add([4, 0, 0]).normalize().scale(10);
@@ -2839,11 +3098,11 @@ export declare interface Vector3 {
  */
 export declare function vector3(input: Vector3Input): Vector3;
 
-/** An XYZ tuple or immutable fluent vector accepted by vector operations. */
-export declare type Vector3Input = Vector3Tuple | Vector3;
-
 /** A three-dimensional Cartesian vector or point. */
-export declare type Vector3Tuple = readonly [x: number, y: number, z: number];
+export declare type Vector3Data = readonly [x: number, y: number, z: number];
+
+/** An XYZ tuple or immutable fluent vector accepted by vector operations. */
+export declare type Vector3Input = Vector3Data | Vector3;
 
 /**
  * Immutable vector layout with no browser, font parser, or kernel ownership.
@@ -2858,7 +3117,7 @@ export declare interface VectorTextLayout {
 /** Text measurements from the same immutable layout that supplies geometry and SVG outlines. */
 export declare interface VectorTextMetrics {
   /** Visible curve bounds after alignment, or null when the text has no ink. */
-  readonly bounds: Bounds2 | null;
+  readonly bounds: Bounds2Data | null;
   /** Unaligned logical advance and negative baseline displacement in mm; arcs retain [arc length, 0]. */
   readonly advance: readonly [number, number];
   /** Maximum logical line advance in millimetres, including spaces; arc length on circular baselines. */