@metamesh/modeling 0.19.0 → 0.20.0

package/dist/geometry/{sweeps → sweep}/validation.js

@@ -1,9 +1,9 @@
 import { GeometryError } from "../errors.js";
+import { assertMeshAllocationWithinLimits, resolveModelingLimits, } from "../limits.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";
-import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
+import { writeMeshVertex } from "../mesh/write-vertex.js";
+import { normalizeContour } from "../regions/operations.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling/limits.js";
 import { resolveGeometryTolerance } from "../tolerance.js";
 /** @internal Normalizes simple profiles before cap triangulation or side construction. */
 export function normalizeSweepProfile(profile, operation, limits = {}) {

package/dist/geometry/{text-contours.js → text/contours.js}

@@ -1,11 +1,11 @@
-import { GeometryError } from "./errors.js";
-import { flattenSvgPath, SvgVertexBudget } from "./svg/path.js";
+import { GeometryError } from "../errors.js";
+import { flattenSvgPath, SvgVertexBudget } from "../svg/path.js";
 /**
  * Samples a prepared text layout without shaping text again or loading a font.
  *
  * @param layout - Immutable millimetre paths and measurements retained from text preparation.
  * @param resolution - Explicit curve sampling policy; omitted uses the pure default policy.
- * @param limits - Explicit profile and circular allocation ceilings.
+ * @param limits - Profile-point and circle-segment limits.
  * @returns Frozen contours with original glyph winding and no repeated closing vertex.
  * @throws GeometryError for empty outlines, invalid paths or policies, over 1000 paths or selected sampling ceilings.
  */

package/dist/geometry/{text-fitting.js → text/fitting.js}

@@ -1,6 +1,7 @@
 import { SVGPathData, SVGPathDataTransformer } from "svg-pathdata";
-import { boundsSize, fitBounds } from "./bounds.js";
-import { GeometryError } from "./errors.js";
+import { boundsSize, fitBounds } from "../bounds/operations.js";
+import { bounds2 } from "../bounds/value.js";
+import { GeometryError } from "../errors.js";
 function fail(message) {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation: "fitTextLayout" });
 }
@@ -29,7 +30,7 @@ export function fitTextLayout(layout, target, options = {}) {
         fail("Prepared text needs visible outlines and ink bounds, with at most 1000 paths.");
     if (boundsSize(layout.metrics.bounds).some((extent) => extent <= 0))
         fail("Prepared text needs positive visible width and height.");
-    const fit = fitBounds(layout.metrics.bounds, target, options);
+    const fit = fitBounds(layout.metrics.bounds, bounds2(target).toData(), options);
     const { scale, position: [x, y], } = fit;
     let bytes = 0, outputBytes = 0, commands = 0;
     const paths = layout.paths.map((path) => {

package/dist/geometry/text/layout.js

@@ -0,0 +1 @@
+export {};

package/dist/geometry/{transform3.js → transforms/affine3.js}

@@ -1,13 +1,14 @@
-import { GeometryError } from "./errors.js";
-import { cross3, dot3, length3, normalize3 } from "./math/vector3.js";
-import { resolveGeometryTolerance } from "./tolerance.js";
+import { GeometryError } from "../errors.js";
+import { dot3, length3, normalize3 } from "../math/vector3.js";
+import { resolveGeometryTolerance } from "../tolerance.js";
+import { resolveFrame3 } from "./frame.js";
 const finiteVector = (vector, label) => {
     if (!Array.isArray(vector) || vector.length !== 3) {
         throw new GeometryError("INVALID_ARGUMENT", `${label} requires exactly three coordinates.`);
     }
-    if (!vector.every(Number.isFinite)) {
-        throw new GeometryError("NON_FINITE_VALUE", `${label} coordinates must be finite.`);
-    }
+    for (let axis = 0; axis < 3; axis++)
+        if (!Number.isFinite(vector[axis]))
+            throw new GeometryError("NON_FINITE_VALUE", `${label} coordinates must be finite.`);
 };
 const normalized = (vector, label, tolerance) => {
     finiteVector(vector, label);
@@ -28,15 +29,15 @@ export const IDENTITY_TRANSFORM3 = frozenTransform([
  * @param transform - Row-major matrix to validate.
  * @param tolerance - Optional comparison overrides.
  * @returns The original transform after successful validation.
- * @throws {@link GeometryError} For non-finite, non-affine, or singular matrices.
+ * @throws [GeometryError](/docs/reference/geometry/GeometryError) For nonfinite, non-affine, or singular matrices.
  */
 export function validateTransform3(transform, tolerance = {}) {
     if (!Array.isArray(transform) || transform.length !== 16) {
         throw new GeometryError("INVALID_ARGUMENT", "XYZ matrices require exactly sixteen entries.");
     }
-    if (!transform.every(Number.isFinite)) {
-        throw new GeometryError("NON_FINITE_VALUE", "Transforms require sixteen finite values.");
-    }
+    for (let index = 0; index < 16; index++)
+        if (!Number.isFinite(transform[index]))
+            throw new GeometryError("NON_FINITE_VALUE", "Transforms require sixteen finite values.");
     const scale = Math.max(Math.abs(transform[0]), Math.abs(transform[1]), Math.abs(transform[2]), Math.abs(transform[4]), Math.abs(transform[5]), Math.abs(transform[6]), Math.abs(transform[8]), Math.abs(transform[9]), Math.abs(transform[10]));
     const resolved = resolveGeometryTolerance(scale, tolerance);
     if (Math.abs(transform[12]) > resolved.angular ||
@@ -64,7 +65,9 @@ export function validateTransform3(transform, tolerance = {}) {
  * Scale, shear, reflection, and perspective are rejected within the default angular tolerance.
  * Returns the original row-major 4x4 matrix without copying or normalizing it.
  *
- * @throws {@link GeometryError} For a malformed, non-finite, or non-rigid matrix.
+ * @param transform - Row-major 4x4 matrix with a proper rigid transform.
+ *
+ * @throws [GeometryError](/docs/reference/geometry/GeometryError) For a malformed, nonfinite, or non-rigid matrix.
  */
 export function validateRigidTransform3(transform) {
     if (!Array.isArray(transform) || transform.length !== 16)
@@ -91,7 +94,7 @@ export function validateRigidTransform3(transform) {
 /**
  * Creates an immutable translation transform.
  *
- * @param offset - Finite XYZ translation in model units.
+ * @param offset - Finite XYZ translation in millimetres.
  * @returns A frozen row-major transform.
  */
 export function translationTransform3(offset) {
@@ -104,7 +107,7 @@ export function translationTransform3(offset) {
  * Negative components are reflections. Zero components are rejected because
  * they collapse volume and cannot be inverted.
  *
- * @param factors - Finite, non-zero XYZ scale factors.
+ * @param factors - Finite, nonzero XYZ scale factors.
  * @returns A frozen row-major transform.
  */
 export function scaleTransform3(factors) {
@@ -186,30 +189,30 @@ export function rotationTransform3(axis, angle, tolerance = {}) {
  *
  * @param rotationDegrees - Finite `[x, y, z]` rotation angles in degrees.
  * @returns A frozen row-major transform.
- * @throws {@link GeometryError} When an angle is non-finite.
+ * @throws [GeometryError](/docs/reference/geometry/GeometryError) When an angle is nonfinite.
  */
 export function eulerTransform3(rotationDegrees) {
     finiteVector(rotationDegrees, "Euler rotation");
-    return composeTransform3(rotationTransform3([0, 0, 1], { degrees: rotationDegrees[2] }), composeTransform3(rotationTransform3([0, 1, 0], { degrees: rotationDegrees[1] }), rotationTransform3([1, 0, 0], { degrees: rotationDegrees[0] })));
+    return multiplyTransform3(rotationTransform3([0, 0, 1], { degrees: rotationDegrees[2] }), multiplyTransform3(rotationTransform3([0, 1, 0], { degrees: rotationDegrees[1] }), rotationTransform3([1, 0, 0], { degrees: rotationDegrees[0] })));
 }
 /**
  * Composes two affine transforms without mutating either matrix.
  *
- * `composeTransform3(after, before)` applies `before` first and `after` second.
+ * `multiplyTransform3(left, right)` returns `left * right`; `right` acts first on column vectors.
  *
- * @param after - Transform applied second.
- * @param before - Transform applied first.
- * @returns A new frozen transform equal to `after * before`.
+ * @param left - Left matrix factor, applied second.
+ * @param right - Right matrix factor, applied first.
+ * @returns A new frozen transform equal to `left * right`.
  */
-export function composeTransform3(after, before) {
-    validateTransform3(after);
-    validateTransform3(before);
+export function multiplyTransform3(left, right) {
+    validateTransform3(left);
+    validateTransform3(right);
     const values = new Array(16).fill(0);
     for (let row = 0; row < 4; row += 1) {
         for (let column = 0; column < 4; column += 1) {
             let value = 0;
             for (let inner = 0; inner < 4; inner += 1) {
-                value += after[row * 4 + inner] * before[inner * 4 + column];
+                value += left[row * 4 + inner] * right[inner * 4 + column];
             }
             values[row * 4 + column] = value;
         }
@@ -370,41 +373,23 @@ export function applyInverseTranspose3(inverse, normal) {
  * @param frame - Frame whose axes become the transform columns.
  * @param tolerance - Optional orthonormality comparison overrides.
  * @returns A frozen rigid transform.
- * @throws {@link GeometryError} When axes are non-unit, non-orthogonal, or left-handed.
+ * @throws [GeometryError](/docs/reference/geometry/GeometryError) When axes are non-unit, non-orthogonal, or left-handed.
  */
 export function frameTransform3(frame, tolerance = {}) {
-    finiteVector(frame.origin, "Frame origin");
-    const resolved = resolveGeometryTolerance(1, tolerance);
-    const xLength = length3(frame.xAxis);
-    const yLength = length3(frame.yAxis);
-    const zLength = length3(frame.zAxis);
-    if (Math.abs(xLength - 1) > resolved.angular ||
-        Math.abs(yLength - 1) > resolved.angular ||
-        Math.abs(zLength - 1) > resolved.angular) {
-        throw new GeometryError("INVALID_ARGUMENT", "Frame axes must have unit length.");
-    }
-    const x = normalized(frame.xAxis, "Frame X axis", resolved.linear);
-    const y = normalized(frame.yAxis, "Frame Y axis", resolved.linear);
-    const z = normalized(frame.zAxis, "Frame Z axis", resolved.linear);
-    if (Math.abs(dot3(x, y)) > resolved.angular ||
-        Math.abs(dot3(x, z)) > resolved.angular ||
-        Math.abs(dot3(y, z)) > resolved.angular ||
-        dot3(cross3(x, y), z) < 1 - resolved.angular) {
-        throw new GeometryError("INVALID_ARGUMENT", "Frame axes must be right-handed and mutually orthogonal.");
-    }
+    const { origin, xAxis: x, yAxis: y, zAxis: z } = resolveFrame3(frame, tolerance);
     return frozenTransform([
         x[0],
         y[0],
         z[0],
-        frame.origin[0],
+        origin[0],
         x[1],
         y[1],
         z[1],
-        frame.origin[1],
+        origin[1],
         x[2],
         y[2],
         z[2],
-        frame.origin[2],
+        origin[2],
         0,
         0,
         0,

package/dist/geometry/{anchors.js → transforms/anchors.js}

@@ -1,8 +1,9 @@
-import { GeometryError } from "./errors.js";
-import { vector3Data } from "./math/vector-value.js";
-import { cross3, dot3 } from "./math/vector3.js";
-import { resolveGeometryTolerance } from "./tolerance.js";
-import { composeTransform3, frameTransform3, inverseTransform3 } from "./transform3.js";
+import { GeometryError } from "../errors.js";
+import { vector3Data } from "../math/vector-value.js";
+import { cross3, dot3 } from "../math/vector3.js";
+import { resolveGeometryTolerance } from "../tolerance.js";
+import { frameTransform3, inverseTransform3, multiplyTransform3 } from "./affine3.js";
+import { transform3 } from "./value.js";
 const boxFaces = {
     back: [
         [0, -1, 0],
@@ -42,7 +43,9 @@ const assertAnchorOptions = (options, operation) => {
     if (typeof options !== "object" || options === null || Array.isArray(options))
         throw new GeometryError("INVALID_ARGUMENT", "Anchor options must be an object.", { operation });
 };
-/** Creates an outward face-center anchor using the same local origin convention as box().
+/**
+ * Creates an outward face-center anchor using the same local origin convention as box().
+ *
  * @remarks origin applies an explicit translation. For rotated components, transform the
  * resulting anchor frame explicitly; no anchor is inherited from a Boolean result.
  */
@@ -66,10 +69,12 @@ export function boxAnchor3(options) {
             return origin[axis] + (direction[axis] * size[axis]) / 2;
         return (origin[axis] + (direction[axis] > 0 ? size[axis] : direction[axis] < 0 ? 0 : size[axis] / 2));
     };
-    return anchor3([coordinate(0), coordinate(1), coordinate(2)], direction, up);
+    return anchor3({ position: [coordinate(0), coordinate(1), coordinate(2)], direction, up });
 }
-/** Creates a cap-center or radial-side anchor using cylinder()'s construction origin.
- * @remarks Both centered and noncentered cylinders extend along +Z. Side angle uses degrees;
+/**
+ * Creates a cap-center or radial-side anchor using cylinder()'s construction origin.
+ *
+ * @remarks Cylinders use the local Z axis. Side angle uses degrees;
  * origin applies an explicit translation, and arbitrary component transforms remain explicit.
  */
 export function cylinderAnchor3(options) {
@@ -90,12 +95,26 @@ export function cylinderAnchor3(options) {
         throw new GeometryError("INVALID_ARGUMENT", "Unsupported cylinder anchor face.", { operation });
     const center = options.center ?? true;
     if (face === "top")
-        return anchor3([origin[0], origin[1], origin[2] + (center ? height / 2 : height)], [0, 0, 1], [0, 1, 0]);
+        return anchor3({
+            position: [origin[0], origin[1], origin[2] + (center ? height / 2 : height)],
+            direction: [0, 0, 1],
+        });
     if (face === "bottom")
-        return anchor3([origin[0], origin[1], origin[2] - (center ? height / 2 : 0)], [0, 0, -1], [0, 1, 0]);
+        return anchor3({
+            position: [origin[0], origin[1], origin[2] - (center ? height / 2 : 0)],
+            direction: [0, 0, -1],
+        });
     const angleRadians = angle * (Math.PI / 180);
     const cosine = Math.cos(angleRadians), sine = Math.sin(angleRadians);
-    return anchor3([origin[0] + radius * cosine, origin[1] + radius * sine, origin[2] + (center ? 0 : height / 2)], [cosine, sine, 0], [0, 0, 1]);
+    return anchor3({
+        position: [
+            origin[0] + radius * cosine,
+            origin[1] + radius * sine,
+            origin[2] + (center ? 0 : height / 2),
+        ],
+        direction: [cosine, sine, 0],
+        up: [0, 0, 1],
+    });
 }
 const normalized = (vector, label, tolerance) => {
     if (!vector.every(Number.isFinite)) {
@@ -116,14 +135,13 @@ const normalized = (vector, label, tolerance) => {
  * `up` is projected onto the plane perpendicular to `direction`, removing small
  * input drift while preserving its roll intent.
  *
- * @param position - Finite anchor point in model coordinates.
- * @param direction - Non-zero outward attachment normal.
- * @param up - Non-parallel roll reference; defaults to +Y.
- * @param tolerance - Optional comparison overrides.
+ * @param options - Finite position, orientation guides, and optional comparison overrides.
  * @returns A frozen anchor with unit, orthogonal direction and up vectors.
- * @throws {@link GeometryError} For non-finite or degenerate inputs.
+ * @throws {@link GeometryError} For nonfinite or degenerate inputs.
  */
-export function anchor3(position, direction, up = [0, 1, 0], tolerance = {}) {
+export function anchor3(options) {
+    assertAnchorOptions(options, "anchor3");
+    const { position, direction, up = [0, 1, 0], tolerance = {} } = options;
     const coordinates = (input) => {
         const values = vector3Data(input);
         const point = [values[0], values[1], values[2]];
@@ -159,7 +177,7 @@ export function anchor3(position, direction, up = [0, 1, 0], tolerance = {}) {
  * @returns A normalized right-handed frame at the anchor position.
  */
 export function anchorFrame3(anchor, tolerance = {}) {
-    const normalizedAnchor = anchor3(anchor.position, anchor.direction, anchor.up, tolerance);
+    const normalizedAnchor = anchor3({ ...anchor, tolerance });
     const xAxis = normalized(cross3(normalizedAnchor.up, normalizedAnchor.direction), "Anchor X axis", 0);
     return Object.freeze({
         origin: normalizedAnchor.position,
@@ -179,10 +197,11 @@ export function anchorFrame3(anchor, tolerance = {}) {
  * @param source - Anchor expressed in the moving object's local coordinates.
  * @param target - Desired anchor pose in destination coordinates.
  * @param options - Alignment, gap, spin, and tolerance policy.
- * @returns A frozen affine transform for the moving object.
- * @throws {@link GeometryError} For invalid anchors or non-finite options.
+ * @returns An immutable affine transform for the moving object.
+ * @throws {@link GeometryError} For invalid anchors or nonfinite options.
  */
 export function attachmentTransform3(source, target, options = {}) {
+    assertAnchorOptions(options, "attachmentTransform3");
     const gap = options.gap ?? 0;
     const spin = options.spin ?? 0;
     if (options.alignment !== undefined &&
@@ -194,11 +213,11 @@ export function attachmentTransform3(source, target, options = {}) {
         throw new GeometryError("NON_FINITE_VALUE", "Attachment gap and spin must be finite.");
     }
     const sourceFrame = anchorFrame3(source, options.tolerance);
-    const targetAnchor = anchor3(target.position, target.direction, target.up, options.tolerance);
+    const targetAnchor = anchor3({ ...target, tolerance: options.tolerance ?? {} });
     const desiredDirection = (options.alignment ?? "opposed") === "opposed"
         ? [-targetAnchor.direction[0], -targetAnchor.direction[1], -targetAnchor.direction[2]]
         : targetAnchor.direction;
-    const baseFrame = anchorFrame3(anchor3(targetAnchor.position, desiredDirection, targetAnchor.up, options.tolerance), options.tolerance);
+    const baseFrame = anchorFrame3(anchor3({ ...targetAnchor, direction: desiredDirection, tolerance: options.tolerance ?? {} }), options.tolerance);
     const spinRadians = ((spin % 360) * Math.PI) / 180;
     const cosine = Math.cos(spinRadians);
     const sine = Math.sin(spinRadians);
@@ -222,5 +241,5 @@ export function attachmentTransform3(source, target, options = {}) {
         yAxis: spunY,
         zAxis: baseFrame.zAxis,
     };
-    return composeTransform3(frameTransform3(desiredFrame, options.tolerance), inverseTransform3(frameTransform3(sourceFrame, options.tolerance)));
+    return transform3(multiplyTransform3(frameTransform3(desiredFrame, options.tolerance), inverseTransform3(frameTransform3(sourceFrame, options.tolerance))));
 }

package/dist/geometry/{transform-geometry.js → transforms/apply.js}

@@ -1,8 +1,8 @@
-import { vector2Data } from "./math/vector-value.js";
-import { normalizeContour, normalizeRegion, signedContourArea } from "./regions.js";
-import { readTransformMatrix } from "./transform-matrix.js";
-import { embedTransform2 } from "./transform2.js";
-import { applyValidatedTransformPoint3, validateTransform3 } from "./transform3.js";
+import { vector2Data } from "../math/vector-value.js";
+import { normalizeContour, normalizeRegion, signedContourArea } from "../regions/operations.js";
+import { applyValidatedTransformPoint3, validateTransform3 } from "./affine3.js";
+import { embedTransform2 } from "./dimensions.js";
+import { readTransformMatrix } from "./matrix-input.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);
@@ -28,6 +28,9 @@ const transformContourWithMatrix = (loop, transform, 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.
+ *
+ * @param region - Millimetre polygons whose boundaries are normalized before placement.
+ * @param transform - Planar affine placement; reflections preserve winding.
  */
 export function transformRegionData(region, transform, tolerance = {}) {
     const planar = embedTransform2(readTransformMatrix(transform, 2), tolerance);

package/dist/geometry/{transform2.js → transforms/dimensions.js}

@@ -1,21 +1,9 @@
-import { GeometryError } from "./errors.js";
-import { resolveGeometryTolerance } from "./tolerance.js";
-import { validateTransform3 } from "./transform3.js";
-/** Embeds a validated affine XY matrix into XYZ, leaving Z unchanged. */
-export function embedTransform2(matrix, options = {}) {
-    if (!Array.isArray(matrix) || matrix.length !== 9) {
-        throw new GeometryError("INVALID_ARGUMENT", "XY matrices require exactly nine entries.");
-    }
-    if (!matrix.every(Number.isFinite)) {
-        throw new GeometryError("NON_FINITE_VALUE", "XY transforms require nine finite values.");
-    }
-    const tolerance = resolveGeometryTolerance(1, options);
-    if (Math.abs(matrix[6]) > tolerance.angular ||
-        Math.abs(matrix[7]) > tolerance.angular ||
-        Math.abs(matrix[8] - 1) > tolerance.angular) {
-        throw new GeometryError("INVALID_ARGUMENT", "XY transform final row must be [0, 0, 1].");
-    }
-    return Object.freeze(validateTransform3([
+import { GeometryError } from "../errors.js";
+import { resolveGeometryTolerance } from "../tolerance.js";
+import { validateTransform3 } from "./affine3.js";
+/** @internal Embeds an already validated XY matrix into an owned XYZ matrix without revalidation. */
+export function embedValidatedTransform2(matrix) {
+    return [
         matrix[0],
         matrix[1],
         0,
@@ -32,7 +20,23 @@ export function embedTransform2(matrix, options = {}) {
         0,
         0,
         1,
-    ], options));
+    ];
+}
+/** Embeds a validated affine XY matrix into XYZ, leaving Z unchanged. */
+export function embedTransform2(matrix, options = {}) {
+    if (!Array.isArray(matrix) || matrix.length !== 9) {
+        throw new GeometryError("INVALID_ARGUMENT", "XY matrices require exactly nine entries.");
+    }
+    if (!matrix.every(Number.isFinite)) {
+        throw new GeometryError("NON_FINITE_VALUE", "XY transforms require nine finite values.");
+    }
+    const tolerance = resolveGeometryTolerance(1, options);
+    if (Math.abs(matrix[6]) > tolerance.angular ||
+        Math.abs(matrix[7]) > tolerance.angular ||
+        Math.abs(matrix[8] - 1) > tolerance.angular) {
+        throw new GeometryError("INVALID_ARGUMENT", "XY transform final row must be [0, 0, 1].");
+    }
+    return Object.freeze(validateTransform3(embedValidatedTransform2(matrix), options));
 }
 /** Restricts an affine XYZ matrix to XY; validates the plane independently of sampled points. */
 export function restrictTransform3(matrix, options = {}) {

package/dist/geometry/transforms/frame.js

@@ -0,0 +1,64 @@
+import { GeometryError } from "../errors.js";
+import { vector3Data } from "../math/vector-value.js";
+import { cross3, dot3, length3 } from "../math/vector3.js";
+import { resolveGeometryTolerance } from "../tolerance.js";
+const coordinates = (input, label) => {
+    const values = vector3Data(input);
+    const copied = [values[0], values[1], values[2]];
+    if (!copied.every(Number.isFinite))
+        throw new GeometryError("NON_FINITE_VALUE", `${label} coordinates must be finite.`);
+    return copied;
+};
+/** @internal One validation and normalization owner for frame values and placement conversion. */
+export function resolveFrame3(options, tolerance = {}) {
+    if (typeof options !== "object" || options === null || Array.isArray(options))
+        throw new GeometryError("INVALID_ARGUMENT", "A frame requires an origin and three axes.");
+    const origin = coordinates(options.origin, "Frame origin");
+    const resolved = resolveGeometryTolerance(1, tolerance);
+    const axis = (input) => {
+        const value = coordinates(input, "Frame axis");
+        const length = length3(value);
+        if (Math.abs(length - 1) > resolved.angular)
+            throw new GeometryError("INVALID_ARGUMENT", "Frame axes must have unit length.");
+        if (length <= resolved.linear)
+            throw new GeometryError("DEGENERATE_GEOMETRY", "Frame axes must have non-zero length.");
+        value[0] /= length;
+        value[1] /= length;
+        value[2] /= length;
+        return value;
+    };
+    const xAxis = axis(options.xAxis);
+    const yAxis = axis(options.yAxis);
+    const zAxis = axis(options.zAxis);
+    if (Math.abs(dot3(xAxis, yAxis)) > resolved.angular ||
+        Math.abs(dot3(xAxis, zAxis)) > resolved.angular ||
+        Math.abs(dot3(yAxis, zAxis)) > resolved.angular ||
+        dot3(cross3(xAxis, yAxis), zAxis) < 1 - resolved.angular)
+        throw new GeometryError("INVALID_ARGUMENT", "Frame axes must be right-handed and mutually orthogonal.");
+    return { origin, xAxis, yAxis, zAxis };
+}
+/**
+ * Creates a copied, deeply frozen plain coordinate frame in world space.
+ * Axes must be right-handed, unit length, and mutually orthogonal. Only accepted numerical
+ * roundoff is normalized; scale, shear, reflection, and materially invalid bases reject.
+ * Frames are placement inputs; use transform3(frame) when affine methods are needed.
+ *
+ * @example Place an XY profile using an analytic radial frame
+ * ```ts
+ * const radial = frame3({
+ *   origin: [20, 0, 5],
+ *   xAxis: [0, 1, 0],
+ *   yAxis: [0, 0, 1],
+ *   zAxis: [1, 0, 0],
+ * });
+ * const placed = transform3(radial).applyPoint([2, 3, 0]).toData(); // [20, 2, 8]
+ * ```
+ */
+export function frame3(options) {
+    const frame = resolveFrame3(options);
+    Object.freeze(frame.origin);
+    Object.freeze(frame.xAxis);
+    Object.freeze(frame.yAxis);
+    Object.freeze(frame.zAxis);
+    return Object.freeze(frame);
+}

package/dist/geometry/{transform-matrix.js → transforms/matrix-input.js}

@@ -1,10 +1,17 @@
-import { GeometryError } from "./errors.js";
+import { GeometryError } from "../errors.js";
+import { frameTransform3 } from "./affine3.js";
+/** @internal Recognizes frame-shaped data after giving callable toData values precedence. */
+export function isFrame3Input(input) {
+    return typeof input === "object" && input !== null && !Array.isArray(input) && "origin" in input;
+}
 export function readTransformMatrix(input, dimension) {
     let matrix = input;
     if (typeof input === "object" && input !== null && !Array.isArray(input)) {
         const method = Reflect.get(input, "toData");
         if (typeof method === "function")
             matrix = Reflect.apply(method, input, []);
+        else if (dimension === 3 && isFrame3Input(input))
+            matrix = frameTransform3(input);
     }
     const length = dimension === 2 ? 9 : 16;
     if (!Array.isArray(matrix) || matrix.length !== length) {

package/dist/geometry/{transform-value.js → transforms/value.js}

@@ -1,12 +1,12 @@
-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";
+import { GeometryError } from "../errors.js";
+import { immutableMathClass } from "../math/immutable-value.js";
+import { vector2, vector2Data, vector3, vector3Data, } from "../math/vector-value.js";
+import { applyInverseTranspose3, applyValidatedTransformDirection3, applyValidatedTransformPoint3, eulerTransform3, IDENTITY_TRANSFORM3, inverseLinearTransform3, inverseTransform3, multiplyTransform3, rotationTransform3, scaleTransform3, translationTransform3, validateTransform3, } from "./affine3.js";
+import { embedTransform2, restrictTransform3 } from "./dimensions.js";
+import { readTransformMatrix } from "./matrix-input.js";
 const pivotTransform = (matrix, pivot) => pivot === undefined
     ? matrix
-    : composeTransform3(translationTransform3(pivot), composeTransform3(matrix, translationTransform3([-pivot[0], -pivot[1], -pivot[2]])));
+    : multiplyTransform3(translationTransform3(pivot), multiplyTransform3(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) => {
@@ -75,7 +75,7 @@ const Placement3 = /* @__PURE__ */ immutableMathClass(class Placement3 {
         return this.andThen(pivotTransform(scaleTransform3(values), pivot3(options)));
     }
     andThen(next) {
-        return new Placement3(composeTransform3(snapshotTransform3(readTransformMatrix(next, 3)), this.matrix));
+        return new Placement3(multiplyTransform3(snapshotTransform3(readTransformMatrix(next, 3)), this.matrix));
     }
     inverse() {
         return new Placement3(inverseTransform3(this.matrix));
@@ -148,6 +148,8 @@ const Placement2 = /* @__PURE__ */ immutableMathClass(class Placement2 {
  *
  * Use `toData()` for frozen matrix interchange.
  *
+ * @param input - XY affine value or row-major 3x3 matrix; copied. Defaults to identity.
+ *
  * @example
  * ```ts
  * const placement = transform2().rotate(90).translate([10, 0]);
@@ -162,19 +164,35 @@ export function transform2(input) {
 /**
  * Creates an immutable XYZ transform, identity by default.
  *
- * Values and data are copied and validated.
+ * Values, matrices, and frames 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.
+ * A frame supplies its origin in millimetres and right-handed orthonormal axes as local-to-world
+ * columns. Invalid axes reject; unit-length roundoff is normalized within geometry tolerance.
  *
  * Use `toData()` for frozen matrix interchange.
- * [composeTransform3](/docs/reference/geometry/composeTransform3) takes matrices in after, before order.
+ * [multiplyTransform3](/docs/reference/math/multiplyTransform3) multiplies left and right matrices;
+ * the right factor acts first on column vectors.
+ *
+ * @param input - XYZ affine value, row-major 4x4 matrix, or frame; copied. Defaults to identity.
  *
  * @example
  * ```ts
  * const placement = transform3().rotate([0, 0, 90]).translate([10, 0, 0]);
  * placement.applyPoint([1, 0, 0]).toData(); // approximately [10, 1, 0]
  * ```
+ *
+ * @example Convert a coordinate frame to an affine value
+ * ```ts
+ * const local = frame3({
+ *   origin: [10, 0, 0],
+ *   xAxis: [0, 1, 0],
+ *   yAxis: [-1, 0, 0],
+ *   zAxis: [0, 0, 1],
+ * });
+ * const placement = transform3(local);
+ * placement.applyPoint([2, 0, 0]).toData(); // [10, 2, 0]
+ * ```
  */
 export function transform3(input = IDENTITY_TRANSFORM3) {
     return new Placement3(snapshotTransform3(readTransformMatrix(input, 3)));

package/dist/index.js

@@ -1,9 +1,3 @@
-/** Immutable modeling recipes and math values; the host owns geometry evaluation. @packageDocumentation */
-export { GeometryError, isGeometryError, } from "./geometry/errors.js";
-export { bounds2, bounds3, } from "./geometry/bounds-value.js";
-export { transform2, transform3, } from "./geometry/transform-value.js";
-export { vector2, vector3, } from "./geometry/math/vector-value.js";
-export { path2, path3, } from "./geometry/paths/path-value.js";
-export * from "./model/operations.js";
-export * from "./model/generation.js";
-export { immutableBuffer } from "./geometry/immutable-buffer.js";
+/** Immutable solid and section recipes; the host owns geometry evaluation. @packageDocumentation */
+export { box, circle, cornerCutter, cylinder, edgeCutter, ellipse, extrude, gridPattern, heightfield, holeCutter, hull, implicit, internalThreadCutter, intersect, join, knuckleHinge, linearPattern, loft, minkowskiSum, pathPattern, polygon, radialPattern, rectangle, regularPolygon, revolve, solidFromMesh, sphere, star, stroke, svgPathSection, svgSection, sweep, textSection, threadRidge, threadedNut, threadedRod, torus, tube, union, } from "./model/operations.js";
+export { generate, GenerationError } from "./model/generation.js";

package/dist/model/cutters.js

@@ -0,0 +1 @@
+export {};

package/dist/model/execution-binding.js

@@ -1,7 +1,7 @@
 import { GeometryError } from "../geometry/errors.js";
 // One protocol key lets locally bundled operation wrappers resolve the host's execution
 // without depending on package instances, class identity, or initializing a native runtime.
-const executionKey = Symbol.for("@metamesh/modeling/execution/12");
+const executionKey = Symbol.for("@metamesh/modeling/execution/13");
 const bindings = globalThis;
 /** Internal host binding. Executable callbacks are synchronous and may not nest executions. */
 export function bindModelContext(context, build) {
@@ -10,7 +10,7 @@ export function bindModelContext(context, build) {
             operation: "build",
         });
     }
-    bindings[executionKey] = { version: 12, context };
+    bindings[executionKey] = { version: 13, context };
     try {
         return build();
     }
@@ -31,5 +31,5 @@ export function currentModelContext(operation) {
 /** Reads an optional binding without initializing an engine or creating ambient authoring state. */
 export function activeModelContext() {
     const binding = bindings[executionKey];
-    return binding?.version === 12 ? binding.context : undefined;
+    return binding?.version === 13 ? binding.context : undefined;
 }

package/dist/model/generation.js

@@ -18,6 +18,8 @@ export class GenerationError extends Error {
  * runtime capture rejects arrays at the root, ordinary class instances, mutable buffers, and functions.
  * Supply live capabilities through services. Use `memo` only for work worth reusing.
  *
+ * @param callback - Synchronous callback returning one part or a readonly part array.
+ *
  * @example A simple model
  * ```ts
  * const model = generate<{ height: number }>(({ params, part, assert }) => {