@metamesh/modeling 0.19.0 → 0.20.0

package/dist/geometry/mechanical/threads/mesh.js

@@ -1,7 +1,8 @@
 /** Closed ridge and complete-solid mesh construction from resolved thread plans. */
-import { triangulateContour } from "../../loft/loft.js";
-import { analyzeTriangleMesh, joinTriangleMeshes, reverseTriangleMesh, validateTriangleMesh, } from "../../mesh/mesh.js";
-import { assertMeshAllocationWithinLimits, resolveModelingLimits } from "../../model-limits.js";
+import { assertMeshAllocationWithinLimits, resolveModelingLimits } from "../../limits.js";
+import { analyzeTriangleMesh, joinTriangleMeshes, } from "../../mesh/operations.js";
+import { reverseOwnedTriangleWinding } from "../../mesh/winding.js";
+import { triangulateContour } from "../../regions/triangulation.js";
 import { resolveHelicalThreadMeshOptions, resolveHelicalThreadSolidMeshPreflight, } from "./mesh-plan.js";
 import { buildThreadSurfaceColumn, stitchThreadSurfaceColumns } from "./surface.js";
 const MINIMUM_TAPERED_RIDGE_HEIGHT = 0.0005;
@@ -56,13 +57,12 @@ const buildThreadRidgeComponent = (options) => {
     };
     cap(0, false);
     cap(spans, true);
-    let mesh = {
+    const mesh = {
         positions: new Float32Array(positions),
         indices: new Uint32Array(indices),
     };
-    validateTriangleMesh(mesh, { requireClosed: true });
     if (analyzeTriangleMesh(mesh, { requireClosed: true }).signedVolume < 0)
-        mesh = reverseTriangleMesh(mesh);
+        reverseOwnedTriangleWinding(mesh.indices);
     return mesh;
 };
 /**
@@ -73,6 +73,8 @@ const buildThreadRidgeComponent = (options) => {
  * 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 function threadSolidMesh(options) {
     const operation = "threadSolidMesh";
@@ -98,13 +100,12 @@ export function threadSolidMesh(options) {
         indices.push(bottomCenter, nextBottom, bottom, topCenter, top, nextTop);
     }
     assertMeshAllocationWithinLimits(positions.length / 3, indices.length / 3, (positions.length + indices.length) * 4, operation, resolveModelingLimits(options.limits));
-    let mesh = {
+    const mesh = {
         positions: new Float32Array(positions),
         indices: new Uint32Array(indices),
     };
-    validateTriangleMesh(mesh, { requireClosed: true });
     if (analyzeTriangleMesh(mesh, { requireClosed: true }).signedVolume < 0) {
-        mesh = reverseTriangleMesh(mesh);
+        reverseOwnedTriangleWinding(mesh.indices);
     }
     return mesh;
 }
@@ -112,6 +113,8 @@ export function threadSolidMesh(options) {
  * 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 function threadRidgeMesh(options) {
     const operation = "threadRidgeMesh";

package/dist/geometry/mechanical/threads/profiles.js

@@ -1,6 +1,6 @@
 /** Periodic thread profiles and axial/radial fit compensation. */
 import { GeometryError } from "../../errors.js";
-import { triangulateContour } from "../../loft/loft.js";
+import { triangulateContour } from "../../regions/triangulation.js";
 import { resolveGeometryTolerance } from "../../tolerance.js";
 const BUTTRESS_DEFAULT_DEPTH_RATIO = 0.66271;
 const BUTTRESS_CREST_FLAT_RATIO = 0.16316;
@@ -11,9 +11,13 @@ export const MAX_THREAD_PROFILE_POINTS = 1_024;
 /**
  * Applies axial fit allowance to a validated periodic profile.
  *
- * Male crests/ridges narrow by the requested backlash; female cutter ridges
- * widen by it. Periodic root endpoints remain fixed so pitch and lead do not
- * change. The returned profile is a new deeply immutable value.
+ * Each flank moves by one quarter of the mating pair's total backlash: male ridges narrow and
+ * female cutter ridges widen. Periodic root endpoints remain fixed, preserving pitch and lead.
+ * Changed profiles are deeply immutable; zero backlash returns the input unchanged.
+ *
+ * @param profile - Validated `[axial, radial]` profile in millimetres.
+ * @param axialBacklash - Nonnegative total pair allowance in millimetres, below half the pitch.
+ * @param role - Male ridge to narrow or female cutter ridge to widen.
  */
 export function compensateThreadProfileAxially(profile, axialBacklash, role) {
     const operation = "compensateThreadProfileAxially";
@@ -92,6 +96,12 @@ export function scaleThreadProfileRadially(profile, scale) {
  * This helper distributes the full conservative flank clearance between the male crest and female
  * root according to their available flat widths, and rejects a resolution that cannot represent
  * it exactly.
+ *
+ * @param profile - Uncompensated `[axial, radial]` profile in millimetres.
+ * @param axialBacklash - Nonnegative total pair allowance in millimetres, below half the pitch.
+ * @param role - Male ridge or female cutter receiving its share of the allowances.
+ * @param starts - Integer start count from 1 through 32.
+ * @param circularSegments - Full-circle facet count, at least 3 and divisible by starts.
  */
 export function compensateThreadProfileForFaceting(profile, axialBacklash, role, starts, circularSegments) {
     const operation = "compensateThreadProfileForFaceting";
@@ -235,8 +245,12 @@ const standardProfile = (kind, pitch, depth, root, crest, leftRun, rightRun) =>
  * values point toward the shaft. Custom paths must be finite, axially
  * non-decreasing, periodic at their endpoints, and reach radial zero.
  *
+ * @param spec - Profile family or custom one-pitch `[axial, radial]` path, in millimetres.
+ *
  * @example Printable triangular thread profile
  * ```ts
+ * import { threadProfile } from "@metamesh/modeling/geometry/mechanical";
+ *
  * threadProfile({ kind: "triangular", pitch: 1.75 });
  * ```
  */

package/dist/geometry/mechanical/threads/solids.js

@@ -1,8 +1,9 @@
 import { GeometryError } from "../../errors.js";
-import { resolveCircularSegments } from "../../resolution.js";
+import { resolveCircularSegments } from "../../sampling/resolution.js";
 import { resolveGeometryTolerance } from "../../tolerance.js";
-import { compensateThreadDiameters, preflightThreadSolidMesh, resolveThreadCircularSegments, } from "../index.js";
 import { resolveBevel } from "./bevel.js";
+import { compensateThreadDiameters, resolveThreadCircularSegments, } from "./fit.js";
+import { preflightThreadSolidMesh, } from "./mesh-plan.js";
 import { compensateThreadProfileForFaceting, scaleThreadProfileRadially } from "./profiles.js";
 const THREAD_FACETING_MARGIN = 0.001;
 const resolveCompensatedThreadBevelSize = (role, compensated, style, depth) => {
@@ -11,6 +12,7 @@ const resolveCompensatedThreadBevelSize = (role, compensated, style, depth) => {
     const envelopeDiameter = role === "female" ? compensated.majorDiameter : compensated.minorDiameter;
     return envelopeDiameter / 12;
 };
+/** @internal Applies shared mating allowances before role-specific bevel and mesh planning. */
 export const resolveCompensatedThreadSolidMesh = (options, role) => {
     const compensated = compensateThreadDiameters({
         nominalMajorDiameter: options.nominalMajorDiameter,
@@ -97,6 +99,8 @@ const preflightCompensatedThreadSolid = (options, role) => preflightThreadSolidM
  *
  * See `mesh.preflightThreadSolid` for standalone mesh estimates.
  * See `mesh.threadSolid` for standalone mesh construction.
+ *
+ * @param options - Nominal rod dimensions in millimetres, fit, and sampling controls.
  */
 export function preflightThreadedRodSolid(options) {
     return preflightCompensatedThreadSolid(options, "male");
@@ -111,6 +115,8 @@ export function preflightThreadedRodSolid(options) {
  *
  * See `mesh.preflightThreadSolid` for standalone mesh estimates.
  * See `mesh.threadSolid` for standalone mesh construction.
+ *
+ * @param options - Nominal cavity dimensions in millimetres, before fit and face extension.
  */
 export function preflightInternalThreadCutterSolid(options) {
     return preflightCompensatedThreadSolid(options, "female");
@@ -121,6 +127,7 @@ const throwInvalidNutScalar = (label, parameter, requirement, operation) => {
         details: { parameter },
     });
 };
+/** @internal Checks nut faces and plans the compensated cutter before native allocation. */
 export const resolveThreadedNutSolid = (options, operation) => {
     // Keep these public boundary checks ahead of resolution and all Manifold body construction.
     if (!Number.isFinite(options.width) || !(options.width > 0)) {
@@ -218,6 +225,8 @@ export const resolveThreadedNutSolid = (options, operation) => {
  * Successful preflight leaves mesh validity, native construction, and manufacturing fit to later checks.
  *
  * See `mesh.preflightThreadSolid` for standalone mesh estimates.
+ *
+ * @param options - Nominal nut dimensions in millimetres, fit, and sampling controls.
  */
 export function preflightThreadedNutSolid(options) {
     return resolveThreadedNutSolid(options, "preflightThreadedNutSolid").preflight;

package/dist/geometry/mechanical-api.js

@@ -0,0 +1,10 @@
+/** Pure mechanical dimensions, fit policies, standards, and preflight calculations. @packageDocumentation */
+export { preflightThreadedRodSolid as preflightThreadedRod, preflightInternalThreadCutterSolid as preflightInternalThreadCutter, preflightThreadedNutSolid as preflightThreadedNut, } from "./mechanical/threads/solids.js";
+export { minimumCylindricalGearToothCountWithoutUndercut, resolveCylindricalGear, resolveCylindricalGearPair, resolveRackPitch, sampleCylindricalGearOutline, sampleInternalCylindricalGearSpaceOutline, sampleRackToothPath, } from "./mechanical/gears.js";
+export { measureInternalCylindricalGearPairMotion, } from "./mechanical/gear-motion.js";
+export { METRIC_FASTENER_STANDARDS, getMetricClearanceHoleDiameter, getMetricFastenerStandard, } from "./mechanical/fastener-standards.js";
+export { compensateThreadProfileAxially, compensateThreadProfileForFaceting, threadProfile, } from "./mechanical/threads/profiles.js";
+export {} from "./mechanical/threads/mesh-plan.js";
+export { sampleConventionalThreadHelices as sampleThreadHelices, } from "./mechanical/threads/helices.js";
+export { PRINTABLE_THREAD_FIT_POLICIES, compensateThreadDiameters, resolvePrintableThreadFitPolicy, resolveThreadCircularSegments, } from "./mechanical/threads/fit.js";
+export { resolveKnuckleHinge, } from "./mechanical/knuckle-hinge.js";

package/dist/geometry/mesh/{mesh-centroid.js → centroid.js}

@@ -1,6 +1,6 @@
 import { GeometryError } from "../errors.js";
 import { immutableMeshView } from "../immutable-buffer.js";
-import { analyzeTriangleMesh } from "./mesh.js";
+import { analyzeTriangleMesh } from "./operations.js";
 /**
  * Computes the uniform-density volume centroid of an oriented closed solid, including cavity shells.
  *
@@ -16,6 +16,7 @@ export function computeTriangleMeshCentroid(mesh) {
     const facts = analyzeTriangleMesh(source, { requireClosed: true });
     if (!(facts.signedVolume > 0))
         throw new GeometryError("INVALID_TOPOLOGY", "A volume centroid requires positive oriented volume.", { operation: "computeTriangleMeshCentroid" });
+    // Translate tetrahedra near the mesh before summing moments to limit cancellation at large offsets.
     const origin = facts.bounds.min;
     const totals = [0, 0, 0], corrections = [0, 0, 0];
     for (let offset = 0; offset < source.indices.length; offset += 3) {

package/dist/geometry/{heightfield.js → mesh/heightfield.js}

@@ -1,8 +1,8 @@
-import { GeometryError } from "./errors.js";
-import { vector2Data } from "./math/vector-value.js";
-import { validateTriangleMesh } from "./mesh/mesh.js";
-import { assertMeshAllocationWithinLimits, resolveModelingLimits, } from "./model-limits.js";
-import { writeMeshVertex } from "./numeric.js";
+import { GeometryError } from "../errors.js";
+import { assertMeshAllocationWithinLimits, resolveModelingLimits, } from "../limits.js";
+import { vector2Data } from "../math/vector-value.js";
+import { validateTriangleMesh } from "./operations.js";
+import { writeMeshVertex } from "./write-vertex.js";
 function planHeightfield(options, limits) {
     const operation = "preflightHeightfield";
     if (typeof options !== "object" ||
@@ -82,6 +82,8 @@ function planHeightfield(options, limits) {
  * 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 function preflightHeightfield(options, limits = {}) {
@@ -94,6 +96,8 @@ export function preflightHeightfield(options, limits = {}) {
  * 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

package/dist/geometry/{join-geometry.js → mesh/join-layers.js}

@@ -1,6 +1,6 @@
-import { GeometryError } from "./errors.js";
-import { assertMeshAllocationWithinLimits } from "./model-limits.js";
-import { signedContourArea } from "./regions.js";
+import { GeometryError } from "../errors.js";
+import { assertMeshAllocationWithinLimits } from "../limits.js";
+import { signedContourArea } from "../regions/operations.js";
 /** @internal One bounded traversal budget for connection arrangement and meshing. */
 export class JoinWork {
     count;
@@ -23,9 +23,12 @@ export function clipJoinPolygon(polygon, plane) {
 }
 function clipJoinHalfPlane(polygon, distance) {
     const output = [];
+    if (polygon.length === 0)
+        return output;
+    let da = distance(polygon[0]);
     for (let i = 0; i < polygon.length; i++) {
         const a = polygon[i], b = polygon[(i + 1) % polygon.length];
-        const da = distance(a), db = distance(b);
+        const db = distance(b);
         const aInside = da >= 0, bInside = db >= 0;
         if (aInside)
             output.push(a);
@@ -33,6 +36,7 @@ function clipJoinHalfPlane(polygon, distance) {
             const t = da / (da - db);
             output.push([a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t]);
         }
+        da = db;
     }
     return output;
 }
@@ -232,7 +236,8 @@ export function createJoinPolygonIndex(polygons, work, limits) {
         return result;
     };
 }
-/** @internal Prepare one conforming XY partition for proof and visible layers at different heights.
+/**
+ * @internal Prepare one conforming XY partition for proof and visible layers at different heights.
  * Shared construction vertices are captured once; this does not weld or repair an input mesh.
  */
 export function prepareJoinLayer(polygons, epsilon, limits, work, options = {}) {
@@ -389,23 +394,16 @@ export function prepareJoinLayer(polygons, epsilon, limits, work, options = {})
         });
         for (let i = 0; i < face.length; i++) {
             const a = face[i], b = face[(i + 1) % face.length];
-            const key = `${Math.min(a, b)},${Math.max(a, b)}`;
-            const edge = edges.get(key);
-            if (edge === undefined)
-                edges.set(key, { a, b, count: 1 });
-            else if (edge.a !== b || edge.b !== a || edge.count !== 1)
-                throw new GeometryError("INVALID_TOPOLOGY", "Join partition cells reverse or repeat a shared boundary.", {
-                    operation: "join",
-                    details: { x1: points[a][0], y1: points[a][1], x2: points[b][0], y2: points[b][1] },
-                });
-            else
-                edge.count++;
+            appendJoinEdge(edges, a, b, points);
         }
     }
+    // Affine support caps can drop transverse cell edges. The sampled top keeps
+    // every cell because its heights can vary within a single support group.
     if (options.triangulate !== undefined)
         appendJoinCaps(faces, cells.map((cell) => cell.group), points, options.triangulate, (a, b, c) => triangle(bottomTriangles, a, b, c), work);
     const realize = (top, bottom, maximumLength, upperTriangles) => {
         const positions = [], nativePositions = [], indices = [];
+        // Each upper vertex is immediately followed by its lower partner.
         const vertices = new Map();
         const vertex = (id) => {
             const cached = vertices.get(id);
@@ -415,38 +413,27 @@ export function prepareJoinLayer(polygons, epsilon, limits, work, options = {})
             const native = nativePoints[id], nativeHi = top(native, nativeSupportHeights?.[id]), nativeLo = bottom(native, nativeSupportHeights?.[id]);
             if (![hi, lo, nativeHi, nativeLo].every(Number.isFinite) || hi <= lo || nativeHi <= nativeLo)
                 throw new GeometryError("DEGENERATE_GEOMETRY", "Join layer needs resolved positive thickness.", { operation: "join" });
-            const pair = [positions.length / 3, positions.length / 3 + 1];
+            const upper = positions.length / 3;
             assertMeshAllocationWithinLimits(positions.length / 3 + 2, indices.length / 3, (positions.length + 6) * 12 + indices.length * 4, "join", limits);
             positions.push(p[0], p[1], hi, p[0], p[1], lo);
             nativePositions.push(native[0], native[1], nativeHi, native[0], native[1], nativeLo);
-            vertices.set(id, pair);
-            return pair;
+            vertices.set(id, upper);
+            return upper;
         };
         const append = (a, b, c) => {
             assertMeshAllocationWithinLimits(positions.length / 3, indices.length / 3 + 1, positions.length * 12 + (indices.length + 3) * 4, "join", limits);
             indices.push(a, b, c);
         };
         for (let i = 0; i < upperTriangles.length; i += 3)
-            append(vertex(upperTriangles[i])[0], vertex(upperTriangles[i + 1])[0], vertex(upperTriangles[i + 2])[0]);
+            append(vertex(upperTriangles[i]), vertex(upperTriangles[i + 1]), vertex(upperTriangles[i + 2]));
         for (let i = 0; i < bottomTriangles.length; i += 3)
-            append(vertex(bottomTriangles[i])[1], vertex(bottomTriangles[i + 1])[1], vertex(bottomTriangles[i + 2])[1]);
+            append(vertex(bottomTriangles[i]) + 1, vertex(bottomTriangles[i + 1]) + 1, vertex(bottomTriangles[i + 2]) + 1);
         for (const edge of edges.values()) {
-            if (edge.count === 2)
+            if (edge.paired)
                 continue;
-            if (edge.count !== 1)
-                throw new GeometryError("INVALID_TOPOLOGY", "Join chart partition overlaps.", {
-                    operation: "join",
-                    details: {
-                        count: edge.count,
-                        x1: points[edge.a][0],
-                        y1: points[edge.a][1],
-                        x2: points[edge.b][0],
-                        y2: points[edge.b][1],
-                    },
-                });
             const a = vertex(edge.a), b = vertex(edge.b);
-            append(a[0], a[1], b[1]);
-            append(a[0], b[1], b[0]);
+            append(a, a + 1, b + 1);
+            append(a, b + 1, b);
         }
         assertMeshAllocationWithinLimits(positions.length / 3, indices.length / 3, positions.length * 12 + indices.length * 4, "join", limits);
         // Coarse caps need no unused partners for fine top interior vertices.
@@ -477,7 +464,7 @@ export function prepareJoinLayer(polygons, epsilon, limits, work, options = {})
                 throw new GeometryError("DEGENERATE_GEOMETRY", "Join layer thickness exceeds coordinate precision.", { operation: "join" });
             compactIndices.push(a, b, c);
         }
-        return refineJoinLayer(Float32Array.from(compact), Float64Array.from(compactNative), compactIndices, maximumLength, limits, work);
+        return refineJoinLayer(compact, compactNative, compactIndices, maximumLength, limits, work);
     };
     return {
         build: (top, bottom, maximumLength) => realize(top, bottom, maximumLength, topTriangles),
@@ -660,6 +647,27 @@ function triangulateJoinCell(face, points, work, append) {
             operation: "join",
         });
 }
+// Shared edges must occur exactly twice with opposite winding, in both the full
+// partition and each cap group. Keep paired records so a third use still rejects.
+function appendJoinEdge(edges, a, b, points) {
+    const key = `${Math.min(a, b)},${Math.max(a, b)}`;
+    const previous = edges.get(key);
+    if (previous === undefined)
+        edges.set(key, { a, b, paired: false });
+    else if (previous.a !== b || previous.b !== a || previous.paired)
+        throw new GeometryError("INVALID_TOPOLOGY", "Join partition cells reverse or repeat a shared boundary.", {
+            operation: "join",
+            details: {
+                count: previous.paired ? 2 : 1,
+                x1: points[a][0],
+                y1: points[a][1],
+                x2: points[b][0],
+                y2: points[b][1],
+            },
+        });
+    else
+        previous.paired = true;
+}
 function appendJoinCaps(faces, groups, points, triangulate, append, work) {
     const grouped = new Map();
     for (let index = 0; index < faces.length; index++) {
@@ -673,27 +681,11 @@ function appendJoinCaps(faces, groups, points, triangulate, append, work) {
         for (let i = 0; i < face.length; i++) {
             work.use();
             const a = face[i], b = face[(i + 1) % face.length];
-            const key = `${Math.min(a, b)},${Math.max(a, b)}`;
-            const previous = edges.get(key);
-            if (previous === undefined)
-                edges.set(key, { a, b, count: 1 });
-            else if (previous.a !== b || previous.b !== a || previous.count !== 1)
-                throw new GeometryError("INVALID_TOPOLOGY", "Join cap cells overlap or reverse lineage.", {
-                    operation: "join",
-                    details: {
-                        count: previous.count,
-                        x1: points[a][0],
-                        y1: points[a][1],
-                        x2: points[b][0],
-                        y2: points[b][1],
-                    },
-                });
-            else
-                previous.count = 2;
+            appendJoinEdge(edges, a, b, points);
         }
     }
     for (const edges of grouped.values()) {
-        const boundary = [...edges.values()].filter((edge) => edge.count === 1);
+        const boundary = [...edges.values()].filter((edge) => !edge.paired);
         const outgoing = new Map();
         for (const edge of boundary) {
             const entries = outgoing.get(edge.a);
@@ -754,22 +746,24 @@ function appendJoinCaps(faces, groups, points, triangulate, append, work) {
         }
     }
 }
-function refineJoinLayer(initial, initialNative, initialIndices, maximumLength, limits, work) {
+function refineJoinLayer(positions, nativePositions, initialIndices, maximumLength, limits, work) {
+    // Inputs are owned arrays with proxy positions already rounded to Float32.
+    // Keep native coordinates separate until both buffers are finalized.
     if (maximumLength === undefined)
         return {
-            positions: initial,
-            nativePositions: initialNative,
+            positions: Float32Array.from(positions),
+            nativePositions: Float64Array.from(nativePositions),
             indices: Uint32Array.from(initialIndices),
         };
     if (!Number.isFinite(maximumLength) || maximumLength <= 0)
         throw new GeometryError("INVALID_ARGUMENT", "Join segment length must be finite and positive.", {
             operation: "join",
         });
-    const positions = Array.from(initial);
-    const nativePositions = Array.from(initialNative);
     let indices = initialIndices;
     const key = (a, b) => (a < b ? `${a},${b}` : `${b},${a}`);
     while (true) {
+        // Discover all splits before replacing faces so every incident triangle
+        // shares each edge midpoint, regardless of its other edge lengths.
         const midpoints = new Map();
         for (let i = 0; i < indices.length; i += 3) {
             const face = [indices[i], indices[i + 1], indices[i + 2]];

package/dist/geometry/mesh/{mesh.js → operations.js}

@@ -1,10 +1,11 @@
 import { GeometryError } from "../errors.js";
 import { immutableMeshView } from "../immutable-buffer.js";
-import { writeMeshVertex } from "../numeric.js";
 import { resolveGeometryTolerance } from "../tolerance.js";
-import { readTransformMatrix } from "../transform-matrix.js";
-import { transformDeterminant3, validateTransform3 } from "../transform3.js";
-import { IndexedMeshEdgeTable } from "./mesh-edge-table.js";
+import { transformDeterminant3, validateTransform3 } from "../transforms/affine3.js";
+import { readTransformMatrix } from "../transforms/matrix-input.js";
+import { IndexedMeshEdgeTable } from "./edge-table.js";
+import { reverseOwnedTriangleWinding } from "./winding.js";
+import { writeMeshVertex } from "./write-vertex.js";
 function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = false) {
     // Normalize immutable storage and read raw input accessors once before traversal.
     const source = immutableMeshView(mesh);
@@ -77,6 +78,7 @@ function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = f
     };
     // Keep the two hot-loop accumulators independent and local: no mutable numeric objects escape.
     let surfaceArea = 0, areaCorrection = 0, signedVolume = 0, volumeCorrection = 0;
+    // A local tetrahedron origin limits cancellation when the mesh has a large world offset.
     const originX = source.positions[0] ?? 0, originY = source.positions[1] ?? 0, originZ = source.positions[2] ?? 0;
     for (let offset = 0; offset < source.indices.length; offset += 3) {
         const a = source.indices[offset], b = source.indices[offset + 1], c = source.indices[offset + 2];
@@ -157,7 +159,7 @@ export function analyzeTriangleMesh(mesh, options = {}) {
  * 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.
@@ -222,11 +224,7 @@ export function reverseTriangleMesh(mesh) {
     const source = immutableMeshView(mesh);
     validateTriangleMesh(source);
     const indices = new Uint32Array(source.indices);
-    for (let offset = 0; offset < indices.length; offset += 3) {
-        const second = indices[offset + 1];
-        indices[offset + 1] = indices[offset + 2];
-        indices[offset + 2] = second;
-    }
+    reverseOwnedTriangleWinding(indices);
     return { indices, positions: new Float32Array(source.positions) };
 }
 /**
@@ -236,7 +234,7 @@ export function reverseTriangleMesh(mesh) {
  * 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 function transformTriangleMesh(mesh, placement) {
@@ -256,12 +254,7 @@ export function transformTriangleMesh(mesh, placement) {
         ], "transformTriangleMesh");
     }
     const indices = new Uint32Array(source.indices);
-    if (transformDeterminant3(transform) < 0) {
-        for (let offset = 0; offset < indices.length; offset += 3) {
-            const second = indices[offset + 1];
-            indices[offset + 1] = indices[offset + 2];
-            indices[offset + 2] = second;
-        }
-    }
+    if (transformDeterminant3(transform) < 0)
+        reverseOwnedTriangleWinding(indices);
     return validateTriangleMesh({ indices, positions });
 }

package/dist/geometry/mesh/{mesh-planar.js → planar.js}

@@ -1,6 +1,7 @@
 import { GeometryError } from "../errors.js";
 import { immutableMeshView, isImmutableBuffer } from "../immutable-buffer.js";
-import { buildTriangleMeshQualityAnalysis, } from "./mesh-quality.js";
+import { buildTriangleMeshQualityAnalysis, } from "./quality.js";
+import { triangleQuality } from "./triangle-quality.js";
 const DEFAULT_MAXIMUM_FLIP_ATTEMPTS = 1_000_000;
 const DEFAULT_MAXIMUM_PATCH_TRIANGLE_COUNT = 50_000;
 const DEFAULT_MAXIMUM_PROCESSED_TRIANGLE_COUNT = 200_000;
@@ -17,6 +18,8 @@ const pointAt = (positions, vertex) => [
     positions[vertex * 3 + 1],
     positions[vertex * 3 + 2],
 ];
+// Keep these kernels local to isolate V8's array-type feedback from other modeling operations.
+// Shared helpers see more array representations, which can slow hot loops even when inlined.
 const subtract = (left, right) => [
     left[0] - right[0],
     left[1] - right[1],
@@ -70,22 +73,9 @@ const pairQuality = (positions, first, second) => {
     let maximumAspectRatio = 0;
     for (const triangle of [first, second]) {
         const points = triangle.map((vertex) => pointAt(positions, vertex));
-        const edgeVectors = [
-            subtract(points[1], points[0]),
-            subtract(points[2], points[1]),
-            subtract(points[0], points[2]),
-        ];
-        const edgeSquaredLengths = edgeVectors.map(squaredLength);
-        const doubleArea = Math.sqrt(squaredLength(cross(edgeVectors[0], subtract(points[2], points[0]))));
-        maximumAspectRatio = Math.max(maximumAspectRatio, doubleArea === 0
-            ? Number.POSITIVE_INFINITY
-            : (Math.sqrt(3) * Math.max(...edgeSquaredLengths)) / (2 * doubleArea));
-        for (let corner = 0; corner < 3; corner += 1) {
-            const origin = points[corner];
-            const incoming = subtract(points[(corner + 1) % 3], origin);
-            const outgoing = subtract(points[(corner + 2) % 3], origin);
-            angles.push(Math.atan2(Math.sqrt(squaredLength(cross(incoming, outgoing))), dot(incoming, outgoing)));
-        }
+        const quality = triangleQuality(points[0], points[1], points[2], "squared");
+        maximumAspectRatio = Math.max(maximumAspectRatio, quality.aspectRatio);
+        angles.push(...quality.angles);
     }
     angles.sort((left, right) => left - right);
     return { angles, maximumAspectRatio };
@@ -170,7 +160,7 @@ const fallbackReasonForCandidate = (before, after, boundaryEdgeKeys) => {
  * 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.
  */