@metamesh/modeling 0.14.0 → 0.16.0

package/dist/api/index.d.ts

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