@metamesh/modeling 0.12.0 → 0.14.0

package/dist/geometry/tolerance.js

@@ -18,8 +18,8 @@ const positiveFinite = (value, label) => {
  * Resolves comparison tolerances for a characteristic model scale.
  *
  * The effective linear tolerance is `max(absolute, relative * abs(scale))`.
- * Supplying a scale of zero therefore retains the absolute floor. The function
- * returns a new frozen value with finite distance and area thresholds and never mutates `options`.
+ * A zero scale retains the absolute floor. Returns a new frozen value with finite distance and
+ * area thresholds without mutating `options`.
  *
  * @param scale - Finite characteristic size in model units.
  * @param options - Optional policy overrides.

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,45 @@
-import { GeometryError } from "./errors.js";
-import { normalizeLoop2, normalizeRegion2, signedAreaLoop2 } from "./regions.js";
-import { resolveGeometryTolerance } from "./tolerance.js";
-import { applyTransformPoint3, validateTransform3 } from "./transform3.js";
+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";
 /** Applies an affine transform to a 3D path without mutating its points. */
-export function transformPath3(path, transform) {
+export function transformPath3(path, placement) {
+    const transform = readTransformMatrix(placement, 3);
     validateTransform3(transform);
-    return Object.freeze(path.map((point) => Object.freeze(applyTransformPoint3(transform, point))));
+    return Object.freeze(path.map((point) => Object.freeze(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",
-        });
-    }
+const transformPoint2 = (point, transform) => {
+    const values = vector2Data(point);
+    const transformed = applyValidatedTransformPoint3(transform, [values[0], values[1], 0]);
     return Object.freeze([transformed[0], transformed[1]]);
 };
-/** Applies an XY-plane-preserving affine transform to a 2D path. */
+const transformPlanarPath = (path, transform) => Object.freeze(path.map((point) => transformPoint2(point, transform)));
+/** Applies a canonical affine XY transform to a 2D path without changing point order. */
 export function transformPath2(path, transform, tolerance = {}) {
-    validateTransform3(transform, tolerance);
-    return Object.freeze(path.map((point) => transformPoint2(point, transform, tolerance)));
+    return transformPlanarPath(path, embedTransform2(readTransformMatrix(transform, 2), tolerance));
 }
+const transformContourWithMatrix = (loop, transform, tolerance) => {
+    const counterClockwise = signedContourArea(loop) > 0;
+    const normalized = normalizeContour(loop, counterClockwise, tolerance);
+    return normalizeContour(transformPlanarPath(normalized, transform), counterClockwise, tolerance);
+};
 /**
- * Transforms a closed loop and preserves its original winding convention.
+ * Applies a canonical affine XY transform to a closed loop and preserves its original winding.
  *
  * Reflections reverse the point order automatically through normalization.
  */
-export function transformLoop2(loop, transform, tolerance = {}) {
-    const counterClockwise = signedAreaLoop2(loop) > 0;
-    const normalized = normalizeLoop2(loop, counterClockwise, tolerance);
-    return normalizeLoop2(transformPath2(normalized, transform, tolerance), counterClockwise, tolerance);
+export function transformContour(loop, transform, tolerance = {}) {
+    return transformContourWithMatrix(loop, embedTransform2(readTransformMatrix(transform, 2), tolerance), tolerance);
 }
-/** Transforms an explicit outer/hole region with reflection-safe winding correction. */
-export function transformRegion2(region, transform, tolerance = {}) {
-    return normalizeRegion2(region.map((polygon) => ({
-        holes: polygon.holes.map((hole) => transformLoop2(hole, transform, tolerance)),
-        outer: transformLoop2(polygon.outer, 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.
+ */
+export function transformRegionData(region, transform, tolerance = {}) {
+    const planar = embedTransform2(readTransformMatrix(transform, 2), tolerance);
+    return normalizeRegion(region.map((polygon) => ({
+        holes: polygon.holes.map((hole) => transformContourWithMatrix(hole, planar, tolerance)),
+        outer: transformContourWithMatrix(polygon.outer, planar, tolerance),
     })), tolerance);
 }

package/dist/geometry/transform-matrix.js

@@ -0,0 +1,14 @@
+import { GeometryError } from "./errors.js";
+export function readTransformMatrix(input, dimension) {
+    let matrix = input;
+    if (typeof input === "object" && input !== null && !Array.isArray(input)) {
+        const method = Reflect.get(input, "toMatrix");
+        if (typeof method === "function")
+            matrix = Reflect.apply(method, input, []);
+    }
+    const length = dimension === 2 ? 9 : 16;
+    if (!Array.isArray(matrix) || matrix.length !== length) {
+        throw new GeometryError("INVALID_ARGUMENT", `A ${dimension}D placement requires a canonical ${length}-element matrix.`);
+    }
+    return matrix;
+}

package/dist/geometry/transform2.js

@@ -0,0 +1,60 @@
+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([
+        matrix[0],
+        matrix[1],
+        0,
+        matrix[2],
+        matrix[3],
+        matrix[4],
+        0,
+        matrix[5],
+        0,
+        0,
+        1,
+        0,
+        0,
+        0,
+        0,
+        1,
+    ], options));
+}
+/** Restricts an affine XYZ matrix to XY; validates the plane independently of sampled points. */
+export function restrictTransform3(matrix, options = {}) {
+    validateTransform3(matrix, options);
+    const tolerance = resolveGeometryTolerance(1, options);
+    if (Math.abs(matrix[8]) > tolerance.angular ||
+        Math.abs(matrix[9]) > tolerance.angular ||
+        Math.abs(matrix[11]) > tolerance.linear) {
+        throw new GeometryError("INVALID_ARGUMENT", "A 2D transform must preserve the XY plane.");
+    }
+    const result = [
+        matrix[0],
+        matrix[1],
+        matrix[3],
+        matrix[4],
+        matrix[5],
+        matrix[7],
+        0,
+        0,
+        1,
+    ];
+    // Restriction can be singular even when the tolerated 3D matrix is invertible.
+    embedTransform2(result, options);
+    return Object.freeze(result);
+}

package/dist/geometry/transform3.js

@@ -1,20 +1,17 @@
 import { GeometryError } from "./errors.js";
+import { cross3, dot3, length3, normalize3 } from "./math/vector3.js";
 import { resolveGeometryTolerance } from "./tolerance.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.`);
     }
 };
-const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
-const cross = (a, b) => [
-    a[1] * b[2] - a[2] * b[1],
-    a[2] * b[0] - a[0] * b[2],
-    a[0] * b[1] - a[1] * b[0],
-];
-const length = (vector) => Math.hypot(vector[0], vector[1], vector[2]);
 const normalized = (vector, label, tolerance) => {
     finiteVector(vector, label);
-    const magnitude = length(vector);
+    const magnitude = length3(vector);
     if (magnitude <= tolerance) {
         throw new GeometryError("DEGENERATE_GEOMETRY", `${label} must have non-zero length.`);
     }
@@ -34,7 +31,10 @@ export const IDENTITY_TRANSFORM3 = frozenTransform([
  * @throws {@link GeometryError} For non-finite, non-affine, or singular matrices.
  */
 export function validateTransform3(transform, tolerance = {}) {
-    if (transform.length !== 16 || !transform.every(Number.isFinite)) {
+    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.");
     }
     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]));
@@ -120,7 +120,12 @@ export function rotationTransform3(axis, angle, tolerance = {}) {
     if (!Number.isFinite(radians)) {
         throw new GeometryError("NON_FINITE_VALUE", "Rotation angle must be finite.");
     }
-    const resolved = resolveGeometryTolerance(length(axis), tolerance);
+    finiteVector(axis, "Rotation axis");
+    const axisLength = length3(axis);
+    if (!Number.isFinite(axisLength)) {
+        throw new GeometryError("NON_FINITE_VALUE", "Rotation axis length must be finite.");
+    }
+    const resolved = resolveGeometryTolerance(axisLength, tolerance);
     const [x, y, z] = normalized(axis, "Rotation axis", resolved.linear);
     const cosine = Math.cos(radians);
     const sine = Math.sin(radians);
@@ -156,10 +161,7 @@ export function rotationTransform3(axis, angle, tolerance = {}) {
  */
 export function eulerTransform3(rotationDegrees) {
     finiteVector(rotationDegrees, "Euler rotation");
-    const x = (rotationDegrees[0] * Math.PI) / 180;
-    const y = (rotationDegrees[1] * Math.PI) / 180;
-    const z = (rotationDegrees[2] * Math.PI) / 180;
-    return composeTransform3(rotationTransform3([0, 0, 1], { radians: z }), composeTransform3(rotationTransform3([0, 1, 0], { radians: y }), rotationTransform3([1, 0, 0], { radians: x })));
+    return composeTransform3(rotationTransform3([0, 0, 1], { degrees: rotationDegrees[2] }), composeTransform3(rotationTransform3([0, 1, 0], { degrees: rotationDegrees[1] }), rotationTransform3([1, 0, 0], { degrees: rotationDegrees[0] })));
 }
 /**
  * Composes two affine transforms without mutating either matrix.
@@ -196,12 +198,18 @@ export function composeTransform3(after, before) {
  */
 export function applyTransformPoint3(transform, point) {
     validateTransform3(transform);
+    return applyValidatedTransformPoint3(transform, point);
+}
+/** Internal application kernel for a matrix already validated by its collection or immutable chain. */
+export function applyValidatedTransformPoint3(transform, point) {
     finiteVector(point, "Point");
-    return [
+    const result = [
         transform[0] * point[0] + transform[1] * point[1] + transform[2] * point[2] + transform[3],
         transform[4] * point[0] + transform[5] * point[1] + transform[6] * point[2] + transform[7],
         transform[8] * point[0] + transform[9] * point[1] + transform[10] * point[2] + transform[11],
     ];
+    finiteVector(result, "Transformed point");
+    return result;
 }
 /**
  * Applies only the linear component of an affine transform to a direction.
@@ -214,12 +222,18 @@ export function applyTransformPoint3(transform, point) {
  */
 export function applyTransformDirection3(transform, direction) {
     validateTransform3(transform);
+    return applyValidatedTransformDirection3(transform, direction);
+}
+/** Internal application kernel for a matrix already validated by an immutable chain. */
+export function applyValidatedTransformDirection3(transform, direction) {
     finiteVector(direction, "Direction");
-    return [
+    const result = [
         transform[0] * direction[0] + transform[1] * direction[1] + transform[2] * direction[2],
         transform[4] * direction[0] + transform[5] * direction[1] + transform[6] * direction[2],
         transform[8] * direction[0] + transform[9] * direction[1] + transform[10] * direction[2],
     ];
+    finiteVector(result, "Transformed direction");
+    return result;
 }
 /**
  * Returns the determinant of a transform's linear 3x3 component.
@@ -266,9 +280,9 @@ export function inverseTransform3(transform) {
     ];
     const translation = [transform[3], transform[7], transform[11]];
     const inverseTranslation = [
-        -dot([inverseLinear[0], inverseLinear[1], inverseLinear[2]], translation),
-        -dot([inverseLinear[3], inverseLinear[4], inverseLinear[5]], translation),
-        -dot([inverseLinear[6], inverseLinear[7], inverseLinear[8]], translation),
+        -dot3([inverseLinear[0], inverseLinear[1], inverseLinear[2]], translation),
+        -dot3([inverseLinear[3], inverseLinear[4], inverseLinear[5]], translation),
+        -dot3([inverseLinear[6], inverseLinear[7], inverseLinear[8]], translation),
     ];
     const inverse = frozenTransform([
         inverseLinear[0],
@@ -291,6 +305,36 @@ export function inverseTransform3(transform) {
     validateTransform3(inverse);
     return inverse;
 }
+/** Internal inverse linear map; translation cannot affect normals or overflow their inverse. */
+export function inverseLinearTransform3(matrix) {
+    return inverseTransform3([
+        matrix[0],
+        matrix[1],
+        matrix[2],
+        0,
+        matrix[4],
+        matrix[5],
+        matrix[6],
+        0,
+        matrix[8],
+        matrix[9],
+        matrix[10],
+        0,
+        0,
+        0,
+        0,
+        1,
+    ]);
+}
+/** Internal unit normal application for a validated inverse linear transform. */
+export function applyInverseTranspose3(inverse, normal) {
+    const unit = normalize3(normal, 0);
+    return normalize3([
+        inverse[0] * unit[0] + inverse[4] * unit[1] + inverse[8] * unit[2],
+        inverse[1] * unit[0] + inverse[5] * unit[1] + inverse[9] * unit[2],
+        inverse[2] * unit[0] + inverse[6] * unit[1] + inverse[10] * unit[2],
+    ], 0);
+}
 /**
  * Converts a right-handed orthonormal frame into a local-to-world transform.
  *
@@ -302,9 +346,9 @@ export function inverseTransform3(transform) {
 export function frameTransform3(frame, tolerance = {}) {
     finiteVector(frame.origin, "Frame origin");
     const resolved = resolveGeometryTolerance(1, tolerance);
-    const xLength = length(frame.xAxis);
-    const yLength = length(frame.yAxis);
-    const zLength = length(frame.zAxis);
+    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) {
@@ -313,10 +357,10 @@ export function frameTransform3(frame, tolerance = {}) {
     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(dot(x, y)) > resolved.angular ||
-        Math.abs(dot(x, z)) > resolved.angular ||
-        Math.abs(dot(y, z)) > resolved.angular ||
-        dot(cross(x, y), z) < 1 - resolved.angular) {
+    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.");
     }
     return frozenTransform([

package/dist/index.js

@@ -1,3 +1,6 @@
+/** Immutable modeling recipes and math values; the host owns geometry evaluation. @packageDocumentation */
+export { transform2, transform3, } from "./geometry/transform-chain.js";
+export { vector2, vector3, } from "./geometry/math/vector-value.js";
 export * from "./model/operations.js";
 export * from "./model/generation.js";
 export { immutableBuffer, immutableMesh } from "./model/immutable-buffer.js";

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/4");
+const executionKey = Symbol.for("@metamesh/modeling/execution/6");
 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: 4, context };
+    bindings[executionKey] = { version: 6, context };
     try {
         return build();
     }
@@ -20,11 +20,16 @@ export function bindModelContext(context, build) {
 }
 /** Resolves the private realm protocol; imported functions carry no native state themselves. */
 export function currentModelContext(operation) {
-    const binding = bindings[executionKey];
-    if (binding?.version !== 4) {
+    const context = activeModelContext();
+    if (context === undefined) {
         throw new GeometryError("INVALID_ARGUMENT", "Modeling functions can only run inside generate().", {
             operation,
         });
     }
-    return binding.context;
+    return context;
+}
+/** Reads an optional binding without initializing an engine or creating ambient authoring state. */
+export function activeModelContext() {
+    const binding = bindings[executionKey];
+    return binding?.version === 6 ? binding.context : undefined;
 }

package/dist/model/generation.js

@@ -16,7 +16,7 @@ export class GenerationError extends Error {
  * ```ts
  * const model = generate<{ height: number }>(({ params, part, assert }) => {
  *   assert(params.height > 0, "Height must be positive.");
- *   return [part("body", box({ size: [10, 10, params.height] }))];
+ *   return part("body", box({ size: [10, 10, params.height] }));
  * });
  * ```
  */

package/dist/model/geometry-recipes.js

@@ -0,0 +1,15 @@
+import { createSectionHandle, createSolidHandle } from "./shape-handles.js";
+// One realm protocol lets bundled authoring code declare recipes before a host is initialized.
+// The payload contains no native handles and the engine remains responsible for realization.
+const recipeKey = Symbol.for("@metamesh/modeling/recipe/6");
+/** Reads private recipe metadata without requiring an execution context. */
+export const geometryRecipe = (value) => Object.getOwnPropertyDescriptor(value, recipeKey)?.value;
+/** Recognizes only opaque recipe handles issued by this engine. */
+export const isGeometryRecipe = (value) => typeof value === "object" && value !== null && geometryRecipe(value) !== undefined;
+/** Creates an immutable opaque handle for a recorded operation. */
+export function recordGeometryRecipe(recipe, dispatch) {
+    const metadata = Object.freeze({ ...recipe, call: Object.freeze(recipe.call) });
+    return recipe.kind === "solid"
+        ? createSolidHandle(dispatch, { [recipeKey]: { value: metadata } })
+        : createSectionHandle(dispatch, { [recipeKey]: { value: metadata } });
+}

package/dist/{engine → model}/immutable-generation-data.js

@@ -1,6 +1,7 @@
 import { GeometryError } from "../geometry/errors.js";
-import { adoptImmutableBuffer, immutableBuffer, immutableBufferView, isImmutableBuffer, } from "../model/immutable-buffer.js";
+import { isImmutableMathValue } from "../geometry/math/immutable-value.js";
 import { geometryRecipe, isGeometryRecipe } from "./geometry-recipes.js";
+import { adoptImmutableBuffer, immutableBuffer, immutableBufferView, isImmutableBuffer, } from "./immutable-buffer.js";
 const mutableBufferMessage = "Generation data cannot contain mutable typed arrays or raw ArrayBuffers. Use immutableBuffer(array) or immutableMesh(mesh) before caching them or declaring dependencies.";
 /** Iterates plain fields; recipe capture may read each enumerable accessor once. */
 export function* generationDataEntries(value, captureAccessors = false) {
@@ -44,6 +45,11 @@ export function generationValueBytes(values, ceiling) {
         if (seen.has(value))
             return;
         seen.add(value);
+        if (isImmutableMathValue(value)) {
+            bytes += 32;
+            visit(mathValueData(value), depth + 1);
+            return;
+        }
         const array = isImmutableBuffer(value)
             ? immutableBufferView(value)
             : ArrayBuffer.isView(value)
@@ -91,11 +97,16 @@ export function compareGenerationValues(left, right) {
         const matches = visited.get(a) ?? new Set();
         matches.add(b);
         visited.set(a, matches);
+        if (isImmutableMathValue(a) || isImmutableMathValue(b)) {
+            return isImmutableMathValue(a) && isImmutableMathValue(b)
+                ? compare(mathValueData(a), mathValueData(b), depth + 1)
+                : "different";
+        }
         const recipeA = geometryRecipe(a), recipeB = geometryRecipe(b);
         if (recipeA !== undefined || recipeB !== undefined) {
             if (recipeA === undefined ||
                 recipeB === undefined ||
-                recipeA.owner !== recipeB.owner ||
+                recipeA.observedSession !== recipeB.observedSession ||
                 recipeA.kind !== recipeB.kind ||
                 recipeA.call.method !== recipeB.call.method ||
                 recipeA.index !== recipeB.index)
@@ -144,13 +155,24 @@ export function compareGenerationValues(left, right) {
     };
     return compare(left, right);
 }
+function mathValueData(value) {
+    for (const name of ["toArray", "toMatrix"]) {
+        const method = Reflect.get(value, name);
+        if (typeof method === "function")
+            return Reflect.apply(method, value, []);
+    }
+    throw new TypeError("Immutable math values must expose their canonical numeric data.");
+}
 function captureValue(value, mode, readerAllowed = () => false, validated) {
     const recipeInputs = mode === "recipe";
     const seen = new Map();
     const copy = (input) => {
         if (typeof input === "function" && !recipeInputs && !readerAllowed(input))
             throw new GeometryError("INVALID_ARGUMENT", "Computed values and dependencies cannot contain arbitrary function closures.", { operation: "computed" });
-        if (typeof input !== "object" || input === null || isGeometryRecipe(input))
+        if (typeof input !== "object" ||
+            input === null ||
+            isGeometryRecipe(input) ||
+            isImmutableMathValue(input))
             return input;
         if (isImmutableBuffer(input))
             return adoptImmutableBuffer(input);

package/dist/model/operation-contracts.js

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