@metamesh/modeling 0.17.0 → 0.19.0

package/dist/geometry/mesh/mesh-centroid.js

@@ -1,17 +1,18 @@
 import { GeometryError } from "../errors.js";
+import { immutableMeshView } from "../immutable-buffer.js";
 import { analyzeTriangleMesh } from "./mesh.js";
 /**
  * Computes the uniform-density volume centroid of an oriented closed solid, including cavity shells.
  *
  * Coordinates are millimetres. Indexed closure and positive aggregate volume are required; callers
- * may use validateSolidMesh first when geometric intersections and shell orientation are untrusted.
+ * may use mesh.validateSolid first when geometric intersections and shell orientation are untrusted.
  * Fresh mutable input is inspected on every call, and buffers are never changed.
  *
  * @param mesh - Consistently oriented closed mesh with positive enclosed volume.
  * @returns A fresh immutable XYZ volume centroid.
  */
 export function computeTriangleMeshCentroid(mesh) {
-    const source = { positions: mesh.positions, indices: mesh.indices };
+    const source = immutableMeshView(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" });

package/dist/geometry/mesh/mesh-planar.js

@@ -1,4 +1,5 @@
 import { GeometryError } from "../errors.js";
+import { immutableMeshView, isImmutableBuffer } from "../immutable-buffer.js";
 import { buildTriangleMeshQualityAnalysis, } from "./mesh-quality.js";
 const DEFAULT_MAXIMUM_FLIP_ATTEMPTS = 1_000_000;
 const DEFAULT_MAXIMUM_PATCH_TRIANGLE_COUNT = 50_000;
@@ -165,19 +166,37 @@ const fallbackReasonForCandidate = (before, after, boundaryEdgeKeys) => {
  * The operation changes indices only: it never moves, adds, welds, or removes vertices; never
  * crosses a coplanar-patch boundary; and never changes the face count. Each accepted flip improves
  * a deterministic ordering of triangle angles, aspect ratio, diagonal locality, and local
- * incidence/valence concentration. Unsupported input or a failed final integrity check returns the
- * exact original mesh object. Malformed buffers and the configured analysis complexity limit throw.
+ * incidence/valence concentration. Unsupported input or a failed final integrity check preserves the
+ * 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 options - Patch eligibility, numeric tolerance, and deterministic work bounds.
  * @returns Optimized connectivity and before/after diagnostics, or an unchanged safe fallback.
  */
 export function optimizePlanarPatches(mesh, options = {}) {
-    const source = { positions: mesh.positions, indices: mesh.indices };
+    const { positions, indices } = mesh;
+    const immutable = isImmutableBuffer(positions) || isImmutableBuffer(indices);
+    const source = immutableMeshView({ positions, indices });
+    const result = optimizePlanarMesh(source, options);
+    // Raw numerical outputs may alias caller-owned raw inputs, never immutable private storage.
+    return !immutable
+        ? result.changed
+            ? result
+            : { ...result, mesh: mesh }
+        : {
+            ...result,
+            mesh: {
+                positions: new Float32Array(result.mesh.positions),
+                indices: new Uint32Array(result.mesh.indices),
+            },
+        };
+}
+function optimizePlanarMesh(source, options) {
     const resolved = resolveOptions(options);
     const before = buildTriangleMeshQualityAnalysis(source, options);
     if (!before.report.isClosedOrientedManifold) {
-        return unchangedResult(mesh, before.report, 0, false, "input-not-closed-oriented-manifold");
+        return unchangedResult(source, before.report, 0, false, "input-not-closed-oriented-manifold");
     }
     const selectedPatchIds = new Set();
     const boundaryEdgeKeys = new Set();
@@ -199,7 +218,7 @@ export function optimizePlanarPatches(mesh, options = {}) {
             boundaryEdgeKeys.add(key);
     }
     if (selectedPatchIds.size === 0) {
-        return unchangedResult(mesh, before.report, skippedPatchCount, budgetExhausted);
+        return unchangedResult(source, before.report, skippedPatchCount, budgetExhausted);
     }
     const triangles = before.faces.map(({ vertices }) => [...vertices]);
     const edges = new Map();
@@ -226,7 +245,7 @@ export function optimizePlanarPatches(mesh, options = {}) {
     const maxFlipAttempts = resolved.maxFlipAttempts ??
         Math.min(DEFAULT_MAXIMUM_FLIP_ATTEMPTS, initialEdges.length * ATTEMPTS_PER_INITIAL_EDGE);
     if (maxFlipAttempts === 0) {
-        return unchangedResult(mesh, before.report, skippedPatchCount, budgetExhausted);
+        return unchangedResult(source, before.report, skippedPatchCount, budgetExhausted);
     }
     const queue = initialEdges.map(({ key }) => key);
     const queued = new Set(queue);
@@ -382,7 +401,7 @@ export function optimizePlanarPatches(mesh, options = {}) {
     if (queueOffset < queue.length)
         budgetExhausted = true;
     if (flipCount === 0) {
-        return unchangedResult(mesh, before.report, skippedPatchCount, budgetExhausted);
+        return unchangedResult(source, before.report, skippedPatchCount, budgetExhausted);
     }
     const indices = new Uint32Array(source.indices.length);
     for (let faceIndex = 0; faceIndex < triangles.length; faceIndex += 1) {
@@ -392,7 +411,7 @@ export function optimizePlanarPatches(mesh, options = {}) {
     const after = buildTriangleMeshQualityAnalysis(candidate, options);
     const fallbackReason = fallbackReasonForCandidate(before, after, boundaryEdgeKeys);
     if (fallbackReason !== undefined) {
-        return unchangedResult(mesh, before.report, skippedPatchCount, budgetExhausted, fallbackReason);
+        return unchangedResult(source, before.report, skippedPatchCount, budgetExhausted, fallbackReason);
     }
     return {
         after: after.report,

package/dist/geometry/mesh/mesh-quality.js

@@ -1,4 +1,5 @@
 import { GeometryError } from "../errors.js";
+import { immutableMeshView } from "../immutable-buffer.js";
 import { resolveGeometryTolerance, } from "../tolerance.js";
 const DEFAULT_MAXIMUM_TRIANGLE_COUNT = 200_000;
 const FLOAT32_EPSILON = 2 ** -23;
@@ -235,7 +236,7 @@ const buildPatchAnalysis = (faces, edges, faceIndices, id) => {
 };
 /** @internal */
 export function buildTriangleMeshQualityAnalysis(mesh, options = {}) {
-    const source = { positions: mesh.positions, indices: mesh.indices };
+    const source = immutableMeshView(mesh);
     const maxTriangles = positiveInteger(options.maxTriangles ?? DEFAULT_MAXIMUM_TRIANGLE_COUNT, "Maximum analyzed triangle count");
     structurallyValidateMesh(source, maxTriangles);
     const { bounds, extent } = meshBoundsAndExtent(source.positions);

package/dist/geometry/mesh/mesh-render.js

@@ -0,0 +1,205 @@
+import { GeometryError } from "../errors.js";
+import { immutableMeshView } from "../immutable-buffer.js";
+import { validateTriangleMesh } from "./mesh.js";
+const MAX_NORMAL_COMPARISONS = 50_000_000;
+function tableCapacity(count) {
+    let capacity = 16;
+    while (capacity < count * 2)
+        capacity *= 2;
+    if (capacity > 0x8000_0000)
+        throw new GeometryError("COMPLEXITY_LIMIT", "Render mesh exceeds hash table capacity.");
+    return capacity;
+}
+/**
+ * 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.
+ *
+ * @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 function renderMesh(input, options = {}) {
+    const angle = options.creaseAngle ?? 20;
+    if (!Number.isFinite(angle) || angle < 0 || angle > 180)
+        throw new GeometryError("INVALID_ARGUMENT", "Crease angle must be from 0 through 180 degrees.", {
+            operation: "renderMesh",
+        });
+    validateTriangleMesh(input);
+    const { positions, indices } = immutableMeshView(input);
+    const vertexCount = positions.length / 3;
+    const cornerCount = indices.length;
+    const faceCount = cornerCount / 3;
+    const positionBits = new Uint32Array(positions.buffer, positions.byteOffset, positions.length);
+    const faceNormals = new Float64Array(cornerCount);
+    for (let face = 0; face < faceCount; face += 1) {
+        const offset = face * 3;
+        const a = indices[offset] * 3;
+        const b = indices[offset + 1] * 3;
+        const c = indices[offset + 2] * 3;
+        const ux = positions[b] - positions[a];
+        const uy = positions[b + 1] - positions[a + 1];
+        const uz = positions[b + 2] - positions[a + 2];
+        const vx = positions[c] - positions[a];
+        const vy = positions[c + 1] - positions[a + 1];
+        const vz = positions[c + 2] - positions[a + 2];
+        const nx = uy * vz - uz * vy;
+        const ny = uz * vx - ux * vz;
+        const nz = ux * vy - uy * vx;
+        const inverseLength = 1 / Math.hypot(nx, ny, nz);
+        faceNormals[offset] = nx * inverseLength;
+        faceNormals[offset + 1] = ny * inverseLength;
+        faceNormals[offset + 2] = nz * inverseLength;
+    }
+    // Position identity is exact. In particular, no tolerance can collapse a thin physical gap.
+    const positionIds = new Uint32Array(vertexCount);
+    const representatives = new Uint32Array(vertexCount);
+    const positionTable = new Uint32Array(tableCapacity(vertexCount));
+    const positionMask = positionTable.length - 1;
+    let uniquePositions = 0;
+    const positionHash = (offset) => Math.imul(positions[offset] === 0 ? 0 : positionBits[offset], 73_856_093) ^
+        Math.imul(positions[offset + 1] === 0 ? 0 : positionBits[offset + 1], 19_349_663) ^
+        Math.imul(positions[offset + 2] === 0 ? 0 : positionBits[offset + 2], 83_492_791);
+    for (let vertex = 0; vertex < vertexCount; vertex += 1) {
+        const offset = vertex * 3;
+        let slot = positionHash(offset) & positionMask;
+        while (positionTable[slot] !== 0) {
+            const id = positionTable[slot] - 1;
+            const other = representatives[id] * 3;
+            if (positions[offset] === positions[other] &&
+                positions[offset + 1] === positions[other + 1] &&
+                positions[offset + 2] === positions[other + 2])
+                break;
+            slot = (slot + 1) & positionMask;
+        }
+        if (positionTable[slot] === 0) {
+            representatives[uniquePositions] = vertex;
+            positionTable[slot] = ++uniquePositions;
+        }
+        positionIds[vertex] = positionTable[slot] - 1;
+    }
+    const bucketOffsets = new Uint32Array(uniquePositions + 1);
+    for (const vertex of indices)
+        bucketOffsets[positionIds[vertex] + 1] += 1;
+    let comparisons = 0;
+    for (let id = 0; id < uniquePositions; id += 1) {
+        const count = bucketOffsets[id + 1];
+        comparisons += count * count;
+        if (angle !== 0 && comparisons > MAX_NORMAL_COMPARISONS)
+            throw new GeometryError("COMPLEXITY_LIMIT", "Render mesh exceeds the normal comparison work limit.", { operation: "renderMesh", details: { maxNormalComparisons: MAX_NORMAL_COMPARISONS } });
+        bucketOffsets[id + 1] = count + bucketOffsets[id];
+    }
+    const bucketFaces = new Uint32Array(cornerCount);
+    const cursors = bucketOffsets.slice(0, uniquePositions);
+    for (let corner = 0; corner < cornerCount; corner += 1) {
+        const id = positionIds[indices[corner]];
+        bucketFaces[cursors[id]] = Math.floor(corner / 3);
+        cursors[id] += 1;
+    }
+    let capacity = Math.min(cornerCount, Math.max(16, vertexCount));
+    let renderPositions = new Float32Array(capacity * 3);
+    let renderNormals = new Float32Array(capacity * 3);
+    let renderPositionBits = new Uint32Array(renderPositions.buffer);
+    let renderNormalBits = new Uint32Array(renderNormals.buffer);
+    let renderTable = new Uint32Array(tableCapacity(capacity));
+    let renderMask = renderTable.length - 1;
+    const renderedIndices = new Uint32Array(cornerCount);
+    const candidateNormal = new Float32Array(3);
+    const normalBits = new Uint32Array(candidateNormal.buffer);
+    let renderedCount = 0;
+    const creaseDot = Math.cos((angle * Math.PI) / 180);
+    const renderHash = (offset) => {
+        return (Math.imul(renderPositions[offset] === 0 ? 0 : renderPositionBits[offset], 73_856_093) ^
+            Math.imul(renderPositions[offset + 1] === 0 ? 0 : renderPositionBits[offset + 1], 19_349_663) ^
+            Math.imul(renderPositions[offset + 2] === 0 ? 0 : renderPositionBits[offset + 2], 83_492_791) ^
+            Math.imul(renderNormals[offset] === 0 ? 0 : renderNormalBits[offset], 49_979_687) ^
+            Math.imul(renderNormals[offset + 1] === 0 ? 0 : renderNormalBits[offset + 1], 67_867_967) ^
+            Math.imul(renderNormals[offset + 2] === 0 ? 0 : renderNormalBits[offset + 2], 86_028_121));
+    };
+    for (let corner = 0; corner < cornerCount; corner += 1) {
+        const faceOffset = Math.floor(corner / 3) * 3;
+        const nx = faceNormals[faceOffset];
+        const ny = faceNormals[faceOffset + 1];
+        const nz = faceNormals[faceOffset + 2];
+        const positionOffset = indices[corner] * 3;
+        let sumX = nx, sumY = ny, sumZ = nz;
+        if (angle !== 0) {
+            sumX = 0;
+            sumY = 0;
+            sumZ = 0;
+            const id = positionIds[indices[corner]];
+            for (let k = bucketOffsets[id]; k < bucketOffsets[id + 1]; k += 1) {
+                const other = bucketFaces[k] * 3;
+                const ox = faceNormals[other];
+                const oy = faceNormals[other + 1];
+                const oz = faceNormals[other + 2];
+                if (other === faceOffset || nx * ox + ny * oy + nz * oz >= creaseDot) {
+                    sumX += ox;
+                    sumY += oy;
+                    sumZ += oz;
+                }
+            }
+        }
+        const length = Math.hypot(sumX, sumY, sumZ);
+        candidateNormal[0] = length > 1e-12 ? sumX / length : nx;
+        candidateNormal[1] = length > 1e-12 ? sumY / length : ny;
+        candidateNormal[2] = length > 1e-12 ? sumZ / length : nz;
+        const hash = positionHash(positionOffset) ^
+            Math.imul(candidateNormal[0] === 0 ? 0 : normalBits[0], 49_979_687) ^
+            Math.imul(candidateNormal[1] === 0 ? 0 : normalBits[1], 67_867_967) ^
+            Math.imul(candidateNormal[2] === 0 ? 0 : normalBits[2], 86_028_121);
+        let slot = hash & renderMask;
+        while (renderTable[slot] !== 0) {
+            const offset = (renderTable[slot] - 1) * 3;
+            if (renderPositions[offset] === positions[positionOffset] &&
+                renderPositions[offset + 1] === positions[positionOffset + 1] &&
+                renderPositions[offset + 2] === positions[positionOffset + 2] &&
+                renderNormals[offset] === candidateNormal[0] &&
+                renderNormals[offset + 1] === candidateNormal[1] &&
+                renderNormals[offset + 2] === candidateNormal[2])
+                break;
+            slot = (slot + 1) & renderMask;
+        }
+        if (renderTable[slot] === 0) {
+            if (renderedCount === capacity) {
+                capacity = Math.min(cornerCount, capacity * 2);
+                const grownPositions = new Float32Array(capacity * 3);
+                const grownNormals = new Float32Array(capacity * 3);
+                grownPositions.set(renderPositions);
+                grownNormals.set(renderNormals);
+                renderPositions = grownPositions;
+                renderNormals = grownNormals;
+                renderPositionBits = new Uint32Array(renderPositions.buffer);
+                renderNormalBits = new Uint32Array(renderNormals.buffer);
+                renderTable = new Uint32Array(tableCapacity(capacity));
+                renderMask = renderTable.length - 1;
+                for (let index = 0; index < renderedCount; index += 1) {
+                    let target = renderHash(index * 3) & renderMask;
+                    while (renderTable[target] !== 0)
+                        target = (target + 1) & renderMask;
+                    renderTable[target] = index + 1;
+                }
+                slot = hash & renderMask;
+                while (renderTable[slot] !== 0)
+                    slot = (slot + 1) & renderMask;
+            }
+            const offset = renderedCount * 3;
+            renderPositions[offset] = positions[positionOffset];
+            renderPositions[offset + 1] = positions[positionOffset + 1];
+            renderPositions[offset + 2] = positions[positionOffset + 2];
+            renderNormals.set(candidateNormal, offset);
+            renderTable[slot] = ++renderedCount;
+        }
+        renderedIndices[corner] = renderTable[slot] - 1;
+    }
+    return {
+        positions: renderPositions.slice(0, renderedCount * 3),
+        normals: renderNormals.slice(0, renderedCount * 3),
+        indices: renderedIndices,
+    };
+}

package/dist/geometry/mesh/mesh-signature.js

@@ -1,4 +1,5 @@
 import { GeometryError } from "../errors.js";
+import { immutableMeshView } from "../immutable-buffer.js";
 import { analyzeTriangleMesh, validateTriangleMesh } from "./mesh.js";
 const DEFAULT_POSITION_TOLERANCE = 1e-5;
 const DEFAULT_VOLUME_TOLERANCE = 1e-4;
@@ -68,10 +69,10 @@ const hashCanonicalKeys = (header, groups) => {
  * @param mesh - Closed oriented mesh to measure without mutation.
  * @param options - Absolute quantization and complexity limits.
  * @returns Compact counts, bounds, volume, topology, tolerances, and canonical fingerprint.
- * @throws {@link GeometryError} When validation, topology, tolerance, or complexity checks fail.
+ * @throws `GeometryError` When validation, topology, tolerance, or complexity checks fail.
  */
 export function computeTriangleMeshSignature(mesh, options = {}) {
-    const source = { positions: mesh.positions, indices: mesh.indices };
+    const source = immutableMeshView(mesh);
     const maxTriangles = options.maxTriangles ?? DEFAULT_MAXIMUM_TRIANGLE_COUNT;
     if (!Number.isSafeInteger(maxTriangles) || maxTriangles <= 0) {
         throw new GeometryError("INVALID_ARGUMENT", "maxTriangles must be a positive safe integer.", {
@@ -92,14 +93,14 @@ export function computeTriangleMeshSignature(mesh, options = {}) {
     const positionTolerance = validatePositiveTolerance(options.positionTolerance ?? DEFAULT_POSITION_TOLERANCE, "positionTolerance");
     const volumeTolerance = validatePositiveTolerance(options.volumeTolerance ?? DEFAULT_VOLUME_TOLERANCE, "volumeTolerance");
     const measured = analyzeTriangleMesh(source, { requireClosed: true, includeTopology: true });
-    const connectedComponentCount = measured.connectedComponentCount;
+    const shellCount = measured.shellCount;
     const edgeCount = measured.edgeCount;
     const eulerCharacteristic = measured.vertexCount - edgeCount + measured.triangleCount;
-    const twiceGenus = connectedComponentCount * 2 - eulerCharacteristic;
+    const twiceGenus = shellCount * 2 - eulerCharacteristic;
     if (twiceGenus < 0 || twiceGenus % 2 !== 0) {
         throw new GeometryError("INVALID_TOPOLOGY", "Closed mesh topology does not describe orientable vertex-manifold components.", {
             operation: "computeTriangleMeshSignature",
-            details: { connectedComponentCount, edgeCount, eulerCharacteristic },
+            details: { shellCount, edgeCount, eulerCharacteristic },
         });
     }
     const coordinateKeys = Array.from({ length: measured.vertexCount }, (_, vertex) => coordinateKey(source.positions, vertex, positionTolerance));
@@ -127,7 +128,7 @@ export function computeTriangleMeshSignature(mesh, options = {}) {
     });
     return Object.freeze({
         bounds: quantizeBounds(measured.bounds),
-        connectedComponentCount,
+        shellCount,
         fingerprint: hashCanonicalKeys(`${measured.vertexCount}|${measured.triangleCount}|${positionTolerance}`, [vertexKeys, triangleKeys]),
         genus: twiceGenus / 2,
         signedVolume: quantizedScalar(measured.signedVolume, volumeTolerance, "Signed volume"),

package/dist/geometry/mesh/mesh-solid-intersections.js

@@ -28,13 +28,26 @@ const dominantAxis = (value) => {
             axis = index;
     return axis;
 };
+/** Returns the actual nearby segment point; offset half-planes overexpand acute corners. */
+function nearbySegmentPoint(point, a, b, epsilon) {
+    const dx = b[0] - a[0], dy = b[1] - a[1], dz = b[2] - a[2];
+    const lengthSquared = dx * dx + dy * dy + dz * dz;
+    const fraction = lengthSquared === 0
+        ? 0
+        : Math.max(0, Math.min(1, ((point[0] - a[0]) * dx + (point[1] - a[1]) * dy + (point[2] - a[2]) * dz) /
+            lengthSquared));
+    const x = a[0] + fraction * dx, y = a[1] + fraction * dy, z = a[2] + fraction * dz;
+    return Math.hypot(point[0] - x, point[1] - y, point[2] - z) <= epsilon ? [x, y, z] : undefined;
+}
 function inside(point, triangle, direction, epsilon) {
     const axis = dominantAxis(direction), p = project(point, axis), points = triangle.map((vertex) => project(vertex, axis));
     const sign = Math.sign(turn(points[0], points[1], points[2]));
-    return points.every((a, index) => {
+    if (points.every((a, index) => {
         const b = points[(index + 1) % 3];
-        return sign * turn(a, b, p) >= -epsilon * Math.hypot(b[0] - a[0], b[1] - a[1]);
-    });
+        return sign * turn(a, b, p) >= 0;
+    }))
+        return true;
+    return triangle.some((a, index) => nearbySegmentPoint(point, a, triangle[(index + 1) % 3], epsilon) !== undefined);
 }
 function onSharedBoundary(point, shared, epsilon) {
     if (shared.some((vertex) => distance(point, vertex) <= epsilon))
@@ -53,13 +66,12 @@ function coplanarIntersection(first, second, direction, shared, epsilon) {
     let polygon = [...first];
     for (let edge = 0; edge < 3 && polygon.length > 0; edge++) {
         const a = clip[edge], b = clip[(edge + 1) % 3];
-        const tolerance = epsilon * Math.hypot(b[0] - a[0], b[1] - a[1]);
         const signed = (point) => sign * turn(a, b, project(point, axis));
         const next = [];
         for (let index = 0; index < polygon.length; index++) {
             const start = polygon[index], end = polygon[(index + 1) % polygon.length];
             const d0 = signed(start), d1 = signed(end);
-            const in0 = d0 >= -tolerance, in1 = d1 >= -tolerance;
+            const in0 = d0 >= 0, in1 = d1 >= 0;
             if (in0)
                 next.push(start);
             if (in0 !== in1) {
@@ -73,22 +85,36 @@ function coplanarIntersection(first, second, direction, shared, epsilon) {
         }
         polygon = next;
     }
-    if (polygon.length === 0)
-        return false;
-    const origin = project(polygon[0], axis);
-    let area = 0;
-    for (let index = 1; index + 1 < polygon.length; index++)
-        area += turn(origin, project(polygon[index], axis), project(polygon[index + 1], axis));
-    const scale = Math.max(...first.map((point, index) => distance(point, first[(index + 1) % 3])));
-    if (Math.abs(area) > epsilon * scale)
-        return true;
-    return polygon.some((point) => !onSharedBoundary(point, shared, epsilon));
+    if (polygon.length > 0) {
+        const origin = project(polygon[0], axis);
+        let area = 0;
+        for (let index = 1; index + 1 < polygon.length; index++)
+            area += turn(origin, project(polygon[index], axis), project(polygon[index + 1], axis));
+        const scale = Math.max(...first.map((point, index) => distance(point, first[(index + 1) % 3])));
+        if (Math.abs(area) > epsilon * scale)
+            return true;
+        if (polygon.some((point) => !onSharedBoundary(point, shared, epsilon)))
+            return true;
+    }
+    // A distance tolerance rounds a triangle's corners. Clipping against independently offset
+    // support lines instead creates long miters and can report contact many epsilons away.
+    const nearbyContact = (source, target) => source.some((point) => target.some((a, index) => {
+        const closest = nearbySegmentPoint(point, a, target[(index + 1) % 3], epsilon);
+        return (closest !== undefined &&
+            (!onSharedBoundary(point, shared, epsilon) || !onSharedBoundary(closest, shared, epsilon)));
+    }));
+    return nearbyContact(first, second) || nearbyContact(second, first);
 }
 /** @internal Detects contact beyond a permitted indexed vertex or edge, without welding. */
 export function trianglesIntersectBeyondSharedBoundary(firstGeometry, secondGeometry, shared, epsilon) {
     const first = firstGeometry.points, second = secondGeometry.points, n0 = firstGeometry.normal, n1 = secondGeometry.normal;
-    const distances0 = first.map((point) => dot(n1, subtract(point, second[0])));
-    const distances1 = second.map((point) => dot(n0, subtract(point, first[0])));
+    // Indexed shared vertices lie exactly on both planes. Dot-product cancellation must not
+    // turn that known zero into a false crossing along a nearly coplanar edge.
+    const planeDistance = (point, n, origin) => shared.some((vertex) => vertex.every((value, axis) => value === point[axis]))
+        ? 0
+        : dot(n, subtract(point, origin));
+    const distances0 = first.map((point) => planeDistance(point, n1, second[0]));
+    const distances1 = second.map((point) => planeDistance(point, n0, first[0]));
     const separated = (values) => values.every((value) => value > epsilon) || values.every((value) => value < -epsilon);
     if (separated(distances0) || separated(distances1))
         return false;

package/dist/geometry/mesh/mesh-solid.js

@@ -1,4 +1,5 @@
 import { GeometryError } from "../errors.js";
+import { immutableMeshView } from "../immutable-buffer.js";
 import { resolveGeometryTolerance } from "../tolerance.js";
 import { IndexedMeshEdgeTable } from "./mesh-edge-table.js";
 import { prepareSolidTriangle, trianglesIntersectBeyondSharedBoundary, triangleSolidAngle, } from "./mesh-solid-intersections.js";
@@ -51,9 +52,7 @@ function validationWork(mesh, options) {
 }
 /** @internal Fresh measurements precede one adjacency traversal for closure, fans, and shells. */
 export function analyzeSolidMesh(mesh, options = {}) {
-    const source = typeof mesh === "object" && mesh !== null
-        ? { positions: mesh.positions, indices: mesh.indices }
-        : mesh;
+    const source = typeof mesh === "object" && mesh !== null ? immutableMeshView(mesh) : mesh;
     const work = validationWork(source, options);
     const measurements = analyzeTriangleMesh(source, {
         ...(options.tolerance === undefined ? {} : { tolerance: options.tolerance }),
@@ -173,7 +172,8 @@ function checkSolidGeometry(mesh, facts, options, { count, maxTests }) {
                 min[axis] = Math.min(min[axis], bounds[order[index] * 6 + axis]);
                 max[axis] = Math.max(max[axis], bounds[order[index] * 6 + axis + 3]);
             }
-        if (end - start <= 8)
+        // Small leaves avoid an 8x8 cross-product of false candidates on thin sampled surfaces.
+        if (end - start <= 4)
             return { start, end, min, max };
         let axis = 0;
         for (let index = 1; index < 3; index++)
@@ -220,7 +220,10 @@ function checkSolidGeometry(mesh, facts, options, { count, maxTests }) {
             visit(a.children[1], a.children[1]);
             return;
         }
-        if (a.children !== undefined) {
+        // Narrow both sides of a candidate pair instead of descending one entire subtree
+        // against a broad node on the other side of the thin sampled surface.
+        if (a.children !== undefined &&
+            (b.children === undefined || a.end - a.start >= b.end - b.start)) {
             visit(a.children[0], b);
             visit(a.children[1], b);
             return;

package/dist/geometry/mesh/mesh-types.js

@@ -0,0 +1 @@
+export {};

package/dist/geometry/mesh/mesh.js

@@ -1,12 +1,13 @@
 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";
 function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = false) {
-    // Snapshot meshes can expose owned-copy accessors. Read each buffer once before traversal.
-    const source = { positions: mesh.positions, indices: mesh.indices };
+    // Normalize immutable storage and read raw input accessors once before traversal.
+    const source = immutableMeshView(mesh);
     const measurements = mode === "measure";
     if (!(source.positions instanceof Float32Array) || !(source.indices instanceof Uint32Array)) {
         throw new GeometryError("INVALID_MESH", "Triangle meshes require Float32Array positions and Uint32Array indices.");
@@ -43,7 +44,7 @@ function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = f
     const parents = topology ? new Int32Array(triangleCount) : null;
     const ranks = topology ? new Uint8Array(triangleCount) : null;
     const referenced = topology ? new Uint8Array(vertexCount) : null;
-    let connectedComponentCount = 0;
+    let shellCount = 0;
     const root = (triangle) => {
         let current = triangle;
         while (parents[current] !== current)
@@ -64,7 +65,7 @@ function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = f
         parents[right] = left;
         if (ranks[left] === ranks[right])
             ranks[left] = ranks[left] + 1;
-        connectedComponentCount -= 1;
+        shellCount -= 1;
     };
     let edgeCount = 0;
     const addEdge = (a, b, triangle) => {
@@ -113,7 +114,7 @@ function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = f
             const triangle = offset / 3;
             parents[triangle] = triangle;
             referenced[a] = referenced[b] = referenced[c] = 1;
-            connectedComponentCount += 1;
+            shellCount += 1;
         }
         if (edges !== null) {
             addEdge(a, b, offset / 3);
@@ -143,19 +144,9 @@ function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = f
         surfaceArea: surfaceArea + areaCorrection,
         triangleCount,
         vertexCount,
-        ...(topology ? { connectedComponentCount, edgeCount } : {}),
+        ...(topology ? { shellCount, edgeCount } : {}),
     });
 }
-/**
- * Validates and measures a mesh in one position and one triangle traversal.
- *
- * Bounds, area in square model units and signed volume in cubic model units are computed without
- * copying or changing the input buffers. Volume is meaningful for consistently wound closed
- * geometry; `requireClosed` checks oriented edge closure. Optional indexed topology counts require
- * 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.
- */
 export function analyzeTriangleMesh(mesh, options = {}) {
     return inspectTriangleMesh(mesh, options, "measure", options.includeTopology ?? false);
 }
@@ -169,7 +160,7 @@ export function analyzeTriangleMesh(mesh, options = {}) {
  * @param mesh - Mesh to inspect.
  * @param options - Empty-mesh, topology, and tolerance policy.
  * @returns The original mesh after successful validation.
- * @throws {@link GeometryError} When any requested invariant fails.
+ * @throws `GeometryError` When any requested invariant fails.
  */
 export function validateTriangleMesh(mesh, options = {}) {
     inspectTriangleMesh(mesh, options);
@@ -180,7 +171,7 @@ export function validateTriangleMesh(mesh, options = {}) {
  *
  * @param mesh - Mesh whose finite complete vertices will be measured.
  * @returns Fresh immutable minimum and maximum XYZ tuples.
- * @throws {@link GeometryError} When the mesh is structurally invalid.
+ * @throws `GeometryError` When the mesh is structurally invalid.
  */
 export const meshBounds = (mesh) => {
     return inspectTriangleMesh(mesh, {}, "bounds");
@@ -192,10 +183,10 @@ export const meshBounds = (mesh) => {
  *
  * @param meshes - One or more meshes to concatenate.
  * @returns Fresh typed arrays with indices offset to their source vertex ranges.
- * @throws {@link GeometryError} When no mesh is supplied or an input is invalid.
+ * @throws `GeometryError` When no mesh is supplied or an input is invalid.
  */
 export function joinTriangleMeshes(meshes) {
-    const sources = meshes.map(({ positions, indices }) => ({ positions, indices }));
+    const sources = meshes.map((mesh) => immutableMeshView(mesh));
     if (sources.length === 0) {
         throw new GeometryError("INVALID_ARGUMENT", "Joining meshes requires at least one mesh.");
     }
@@ -228,7 +219,7 @@ export function joinTriangleMeshes(meshes) {
  * @returns Fresh position and index buffers; the input remains unchanged.
  */
 export function reverseTriangleMesh(mesh) {
-    const source = { positions: mesh.positions, indices: mesh.indices };
+    const source = immutableMeshView(mesh);
     validateTriangleMesh(source);
     const indices = new Uint32Array(source.indices);
     for (let offset = 0; offset < indices.length; offset += 3) {
@@ -249,7 +240,7 @@ export function reverseTriangleMesh(mesh) {
  * @returns A mesh with fresh transformed positions and copied or reversed indices.
  */
 export function transformTriangleMesh(mesh, placement) {
-    const source = { positions: mesh.positions, indices: mesh.indices };
+    const source = immutableMeshView(mesh);
     validateTriangleMesh(source);
     const transform = readTransformMatrix(placement, 3);
     validateTransform3(transform);

package/dist/geometry/mesh-api.js

@@ -0,0 +1,15 @@
+/** Pure triangle mesh construction, processing, and inspection without a host engine. */
+export { extrudeMesh as extrude, loftMesh as loft } from "./loft/loft.js";
+export { revolveMesh as revolve } from "./revolve/revolve-mesh.js";
+export { sweepMesh as sweep } from "./sweeps/sweep-mesh.js";
+export { heightfieldMesh as heightfield, preflightHeightfield } from "./heightfield.js";
+export { threadRidgeMesh as threadRidge, threadSolidMesh as threadSolid, } from "./mechanical/threads/mesh.js";
+export { preflightThreadSolidMesh as preflightThreadSolid } from "./mechanical/threads/mesh-plan.js";
+export { transformTriangleMesh as transform, joinTriangleMeshes as join, reverseTriangleMesh as reverse, meshBounds as bounds, analyzeTriangleMesh as analyze, validateTriangleMesh as validate, } from "./mesh/mesh.js";
+export { computeTriangleMeshCentroid as centroid } from "./mesh/mesh-centroid.js";
+export { analyzeTriangleMeshQuality as analyzeQuality } from "./mesh/mesh-quality.js";
+export { computeTriangleMeshSignature as signature } from "./mesh/mesh-signature.js";
+export { validateSolidMesh as validateSolid } from "./mesh/mesh-solid.js";
+export { renderMesh as render } from "./mesh/mesh-render.js";
+export { optimizePlanarPatches } from "./mesh/mesh-planar.js";
+export { immutableMesh as immutable } from "./immutable-buffer.js";