@metamesh/modeling 0.15.0 → 0.17.0

package/dist/geometry/svg/matrix.js

@@ -1,3 +1,4 @@
+import { invalid } from "./errors.js";
 export function multiplyMatrices(left, right) {
     return [
         left[0] * right[0] + left[2] * right[1],
@@ -14,3 +15,23 @@ export function transformPoint(matrix, point) {
         matrix[1] * point[0] + matrix[3] * point[1] + matrix[5],
     ];
 }
+/** Inverts an affine map after checking relative linear conditioning, independent of unit scale. */
+export function inverseMatrix(matrix, operation) {
+    const scale = Math.max(...matrix.slice(0, 4).map(Math.abs));
+    const [a, b, c, d] = matrix.slice(0, 4).map((value) => value / scale);
+    const determinant = a * d - b * c;
+    if (!Number.isFinite(determinant) || Math.abs(determinant) <= 1e-15)
+        invalid(operation, "SVG geometry transforms must be non-singular.");
+    const divisor = determinant * scale;
+    const result = [
+        d / divisor,
+        -b / divisor,
+        -c / divisor,
+        a / divisor,
+        (c * matrix[5] - d * matrix[4]) / divisor,
+        (b * matrix[4] - a * matrix[5]) / divisor,
+    ];
+    if (!result.every(Number.isFinite))
+        invalid(operation, "SVG inverse transform must be finite.");
+    return result;
+}

package/dist/geometry/svg-import.js

@@ -1,16 +1,20 @@
 import { SaxesParser } from "saxes";
+import { SVGPathData } from "svg-pathdata";
+import { bounds2 } from "./bounds-value.js";
+import { fitBounds } from "./bounds.js";
 import { GeometryError } from "./errors.js";
 import { regionArea, signedContourArea } from "./regions.js";
 import { resolveCircularSegments, resolveGeometryResolution, } from "./resolution.js";
 import { resolveGeometrySamplingLimits } from "./sampling-limits.js";
 import { strokePathMultiPolygon } from "./stroke-path.js";
 import { createBoundedSvgClipping } from "./svg/fill.js";
-import { multiplyMatrices as multiply, transformPoint } from "./svg/matrix.js";
+import { inverseMatrix, multiplyMatrices as multiply, transformPoint } from "./svg/matrix.js";
 import { flattenSvgSubpaths, SvgVertexBudget } from "./svg/path.js";
 const MAX_SVG_BYTES = 256 * 1024;
 const MAX_SVG_ELEMENTS = 500;
 const MAX_SVG_NESTING_DEPTH = 64;
 const MAX_SVG_NODES = 2_000;
+const MAX_SVG_FIT_PASSES = 8;
 const SHORT_EDGE_LENGTH_MM = 0.01;
 const TINY_ISLAND_AREA_MM2 = 0.01;
 const SUPPORTED_TAGS = new Set([
@@ -79,6 +83,14 @@ function complexityFail(message, details) {
         details,
     });
 }
+function svgResolution(options) {
+    return resolveGeometryResolution({
+        ...options.resolution,
+        ...(options.circularSegments === undefined
+            ? {}
+            : { circularSegments: options.circularSegments }),
+    }, options.limits);
+}
 function finite(value, fallback) {
     if (value === undefined || value.trim() === "") {
         if (fallback !== undefined)
@@ -301,31 +313,28 @@ function parsePoints(value) {
         points.push([numbers[index] ?? 0, numbers[index + 1] ?? 0]);
     return points;
 }
-function inverseMatrix(matrix) {
-    const determinant = matrix[0] * matrix[3] - matrix[1] * matrix[2];
-    if (!Number.isFinite(determinant) || Math.abs(determinant) <= 1e-15) {
-        return fail("SVG geometry transforms must be non-singular.");
-    }
-    return [
-        matrix[3] / determinant,
-        -matrix[1] / determinant,
-        -matrix[2] / determinant,
-        matrix[0] / determinant,
-        (matrix[2] * matrix[5] - matrix[3] * matrix[4]) / determinant,
-        (matrix[1] * matrix[4] - matrix[0] * matrix[5]) / determinant,
-    ];
-}
 function maximumLinearScale(matrix) {
     const trace = matrix[0] * matrix[0] + matrix[1] * matrix[1] + matrix[2] * matrix[2] + matrix[3] * matrix[3];
     const determinant = matrix[0] * matrix[3] - matrix[1] * matrix[2];
     return Math.sqrt(Math.max(0, (trace + Math.sqrt(Math.max(0, trace * trace - 4 * determinant * determinant))) / 2));
 }
-function adaptivePathSubpaths(d, transform, resolution, budget) {
+function adaptivePathSubpaths(d, transform, resolution, budget, estimate = false) {
     if (d.trim() === "")
         return fail("SVG path data is required.");
-    const inverse = inverseMatrix(transform);
+    const inverse = inverseMatrix(transform, "preflightSvgRegion");
     try {
-        return flattenSvgSubpaths(d, transform, resolution, budget, "preflightSvgRegion").map(({ closed, points }) => ({
+        let selected = resolution;
+        if (estimate) {
+            const bounds = new SVGPathData(d).getBounds();
+            const estimateError = (Math.hypot(bounds.maxX - bounds.minX, bounds.maxY - bounds.minY) *
+                maximumLinearScale(transform)) /
+                16;
+            selected = {
+                ...resolution,
+                maxChordError: estimateError || resolution.maxChordError,
+            };
+        }
+        return flattenSvgSubpaths(d, transform, selected, budget, "preflightSvgRegion").map(({ closed, points }) => ({
             closed,
             points: points.map((point) => transformPoint(inverse, point)),
         }));
@@ -336,7 +345,7 @@ function adaptivePathSubpaths(d, transform, resolution, budget) {
         return fail(error instanceof Error ? `Invalid SVG path: ${error.message}` : "Invalid SVG path data.");
     }
 }
-function elementSubpaths(tag, values, transform, resolution, budget) {
+function elementSubpaths(tag, values, transform, resolution, budget, estimate = false) {
     switch (tag) {
         case "rect": {
             const x = finite(values.x, 0);
@@ -348,11 +357,11 @@ function elementSubpaths(tag, values, transform, resolution, budget) {
             const rx = values.rx === undefined ? finite(values.ry, 0) : finite(values.rx, 0);
             const ry = values.ry === undefined ? rx : finite(values.ry, 0);
             if (rx === 0 || ry === 0) {
-                return adaptivePathSubpaths(`M${x} ${y}H${x + width}V${y + height}H${x}Z`, transform, resolution, budget);
+                return adaptivePathSubpaths(`M${x} ${y}H${x + width}V${y + height}H${x}Z`, transform, resolution, budget, estimate);
             }
             const radiusX = Math.min(Math.max(0, rx), width / 2);
             const radiusY = Math.min(Math.max(0, ry), height / 2);
-            return adaptivePathSubpaths(`M${x + radiusX} ${y}H${x + width - radiusX}A${radiusX} ${radiusY} 0 0 1 ${x + width} ${y + radiusY}V${y + height - radiusY}A${radiusX} ${radiusY} 0 0 1 ${x + width - radiusX} ${y + height}H${x + radiusX}A${radiusX} ${radiusY} 0 0 1 ${x} ${y + height - radiusY}V${y + radiusY}A${radiusX} ${radiusY} 0 0 1 ${x + radiusX} ${y}Z`, transform, resolution, budget);
+            return adaptivePathSubpaths(`M${x + radiusX} ${y}H${x + width - radiusX}A${radiusX} ${radiusY} 0 0 1 ${x + width} ${y + radiusY}V${y + height - radiusY}A${radiusX} ${radiusY} 0 0 1 ${x + width - radiusX} ${y + height}H${x + radiusX}A${radiusX} ${radiusY} 0 0 1 ${x} ${y + height - radiusY}V${y + radiusY}A${radiusX} ${radiusY} 0 0 1 ${x + radiusX} ${y}Z`, transform, resolution, budget, estimate);
         }
         case "circle": {
             const radius = finite(values.r);
@@ -376,17 +385,17 @@ function elementSubpaths(tag, values, transform, resolution, budget) {
             ];
         }
         case "line":
-            return adaptivePathSubpaths(`M${finite(values.x1, 0)} ${finite(values.y1, 0)}L${finite(values.x2, 0)} ${finite(values.y2, 0)}`, transform, resolution, budget);
+            return adaptivePathSubpaths(`M${finite(values.x1, 0)} ${finite(values.y1, 0)}L${finite(values.x2, 0)} ${finite(values.y2, 0)}`, transform, resolution, budget, estimate);
         case "polyline": {
             const points = parsePoints(values.points);
-            return adaptivePathSubpaths(points.map(([x, y], index) => `${index === 0 ? "M" : "L"}${x} ${y}`).join(""), transform, resolution, budget);
+            return adaptivePathSubpaths(points.map(([x, y], index) => `${index === 0 ? "M" : "L"}${x} ${y}`).join(""), transform, resolution, budget, estimate);
         }
         case "polygon": {
             const points = parsePoints(values.points);
-            return adaptivePathSubpaths(`${points.map(([x, y], index) => `${index === 0 ? "M" : "L"}${x} ${y}`).join("")}Z`, transform, resolution, budget);
+            return adaptivePathSubpaths(`${points.map(([x, y], index) => `${index === 0 ? "M" : "L"}${x} ${y}`).join("")}Z`, transform, resolution, budget, estimate);
         }
         case "path":
-            return adaptivePathSubpaths(values.d ?? "", transform, resolution, budget);
+            return adaptivePathSubpaths(values.d ?? "", transform, resolution, budget, estimate);
         default:
             return [];
     }
@@ -476,10 +485,10 @@ function measureSvgRegion(region) {
  *
  * @param svg - Complete SVG XML source, limited to 256 KiB of UTF-8.
  * @param options - Physical flattening and viewport-origin controls.
- * @returns The exact normalized region used for import plus bounded review metrics and repairs.
+ * @returns The normalized sampled region plus bounded review metrics and repairs.
  * @throws {@link GeometryError} When XML, supported-feature, geometry, or complexity checks fail.
  */
-function createSvgRegionPreflight(svg, options = {}) {
+function createSvgRegionPreflight(svg, options = {}, estimate = false) {
     const bytes = new TextEncoder().encode(svg).byteLength;
     if (bytes > MAX_SVG_BYTES)
         return fail("SVG geometry must be 256 KiB or smaller.");
@@ -488,15 +497,17 @@ function createSvgRegionPreflight(svg, options = {}) {
         return fail('SVG origin must be either "center" or "document".');
     }
     const limits = resolveGeometrySamplingLimits(options.limits);
-    const resolution = resolveGeometryResolution({
-        ...options.resolution,
-        ...(options.circularSegments === undefined
-            ? {}
-            : { circularSegments: options.circularSegments }),
-    }, limits);
+    const resolution = { ...svgResolution(options) };
+    // The first fitted pass estimates size using bounded, scale-relative samples. Resolving
+    // source curves at the final tolerance first would reject large documents before shrinking.
+    if (estimate) {
+        resolution.circularSegments ??= resolution.minSegments;
+        delete resolution.maxSegmentLength;
+    }
     const { assertExpandedVertexCount, boundedMultiPolygon, fillGeometry, multiPolygonVertexCount, regionFromMultiPolygon, unionAll, } = createBoundedSvgClipping(limits.maxProfilePoints);
     const stack = [];
     const geometry = [];
+    const estimateGeometry = [];
     let elementCount = 0;
     let emptyElementCount = 0;
     let expandedGeometryVertices = 0;
@@ -504,6 +515,7 @@ function createSvgRegionPreflight(svg, options = {}) {
     let invisibleElementCount = 0;
     let nodeCount = 0;
     let rootSeen = false;
+    let coordinateScale = 1;
     let strokeConstructionVertices = 0;
     const budget = new SvgVertexBudget(limits);
     const appendGeometry = (target, value, stage) => {
@@ -565,6 +577,13 @@ function createSvgRegionPreflight(svg, options = {}) {
             const width = lengthMm(values.width, viewWidth);
             const height = lengthMm(values.height, viewHeight);
             transform = multiply(canvasTransform(values, width, height, box, origin), parseTransform(values.transform));
+            if (options.fit !== undefined) {
+                // Fitted artwork has no meaningful source-unit topology tolerance. Keep sampling,
+                // stroking and clipping near a unit viewport, then compose this physical-unit scale
+                // into the final fit. Unfitted documents retain their millimetre coordinates.
+                coordinateScale = 1 / Math.max(width, height);
+                transform = multiply([coordinateScale, 0, 0, coordinateScale, 0, 0], transform);
+            }
         }
         else if (parent === undefined) {
             return fail("The SVG root element is missing.");
@@ -573,13 +592,17 @@ function createSvgRegionPreflight(svg, options = {}) {
             elementCount += 1;
             if (elementCount > MAX_SVG_ELEMENTS)
                 return fail(`SVG geometry may contain at most ${MAX_SVG_ELEMENTS} elements.`);
-            const localSubpaths = elementSubpaths(tag, values, transform, resolution, budget);
+            const localSubpaths = elementSubpaths(tag, values, transform, resolution, budget, estimate);
             const subpaths = localSubpaths.map((subpath) => ({
                 ...subpath,
                 points: subpath.points.map((point) => transformPoint(transform, point)),
             }));
             const paintedFill = isPainted(paint.fill, paint.fillOpacity);
             const paintedStroke = isPainted(paint.stroke, paint.strokeOpacity) && paint.strokeWidth > 0;
+            if (estimate && (paintedFill || paintedStroke)) {
+                for (const { points } of subpaths)
+                    estimateGeometry.push({ outer: points, holes: [] });
+            }
             const elementGeometry = [];
             if (!paintedFill && !paintedStroke)
                 invisibleElementCount += 1;
@@ -624,31 +647,96 @@ function createSvgRegionPreflight(svg, options = {}) {
     assertExpandedVertexCount(region.reduce((total, polygon) => total +
         polygon.outer.length +
         polygon.holes.reduce((holeTotal, hole) => holeTotal + hole.length, 0), 0), "normalized region");
-    return Object.freeze({
-        geometry: measureSvgRegion(region),
-        region,
-        repairs: Object.freeze({
-            emptyElementCount,
-            implicitFilledClosureCount,
-            invisibleElementCount,
-            removedDuplicateVertexCount: budget.removedDuplicateCount,
-            removedSeamVertexCount: budget.removedSeamCount,
-        }),
-        source: Object.freeze({
-            byteCount: bytes,
-            elementCount,
-            emittedVertexCount: budget.emittedCount,
-            parsedVertexCount: budget.parsedCount,
+    return [
+        Object.freeze({
+            geometry: measureSvgRegion(region),
+            region,
+            repairs: Object.freeze({
+                emptyElementCount,
+                implicitFilledClosureCount,
+                invisibleElementCount,
+                removedDuplicateVertexCount: budget.removedDuplicateCount,
+                removedSeamVertexCount: budget.removedSeamCount,
+            }),
+            source: Object.freeze({
+                byteCount: bytes,
+                elementCount,
+                emittedVertexCount: budget.emittedCount,
+                parsedVertexCount: budget.parsedCount,
+            }),
         }),
-    });
+        coordinateScale,
+        estimate && region.length === 0 ? measureSvgRegion(estimateGeometry).bounds : null,
+    ];
 }
 /**
- * Preflights bounded SVG geometry without browser or Manifold dependencies.
+ * Parses and validates bounded SVG input, constructing its normalized sampled region and diagnostics.
+ *
+ * This pure operation performs curve flattening, fill and stroke construction, and polygon union;
+ * it needs no browser or engine. Geometry counts measure the returned region at the selected
+ * resolution, rather than predicting later mesh allocation. With `fit`, painted bounds are
+ * uniformly centered inside the target and adaptive sampling remains in final millimetres.
+ * Refinement runs at most eight bounded import passes; exact circular counts retain precedence.
+ * Without `fit` the region may be empty. Tiny-island and short-edge indicators do not establish
+ * manufacturability or later solid validity.
  *
  * @param svg - Complete SVG XML source, limited to 256 KiB of UTF-8.
  * @param options - Physical flattening and viewport-origin controls.
  * @returns The canonical normalized region plus bounded source, topology, and safe-repair facts.
+ * @throws {@link GeometryError} When XML, supported-feature, geometry, or complexity checks fail.
  */
 export function preflightSvgRegion(svg, options = {}) {
-    return createSvgRegionPreflight(svg, options);
+    if (options.fit === undefined)
+        return createSvgRegionPreflight(svg, options)[0];
+    // Capture mutable caller data once; all refinement passes fit to the same finite target.
+    const target = bounds2(options.fit);
+    const resolution = svgResolution(options);
+    let samplingScale = 1;
+    for (let pass = 0; pass < MAX_SVG_FIT_PASSES; pass++) {
+        // Each pass retains the importer's source, recursion, sampling and clipping ceilings.
+        // The fixed pass cap also bounds aggregate work without consuming the final profile's
+        // allocation allowance on a discarded scale estimate.
+        const [imported, coordinateScale, estimateBounds] = createSvgRegionPreflight(svg, {
+            ...options,
+            resolution: {
+                ...resolution,
+                maxChordError: resolution.maxChordError / samplingScale,
+                ...(resolution.maxSegmentLength === undefined
+                    ? {}
+                    : { maxSegmentLength: resolution.maxSegmentLength / samplingScale }),
+            },
+        }, pass === 0);
+        // Coarse estimation can collapse a thin closed curve to a segment. Its sampled span
+        // still determines a first scale; only the verified pass may declare painted artwork empty.
+        const sourceBounds = imported.geometry.bounds ?? estimateBounds;
+        if (sourceBounds === null)
+            return fail("Cannot fit empty SVG artwork.");
+        const fit = fitBounds(sourceBounds, target);
+        if (pass > 0 && fit.scale <= samplingScale) {
+            const placement = [fit.scale, 0, 0, fit.scale, ...fit.position];
+            const transform = (loop) => Object.freeze(loop.map((point) => Object.freeze(transformPoint(placement, point))));
+            // Positive uniform fitting preserves winding and topology. Re-normalizing here would
+            // erase small fitted details. fitBounds validates transformed extrema, bounding every
+            // transformed point without repeating finite checks for each coordinate.
+            const region = Object.freeze(imported.region.map(({ outer, holes }) => Object.freeze({ outer: transform(outer), holes: Object.freeze(holes.map(transform)) })));
+            const geometry = measureSvgRegion(region);
+            if (!Number.isFinite(geometry.area))
+                return fail("Fitted SVG area is not finite.");
+            const scale = fit.scale * coordinateScale;
+            if (!(scale > 0) || !Number.isFinite(scale))
+                return fail("SVG fit scale must be finite and positive.");
+            return Object.freeze({
+                ...imported,
+                fit: Object.freeze({ ...fit, scale }),
+                geometry,
+                region,
+            });
+        }
+        // One representable relative step avoids retrying solely because a division rounded down.
+        // The next pass still verifies the actual fitted scale instead of trusting a safety factor.
+        samplingScale = fit.scale * (1 + Number.EPSILON);
+    }
+    return complexityFail("SVG fit did not converge.", {
+        maxFitPasses: MAX_SVG_FIT_PASSES,
+    });
 }

package/dist/geometry/sweeps/options.js

@@ -18,7 +18,7 @@ export function resolveSweepScales(scale, stationCount) {
     };
     if (scale === undefined ||
         typeof scale === "number" ||
-        (typeof scale === "object" && scale !== null && "toArray" in scale) ||
+        (typeof scale === "object" && scale !== null && "toData" in scale) ||
         (Array.isArray(scale) && typeof scale[0] === "number")) {
         const value = pair(scale ?? 1);
         return Array.from({ length: stationCount }, () => value);

package/dist/geometry/text-fitting.js

@@ -6,6 +6,7 @@ function fail(message) {
 }
 /**
  * Uniformly fits visible text ink inside finite XY bounds, centering it on the target.
+ *
  * Transforms retained vector paths before sampling, so later textSection/sampleTextContours
  * resolution remains in final millimetres. Logical advances scale without translation;
  * line count is unchanged. The input layout is preserved.

package/dist/geometry/transform-matrix.js

@@ -2,7 +2,7 @@ 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");
+        const method = Reflect.get(input, "toData");
         if (typeof method === "function")
             matrix = Reflect.apply(method, input, []);
     }

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

@@ -89,7 +89,7 @@ const Placement3 = /* @__PURE__ */ immutableMathClass(class Placement3 {
     applyNormal(normal) {
         return vector3(applyNormal(this, this.matrix, vector3Data(normal)));
     }
-    toMatrix() {
+    toData() {
         return this.matrix;
     }
     to2D() {
@@ -101,7 +101,7 @@ const Placement2 = /* @__PURE__ */ immutableMathClass(class Placement2 {
     matrix;
     constructor(spatial) {
         this.spatial = spatial;
-        this.matrix = restrictTransform3(spatial.toMatrix());
+        this.matrix = restrictTransform3(spatial.toData());
         Object.freeze(this);
     }
     translate(offset) {
@@ -124,15 +124,15 @@ const Placement2 = /* @__PURE__ */ immutableMathClass(class Placement2 {
         return new Placement2(this.spatial.inverse());
     }
     applyPoint(point) {
-        return vector2(xy(applyValidatedTransformPoint3(this.spatial.toMatrix(), xyz(vector2Data(point)))));
+        return vector2(xy(applyValidatedTransformPoint3(this.spatial.toData(), xyz(vector2Data(point)))));
     }
     applyDirection(direction) {
-        return vector2(xy(applyValidatedTransformDirection3(this.spatial.toMatrix(), xyz(vector2Data(direction)))));
+        return vector2(xy(applyValidatedTransformDirection3(this.spatial.toData(), xyz(vector2Data(direction)))));
     }
     applyNormal(normal) {
-        return vector2(xy(applyNormal(this, this.spatial.toMatrix(), xyz(vector2Data(normal)))));
+        return vector2(xy(applyNormal(this, this.spatial.toData(), xyz(vector2Data(normal)))));
     }
-    toMatrix() {
+    toData() {
         return this.matrix;
     }
     to3D() {
@@ -140,33 +140,42 @@ const Placement2 = /* @__PURE__ */ immutableMathClass(class Placement2 {
     }
 });
 /**
- * Creates an immutable XY transform, identity by default. Matrices are copied and validated.
+ * Creates an immutable XY transform, identity by default.
+ *
+ * Values and data 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.
  *
+ * Use `toData()` for frozen matrix interchange.
+ *
  * @example
  * ```ts
  * const placement = transform2().rotate(90).translate([10, 0]);
- * placement.applyPoint([1, 0]).toArray(); // approximately [10, 1]
+ * placement.applyPoint([1, 0]).toData(); // approximately [10, 1]
  * ```
  */
-export function transform2(matrix) {
-    return new Placement2(matrix === undefined
+export function transform2(input) {
+    return new Placement2(input === undefined
         ? new Placement3(IDENTITY_TRANSFORM3)
-        : new Placement3(embedTransform2(matrix)));
+        : new Placement3(embedTransform2(readTransformMatrix(input, 2))));
 }
 /**
- * Creates an immutable XYZ transform, identity by default. Matrices are copied and validated.
+ * Creates an immutable XYZ transform, identity by default.
+ *
+ * Values and data 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.
  *
+ * Use `toData()` for frozen matrix interchange.
+ * [composeTransform3](/docs/reference/geometry/composeTransform3) takes matrices in after, before order.
+ *
  * @example
  * ```ts
  * const placement = transform3().rotate([0, 0, 90]).translate([10, 0, 0]);
- * placement.applyPoint([1, 0, 0]).toArray(); // approximately [10, 1, 0]
+ * placement.applyPoint([1, 0, 0]).toData(); // approximately [10, 1, 0]
  * ```
  */
-export function transform3(matrix = IDENTITY_TRANSFORM3) {
-    return new Placement3(snapshotTransform3(matrix));
+export function transform3(input = IDENTITY_TRANSFORM3) {
+    return new Placement3(snapshotTransform3(readTransformMatrix(input, 3)));
 }

package/dist/index.js

@@ -1,5 +1,6 @@
 /** Immutable modeling recipes and math values; the host owns geometry evaluation. @packageDocumentation */
-export { transform2, transform3, } from "./geometry/transform-chain.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";

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/7");
+const executionKey = Symbol.for("@metamesh/modeling/execution/9");
 const bindings = globalThis;
 /** Internal host binding. Executable callbacks are synchronous and may not nest executions. */
 export function bindModelContext(context, build) {

package/dist/model/geometry-recipes.js

@@ -1,7 +1,7 @@
 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");
+const recipeKey = Symbol.for("@metamesh/modeling/recipe/9");
 /** 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. */

package/dist/model/hole-cutter.js

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

package/dist/model/immutable-generation-data.js

@@ -185,18 +185,10 @@ 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.");
+    const method = Reflect.get(value, "toData");
+    if (typeof method !== "function")
+        throw new TypeError("Immutable math values must expose canonical data through toData().");
+    return Reflect.apply(method, value, []);
 }
 function captureValue(value, mode, readerAllowed = () => false, validated) {
     const recipeInputs = mode === "recipe";

package/dist/model/knuckle-hinge.js

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

package/dist/model/operations.js

@@ -32,6 +32,27 @@ export function box(options) {
 export function cylinder(options) {
     return invoke("cylinder", [options]);
 }
+/**
+ * Declares a +Z hole or blind-pocket cutter with explicit end overrun in millimetres.
+ * Choose exactly one circular diameter or existing Section. A 45-degree entry chamfer
+ * supports one strictly convex contour without holes; plain profiles may have any topology.
+ * Circular entries retain nominal frustum radii; profile entries offset the supplied polygon edges.
+ * Circular head recesses are mutually exclusive with entryChamfer. Both overrun ends default
+ * to zero, so the nominal bottom remains at Z=0 and blind pocket floors are preserved.
+ * Existing Section samples are authoritative; limits and unspecified circular sampling belong
+ * to the evaluating host. Compiled packages require runtime major 9.
+ *
+ * @example A blind hex pocket with an open top
+ * ```ts
+ * holeCutter({
+ *   profile: regularPolygon({ sides: 6, radius: 3.5, sizing: "face", rotation: 30 }),
+ *   height: 12, entryChamfer: 0.5, overrun: { top: 0.05 },
+ * });
+ * ```
+ */
+export function holeCutter(options) {
+    return invoke("holeCutter", [options]);
+}
 /**
  * Hollow +Z tube.
  *
@@ -153,6 +174,7 @@ export function anchor(shape, name) {
 }
 /**
  * Fills one closed millimetre XY outline, explicit outer/hole topology, or compound contours.
+ *
  * Closing edges are implicit. Compound contours use nonzero fill unless selected otherwise.
  * Explicit topology must be simple and disjoint; compound winding may resolve overlaps.
  *
@@ -182,6 +204,9 @@ export function stroke(path, options) {
 /**
  * Filled rectangular section with uniform or independently treated corners.
  *
+ * Use [rectangleContour](/docs/reference/geometry/rectangleContour) for sampled boundary coordinates,
+ * or [rectangleProfile](/docs/reference/geometry/rectangleProfile) to retain identified loft landmarks.
+ *
  * @example Round the corners
  * ```ts
  * rectangle({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
@@ -373,6 +398,7 @@ export function implicit(options) {
 }
 /**
  * Closed rectilinear top above a flat base, with uniform or explicit XY coordinates.
+ *
  * Samples each grid height once; center-error triangulation also samples each cell centre.
  * The retained callback must capture independent immutable inputs, not live session readers or parameters.
  *
@@ -403,6 +429,31 @@ export function pathPattern(...args) {
 export function threadRidge(options) {
     return invoke("threadRidge", [options]);
 }
+/**
+ * Declares separate knuckle-joint halves along the centered +X pin axis, in millimetres.
+ *
+ * A starts at negative X. Attach independent webs or use barrels only; caller geometry connects
+ * otherwise disconnected intervals. Returns portable recipes without initializing the engine.
+ * Unspecified resolution inherits the evaluating session. Axis direction is +X with +Z up.
+ *
+ * Each half's `chamfer` bevels its barrel outer rims and all web edges. Consumers own plates, screw holes,
+ * pin retention, fit policy, and part placement. Added mounting material must preserve the bores.
+ * No opening range or collision freedom is implied for arbitrary caller attachments.
+ * Compiled Generator packages using this operation require runtime 9.0.0 or newer in major 9.
+ *
+ * @example Integral-pin hinge with two mounting webs
+ * ```ts
+ * const joint = knuckleHinge({
+ *   mode: "print-in-place", length: 30, knuckleCount: 3,
+ *   barrelDiameter: 10, pinDiameter: 3, radialClearance: 0.3, axialGap: 0.4,
+ *   halfA: { web: { direction: "positive-y", reach: 8, zMin: -5, thickness: 2 } },
+ *   halfB: { web: { direction: "negative-y", reach: 8, zMin: -5, thickness: 2 } },
+ * });
+ * ```
+ */
+export function knuckleHinge(options) {
+    return invoke("knuckleHinge", [options]);
+}
 /**
  * Compensated external threaded rod.
  *
@@ -449,15 +500,39 @@ export function internalThreadCutter(options) {
 export function threadedNut(options) {
     return invoke("threadedNut", [options]);
 }
-/** External-thread facts using host resolution and limits; requires active synchronous model execution. */
+/**
+ * Checks compensated rod dimensions and conservative mesh estimates against host output limits.
+ *
+ * Requires active synchronous model execution and uses its resolution and limits. Returns selected
+ * sampling and conservative row/triangle estimates without mesh buffers or native objects.
+ * Mesh validity, native construction, and aggregate output limits are checked later.
+ *
+ * @see {@link threadedRod}
+ */
 export function preflightThreadedRod(options) {
     return invoke("preflightThreadedRod", [options]);
 }
-/** Internal-thread facts using host resolution and limits; requires active synchronous model execution. */
+/**
+ * Checks compensated cutter dimensions and conservative mesh estimates against host output limits.
+ *
+ * Requires active synchronous model execution and uses its resolution and limits. Estimates include
+ * the one-pitch extension beyond each requested face, without mesh buffers or native objects.
+ * Mesh validity, native construction, and aggregate output limits are checked later.
+ *
+ * @see {@link internalThreadCutter}
+ */
 export function preflightInternalThreadCutter(options) {
     return invoke("preflightInternalThreadCutter", [options]);
 }
-/** Nut/cutter facts using host resolution and limits; requires active synchronous model execution. */
+/**
+ * Checks nut dimensions, chamfers, end-face wall, and the extended compensated cutter's allocation plan.
+ *
+ * Requires active synchronous model execution and uses its resolution and limits, without mesh
+ * buffers or native objects. Returned thread estimates cover the cutter, excluding the body and
+ * Boolean result. Mesh validity, native construction, and aggregate output limits are checked later.
+ *
+ * @see {@link threadedNut}
+ */
 export function preflightThreadedNut(options) {
     return invoke("preflightThreadedNut", [options]);
 }