@metamesh/modeling 0.18.0 → 0.20.0

package/dist/engine/operations/join.js

@@ -0,0 +1,521 @@
+import { GeometryError } from "../../geometry/errors.js";
+import { assertMeshAllocationWithinLimits } from "../../geometry/limits.js";
+import { clipJoinPolygon, createJoinPolygonIndex, expandJoinPolygon, inJoinPolygon, intersectJoinPolygons, joinArea, joinHeight, JoinWork, prepareJoinLayer, subtractJoinPolygon, } from "../../geometry/mesh/join-layers.js";
+import { validateSolidMesh } from "../../geometry/mesh/solid.js";
+import { planRegionOffsets } from "../../geometry/regions/offset.js";
+import { contourContainsPoint } from "../../geometry/regions/operations.js";
+import { assertSamplingCount } from "../../geometry/sampling/limits.js";
+import { resolveGeometryResolution } from "../../geometry/sampling/resolution.js";
+import { resolveGeometryTolerance } from "../../geometry/tolerance.js";
+import { anchor3, anchorFrame3 } from "../../geometry/transforms/anchors.js";
+import { nativeConstructionMesh } from "../native/construction-mesh.js";
+import { ownScopedManifoldValue } from "../native/context.js";
+import { observeNativeMesh } from "../native/mesh-observation.js";
+import { assertNativeSolidStatus } from "../native/status.js";
+import { nativeCollarProfile } from "./join-collar-profile.js";
+const fail = (message, phase) => {
+    throw new GeometryError("INVALID_ARGUMENT", message, { operation: "join", details: { phase } });
+};
+// Keep these kernels local to isolate V8's array-type feedback from other modeling operations.
+// Shared helpers see more array representations, which can slow hot loops even when inlined.
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+const profileContours = (profile) => profile.components.flatMap((component) => [
+    component.outer.points,
+    ...component.holes.map((hole) => hole.points),
+]);
+/**
+ * Builds one connection from authoritative native operands. Proves support coverage, material,
+ * and the constant-section collar before constructing the transition. Only the finished collar
+ * is transformed back and fused with the unchanged original operands.
+ */
+export function createJoinOperation(environment) {
+    return (base, feature, options) => {
+        const { module, scope } = environment;
+        const own = (value) => {
+            // Register first: failed native proofs and limit checks must dispose their intermediates too.
+            ownScopedManifoldValue(scope, value);
+            const vertices = value.numVert();
+            if (value instanceof module.Manifold) {
+                const triangles = value.numTri();
+                assertMeshAllocationWithinLimits(vertices, triangles, 12 * (vertices + triangles), "join", limits);
+            }
+            else
+                assertSamplingCount(vertices, "join", limits.maxProfilePoints);
+            return value;
+        };
+        if (typeof options !== "object" || options === null || Array.isArray(options))
+            fail("Join options are required.", "options");
+        if (Object.keys(options).some((key) => !["source", "transition", "resolution", "limits"].includes(key)))
+            fail("Unknown join option.", "options");
+        const transition = options.transition;
+        if (typeof transition !== "object" ||
+            transition === null ||
+            Array.isArray(transition) ||
+            Object.keys(transition).some((key) => !["kind", "width", "height"].includes(key)))
+            fail("Transition requires width and height and accepts an optional kind.", "options");
+        const kind = transition.kind === undefined ? "smooth" : transition.kind;
+        if (kind !== "smooth" && kind !== "straight")
+            fail('Join transition kind must be "smooth" or "straight".', "options");
+        const { width, height } = transition;
+        if (!Number.isFinite(width) || !Number.isFinite(height))
+            throw new GeometryError("NON_FINITE_VALUE", "Join width and height must be finite.", {
+                operation: "join",
+            });
+        if (width < 0 || height < 0 || (width === 0) !== (height === 0))
+            fail("Join width and height must both be positive or both zero.", "options");
+        const selected = environment.withResolutionDefaults(options);
+        const { limits } = selected;
+        const policy = resolveGeometryResolution(selected.resolution, limits);
+        const originalBase = environment.nativeSolid(base), originalFeature = environment.nativeSolid(feature);
+        assertNativeSolidStatus(originalBase, "join");
+        assertNativeSolidStatus(originalFeature, "join");
+        if (originalBase.isEmpty() || originalFeature.isEmpty())
+            throw new GeometryError("DEGENERATE_GEOMETRY", "Joining requires nonempty base and feature solids.", { operation: "join" });
+        const supplied = typeof options.source === "string"
+            ? environment.anchor(feature, options.source)
+            : options.source;
+        if (typeof supplied !== "object" || supplied === null)
+            fail("Join source must name a feature anchor or supply an Anchor3.", "source");
+        const sourceAnchor = anchor3({
+            position: supplied.position,
+            direction: supplied.direction,
+            up: supplied.up,
+        });
+        // The root points out of the feature; chart Z points into its unchanged straight collar.
+        const frame = anchorFrame3(anchor3({
+            position: sourceAnchor.position,
+            direction: [
+                -sourceAnchor.direction[0],
+                -sourceAnchor.direction[1],
+                -sourceAnchor.direction[2],
+            ],
+            up: sourceAnchor.up,
+        }));
+        const { xAxis: x, yAxis: y, zAxis: z, origin: o } = frame;
+        const forward = [
+            x[0],
+            x[1],
+            x[2],
+            0,
+            y[0],
+            y[1],
+            y[2],
+            0,
+            z[0],
+            z[1],
+            z[2],
+            0,
+            o[0],
+            o[1],
+            o[2],
+            1,
+        ];
+        const inverse = [
+            x[0],
+            y[0],
+            z[0],
+            0,
+            x[1],
+            y[1],
+            z[1],
+            0,
+            x[2],
+            y[2],
+            z[2],
+            0,
+            -dot(x, o),
+            -dot(y, o),
+            -dot(z, o),
+            1,
+        ];
+        // Local copies serve the proofs. Fuse the original operands later to avoid a frame round trip.
+        const support = own(originalBase.transform(inverse)), neck = own(originalFeature.transform(inverse));
+        const bounds = neck.boundingBox();
+        const raw = observeNativeMesh(scope, support, limits, "join");
+        const scale = Math.max(1, ...bounds.min.map(Math.abs), ...bounds.max.map(Math.abs), width, height);
+        // Final mesh capture is Float32. Reserve conversion/closure error before the sampling budget.
+        const epsilon = Math.max(resolveGeometryTolerance(scale).linear, support.tolerance(), neck.tolerance(), scale * 2 ** -22);
+        // Contact selection uses native precision; the larger Float32 meshing allowance must not bridge a gap.
+        const datumTolerance = Math.max(support.tolerance(), neck.tolerance(), scale * Number.EPSILON * 64);
+        let allowance = epsilon * 16;
+        if (allowance >= policy.maxChordError / 2)
+            fail("Join coordinate precision cannot resolve the requested physical error budget.", "precision");
+        const meshEpsilon = epsilon / 8;
+        // Slice just inside the root cap, removing cut seams only within the reserved numeric allowance.
+        const sourceSection = own(own(neck.slice(epsilon * 2)).simplify(epsilon / 8));
+        if (sourceSection.isEmpty())
+            fail("Source datum must cut a nonempty straight feature collar.", "collar");
+        const work = new JoinWork();
+        // Native Sections supply robust regional proofs; exact facet slicing retains wall coordinates
+        // for the corresponding construction instead of moving them through integer clipping.
+        const source = nativeCollarProfile(scope, neck, epsilon * 2, limits, work);
+        const closingInset = epsilon * 8;
+        const offset = planRegionOffsets(source, [-width, closingInset], "join", limits);
+        work.use(offset.workCount);
+        const crossSectionFromContours = (contours) => own(contours.length === 0
+            ? sourceSection.subtract(sourceSection)
+            : new module.CrossSection(contours.map((contour) => contour.map((p) => [p[0], p[1]])), "NonZero"));
+        const expandedProfile = offset.profileAt(-width);
+        const footprint = crossSectionFromContours(profileContours(expandedProfile));
+        const triangles = [];
+        const canonicalPlanes = [];
+        const chartTolerance = resolveGeometryTolerance(scale);
+        let chartArithmeticScale = scale;
+        const maxZ = bounds.max[2];
+        for (let i = 0; i < raw.triangles.length; i += 3) {
+            work.use();
+            const points = [0, 1, 2].map((j) => {
+                const index = raw.vertexIndices[raw.triangles[i + j]] * 3;
+                return [
+                    raw.coordinates[index],
+                    raw.coordinates[index + 1],
+                    raw.coordinates[index + 2],
+                ];
+            });
+            const a = points[0], b = points[1], c = points[2];
+            const ab = [b[0] - a[0], b[1] - a[1], b[2] - a[2]], ac = [c[0] - a[0], c[1] - a[1], c[2] - a[2]];
+            const normal = [
+                ab[1] * ac[2] - ab[2] * ac[1],
+                ab[2] * ac[0] - ab[0] * ac[2],
+                ab[0] * ac[1] - ab[1] * ac[0],
+            ];
+            const normalLength = Math.hypot(...normal);
+            if (normal[2] <= normalLength * 1e-10)
+                continue;
+            let plane = [
+                -normal[0] / normal[2],
+                -normal[1] / normal[2],
+                a[2] + (normal[0] / normal[2]) * a[0] + (normal[1] / normal[2]) * a[1],
+            ];
+            let polygon = points.map((p) => [p[0], p[1]]);
+            polygon = clipJoinPolygon(polygon, [plane[0], plane[1], plane[2] + datumTolerance]);
+            polygon = clipJoinPolygon(polygon, [-plane[0], -plane[1], maxZ - plane[2]]);
+            if (polygon.length < 3 || Math.abs(joinArea(polygon)) <= meshEpsilon ** 2)
+                continue;
+            const clipped = own(crossSectionFromContours([polygon]).intersect(footprint));
+            if (clipped.isEmpty())
+                continue;
+            for (const point of points)
+                chartArithmeticScale = Math.max(chartArithmeticScale, ...point.map(Math.abs));
+            // Float64 arithmetic can give coplanar tessellation triangles slightly different equations.
+            // Match dimensionless unit normals and actual height predictions, never encoded face IDs.
+            const priorPlane = canonicalPlanes.find((candidate) => {
+                work.use();
+                const length = Math.hypot(candidate[0], candidate[1], 1);
+                return (Math.hypot(-candidate[0] / length - normal[0] / normalLength, -candidate[1] / length - normal[1] / normalLength, 1 / length - normal[2] / normalLength) <= chartTolerance.angular &&
+                    points.every((point) => Math.abs(joinHeight(candidate, [point[0], point[1]]) - point[2]) <=
+                        chartTolerance.linear));
+            });
+            if (priorPlane === undefined)
+                canonicalPlanes.push(plane);
+            else
+                plane = priorPlane;
+            triangles.push({ polygon, plane });
+        }
+        // Convex components need one exact clip, not arbitrary triangulation seams.
+        // Inspect the actual clipping coordinates; holes and concavity retain their full partition.
+        const convexPartition = (contours) => {
+            const outer = contours[0];
+            const convex = contours.length === 1 &&
+                outer.length >= 3 &&
+                joinArea(outer) > 0 &&
+                outer.every((point, i) => {
+                    work.use();
+                    const previous = outer[(i + outer.length - 1) % outer.length], next = outer[(i + 1) % outer.length];
+                    return ((point[0] - previous[0]) * (next[1] - point[1]) -
+                        (point[1] - previous[1]) * (next[0] - point[0]) >=
+                        0);
+                });
+            if (convex)
+                return [outer];
+            const vertices = contours.flat();
+            return module
+                .triangulate(contours.map((contour) => contour.map((p) => [p[0], p[1]])), 0, false)
+                .map((ids) => ids.map((id) => vertices[id]));
+        };
+        const footprintCells = expandedProfile.components.flatMap((component) => convexPartition(crossSectionFromContours([
+            component.outer.points,
+            ...component.holes.map((hole) => hole.points),
+        ]).toPolygons()));
+        const usable = (polygon) => polygon.length >= 3 && Math.abs(joinArea(polygon)) > meshEpsilon ** 2;
+        const cells = [];
+        // Remove every nearer exit over its complete projected overlap, rather than probing a few rays.
+        for (let i = 0; i < triangles.length; i++) {
+            const current = triangles[i];
+            let visible = footprintCells
+                .map((polygon) => intersectJoinPolygons(current.polygon, polygon))
+                .filter(usable);
+            for (let j = 0; j < triangles.length && visible.length > 0; j++) {
+                if (i === j)
+                    continue;
+                work.use();
+                const other = triangles[j];
+                const overlap = intersectJoinPolygons(current.polygon, other.polygon);
+                if (!usable(overlap))
+                    continue;
+                const difference = [
+                    current.plane[0] - other.plane[0],
+                    current.plane[1] - other.plane[1],
+                    current.plane[2] - other.plane[2],
+                ];
+                const equal = overlap.every((point) => Math.abs(joinHeight(difference, point)) <= chartTolerance.linear);
+                if (equal && j > i)
+                    continue;
+                const nearer = equal ? other.polygon : clipJoinPolygon(other.polygon, difference);
+                if (usable(nearer))
+                    visible = visible
+                        .flatMap((polygon) => subtractJoinPolygon(polygon, nearer, work))
+                        .filter(usable);
+            }
+            for (const polygon of visible)
+                cells.push({ polygon, plane: current.plane });
+        }
+        if (cells.length === 0)
+            fail("The entire transition footprint needs a regular outward support patch after the source datum.", "support");
+        // Bound each affine proof cell's extension by epsilon/2 in Euclidean distance.
+        // The native union must cover the complete footprint; every extended part is
+        // included in the material witness below, so a real slit cannot be waived.
+        const proofSections = cells.map((cell) => {
+            work.use(cell.polygon.length);
+            const expanded = expandJoinPolygon(cell.polygon, epsilon / (2 * Math.SQRT2), work);
+            return crossSectionFromContours([expanded]);
+        });
+        const proofPoints = proofSections.reduce((count, section) => count + section.numVert(), 0);
+        assertMeshAllocationWithinLimits(proofPoints * 2, proofPoints * 4, proofPoints * 96, "join", limits);
+        const proofCoverage = own(module.CrossSection.union(proofSections));
+        if (!own(footprint.subtract(proofCoverage)).isEmpty())
+            fail("The entire transition footprint needs a regular outward support patch after the source datum.", "support");
+        let maximumSlope = 0, highestSupport = -Infinity;
+        for (const cell of cells) {
+            maximumSlope = Math.max(maximumSlope, Math.hypot(cell.plane[0], cell.plane[1]));
+            for (const point of cell.polygon) {
+                highestSupport = Math.max(highestSupport, joinHeight(cell.plane, point));
+            }
+        }
+        allowance *= 1 + maximumSlope;
+        if (allowance >= policy.maxChordError / 2)
+            fail("Support slope exhausts the physical extraction error budget.", "precision");
+        // Local bounds keep distant roots from broadening each other's support searches.
+        const cellIndex = createJoinPolygonIndex(cells.map((cell) => cell.polygon), work, limits);
+        for (const cell of cells)
+            for (const point of cell.polygon)
+                for (const index of cellIndex(point, meshEpsilon)) {
+                    const other = cells[index];
+                    work.use();
+                    if (cell !== other &&
+                        inJoinPolygon(point, other.polygon, meshEpsilon) &&
+                        Math.abs(joinHeight(cell.plane, point) - joinHeight(other.plane, point)) > allowance)
+                        fail("Support patch must be continuous; height jumps and branch changes are unsupported.", "support");
+                }
+        const collarTop = highestSupport + height + allowance;
+        if (collarTop > maxZ + epsilon)
+            fail("Feature needs a longer constant-section collar above the support patch.", "collar");
+        const proofDomain = own(module.Manifold.extrude(footprint, collarTop + allowance * 3).translate([
+            0,
+            0,
+            -allowance * 2,
+        ]));
+        const toNative = (mesh) => nativeConstructionMesh(scope, mesh, limits, "join");
+        const terrain = (top, bottom) => {
+            const pieces = cells.flatMap((cell, index) => {
+                const area = proofSections[index];
+                if (area.isEmpty())
+                    return [];
+                const guard = epsilon * (2 + Math.hypot(cell.plane[0], cell.plane[1]) / 2);
+                const slab = own(module.Manifold.extrude(area, 1));
+                const piece = own(slab.warpBatch((vertices, count) => {
+                    work.use(count);
+                    for (let i = 0; i < count; i++) {
+                        const k = i * 3, value = joinHeight(cell.plane, [vertices[k], vertices[k + 1]]);
+                        vertices[k + 2] = vertices[k + 2] > 0.5 ? top(value, guard) : bottom(value, guard);
+                    }
+                }));
+                assertNativeSolidStatus(piece, "join");
+                return [piece];
+            });
+            return own(own(module.Manifold.union(pieces)).intersect(proofDomain));
+        };
+        // Follow the curved chart. A flat witness would incorrectly exclude thin curved shells.
+        const witness = terrain((value, guard) => value - guard, (value, guard) => value - guard - epsilon * 6);
+        if (!own(witness.subtract(support)).isEmpty())
+            fail("Support material is missing or too thin beneath the complete curved footprint.", "support");
+        const overhead = terrain(() => collarTop + allowance, (value, guard) => value + guard);
+        if (!own(overhead.intersect(support)).isEmpty())
+            fail("Support reenters the connection band above the selected patch.", "support");
+        // Guard both directions over the full collar volume: matching two cross-sections is insufficient.
+        const domain = own(module.Manifold.extrude(footprint, collarTop - epsilon * 2).translate([0, 0, epsilon * 2]));
+        const innerSection = own(sourceSection.offset(-epsilon * 2, "Miter"));
+        const outerSection = own(sourceSection.offset(epsilon * 2, "Miter"));
+        const expected = own(module.Manifold.extrude(innerSection, collarTop - epsilon * 2).translate([0, 0, epsilon * 2]));
+        const outer = own(module.Manifold.extrude(outerSection, collarTop - epsilon * 2).translate([0, 0, epsilon * 2]));
+        const actual = own(neck.intersect(domain));
+        if (!own(expected.subtract(actual)).isEmpty() || !own(actual.subtract(outer)).isEmpty())
+            fail("Feature must have a straight constant-section collar throughout the complete connection band.", "collar");
+        if (width === 0)
+            return environment.wrapSolid(own(originalBase.add(originalFeature)));
+        const originalContours = profileContours(source), outsideContours = profileContours(expandedProfile);
+        // Close inside the real feature wall, proving this private numerical overlap adds no exposed shape.
+        const insideProfile = offset.profileAt(closingInset);
+        const insideContours = profileContours(insideProfile);
+        const closingSection = crossSectionFromContours(insideContours);
+        if (closingSection.isEmpty() || closingSection.numContour() !== sourceSection.numContour())
+            fail("Source boundaries cannot resolve the private closing allowance.", "precision");
+        const closingCore = own(module.Manifold.extrude(closingSection, collarTop));
+        if (!own(own(closingCore.subtract(neck)).subtract(support)).isEmpty())
+            fail("The private closing boundary cannot be contained in the supplied solids.", "precision");
+        const strips = [];
+        for (let contourIndex = 0; contourIndex < originalContours.length; contourIndex++) {
+            const original = originalContours[contourIndex], expanded = outsideContours[contourIndex];
+            for (let i = 0; i < original.length; i++) {
+                const next = (i + 1) % original.length, a = original[i], b = original[next];
+                const length = Math.hypot(b[0] - a[0], b[1] - a[1]);
+                if (length <= epsilon)
+                    fail("Source edge cannot resolve the connection precision.", "precision");
+                strips.push({
+                    polygon: [a, expanded[i], expanded[next], b],
+                    start: a,
+                    normal: [(b[1] - a[1]) / length, -(b[0] - a[0]) / length],
+                });
+            }
+        }
+        // A straight profile is planar on each support facet; only the cubic needs transverse rows.
+        const effectiveRise = height + epsilon * 2;
+        const curvature = 6 * Math.hypot(width * offset.magnification * (1 + maximumSlope), effectiveRise);
+        const tolerance = (policy.maxChordError - allowance) / 4;
+        const divisions = kind === "straight"
+            ? 1
+            : Math.max(2, Math.ceil(Math.sqrt(curvature / (8 * tolerance))), policy.maxSegmentLength === undefined
+                ? 0
+                : Math.ceil((3 *
+                    Math.hypot(width * offset.magnification * (1 + maximumSlope), effectiveRise)) /
+                    policy.maxSegmentLength));
+        if (divisions > limits.maxPathPoints)
+            throw new GeometryError("COMPLEXITY_LIMIT", "Join profile exceeds its station ceiling.", {
+                operation: "join",
+            });
+        const polygons = [];
+        const bottomGroups = [];
+        const planeGroups = new Map();
+        const supportPlanes = [];
+        const cellGroups = cells.map((cell) => {
+            const key = cell.plane.join(",");
+            let group = planeGroups.get(key);
+            if (group === undefined) {
+                group = planeGroups.size;
+                planeGroups.set(key, group);
+                supportPlanes.push(cell.plane);
+            }
+            return group;
+        });
+        const appendClippedCells = (polygon) => {
+            for (const [cellIndex, cell] of cells.entries()) {
+                work.use();
+                const piece = intersectJoinPolygons(polygon, cell.polygon);
+                if (piece.length >= 3 && Math.abs(joinArea(piece)) > meshEpsilon ** 2) {
+                    polygons.push(piece);
+                    bottomGroups.push(cellGroups[cellIndex]);
+                }
+            }
+        };
+        // Split at every chart crossing so the generated surface retains actual support facets and creases.
+        for (const strip of strips)
+            for (let row = 0; row < divisions; row++) {
+                const exponent = kind === "straight" ? 1 : 3;
+                const ra = width * (1 - row / divisions) ** exponent, rb = width * (1 - (row + 1) / divisions) ** exponent;
+                const projection = [
+                    strip.normal[0],
+                    strip.normal[1],
+                    -strip.normal[0] * strip.start[0] - strip.normal[1] * strip.start[1],
+                ];
+                const band = clipJoinPolygon(clipJoinPolygon(strip.polygon, [projection[0], projection[1], projection[2] - rb]), [-projection[0], -projection[1], ra - projection[2]]);
+                if (band.length < 3)
+                    continue;
+                appendClippedCells(band);
+            }
+        // Use the same corresponding boundaries and clipping arithmetic as the outside strips.
+        // Independent native offsets/intersections would round these shared mesh seams differently.
+        for (let contourIndex = 0; contourIndex < originalContours.length; contourIndex++) {
+            const original = originalContours[contourIndex], inside = insideContours[contourIndex];
+            for (let i = 0; i < original.length; i++) {
+                const next = (i + 1) % original.length;
+                const ring = [original[i], original[next], inside[next], inside[i]];
+                appendClippedCells(ring);
+            }
+        }
+        // Fill the already-proven feature interior down to the same support witness. An annular-only
+        // collar can enclose a numerical contact sheet when two independently transformed caps meet.
+        const coreCells = insideProfile.components.flatMap((component) => convexPartition([component.outer.points, ...component.holes.map((hole) => hole.points)]));
+        for (const coreCell of coreCells)
+            appendClippedCells(coreCell);
+        const stripIndex = createJoinPolygonIndex(strips.map((strip) => strip.polygon), work, limits);
+        const rise = (p) => {
+            for (const index of stripIndex(p, epsilon)) {
+                const strip = strips[index];
+                work.use();
+                if (inJoinPolygon(p, strip.polygon, epsilon)) {
+                    const r = Math.max(0, Math.min(width, (p[0] - strip.start[0]) * strip.normal[0] + (p[1] - strip.start[1]) * strip.normal[1]));
+                    return height * (kind === "straight" ? 1 - r / width : (1 - Math.cbrt(r / width)) ** 3);
+                }
+            }
+            if (source.components.some((component) => contourContainsPoint(component.outer.points, p) &&
+                !component.holes.some((hole) => contourContainsPoint(hole.points, p))))
+                return height;
+            return fail("Transition cell escaped its source offset strip.", "transition");
+        };
+        const layerOptions = {
+            bottomGroups,
+            supportPlanes,
+            triangulate: (contours) => module.triangulate(contours.map((contour) => contour.map((p) => [p[0], p[1]])), 0, false),
+        };
+        const layer = prepareJoinLayer(polygons, meshEpsilon, limits, work, layerOptions);
+        // Prepared nodes retain their incident support planes, avoiding a second spatial guess at creases.
+        const chartHeight = (value) => value ?? fail("Join layer has no supporting chart plane.", "support");
+        // A guarded witness can miss a void immediately under the selected face. Prove the complete
+        // numerical foot before adding material, retaining its exact boundary and affine support faces.
+        const footMesh = layer.supportBand(epsilon * 8);
+        validateSolidMesh(footMesh);
+        const footNative = toNative(footMesh);
+        const missingFoot = own(own(footNative.subtract(support)).subtract(neck));
+        if (!missingFoot.isEmpty()) {
+            // Native subtraction can retain zero-thickness contact sheets. Bound each component at
+            // Float64 roundoff, never by the larger construction allowance or another component's area.
+            const missingComponents = missingFoot.decompose().map(own);
+            if (missingComponents.length === 0)
+                fail("Numerical connection containment could not be established.", "support");
+            for (const missing of missingComponents) {
+                work.use();
+                const bounds = missing.boundingBox();
+                if (![...bounds.min, ...bounds.max].every(Number.isFinite))
+                    fail("Numerical connection containment could not be established.", "support");
+                const arithmetic = Number.EPSILON *
+                    64 *
+                    Math.max(chartArithmeticScale, ...bounds.min.map(Math.abs), ...bounds.max.map(Math.abs));
+                const roundoff = Math.min(arithmetic, support.tolerance(), neck.tolerance());
+                // Measure around the component, avoiding cancellation against global chart coordinates.
+                const center = bounds.min.map((value, axis) => value / 2 + bounds.max[axis] / 2);
+                const centered = own(missing.warpBatch((positions, count) => {
+                    work.use(count);
+                    for (let i = 0; i < positions.length; i++)
+                        positions[i] = positions[i] - center[i % 3];
+                }));
+                const volume = Math.abs(centered.volume());
+                const area = missing.surfaceArea();
+                if (![roundoff, volume, area].every(Number.isFinite) || roundoff < 0 || area < 0)
+                    fail("Numerical connection containment could not be established.", "support");
+                if (volume > area * roundoff)
+                    fail("Support material must fill the complete numerical connection foot.", "support");
+            }
+        }
+        const collarMesh = layer.build(
+        // Begin inside the proven support witness, fading the extraction allowance to zero at the wall.
+        // This avoids nearly coincident foot slivers when the native Boolean meets its Float32 chart.
+        (p, value) => chartHeight(value) + rise(p) * (effectiveRise / height) - epsilon * 2, (_p, value) => chartHeight(value) - epsilon * 8, policy.maxSegmentLength);
+        validateSolidMesh(collarMesh);
+        const collar = toNative(collarMesh);
+        const worldCollar = own(collar.transform(forward));
+        // Construction adds a collar; neither supplied operand is trimmed, moved, or reconstructed.
+        const combined = own(module.Manifold.union([originalBase, originalFeature, worldCollar]));
+        assertNativeSolidStatus(combined, "join");
+        return environment.wrapSolid(combined);
+    };
+}

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

@@ -1,15 +1,16 @@
 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";
+import { assertPrimitiveOptions } from "../../geometry/primitives/resolvers.js";
+import { assertSamplingCount } from "../../geometry/sampling/limits.js";
+import { frameTransform3 } from "../../geometry/transforms/affine3.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 dimensions = resolveKnuckleHinge(options, resolved);
+        assertSamplingCount(dimensions.segments * dimensions.spec.knuckleCount * 2, "knuckleHinge", resolved.limits.maxVertices);
         const invalid = (message) => {
             throw new GeometryError("INVALID_ARGUMENT", message, { operation: "knuckleHinge" });
         };
@@ -18,8 +19,8 @@ export function createKnuckleHingeOperation(environment, operations) {
             const chamfer = half.chamfer ?? 0;
             if (!Number.isFinite(chamfer) ||
                 chamfer < 0 ||
-                2 * chamfer >= d.knuckleLength ||
-                chamfer >= d.minimumBarrelWall)
+                2 * chamfer >= dimensions.knuckleLength ||
+                chamfer >= dimensions.minimumBarrelWall)
                 invalid("chamfer must be nonnegative and leave a positive axial band and faceted barrel wall.");
             const web = half.web;
             if (web !== undefined) {
@@ -34,9 +35,9 @@ export function createKnuckleHingeOperation(environment, operations) {
                     !Number.isFinite(web.zMin + web.thickness))
                     invalid("Web dimensions must be finite, with positive reach and thickness.");
                 if (2 * chamfer >= web.thickness ||
-                    2 * Math.SQRT2 * chamfer >= Math.min(d.knuckleLength, web.reach))
+                    2 * Math.SQRT2 * chamfer >= Math.min(dimensions.knuckleLength, web.reach))
                     invalid("chamfer must leave a positive web band and noncollapsed end contours.");
-                const innerRadius = d.barrelRadius * Math.cos(Math.PI / d.segments);
+                const innerRadius = dimensions.barrelRadius * Math.cos(Math.PI / dimensions.segments);
                 if (web.zMin >= innerRadius || web.zMin + web.thickness <= -innerRadius)
                     invalid("A web must overlap the interior of its barrel.");
             }
@@ -49,7 +50,7 @@ export function createKnuckleHingeOperation(environment, operations) {
             radius,
             height: length,
             center: false,
-            segments: d.segments,
+            segments: dimensions.segments,
             sizing: bore ? "face" : "vertex",
             ...(chamfer === 0
                 ? {}
@@ -69,7 +70,7 @@ export function createKnuckleHingeOperation(environment, operations) {
                 // Parallel offsets finish the exposed tip; the two root corners stay square.
                 const corner = { kind: "chamfer", distance: chamfer + (Math.SQRT2 - 2) * inset };
                 const profile = operations.rectangle({
-                    size: [d.knuckleLength - 2 * inset, web.reach - inset],
+                    size: [dimensions.knuckleLength - 2 * inset, web.reach - inset],
                     center: false,
                     treatment: [corner, corner, { kind: "square" }, { kind: "square" }],
                 });
@@ -78,10 +79,10 @@ export function createKnuckleHingeOperation(environment, operations) {
                     web.direction === "positive-y" ? 1 : -1,
                 ]);
             };
-            for (const interval of d.knuckles) {
+            for (const interval of dimensions.knuckles) {
                 if (interval.side !== side)
                     continue;
-                features.push(atBase(axial(d.barrelRadius, interval.start, interval.length, false, chamfer)));
+                features.push(atBase(axial(dimensions.barrelRadius, interval.start, interval.length, false, chamfer)));
                 if (web !== undefined) {
                     features.push(chamfer === 0
                         ? operations.translate(operations.box({
@@ -99,30 +100,34 @@ export function createKnuckleHingeOperation(environment, operations) {
                             [chamfer, web.thickness],
                         ].map(([inset, z]) => ({
                             profile: webProfile(web, inset),
-                            frame: {
+                            transform: frameTransform3({
                                 origin: [interval.start, 0, z],
                                 xAxis: [1, 0, 0],
                                 yAxis: [0, 1, 0],
                                 zAxis: [0, 0, 1],
-                            },
+                            }),
                         }))));
                 }
             }
-            if (side === "a" && d.pin !== null)
-                features.push(atBase(axial(d.pinRadius, d.pin.start, d.pin.length)));
+            if (side === "a" && dimensions.pin !== null)
+                features.push(atBase(axial(dimensions.pinRadius, dimensions.pin.start, dimensions.pin.length)));
             // Match the kernel cylinders to the same mesh precision as the explicit web stations.
             const solid = operations.union(features.map((feature) => chamfer === 0 || web === undefined
                 ? feature
                 : operations.solidFromMesh(environment.analyzedMeshFor(feature).mesh)));
             // Overtravel is numerical cutter extent, independent of the physical radial/axial allowances.
-            const overtravel = Math.min(d.knuckleLength, d.barrelRadius) * 0.01;
-            const result = side === "a" && d.pin !== null
+            const overtravel = Math.min(dimensions.knuckleLength, dimensions.barrelRadius) * 0.01;
+            const result = side === "a" && dimensions.pin !== null
                 ? solid
                 : operations.subtract(solid, [
-                    atBase(axial(d.boreRadius, -d.spec.length / 2 - overtravel, d.spec.length + 2 * overtravel, true)),
+                    atBase(axial(dimensions.boreRadius, -dimensions.spec.length / 2 - overtravel, dimensions.spec.length + 2 * overtravel, true)),
                 ]);
             return operations.translate(result, [0, 0, baseZ]);
         };
-        return Object.freeze({ halfA: buildHalf("a", a), halfB: buildHalf("b", b), axis: d.axis });
+        return Object.freeze({
+            halfA: buildHalf("a", a),
+            halfB: buildHalf("b", b),
+            axis: dimensions.axis,
+        });
     };
 }