@metamesh/modeling 0.6.0 → 0.8.0

package/dist/geometry/mesh-edge-table.js

@@ -0,0 +1,126 @@
+const MAXIMUM_UINT32 = 0xffff_ffff;
+const MAXIMUM_SLOT_CAPACITY = 0x1_0000_0000;
+const FORWARD = 1;
+const BACKWARD = 2;
+const PAIRED = 3;
+const INVALID = 4;
+function doubledCapacity(capacity) {
+    const doubled = capacity * 2;
+    if (doubled > MAXIMUM_SLOT_CAPACITY)
+        throw new RangeError("Mesh edge table exceeds Uint32 slot capacity.");
+    return doubled;
+}
+/**
+ * @internal Indexed edge closure and first-face records; coordinates are never welded.
+ * Dense record IDs remain stable when the hash slots grow. Inputs are validated Uint32
+ * vertex indices with distinct endpoints, and triangle IDs fit Uint32 storage.
+ */
+export class IndexedMeshEdgeTable {
+    slotCapacity;
+    mask;
+    slots;
+    recordCapacity;
+    recordCount = 0;
+    lower;
+    upper;
+    states;
+    firstTriangle;
+    constructor(indexCount, includeTopology) {
+        if (!Number.isSafeInteger(indexCount) || indexCount < 0 || indexCount > MAXIMUM_UINT32)
+            throw new RangeError("Mesh edge table requires an index count within Uint32 capacity.");
+        let capacity = 16;
+        // Multiplication avoids the signed-int32 wrap of bitwise capacity doubling.
+        while (capacity < indexCount)
+            capacity = doubledCapacity(capacity);
+        this.slotCapacity = capacity;
+        this.mask = capacity - 1;
+        this.slots = new Uint32Array(capacity);
+        this.recordCapacity = capacity / 2;
+        this.lower = new Uint32Array(this.recordCapacity);
+        this.upper = new Uint32Array(this.recordCapacity);
+        this.states = new Uint8Array(this.recordCapacity);
+        this.firstTriangle = includeTopology ? new Uint32Array(this.recordCapacity) : null;
+    }
+    /** Returns -1 for a new edge, otherwise its first triangle (or zero without topology). */
+    touch(a, b, triangle) {
+        const lower = Math.min(a, b);
+        const upper = Math.max(a, b);
+        const state = a < b ? FORWARD : BACKWARD;
+        let slot = (this.hash(lower, upper) & this.mask) >>> 0;
+        while (this.slots[slot] !== 0) {
+            const record = this.slots[slot] - 1;
+            // Hashes wrap to int32; only the complete two Uint32 keys establish identity.
+            if (this.lower[record] === lower && this.upper[record] === upper) {
+                const previous = this.states[record];
+                this.states[record] =
+                    (previous === FORWARD && state === BACKWARD) ||
+                        (previous === BACKWARD && state === FORWARD)
+                        ? PAIRED
+                        : INVALID;
+                return this.firstTriangle?.[record] ?? 0;
+            }
+            slot = ((slot + 1) & this.mask) >>> 0;
+        }
+        // Repeat touches cannot increase occupancy; check growth only for an absent key.
+        if (this.recordCount + 1 > this.slotCapacity * 0.7) {
+            this.growSlots();
+            return this.touch(a, b, triangle);
+        }
+        if (this.recordCount >= MAXIMUM_UINT32)
+            throw new RangeError("Mesh edge table exceeds Uint32 record capacity.");
+        if (this.recordCount === this.recordCapacity)
+            this.growRecords();
+        const record = this.recordCount;
+        this.slots[slot] = record + 1;
+        this.lower[record] = lower;
+        this.upper[record] = upper;
+        this.states[record] = state;
+        if (this.firstTriangle !== null)
+            this.firstTriangle[record] = triangle;
+        this.recordCount += 1;
+        return -1;
+    }
+    /** Checks exactly two oppositely wound uses after every triangle has been validated. */
+    isClosed() {
+        for (let record = 0; record < this.recordCount; record += 1)
+            if (this.states[record] !== PAIRED)
+                return false;
+        return true;
+    }
+    hash(lower, upper) {
+        const mixed = Math.imul(lower, 0x9e3779b1) ^ Math.imul(upper, 0x85ebca6b);
+        return (mixed ^ (mixed >>> 16)) >>> 0;
+    }
+    growSlots() {
+        const capacity = doubledCapacity(this.slotCapacity);
+        const mask = capacity - 1;
+        const slots = new Uint32Array(capacity);
+        // Paired and invalid records must remain: forgetting either could admit four-face edges.
+        for (let record = 0; record < this.recordCount; record += 1) {
+            let slot = (this.hash(this.lower[record], this.upper[record]) & mask) >>> 0;
+            while (slots[slot] !== 0)
+                slot = ((slot + 1) & mask) >>> 0;
+            slots[slot] = record + 1;
+        }
+        this.slotCapacity = capacity;
+        this.mask = mask;
+        this.slots = slots;
+    }
+    growRecords() {
+        const capacity = doubledCapacity(this.recordCapacity);
+        const lower = new Uint32Array(capacity);
+        const upper = new Uint32Array(capacity);
+        const states = new Uint8Array(capacity);
+        const firstTriangle = this.firstTriangle === null ? null : new Uint32Array(capacity);
+        lower.set(this.lower);
+        upper.set(this.upper);
+        states.set(this.states);
+        if (firstTriangle !== null)
+            firstTriangle.set(this.firstTriangle);
+        this.recordCapacity = capacity;
+        this.lower = lower;
+        this.upper = upper;
+        this.states = states;
+        this.firstTriangle = firstTriangle;
+    }
+}

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

@@ -0,0 +1,123 @@
+const subtract = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+const cross = (a, b) => [
+    a[1] * b[2] - a[2] * b[1],
+    a[2] * b[0] - a[0] * b[2],
+    a[0] * b[1] - a[1] * b[0],
+];
+const distance = (a, b) => Math.hypot(...subtract(a, b));
+const normal = (triangle) => {
+    const value = cross(subtract(triangle[1], triangle[0]), subtract(triangle[2], triangle[0]));
+    const length = Math.hypot(...value);
+    return [value[0] / length, value[1] / length, value[2] / length];
+};
+/** @internal Reuses the same double-precision normal for repeated contact tests. */
+export function prepareSolidTriangle(points) {
+    return { points, normal: normal(points) };
+}
+const project = (point, axis) => axis === 0 ? [point[1], point[2]] : axis === 1 ? [point[0], point[2]] : [point[0], point[1]];
+const turn = (a, b, p) => (b[0] - a[0]) * (p[1] - a[1]) - (b[1] - a[1]) * (p[0] - a[0]);
+const dominantAxis = (value) => {
+    let axis = 0;
+    for (let index = 1; index < 3; index++)
+        if (Math.abs(value[index]) > Math.abs(value[axis]))
+            axis = index;
+    return axis;
+};
+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) => {
+        const b = points[(index + 1) % 3];
+        return sign * turn(a, b, p) >= -epsilon * Math.hypot(b[0] - a[0], b[1] - a[1]);
+    });
+}
+function onSharedBoundary(point, shared, epsilon) {
+    if (shared.some((vertex) => distance(point, vertex) <= epsilon))
+        return true;
+    if (shared.length !== 2)
+        return false;
+    const a = shared[0], b = shared[1], edge = subtract(b, a), delta = subtract(point, a);
+    const length = Math.hypot(...edge), along = dot(delta, edge) / length;
+    return (along >= -epsilon &&
+        along <= length + epsilon &&
+        Math.hypot(...cross(delta, edge)) / length <= epsilon);
+}
+function coplanarIntersection(first, second, direction, shared, epsilon) {
+    const axis = dominantAxis(direction), clip = second.map((point) => project(point, axis));
+    const sign = Math.sign(turn(clip[0], clip[1], clip[2]));
+    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;
+            if (in0)
+                next.push(start);
+            if (in0 !== in1) {
+                const fraction = Math.max(0, Math.min(1, d0 / (d0 - d1)));
+                next.push([
+                    start[0] + (end[0] - start[0]) * fraction,
+                    start[1] + (end[1] - start[1]) * fraction,
+                    start[2] + (end[2] - start[2]) * fraction,
+                ]);
+            }
+        }
+        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));
+}
+/** @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])));
+    const separated = (values) => values.every((value) => value > epsilon) || values.every((value) => value < -epsilon);
+    if (separated(distances0) || separated(distances1))
+        return false;
+    if (distances0.every((value) => Math.abs(value) <= epsilon) &&
+        distances1.every((value) => Math.abs(value) <= epsilon))
+        return coplanarIntersection(first, second, n0, shared, epsilon);
+    const points = [];
+    const collect = (source, target, values, n) => {
+        for (let index = 0; index < 3; index++) {
+            const a = source[index], b = source[(index + 1) % 3];
+            const d0 = values[index], d1 = values[(index + 1) % 3];
+            if (Math.abs(d0) <= epsilon && inside(a, target, n, epsilon))
+                points.push(a);
+            if ((d0 < 0 && d1 > 0) || (d0 > 0 && d1 < 0)) {
+                const fraction = d0 / (d0 - d1);
+                const point = [
+                    a[0] + (b[0] - a[0]) * fraction,
+                    a[1] + (b[1] - a[1]) * fraction,
+                    a[2] + (b[2] - a[2]) * fraction,
+                ];
+                if (inside(point, target, n, epsilon))
+                    points.push(point);
+            }
+        }
+    };
+    collect(first, second, distances0, n1);
+    collect(second, first, distances1, n0);
+    return points.some((point) => !onSharedBoundary(point, shared, epsilon));
+}
+/** @internal Signed solid angle at a point separated from a closed triangle shell. */
+export function triangleSolidAngle(point, triangle) {
+    const a = subtract(triangle[0], point), b = subtract(triangle[1], point), c = subtract(triangle[2], point);
+    const la = Math.hypot(...a), lb = Math.hypot(...b), lc = Math.hypot(...c);
+    return (2 *
+        Math.atan2(dot(a, cross(b, c)), la * lb * lc + dot(a, b) * lc + dot(b, c) * la + dot(c, a) * lb));
+}

package/dist/geometry/mesh-solid.js

@@ -0,0 +1,284 @@
+import { GeometryError } from "./errors.js";
+import { IndexedMeshEdgeTable } from "./mesh-edge-table.js";
+import { prepareSolidTriangle, trianglesIntersectBeyondSharedBoundary, triangleSolidAngle, } from "./mesh-solid-intersections.js";
+import { analyzeTriangleMesh } from "./mesh.js";
+import { resolveGeometryTolerance } from "./tolerance.js";
+const MAXIMUM_TRIANGLES = 200_000;
+const MAXIMUM_TESTS = 2_000_000;
+/**
+ * Checks closed indexed topology, triangle intersections, and alternating nested shell orientation.
+ * Outward exterior shells and inward cavity shells are accepted. Separate shells must not touch,
+ * intersect, or overlap as material. Indexed neighbours may share their own vertex or edge.
+ *
+ * Uses bounded floating-point tests, not exact predicates or repair. Contacts within the selected
+ * tolerance reject conservatively. At most 200,000 triangles and 2,000,000 spatial/containment tests
+ * are supported; exhausting a ceiling throws COMPLEXITY_LIMIT rather than claiming validity.
+ * 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.
+ * @returns The original mesh after every requested check succeeds.
+ */
+export function validateSolidMesh(mesh, options = {}) {
+    analyzeSolidMesh(mesh, options);
+    return mesh;
+}
+function validationWork(mesh, options) {
+    if (typeof mesh !== "object" ||
+        mesh === null ||
+        !(mesh.positions instanceof Float32Array) ||
+        !(mesh.indices instanceof Uint32Array) ||
+        mesh.positions.length % 3 !== 0 ||
+        mesh.indices.length % 3 !== 0)
+        throw new GeometryError("INVALID_MESH", "Solid validation requires complete Float32 XYZ vertices and Uint32 triangle indices.", { operation: "validateSolidMesh" });
+    if (typeof options !== "object" || options === null || Array.isArray(options))
+        throw new GeometryError("INVALID_ARGUMENT", "Solid validation options must be an object.", {
+            operation: "validateSolidMesh",
+        });
+    const count = mesh.indices.length / 3;
+    const maximumTests = options.maximumTests ?? MAXIMUM_TESTS;
+    if (!Number.isSafeInteger(maximumTests) || maximumTests < 1 || maximumTests > MAXIMUM_TESTS)
+        throw new GeometryError("INVALID_ARGUMENT", "Solid validation maximumTests must be an integer from 1 through 2,000,000.", { operation: "validateSolidMesh" });
+    if (count > MAXIMUM_TRIANGLES)
+        throw new GeometryError("COMPLEXITY_LIMIT", "Solid validation exceeds its triangle ceiling.", {
+            operation: "validateSolidMesh",
+            details: { required: count, allowed: MAXIMUM_TRIANGLES },
+        });
+    if (mesh.positions.length / 3 > mesh.indices.length)
+        throw new GeometryError("INVALID_MESH", "Solid validation requires every position-buffer vertex to be referenced.", { operation: "validateSolidMesh" });
+    return { count, maximumTests };
+}
+/** @internal Fresh measurements precede one adjacency traversal for closure, fans, and shells. */
+export function analyzeSolidMesh(mesh, options = {}) {
+    const work = validationWork(mesh, options);
+    const measurements = analyzeTriangleMesh(mesh, {
+        ...(options.tolerance === undefined ? {} : { tolerance: options.tolerance }),
+    });
+    checkSolidGeometry(mesh, measurements, options, work);
+    return measurements;
+}
+/**
+ * @internal Checks the engine's privately owned snapshot using fresh closed-topology measurements.
+ * Callers must own the exact unchanged buffer ranges and use the same tolerance as their analysis.
+ * Never accepts public cached facts; public validation always analyzes mutable input afresh.
+ */
+export function validateAnalyzedSolidMesh(mesh, measurements, options = {}) {
+    checkSolidGeometry(mesh, measurements, options, validationWork(mesh, options));
+}
+function checkSolidGeometry(mesh, facts, options, { count, maximumTests }) {
+    const epsilon = resolveGeometryTolerance(Math.hypot(...facts.bounds.max.map((value, axis) => value - facts.bounds.min[axis])), options.tolerance).linear;
+    let tests = 0;
+    const spend = () => {
+        if (++tests > maximumTests)
+            throw new GeometryError("COMPLEXITY_LIMIT", "Solid validation exhausted its work ceiling.", {
+                operation: "validateSolidMesh",
+                details: { required: tests, allowed: maximumTests },
+            });
+    };
+    const vertex = (index) => [
+        mesh.positions[index * 3],
+        mesh.positions[index * 3 + 1],
+        mesh.positions[index * 3 + 2],
+    ];
+    const triangle = (index) => [
+        vertex(mesh.indices[index * 3]),
+        vertex(mesh.indices[index * 3 + 1]),
+        vertex(mesh.indices[index * 3 + 2]),
+    ];
+    // Cache only exact double-precision normals. Two reusable contact records avoid retaining
+    // per-triangle point objects or allocating new coordinates for every spatial comparison.
+    const normals = new Float64Array(mesh.indices.length);
+    const contactTriangle = () => ({
+        points: [
+            [0, 0, 0],
+            [0, 0, 0],
+            [0, 0, 0],
+        ],
+        normal: [0, 0, 0],
+    });
+    const left = contactTriangle(), right = contactTriangle();
+    const readContactTriangle = (index, target) => {
+        for (let corner = 0; corner < 3; corner++) {
+            const offset = mesh.indices[index * 3 + corner] * 3;
+            const point = target.points[corner];
+            point[0] = mesh.positions[offset];
+            point[1] = mesh.positions[offset + 1];
+            point[2] = mesh.positions[offset + 2];
+            target.normal[corner] = normals[index * 3 + corner];
+        }
+    };
+    const parents = Uint32Array.from({ length: count }, (_, index) => index);
+    const cornerParents = Uint32Array.from({ length: mesh.indices.length }, (_, index) => index);
+    const find = (links, value) => {
+        let current = value;
+        while (links[current] !== current) {
+            links[current] = links[links[current]];
+            current = links[current];
+        }
+        return current;
+    };
+    const root = (value) => find(parents, value);
+    const cornerOf = (triangle, vertex) => {
+        for (let corner = triangle * 3; corner < triangle * 3 + 3; corner++)
+            if (mesh.indices[corner] === vertex)
+                return corner;
+        throw new GeometryError("INVALID_TOPOLOGY", "Mesh edge incidence is inconsistent.", {
+            operation: "validateSolidMesh",
+        });
+    };
+    const edges = new IndexedMeshEdgeTable(mesh.indices.length, true);
+    const bounds = new Float64Array(count * 6);
+    for (let index = 0; index < count; index++) {
+        const points = triangle(index);
+        const direction = prepareSolidTriangle(points).normal;
+        for (let axis = 0; axis < 3; axis++) {
+            normals[index * 3 + axis] = direction[axis];
+            bounds[index * 6 + axis] = Math.min(points[0][axis], points[1][axis], points[2][axis]);
+            bounds[index * 6 + axis + 3] = Math.max(points[0][axis], points[1][axis], points[2][axis]);
+        }
+        for (let edge = 0; edge < 3; edge++) {
+            const a = mesh.indices[index * 3 + edge], b = mesh.indices[index * 3 + ((edge + 1) % 3)];
+            const previous = edges.touch(a, b, index);
+            if (previous >= 0) {
+                parents[root(index)] = root(previous);
+                for (const vertex of [a, b])
+                    cornerParents[find(cornerParents, cornerOf(index, vertex))] = find(cornerParents, cornerOf(previous, vertex));
+            }
+        }
+    }
+    if (!edges.isClosed())
+        throw new GeometryError("INVALID_MESH", "Closed meshes require exactly two oppositely wound faces at every edge.", { operation: "validateSolidMesh" });
+    const firstCorners = new Uint32Array(mesh.positions.length / 3).fill(0xffff_ffff);
+    for (let corner = 0; corner < mesh.indices.length; corner++) {
+        const vertex = mesh.indices[corner], link = find(cornerParents, corner);
+        if (firstCorners[vertex] === 0xffff_ffff)
+            firstCorners[vertex] = link;
+        else if (firstCorners[vertex] !== link)
+            throw new GeometryError("INVALID_TOPOLOGY", "Solid vertices require one connected closed incident triangle fan.", { operation: "validateSolidMesh", details: { vertex } });
+    }
+    if (firstCorners.includes(0xffff_ffff))
+        throw new GeometryError("INVALID_MESH", "Solid validation requires every position-buffer vertex to be referenced.", { operation: "validateSolidMesh" });
+    const order = Array.from({ length: count }, (_, index) => index);
+    const build = (start, end) => {
+        const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+        for (let index = start; index < end; index++)
+            for (let axis = 0; axis < 3; axis++) {
+                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)
+            return { start, end, min, max };
+        let axis = 0;
+        for (let index = 1; index < 3; index++)
+            if (max[index] - min[index] > max[axis] - min[axis])
+                axis = index;
+        const partition = order
+            .slice(start, end)
+            .sort((a, b) => bounds[a * 6 + axis] +
+            bounds[a * 6 + axis + 3] -
+            (bounds[b * 6 + axis] + bounds[b * 6 + axis + 3]));
+        for (let index = 0; index < partition.length; index++)
+            order[start + index] = partition[index];
+        const middle = start + Math.floor((end - start) / 2);
+        return { start, end, min, max, children: [build(start, middle), build(middle, end)] };
+    };
+    const overlaps = (a, b) => a.min.every((value, axis) => value <= b.max[axis] + epsilon && a.max[axis] + epsilon >= b.min[axis]);
+    const pair = (a, b) => {
+        spend();
+        for (let axis = 0; axis < 3; axis++)
+            if (bounds[a * 6 + axis] > bounds[b * 6 + axis + 3] + epsilon ||
+                bounds[b * 6 + axis] > bounds[a * 6 + axis + 3] + epsilon)
+                return;
+        const shared = [];
+        if (root(a) === root(b))
+            for (let index = 0; index < 3; index++) {
+                const id = mesh.indices[a * 3 + index];
+                if (id === mesh.indices[b * 3] ||
+                    id === mesh.indices[b * 3 + 1] ||
+                    id === mesh.indices[b * 3 + 2])
+                    shared.push(vertex(id));
+            }
+        readContactTriangle(a, left);
+        readContactTriangle(b, right);
+        if (trianglesIntersectBeyondSharedBoundary(left, right, shared, epsilon))
+            throw new GeometryError("SELF_INTERSECTION", "Solid triangles intersect or touch beyond their indexed boundary.", { operation: "validateSolidMesh", details: { triangleA: a, triangleB: b } });
+    };
+    const visit = (a, b) => {
+        spend();
+        if (!overlaps(a, b))
+            return;
+        if (a === b && a.children !== undefined) {
+            visit(a.children[0], a.children[0]);
+            visit(a.children[0], a.children[1]);
+            visit(a.children[1], a.children[1]);
+            return;
+        }
+        if (a.children !== undefined) {
+            visit(a.children[0], b);
+            visit(a.children[1], b);
+            return;
+        }
+        if (b.children !== undefined) {
+            visit(a, b.children[0]);
+            visit(a, b.children[1]);
+            return;
+        }
+        for (let first = a.start; first < a.end; first++)
+            for (let second = b.start; second < b.end; second++)
+                if (a !== b || first < second)
+                    pair(order[first], order[second]);
+    };
+    const tree = build(0, count);
+    visit(tree, tree);
+    const shells = new Map();
+    for (let index = 0; index < count; index++) {
+        const id = root(index), shell = shells.get(id);
+        if (shell === undefined)
+            shells.set(id, [index]);
+        else
+            shell.push(index);
+    }
+    const entries = [...shells.values()].map((triangles) => {
+        const origin = triangle(triangles[0])[0];
+        let volume = 0;
+        const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+        for (const index of triangles) {
+            const [a, b, c] = triangle(index).map((point) => point.map((value, axis) => value - origin[axis]));
+            volume +=
+                (a[0] * (b[1] * c[2] - b[2] * c[1]) +
+                    a[1] * (b[2] * c[0] - b[0] * c[2]) +
+                    a[2] * (b[0] * c[1] - b[1] * c[0])) /
+                    6;
+            for (let axis = 0; axis < 3; axis++) {
+                min[axis] = Math.min(min[axis], bounds[index * 6 + axis]);
+                max[axis] = Math.max(max[axis], bounds[index * 6 + axis + 3]);
+            }
+        }
+        return { triangles, origin, volume, min, max };
+    });
+    for (const shell of entries) {
+        let depth = 0;
+        for (const other of entries) {
+            spend();
+            if (shell === other ||
+                shell.origin.some((value, axis) => value < other.min[axis] || value > other.max[axis]))
+                continue;
+            let angle = 0;
+            for (const index of other.triangles) {
+                spend();
+                angle += triangleSolidAngle(shell.origin, triangle(index));
+            }
+            if (Math.abs(angle) > 2 * Math.PI)
+                depth++;
+        }
+        if ((depth % 2 === 0 ? shell.volume : -shell.volume) <= epsilon ** 3)
+            throw new GeometryError("INVALID_TOPOLOGY", "Solid shells require outward exteriors and inward nested cavity boundaries.", {
+                operation: "validateSolidMesh",
+                details: {
+                    triangle: shell.triangles[0],
+                    nestingDepth: depth,
+                    signedVolume: shell.volume,
+                },
+            });
+    }
+}

package/dist/geometry/mesh.js

@@ -1,4 +1,5 @@
 import { GeometryError } from "./errors.js";
+import { IndexedMeshEdgeTable } from "./mesh-edge-table.js";
 import { writeMeshVertex } from "./numeric.js";
 import { resolveGeometryTolerance } from "./tolerance.js";
 import { transformDeterminant3, validateTransform3 } from "./transform3.js";
@@ -33,7 +34,7 @@ function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = f
     const extent = vertexCount === 0 ? 0 : Math.max(max[0] - min[0], max[1] - min[1], max[2] - min[2]);
     const minimumDoubleArea = resolveGeometryTolerance(extent, options.tolerance).area;
     const edges = options.requireClosed || topology
-        ? new Map()
+        ? new IndexedMeshEdgeTable(mesh.indices.length, topology)
         : null;
     const triangleCount = mesh.indices.length / 3;
     const parents = topology ? new Int32Array(triangleCount) : null;
@@ -64,23 +65,11 @@ function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = f
     };
     let edgeCount = 0;
     const addEdge = (a, b, triangle) => {
-        const lower = Math.min(a, b), upper = Math.max(a, b);
-        let neighbors = edges.get(lower);
-        if (neighbors === undefined) {
-            neighbors = new Map();
-            edges.set(lower, neighbors);
-        }
-        let edge = neighbors.get(upper);
-        if (edge === undefined) {
-            edge = { count: 0, balance: 0, ...(topology ? { firstTriangle: triangle } : {}) };
-            neighbors.set(upper, edge);
+        const firstTriangle = edges.touch(a, b, triangle);
+        if (firstTriangle === -1)
             edgeCount += 1;
-        }
-        else if (topology) {
-            connect(edge.firstTriangle, triangle);
-        }
-        edge.count += 1;
-        edge.balance += a < b ? 1 : -1;
+        else if (topology)
+            connect(firstTriangle, triangle);
     };
     // Keep the two hot-loop accumulators independent and local: no mutable numeric objects escape.
     let surfaceArea = 0, areaCorrection = 0, signedVolume = 0, volumeCorrection = 0;
@@ -129,14 +118,8 @@ function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = f
             addEdge(c, a, offset / 3);
         }
     }
-    if (options.requireClosed && edges !== null) {
-        for (const neighbors of edges.values())
-            for (const edge of neighbors.values()) {
-                if (edge.count !== 2 || edge.balance !== 0) {
-                    throw new GeometryError("INVALID_MESH", "Closed meshes require exactly two oppositely wound faces at every edge.");
-                }
-            }
-    }
+    if (options.requireClosed && edges !== null && !edges.isClosed())
+        throw new GeometryError("INVALID_MESH", "Closed meshes require exactly two oppositely wound faces at every edge.");
     if (referenced !== null) {
         for (let vertex = 0; vertex < vertexCount; vertex += 1) {
             if (referenced[vertex] === 0) {

package/dist/geometry/paths/path.js

@@ -26,5 +26,7 @@ export const cumulativePathLengths = (path, limits = {}) => {
     }
     return cumulative;
 };
-/** Returns total sampled 3D path length, or zero for an empty path. */
+/**
+ * Returns total sampled 3D path length, or zero for an empty path.
+ */
 export const pathLength = (path, limits = {}) => cumulativePathLengths(path, limits).at(-1) ?? 0;

package/dist/geometry/paths/resampling.js

@@ -99,7 +99,8 @@ function resamplePolyline(path, dimensions, options, createWriter) {
     }
     return writer.finish();
 }
-/** Resamples a spatial polyline at equal arc lengths with directed outgoing tangents.
+/**
+ * Resamples a spatial polyline at equal arc lengths with directed outgoing tangents.
  * @remarks Open paths retain both endpoints; closed paths include the closing edge and omit the
  * repeated seam. Repeated adjacent inputs and explicit closing duplicates are removed. Physical
  * maxSegmentLength bounds arc-length intervals; exact counts override that policy. Output edges

package/dist/geometry/profiles/matched.js

@@ -68,6 +68,14 @@ const contours = (component) => [
  * Cubics share a checked uniform parameter grid, including grids selected by exact paired requests.
  * Input order and winding are preserved. Collapsed spans retain repeated logical slots, which
  * the engine maps to shared physical vertices while omitting degenerate faces.
+ *
+ * @example Match named rectangle landmarks
+ * ```ts
+ * matchProfiles([
+ *   rectangleProfile({ size: [20, 12] }),
+ *   rectangleProfile({ size: [30, 20], treatment: { kind: "round", radius: 3 } }),
+ * ]);
+ * ```
  */
 export function matchProfiles(profiles, options = {}) {
     if (!isArray(profiles) || profiles.length === 0 || profiles.length > 1000)