@metamesh/modeling 0.13.0 → 0.15.0

package/dist/geometry/svg/fill.js

@@ -1,16 +1,8 @@
-import { polygonClipping, unionPolygonGeometry, xorPolygonGeometry } from "../polygon-clipping.js";
-import { normalizeRegion, signedContourArea } from "../regions.js";
+import { clippingRing, polygonClipping, regionFromMultiPolygon, unionPolygonGeometry, xorPolygonGeometry, } from "../polygon-clipping.js";
+import { signedContourArea } from "../regions.js";
 import { assertSamplingCount } from "../sampling-limits.js";
 /** Private clipping stage with the selected execution's immutable allocation ceiling. */
-export function createBoundedSvgClipping(maximumVertices) {
-    function ring(points) {
-        const result = points.map(([x, y]) => [x, y]);
-        const first = result[0];
-        const last = result.at(-1);
-        if (first !== undefined && last !== undefined && (first[0] !== last[0] || first[1] !== last[1]))
-            result.push([...first]);
-        return result;
-    }
+export function createBoundedSvgClipping(maxVertices) {
     function ringVertexCount(value) {
         const first = value[0];
         const last = value.at(-1);
@@ -21,7 +13,7 @@ export function createBoundedSvgClipping(maximumVertices) {
         return value.reduce((total, polygon) => total + polygon.reduce((polygonTotal, path) => polygonTotal + ringVertexCount(path), 0), 0);
     }
     function assertExpandedVertexCount(vertices, stage) {
-        assertSamplingCount(vertices, "preflightSvgRegion", maximumVertices, `SVG ${stage} exceeds ${maximumVertices} expanded vertices (requires ${vertices}).`);
+        assertSamplingCount(vertices, "preflightSvgRegion", maxVertices, `SVG ${stage} exceeds ${maxVertices} expanded vertices (requires ${vertices}).`);
     }
     function boundedMultiPolygon(value, stage) {
         assertExpandedVertexCount(multiPolygonVertexCount(value), stage);
@@ -136,16 +128,16 @@ export function createBoundedSvgClipping(maximumVertices) {
             .map((subpath) => subpath.points);
         if (rings.length === 0)
             return [];
-        const polygons = rings.map((points) => [ring(points)]);
+        const polygons = rings.map((points) => [clippingRing(points)]);
         if (fillRule === "evenodd") {
             return boundedXor(polygons.map((polygon) => [polygon]), "even-odd fill output");
         }
         const positive = rings
             .filter((points) => signedContourArea(points) >= 0)
-            .map((points) => [ring(points)]);
+            .map((points) => [clippingRing(points)]);
         const negative = rings
             .filter((points) => signedContourArea(points) < 0)
-            .map((points) => [ring(points)]);
+            .map((points) => [clippingRing(points)]);
         if (positive.length === 0)
             return boundedUnion([negative], "negative fill output");
         if (negative.length === 0)
@@ -155,12 +147,6 @@ export function createBoundedSvgClipping(maximumVertices) {
         // precisely where positive and negative nonzero winding counts match.
         return differingCoverage(positive, negative);
     }
-    function regionFromMultiPolygon(value) {
-        return normalizeRegion(value.map((polygon) => ({
-            outer: polygon[0].slice(0, -1).map(([x, y]) => [x, y]),
-            holes: polygon.slice(1).map((hole) => hole.slice(0, -1).map(([x, y]) => [x, y])),
-        })));
-    }
     return {
         assertExpandedVertexCount,
         boundedMultiPolygon,

package/dist/geometry/svg-import.js

@@ -429,7 +429,7 @@ function measureSvgRegion(region) {
     let minEdgeLength = Number.POSITIVE_INFINITY;
     let minX = Number.POSITIVE_INFINITY;
     let minY = Number.POSITIVE_INFINITY;
-    let shortEdges = 0;
+    let shortEdgeCount = 0;
     let vertices = 0;
     for (const polygon of region) {
         for (const loop of [polygon.outer, ...polygon.holes]) {
@@ -443,7 +443,7 @@ function measureSvgRegion(region) {
             for (const length of loopEdgeLengths(loop)) {
                 minEdgeLength = Math.min(minEdgeLength, length);
                 if (length < SHORT_EDGE_LENGTH_MM)
-                    shortEdges += 1;
+                    shortEdgeCount += 1;
             }
         }
     }
@@ -456,13 +456,13 @@ function measureSvgRegion(region) {
     return Object.freeze({
         area: regionArea(region),
         bounds,
-        components: region.length,
-        contours: region.length + holes,
-        holes,
+        componentCount: region.length,
+        contourCount: region.length + holes,
+        holeCount: holes,
         minEdgeLength: Number.isFinite(minEdgeLength) ? minEdgeLength : null,
-        shortEdges,
-        tinyIslands: region.filter((polygon) => polygonArea(polygon) < TINY_ISLAND_AREA_MM2).length,
-        vertices,
+        shortEdgeCount,
+        tinyIslandCount: region.filter((polygon) => polygonArea(polygon) < TINY_ISLAND_AREA_MM2).length,
+        vertexCount: vertices,
     });
 }
 /**
@@ -498,10 +498,10 @@ function createSvgRegionPreflight(svg, options = {}) {
     const stack = [];
     const geometry = [];
     let elementCount = 0;
-    let emptyElements = 0;
+    let emptyElementCount = 0;
     let expandedGeometryVertices = 0;
-    let implicitFilledClosures = 0;
-    let invisibleElements = 0;
+    let implicitFilledClosureCount = 0;
+    let invisibleElementCount = 0;
     let nodeCount = 0;
     let rootSeen = false;
     let strokeConstructionVertices = 0;
@@ -582,9 +582,9 @@ function createSvgRegionPreflight(svg, options = {}) {
             const paintedStroke = isPainted(paint.stroke, paint.strokeOpacity) && paint.strokeWidth > 0;
             const elementGeometry = [];
             if (!paintedFill && !paintedStroke)
-                invisibleElements += 1;
+                invisibleElementCount += 1;
             if (paintedFill) {
-                implicitFilledClosures += subpaths.filter((subpath) => !subpath.closed && subpath.points.length >= 3).length;
+                implicitFilledClosureCount += subpaths.filter((subpath) => !subpath.closed && subpath.points.length >= 3).length;
                 appendGeometry(elementGeometry, fillGeometry(subpaths, paint.fillRule), "element fill output");
             }
             if (paintedStroke) {
@@ -606,7 +606,7 @@ function createSvgRegionPreflight(svg, options = {}) {
                 }
             }
             if ((paintedFill || paintedStroke) && elementGeometry.every((value) => value.length === 0)) {
-                emptyElements += 1;
+                emptyElementCount += 1;
             }
             geometry.push(...elementGeometry);
         }
@@ -628,17 +628,17 @@ function createSvgRegionPreflight(svg, options = {}) {
         geometry: measureSvgRegion(region),
         region,
         repairs: Object.freeze({
-            emptyElements,
-            implicitFilledClosures,
-            invisibleElements,
-            removedDuplicateVertices: budget.removedDuplicateCount,
-            removedSeamVertices: budget.removedSeamCount,
+            emptyElementCount,
+            implicitFilledClosureCount,
+            invisibleElementCount,
+            removedDuplicateVertexCount: budget.removedDuplicateCount,
+            removedSeamVertexCount: budget.removedSeamCount,
         }),
         source: Object.freeze({
-            bytes,
-            elements: elementCount,
-            emittedVertices: budget.emittedCount,
-            parsedVertices: budget.parsedCount,
+            byteCount: bytes,
+            elementCount,
+            emittedVertexCount: budget.emittedCount,
+            parsedVertexCount: budget.parsedCount,
         }),
     });
 }

package/dist/geometry/sweeps/options.js

@@ -1,4 +1,5 @@
 import { GeometryError } from "../errors.js";
+import { vector2Data } from "../math/vector-value.js";
 /** @internal Validates local scales before any manufacturing buffer allocation. */
 export function resolveSweepScales(scale, stationCount) {
     const fail = () => {
@@ -10,14 +11,14 @@ export function resolveSweepScales(scale, stationCount) {
                 fail();
             return [value, value];
         }
-        if (!Array.isArray(value) ||
-            value.length !== 2 ||
-            !value.every((n) => typeof n === "number" && Number.isFinite(n) && n > 0))
+        const coordinates = vector2Data(value);
+        if (!coordinates.every((n) => typeof n === "number" && Number.isFinite(n) && n > 0))
             fail();
-        return value;
+        return coordinates;
     };
     if (scale === undefined ||
         typeof scale === "number" ||
+        (typeof scale === "object" && scale !== null && "toArray" in scale) ||
         (Array.isArray(scale) && typeof scale[0] === "number")) {
         const value = pair(scale ?? 1);
         return Array.from({ length: stationCount }, () => value);

package/dist/geometry/sweeps/orientation.js

@@ -14,7 +14,7 @@ export function validateSweepOptions(options) {
         "limits",
         "orientation",
         "resolution",
-        "twistDegrees",
+        "twist",
         "twistBy",
         "scale",
         "seamProfileOffset",
@@ -27,8 +27,8 @@ export function validateSweepOptions(options) {
         options.twistBy !== "length" &&
         options.twistBy !== "stations")
         fail("Sweep twistBy must be length or stations.");
-    if (!Number.isFinite(options.twistDegrees ?? 0))
-        throw new GeometryError("NON_FINITE_VALUE", "Sweep twistDegrees must be finite.", {
+    if (!Number.isFinite(options.twist ?? 0))
+        throw new GeometryError("NON_FINITE_VALUE", "Sweep twist must be finite.", {
             operation: "sweep",
         });
     const policy = options.orientation;
@@ -58,8 +58,8 @@ export function validateSweepOptions(options) {
     if (Object.keys(policy).some((key) => !keys.includes(key)))
         fail("Unsupported field for the selected sweep orientation.");
 }
-function directedNormal(value, tangent, label) {
-    validateSweepNormal(value, "sweep");
+function directedNormal(input, tangent, label) {
+    const value = validateSweepNormal(input, "sweep");
     const maximum = Math.max(...value.map(Math.abs));
     const unit = normalize3([value[0] / maximum, value[1] / maximum, value[2] / maximum]);
     const projected = projectOntoPlane3(unit, tangent);

package/dist/geometry/sweeps/stations.js

@@ -1,5 +1,5 @@
 import { GeometryError } from "../errors.js";
-import { cross3, dot3, lerp3, normalize3, rotateAroundAxis3 } from "../math/vector3.js";
+import { cross3, dot3, lerp3, normalize3, rotateAroundAxis3Radians } from "../math/vector3.js";
 import { resolveGeometryResolution } from "../resolution.js";
 import { assertSamplingCount, resolveGeometrySamplingLimits } from "../sampling-limits.js";
 /** @internal Original station progression, with a virtual final seam endpoint for closed paths. */
@@ -65,14 +65,14 @@ function frameRotation(from, to) {
 export function planSweepStations(contours, path, scales, options, frames) {
     const closed = options.closed ?? false;
     const segmentCount = closed ? path.length : path.length - 1;
-    const twist = ((options.twistDegrees ?? 0) / 180) * Math.PI;
-    if (!Number.isFinite(twist))
-        throw new GeometryError("NON_FINITE_VALUE", "Sweep twistDegrees must be finite.", {
+    const twistRadians = ((options.twist ?? 0) / 180) * Math.PI;
+    if (!Number.isFinite(twistRadians))
+        throw new GeometryError("NON_FINITE_VALUE", "Sweep twist must be finite.", {
             operation: "sweep",
         });
     const intervals = [];
     const progress = sweepProgress(path, options);
-    if (twist === 0)
+    if (twistRadians === 0)
         return { intervals: Array(segmentCount).fill(1), stationCount: path.length, progress };
     const resolution = resolveGeometryResolution(options.resolution, options.limits);
     const limits = resolveGeometrySamplingLimits(options.limits);
@@ -92,7 +92,7 @@ export function planSweepStations(contours, path, scales, options, frames) {
     let stationCount = closed ? 0 : 1;
     for (let i = 0; i < segmentCount; i++) {
         const next = (i + 1) % path.length;
-        const twistStep = Math.abs(twist * (progress[i + 1] - progress[i]));
+        const twistStep = Math.abs(twistRadians * (progress[i + 1] - progress[i]));
         const frameAngle = frames === undefined ? 0 : frameRotation(frames[i], frames[next]).angle;
         const angle = frameAngle + twistStep;
         const maximumScale = Math.max(...scales[i], ...scales[next]);
@@ -104,9 +104,9 @@ export function planSweepStations(contours, path, scales, options, frames) {
         const a = curvature / 8, b = (edgeLength * (maximumScale * angle + scaleChange)) / 4;
         const requiredAngular = resolution.circularSegments === undefined
             ? Math.max(1, Math.ceil((b + Math.hypot(b, 2 * Math.sqrt(a * resolution.maxChordError))) /
-                (2 * resolution.maxChordError)), Math.ceil((resolution.minimumSegments * angle) / (2 * Math.PI)))
+                (2 * resolution.maxChordError)), Math.ceil((resolution.minSegments * angle) / (2 * Math.PI)))
             : Math.max(1, Math.ceil((resolution.circularSegments * angle) / (2 * Math.PI)));
-        const allowedAngular = Math.max(1, scaleChange === 0 ? 0 : resolution.maximumSegments, Math.ceil((resolution.maximumSegments * angle) / (2 * Math.PI)));
+        const allowedAngular = Math.max(1, scaleChange === 0 ? 0 : resolution.maxSegments, Math.ceil((resolution.maxSegments * angle) / (2 * Math.PI)));
         if (requiredAngular > allowedAngular)
             throw new GeometryError("COMPLEXITY_LIMIT", `Sweep surface refinement requires ${requiredAngular} intervals; the selected circular ceiling allows ${allowedAngular}.`, {
                 operation: "sweep",
@@ -126,7 +126,7 @@ export function planSweepStations(contours, path, scales, options, frames) {
 }
 /** Inserts twist samples without calling authored guides again or changing original station meaning. */
 export function refineSweepStations(path, scales, frames, options, plan) {
-    const twist = ((options.twistDegrees ?? 0) / 180) * Math.PI;
+    const twistRadians = ((options.twist ?? 0) / 180) * Math.PI;
     const segmentCount = plan.intervals.length;
     const points = [], sampledScales = [], sampledFrames = [], twists = [];
     for (let i = 0; i < segmentCount; i++) {
@@ -144,18 +144,18 @@ export function refineSweepStations(path, scales, frames, options, plan) {
             sampledFrames.push(amount === 0
                 ? frames[i]
                 : {
-                    normal: rotateAroundAxis3(frames[i].normal, rotation.axis, rotation.angle * amount),
-                    binormal: rotateAroundAxis3(frames[i].binormal, rotation.axis, rotation.angle * amount),
-                    tangent: rotateAroundAxis3(frames[i].tangent, rotation.axis, rotation.angle * amount),
+                    normal: rotateAroundAxis3Radians(frames[i].normal, rotation.axis, rotation.angle * amount),
+                    binormal: rotateAroundAxis3Radians(frames[i].binormal, rotation.axis, rotation.angle * amount),
+                    tangent: rotateAroundAxis3Radians(frames[i].tangent, rotation.axis, rotation.angle * amount),
                 });
-            twists.push(twist * (plan.progress[i] + (plan.progress[i + 1] - plan.progress[i]) * amount));
+            twists.push(twistRadians * (plan.progress[i] + (plan.progress[i + 1] - plan.progress[i]) * amount));
         }
     }
     if (options.closed !== true) {
         points.push(path.at(-1));
         sampledScales.push(scales.at(-1));
         sampledFrames.push(frames.at(-1));
-        twists.push(twist);
+        twists.push(twistRadians);
     }
     return { path: points, scales: sampledScales, frames: sampledFrames, twists };
 }

package/dist/geometry/sweeps/sweep-closed.js

@@ -1,5 +1,5 @@
 import { GeometryError } from "../errors.js";
-import { add3, rotateAroundAxis3, scale3 } from "../math/vector3.js";
+import { add3, rotateAroundAxis3Radians, scale3 } from "../math/vector3.js";
 import { validateTriangleMesh } from "../mesh/mesh.js";
 import { resolveGeometryTolerance } from "../tolerance.js";
 import { resolveSweepScales } from "./options.js";
@@ -20,9 +20,9 @@ export const buildClosedSweepMesh = (profile, path, options = {}) => {
             operation,
         });
     }
-    const twistRadians = ((options.twistDegrees ?? 0) / 180) * Math.PI;
+    const twistRadians = ((options.twist ?? 0) / 180) * Math.PI;
     if (!Number.isFinite(twistRadians)) {
-        throw new GeometryError("NON_FINITE_VALUE", "Sweep twistDegrees must be finite.", {
+        throw new GeometryError("NON_FINITE_VALUE", "Sweep twist must be finite.", {
             operation,
         });
     }
@@ -63,8 +63,8 @@ export const buildClosedSweepMesh = (profile, path, options = {}) => {
         const tangent = transportedFrames[ring].tangent;
         const twist = twists?.[ring] ?? twistRadians * (ring / path.length);
         const baseNormal = transportedFrames[ring].normal;
-        const normal = rotateAroundAxis3(baseNormal, tangent, twist);
-        const binormal = rotateAroundAxis3(transportedFrames[ring].binormal, tangent, twist);
+        const normal = rotateAroundAxis3Radians(baseNormal, tangent, twist);
+        const binormal = rotateAroundAxis3Radians(transportedFrames[ring].binormal, tangent, twist);
         const [scaleX, scaleY] = scales[ring];
         for (let profileIndex = 0; profileIndex < profile.length; profileIndex += 1) {
             const [x, y] = profile[profileIndex];

package/dist/geometry/sweeps/sweep-mesh.js

@@ -1,4 +1,6 @@
 import { GeometryError } from "../errors.js";
+import { resolveModelingLimits } from "../model-limits.js";
+import { path2InputData, path3InputData, } from "../paths/path-value.js";
 import { validateSweepOptions } from "./orientation.js";
 import { buildClosedSweepMesh } from "./sweep-closed.js";
 import { buildOpenSweepMesh } from "./sweep-open.js";
@@ -15,12 +17,16 @@ import { buildOpenSweepMesh } from "./sweep-open.js";
  */
 export function sweepMesh(profile, path, options = {}) {
     validateSweepOptions(options);
-    if (options.closed === true) {
-        return buildClosedSweepMesh(profile, path, options);
+    const limits = resolveModelingLimits(options.limits);
+    const outline = path2InputData(profile, true, { maxPathPoints: limits.maxProfilePoints }).points;
+    const data = path3InputData(path, options.closed, limits);
+    const selected = { ...options, closed: data.closed };
+    if (data.closed) {
+        return buildClosedSweepMesh(outline, data.points, selected);
     }
     if ((options.seamProfileOffset ?? 0) !== 0)
         throw new GeometryError("INVALID_ARGUMENT", "A seamProfileOffset requires a closed path.", {
             operation: "sweep",
         });
-    return buildOpenSweepMesh(profile, path, options);
+    return buildOpenSweepMesh(outline, data.points, selected);
 }

package/dist/geometry/sweeps/sweep-open.js

@@ -1,5 +1,5 @@
 import { triangulateContour } from "../loft/loft.js";
-import { add3, rotateAroundAxis3, scale3 } from "../math/vector3.js";
+import { add3, rotateAroundAxis3Radians, scale3 } from "../math/vector3.js";
 import { validateTriangleMesh } from "../mesh/mesh.js";
 import { resolveSweepScales } from "./options.js";
 import { computeSweepFrames, validateSweepOptions } from "./orientation.js";
@@ -13,7 +13,7 @@ export const buildOpenSweepMesh = (profile, path, options = {}) => {
     path = normalizeSweepPath(path, false, operation, options.limits);
     assertSweepAllocation(path.length, profile.length, false, operation, options.limits);
     let scales = resolveSweepScales(options.scale, path.length);
-    const twistRadians = ((options.twistDegrees ?? 0) / 180) * Math.PI;
+    const twistRadians = ((options.twist ?? 0) / 180) * Math.PI;
     if (twistRadians !== 0) {
         const plan = planSweepStations([profile], path, scales, options);
         assertSweepAllocation(plan.stationCount, profile.length, false, operation, options.limits);
@@ -37,8 +37,8 @@ export const buildOpenSweepMesh = (profile, path, options = {}) => {
         const point = path[ring];
         const frame = frames[ring];
         const twist = twists?.[ring] ?? (twistRadians * ring) / (path.length - 1);
-        const normal = rotateAroundAxis3(frame.normal, frame.tangent, twist);
-        const binormal = rotateAroundAxis3(frame.binormal, frame.tangent, twist);
+        const normal = rotateAroundAxis3Radians(frame.normal, frame.tangent, twist);
+        const binormal = rotateAroundAxis3Radians(frame.binormal, frame.tangent, twist);
         const [scaleX, scaleY] = scales[ring];
         for (let profileIndex = 0; profileIndex < profile.length; profileIndex += 1) {
             const [x, y] = profile[profileIndex];

package/dist/geometry/sweeps/validation.js

@@ -1,4 +1,5 @@
 import { GeometryError } from "../errors.js";
+import { vector3Data } from "../math/vector-value.js";
 import { assertMeshAllocationWithinLimits, resolveModelingLimits, } from "../model-limits.js";
 import { writeMeshVertex } from "../numeric.js";
 import { normalizeContour } from "../regions.js";
@@ -97,13 +98,8 @@ export function writeSweepVertex(positions, offset, point, operation) {
     writeMeshVertex(positions, offset, point, operation);
 }
 /** @internal Checks user-provided orientation controls before vector normalization. */
-export function validateSweepNormal(normal, operation) {
-    const hasArrayShape = Array.isArray(normal);
-    if (!hasArrayShape || normal.length !== 3) {
-        throw new GeometryError("INVALID_ARGUMENT", "Sweep normals must be exact XYZ tuples.", {
-            operation,
-        });
-    }
+export function validateSweepNormal(input, operation) {
+    const normal = vector3Data(input);
     if (![normal[0], normal[1], normal[2]].every(Number.isFinite)) {
         throw new GeometryError("NON_FINITE_VALUE", "Sweep normal coordinates must be finite XYZ values.", { operation });
     }
@@ -112,4 +108,5 @@ export function validateSweepNormal(normal, operation) {
             operation,
         });
     }
+    return normal;
 }

package/dist/geometry/transform-chain.js

@@ -0,0 +1,172 @@
+import { GeometryError } from "./errors.js";
+import { immutableMathClass } from "./math/immutable-value.js";
+import { vector2, vector2Data, vector3, vector3Data, } from "./math/vector-value.js";
+import { readTransformMatrix } from "./transform-matrix.js";
+import { embedTransform2, restrictTransform3 } from "./transform2.js";
+import { applyInverseTranspose3, applyValidatedTransformDirection3, applyValidatedTransformPoint3, composeTransform3, eulerTransform3, IDENTITY_TRANSFORM3, inverseLinearTransform3, inverseTransform3, rotationTransform3, scaleTransform3, translationTransform3, validateTransform3, } from "./transform3.js";
+const pivotTransform = (matrix, pivot) => pivot === undefined
+    ? matrix
+    : composeTransform3(translationTransform3(pivot), composeTransform3(matrix, translationTransform3([-pivot[0], -pivot[1], -pivot[2]])));
+const xyz = (point) => [point[0], point[1], 0];
+const xy = (point) => [point[0], point[1]];
+const pivot2 = (options) => {
+    validatePivotOptions(options);
+    return options?.pivot === undefined ? undefined : xyz(vector2Data(options.pivot));
+};
+const pivot3 = (options) => {
+    validatePivotOptions(options);
+    return options?.pivot === undefined ? undefined : vector3Data(options.pivot);
+};
+function validatePivotOptions(options) {
+    if (options !== undefined &&
+        (options === null || typeof options !== "object" || Array.isArray(options))) {
+        throw new GeometryError("INVALID_ARGUMENT", "Rotation and scaling options require a named pivot.");
+    }
+}
+// Translation does not affect normals. Inverting only the linear component also avoids
+// irrelevant overflow from a large inverse translation. Cache once per immutable placement.
+const normalMatrices = new WeakMap();
+function applyNormal(owner, matrix, normal) {
+    let inverse = normalMatrices.get(owner);
+    if (inverse === undefined) {
+        inverse = inverseLinearTransform3(matrix);
+        normalMatrices.set(owner, inverse);
+    }
+    return applyInverseTranspose3(inverse, normal);
+}
+const snapshotTransform3 = (matrix) => {
+    validateTransform3(matrix);
+    return Object.freeze([
+        matrix[0],
+        matrix[1],
+        matrix[2],
+        matrix[3],
+        matrix[4],
+        matrix[5],
+        matrix[6],
+        matrix[7],
+        matrix[8],
+        matrix[9],
+        matrix[10],
+        matrix[11],
+        0,
+        0,
+        0,
+        1,
+    ]);
+};
+const Placement3 = /* @__PURE__ */ immutableMathClass(class Placement3 {
+    matrix;
+    constructor(matrix) {
+        this.matrix = matrix;
+        Object.freeze(this);
+    }
+    translate(offset) {
+        return this.andThen(translationTransform3(vector3Data(offset)));
+    }
+    rotate(degrees, options) {
+        return this.andThen(pivotTransform(eulerTransform3(vector3Data(degrees)), pivot3(options)));
+    }
+    rotateAxis(axis, degrees, options) {
+        return this.andThen(pivotTransform(rotationTransform3(vector3Data(axis), { degrees }), pivot3(options)));
+    }
+    scale(factors, options) {
+        const values = typeof factors === "number" ? [factors, factors, factors] : vector3Data(factors);
+        return this.andThen(pivotTransform(scaleTransform3(values), pivot3(options)));
+    }
+    andThen(next) {
+        return new Placement3(composeTransform3(snapshotTransform3(readTransformMatrix(next, 3)), this.matrix));
+    }
+    inverse() {
+        return new Placement3(inverseTransform3(this.matrix));
+    }
+    applyPoint(point) {
+        return vector3(applyValidatedTransformPoint3(this.matrix, vector3Data(point)));
+    }
+    applyDirection(direction) {
+        return vector3(applyValidatedTransformDirection3(this.matrix, vector3Data(direction)));
+    }
+    applyNormal(normal) {
+        return vector3(applyNormal(this, this.matrix, vector3Data(normal)));
+    }
+    toMatrix() {
+        return this.matrix;
+    }
+    to2D() {
+        return transform2(restrictTransform3(this.matrix));
+    }
+});
+const Placement2 = /* @__PURE__ */ immutableMathClass(class Placement2 {
+    spatial;
+    matrix;
+    constructor(spatial) {
+        this.spatial = spatial;
+        this.matrix = restrictTransform3(spatial.toMatrix());
+        Object.freeze(this);
+    }
+    translate(offset) {
+        return new Placement2(this.spatial.translate(xyz(vector2Data(offset))));
+    }
+    rotate(degrees, options) {
+        const pivot = pivot2(options);
+        return new Placement2(this.spatial.rotateAxis([0, 0, 1], degrees, pivot === undefined ? undefined : { pivot }));
+    }
+    scale(factors, options) {
+        const pair = typeof factors === "number" ? [factors, factors] : vector2Data(factors);
+        const values = [pair[0], pair[1], 1];
+        const pivot = pivot2(options);
+        return new Placement2(this.spatial.scale(values, pivot === undefined ? undefined : { pivot }));
+    }
+    andThen(next) {
+        return new Placement2(this.spatial.andThen(embedTransform2(readTransformMatrix(next, 2))));
+    }
+    inverse() {
+        return new Placement2(this.spatial.inverse());
+    }
+    applyPoint(point) {
+        return vector2(xy(applyValidatedTransformPoint3(this.spatial.toMatrix(), xyz(vector2Data(point)))));
+    }
+    applyDirection(direction) {
+        return vector2(xy(applyValidatedTransformDirection3(this.spatial.toMatrix(), xyz(vector2Data(direction)))));
+    }
+    applyNormal(normal) {
+        return vector2(xy(applyNormal(this, this.spatial.toMatrix(), xyz(vector2Data(normal)))));
+    }
+    toMatrix() {
+        return this.matrix;
+    }
+    to3D() {
+        return this.spatial;
+    }
+});
+/**
+ * Creates an immutable XY transform, identity by default. Matrices are copied and validated.
+ * Pass it directly to Section.transform() and planar data helpers; to3D() explicitly crosses into XYZ.
+ * Zero scales and singular matrices throw GeometryError; negative scales reflect.
+ *
+ * @example
+ * ```ts
+ * const placement = transform2().rotate(90).translate([10, 0]);
+ * placement.applyPoint([1, 0]).toArray(); // approximately [10, 1]
+ * ```
+ */
+export function transform2(matrix) {
+    return new Placement2(matrix === undefined
+        ? new Placement3(IDENTITY_TRANSFORM3)
+        : new Placement3(embedTransform2(matrix)));
+}
+/**
+ * Creates an immutable XYZ transform, identity by default. Matrices are copied and validated.
+ * Calls apply in written order; rotations use degrees and pivots use current world coordinates.
+ * Zero scales, singular matrices, nonfinite inputs and zero rotation axes throw GeometryError.
+ * Use frameTransform3(frame) as the input for existing orthonormal frame placement.
+ *
+ * @example
+ * ```ts
+ * const placement = transform3().rotate([0, 0, 90]).translate([10, 0, 0]);
+ * placement.applyPoint([1, 0, 0]).toArray(); // approximately [10, 1, 0]
+ * ```
+ */
+export function transform3(matrix = IDENTITY_TRANSFORM3) {
+    return new Placement3(snapshotTransform3(matrix));
+}

package/dist/geometry/transform-geometry.js

@@ -1,41 +1,38 @@
-import { GeometryError } from "./errors.js";
+import { vector2Data } from "./math/vector-value.js";
 import { normalizeContour, normalizeRegion, signedContourArea } from "./regions.js";
-import { resolveGeometryTolerance } from "./tolerance.js";
-import { applyTransformPoint3, validateTransform3 } from "./transform3.js";
-/** Applies an affine transform to a 3D path without mutating its points. */
-export function transformPath3(path, transform) {
+import { readTransformMatrix } from "./transform-matrix.js";
+import { embedTransform2 } from "./transform2.js";
+import { applyValidatedTransformPoint3, validateTransform3 } from "./transform3.js";
+/** Internal owned coordinates for a Path3 result; no mutable coordinates escape the path value. */
+export function transformPath3(path, placement) {
+    const transform = readTransformMatrix(placement, 3);
     validateTransform3(transform);
-    return Object.freeze(path.map((point) => Object.freeze(applyTransformPoint3(transform, point))));
+    return path.map((point) => applyValidatedTransformPoint3(transform, point));
 }
-const transformPoint2 = (point, transform, tolerance) => {
-    const transformed = applyTransformPoint3(transform, [point[0], point[1], 0]);
-    const resolved = resolveGeometryTolerance(Math.max(1, Math.abs(transformed[0]), Math.abs(transformed[1])), tolerance);
-    if (Math.abs(transformed[2]) > resolved.linear) {
-        throw new GeometryError("INVALID_ARGUMENT", "A 2D transform must preserve the XY plane.", {
-            operation: "transformPath2",
-        });
-    }
-    return Object.freeze([transformed[0], transformed[1]]);
+const transformPoint2 = (point, transform) => {
+    const values = vector2Data(point);
+    const transformed = applyValidatedTransformPoint3(transform, [values[0], values[1], 0]);
+    return [transformed[0], transformed[1]];
 };
-/** Applies an XY-plane-preserving affine transform to a 2D path. */
+const transformPlanarPath = (path, transform) => Object.freeze(path.map((point) => Object.freeze(transformPoint2(point, transform))));
+/** Internal owned XY coordinates preserving path traversal; public interchange is frozen by Path2. */
 export function transformPath2(path, transform, tolerance = {}) {
-    validateTransform3(transform, tolerance);
-    return Object.freeze(path.map((point) => transformPoint2(point, transform, tolerance)));
+    const matrix = embedTransform2(readTransformMatrix(transform, 2), tolerance);
+    return path.map((point) => transformPoint2(point, matrix));
 }
-/**
- * Transforms a closed loop and preserves its original winding convention.
- *
- * Reflections reverse the point order automatically through normalization.
- */
-export function transformContour(loop, transform, tolerance = {}) {
+const transformContourWithMatrix = (loop, transform, tolerance) => {
     const counterClockwise = signedContourArea(loop) > 0;
     const normalized = normalizeContour(loop, counterClockwise, tolerance);
-    return normalizeContour(transformPath2(normalized, transform, tolerance), counterClockwise, tolerance);
-}
-/** Transforms an explicit outer/hole region with reflection-safe winding correction. */
-export function transformRegion(region, transform, tolerance = {}) {
+    return normalizeContour(transformPlanarPath(normalized, transform), counterClockwise, tolerance);
+};
+/**
+ * Transforms serialized polygon data with reflection-safe winding, without an engine.
+ * Use Section.transform(placement) when authoring filled geometry; this utility serves pure data preparation.
+ */
+export function transformRegionData(region, transform, tolerance = {}) {
+    const planar = embedTransform2(readTransformMatrix(transform, 2), tolerance);
     return normalizeRegion(region.map((polygon) => ({
-        holes: polygon.holes.map((hole) => transformContour(hole, transform, tolerance)),
-        outer: transformContour(polygon.outer, transform, tolerance),
+        holes: polygon.holes.map((hole) => transformContourWithMatrix(hole, planar, tolerance)),
+        outer: transformContourWithMatrix(polygon.outer, planar, tolerance),
     })), tolerance);
 }