@metamesh/modeling 0.14.0 → 0.16.0

package/dist/engine/index.js

@@ -97,8 +97,13 @@ function engineFromModule(module, engineLimits) {
  */
 export async function createModelEngine(options = {}) {
     const limits = resolveModelingLimits(options.limits);
+    const wasmUrl = options.wasmUrl === undefined ? modelingWasmUrl : options.wasmUrl;
+    if (typeof wasmUrl !== "string" || wasmUrl.trim().length === 0)
+        throw new GeometryError("INVALID_ARGUMENT", "wasmUrl must be a non-empty asset URL string.", {
+            operation: "createModelEngine",
+        });
     const module = await createManifoldModule({
-        locateFile: options.locateFile ?? (() => modelingWasmUrl),
+        locateFile: () => wasmUrl,
     });
     module.setup();
     return engineFromModule(module, limits);

package/dist/engine/inspection-operations.js

@@ -1,10 +1,11 @@
+import { vector3Data } from "../geometry/math/vector-value.js";
 import { ownScopedManifoldValue } from "./native/context.js";
 import { copiedMeshViews } from "./native/copied-views.js";
 import { measureSolidDistance } from "./native/distance.js";
 import { assertNativeSolidStatus } from "./native/status.js";
 /** Internal host-bound inspection operations. */
 export function createInspectionOperations(environment) {
-    const { scope, throwGeometryError, nativeSolid, resolveHandle, ownSolid, ownSection, validateFiniteNumber, requirePositiveNumber, validateCoordinates, analyzedMeshFor, solidInspectionFor, sectionInspectionFor, } = environment;
+    const { scope, throwGeometryError, nativeSolid, resolveHandle, ownSolid, ownSection, wrapSolid, wrapSection, validateFiniteNumber, requirePositiveNumber, validateCoordinates, analyzedMeshFor, solidInspectionFor, sectionInspectionFor, solidComponentsFor, sectionComponentsFor, } = environment;
     const operations = {
         toTriangleMesh: (value) => copiedMeshViews(analyzedMeshFor(value).mesh, new Map()),
         inspectSection: sectionInspectionFor,
@@ -16,12 +17,14 @@ export function createInspectionOperations(environment) {
             return native.value.isEmpty();
         },
         distance: (handle, other) => measureSolidDistance(nativeSolid(handle), nativeSolid(other)),
-        rayCast: (handle, origin, endpoint) => {
-            validateCoordinates(origin, 3, "rayCast");
-            validateCoordinates(endpoint, 3, "rayCast");
+        castSegment: (handle, inputOrigin, inputEndpoint) => {
+            const origin = vector3Data(inputOrigin);
+            const endpoint = vector3Data(inputEndpoint);
+            validateCoordinates(origin, 3, "castSegment");
+            validateCoordinates(endpoint, 3, "castSegment");
             const segmentLength = Math.hypot(...origin.map((value, axis) => value - endpoint[axis]));
             if (!Number.isFinite(segmentLength) || segmentLength === 0)
-                throwGeometryError("DEGENERATE_GEOMETRY", "rayCast", "Ray segment endpoints must differ.");
+                throwGeometryError("DEGENERATE_GEOMETRY", "castSegment", "Segment endpoints must differ.");
             return Object.freeze(nativeSolid(handle)
                 .rayCast([...origin], [...endpoint])
                 .map((hit) => Object.freeze({
@@ -34,9 +37,8 @@ export function createInspectionOperations(environment) {
         components: ((handle) => {
             const native = resolveHandle(handle);
             if (native.kind === "section")
-                return Object.freeze(native.value.isEmpty() ? [] : native.value.decompose().map(ownSection));
-            assertNativeSolidStatus(native.value, "components");
-            return Object.freeze(native.value.decompose().map(ownSolid));
+                return Object.freeze(sectionComponentsFor(handle).map(wrapSection));
+            return Object.freeze(solidComponentsFor(handle).map(wrapSolid));
         }),
         simplify: ((handle, tolerance) => {
             const native = resolveHandle(handle);
@@ -46,9 +48,9 @@ export function createInspectionOperations(environment) {
             const original = ownScopedManifoldValue(scope, native.value.asOriginal());
             return ownSolid(original.simplify(distance));
         }),
-        setTolerance: (handle, tolerance) => {
-            if (validateFiniteNumber(tolerance, "setTolerance") < 0)
-                throwGeometryError("INVALID_ARGUMENT", "setTolerance", "Tolerance must be nonnegative millimetres.");
+        withTolerance: (handle, tolerance) => {
+            if (validateFiniteNumber(tolerance, "withTolerance") < 0)
+                throwGeometryError("INVALID_ARGUMENT", "withTolerance", "Tolerance must be nonnegative millimetres.");
             return ownSolid(nativeSolid(handle).setTolerance(tolerance));
         },
     };

package/dist/engine/knuckle-hinge-operation.js

@@ -0,0 +1,85 @@
+import { GeometryError } from "../geometry/errors.js";
+import { resolveKnuckleHinge } from "../geometry/mechanical/knuckle-hinge.js";
+import { assertPrimitiveOptions } from "../geometry/primitive-resolvers.js";
+import { assertSamplingCount } from "../geometry/sampling-limits.js";
+/** Composes existing scoped operations after resolving both halves against one host policy. */
+export function createKnuckleHingeOperation(environment, operations) {
+    return (options) => {
+        environment.assertActive();
+        assertPrimitiveOptions(options, "knuckleHinge");
+        const resolved = environment.withResolutionDefaults(options);
+        const d = resolveKnuckleHinge(options, resolved);
+        assertSamplingCount(d.segments * d.spec.knuckleCount * 2, "knuckleHinge", resolved.limits.maxVertices);
+        const invalid = (message) => {
+            throw new GeometryError("INVALID_ARGUMENT", message, { operation: "knuckleHinge" });
+        };
+        const validateHalf = (half = {}) => {
+            assertPrimitiveOptions(half, "knuckleHinge");
+            const chamfer = half.barrelChamfer ?? 0;
+            if (!Number.isFinite(chamfer) ||
+                chamfer < 0 ||
+                2 * chamfer >= d.knuckleLength ||
+                chamfer >= d.minimumBarrelWall)
+                invalid("barrelChamfer must be nonnegative and leave a positive axial band and faceted barrel wall.");
+            const web = half.web;
+            if (web !== undefined) {
+                assertPrimitiveOptions(web, "knuckleHinge");
+                if (web.direction !== "positive-y" && web.direction !== "negative-y")
+                    invalid("Unknown web direction.");
+                if (!Number.isFinite(web.reach) ||
+                    web.reach <= 0 ||
+                    !Number.isFinite(web.thickness) ||
+                    web.thickness <= 0 ||
+                    !Number.isFinite(web.zMin) ||
+                    !Number.isFinite(web.zMin + web.thickness))
+                    invalid("Web dimensions must be finite, with positive reach and thickness.");
+                const innerRadius = d.barrelRadius * Math.cos(Math.PI / d.segments);
+                if (web.zMin >= innerRadius || web.zMin + web.thickness <= -innerRadius)
+                    invalid("A web must overlap the interior of its barrel.");
+            }
+            return { chamfer, web };
+        };
+        // Validate both attachments before allocating either half.
+        const a = validateHalf(options.halfA);
+        const b = validateHalf(options.halfB);
+        const axial = (radius, start, length, bore = false, chamfer = 0) => operations.translate(operations.rotate(operations.cylinder({
+            radius,
+            height: length,
+            center: false,
+            segments: d.segments,
+            sizing: bore ? "face" : "vertex",
+            ...(chamfer === 0
+                ? {}
+                : {
+                    ends: {
+                        bottom: { kind: "chamfer", distance: chamfer },
+                        top: { kind: "chamfer", distance: chamfer },
+                    },
+                }),
+        }), [0, 90, 0]), [start, 0, 0]);
+        const buildHalf = (side, { chamfer, web }) => {
+            const features = [];
+            for (const interval of d.knuckles) {
+                if (interval.side !== side)
+                    continue;
+                features.push(axial(d.barrelRadius, interval.start, interval.length, false, chamfer));
+                if (web !== undefined)
+                    features.push(operations.translate(operations.box({
+                        size: [interval.length, web.reach, web.thickness],
+                        center: false,
+                    }), [interval.start, web.direction === "positive-y" ? 0 : -web.reach, web.zMin]));
+            }
+            if (side === "a" && d.pin !== null)
+                features.push(axial(d.pinRadius, d.pin.start, d.pin.length));
+            const solid = operations.union(features);
+            // Overtravel is numerical cutter extent, independent of the physical radial/axial allowances.
+            const overtravel = Math.min(d.knuckleLength, d.barrelRadius) * 0.01;
+            return side === "a" && d.pin !== null
+                ? solid
+                : operations.subtract(solid, [
+                    axial(d.boreRadius, -d.spec.length / 2 - overtravel, d.spec.length + 2 * overtravel, true),
+                ]);
+        };
+        return Object.freeze({ halfA: buildHalf("a", a), halfB: buildHalf("b", b), axis: d.axis });
+    };
+}

package/dist/engine/loft-operations.js

@@ -2,11 +2,13 @@ import { GeometryError } from "../geometry/errors.js";
 import { loftProfilePointCount, pointLoftProfile, prepareLoftGeometry, } from "../geometry/loft/loft-geometry.js";
 import { loftFrame, resolveLoftControls } from "../geometry/loft/loft-options.js";
 import { simpleLoftMesh } from "../geometry/loft/loft-simple-mesh.js";
-import { measureTriangleMesh } from "../geometry/mesh/mesh.js";
+import { analyzeTriangleMesh } from "../geometry/mesh/mesh.js";
+import { capturePath2Input, path2InputData, } from "../geometry/paths/path-value.js";
 import { assertSamplingCount } from "../geometry/sampling-limits.js";
 import { correspondingPrimitiveProfiles, rectangularPrimitiveFamily, } from "./primitive-profiles.js";
 import { buildProfileLoftMesh } from "./profile-mesh.js";
 const explicitProfile = (value) => typeof value === "object" && value !== null && "components" in value;
+const pointProfile = (value) => Array.isArray(value) || (typeof value === "object" && value !== null && "toData" in value);
 const fail = (message) => {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation: "loft" });
 };
@@ -63,21 +65,40 @@ function primitivePolygon(profile) {
 }
 /** Private host adapter: known authored identity or explicitly requested geometric correspondence. */
 export function createLoftOperation(environment, solidFromMesh) {
-    return (stations, value = {}) => {
+    return (inputStations, value = {}) => {
         environment.assertActive();
-        if (!Array.isArray(stations) || stations.length < 2)
+        if (!Array.isArray(inputStations) || inputStations.length < 2)
             fail("Loft requires at least two stations.");
-        assertSamplingCount(stations.length, "loft", environment.limits.maxPathPoints);
-        stations.forEach((station) => loftFrame(station));
-        resolveLoftControls(value, stations.length);
-        const rawPoints = stations.reduce((sum, station) => sum +
-            (explicitProfile(station.profile)
-                ? loftProfilePointCount(station.profile)
-                : Array.isArray(station.profile)
-                    ? station.profile.length
-                    : environment.nativeSection(station.profile).numVert()), 0);
-        assertSamplingCount(rawPoints, "loft", 1_000_000);
+        assertSamplingCount(inputStations.length, "loft", environment.limits.maxPathPoints);
+        inputStations.forEach((station) => loftFrame(station));
         let selected = environment.withResolutionDefaults(value);
+        resolveLoftControls(value, inputStations.length);
+        const captured = inputStations.map(({ profile, ...placement }) => {
+            const source = pointProfile(profile) ? capturePath2Input(profile, true) : undefined;
+            return { placement, profile: source?.input ?? profile, count: source?.count };
+        });
+        let rawPoints = 0, fixedPoints = 0;
+        for (const { profile, count } of captured) {
+            const fixed = count === undefined
+                ? explicitProfile(profile)
+                    ? loftProfilePointCount(profile)
+                    : environment.nativeSection(profile).numVert()
+                : 0;
+            fixedPoints += fixed;
+            rawPoints += count ?? fixed;
+            assertSamplingCount(rawPoints, "loft", 1_000_000);
+        }
+        let remaining = 1_000_000 - fixedPoints;
+        const stations = captured.map(({ placement, profile, count }) => {
+            if (count === undefined)
+                return { ...placement, profile };
+            const points = path2InputData(profile, true, {
+                maxPathPoints: Math.max(1, Math.min(selected.limits.maxProfilePoints, remaining)),
+            }).points;
+            assertSamplingCount(points.length, "loft", remaining);
+            remaining -= points.length;
+            return { ...placement, profile: points };
+        });
         const controls = resolveLoftControls(selected, stations.length);
         const explicit = stations.some((station) => explicitProfile(station.profile));
         let profiles, authoritative = false;
@@ -145,7 +166,7 @@ export function createLoftOperation(environment, solidFromMesh) {
             station.profile.components[0].holes.length === 0))
             return solidFromMesh(simpleLoftMesh(geometry, selected.limits));
         const mesh = buildProfileLoftMesh(environment.module, geometry.stations, selected.limits, false, 0, (station, contour, slot) => geometry.world[station][contour][slot]);
-        if (measureTriangleMesh(mesh).signedVolume < 0)
+        if (analyzeTriangleMesh(mesh).signedVolume < 0)
             for (let index = 0; index < mesh.indices.length; index += 3) {
                 const b = mesh.indices[index + 1];
                 mesh.indices[index + 1] = mesh.indices[index + 2];

package/dist/engine/mechanical-operations.js

@@ -1,6 +1,7 @@
+import { createKnuckleHingeOperation } from "./knuckle-hinge-operation.js";
 import * as kernel from "./native/index.js";
 /** Internal host-bound mechanical operations. */
-export function createMechanicalOperations(environment) {
+export function createMechanicalOperations(environment, construction) {
     const { resolution } = environment;
     const { scope, assertActive, wrapSolid, withResolutionDefaults } = environment;
     const nutOptions = (value) => ({
@@ -9,6 +10,7 @@ export function createMechanicalOperations(environment) {
     });
     // Explicit preflight preserves the stable error operation names exposed by these constructors.
     const operations = {
+        knuckleHinge: createKnuckleHingeOperation(environment, construction),
         threadRidge: (value) => {
             assertActive();
             return wrapSolid(kernel.threadRidge(scope, withResolutionDefaults(value)));

package/dist/engine/model-summary.js

@@ -1,11 +1,12 @@
 import { GeometryError } from "../geometry/errors.js";
 /** Counts manufacturing instances while charging shared backing storage only once. */
 export function createModelSummary(limits) {
-    let vertices = 0, triangles = 0, bytes = 0, volumeMm3 = 0;
+    let vertices = 0, triangles = 0, bytes = 0, partCount = 0, volumeMm3 = 0;
     const storage = new Set();
     const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
     return {
         add(geometry) {
+            partCount++;
             const measurements = geometry.measurements;
             vertices += measurements.vertexCount;
             triangles += measurements.triangleCount;
@@ -15,7 +16,8 @@ export function createModelSummary(limits) {
                     storage.add(buffer);
                     bytes += buffer.byteLength;
                 }
-            if (vertices > limits.maxVertices ||
+            if (partCount > limits.maxParts ||
+                vertices > limits.maxVertices ||
                 triangles > limits.maxTriangles ||
                 bytes > limits.maxBytes)
                 throw new GeometryError("COMPLEXITY_LIMIT", "Aggregate output exceeds the execution limits.", { operation: "generate" });
@@ -29,9 +31,10 @@ export function createModelSummary(limits) {
             return {
                 bounds: Object.freeze({ min: Object.freeze(min), max: Object.freeze(max) }),
                 stats: Object.freeze({
-                    vertices,
-                    triangles,
-                    bytes,
+                    partCount,
+                    vertexCount: vertices,
+                    triangleCount: triangles,
+                    byteCount: bytes,
                     volumeMm3,
                     buildMs: builtAt - startedAt,
                     finalizationMs: endedAt - builtAt,

package/dist/engine/modeling-context.js

@@ -15,7 +15,14 @@ export function createModelingContext(owner, initialResolution) {
         const sections = createSectionOperations(environment, transforms);
         const primitives = createPrimitiveOperations(environment, transforms, sections);
         const construction = createConstructionOperations(environment, sections);
-        const mechanical = createMechanicalOperations(environment);
+        const mechanical = createMechanicalOperations(environment, {
+            cylinder: primitives.cylinder,
+            box: primitives.box,
+            union: construction.union,
+            rotate: transforms.operations.rotate,
+            translate: transforms.operations.translate,
+            subtract: construction.subtract,
+        });
         const patterns = createPatternOperations(environment, transforms);
         const inspection = createInspectionOperations(environment);
         return Object.freeze({

package/dist/engine/native/material-components.js

@@ -0,0 +1,305 @@
+import { GeometryError } from "../../geometry/errors.js";
+import { triangleSolidAngle } from "../../geometry/mesh/mesh-solid-intersections.js";
+import { assertMeshAllocationWithinLimits, } from "../../geometry/model-limits.js";
+import { ownScopedManifoldValue, scopedManifoldModule, } from "./context.js";
+import { assertNativeSolidStatus } from "./status.js";
+const MAXIMUM_CONTAINMENT_TESTS = 2_000_000;
+/** Certifies the native sign only when its floating-point error cannot reach zero. */
+function certifiedNativeOrientation(volume, bounds, triangles) {
+    const magnitudes = bounds.min.map((value, axis) => Math.max(Math.abs(value), Math.abs(bounds.max[axis])));
+    const ranges = bounds.min.map((value, axis) => bounds.max[axis] - value);
+    const magnitude = Math.max(...magnitudes);
+    // Pinned Manifold 3.5.4 src/properties.cpp:245-270 computes edge-cross/dot/6
+    // terms q followed by s'=fl(s+q), c+=fl(fl(s-s')+q). In exact algebra the
+    // compensation cancels the running-sum errors. For u=2^-53 and n*u<1/4,
+    // remaining summation error is <=(6u+7n^2*u^2)*sum(abs(q)). For
+    // P=sum(Mi*Rj*Rk), each triangle's absolute product sum is <=P/3 and its
+    // arithmetic error is <=64uP. Their total is <80*u*n*P*(1+n^2*u);
+    // 512 also covers rounding of ranges/P. This selects arithmetic, never size.
+    // These windows keep the bound finite/normal and absolute subnormal errors
+    // below its spare margin; coordinates outside them use exact arithmetic.
+    if (!Number.isFinite(volume) ||
+        triangles < 4 ||
+        triangles >= 2 ** 31 ||
+        magnitude < 2 ** -300 ||
+        magnitude > 2 ** 300 ||
+        ranges.some((range) => range < 2 ** -300 || range > 2 ** 300))
+        return undefined;
+    const productSum = magnitudes[0] * ranges[1] * ranges[2] +
+        magnitudes[1] * ranges[0] * ranges[2] +
+        magnitudes[2] * ranges[0] * ranges[1];
+    const unitRoundoff = Number.EPSILON / 2;
+    const error = 512 * unitRoundoff * triangles * productSum * (1 + triangles * triangles * unitRoundoff);
+    if (!Number.isFinite(error))
+        return undefined;
+    return Math.abs(volume) > error ? (volume < 0 ? -1 : 1) : undefined;
+}
+/** Observes native coordinates and topology without converting geometry to Float32. */
+function nativeShellMesh(scope, shell, limits) {
+    const vertices = shell.numVert();
+    const properties = shell.numPropVert();
+    const triangles = shell.numTri();
+    // Both native observation work and copied topology stay within the host's mesh limits.
+    // Charge the Float64 coordinates, Float32 property mesh, index map and triangle indices.
+    assertMeshAllocationWithinLimits(Math.max(vertices, properties), triangles, vertices * 24 + properties * (shell.numProp() + 4) * 4 + triangles * 12, "components", limits);
+    const coordinates = new Float64Array(vertices * 3);
+    const encoded = ownScopedManifoldValue(scope, shell.warpBatch((positions, count) => {
+        coordinates.set(positions);
+        for (let vertex = 0; vertex < count; vertex++) {
+            // Exact Float32-safe IDs recover native indices even when property vertices
+            // are duplicated or reordered by getMesh(). The original coordinates stay Float64.
+            positions[vertex * 3] = vertex % 65536;
+            positions[vertex * 3 + 1] = Math.floor(vertex / 65536);
+            positions[vertex * 3 + 2] = 0;
+        }
+    }));
+    assertNativeSolidStatus(encoded, "components");
+    if (encoded.numVert() !== vertices || encoded.numTri() !== triangles)
+        throw new GeometryError("INVALID_TOPOLOGY", "Native observation changed shell topology.", {
+            operation: "components",
+        });
+    const mesh = encoded.getMesh();
+    if (mesh.numVert !== properties || mesh.numTri !== triangles)
+        throw new GeometryError("INVALID_TOPOLOGY", "Native observation changed property topology.", {
+            operation: "components",
+        });
+    const indices = new Uint32Array(properties);
+    for (let vertex = 0; vertex < properties; vertex++) {
+        const offset = vertex * mesh.numProp;
+        const low = mesh.vertProperties[offset];
+        const high = mesh.vertProperties[offset + 1];
+        const index = low + high * 65536;
+        if (!Number.isInteger(low) ||
+            low < 0 ||
+            low >= 65536 ||
+            !Number.isInteger(high) ||
+            high < 0 ||
+            !Number.isSafeInteger(index) ||
+            index >= vertices ||
+            mesh.vertProperties[offset + 2] !== 0)
+            throw new GeometryError("INVALID_TOPOLOGY", "Native observation lost a vertex identity.", {
+                operation: "components",
+            });
+        indices[vertex] = index;
+    }
+    return { coordinates, vertexIndices: indices, triangles: mesh.triVerts };
+}
+/** Computes signed enclosed volume without rounding, including folded contact boundaries. */
+function nativeShellOrientation(mesh) {
+    const { coordinates, vertexIndices, triangles } = mesh;
+    const bits = new DataView(new ArrayBuffer(8));
+    const fractionMask = (1n << 52n) - 1n;
+    const representation = (value) => {
+        bits.setFloat64(0, value);
+        return bits.getBigUint64(0);
+    };
+    let minimumExponent = 2047;
+    for (const value of coordinates) {
+        if (!Number.isFinite(value))
+            throw new GeometryError("NON_FINITE_VALUE", "Native coordinates must be finite.", {
+                operation: "components",
+            });
+        if (value !== 0)
+            minimumExponent = Math.min(minimumExponent, Number((representation(value) >> 52n) & 2047n) || 1);
+    }
+    // One common binary scale makes each coefficient exact while avoiding thousands
+    // of unnecessary zero bits for ordinary millimetre coordinates.
+    const integer = (value) => {
+        if (value === 0)
+            return 0n;
+        const encodedValue = representation(value);
+        const exponent = Number((encodedValue >> 52n) & 2047n);
+        const significand = (encodedValue & fractionMask) | (exponent === 0 ? 0n : 1n << 52n);
+        const magnitude = significand << BigInt((exponent || 1) - minimumExponent);
+        return encodedValue >> 63n === 0n ? magnitude : -magnitude;
+    };
+    const origin = [integer(coordinates[0]), integer(coordinates[1]), integer(coordinates[2])];
+    const pointAt = (propertyVertex) => {
+        const offset = vertexIndices[propertyVertex] * 3;
+        return [
+            integer(coordinates[offset]) - origin[0],
+            integer(coordinates[offset + 1]) - origin[1],
+            integer(coordinates[offset + 2]) - origin[2],
+        ];
+    };
+    let volume = 0n;
+    for (let triangle = 0; triangle < triangles.length; triangle += 3) {
+        const a = pointAt(triangles[triangle]);
+        const b = pointAt(triangles[triangle + 1]);
+        const c = pointAt(triangles[triangle + 2]);
+        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]);
+    }
+    return volume < 0n ? -1 : volume > 0n ? 1 : 0;
+}
+/** Internal material decomposition; inward boundary shells stay with their enclosing exterior. */
+export function solidMaterialComponents(scope, solid, limits) {
+    assertNativeSolidStatus(solid, "components");
+    assertMeshAllocationWithinLimits(Math.max(solid.numVert(), solid.numPropVert()), solid.numTri(), solid.numPropVert() * (solid.numProp() + 3) * 4 + solid.numTri() * 12, "components", limits);
+    const shells = solid.decompose().map((shell) => ownScopedManifoldValue(scope, shell));
+    const boundaries = shells
+        .map((shell) => ({ shell, volume: shell.volume(), bounds: shell.boundingBox() }))
+        .filter(({ bounds }) => {
+        // Coplanar Boolean contact can leave native boundary shells without any material.
+        // Exact collapsed native bounds identify axis-aligned contacts cheaply. Do not
+        // use volume, an epsilon or Float32 mesh tests: any of them could
+        // discard a thin positive piece or an inward shell enclosing a real cavity.
+        return bounds.min.every((value, axis) => value !== bounds.max[axis]);
+    })
+        .map((entry) => ({
+        ...entry,
+        orientation: certifiedNativeOrientation(entry.volume, entry.bounds, entry.shell.numTri()),
+    }));
+    const uncertain = boundaries.filter(({ orientation }) => orientation === undefined);
+    if (uncertain.length > 0) {
+        let vertices = 0;
+        let properties = 0;
+        let triangles = 0;
+        let bytes = 0;
+        for (const { shell } of uncertain) {
+            vertices += shell.numVert();
+            properties += shell.numPropVert();
+            triangles += shell.numTri();
+            bytes +=
+                shell.numVert() * 24 +
+                    shell.numPropVert() * (shell.numProp() + 4) * 4 +
+                    shell.numTri() * 12;
+        }
+        assertMeshAllocationWithinLimits(Math.max(vertices, properties), triangles, bytes, "components", limits);
+    }
+    const meshes = new Map();
+    let observedVertices = 0;
+    let observedProperties = 0;
+    let observedTriangles = 0;
+    let observedBytes = 0;
+    const meshFor = (shell) => {
+        const cached = meshes.get(shell);
+        if (cached !== undefined)
+            return cached;
+        const vertices = observedVertices + shell.numVert();
+        const properties = observedProperties + shell.numPropVert();
+        const triangles = observedTriangles + shell.numTri();
+        const bytes = observedBytes +
+            shell.numVert() * 24 +
+            shell.numPropVert() * (shell.numProp() + 4) * 4 +
+            shell.numTri() * 12;
+        assertMeshAllocationWithinLimits(Math.max(vertices, properties), triangles, bytes, "components", limits);
+        const mesh = nativeShellMesh(scope, shell, limits);
+        meshes.set(shell, mesh);
+        observedVertices = vertices;
+        observedProperties = properties;
+        observedTriangles = triangles;
+        observedBytes = bytes;
+        return mesh;
+    };
+    const entries = boundaries
+        .map((entry) => ({
+        ...entry,
+        orientation: entry.orientation ?? nativeShellOrientation(meshFor(entry.shell)),
+    }))
+        .filter(({ orientation }) => orientation !== 0);
+    let tests = 0;
+    const spend = (count = 1) => {
+        tests += count;
+        if (tests > MAXIMUM_CONTAINMENT_TESTS)
+            throw new GeometryError("COMPLEXITY_LIMIT", "Material component containment exceeds its work ceiling.", {
+                operation: "components",
+                details: { required: tests, allowed: MAXIMUM_CONTAINMENT_TESTS },
+            });
+    };
+    const exteriors = entries.filter(({ orientation }) => orientation > 0);
+    const cavities = entries.filter(({ orientation }) => orientation < 0);
+    if (exteriors.length === 0)
+        return Object.freeze([]);
+    if (cavities.length === 0)
+        return Object.freeze(exteriors.map(({ shell }) => shell));
+    const pointAt = (mesh, index) => {
+        const offset = mesh.vertexIndices[index] * 3;
+        return [
+            mesh.coordinates[offset],
+            mesh.coordinates[offset + 1],
+            mesh.coordinates[offset + 2],
+        ];
+    };
+    const candidates = [...exteriors].sort((left, right) => Math.abs(left.volume) - Math.abs(right.volume));
+    const enclosingExterior = (entry) => {
+        return candidates.find((candidate) => {
+            spend();
+            if (candidate === entry ||
+                entry.bounds.min.some((value, axis) => value < candidate.bounds.min[axis]) ||
+                entry.bounds.max.some((value, axis) => value > candidate.bounds.max[axis]))
+                return false;
+            const childMesh = meshFor(entry.shell);
+            const point = pointAt(childMesh, childMesh.triangles[0]);
+            const mesh = meshFor(candidate.shell);
+            let angle = 0;
+            for (let triangle = 0; triangle < mesh.triangles.length; triangle += 3) {
+                spend();
+                angle += triangleSolidAngle(point, [
+                    pointAt(mesh, mesh.triangles[triangle]),
+                    pointAt(mesh, mesh.triangles[triangle + 1]),
+                    pointAt(mesh, mesh.triangles[triangle + 2]),
+                ]);
+            }
+            return Math.abs(angle) > 2 * Math.PI;
+        });
+    };
+    const module = scopedManifoldModule(scope);
+    const enclosedCavities = cavities.map((cavity) => ({
+        cavity,
+        parent: enclosingExterior(cavity),
+    }));
+    const orphanedCavity = enclosedCavities.some(({ parent }) => parent === undefined);
+    if (exteriors.length === 1 && entries.length === shells.length && !orphanedCavity)
+        return Object.freeze([solid]);
+    if (entries.length !== shells.length || orphanedCavity) {
+        // Selecting from the original would retain contact sheets inside a sealed cavity.
+        // Rebuild only this exceptional case from its material boundaries. The JS kernel's
+        // compose aliases union, so turn inward shells into positive native cutters instead.
+        const cutters = new Map(exteriors.map(({ shell }) => [shell, []]));
+        for (const { cavity, parent } of enclosedCavities) {
+            // An inward shell removes positive occupancy only inside an exterior. A lone
+            // inward contact remnant cannot define a bounded piece of material.
+            if (parent === undefined)
+                continue;
+            // Warp preserves winding while native mirror reverses it. The two exact X sign
+            // changes restore all Float64 coordinates without a mesh round-trip or tolerance.
+            spend(cavity.shell.numVert());
+            const reflected = ownScopedManifoldValue(scope, cavity.shell.warpBatch((vertices, count) => {
+                for (let vertex = 0; vertex < count; vertex++) {
+                    vertices[vertex * 3] = -vertices[vertex * 3];
+                }
+            }));
+            const cutter = ownScopedManifoldValue(scope, reflected.mirror([1, 0, 0]));
+            assertNativeSolidStatus(cutter, "components");
+            cutters.get(parent.shell).push(cutter);
+        }
+        return Object.freeze(exteriors.map(({ shell }) => {
+            const holes = cutters.get(shell);
+            const component = holes.length === 0
+                ? shell
+                : ownScopedManifoldValue(scope, module.Manifold.difference([shell, ...holes]));
+            assertNativeSolidStatus(component, "components");
+            return component;
+        }));
+    }
+    const children = new Map(exteriors.map(({ shell }) => [shell, []]));
+    for (const exterior of exteriors) {
+        const parent = enclosingExterior(exterior);
+        if (parent !== undefined)
+            children.get(parent.shell).push(exterior.shell);
+    }
+    // The JS kernel aliases compose to union, which fills independently supplied inward shells.
+    // Select from the original material instead, retaining its native precision and cavity winding.
+    return Object.freeze(exteriors.map(({ shell }) => {
+        const selected = ownScopedManifoldValue(scope, solid.intersect(shell));
+        const nested = children.get(shell);
+        const component = nested.length === 0
+            ? selected
+            : ownScopedManifoldValue(scope, module.Manifold.difference([selected, ...nested]));
+        assertNativeSolidStatus(component, "components");
+        return component;
+    }));
+}

package/dist/engine/native/regions.js

@@ -2,7 +2,8 @@ import { GeometryError } from "../../geometry/errors.js";
 import { contourContainsPoint, normalizeContour, normalizeRegion, signedContourArea, } from "../../geometry/regions.js";
 import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../../geometry/sampling-limits.js";
 import { assertScopedManifoldValue, ownScopedManifoldValue, scopedManifoldModule, } from "./context.js";
-const MAX_AGGREGATE_CONTOURS = 25_000;
+/** @internal One contour ceiling shared with authored input normalization preflights. */
+export const MAX_AGGREGATE_CONTOURS = 25_000;
 const assertRegionBounds = (regions, operation, limits = {}) => {
     const hasArrayShape = Array.isArray(regions);
     if (!hasArrayShape) {

package/dist/engine/native/threads.js

@@ -1,10 +1,10 @@
-import { buildHelicalThreadRidgeMesh, buildHelicalThreadSolidMesh, } from "../../geometry/mechanical/index.js";
+import { helicalThreadRidgeMesh, helicalThreadSolidMesh } from "../../geometry/mechanical/index.js";
 import { resolveCompensatedThreadSolidMesh, resolveThreadedNutSolid, } from "../../geometry/mechanical/thread-solids.js";
 import { triangleMeshToManifold } from "./adapter.js";
 export { preflightThreadedRodSolid, preflightInternalThreadCutterSolid, preflightThreadedNutSolid, } from "../../geometry/mechanical/thread-solids.js";
 /** Converts the runtime-neutral ridge mesh into a scope-owned Manifold solid. */
 export function threadRidgeSolid(module, options, scope) {
-    return triangleMeshToManifold(module, buildHelicalThreadRidgeMesh(options), scope);
+    return triangleMeshToManifold(module, helicalThreadRidgeMesh(options), scope);
 }
 const compensatedThreadSolid = (module, options, role, scope) => {
     const resolved = resolveCompensatedThreadSolidMesh(options, role);
@@ -12,7 +12,7 @@ const compensatedThreadSolid = (module, options, role, scope) => {
 };
 const compensatedThreadSolidFromResolved = (module, resolved, scope) => {
     const { axialExtension, meshOptions } = resolved;
-    const combined = triangleMeshToManifold(module, buildHelicalThreadSolidMesh(meshOptions), scope);
+    const combined = triangleMeshToManifold(module, helicalThreadSolidMesh(meshOptions), scope);
     return axialExtension === 0 ? combined : scope.own(combined.translate([0, 0, -axialExtension]));
 };
 /** Creates a compensated, scope-owned external threaded rod along +Z. */