@metamesh/modeling 0.19.0 → 0.20.0

package/dist/engine/operations/primitives/construction.js

@@ -1,18 +1,20 @@
-import { resolveCircularSampling } from "../../../geometry/circular-sampling.js";
-import { resolveCylinderRadii } from "../../../geometry/cylinder.js";
+import { resolveModelingLimits } from "../../../geometry/limits.js";
 import { vector2Data } from "../../../geometry/math/vector-value.js";
-import { resolveModelingLimits } from "../../../geometry/model-limits.js";
-import { assertPrimitiveOptions } from "../../../geometry/primitive-resolvers.js";
+import { resolveCylinderRadii } from "../../../geometry/primitives/cylinder.js";
+import { edgeTreatmentSetbacks } from "../../../geometry/primitives/edges.js";
+import { assertPrimitiveOptions, resolveTubePrimitive, } from "../../../geometry/primitives/resolvers.js";
+import { circleContour } from "../../../geometry/profiles/primitives/circle.js";
 import { ellipseContour } from "../../../geometry/profiles/primitives/ellipse.js";
 import { rectangleContour, resolveRectangle, } from "../../../geometry/profiles/primitives/rectangle.js";
 import { regularPolygonContour } from "../../../geometry/profiles/primitives/regular-polygon.js";
 import { starContour } from "../../../geometry/profiles/primitives/star.js";
 import { requireProfileVertexCount } from "../../../geometry/profiles/validation.js";
+import { resolveCircularSampling } from "../../../geometry/sampling/circular.js";
 import * as kernel from "../../native/index.js";
 import { boxAnchors, cylinderAnchors, originAnchor, planarAnchors, sphereAnchors, torusAnchors, tubeAnchors, } from "./anchors.js";
 import { ellipticalSectionProfile, polygonSectionProfile, rectangleSectionProfile, } from "./profiles.js";
 /** Internal host-bound primitive operations. */
-export function createPrimitiveOperations(environment, transforms, sections) {
+export function createPrimitiveOperations(environment, transforms, sections, construction) {
     const { module, scope, assertActive, throwGeometryError, ownSection, requirePositiveNumber, validateCoordinates, withResolutionDefaults, resolveCircularSegments, } = environment;
     const { placedSolid, placedSection } = transforms;
     const fromContours = (contours) => sections.polygon({ contours });
@@ -72,7 +74,31 @@ export function createPrimitiveOperations(environment, transforms, sections) {
         },
         tube: (value) => {
             assertActive();
-            return placedSolid(value, () => kernel.tube(scope, withResolutionDefaults(value)), () => tubeAnchors(value));
+            assertPrimitiveOptions(value, "tube");
+            const resolved = withResolutionDefaults(value);
+            const ends = value.ends;
+            if (ends !== undefined) {
+                assertPrimitiveOptions(ends, "tube");
+                const setbacks = [ends.bottom, ends.top].map((treatment) => treatment === undefined
+                    ? [0, 0]
+                    : edgeTreatmentSetbacks(treatment, "tube", Math.PI / 2, resolved.limits));
+                if (setbacks.some((pair) => pair.some((distance) => distance > 0))) {
+                    const { innerVertexRadius, outerVertexRadius, segments } = resolveTubePrimitive(resolved);
+                    const contour = (radius) => circleContour({ radius, segments, limits: resolved.limits });
+                    const section = sections.polygon({
+                        outer: contour(outerVertexRadius),
+                        holes: [contour(innerVertexRadius)],
+                    });
+                    return placedSolid(value, () => environment.nativeSolid(construction.extrude(section, {
+                        height: value.height,
+                        center: value.center ?? true,
+                        ends,
+                        resolution: resolved.resolution,
+                        limits: resolved.limits,
+                    })), () => tubeAnchors(value));
+                }
+            }
+            return placedSolid(value, () => kernel.tube(scope, resolved), () => tubeAnchors(value));
         },
         sphere: (value) => {
             assertActive();
@@ -148,15 +174,15 @@ export function createPrimitiveOperations(environment, transforms, sections) {
             return environment.rememberPrimitiveProfile(section, ellipticalSectionProfile(radii, value, resolved.resolution, resolved.limits));
         }),
         regularPolygon: (value) => placedSection(value, () => {
-            const resolved = withResolutionDefaults(value), loop = regularPolygonContour(resolved);
-            const section = environment.rememberAnchors(fromContours([loop]), originAnchor());
-            return environment.rememberPrimitiveProfile(section, polygonSectionProfile(`polygon-${value.sides}`, loop, resolved.resolution, resolved.limits));
+            const resolved = withResolutionDefaults(value), contour = regularPolygonContour(resolved);
+            const section = environment.rememberAnchors(fromContours([contour]), originAnchor());
+            return environment.rememberPrimitiveProfile(section, polygonSectionProfile(`polygon-${value.sides}`, contour, resolved.resolution, resolved.limits));
         }),
         star: (value) => placedSection(value, () => {
             const resolved = withResolutionDefaults(value);
-            const loop = starContour({ ...value, limits: resolved.limits });
-            const section = environment.rememberAnchors(fromContours([loop]), originAnchor());
-            return environment.rememberPrimitiveProfile(section, polygonSectionProfile(`star-${value.points}`, loop, resolved.resolution, resolved.limits));
+            const contour = starContour({ ...value, limits: resolved.limits });
+            const section = environment.rememberAnchors(fromContours([contour]), originAnchor());
+            return environment.rememberPrimitiveProfile(section, polygonSectionProfile(`star-${value.points}`, contour, resolved.resolution, resolved.limits));
         }),
     };
     return operations;

package/dist/engine/operations/primitives/correspondence.js

@@ -1,7 +1,7 @@
 import { GeometryError } from "../../../geometry/errors.js";
-import { matchProfiles, } from "../../../geometry/profiles/match-profiles.js";
+import { matchProfiles, } from "../../../geometry/profiles/matching.js";
 import { createProfileSpanSampler } from "../../../geometry/profiles/span-sampling.js";
-import { assertSamplingCount, } from "../../../geometry/sampling-limits.js";
+import { assertSamplingCount, } from "../../../geometry/sampling/limits.js";
 /** Primitive exact counts describe physical facets; identified user Profile counts describe analytic grids. */
 export function samplePrimitiveFamily(sources, profiles, resolution, limits) {
     const matched = matchProfiles(profiles, { resolution, limits });

package/dist/engine/operations/primitives/profile-mesh.js

@@ -1,47 +1,25 @@
 import { GeometryError } from "../../../geometry/errors.js";
-import { loftFrame } from "../../../geometry/loft/loft-options.js";
-import { assertMeshAllocationWithinLimits } from "../../../geometry/model-limits.js";
-import { writeMeshVertex } from "../../../geometry/numeric.js";
-import { normalizeRegion, signedContourArea } from "../../../geometry/regions.js";
-import { assertSamplingCount } from "../../../geometry/sampling-limits.js";
-import { resolveSweepScales } from "../../../geometry/sweeps/options.js";
-import { computeSweepFrames, validateSweepOptions } from "../../../geometry/sweeps/orientation.js";
-import { planSweepStations, refineSweepStations } from "../../../geometry/sweeps/stations.js";
-import { normalizeSweepPath } from "../../../geometry/sweeps/validation.js";
-import { resolveGeometryTolerance } from "../../../geometry/tolerance.js";
-import { frameTransform3 } from "../../../geometry/transform3.js";
+import { assertMeshAllocationWithinLimits } from "../../../geometry/limits.js";
+import { loftProfilePointCount } from "../../../geometry/loft/geometry.js";
+import { loftTransform } from "../../../geometry/loft/options.js";
+import { analyzeTriangleMesh } from "../../../geometry/mesh/operations.js";
+import { reverseOwnedTriangleWinding } from "../../../geometry/mesh/winding.js";
+import { writeMeshVertex } from "../../../geometry/mesh/write-vertex.js";
+import { normalizeRegion, signedContourArea } from "../../../geometry/regions/operations.js";
+import { assertSamplingCount } from "../../../geometry/sampling/limits.js";
+import { validateSweepOptions } from "../../../geometry/sweep/orientation.js";
+import { sweepSeamOffset } from "../../../geometry/sweep/seam.js";
+import { prepareSweepStations, resolveSweepScales } from "../../../geometry/sweep/stations.js";
+import { normalizeSweepPath } from "../../../geometry/sweep/validation.js";
+import { frameTransform3 } from "../../../geometry/transforms/affine3.js";
 const fail = (message) => {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation: "loft" });
 };
 const isArray = (value) => Array.isArray(value);
 const contourList = (profile) => profile.components.flatMap((component) => [component.outer, ...component.holes]);
 function profileMeshAllocation(first, stationCount, limits, closed) {
-    if (!isArray(first.components) || first.components.length === 0 || first.components.length > 1000)
-        fail("Matched profiles require one through 1000 identified components.");
-    const validIdentity = (id) => typeof id === "string" && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(id) && id.length <= 64;
-    const componentIds = new Set();
-    for (const component of first.components) {
-        if (!validIdentity(component.id) || componentIds.has(component.id) || !isArray(component.holes))
-            fail("Matched component identities must be canonical and unique.");
-        componentIds.add(component.id);
-        const contourIds = new Set();
-        for (const contour of [component.outer, ...component.holes]) {
-            if (!validIdentity(contour.id) || contourIds.has(contour.id))
-                fail("Matched contour identities must be canonical and unique within a component.");
-            contourIds.add(contour.id);
-        }
-    }
+    const logicalCount = loftProfilePointCount(first);
     const firstContours = contourList(first);
-    let logicalCount = 0;
-    for (const contour of firstContours) {
-        if (!isArray(contour.points) ||
-            !isArray(contour.spans) ||
-            contour.spans.some((span) => !validIdentity(span)) ||
-            contour.points.length !== contour.spans.length ||
-            contour.points.length < 3)
-            fail("Matched contours require at least three logical points and paired span identities.");
-        logicalCount += contour.points.length;
-    }
     const maxVertices = logicalCount * stationCount;
     const capTriangles = 2 * (logicalCount + firstContours.length * 2);
     const maximumTriangles = (closed ? stationCount : stationCount - 1) * logicalCount * 2 + (closed ? 0 : capTriangles);
@@ -49,8 +27,12 @@ function profileMeshAllocation(first, stationCount, limits, closed) {
     assertMeshAllocationWithinLimits(maxVertices, maximumTriangles, 12 * (maxVertices + maximumTriangles), "loft", limits);
     return { firstContours, maxVertices, maximumTriangles };
 }
-/** Internal native hole-cap triangulation over copied, explicit matched logical slots. */
-export function buildProfileLoftMesh(module, stations, limits, closed = false, seamProfileOffset = 0, positionFor) {
+/**
+ * Realizes matched logical slots as bounded Float32 geometry. Coincident neighboring slots share
+ * physical vertices without losing correspondence; side faces follow those logical slots, while
+ * caps use the deduplicated contours and native hole-aware triangulation.
+ */
+export function buildProfileLoftMesh(module, stations, limits, closed = false, seamProfileOffsets = [], positionFor) {
     if (!isArray(stations) || stations.length < (closed ? 3 : 2))
         fail("Profile lofts require a bounded station array with two stations, or three for a closed path.");
     assertSamplingCount(stations.length, "loft", limits.maxPathPoints);
@@ -59,6 +41,7 @@ export function buildProfileLoftMesh(module, stations, limits, closed = false, s
     const positions = new Float32Array(maxVertices * 3);
     const indices = new Uint32Array(maximumTriangles * 3);
     let vertexCount = 0, cursor = 0;
+    // Capture and validate every station before connecting any of their physical vertices.
     const physicalStations = stations.map((station, stationIndex) => {
         const profile = station.profile;
         if (!isArray(profile.components) || profile.components.length !== first.components.length)
@@ -70,7 +53,7 @@ export function buildProfileLoftMesh(module, stations, limits, closed = false, s
                 component.holes.length !== expected.holes.length)
                 fail("Matched component identities and hole counts must preserve their order.");
         });
-        const transform = frameTransform3(loftFrame(station));
+        const transform = loftTransform(station);
         const physical = contourList(profile).map((contour, contourIndex) => {
             const expected = firstContours[contourIndex];
             if (contour.id !== expected.id ||
@@ -157,13 +140,14 @@ export function buildProfileLoftMesh(module, stations, limits, closed = false, s
         indices[cursor++] = b;
         indices[cursor++] = c;
     };
+    // Collapsed corner slots retain their logical partners even when physical vertex counts differ.
     for (let station = 0; station < (closed ? stations.length : stations.length - 1); station += 1) {
         const lower = physicalStations[station], upper = physicalStations[(station + 1) % stations.length];
         lower.forEach((contour, contourIndex) => {
             const paired = upper[contourIndex];
             for (let index = 0; index < contour.slots.length; index += 1) {
                 const next = (index + 1) % contour.slots.length;
-                const advance = signedContourArea(paired.points) < 0 ? -seamProfileOffset : seamProfileOffset;
+                const advance = seamProfileOffsets[contourIndex] ?? 0;
                 const offset = closed && station === stations.length - 1
                     ? ((advance % paired.slots.length) + paired.slots.length) % paired.slots.length
                     : 0;
@@ -195,52 +179,29 @@ export function buildProfileLoftMesh(module, stations, limits, closed = false, s
             }
         }
     }
-    return { positions: positions.slice(0, vertexCount * 3), indices: indices.slice(0, cursor) };
+    const mesh = {
+        positions: positions.slice(0, vertexCount * 3),
+        indices: indices.slice(0, cursor),
+    };
+    if (analyzeTriangleMesh(mesh).signedVolume < 0)
+        reverseOwnedTriangleWinding(mesh.indices);
+    return mesh;
 }
 /** Internal hollow sweep using explicit matched contours and transported right-handed frames. */
 export function buildProfileSweepMesh(module, profile, inputPath, options, limits) {
     const closed = options.closed ?? false;
     validateSweepOptions(options);
-    let path = normalizeSweepPath(inputPath, closed, "sweep", limits);
+    const normalizedPath = normalizeSweepPath(inputPath, closed, "sweep", limits);
     assertSamplingCount(contourList(profile).reduce((count, contour) => count + contour.points.length, 0), "sweep", limits.maxSweepProfilePoints);
-    profileMeshAllocation(profile, path.length, limits, closed);
-    let scales = resolveSweepScales(options.scale, path.length);
+    profileMeshAllocation(profile, normalizedPath.length, limits, closed);
+    const originalScales = resolveSweepScales(options.scale, normalizedPath, closed);
     const twist = options.twist ?? 0;
     if (!Number.isFinite(twist))
         fail("Sweep twist must be finite.");
-    const seamProfileOffset = options.seamProfileOffset ?? 0;
-    if (!Number.isSafeInteger(seamProfileOffset) || (!closed && seamProfileOffset !== 0))
-        fail("A finite integer seamProfileOffset requires a closed path.");
-    if (closed) {
-        const [scaleX, scaleY] = scales[0];
-        const angle = (twist * Math.PI) / 180, cosine = Math.cos(angle), sine = Math.sin(angle);
-        for (const contour of contourList(profile)) {
-            const extent = contour.points.reduce((maximum, [x, y]) => Math.max(maximum, Math.abs(x * scaleX), Math.abs(y * scaleY)), 1);
-            const tolerance = resolveGeometryTolerance(extent).linear;
-            const advance = signedContourArea(contour.points) < 0 ? -seamProfileOffset : seamProfileOffset;
-            const offset = ((advance % contour.points.length) + contour.points.length) % contour.points.length;
-            for (let index = 0; index < contour.points.length; index++) {
-                const [x, y] = contour.points[index], target = contour.points[(index + offset) % contour.points.length];
-                if (Math.hypot(x * scaleX * cosine - y * scaleY * sine - target[0] * scaleX, x * scaleX * sine + y * scaleY * cosine - target[1] * scaleY) > tolerance)
-                    fail("Sweep twist must match the explicit seam offset on every component and contour.");
-            }
-        }
-    }
-    if (twist !== 0) {
-        const plan = planSweepStations(contourList(profile).map((contour) => contour.points), path, scales, options);
-        profileMeshAllocation(profile, plan.stationCount, limits, closed);
-    }
-    let frames = computeSweepFrames(path, options);
-    let twists;
-    if (twist !== 0) {
-        const plan = planSweepStations(contourList(profile).map((contour) => contour.points), path, scales, options, frames);
-        profileMeshAllocation(profile, plan.stationCount, limits, closed);
-        const refined = refineSweepStations(path, scales, frames, options, plan);
-        path = refined.path;
-        scales = refined.scales;
-        frames = refined.frames;
-        twists = refined.twists;
-    }
+    const seamProfileOffsets = closed
+        ? contourList(profile).map((contour) => sweepSeamOffset(contour.points, originalScales[0], twist))
+        : [];
+    const { path, scales, frames, twists } = prepareSweepStations(contourList(profile).map((contour) => contour.points), normalizedPath, originalScales, options, (count) => profileMeshAllocation(profile, count, limits, closed));
     const stations = path.map((origin, index) => {
         const frame = frames[index];
         const angle = twists?.[index] ??
@@ -267,13 +228,13 @@ export function buildProfileSweepMesh(module, profile, inputPath, options, limit
                     };
                 }),
             },
-            frame: {
+            transform: frameTransform3({
                 origin,
                 xAxis: combine(frame.normal, frame.binormal, cosine, sine),
                 yAxis: combine(frame.normal, frame.binormal, -sine, cosine),
                 zAxis: frame.tangent,
-            },
+            }),
         };
     });
-    return buildProfileLoftMesh(module, stations, limits, closed, seamProfileOffset);
+    return buildProfileLoftMesh(module, stations, limits, closed, seamProfileOffsets);
 }

package/dist/engine/operations/primitives/profiles.js

@@ -1,9 +1,9 @@
 import { planarCubicControl } from "../../../geometry/curves/evaluation.js";
 import { resolveLineSegmentCount, resolveUniformCubicSegments, } from "../../../geometry/curves/sampling.js";
 import { GeometryError } from "../../../geometry/errors.js";
-import {} from "../../../geometry/profiles/match-profiles.js";
+import {} from "../../../geometry/profiles/matching.js";
 import { rectangleProfile, resolveRectangle, } from "../../../geometry/profiles/primitives/rectangle.js";
-import { resolveArcSegments, resolveGeometryResolution, } from "../../../geometry/resolution.js";
+import { resolveArcSegments, resolveGeometryResolution, } from "../../../geometry/sampling/resolution.js";
 import { samplePrimitiveFamily } from "./correspondence.js";
 const identity = [1, 0, 0, 0, 1, 0, 0, 0, 1];
 const cornerIds = ["top-right", "top-left", "bottom-left", "bottom-right"];
@@ -61,7 +61,7 @@ export function ellipticalSectionProfile(radii, options, resolution, limits, fac
     };
 }
 /** Captures the explicitly indexed edges of a polygon or star; its topology is its family key. */
-export function polygonSectionProfile(family, loop, resolution, limits) {
+export function polygonSectionProfile(family, contour, resolution, limits) {
     return {
         family,
         profile: {
@@ -71,11 +71,11 @@ export function polygonSectionProfile(family, loop, resolution, limits) {
                     holes: [],
                     outer: {
                         id: "outline",
-                        spans: loop.map((start, index) => ({
+                        spans: contour.map((start, index) => ({
                             id: `edge-${index}`,
                             kind: "line",
                             start,
-                            end: loop[(index + 1) % loop.length],
+                            end: contour[(index + 1) % contour.length],
                         })),
                     },
                 },

package/dist/engine/operations/sections.js

@@ -1,9 +1,9 @@
-import { path2InputData, path2InputPointCount, } from "../../geometry/paths/path-value.js";
-import { assertSamplingCount } from "../../geometry/sampling-limits.js";
-import { strokePathContours } from "../../geometry/stroke-path.js";
+import { path2InputData, path2InputPointCount, } from "../../geometry/paths/value.js";
+import { strokePathContours } from "../../geometry/regions/stroke.js";
+import { assertSamplingCount } from "../../geometry/sampling/limits.js";
 import { preflightSvgRegion } from "../../geometry/svg/import.js";
-import { parseSvgPath } from "../../geometry/svg/index.js";
-import { sampleTextContours } from "../../geometry/text-contours.js";
+import { parseSvgPath } from "../../geometry/svg/parser.js";
+import { sampleTextContours } from "../../geometry/text/contours.js";
 import * as kernel from "../native/index.js";
 import { MAX_AGGREGATE_CONTOURS } from "../native/regions.js";
 /** Internal host-bound section operations. */
@@ -91,10 +91,10 @@ export function createSectionOperations(environment, transforms) {
         },
         toRegionData: (handle) => {
             const profile = environment.sectionProfileFor(handle);
-            const copiedLoop = (points) => Object.freeze(points.map(([x, y]) => Object.freeze([x, y])));
+            const copyContour = (points) => Object.freeze(points.map(([x, y]) => Object.freeze([x, y])));
             return Object.freeze(profile.components.map((component) => Object.freeze({
-                outer: copiedLoop(component.outer.points),
-                holes: Object.freeze(component.holes.map((contour) => copiedLoop(contour.points))),
+                outer: copyContour(component.outer.points),
+                holes: Object.freeze(component.holes.map((contour) => copyContour(contour.points))),
             })));
         },
         offset: (handle, distance, value = {}) => {

package/dist/engine/operations/transforms.js

@@ -1,33 +1,17 @@
-import { attachmentTransform3 } from "../../geometry/anchors.js";
+import { isGeometryError } from "../../geometry/errors.js";
 import { vector2Data, vector3Data, } from "../../geometry/math/vector-value.js";
-import { assertPrimitiveOptions } from "../../geometry/primitive-resolvers.js";
-import { readTransformMatrix } from "../../geometry/transform-matrix.js";
-import { transform2, transform3, } from "../../geometry/transform-value.js";
-import { eulerTransform3, scaleTransform3, translationTransform3, validateTransform3, } from "../../geometry/transform3.js";
+import { assertPrimitiveOptions } from "../../geometry/primitives/resolvers.js";
+import { eulerTransform3, scaleTransform3, translationTransform3, validateTransform3, } from "../../geometry/transforms/affine3.js";
+import { attachmentTransform3 } from "../../geometry/transforms/anchors.js";
+import { embedValidatedTransform2, restrictTransform3, } from "../../geometry/transforms/dimensions.js";
+import { transform2, transform3, } from "../../geometry/transforms/value.js";
 import * as kernel from "../native/index.js";
 import { transformPrimitiveSectionProfile } from "./primitives/profiles.js";
 /** Internal host-bound transform operations. */
 export function createTransformOperations(environment) {
     const { scope, throwGeometryError, resolveHandle, nativeSolid, wrapSolid, ownSection, validateFiniteNumber, validateCoordinates, } = environment;
     const preserveProfile = (source, result, matrix) => {
-        environment.preserveAnchors(source, result, [
-            matrix[0],
-            matrix[1],
-            0,
-            matrix[2],
-            matrix[3],
-            matrix[4],
-            0,
-            matrix[5],
-            0,
-            0,
-            1,
-            0,
-            0,
-            0,
-            0,
-            1,
-        ]);
+        environment.preserveAnchors(source, result, embedValidatedTransform2(matrix));
         const profile = environment.primitiveProfileFor(source);
         return profile === undefined
             ? result
@@ -160,8 +144,8 @@ export function createTransformOperations(environment) {
     const transform = ((value, placement) => {
         const native = resolveHandle(value);
         const matrix = native.kind === "solid"
-            ? transform3(readTransformMatrix(placement, 3)).toData()
-            : transform2(readTransformMatrix(placement, 2)).toData();
+            ? transform3(placement).toData()
+            : transform2(placement).toData();
         if (native.kind === "solid") {
             validateCoordinates(matrix, 16, "transform");
             return environment.preserveAnchors(value, wrapSolid(kernel.transform(scope, native.value, matrix)), matrix);
@@ -194,7 +178,7 @@ export function createTransformOperations(environment) {
             ...(attachment.gap === undefined ? {} : { gap: attachment.gap }),
             ...(attachment.tolerance === undefined ? {} : { tolerance: attachment.tolerance }),
             spin,
-        });
+        }).toData();
     };
     const placedSolid = (value, create, anchors) => {
         assertPrimitiveOptions(value, "primitive");
@@ -210,19 +194,15 @@ export function createTransformOperations(environment) {
         const matrix = attachmentMatrix(value.attachment, section);
         if (matrix === undefined)
             return section;
-        if (Math.abs(matrix[8]) > 1e-10 || Math.abs(matrix[9]) > 1e-10 || Math.abs(matrix[11]) > 1e-10)
-            throwGeometryError("INVALID_ARGUMENT", "attachment", "Section attachment must preserve the XY plane.");
-        const xy = [
-            matrix[0],
-            matrix[1],
-            matrix[3],
-            matrix[4],
-            matrix[5],
-            matrix[7],
-            0,
-            0,
-            1,
-        ];
+        let xy;
+        try {
+            xy = restrictTransform3(matrix, { absolute: 1e-10 });
+        }
+        catch (error) {
+            if (isGeometryError(error) && error.code === "INVALID_ARGUMENT")
+                throwGeometryError(error.code, "attachment", "Section attachment must preserve the XY plane.");
+            throw error;
+        }
         const result = transform(section, xy);
         return environment.preserveAnchors(section, result, matrix);
     };

package/dist/engine/placement.js

@@ -1,6 +1,6 @@
-import { validateAnalyzedSolidMesh } from "../geometry/mesh/mesh-solid.js";
-import { analyzeTriangleMesh } from "../geometry/mesh/mesh.js";
-import { IDENTITY_TRANSFORM3 } from "../geometry/transform3.js";
+import { analyzeTriangleMesh } from "../geometry/mesh/operations.js";
+import { validateAnalyzedSolidMesh } from "../geometry/mesh/solid.js";
+import { IDENTITY_TRANSFORM3 } from "../geometry/transforms/affine3.js";
 /** Places already validated immutable geometry once, retaining its indexed topology. */
 export function placeFinalizedGeometry(source, matrix, meshValidation) {
     if (matrix.every((value, index) => value === IDENTITY_TRANSFORM3[index]))

package/dist/engine/recipe-realization.js

@@ -4,8 +4,9 @@ import { isImmutableMathValue } from "../geometry/math/immutable-value.js";
 import { geometryRecipe, isGeometryRecipe } from "../model/geometry-recipes.js";
 import { generationDataMetadata } from "../model/immutable-generation-data.js";
 /**
- * Evaluates immutable recipes within one host revision. These maps memoize borrowed native handles;
- * the execution scope still owns allocation and cleanup, including handles restored from cache.
+ * Evaluates immutable recipes within one host revision. These maps memoize borrowed native handles.
+ * The execution scope owns new allocations; the native cache retains ownership and cleanup
+ * responsibility for restored handles.
  */
 export class RecipeRealization {
     session;
@@ -25,6 +26,11 @@ export class RecipeRealization {
     }
     /** Explicit recipe settings override this host's defaults; unspecified settings remain inherited. */
     invoke(call) {
+        const context = this.contextFor(call);
+        this.realizeShapes([...recipeShapes(call.args)]);
+        return this.invokeNative(call, context);
+    }
+    contextFor(call) {
         const resolution = call.resolution;
         let context = this.nativeContexts.get(resolution);
         if (context === undefined) {
@@ -32,6 +38,9 @@ export class RecipeRealization {
             context = resolution === undefined ? host : host.withResolution(resolution);
             this.nativeContexts.set(resolution, context);
         }
+        return context;
+    }
+    invokeNative(call, context) {
         const operation = context[call.method];
         const args = this.resolveValue(call.args, true);
         return this.duringNative(() => Reflect.apply(operation, undefined, args));
@@ -43,7 +52,8 @@ export class RecipeRealization {
         return this.resolvedCalls.get(call);
     }
     resolve(shape) {
-        return this.resolveValue(shape);
+        this.realizeShapes([shape]);
+        return this.realized.get(shape);
     }
     realizedShape(shape) {
         return this.realized.get(shape);
@@ -57,30 +67,68 @@ export class RecipeRealization {
     assertAccessible(shape) {
         if (this.accessible.has(shape))
             return;
-        const recipe = geometryRecipe(shape);
-        if (recipe.observedSession !== undefined && recipe.observedSession !== this.session)
-            throw new GeometryError("INVALID_ARGUMENT", "Observed components can only be evaluated in the model session that selected them.", { operation: "components" });
-        for (const operand of recipeShapes(recipe.call.args))
-            this.assertAccessible(operand);
-        this.accessible.add(shape);
+        const pending = [shape];
+        const checked = new Set();
+        while (pending.length > 0) {
+            const current = pending.pop();
+            if (this.accessible.has(current) || checked.has(current))
+                continue;
+            const recipe = geometryRecipe(current);
+            if (recipe.observedSession !== undefined && recipe.observedSession !== this.session)
+                throw new GeometryError("INVALID_ARGUMENT", "Observed components can only be evaluated in the model session that selected them.", { operation: "components" });
+            checked.add(current);
+            for (const operand of recipeShapes(recipe.call.args))
+                pending.push(operand);
+        }
+        // Do not mark a parent accessible if validation of a descendant failed and was caught.
+        for (const current of checked)
+            this.accessible.add(current);
     }
-    realizeShape(shape) {
-        const recipe = geometryRecipe(shape);
-        this.assertAccessible(shape);
-        if (this.realized.has(shape))
-            return this.realized.get(shape);
-        // Restoring a retained value avoids replay but still borrows through this revision's scope.
-        const retained = this.restoreNative(shape);
-        if (retained !== undefined) {
-            this.realized.set(shape, retained);
-            return retained;
+    /**
+     * Evaluates recipes in operand order with an explicit work stack.
+     * A retained parent bypasses evaluation of its children, but never their ownership validation.
+     */
+    realizeShapes(shapes) {
+        for (const shape of shapes)
+            this.assertAccessible(shape);
+        const pending = shapes
+            .map((shape) => ({ kind: "shape", shape }))
+            .reverse();
+        while (pending.length > 0) {
+            const work = pending.pop();
+            if (work.kind === "invoke") {
+                if (!this.resolvedCalls.has(work.call))
+                    this.resolvedCalls.set(work.call, this.invokeNative(work.call, work.context));
+                continue;
+            }
+            const { shape } = work;
+            const recipe = geometryRecipe(shape);
+            if (work.kind === "select") {
+                const result = this.resolvedCalls.get(recipe.call);
+                this.realized.set(shape, recipe.index === undefined
+                    ? result
+                    : result[recipe.index]);
+                continue;
+            }
+            if (this.realized.has(shape))
+                continue;
+            // Restoring a parent avoids realizing its operands, after validating their ownership.
+            const retained = this.restoreNative(shape);
+            if (retained !== undefined) {
+                this.realized.set(shape, retained);
+                continue;
+            }
+            // LIFO order is operands -> native call -> selected handle. Shared split/joint calls
+            // execute once; later selections read the cached call result without replaying operands.
+            pending.push({ kind: "select", shape });
+            if (!this.resolvedCalls.has(recipe.call)) {
+                const context = this.contextFor(recipe.call);
+                pending.push({ kind: "invoke", call: recipe.call, context });
+                const operands = [...recipeShapes(recipe.call.args)];
+                for (let index = operands.length - 1; index >= 0; index--)
+                    pending.push({ kind: "shape", shape: operands[index] });
+            }
         }
-        const result = this.evaluate(recipe.call);
-        const selected = recipe.index === undefined
-            ? result
-            : result[recipe.index];
-        this.realized.set(shape, selected);
-        return selected;
     }
     /** Copies argument containers so native code cannot mutate captured recipe inputs. */
     resolveValue(value, operand = false, seen = new Map()) {
@@ -89,7 +137,7 @@ export class RecipeRealization {
         if (isGeometryRecipe(value)) {
             if (operand)
                 this.operands.add(value);
-            return this.realizeShape(value);
+            return this.realized.get(value);
         }
         if (typeof value === "object" && value !== null && isImmutableMathValue(value))
             return value;
@@ -115,14 +163,22 @@ export class RecipeRealization {
     }
 }
 /** Walks captured data once, including shared and cyclic containers, without inspecting buffers. */
-function* recipeShapes(values, seen = new Set()) {
-    for (const value of values) {
+function* recipeShapes(values) {
+    const seen = new Set();
+    const pending = [values[Symbol.iterator]()];
+    while (pending.length > 0) {
+        const next = pending.at(-1).next();
+        if (next.done) {
+            pending.pop();
+            continue;
+        }
+        const value = next.value;
         if (typeof value !== "object" || value === null || seen.has(value))
             continue;
         seen.add(value);
         const metadata = generationDataMetadata(value);
         if (metadata !== undefined) {
-            yield* recipeShapes(metadata.children, seen);
+            pending.push(metadata.children[Symbol.iterator]());
             continue;
         }
         if (isGeometryRecipe(value))
@@ -130,6 +186,6 @@ function* recipeShapes(values, seen = new Set()) {
         else if (!isImmutableBuffer(value) &&
             !ArrayBuffer.isView(value) &&
             !isImmutableMathValue(value))
-            yield* recipeShapes(Object.values(value), seen);
+            pending.push(Object.values(value)[Symbol.iterator]());
     }
 }