@metamesh/modeling 0.18.0 → 0.20.0

package/dist/api/mesh.d.ts

@@ -1,64 +1,40 @@
 import type {
-  Bounds3Data,
-  ExtrudeMeshOptions,
-  HeightfieldMeshLimits,
-  HeightfieldOptions,
-  HeightfieldPreflight,
-  ImmutableTriangleMesh,
-  LoftMeshStation,
-  LoftOptions,
-  Path2Input,
-  Path3Input,
-  PlanarMeshOptimizationOptions,
-  PlanarMeshOptimizationResult,
-  RevolveOptions,
-  SolidMeshValidationOptions,
-  SweepOptions,
-  ThreadRidgeOptions,
-  ThreadSolidOptions,
-  ThreadSolidPreflight,
-  Transform3Input,
-  TriangleMesh,
-  TriangleMeshAnalysis,
-  TriangleMeshAnalysisOptions,
-  TriangleMeshInput,
-  TriangleMeshQualityOptions,
-  TriangleMeshQualityReport,
-  TriangleMeshSignature,
-  TriangleMeshSignatureOptions,
-  TriangleMeshTopologyAnalysis,
-  TriangleMeshValidationOptions,
-  Vector3Data,
-} from "@metamesh/modeling/geometry";
-export type {
   AcmeThreadProfileSpec,
   Bevel,
   BevelSize,
+  ButtressPressureFlankSide,
+  ButtressThreadProfileSpec,
+  CustomThreadProfileSpec,
+  SquareThreadProfileSpec,
+  ThreadEndStyle,
+  ThreadEndTreatmentOptions,
+  ThreadHandedness,
+  ThreadLeadInEnvelope,
+  ThreadLeadInShape,
+  ThreadProfile,
+  ThreadProfileBaseSpec,
+  ThreadProfileSpec,
+  ThreadRidgeOptions,
+  ThreadSolidOptions,
+  ThreadSolidPreflight,
+  TrapezoidalThreadProfileSpec,
+  TriangularThreadProfileSpec,
+} from "@metamesh/modeling/geometry/mechanical";
+import type {
   Bounds2,
   Bounds2Data,
   Bounds2Input,
   Bounds3,
   Bounds3Data,
   Bounds3Input,
-  ButtressPressureFlankSide,
-  ButtressThreadProfileSpec,
   CircularPrimitiveOptions,
   CurveSamplingOptions,
-  CustomThreadProfileSpec,
-  ExtrudeMeshOptions,
   ExtrusionSamplingOptions,
   Frame3,
   GeometryResolution,
   GeometrySamplingLimits,
   GeometryToleranceOptions,
-  HeightfieldMeshLimits,
-  HeightfieldOptions,
-  HeightfieldPreflight,
   ImmutableBuffer,
-  ImmutableTriangleMesh,
-  LoftCorrespondence,
-  LoftMeshStation,
-  LoftOptions,
   LoftPlacement,
   ModelingLimits,
   NumericArray,
@@ -71,48 +47,16 @@ export type {
   PathLocation,
   PathNormalGuide,
   PathResamplingOptions,
+  PathStation,
+  PathSubdivisionOptions,
   Pivot2Options,
   Pivot3Options,
-  PlanarMeshOptimizationFallbackReason,
-  PlanarMeshOptimizationOptions,
-  PlanarMeshOptimizationResult,
-  PlanarPatchQuality,
-  RevolveOptions,
-  SolidMeshValidationOptions,
-  SquareThreadProfileSpec,
-  SweepOptions,
-  SweepOrientation,
-  ThreadEndStyle,
-  ThreadEndTreatmentOptions,
-  ThreadHandedness,
-  ThreadLeadInEnvelope,
-  ThreadLeadInShape,
-  ThreadProfile,
-  ThreadProfileBaseSpec,
-  ThreadProfileSpec,
-  ThreadRidgeOptions,
-  ThreadSolidOptions,
-  ThreadSolidPreflight,
   Transform2,
   Transform2Data,
   Transform2Input,
   Transform3,
   Transform3Data,
   Transform3Input,
-  TrapezoidalThreadProfileSpec,
-  TriangleMesh,
-  TriangleMeshAnalysis,
-  TriangleMeshAnalysisOptions,
-  TriangleMeshInput,
-  TriangleMeshMeasurements,
-  TriangleMeshQualityOptions,
-  TriangleMeshQualityReport,
-  TriangleMeshSignature,
-  TriangleMeshSignatureOptions,
-  TriangleMeshSignatureTolerances,
-  TriangleMeshTopologyAnalysis,
-  TriangleMeshValidationOptions,
-  TriangularThreadProfileSpec,
   Vector2,
   Vector2Data,
   Vector2Input,
@@ -120,6 +64,15 @@ export type {
   Vector3Data,
   Vector3Input,
 } from "@metamesh/modeling/geometry";
+import type {
+  HeightfieldOptions,
+  LoftCorrespondence,
+  LoftOptions,
+  RevolveOptions,
+  SweepOptions,
+  SweepOrientation,
+  SweepTransformOptions,
+} from "@metamesh/modeling";
 
 /**
  * Validates and measures a mesh with one pass over positions and one over triangles.
@@ -130,6 +83,9 @@ export type {
  * every position vertex to be referenced and do not establish freedom from self-intersections.
  * Results and nested bounds are immutable snapshots. Caller-owned mutable meshes are freshly
  * inspected on every call, never cached.
+ *
+ * @param mesh - Indexed triangle buffers in consistent units; source buffers remain unchanged.
+ * @param options - Validation policy with indexed edge and shell counts explicitly requested.
  */
 export declare function analyze(
   mesh: TriangleMeshInput,
@@ -138,7 +94,12 @@ export declare function analyze(
   },
 ): TriangleMeshTopologyAnalysis;
 
-/** Measures a mesh; topology fields are present only when includeTopology is enabled. */
+/**
+ * Measures a mesh; topology fields are present only when includeTopology is enabled.
+ *
+ * @param mesh - Indexed triangle buffers in consistent units; source buffers remain unchanged.
+ * @param options - Validation policy and optional indexed edge and shell counts.
+ */
 export declare function analyze(
   mesh: TriangleMeshInput,
   options?: TriangleMeshAnalysisOptions,
@@ -151,7 +112,7 @@ export declare function analyze(
  * Degenerate triangles are reported rather than rejected, while malformed buffers, non-finite
  * positions, missing vertex references, and the configured complexity limit throw.
  *
- * @param mesh - Indexed triangle mesh in arbitrary consistent model units.
+ * @param mesh - Indexed triangle mesh in consistent units.
  * @param options - Scale-aware tolerance and analysis budget.
  * @returns A deterministic report without mutating or copying the mesh.
  */
@@ -186,6 +147,8 @@ export declare function centroid(mesh: TriangleMeshInput): Vector3Data;
  * Path2 profiles must be closed; raw point collections have an implicit closing edge.
  * End treatments are unsupported and reject at runtime. Use Section.extrude for finished ends.
  *
+ * @param input - Closed XY path or simple contour, in millimetres.
+ *
  * @example Extrude point data without an engine
  * ```ts
  * const outline = rectangleContour({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
@@ -197,6 +160,14 @@ export declare function extrude(
   options: ExtrudeMeshOptions,
 ): TriangleMesh;
 
+/** Dimensions and sampling for pure +Z mesh extrusion, without end treatments. */
+export declare interface ExtrudeMeshOptions extends ExtrusionSamplingOptions {
+  /** Positive extrusion height in millimetres. */
+  readonly height: number;
+  /** Center the extrusion on Z; otherwise its bottom is at zero. Defaults to false. */
+  readonly center?: boolean;
+}
+
 /**
  * Builds a closed indexed mesh from a rectilinear top, matched boundary walls, and flat base.
  *
@@ -204,6 +175,8 @@ export declare function extrude(
  * 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.
  *
+ * @param options - Grid and absolute height callback in millimetres.
+ *
  * @see `mesh.preflightHeightfield`
  *
  * @example Sample a closed wavy mesh
@@ -219,18 +192,36 @@ export declare function heightfield(
   limits?: HeightfieldMeshLimits,
 ): TriangleMesh;
 
+/** Trusted output ceilings for pure construction; omitted fields use package defaults. */
+export declare type HeightfieldMeshLimits = Partial<
+  Pick<ModelingLimits, "maxVertices" | "maxTriangles" | "maxBytes">
+>;
+
+/** Exact grid and mesh buffer allocation counts resolved without evaluating the height callback. */
+export declare interface HeightfieldPreflight {
+  /** 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, excluding temporary storage. */
+  readonly byteCount: number;
+}
+
 /**
  * Copies mesh buffers into immutable data; geometric validation still occurs when modeling or finalizing.
+ *
+ * @param mesh - Triangle buffers to copy; the consumer validates topology.
+ *
  * @example
  * ```ts
  * import { generate } from "@metamesh/modeling";
  * import * as mesh from "@metamesh/modeling/geometry/mesh";
- * const model = generate(({ computed, part }) => {
- *   const surface = computed("surface", () => mesh.immutable(mesh.heightfield({
- *     size: [10, 10], segments: [8, 8], height: () => 2,
- *   })));
- *   return [part("surface", surface)];
- * });
+ * const buildSurface = () => mesh.immutable(mesh.heightfield({
+ *   size: [10, 10], segments: [8, 8], height: () => 2,
+ * }));
+ * const model = generate(({ memo, part }) => part("surface", memo(buildSurface)));
  * ```
  */
 export declare function immutable(mesh: {
@@ -238,6 +229,16 @@ export declare function immutable(mesh: {
   readonly indices: Uint32Array;
 }): ImmutableTriangleMesh;
 
+declare const immutableBufferBrand: unique symbol;
+
+/** Immutable local XYZ positions and triangle indices, suitable for a memo result or part. */
+export declare interface ImmutableTriangleMesh {
+  /** Packed XYZ coordinates in millimetres. */
+  readonly positions: ImmutableBuffer<Float32Array>;
+  /** Zero-based vertex indices, three per triangle. */
+  readonly indices: ImmutableBuffer<Uint32Array>;
+}
+
 /**
  * Concatenates meshes into one indexed mesh without welding coincident vertices.
  *
@@ -252,15 +253,17 @@ export declare function join(
 ): TriangleMesh;
 
 /**
- * Lofts simple point loops at z heights or explicit right-handed frames, in input order.
+ * Lofts simple point contours at z heights or explicit affine transforms, in input order.
  *
- * Correspondence defaults to direct. CCW-normalized loops retain their
+ * Correspondence defaults to direct. CCW-normalized contours retain their
  * seam and original vertices; unequal counts gain subdivisions or repeated fan slots.
  * Both ends use ear-clipped caps, supporting concave profiles without center fans.
  * Intermediate slices interpolate placed world vertices, never frame axes.
  * Transformed coordinates must fit finite Float32 mesh storage.
  * Path2 profiles must be closed; raw point collections are interpreted as closed.
  *
+ * @param stations - At least two XY profiles in connection order, each with Z height or affine placement.
+ *
  * @example Loft with explicit point correspondence
  * ```ts
  * const bottom = rectangleContour({ size: [20, 12] });
@@ -273,6 +276,18 @@ export declare function loft(
   options?: LoftOptions,
 ): TriangleMesh;
 
+/** One point-data profile at a horizontal height or explicit affine transform. */
+export declare type LoftMeshStation = LoftPlacement & {
+  /** Closed Path2 or ordered finite XY boundary points with an implicit closing edge. */
+  readonly profile: Path2Input;
+};
+
+/** Shading policy for a render copy; manufacturing positions and triangle order never change. */
+export declare interface MeshRenderOptions {
+  /** Maximum angle between averaged face normals, in degrees. Defaults to `20`; `0` is flat. */
+  readonly creaseAngle?: number;
+}
+
 /**
  * Improves pathological planar triangulation with bounded legal diagonal flips.
  *
@@ -283,7 +298,7 @@ export declare function loft(
  * original raw mesh object. Immutable inputs produce owned raw output buffers, including unchanged
  * results. Malformed buffers and the configured analysis complexity limit throw.
  *
- * @param mesh - Closed, consistently wound indexed triangle mesh in arbitrary consistent units.
+ * @param mesh - Closed, consistently wound mesh in consistent units.
  * @param options - Patch eligibility, numeric tolerance, and deterministic work bounds.
  * @returns Optimized connectivity and before/after diagnostics, or an unchanged safe fallback.
  */
@@ -292,6 +307,95 @@ export declare function optimizePlanarPatches(
   options?: PlanarMeshOptimizationOptions,
 ): PlanarMeshOptimizationResult;
 
+/** Stable reason why planar optimization preserved the original connectivity. */
+export declare type PlanarMeshOptimizationFallbackReason =
+  | "candidate-boundary-changed"
+  | "candidate-measurements-changed"
+  | "candidate-not-closed-oriented-manifold"
+  | "candidate-quality-regressed"
+  | "input-not-closed-oriented-manifold";
+
+/** Options controlling bounded, connectivity-only optimization of planar triangle patches. */
+export declare interface PlanarMeshOptimizationOptions extends TriangleMeshQualityOptions {
+  /**
+   * Maximum attempted edge evaluations. By default this is twenty times the initial candidate
+   * edge count, capped at `1000000`.
+   */
+  readonly maxFlipAttempts?: number;
+  /** Maximum times one edge may be reconsidered after neighbouring flips. Defaults to `12`. */
+  readonly maxEdgeRevisits?: number;
+  /** Maximum triangles allowed in one selected patch. Defaults to `50000`. */
+  readonly maxPatchTriangles?: number;
+  /** Maximum cumulative triangles across selected patches. Defaults to `200000`. */
+  readonly maxProcessedTriangles?: number;
+  /** Minimum triangles required before a planar patch is eligible. Defaults to `8`. */
+  readonly minPatchTriangles?: number;
+  /** Select patches whose worst normalized aspect ratio exceeds this value. Defaults to `12`. */
+  readonly triggerMaxAspectRatio?: number;
+  /** Select patches whose largest per-vertex triangle share exceeds this ratio. Defaults to `0.2`. */
+  readonly triggerMaxFanRatio?: number;
+  /** Select patches whose largest vertex triangle incidence exceeds this value. Defaults to `16`. */
+  readonly triggerMaxVertexTriangleIncidence?: number;
+  /** Select patches whose smallest interior angle is below this many degrees. Defaults to `8`. */
+  readonly triggerMinAngleDegrees?: number;
+}
+
+/** Outcome of bounded planar-patch optimization, including before/after diagnostics. */
+export declare interface PlanarMeshOptimizationResult {
+  /** Quality report for the returned mesh; equal to `before` on unchanged or fallback results. */
+  readonly after: TriangleMeshQualityReport;
+  /** Quality report for the supplied mesh. */
+  readonly before: TriangleMeshQualityReport;
+  /** Whether a work bound stopped evaluation while eligible work remained. */
+  readonly budgetExhausted: boolean;
+  /** Whether the returned mesh has different triangle connectivity. */
+  readonly changed: boolean;
+  /** Safety reason when candidate validation rejected optimization or input topology was unsupported. */
+  readonly fallbackReason?: PlanarMeshOptimizationFallbackReason;
+  /** Number of accepted legal diagonal flips. */
+  readonly flipCount: number;
+  /** Returned mesh; unchanged raw inputs retain their identity, while immutable inputs produce owned buffers. */
+  readonly mesh: TriangleMesh;
+  /** Number of planar patches in which at least one edge was flipped. */
+  readonly optimizedPatchCount: number;
+  /** Number of triggered patches omitted because a configured triangle bound would be exceeded. */
+  readonly skippedPatchCount: number;
+}
+
+/** Quality measurements for one edge-connected coplanar triangle patch. */
+export declare interface PlanarPatchQuality {
+  /** Number of edges separating this patch from another plane or the mesh boundary. */
+  readonly boundaryEdgeCount: number;
+  /** Number of connected boundary loops; holes contribute additional loops. */
+  readonly boundaryLoopCount: number;
+  /** Maximum ratio of one vertex's incident patch triangles to the patch triangle count. */
+  readonly fanRatio: number;
+  /** Lowest source triangle index in this deterministic patch. */
+  readonly firstTriangleIndex: number;
+  /** Stable zero-based patch identifier in first-triangle order. */
+  readonly id: number;
+  /** Number of edges shared by two triangles within this patch. */
+  readonly internalEdgeCount: number;
+  /** Largest normalized triangle aspect ratio; an equilateral triangle has ratio `1`. */
+  readonly maximumTriangleAspectRatio: number;
+  /** Largest number of patch triangles incident to one vertex. */
+  readonly maximumVertexTriangleIncidence: number;
+  /** Largest number of distinct patch neighbours connected to one vertex. */
+  readonly maximumVertexValence: number;
+  /** Smallest interior triangle angle in degrees. */
+  readonly minimumTriangleAngleDegrees: number;
+  /** Consistently wound unit normal for the patch plane. */
+  readonly normal: Vector3Data;
+  /** Plane offset in `dot(normal, position) = planeOffset` form, in model units. */
+  readonly planeOffset: number;
+  /** Total patch area in squared model units. */
+  readonly surfaceArea: number;
+  /** Number of triangles in this patch. */
+  readonly triangleCount: number;
+  /** Number of distinct indexed vertices referenced by this patch. */
+  readonly vertexCount: number;
+}
+
 /**
  * Checks grid options, Float32 axis precision, and output limits; returns exact mesh buffer counts.
  *
@@ -299,6 +403,8 @@ export declare function optimizePlanarPatches(
  * Successful preflight leaves height values, Float32 base storage, and generated mesh validity to
  * construction. `byteCount` covers position and index buffers, not total working memory.
  *
+ * @param options - Grid in millimetres; the height callback is not evaluated.
+ *
  * @see `mesh.heightfield`
  */
 export declare function preflightHeightfield(
@@ -314,11 +420,40 @@ export declare function preflightHeightfield(
  * Successful preflight leaves generated coordinate and topology checks to mesh construction.
  *
  * See `mesh.threadSolid` for standalone mesh construction.
+ *
+ * @param options - Dimensions in millimetres and a validated profile; apply any fit compensation first.
  */
 export declare function preflightThreadSolid(
   options: ThreadSolidOptions,
 ): ThreadSolidPreflight;
 
+/**
+ * Builds crease-aware render buffers without moving or merging distinct positions.
+ * Face normals are averaged only at exactly coincident positions within the crease angle.
+ * Returns owned buffers; every triangle retains its coordinates, order and winding.
+ * Pathological vertex fans exceeding 50 million normal comparisons reject with a complexity error.
+ *
+ * @param input - Indexed mesh to copy; source buffers remain unchanged.
+ *
+ * @example
+ * ```ts
+ * import * as mesh from "@metamesh/modeling/geometry/mesh";
+ * const surface = mesh.heightfield({ size: [10, 10], segments: [2, 2], height: () => 0 });
+ * const rendered = mesh.render(surface);
+ * // rendered.positions and rendered.normals can be passed to a renderer or GLB writer.
+ * ```
+ */
+export declare function render(
+  input: TriangleMeshInput,
+  options?: MeshRenderOptions,
+): RenderMesh;
+
+/** Owned indexed render buffers with unit vertex normals and positions in millimetres. */
+export declare interface RenderMesh extends TriangleMesh {
+  /** XYZ unit normals, one for each render vertex. Vertices split at shading discontinuities. */
+  readonly normals: Float32Array;
+}
+
 /**
  * Returns a copy of a mesh with every triangle winding reversed.
  *
@@ -338,8 +473,7 @@ export declare function reverse(mesh: TriangleMeshInput): TriangleMesh;
  * Profile coordinates must fit finite Float32 mesh storage.
  * Path2 profiles must be closed; raw point collections have an implicit closing edge.
  *
- * @param profile - Closed CCW `[radius, z]` profile without a duplicated seam point.
- * @param options - Optional physical or exact circumferential sampling controls. Defaults to `{}`.
+ * @param input - Closed `[radius, Z]` profile in millimetres; radii must be non-negative.
  * @returns A closed indexed triangle mesh revolved counter-clockwise around +Z.
  *
  * @example Partial revolution with end caps
@@ -370,8 +504,21 @@ export declare function signature(
   options?: TriangleMeshSignatureOptions,
 ): TriangleMeshSignature;
 
+/** Bounded floating-point intersection and shell-orientation validation settings. */
+export declare interface SolidMeshValidationOptions {
+  /** Work ceiling for spatial comparisons and containment tests; defaults to 2,000,000 and may only lower it. */
+  readonly maxTests?: number;
+  /** Distance comparison policy in millimetres; near contacts reject conservatively. */
+  readonly tolerance?: GeometryToleranceOptions;
+}
+
 /**
- * Sweeps one explicitly ordered point loop, with caps or a geometrically matching closed seam.
+ * Sweeps one ordered point loop along a path or explicit affine placements.
+ * Path mode computes orientation and deformation, automatically matching compatible closed seams.
+ * Transform mode connects only the supplied stations, preserving profile indices without refinement.
+ *
+ * @param profile - Closed XY path or simple contour, in millimetres.
+ * @param path - Ordered XYZ path in millimetres; a Path3 supplies its closure.
  *
  * @example Sweep point data along a bent path
  * ```ts
@@ -387,10 +534,24 @@ export declare function sweep(
   options?: SweepOptions,
 ): TriangleMesh;
 
+/**
+ * Connects one point loop through exactly the supplied affine placements.
+ *
+ * @param profile - Closed XY path or simple contour, in millimetres.
+ * @param transforms - Affine placements in connection order; at least two when open, three when closed.
+ */
+export declare function sweep(
+  profile: Path2Input,
+  transforms: readonly Transform3Input[],
+  options?: SweepTransformOptions,
+): TriangleMesh;
+
 /**
  * Builds closed thread-ridge components with every profile locked to the
  * shaft's radial/axial frame. The mesh is intended for union with its
  * minor-envelope cylinder and never owns WASM objects.
+ *
+ * @param options - Dimensions in millimetres and a validated profile; apply any fit compensation first.
  */
 export declare function threadRidge(options: ThreadRidgeOptions): TriangleMesh;
 
@@ -402,6 +563,8 @@ export declare function threadRidge(options: ThreadRidgeOptions): TriangleMesh;
  * monotone strip, with optional intermediate rows bounded by physical `maxSegmentLength`. A
  * conservative pre-allocation estimate rejects excessive meshes before constructing position
  * arrays.
+ *
+ * @param options - Dimensions in millimetres and a validated profile; apply any fit compensation first.
  */
 export declare function threadSolid(options: ThreadSolidOptions): TriangleMesh;
 
@@ -412,7 +575,7 @@ export declare function threadSolid(options: ThreadSolidOptions): TriangleMesh;
  * automatically reverses every triangle. Singular transforms are rejected.
  *
  * @param mesh - Mesh to transform without mutation.
- * @param placement - Immutable spatial placement or canonical row-major affine matrix.
+ * @param placement - Frame, fluent transform, or row-major affine matrix.
  * @returns A mesh with fresh transformed positions and copied or reversed indices.
  */
 export declare function transform(
@@ -420,6 +583,144 @@ export declare function transform(
   placement: Transform3Input,
 ): TriangleMesh;
 
+/** A topology-preserving indexed triangle mesh with mutable owned XYZ buffers. */
+export declare interface TriangleMesh {
+  /** Three unsigned vertex indices per triangle. */
+  readonly indices: Uint32Array;
+  /** Flat XYZ coordinates in millimetres. */
+  readonly positions: Float32Array;
+}
+
+/** Measurements and optional edge-connected topology from one validated mesh traversal. */
+export declare interface TriangleMeshAnalysis extends TriangleMeshMeasurements {
+  /** Number of surface shells connected by shared indexed edges when includeTopology is requested.
+   * Cavities count separately; shells may be open unless requireClosed is enabled. Coordinates are not welded. */
+  readonly shellCount?: number;
+  /** Number of distinct indexed undirected edges when `includeTopology` is requested. */
+  readonly edgeCount?: number;
+}
+
+/** Validation and optional connectivity controls for a shared mesh analysis. */
+export declare interface TriangleMeshAnalysisOptions extends TriangleMeshValidationOptions {
+  /** Compute indexed edge/shell counts and reject unreferenced vertices; defaults to false. */
+  readonly includeTopology?: boolean;
+}
+
+/** Raw construction buffers or immutable captured geometry accepted by mesh utilities. */
+export declare type TriangleMeshInput = TriangleMesh | ImmutableTriangleMesh;
+
+/** Geometric measurements derived from a validated, non-empty triangle mesh. */
+export declare interface TriangleMeshMeasurements {
+  /** Axis-aligned bounds. */
+  readonly bounds: Bounds3Data;
+  /** Signed enclosed volume in cubic model units; positive values correspond to outward winding. */
+  readonly signedVolume: number;
+  /** Sum of all triangle areas in squared model units. */
+  readonly surfaceArea: number;
+  /** Number of indexed triangles. */
+  readonly triangleCount: number;
+  /** Number of distinct entries in the position buffer. */
+  readonly vertexCount: number;
+}
+
+/** Options controlling bounded triangle-mesh quality analysis. */
+export declare interface TriangleMeshQualityOptions {
+  /** Maximum number of triangles inspected. Defaults to `200000`. */
+  readonly maxTriangles?: number;
+  /** Numeric comparison overrides; model coordinates are interpreted in their existing units. */
+  readonly tolerance?: GeometryToleranceOptions;
+}
+
+/** Structural, topological, and planar-patch measurements for one indexed triangle mesh. */
+export declare interface TriangleMeshQualityReport {
+  /** Number of duplicate triangles beyond their first unordered occurrence. */
+  readonly duplicateTriangleCount: number;
+  /** Number of two-face edges whose incident triangles use the same direction. */
+  readonly inconsistentWindingEdgeCount: number;
+  /** Whether the mesh has valid faces and exactly two oppositely wound faces at every edge. */
+  readonly isClosedOrientedManifold: boolean;
+  /** Largest normalized triangle aspect ratio; an equilateral triangle has ratio `1`. */
+  readonly maximumTriangleAspectRatio: number;
+  /** Largest number of triangles incident to one indexed vertex. */
+  readonly maximumVertexTriangleIncidence: number;
+  /** Largest number of distinct neighbours connected to one indexed vertex. */
+  readonly maximumVertexValence: number;
+  /** Smallest interior triangle angle in degrees. */
+  readonly minimumTriangleAngleDegrees: number;
+  /** Number of triangles at or below the scale-aware zero-area threshold. */
+  readonly nearZeroAreaTriangleCount: number;
+  /** Number of edges with more than two incident triangles. */
+  readonly nonManifoldEdgeCount: number;
+  /** Number of edges with exactly one incident triangle. */
+  readonly openEdgeCount: number;
+  /** Edge-connected coplanar patches in deterministic first-triangle order. */
+  readonly planarPatches: readonly PlanarPatchQuality[];
+  /** Signed enclosed volume in cubic model units; positive values indicate outward winding. */
+  readonly signedVolume: number;
+  /** Total triangle area in squared model units. */
+  readonly surfaceArea: number;
+  /** Number of indexed triangles. */
+  readonly triangleCount: number;
+  /** Number of entries in the position buffer. */
+  readonly vertexCount: number;
+}
+
+/** Immutable deterministic measurements for a closed, oriented triangle mesh. */
+export declare interface TriangleMeshSignature {
+  /** Axis-aligned bounds quantized by `tolerances.position`. */
+  readonly bounds: Bounds3Data;
+  /** Number of edge-connected closed boundary shells; cavities count separately. */
+  readonly shellCount: number;
+  /** Total orientable genus across all connected components. */
+  readonly genus: number;
+  /** Order-independent hash of quantized vertices and oriented triangles. */
+  readonly fingerprint: string;
+  /** Signed enclosed volume quantized by `tolerances.signedVolume`. */
+  readonly signedVolume: number;
+  /** Quantization used to make the signature stable across insignificant numeric drift. */
+  readonly tolerances: TriangleMeshSignatureTolerances;
+  /** Number of indexed triangles. */
+  readonly triangleCount: number;
+  /** Number of referenced position-buffer vertices. */
+  readonly vertexCount: number;
+}
+
+/** Options controlling deterministic triangle-mesh regression signatures. */
+export declare interface TriangleMeshSignatureOptions {
+  /** Maximum accepted triangle count. Defaults to 200,000. */
+  readonly maxTriangles?: number;
+  /** Position and bounds quantization in model units. Defaults to `1e-5`. */
+  readonly positionTolerance?: number;
+  /** Signed-volume quantization in cubic model units. Defaults to `1e-4`. */
+  readonly volumeTolerance?: number;
+}
+
+/** Absolute tolerances recorded in a triangle-mesh regression signature. */
+export declare interface TriangleMeshSignatureTolerances {
+  /** Position and bounds quantization in model units. */
+  readonly position: number;
+  /** Signed-volume quantization in cubic model units. */
+  readonly signedVolume: number;
+}
+
+/** Mesh measurements with the indexed surface-shell and edge counts requested by includeTopology. */
+export declare interface TriangleMeshTopologyAnalysis extends TriangleMeshAnalysis {
+  /** Number of surface shells connected by shared indexed edges; cavities count separately. */
+  readonly shellCount: number;
+  /** Number of distinct indexed undirected edges. */
+  readonly edgeCount: number;
+}
+
+/** Options controlling structural and manufacturing validation of a mesh. */
+export declare interface TriangleMeshValidationOptions {
+  /** Permit an empty position and index buffer. Defaults to `false`. */
+  readonly allowEmpty?: boolean;
+  /** Require two oppositely wound faces per edge; geometric self-intersections are not detected. */
+  readonly requireClosed?: boolean;
+  /** Numeric comparison overrides used for zero-area triangle detection. */
+  readonly tolerance?: GeometryToleranceOptions;
+}
+
 /**
  * Validates mesh buffers, indices, triangle area, and optionally closed topology.
  *
@@ -427,7 +728,7 @@ export declare function transform(
  * and non-manifold edges. It establishes edge connectivity without detecting geometric
  * self-intersections between faces. The mesh is neither mutated nor copied.
  *
- * @param mesh - Mesh to inspect.
+ * @param mesh - Raw or captured indexed buffers with complete finite XYZ vertices.
  * @param options - Empty-mesh, topology, and tolerance policy.
  * @returns The original mesh after successful validation.
  * @throws `GeometryError` When any requested invariant fails.
@@ -449,7 +750,7 @@ export declare function validate<T extends TriangleMeshInput>(
  * Input buffers are freshly inspected and never modified; units are millimetres.
  *
  * @param mesh - Closed triangle mesh to inspect.
- * @param options - Optional lower work ceiling and numeric comparison policy.
+ * @param options - Lower work limit and tolerance for numeric comparisons.
  * @returns The original mesh after every requested check succeeds.
  */
 export declare function validateSolid<T extends TriangleMeshInput>(