@metamesh/modeling 0.15.0 → 0.17.0

package/dist/api/geometry.d.ts

@@ -12,7 +12,7 @@ export declare interface AcmeThreadProfileSpec extends ThreadProfileBaseSpec {
 }
 
 /** Adds two finite XY vectors component-wise. */
-export declare const add2: (a: Vector2Tuple, b: Vector2Tuple) => Vector2Tuple;
+export declare const add2: (a: Vector2Data, b: Vector2Data) => Vector2Data;
 
 /**
  * Adds two finite XYZ vectors component-wise.
@@ -21,7 +21,7 @@ export declare const add2: (a: Vector2Tuple, b: Vector2Tuple) => Vector2Tuple;
  * add3([1, 2, 3], [4, 5, 6]); // [5, 7, 9]
  * ```
  */
-export declare const add3: (a: Vector3Tuple, b: Vector3Tuple) => Vector3Tuple;
+export declare const add3: (a: Vector3Data, b: Vector3Data) => Vector3Data;
 
 /** Controls full-circle sampling that must satisfy one or more topology alignments. */
 export declare interface AlignedCircularSegmentsOptions {
@@ -89,11 +89,11 @@ export declare function analyzeTriangleMeshQuality(
  */
 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;
 }
 
 /**
@@ -138,9 +138,9 @@ export declare function anchorFrame3(
  * @returns A fresh transformed direction.
  */
 export declare function applyTransformDirection3(
-  transform: Transform3Matrix,
-  direction: Vector3Tuple,
-): Vector3Tuple;
+  transform: Transform3Data,
+  direction: Vector3Data,
+): Vector3Data;
 
 /**
  * Applies an affine transform to a point, including translation.
@@ -150,16 +150,16 @@ export declare function applyTransformDirection3(
  * @returns A fresh transformed point.
  */
 export declare function applyTransformPoint3(
-  transform: Transform3Matrix,
-  point: Vector3Tuple,
-): Vector3Tuple;
+  transform: Transform3Data,
+  point: Vector3Data,
+): Vector3Data;
 
 /** Planar circular arc with counterclockwise degree angles. */
 export declare interface ArcCurve2 {
   /** Selects a circular arc in the XY plane. */
   readonly kind: "arc";
   /** Circle center in millimetres. */
-  readonly center: Vector2Tuple;
+  readonly center: Vector2Data;
   /** Positive circular radius in millimetres. */
   readonly radius: number;
   /** Initial angle in degrees; defaults to zero. */
@@ -173,13 +173,13 @@ export declare interface ArcCurve3 {
   /** Selects a circular arc in the supplied plane. */
   readonly kind: "arc";
   /** Circle center in millimetres. */
-  readonly center: Vector3Tuple;
+  readonly center: Vector3Data;
   /** Positive circular radius in millimetres. */
   readonly radius: number;
   /** Orthogonal unit direction at zero degrees. */
-  readonly xAxis: Vector3Tuple;
+  readonly xAxis: Vector3Data;
   /** Orthogonal unit direction at positive ninety degrees. */
-  readonly yAxis: Vector3Tuple;
+  readonly yAxis: Vector3Data;
   /** Initial angle in degrees; defaults to zero. */
   readonly startAngle?: number;
   /** Nonzero signed sweep in degrees, bounded to one complete turn. */
@@ -204,7 +204,7 @@ export declare function attachmentTransform3(
   source: Anchor3,
   target: Anchor3,
   options?: AttachOptions,
-): Transform3Matrix;
+): Transform3Data;
 
 /** Options controlling how one anchor is attached to another. */
 export declare interface AttachOptions {
@@ -235,36 +235,126 @@ export declare type AxisAngleRotation3 =
       readonly degrees?: never;
     };
 
-/** 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;
+}
+
+/**
+ * Constructs immutable finite XY bounds from ordered extrema or nonnegative size in millimetres.
+ *
+ * Zero extents are valid. Invalid dimensions, nonfinite coordinates, reversed bounds and
+ * overflowing extents throw `INVALID_ARGUMENT` GeometryError. Use `toData()` for plain records.
+ * Size construction centers on the origin unless `center` is false. Size and extrema are exclusive.
+ * Compiled Generator packages passing these values to host recipes or computed data require
+ * runtime 9.0.0 or newer in major 9.
+ */
+export declare function bounds2(input: Bounds2Options): 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;
+
+/** XY bounds construction from existing extrema or nonnegative dimensions, never both. */
+export declare type Bounds2Options =
+  | (Bounds2Input & {
+      /** Preserves the size query when snapshotting an existing fluent value. */
+      readonly size?: Bounds2["size"];
+      /** Preserves the center query when snapshotting an existing fluent value. */
+      readonly center?: Bounds2["center"];
+    })
+  | {
+      /** Nonnegative XY dimensions in millimetres. */
+      readonly size: Vector2Data;
+      /** Center on the origin; false starts at the origin. Defaults to true. */
+      readonly center?: boolean;
+      /** Minimum coordinates are unavailable when size is supplied. */
+      readonly min?: never;
+      /** Maximum coordinates are unavailable when size is supplied. */
+      readonly max?: never;
+    };
+
+/** 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 {
+/**
+ * Constructs immutable finite XYZ bounds from ordered extrema or nonnegative size in millimetres.
+ *
+ * Zero extents are valid. Invalid dimensions, nonfinite coordinates, reversed bounds and
+ * overflowing extents throw `INVALID_ARGUMENT` GeometryError. Use `toData()` for plain records.
+ * Size construction centers on the origin unless `center` is false. Size and extrema are exclusive.
+ * Compiled Generator packages passing these values to host recipes or computed data require
+ * runtime 9.0.0 or newer in major 9.
+ */
+export declare function bounds3(input: Bounds3Options): 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;
+
+/** XYZ bounds construction from existing extrema or nonnegative dimensions, never both. */
+export declare type Bounds3Options =
+  | (Bounds3Input & {
+      /** Preserves the size query when snapshotting an existing fluent value. */
+      readonly size?: Bounds3["size"];
+      /** Preserves the center query when snapshotting an existing fluent value. */
+      readonly center?: Bounds3["center"];
+    })
+  | {
+      /** Nonnegative XYZ dimensions in millimetres. */
+      readonly size: Vector3Data;
+      /** Center on the origin; false starts at the origin. Defaults to true. */
+      readonly center?: boolean;
+      /** Minimum coordinates are unavailable when size is supplied. */
+      readonly min?: never;
+      /** Maximum coordinates are unavailable when size is supplied. */
+      readonly max?: never;
+    };
+
 /** Midpoint of finite XY bounds in millimetres. */
-export declare function boundsCenter(bounds: Bounds2): Vector2Tuple;
+export declare function boundsCenter(bounds: Bounds2Data): Vector2Data;
 
 /** Midpoint of finite XYZ bounds in millimetres. */
-export declare function boundsCenter(bounds: Bounds3): Vector3Tuple;
+export declare function boundsCenter(bounds: Bounds3Data): Vector3Data;
 
 /** A uniform XY scale followed by translation, and the resulting bounds. */
 export declare interface BoundsFit2 {
   /** Positive uniform scale. */
   readonly scale: number;
   /** Millimetre translation applied after scaling around the origin. */
-  readonly position: Vector2Tuple;
+  readonly position: Vector2Data;
   /** Bounds after scaling and translation. */
-  readonly bounds: Bounds2;
+  readonly bounds: Bounds2Data;
 }
 
 /** A uniform XYZ scale followed by translation, and the resulting bounds. */
@@ -272,9 +362,9 @@ export declare interface BoundsFit3 {
   /** Positive uniform scale. */
   readonly scale: number;
   /** Millimetre translation applied after scaling around the origin. */
-  readonly position: Vector3Tuple;
+  readonly position: Vector3Data;
   /** Bounds after scaling and translation. */
-  readonly bounds: Bounds3;
+  readonly bounds: Bounds3Data;
 }
 
 /** Uniform fitting controls; fitting centers the source inside the target. */
@@ -283,29 +373,11 @@ export declare interface BoundsFitOptions {
   readonly maxScale?: number;
 }
 
-/** Creates immutable centered XY bounds from nonnegative dimensions in millimetres. */
-export declare function boundsFromSize(
-  size: Vector2Tuple,
-  options?: BoundsFromSizeOptions,
-): Bounds2;
-
-/** Creates immutable centered XYZ bounds from nonnegative dimensions in millimetres. */
-export declare function boundsFromSize(
-  size: Vector3Tuple,
-  options?: BoundsFromSizeOptions,
-): Bounds3;
-
-/** Placement of bounds constructed from nonnegative millimetre dimensions. */
-export declare interface BoundsFromSizeOptions {
-  /** Center on the origin; false starts at the origin. Defaults to true. */
-  readonly center?: boolean;
-}
-
 /** Inclusive XY dimensions in millimetres; zero extents are retained. */
-export declare function boundsSize(bounds: Bounds2): Vector2Tuple;
+export declare function boundsSize(bounds: Bounds2Data): Vector2Data;
 
 /** Inclusive XYZ dimensions in millimetres; zero extents are retained. */
-export declare function boundsSize(bounds: Bounds3): Vector3Tuple;
+export declare function boundsSize(bounds: Bounds3Data): Vector3Data;
 
 /** Creates an outward face-center anchor using the same local origin convention as box().
  * @remarks origin applies an explicit translation. For rotated components, transform the
@@ -320,13 +392,13 @@ export declare type BoxAnchorFace =
 /** Box dimensions and construction origin for one named face anchor. */
 export declare interface BoxAnchorOptions {
   /** XYZ dimensions, or one uniform dimension, in millimetres. */
-  readonly size: number | Vector3Tuple;
+  readonly size: number | Vector3Data;
   /** Named outward face whose center is the attachment point. */
   readonly face: BoxAnchorFace;
   /** Centers the box around its construction origin; defaults to true, matching box(). */
   readonly center?: boolean;
   /** Construction origin; centered-box center or noncentered minimum corner. Defaults to zero. */
-  readonly origin?: Vector3Tuple;
+  readonly origin?: Vector3Data;
 }
 
 /** Box edges use +Z top, +Y front and +X right; vertical names list front/back first. */
@@ -364,7 +436,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;
 }
@@ -409,20 +481,18 @@ export declare interface ChamferedEdgeTreatment {
  */
 export declare const circleContour: (options: CircleContourOptions) => Contour;
 
-/**
- * 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 CircleContourOptions = CircularPrimitiveOptions &
   RadialSizingOptions &
   (
     | {
-        /** Positive nominal radius in millimetres; mutually exclusive with diameter. */
+        /** Positive nominal radius in millimetres. */
         readonly radius: number;
-        /** Full diameter is unavailable when radius is supplied. */
+        /** Diameter is unavailable when radius is supplied. */
         readonly diameter?: never;
       }
     | {
-        /** Positive full diameter in millimetres; mutually exclusive with radius. */
+        /** Positive nominal diameter in millimetres. */
         readonly diameter: number;
         /** Radius is unavailable when diameter is supplied. */
         readonly radius?: never;
@@ -452,6 +522,19 @@ export declare interface CircularResolutionOptions extends GeometryResolution {
   readonly sizing?: RadialSizing;
 }
 
+/** Full-circle count and radial envelopes of its regular sampled polygon, in millimetres. */
+export declare interface CircularSampling {
+  /** Exact resolved full-circle segment count. */
+  readonly segments: number;
+  /** Distance from the origin to every sampled vertex. */
+  readonly vertexRadius: number;
+  /** Minimum distance from the origin to each straight sampled edge. */
+  readonly faceRadius: number;
+}
+
+/** Nominal circle size and explicit physical sampling; supply exactly one radius or diameter. */
+export declare type CircularSamplingOptions = CircleContourOptions;
+
 /** Close, normal, and loose metric clearance-hole diameters in millimetres. */
 export declare interface ClearanceHoleDimensions {
   /** Close-fit clearance-hole diameter. */
@@ -467,13 +550,14 @@ export declare type ClearanceHoleFit = "close" | "normal" | "loose";
 
 /**
  * Closes an open, strictly upward [radius, height] side outline to the radius-zero axis.
+ *
  * Adds horizontal bottom/top edges at the endpoint heights, retaining axis endpoints once.
  * Returns a counterclockwise filled-boundary contour without a repeated seam vertex.
  * Radii must be nonnegative; the result must enclose nonzero area without touching itself.
  * This is a solid-body closure, not a hollow-wall or mounting-bore construction.
  */
 export declare function closeToAxis(
-  side: readonly Vector2Tuple[],
+  side: readonly Vector2Data[],
   limits?: Partial<GeometrySamplingLimits>,
 ): Contour;
 
@@ -540,9 +624,9 @@ export declare function compensateThreadProfileForFaceting(
  * @returns A new frozen transform equal to `after * before`.
  */
 export declare function composeTransform3(
-  after: Transform3Matrix,
-  before: Transform3Matrix,
-): Transform3Matrix;
+  after: Transform3Data,
+  before: Transform3Data,
+): Transform3Data;
 
 /**
  * Builds rotation-minimizing frames for a non-duplicated closed path.
@@ -563,6 +647,7 @@ export declare const computeClosedParallelTransportFrames: (
 
 /**
  * Builds rotation-minimizing frames by parallel-transporting the previous normal.
+ *
  * This avoids the sudden profile flips produced by picking a fresh up-vector per ring.
  * Paths exceeding maxPathPoints (default 100000) reject before frame allocation or guide evaluation.
  * Requires open path values; raw tuples are interpreted as an open path. Invalid paths throw GeometryError.
@@ -577,6 +662,7 @@ export declare const computeParallelTransportFrames: (
 
 /**
  * Computes the uniform-density volume centroid of an oriented closed solid, including cavity shells.
+ *
  * Coordinates are millimetres. Indexed closure and positive aggregate volume are required; callers
  * may use validateSolidMesh first when geometric intersections and shell orientation are untrusted.
  * Fresh mutable input is inspected on every call, and buffers are never changed.
@@ -586,7 +672,7 @@ export declare const computeParallelTransportFrames: (
  */
 export declare function computeTriangleMeshCentroid(
   mesh: TriangleMesh,
-): Vector3Tuple;
+): Vector3Data;
 
 /**
  * Creates an order-independent regression signature for a manufacturing mesh.
@@ -605,24 +691,22 @@ export declare function computeTriangleMeshSignature(
   options?: TriangleMeshSignatureOptions,
 ): TriangleMeshSignature;
 
-/** Tests actual XY containment, including touching boundaries; dimensions must match. */
-export declare function containsBounds(outer: Bounds2, inner: Bounds2): boolean;
-
-/** Tests actual XYZ containment, including touching boundaries; dimensions must match. */
-export declare function containsBounds(outer: Bounds3, inner: Bounds3): boolean;
-
 /**
- * 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[];
 
 /** Returns true when a point lies inside or on the boundary of a loop. */
 export declare function contourContainsPoint(
   loop: Contour,
-  point: Vector2Tuple,
+  point: Vector2Data,
 ): boolean;
 
 /** One explicitly closed planar contour, independent of editor metadata and parameter contracts. */
@@ -693,7 +777,7 @@ export declare type CorrespondingProfileStation = LoftPlacement & {
 };
 
 /** Returns the signed scalar cross product; positive means `b` is counter-clockwise from `a`. */
-export declare const cross2: (a: Vector2Tuple, b: Vector2Tuple) => number;
+export declare const cross2: (a: Vector2Data, b: Vector2Data) => number;
 
 /**
  * Returns the right-handed cross product.
@@ -702,20 +786,20 @@ export declare const cross2: (a: Vector2Tuple, b: Vector2Tuple) => number;
  * cross3([1, 0, 0], [0, 1, 0]); // [0, 0, 1]
  * ```
  */
-export declare const cross3: (a: Vector3Tuple, b: Vector3Tuple) => Vector3Tuple;
+export declare const cross3: (a: Vector3Data, b: Vector3Data) => Vector3Data;
 
 /** Planar cubic Bézier with explicit endpoint and control coordinates. */
 export declare interface CubicBezierCurve2 {
   /** Selects a cubic Bézier through two endpoints and two controls. */
   readonly kind: "cubic";
   /** Initial XY point in millimetres. */
-  readonly start: Vector2Tuple;
+  readonly start: Vector2Data;
   /** First XY control point in millimetres. */
-  readonly control1: Vector2Tuple;
+  readonly control1: Vector2Data;
   /** Second XY control point in millimetres. */
-  readonly control2: Vector2Tuple;
+  readonly control2: Vector2Data;
   /** Final XY point in millimetres. */
-  readonly end: Vector2Tuple;
+  readonly end: Vector2Data;
 }
 
 /**
@@ -725,13 +809,13 @@ export declare interface CubicBezierCurve3 {
   /** Selects a cubic Bézier through two endpoints and two controls. */
   readonly kind: "cubic";
   /** Initial XYZ point in millimetres. */
-  readonly start: Vector3Tuple;
+  readonly start: Vector3Data;
   /** First XYZ control point in millimetres. */
-  readonly control1: Vector3Tuple;
+  readonly control1: Vector3Data;
   /** Second XYZ control point in millimetres. */
-  readonly control2: Vector3Tuple;
+  readonly control2: Vector3Data;
   /** Final XYZ point in millimetres. */
-  readonly end: Vector3Tuple;
+  readonly end: Vector3Data;
 }
 
 /** Reusable planar curve definition. */
@@ -764,7 +848,7 @@ export 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[];
 }
 
 /** Creates a cap-center or radial-side anchor using cylinder()'s construction origin.
@@ -791,7 +875,7 @@ export declare interface CylinderAnchorOptions {
   /** Centers the cylinder along Z; defaults to true, matching cylinder(). */
   readonly center?: boolean;
   /** Construction origin; centered-axis midpoint or noncentered bottom axis. Defaults to zero. */
-  readonly origin?: Vector3Tuple;
+  readonly origin?: Vector3Data;
 }
 
 /**
@@ -968,10 +1052,10 @@ export declare const DEFAULT_GEOMETRY_TOLERANCE: Readonly<{
 export declare const defaultGeometrySamplingLimits: GeometrySamplingLimits;
 
 /** Returns Euclidean point distance without allocating an intermediate difference vector. */
-export declare const distance2: (a: Vector2Tuple, b: Vector2Tuple) => number;
+export declare const distance2: (a: Vector2Data, b: Vector2Data) => number;
 
 /** Returns Euclidean point distance without allocating an intermediate difference vector. */
-export declare const distance3: (a: Vector3Tuple, b: Vector3Tuple) => number;
+export declare const distance3: (a: Vector3Data, b: Vector3Data) => number;
 
 /**
  * Places an exact item count at equal arc-length intervals along a sampled path.
@@ -991,7 +1075,7 @@ export declare const distributeAlongPath: (
 ) => readonly PathPlacement[];
 
 /** Returns the scalar dot product. */
-export declare const dot2: (a: Vector2Tuple, b: Vector2Tuple) => number;
+export declare const dot2: (a: Vector2Data, b: Vector2Data) => number;
 
 /**
  * Returns the scalar dot product.
@@ -1000,7 +1084,7 @@ export declare const dot2: (a: Vector2Tuple, b: Vector2Tuple) => number;
  * dot3([1, 0, 0], [0, 1, 0]); // 0
  * ```
  */
-export declare const dot3: (a: Vector3Tuple, b: Vector3Tuple) => number;
+export declare const dot3: (a: Vector3Data, b: Vector3Data) => number;
 
 /**
  * Uniform finishing vocabulary shared by applicable solid edges and profile corners.
@@ -1028,13 +1112,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;
       }
@@ -1062,8 +1146,8 @@ export declare interface EndTreatments {
  * @throws {@link GeometryError} When an angle is non-finite.
  */
 export declare function eulerTransform3(
-  rotationDegrees: Vector3Tuple,
-): Transform3Matrix;
+  rotationDegrees: Vector3Data,
+): Transform3Data;
 
 /**
  * Linearly extrudes one simple profile along +Z with robust ear-clipped caps.
@@ -1108,15 +1192,15 @@ export declare interface ExtrusionSamplingOptions {
 
 /** Fits XY bounds uniformly and centers them in the target; zero source axes do not constrain scale. */
 export declare function fitBounds(
-  source: Bounds2,
-  target: Bounds2,
+  source: Bounds2Data,
+  target: Bounds2Data,
   options?: BoundsFitOptions,
 ): BoundsFit2;
 
 /** Fits XYZ bounds uniformly and centers them in the target; zero source axes do not constrain scale. */
 export declare function fitBounds(
-  source: Bounds3,
-  target: Bounds3,
+  source: Bounds3Data,
+  target: Bounds3Data,
   options?: BoundsFitOptions,
 ): BoundsFit3;
 
@@ -1125,12 +1209,13 @@ export declare interface FittedTextLayout extends VectorTextLayout {
   /** Transformed physical measurements, including nonempty visible ink bounds. */
   readonly metrics: VectorTextMetrics & {
     /** Finite positive-area ink bounds in final millimetres. */
-    readonly bounds: Bounds2;
+    readonly bounds: Bounds2Data;
   };
 }
 
 /**
  * Uniformly fits visible text ink inside finite XY bounds, centering it on the target.
+ *
  * Transforms retained vector paths before sampling, so later textSection/sampleTextContours
  * resolution remains in final millimetres. Logical advances scale without translation;
  * line count is unchanged. The input layout is preserved.
@@ -1143,20 +1228,20 @@ export declare interface FittedTextLayout extends VectorTextLayout {
  */
 export declare function fitTextLayout(
   layout: VectorTextLayout,
-  target: Bounds2,
+  target: Bounds2Data,
   options?: BoundsFitOptions,
 ): FittedTextLayout;
 
 /** 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;
 }
 
 /**
@@ -1170,7 +1255,7 @@ export declare interface Frame3 {
 export declare function frameTransform3(
   frame: Frame3,
   tolerance?: GeometryToleranceOptions,
-): Transform3Matrix;
+): Transform3Data;
 
 /**
  * Error raised when a geometry precondition or invariant is not satisfied.
@@ -1287,16 +1372,16 @@ 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)
 );
@@ -1304,14 +1389,17 @@ export declare type GridPatternOptions<Dimension extends 2 | 3 = 3> = {
 /** Spatial XYZ matrices for an XY or XYZ grid, in X-fastest order. */
 export declare function gridPatternTransforms(
   options: GridPatternOptions,
-): readonly Transform3Matrix[];
+): readonly Transform3Data[];
 
 /**
  * Builds a closed indexed mesh from a rectilinear top, matched boundary walls, and flat base.
+ *
  * Heights run once per grid point after preflight; center-error adds one evaluation per cell.
  * Top winding is +Z, the base is -Z, and sides face outward. Coordinates and heights must fit
  * Float32 storage. Explicit axes are captured before sampling; shared wall vertices prevent cracks.
  *
+ * @see {@link preflightHeightfield}
+ *
  * @example Sample a closed wavy mesh
  * ```ts
  * heightfieldMesh({
@@ -1341,7 +1429,7 @@ export declare type HeightfieldMeshLimits = Partial<
  */
 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;
   /**
@@ -1354,11 +1442,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;
     }
@@ -1382,15 +1470,15 @@ export declare type HeightfieldOptions = {
     }
 );
 
-/** Predictable rectilinear-grid allocation facts; this does not evaluate the height callback. */
+/** Exact grid and mesh buffer allocation counts resolved without evaluating the height callback. */
 export declare interface HeightfieldPreflight {
-  /** Number of top grid points; center-error also evaluates one height per cell. */
+  /** Number of top grid points; excludes the extra per-cell height evaluations for center-error. */
   readonly sampleCount: number;
   /** Number of allocated XYZ vertices. */
   readonly vertexCount: number;
   /** Number of allocated indexed triangles. */
   readonly triangleCount: number;
-  /** Total bytes of Float32 positions and Uint32 indices. */
+  /** Total bytes of Float32 positions and Uint32 indices, excluding temporary storage. */
   readonly byteCount: number;
 }
 
@@ -1461,7 +1549,7 @@ export declare interface HelicalThreadSolidMeshOptions extends HelicalThreadRidg
   readonly bevelTopSize?: number;
 }
 
-/** 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;
@@ -1474,7 +1562,7 @@ export declare interface HelicalThreadSolidMeshPreflight {
 }
 
 /** Identity transform, safe to share because it is frozen. */
-export declare const IDENTITY_TRANSFORM3: Transform3Matrix;
+export declare const IDENTITY_TRANSFORM3: Transform3Data;
 
 /** Options for a compensated internal-thread subtraction tool along +Z. */
 export declare interface InternalThreadCutterOptions
@@ -1494,11 +1582,12 @@ export declare interface InternalThreadCutterOptions
  * @returns A new frozen transform whose composition with the input is identity.
  */
 export declare function inverseTransform3(
-  transform: Transform3Matrix,
-): Transform3Matrix;
+  transform: Transform3Data,
+): Transform3Data;
 
 /**
  * Recognizes structured geometry errors from separately bundled Modeling copies in the same realm.
+ *
  * Ordinary errors and unmarked code-shaped objects are rejected. The marker is execution-local and
  * does not survive structured cloning; worker protocols carry their own serialized error envelope.
  */
@@ -1517,35 +1606,128 @@ export declare function joinTriangleMeshes(
   meshes: readonly TriangleMesh[],
 ): TriangleMesh;
 
+/** 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;
+}
+
+/** Immutable joint layout and conservative faceted envelopes; no engine initialization. */
+export declare interface KnuckleHingeDimensions {
+  /** Validated, copied nominal inputs. */
+  readonly spec: KnuckleHingeSpec;
+  /** Nominal outside barrel radius. */
+  readonly barrelRadius: number;
+  /** Maximum shaft radius under any rotation. */
+  readonly pinRadius: number;
+  /** Minimum face-sized bore radius, including radial clearance. */
+  readonly boreRadius: number;
+  /** Maximum radius at the faceted bore vertices. */
+  readonly boreOuterRadius: number;
+  /** Conservative radial wall before outer end chamfers, accounting for both polygons. */
+  readonly minimumBarrelWall: number;
+  /** Equal length of every interval. */
+  readonly knuckleLength: number;
+  /** Common exact full-circle segment count. */
+  readonly segments: number;
+  /** Alternating schedule ordered from negative to positive X. */
+  readonly knuckles: readonly KnuckleHingeInterval[];
+  /** Integral pin interval; null when the consumer supplies an inserted pin. */
+  readonly pin: Readonly<{
+    /** Start coordinate along X, in millimetres. */
+    start: number;
+    /** Total integral shaft length, including material inside A. */
+    length: number;
+  }> | null;
+  /** Origin at the joint center, direction +X, roll guide +Z. */
+  readonly axis: Anchor3;
+}
+
+/** One equal-length barrel interval in the shared pin-centered frame. */
+export declare interface KnuckleHingeInterval {
+  /** Alternating owner, beginning with A at the negative end of X. */
+  readonly side: "a" | "b";
+  /** Start along X, in millimetres. */
+  readonly start: number;
+  /** Axial length, excluding the neighboring gaps. */
+  readonly length: number;
+}
+
+/** 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;
+      }
+  );
+
 /**
  * Returns immutable translations for a +X row of finite XYZ bounds with a nonnegative gap.
+ *
  * Each minimum Y/Z becomes zero, and the first minimum X becomes zero. Supply bounds after
  * any intended part rotation; translations apply to those bounds. An empty input returns [].
  */
 export declare function layoutRow(
-  bounds: readonly Bounds3[],
+  bounds: readonly Bounds3Data[],
   options?: RowLayoutOptions,
-): readonly Vector3Tuple[];
+): readonly Vector3Data[];
 
 /** Returns Euclidean vector length in the vector's coordinate units. */
-export declare const length2: (vector: Vector2Tuple) => number;
+export declare const length2: (vector: Vector2Data) => number;
 
 /** Returns Euclidean vector length in the vector's coordinate units. */
-export declare const length3: (vector: Vector3Tuple) => number;
+export declare const length3: (vector: Vector3Data) => number;
 
 /** Linearly interpolates two vectors; `t` is dimensionless and may extrapolate. */
 export declare const lerp2: (
-  a: Vector2Tuple,
-  b: Vector2Tuple,
+  a: Vector2Data,
+  b: Vector2Data,
   t: number,
-) => Vector2Tuple;
+) => Vector2Data;
 
 /** Linearly interpolates two vectors; `t` is dimensionless and may extrapolate. */
 export declare const lerp3: (
-  a: Vector3Tuple,
-  b: Vector3Tuple,
+  a: Vector3Data,
+  b: Vector3Data,
   t: number,
-) => Vector3Tuple;
+) => Vector3Data;
 
 /**
  * Equal linear intervals determined by exactly two of count, spacing and total length.
@@ -1584,16 +1766,16 @@ export declare type LinearPatternOptions<Dimension extends 2 | 3 = 3> = {
 /** Spatial XYZ matrix placements in millimetres, including the original at the origin. */
 export declare function linearPatternTransforms(
   options: LinearPatternOptions,
-): readonly Transform3Matrix[];
+): readonly Transform3Data[];
 
 /** Straight planar curve in millimetres. */
 export declare interface LineCurve2 {
   /** Selects straight interpolation between the two endpoints. */
   readonly kind: "line";
   /** Initial XY point in millimetres. */
-  readonly start: Vector2Tuple;
+  readonly start: Vector2Data;
   /** Final XY point in millimetres. */
-  readonly end: Vector2Tuple;
+  readonly end: Vector2Data;
 }
 
 /** Straight spatial curve in millimetres. */
@@ -1601,9 +1783,9 @@ export declare interface LineCurve3 {
   /** Selects straight interpolation between the two endpoints. */
   readonly kind: "line";
   /** Initial XYZ point in millimetres. */
-  readonly start: Vector3Tuple;
+  readonly start: Vector3Data;
   /** Final XYZ point in millimetres. */
-  readonly end: Vector3Tuple;
+  readonly end: Vector3Data;
 }
 
 /**
@@ -1687,6 +1869,7 @@ export declare type LoftPlacement =
 
 /**
  * Explicitly matches identified component/contour/span topology across a family.
+ *
  * Every paired span uses the maximum physical subdivision count requested by any member.
  * 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
@@ -1734,7 +1917,7 @@ export declare function measureInternalCylindricalGearPairMotion(
  * @returns Fresh immutable minimum and maximum XYZ tuples.
  * @throws {@link GeometryError} When the mesh is structurally invalid.
  */
-export declare const meshBounds: (mesh: TriangleMesh) => Bounds3;
+export declare const meshBounds: (mesh: TriangleMesh) => Bounds3Data;
 
 /**
  * Curated metric modeling dimensions for clearance holes, regular hex nuts,
@@ -1765,7 +1948,7 @@ export declare const METRIC_FASTENER_STANDARDS: Readonly<{
   M12: MetricFastenerStandard;
 }>;
 
-/** Metric fastener sizes included in the first mechanical standards table. */
+/** Supported metric fastener sizes. */
 export declare type MetricFastenerSize =
   "M2" | "M2.5" | "M3" | "M4" | "M5" | "M6" | "M8" | "M10" | "M12";
 
@@ -1825,23 +2008,25 @@ export declare interface ModelingLimits extends GeometrySamplingLimits {
 
 /**
  * Returns a unit vector; `epsilon` is a finite, non-negative length threshold (default `1e-12`).
+ *
  * Rejects invalid thresholds, nonfinite lengths, and lengths at or below the threshold with
  * `INVALID_TOLERANCE`, `NON_FINITE_VALUE`, and `DEGENERATE_GEOMETRY` respectively.
  */
 export declare const normalize2: (
-  vector: Vector2Tuple,
+  vector: Vector2Data,
   epsilon?: number,
-) => Vector2Tuple;
+) => Vector2Data;
 
 /**
  * Returns a unit vector; `epsilon` is a finite, non-negative length threshold (default `1e-12`).
+ *
  * Rejects invalid thresholds, nonfinite lengths, and lengths at or below the threshold with
  * `INVALID_TOLERANCE`, `NON_FINITE_VALUE`, and `DEGENERATE_GEOMETRY` respectively.
  */
 export declare const normalize3: (
-  vector: Vector3Tuple,
+  vector: Vector3Data,
   epsilon?: number,
-) => Vector3Tuple;
+) => Vector3Data;
 
 /**
  * Cleans and validates one closed loop.
@@ -1852,7 +2037,7 @@ export declare const normalize3: (
  * returned unchanged when their winding and tolerance policy match.
  */
 export declare function normalizeContour(
-  input: readonly Vector2Tuple[],
+  input: readonly Vector2Data[],
   counterClockwise: boolean,
   tolerance?: GeometryToleranceOptions,
 ): Contour;
@@ -1902,11 +2087,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>;
@@ -1920,19 +2105,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 {
@@ -1940,11 +2135,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>;
@@ -1959,25 +2154,34 @@ 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[];
 
 /** Orthonormal right-handed frame sampled along a path. */
 export declare interface PathFrame {
   /** Unit path tangent. */
-  readonly tangent: Vector3Tuple;
+  readonly tangent: Vector3Data;
   /** Unit transported profile X axis. */
-  readonly normal: Vector3Tuple;
+  readonly normal: Vector3Data;
   /** Unit profile Y axis equal to tangent × normal. */
-  readonly binormal: Vector3Tuple;
+  readonly binormal: Vector3Data;
 }
 
 /** Nearest location on a sampled boundary, rather than inside a filled shape or on an analytic curve. */
@@ -2000,7 +2204,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;
 
@@ -2023,7 +2227,9 @@ export declare interface PathPatternOptions {
 }
 
 /**
- * Equal physical arc-length placements along a sampled XYZ path. Tangent orientation maps +Z
+ * Equal physical arc-length placements along a sampled XYZ path.
+ *
+ * Tangent orientation maps +Z
  * onto the local path tangent; fixed orientation only translates. Closed paths omit a repeated seam.
  * Explicit sampling ceilings bound both input points and output placements.
  */
@@ -2031,14 +2237,14 @@ export declare function pathPatternTransforms(
   path: Path3Input,
   options: PathPatternOptions,
   limits?: Partial<GeometrySamplingLimits>,
-): readonly Transform3Matrix[];
+): readonly Transform3Data[];
 
 /** Position and unit tangent for one path-distributed item. */
 export declare interface PathPlacement {
   /** Interpolated point on the sampled path. */
-  readonly position: Vector3Tuple;
+  readonly position: Vector3Data;
   /** Unit tangent of the path segment containing the placement. */
-  readonly tangent: Vector3Tuple;
+  readonly tangent: Vector3Data;
 }
 
 /** Equal arc-length sampling; the path itself owns whether its closing edge is included. */
@@ -2137,7 +2343,7 @@ export declare interface PlanarPatchQuality {
   /** Smallest interior triangle angle in degrees. */
   readonly minimumTriangleAngleDegrees: number;
   /** Consistently wound unit normal for the patch plane. */
-  readonly normal: Vector3Tuple;
+  readonly normal: Vector3Data;
   /** Plane offset in `dot(normal, position) = planeOffset` form, in model units. */
   readonly planeOffset: number;
   /** Total patch area in squared model units. */
@@ -2149,11 +2355,14 @@ export declare interface PlanarPatchQuality {
 }
 
 /**
- * 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. */
@@ -2172,31 +2381,63 @@ export declare interface PolylineResamplingOptions extends CurveSamplingOptions
   readonly closed?: boolean;
 }
 
-/** Checks grid dimensions, coordinate precision, and allocation bounds before evaluating heights. */
+/**
+ * Checks grid options, Float32 axis precision, and output limits; returns exact mesh buffer counts.
+ *
+ * This pure operation needs no engine and neither evaluates `height` nor allocates mesh buffers.
+ * Successful preflight leaves height values, Float32 base storage, and generated mesh validity to
+ * construction. `byteCount` covers position and index buffers, not total working memory.
+ *
+ * @see {@link heightfieldMesh}
+ */
 export declare function preflightHeightfield(
   options: HeightfieldOptions,
   limits?: HeightfieldMeshLimits,
 ): HeightfieldPreflight;
 
 /**
- * Validates a direct thread solid and returns its conservative allocation estimate without
- * constructing vertex or index buffers.
+ * Checks thread dimensions, profile, end treatments, sampling, and conservative estimates against output limits.
+ *
+ * This pure operation needs no engine and constructs planning data without vertex or index buffers.
+ * `circularSegments` is the selected count; row and triangle counts are conservative estimates.
+ * Successful preflight leaves generated coordinate and topology checks to mesh construction.
+ *
+ * @see {@link helicalThreadSolidMesh}
  */
 export declare function preflightHelicalThreadSolidMesh(
   options: HelicalThreadSolidMeshOptions,
 ): HelicalThreadSolidMeshPreflight;
 
-/** Preflights the exact extended mesh used by the internal thread cutter constructor. */
+/**
+ * Resolves compensated cutter dimensions and checks extended mesh estimates against output limits.
+ *
+ * This pure operation uses explicit resolution and limits or package defaults, without an active
+ * host execution. It includes the cutter's one-pitch extension beyond each requested face and
+ * creates planning data without mesh buffers or native objects. Row and triangle counts are
+ * estimates; mesh validity and native construction are checked later.
+ *
+ * @see {@link preflightHelicalThreadSolidMesh}
+ * @see {@link helicalThreadSolidMesh}
+ */
 export declare function preflightInternalThreadCutter(
   options: InternalThreadCutterOptions,
 ): HelicalThreadSolidMeshPreflight;
 
 /**
- * Preflights bounded SVG geometry without browser or Manifold dependencies.
+ * Parses and validates bounded SVG input, constructing its normalized sampled region and diagnostics.
+ *
+ * This pure operation performs curve flattening, fill and stroke construction, and polygon union;
+ * it needs no browser or engine. Geometry counts measure the returned region at the selected
+ * resolution, rather than predicting later mesh allocation. With `fit`, painted bounds are
+ * uniformly centered inside the target and adaptive sampling remains in final millimetres.
+ * Refinement runs at most eight bounded import passes; exact circular counts retain precedence.
+ * Without `fit` the region may be empty. Tiny-island and short-edge indicators do not establish
+ * manufacturability or later solid validity.
  *
  * @param svg - Complete SVG XML source, limited to 256 KiB of UTF-8.
  * @param options - Physical flattening and viewport-origin controls.
  * @returns The canonical normalized region plus bounded source, topology, and safe-repair facts.
+ * @throws {@link GeometryError} When XML, supported-feature, geometry, or complexity checks fail.
  */
 export declare function preflightSvgRegion(
   svg: string,
@@ -2204,14 +2445,29 @@ export declare function preflightSvgRegion(
 ): SvgRegionPreflight;
 
 /**
- * Resolves a nut's exact body/cutter chamfer and preflights its extended thread mesh without
- * allocating Manifold WASM objects.
+ * Checks nut dimensions, chamfers, end-face wall, and the extended compensated cutter's allocation plan.
+ *
+ * This pure operation uses explicit resolution and limits or package defaults, without an active
+ * host execution. It resolves body/cutter dimensions without mesh buffers or native objects.
+ * `thread` contains conservative cutter estimates, excluding the body and Boolean result.
+ * Successful preflight leaves mesh validity, native construction, and manufacturing fit to later checks.
+ *
+ * @see {@link preflightHelicalThreadSolidMesh}
  */
 export declare function preflightThreadedNut(
   options: ThreadedNutOptions,
 ): ThreadedNutPreflight;
 
-/** Preflights the exact compensated direct mesh used by the threaded rod constructor. */
+/**
+ * Resolves compensated rod dimensions and checks conservative mesh estimates against output limits.
+ *
+ * This pure operation uses explicit resolution and limits or package defaults, without an active
+ * host execution. It creates planning data without mesh buffers or native objects; returned row
+ * and triangle counts are estimates. Mesh validity and native construction are checked later.
+ *
+ * @see {@link preflightHelicalThreadSolidMesh}
+ * @see {@link helicalThreadSolidMesh}
+ */
 export declare function preflightThreadedRod(
   options: ThreadedRodOptions,
 ): HelicalThreadSolidMeshPreflight;
@@ -2266,7 +2522,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[];
@@ -2282,7 +2544,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;
@@ -2299,7 +2567,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. */
@@ -2315,15 +2583,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. */
@@ -2335,21 +2603,21 @@ 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;
     }
 );
 
 /** Removes the component parallel to a normalized plane normal. */
 export declare const projectOntoPlane3: (
-  vector: Vector3Tuple,
-  normal: Vector3Tuple,
-) => Vector3Tuple;
+  vector: Vector3Data,
+  normal: Vector3Data,
+) => Vector3Data;
 
 /** Resolved pitch-line dimensions for a finite rack segment. */
 export declare interface RackPitchDimensions {
@@ -2412,7 +2680,7 @@ export declare type RadialPatternOptions<Dimension extends 2 | 3 = 3> = {
 /** Rotations about an explicit axis; angles use degrees and the first placement is identity. */
 export declare function radialPatternTransforms(
   options: RadialPatternOptions,
-): readonly Transform3Matrix[];
+): readonly Transform3Data[];
 
 /** Radial dimensions refer to polygon vertices or compensate faceting to meet polygon faces. */
 export declare type RadialSizing = "vertex" | "face";
@@ -2428,7 +2696,11 @@ export declare interface RadialSizingOptions {
 }
 
 /**
- * Creates an immutable CCW rectangle loop. Round radius zero is square; tangent saturated endpoints occur once.
+ * Creates an immutable sampled CCW rectangle boundary. Round radius zero is square; tangent saturated endpoints occur once.
+ *
+ * Use [rectangle](/docs/reference/model/rectangle) for a filled Section.
+ *
+ * @see {@link rectangleProfile} for identified edge/corner spans used by matchProfiles.
  *
  * @example Rounded rectangle outline
  * ```ts
@@ -2444,7 +2716,7 @@ export declare function rectangleContour(
  */
 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. */
@@ -2472,6 +2744,11 @@ export declare type RectangleCornerTreatments = readonly [
 /**
  * Creates an identified rectangle whose edge/corner spans survive zero and saturated round radii. Outer winding is CCW.
  *
+ * Use [rectangle](/docs/reference/model/rectangle) for a filled Section.
+ *
+ * @see {@link matchProfiles} to sample a family with shared landmark correspondence.
+ * @see {@link rectangleContour} for sampled boundary coordinates.
+ *
  * @example Retain rectangle landmarks
  * ```ts
  * rectangleProfile({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
@@ -2500,9 +2777,14 @@ export declare interface RectangleProfileOptions extends RectangleContourOptions
 export declare function regionArea(region: RegionData): number;
 
 /** Returns finite axis-aligned bounds for a non-empty region. */
-export declare function regionBounds(region: RegionData): Bounds2;
+export declare function regionBounds(region: RegionData): Bounds2Data;
 
-/** 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[];
 
 /**
@@ -2515,7 +2797,7 @@ export declare type RegionData = readonly PolygonData[];
  */
 export declare const regularPolygonContour: (
   options: RegularPolygonContourOptions,
-) => readonly Vector2Tuple[];
+) => readonly Vector2Data[];
 
 /** Exact regular polygon dimensions and counterclockwise degree rotation. */
 export declare interface RegularPolygonContourOptions extends RadialSizingOptions {
@@ -2535,7 +2817,7 @@ export declare interface RegularPolygonContourOptions extends RadialSizingOption
  * ```
  */
 export declare function resamplePolyline2(
-  path: readonly Vector2Tuple[],
+  path: readonly Vector2Data[],
   options?: PolylineResamplingOptions,
 ): SampledCurve2;
 
@@ -2551,7 +2833,7 @@ export declare function resamplePolyline2(
  * ```
  */
 export declare function resamplePolyline3(
-  path: readonly Vector3Tuple[],
+  path: readonly Vector3Data[],
   options?: PolylineResamplingOptions,
 ): SampledCurve3;
 
@@ -2607,6 +2889,25 @@ export declare function resolveArcSegments(
   limits?: Partial<GeometrySamplingLimits>,
 ): number;
 
+/**
+ * Resolves circular sampling and its actual radial envelopes without allocating boundary points.
+ *
+ * Vertex sizing retains the nominal vertex radius; face sizing retains the nominal face radius.
+ * Exact `segments` override resolution, while allocation ceilings still apply. Adaptive sampling
+ * uses the same count calculation as `resolveCircularSegments` and `circleContour` and rejects
+ * exhausted limits rather than coarsening. The returned record is immutable and needs no engine.
+ *
+ * @example Check a nominal 8 mm face-sized bore
+ * ```ts
+ * const bore = resolveCircularSampling({ diameter: 8, segments: 64, sizing: "face" });
+ * bore.faceRadius; // 4 mm
+ * bore.vertexRadius; // slightly larger than 4 mm
+ * ```
+ */
+export declare function resolveCircularSampling(
+  options: CircularSamplingOptions,
+): CircularSampling;
+
 /**
  * Resolves a deterministic full-circle segment count for one radius.
  *
@@ -2712,6 +3013,23 @@ export declare function resolveGeometryTolerance(
   options?: GeometryToleranceOptions,
 ): ResolvedGeometryTolerance;
 
+/**
+ * Resolves equal alternating knuckles along +X, centered at the origin, in millimetres.
+ *
+ * Both faces of each running pair use a common polygon count; face-sized bores contain the
+ * shaft's complete rotational envelope. Adaptive sampling satisfies both face and vertex error
+ * bounds; an insufficient ceiling rejects instead of reducing quality. Exact counts are intentional
+ * facets. Zero allowances describe ideal contact, not a printable running fit.
+ *
+ * Rejects nonfinite or nonpositive dimensions, invalid mode/count combinations, exhausted axial
+ * length, missing/excessive lift-off engagement, and nonpositive conservative faceted barrel walls.
+ * Manufacturing minima, strength, mounting, retention, handedness, and motion remain caller policy.
+ */
+export declare function resolveKnuckleHinge(
+  spec: KnuckleHingeSpec,
+  options?: KnuckleHingeSamplingOptions,
+): KnuckleHingeDimensions;
+
 /** Resolves and validates a named or caller-defined print-fit policy. */
 export declare function resolvePrintableThreadFitPolicy(
   fit?: PrintableThreadFit | PrintableThreadFitPolicy,
@@ -2788,9 +3106,9 @@ export declare interface RevolveOptions extends CircularPrimitiveOptions {
  * Throws `NON_FINITE_VALUE` for nonfinite coordinates, angles, or derived coordinates.
  */
 export declare const rotate2: (
-  vector: Vector2Tuple,
+  vector: Vector2Data,
   degrees: number,
-) => Vector2Tuple;
+) => Vector2Data;
 
 /**
  * Creates a right-handed axis-angle rotation transform.
@@ -2801,10 +3119,10 @@ export declare const rotate2: (
  * @returns A frozen row-major transform.
  */
 export declare function rotationTransform3(
-  axis: Vector3Tuple,
+  axis: Vector3Data,
   angle: AxisAngleRotation3,
   tolerance?: GeometryToleranceOptions,
-): Transform3Matrix;
+): Transform3Data;
 
 /**
  * Replaces each vertex of a non-duplicated closed polyline with a sampled
@@ -2821,7 +3139,7 @@ export declare const roundClosedPolylinePath: (
   radius: number,
   segmentsPerCorner: number,
   limits?: Partial<GeometrySamplingLimits>,
-) => readonly Vector3Tuple[];
+) => readonly Vector3Data[];
 
 /**
  * A circular edge or corner roundover with explicit physical sampling.
@@ -2841,6 +3159,7 @@ export declare interface RowLayoutOptions {
 
 /**
  * Samples 2–32 connected line/cubic segments into a simple, nonzero-area, immutable CCW XY loop.
+ *
  * Physical scaling precedes adaptive curve sampling; the final end must repeat start exactly.
  * Shared anchors and the closing seam are emitted once. Winding normalization may change the
  * starting vertex. The sampled loop is checked for self-intersection and degeneracy by
@@ -2884,8 +3203,7 @@ export declare interface SampleContourOptions {
 }
 
 /** Samples a planar curve with the same guarantees and policy as spatial sampling.
- * @remarks Private spatial scratch math is shared, while only final planar vectors are copied and
- * frozen. At stationary tangents, outgoing secants are preferred and endpoints use a backward fallback.
+ * @remarks Returned planar points and tangents are copied and frozen. At stationary tangents, outgoing secants are preferred and endpoints use a backward fallback.
  * @example
  * ```ts
  * const turn = sampleCurve2({kind: "arc", center: [0,0], radius: 10, sweepAngle: 90});
@@ -2925,9 +3243,9 @@ export declare function sampleCylindricalGearOutline(
 /** Immutable planar points and corresponding directed unit tangents. */
 export declare interface SampledCurve2 {
   /** Curves retain both endpoints, including full-circle seams; closed resampling omits its seam. */
-  readonly points: readonly Vector2Tuple[];
+  readonly points: readonly Vector2Data[];
   /** Directed unit vectors; stationary derivatives use the nearest usable direction. */
-  readonly tangents: readonly Vector2Tuple[];
+  readonly tangents: readonly Vector2Data[];
 }
 
 /**
@@ -2935,9 +3253,9 @@ export declare interface SampledCurve2 {
  */
 export declare interface SampledCurve3 {
   /** Curves retain both endpoints, including full-circle seams; closed resampling omits its seam. */
-  readonly points: readonly Vector3Tuple[];
+  readonly points: readonly Vector3Data[];
   /** Directed unit vectors; stationary derivatives use the nearest usable direction. */
-  readonly tangents: readonly Vector3Tuple[];
+  readonly tangents: readonly Vector3Data[];
 }
 
 /** Sampled paths plus conventional pitch and lead measurements. */
@@ -2945,7 +3263,7 @@ export declare interface SampledThreadHelices {
   /** Axial advance over one revolution, equal to `pitch * starts`. */
   readonly lead: number;
   /** One immutable sampled path for each thread start. */
-  readonly paths: readonly Path3Data[];
+  readonly paths: readonly (readonly Vector3Data[])[];
   /** Adjacent axial thread spacing in millimetres. */
   readonly pitch: number;
   /** Number of revolutions represented by each path. */
@@ -2954,6 +3272,7 @@ export declare interface SampledThreadHelices {
 
 /**
  * Creates `segments + 1` points including exact helix endpoints from finite positive dimensions.
+ *
  * Integrated weights must remain finite. The maxPathPoints ceiling defaults to 100000; excessive
  * exact counts reject before evaluating axial weights or allocating sample arrays.
  * Invalid inputs use GeometryError; exceptions thrown by axialWeight propagate unchanged.
@@ -2965,7 +3284,7 @@ export declare const sampleHelix: ({
   segments,
   limits,
   axialWeight,
-}: SampleHelixOptions) => readonly Vector3Tuple[];
+}: SampleHelixOptions) => readonly Vector3Data[];
 
 /** Options for a sampled +Z helix with millimetre dimensions. */
 export declare interface SampleHelixOptions {
@@ -3010,10 +3329,11 @@ export declare function sampleInternalCylindricalGearSpaceOutline(
 export declare function sampleRackToothPath(
   spec: RackPitchSpec,
   limits?: Partial<GeometrySamplingLimits>,
-): Path2Data;
+): readonly Vector2Data[];
 
 /**
  * Samples 1–31 line/cubic segments into a deeply immutable open [radius,height] polyline.
+ *
  * Anchors must progress strictly upward; nonnegative-radius cubic controls must have ordered
  * heights between their endpoints. Cubics use de Casteljau subdivision with a conservative
  * control-hull chord-error bound. Lines also obey the optional physical edge-length ceiling.
@@ -3036,7 +3356,7 @@ export declare function sampleRackToothPath(
 export declare function sampleSideProfile(
   curve: SideProfileCurve,
   options?: SampleSideProfileOptions,
-): readonly Vector2Tuple[];
+): readonly Vector2Data[];
 
 /** Physical scaling and bounded adaptive subdivision for an open profile. */
 export declare interface SampleSideProfileOptions {
@@ -3077,9 +3397,9 @@ export declare function sampleThreadHelices(
 
 /** Multiplies a vector by a dimensionless scalar. */
 export declare const scale2: (
-  vector: Vector2Tuple,
+  vector: Vector2Data,
   scale: number,
-) => Vector2Tuple;
+) => Vector2Data;
 
 /**
  * Multiplies a vector by a dimensionless scalar.
@@ -3089,9 +3409,9 @@ export declare const scale2: (
  * ```
  */
 export declare const scale3: (
-  vector: Vector3Tuple,
+  vector: Vector3Data,
   scale: number,
-) => Vector3Tuple;
+) => Vector3Data;
 
 /**
  * Creates an immutable axis-aligned scale transform.
@@ -3102,9 +3422,7 @@ export declare const scale3: (
  * @param factors - Finite, non-zero XYZ scale factors.
  * @returns A frozen row-major transform.
  */
-export declare function scaleTransform3(
-  factors: Vector3Tuple,
-): Transform3Matrix;
+export declare function scaleTransform3(factors: Vector3Data): Transform3Data;
 
 /** An open radius/height outline; consumers own closure, mounting geometry, and wall policy. */
 export declare interface SideProfileCurve {
@@ -3210,7 +3528,7 @@ export declare const starContour: (
   points: number,
   innerRadius?: number,
   limits?: Partial<GeometrySamplingLimits>,
-) => readonly Vector2Tuple[];
+) => readonly Vector2Data[];
 
 /** End-cap treatment for an open stroked path. */
 export declare type StrokeCap = "butt" | "round" | "square";
@@ -3248,10 +3566,7 @@ export declare function strokeRegionData(
 ): RegionData;
 
 /** Subtracts `b` from `a` component-wise. */
-export declare const subtract2: (
-  a: Vector2Tuple,
-  b: Vector2Tuple,
-) => Vector2Tuple;
+export declare const subtract2: (a: Vector2Data, b: Vector2Data) => Vector2Data;
 
 /**
  * Subtracts `b` from `a`.
@@ -3260,13 +3575,16 @@ export declare const subtract2: (
  * subtract3([4, 5, 6], [1, 2, 3]); // [3, 3, 3]
  * ```
  */
-export declare const subtract3: (
-  a: Vector3Tuple,
-  b: Vector3Tuple,
-) => Vector3Tuple;
+export declare const subtract3: (a: Vector3Data, b: Vector3Data) => Vector3Data;
 
 /** Sampling controls for deterministic SVG-to-region conversion. */
 export declare interface SvgImportOptions {
+  /**
+   * Uniformly fit painted bounds inside this positioned XY target in millimetres.
+   * Adaptive resolution describes the fitted size; exact circular counts retain precedence.
+   * Empty painted geometry cannot be fitted. Omitted preserves the document's physical size.
+   */
+  readonly fit?: Bounds2Input;
   /** Explicit profile and circular allocation ceilings; bounded SVG source/work limits remain fixed. */
   readonly limits?: Partial<GeometrySamplingLimits>;
   /** Exact segments for a complete ellipse or round stroke feature. */
@@ -3280,8 +3598,14 @@ export declare interface SvgImportOptions {
   readonly origin?: "center" | "document";
 }
 
-/** Exact normalized SVG region plus bounded source, geometry, and safe-repair diagnostics. */
+/** Normalized sampled SVG region plus bounded source, geometry, and safe-repair diagnostics. */
 export declare interface SvgRegionPreflight {
+  /**
+   * Applied scale and translation from origin-normalized SVG millimetres to final model
+   * millimetres, present only when a fit target was supplied. Reuse it for registered layers
+   * imported with the same origin and document coordinate system.
+   */
+  readonly fit?: BoundsFit2;
   /** Physical and final-topology measurements of `region`. */
   readonly geometry: SvgRegionPreflightGeometryMetrics;
   /** Appearance-preserving cleanup observed during parsing and normalization. */
@@ -3297,7 +3621,7 @@ export declare interface SvgRegionPreflightGeometryMetrics {
   /** Filled area in square millimetres. */
   readonly area: number;
   /** Millimetre bounds, or `null` when no painted region remains. */
-  readonly bounds: Bounds2 | null;
+  readonly bounds: Bounds2Data | null;
   /** Disconnected filled polygons in the final region. */
   readonly componentCount: number;
   /** Exterior and hole boundary count in the final region. */
@@ -3482,7 +3806,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;
@@ -3494,7 +3818,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;
@@ -3604,7 +3928,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;
 }
@@ -3682,32 +4006,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,
@@ -3719,6 +4044,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. */
@@ -3744,27 +4072,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.
@@ -3772,7 +4102,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,
@@ -3791,6 +4121,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;
+
 /**
  * Returns the determinant of a transform's linear 3x3 component.
  *
@@ -3800,7 +4133,7 @@ export declare type Transform3Matrix = readonly [
  * @returns Signed linear determinant.
  */
 export declare function transformDeterminant3(
-  transform: Transform3Matrix,
+  transform: Transform3Data,
 ): number;
 
 /**
@@ -3835,8 +4168,8 @@ export declare function transformTriangleMesh(
  * @returns A frozen row-major transform.
  */
 export declare function translationTransform3(
-  offset: Vector3Tuple,
-): Transform3Matrix;
+  offset: Vector3Data,
+): Transform3Data;
 
 /** Trapezoidal thread profile with a configurable included angle. */
 export declare interface TrapezoidalThreadProfileSpec extends ThreadProfileBaseSpec {
@@ -3888,7 +4221,7 @@ export declare interface TriangleMeshAnalysisOptions extends TriangleMeshValidat
  */
 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. */
@@ -3944,7 +4277,7 @@ export declare interface TriangleMeshQualityReport {
 /** Immutable deterministic measurements for a closed, oriented triangle mesh. */
 export declare interface TriangleMeshSignature {
   /** Axis-aligned bounds quantized by `tolerances.position`. */
-  readonly bounds: Bounds3;
+  readonly bounds: Bounds3Data;
   /** Number of edge-connected closed boundary shells; cavities count separately. */
   readonly connectedComponentCount: number;
   /** Total orientable genus across all connected components. */
@@ -4030,6 +4363,7 @@ export declare interface TubeOptions
 
 /**
  * Checks closed indexed topology, triangle intersections, and alternating nested shell orientation.
+ *
  * Outward exterior shells and inward cavity shells are accepted. Separate shells must not touch,
  * intersect, or overlap as material. Indexed neighbours may share their own vertex or edge.
  *
@@ -4056,9 +4390,9 @@ export declare function validateSolidMesh(
  * @throws {@link GeometryError} For non-finite, non-affine, or singular matrices.
  */
 export declare function validateTransform3(
-  transform: Transform3Matrix,
+  transform: Transform3Data,
   tolerance?: GeometryToleranceOptions,
-): Transform3Matrix;
+): Transform3Data;
 
 /**
  * Validates mesh buffers, indices, triangle area, and optionally closed topology.
@@ -4102,22 +4436,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 {
@@ -4146,15 +4484,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);
@@ -4163,11 +4505,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;
 
 /** A circular baseline centered at the XY origin, with rigid shaped glyph groups. */
 export declare interface VectorTextArcBaseline {
@@ -4208,7 +4550,7 @@ export declare interface VectorTextLayoutOptions extends VectorTextOptions {
 /** 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. */