@metamesh/modeling 0.13.0 → 0.15.0

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,7 @@
+/** 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 { path2, path3, } from "./geometry/paths/path-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/5");
+const executionKey = Symbol.for("@metamesh/modeling/execution/7");
 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: 5, context };
+    bindings[executionKey] = { version: 7, 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 !== 5) {
+    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 === 7 ? binding.context : undefined;
 }

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/7");
+/** 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,7 +1,15 @@
 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.";
+const capturedMetadata = new WeakMap();
+const noChildren = Object.freeze([]);
+/** Reuses field accounting only for containers captured or deeply validated by this owner. */
+export function generationDataMetadata(value) {
+    return capturedMetadata.get(value);
+}
+const scalarBytes = (value) => (typeof value === "string" ? value.length * 2 : 8);
 /** Iterates plain fields; recipe capture may read each enumerable accessor once. */
 export function* generationDataEntries(value, captureAccessors = false) {
     const prototype = Object.getPrototypeOf(value);
@@ -44,6 +52,33 @@ export function generationValueBytes(values, ceiling) {
         if (seen.has(value))
             return;
         seen.add(value);
+        const metadata = capturedMetadata.get(value);
+        if (metadata !== undefined) {
+            if (depth === 128 && metadata.bytes > 0) {
+                bytes = Infinity;
+                return;
+            }
+            bytes += 32 + metadata.bytes;
+            for (const child of metadata.children)
+                visit(child, depth + 1);
+            return;
+        }
+        if (isImmutableMathValue(value)) {
+            bytes += 32;
+            const data = mathValueData(value);
+            visit(data, depth + 1);
+            if (typeof data === "object" &&
+                data !== null &&
+                "dimension" in data &&
+                (data.dimension === 2 || data.dimension === 3) &&
+                "points" in data &&
+                Array.isArray(data.points)) {
+                // A path retains private numerical tuples as well as its frozen interchange view.
+                // Charge both stores conservatively; the outer seen set still counts value aliases once.
+                bytes += 64 + data.points.length * (40 + 8 * data.dimension);
+            }
+            return;
+        }
         const array = isImmutableBuffer(value)
             ? immutableBufferView(value)
             : ArrayBuffer.isView(value)
@@ -91,11 +126,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 +184,31 @@ 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") {
+            const data = Reflect.apply(method, value, []);
+            // Closure and dimension change path behavior; tuple interchange omits both for empty paths.
+            const closed = Reflect.get(value, "closed");
+            return typeof closed === "boolean"
+                ? { dimension: Reflect.get(value, "dimension"), points: data, closed }
+                : data;
+        }
+    }
+    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 metadata = 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);
@@ -169,20 +227,42 @@ function captureValue(value, mode, readerAllowed = () => false, validated) {
         if (input instanceof ArrayBuffer)
             throw new TypeError(mutableBufferMessage);
         const entries = generationDataEntries(input, recipeInputs);
+        let bytes = 0;
+        const children = [];
+        const recordField = (key, field) => {
+            bytes += 16 + key.length * 2;
+            if (typeof field === "object" && field !== null)
+                children.push(field);
+            else
+                bytes += scalarBytes(field);
+        };
         if (mode === "dependency") {
             if (!Object.isFrozen(input))
                 throw new GeometryError("INVALID_ARGUMENT", "Computed dependencies require deeply immutable objects and arrays. Read params inside the callback, use a computed value, or depend on individual scalar values.", { operation: "computed" });
             seen.set(input, input);
-            for (const [, field] of entries)
+            for (const [key, field] of entries) {
                 copy(field);
+                recordField(key, field);
+            }
+            metadata.set(input, {
+                bytes,
+                children: children.length ? Object.freeze(children) : noChildren,
+            });
             return input;
         }
         const result = Array.isArray(input)
             ? new Array(input.length)
             : Object.create(Object.getPrototypeOf(input) === null ? null : Object.prototype);
         seen.set(input, result);
-        for (const [key, field] of entries)
-            Object.defineProperty(result, key, { value: copy(field), enumerable: true });
+        for (const [key, field] of entries) {
+            const value = copy(field);
+            Object.defineProperty(result, key, { value, enumerable: true });
+            recordField(key, value);
+        }
+        metadata.set(result, {
+            bytes,
+            children: children.length ? Object.freeze(children) : noChildren,
+        });
         return Object.freeze(result);
     };
     const result = copy(value);
@@ -190,6 +270,8 @@ function captureValue(value, mode, readerAllowed = () => false, validated) {
     if (mode === "dependency")
         for (const input of seen.keys())
             validated?.add(input);
+    for (const [value, entry] of metadata)
+        capturedMetadata.set(value, entry);
     return result;
 }
 /** Validates while capturing immutable data; only explicitly allowed session readers may be functions. */

package/dist/model/operation-dispatch.js

@@ -1,6 +1,13 @@
-import { currentModelContext } from "./execution-binding.js";
+import { activeModelContext } from "./execution-binding.js";
+import { declarePortableOperation } from "./recipe-declaration.js";
 /** Resolves a typed operation for this execution without retaining the host context. */
 export function invokeModelOperation(name, args) {
-    const context = currentModelContext(name);
-    return Reflect.apply(context[name], undefined, args);
+    return dispatchModelOperation(name, args);
+}
+/** Shared facade dispatcher; portable declaration and execution use the same operation contract. */
+export function dispatchModelOperation(name, args) {
+    const context = activeModelContext();
+    return context === undefined
+        ? declarePortableOperation(name, args, dispatchModelOperation)
+        : Reflect.apply(context[name], undefined, args);
 }