@metamesh/modeling 0.16.0 → 0.17.0

package/dist/geometry/circular-sampling.js

@@ -0,0 +1,45 @@
+import { GeometryError } from "./errors.js";
+import { resolveCircularPrimitiveSegments } from "./primitive-resolution.js";
+import { assertPrimitiveOptions } from "./primitive-resolvers.js";
+function fail(message, nonfinite = false) {
+    throw new GeometryError(nonfinite ? "NON_FINITE_VALUE" : "INVALID_ARGUMENT", message, {
+        operation: "resolveCircularSampling",
+    });
+}
+/**
+ * Resolves circular sampling and its actual radial envelopes without allocating boundary points.
+ *
+ * Vertex sizing retains the nominal vertex radius; face sizing retains the nominal face radius.
+ * Exact `segments` override resolution, while allocation ceilings still apply. Adaptive sampling
+ * uses the same count calculation as `resolveCircularSegments` and `circleContour` and rejects
+ * exhausted limits rather than coarsening. The returned record is immutable and needs no engine.
+ *
+ * @example Check a nominal 8 mm face-sized bore
+ * ```ts
+ * const bore = resolveCircularSampling({ diameter: 8, segments: 64, sizing: "face" });
+ * bore.faceRadius; // 4 mm
+ * bore.vertexRadius; // slightly larger than 4 mm
+ * ```
+ */
+export function resolveCircularSampling(options) {
+    const operation = "resolveCircularSampling";
+    assertPrimitiveOptions(options, operation);
+    if ((options.radius === undefined) === (options.diameter === undefined)) {
+        fail("Specify exactly one radius or diameter.");
+    }
+    const radius = options.radius ?? options.diameter / 2;
+    const finite = Number.isFinite(radius);
+    if (!finite || radius <= 0)
+        fail("Circle radius must be finite and positive.", !finite);
+    const sizing = options.sizing ?? "vertex";
+    if (sizing !== "vertex" && sizing !== "face") {
+        fail("sizing must be vertex or face.");
+    }
+    const segments = resolveCircularPrimitiveSegments(radius, options, operation);
+    const cosine = Math.cos(Math.PI / segments);
+    const vertexRadius = sizing === "face" ? radius / cosine : radius;
+    const faceRadius = sizing === "face" ? radius : radius * cosine;
+    if (!Number.isFinite(vertexRadius))
+        fail("Sampled radii must remain finite.", true);
+    return Object.freeze({ segments, vertexRadius, faceRadius });
+}

package/dist/geometry/convex-offset.js

@@ -0,0 +1,41 @@
+import { GeometryError } from "./errors.js";
+/** @internal Parallel-edge offsets shared by convex extrusion rims and pocket entries. */
+export function convexContourOffsets(points, operation) {
+    const fail = (message) => {
+        throw new GeometryError("INVALID_ARGUMENT", message, { operation });
+    };
+    if (points.length < 3)
+        fail("A convex contour needs at least three vertices.");
+    const edges = points.map((point, index) => {
+        const next = points[(index + 1) % points.length];
+        const dx = next[0] - point[0], dy = next[1] - point[1];
+        const length = Math.hypot(dx, dy);
+        if (!(length > 0) || !Number.isFinite(length))
+            fail("Contours must have distinct finite vertices.");
+        return [dx / length, dy / length];
+    });
+    const miters = edges.map((edge, index) => {
+        const previous = edges[(index + edges.length - 1) % edges.length];
+        const turn = previous[0] * edge[1] - previous[1] * edge[0];
+        if (!(turn > 1e-12))
+            fail("Entry and end treatments require a strictly convex counterclockwise contour without collinear vertices.");
+        const denominator = 1 + previous[0] * edge[0] + previous[1] * edge[1];
+        return [(-previous[1] - edge[1]) / denominator, (previous[0] + edge[0]) / denominator];
+    });
+    return {
+        magnification: miters.reduce((maximum, [x, y]) => Math.max(maximum, Math.hypot(x, y)), 1),
+        offset(inset) {
+            const result = points.map(([x, y], index) => [
+                x + miters[index][0] * inset,
+                y + miters[index][1] * inset,
+            ]);
+            for (let index = 0; index < result.length; index++) {
+                const point = result[index], next = result[(index + 1) % result.length], edge = edges[index];
+                if (!point.every(Number.isFinite) ||
+                    !((next[0] - point[0]) * edge[0] + (next[1] - point[1]) * edge[1] > 0))
+                    fail("Treatment offset collapses or reverses a contour edge.");
+            }
+            return result;
+        },
+    };
+}

package/dist/geometry/index.js

@@ -1,6 +1,7 @@
 /** Pure geometry foundations without host initialization. @packageDocumentation */
 export { bounds2, bounds3, } from "./bounds-value.js";
-export { boundsFromSize, boundsSize, boundsCenter, containsBounds, fitBounds, layoutRow, } from "./bounds.js";
+export { boundsSize, boundsCenter, fitBounds, layoutRow, } from "./bounds.js";
+export { resolveCircularSampling, } from "./circular-sampling.js";
 export { fitTextLayout } from "./text-fitting.js";
 export { gridPatternTransforms, linearPatternTransforms, radialPatternTransforms, pathPatternTransforms, } from "./patterns.js";
 export { validateSolidMesh } from "./mesh/mesh-solid.js";

package/dist/geometry/math/immutable-value.js

@@ -1,5 +1,5 @@
 // A versioned realm protocol lets separately bundled authoring values cross the host boundary.
-const immutableMath = Symbol.for("@metamesh/modeling/immutable-math/8");
+const immutableMath = Symbol.for("@metamesh/modeling/immutable-math/9");
 /**
  * Brands and freezes only this constructor's prototype. Pure-annotated callers let bundlers
  * discard unused classes without dropping initialization for classes that remain reachable.

package/dist/geometry/profiles/profiles.js

@@ -1,6 +1,5 @@
+import { resolveCircularSampling } from "../circular-sampling.js";
 import { GeometryError } from "../errors.js";
-import { resolveCircularPrimitiveSegments } from "../primitive-resolution.js";
-import { assertPrimitiveOptions } from "../primitive-resolvers.js";
 import { requireFiniteProfileValues, requireProfileVertexCount } from "./validation.js";
 export { rectangleContour } from "./rectangle.js";
 /**
@@ -13,30 +12,11 @@ export { rectangleContour } from "./rectangle.js";
  */
 export const circleContour = (options) => {
     const operation = "circleContour";
-    assertPrimitiveOptions(options, operation);
-    if ((options.radius === undefined) === (options.diameter === undefined)) {
-        throw new GeometryError("INVALID_ARGUMENT", "Specify exactly one radius or diameter.", {
-            operation,
-        });
-    }
-    const radius = options.radius ?? options.diameter / 2;
-    requireFiniteProfileValues([radius], operation);
-    if (!(radius > 0)) {
-        throw new GeometryError("INVALID_ARGUMENT", "Circle radius must be positive.", { operation });
-    }
-    const segments = resolveCircularPrimitiveSegments(radius, options, operation);
+    const { segments, vertexRadius } = resolveCircularSampling(options);
     requireProfileVertexCount(segments, 3, operation, options.limits);
-    const sizing = options.sizing ?? "vertex";
-    if (sizing !== "vertex" && sizing !== "face") {
-        throw new GeometryError("INVALID_ARGUMENT", "Circle sizing must be vertex or face.", {
-            operation,
-        });
-    }
-    const sampledRadius = sizing === "face" ? radius / Math.cos(Math.PI / segments) : radius;
-    requireFiniteProfileValues([sampledRadius], operation);
     return Object.freeze(Array.from({ length: segments }, (_, index) => {
         const angle = (Math.PI * 2 * index) / segments;
-        return Object.freeze([sampledRadius * Math.cos(angle), sampledRadius * Math.sin(angle)]);
+        return Object.freeze([vertexRadius * Math.cos(angle), vertexRadius * Math.sin(angle)]);
     }));
 };
 /**

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 [];
     }
@@ -479,7 +488,7 @@ function measureSvgRegion(region) {
  * @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,38 @@ 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,
+    ];
 }
 /**
  * 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. The region may be empty; tiny-island
- * and short-edge indicators do not establish manufacturability or later solid validity.
+ * 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.
@@ -656,5 +686,57 @@ function createSvgRegionPreflight(svg, options = {}) {
  * @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/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/8");
+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/8");
+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/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.
  *
@@ -415,10 +436,10 @@ export function threadRidge(options) {
  * otherwise disconnected intervals. Returns portable recipes without initializing the engine.
  * Unspecified resolution inherits the evaluating session. Axis direction is +X with +Z up.
  *
- * Barrel end chamfers affect outer rims only; webs have square edges. Consumers own plates, screw holes,
+ * 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 8.0.0 or newer in major 8.
+ * 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

package/dist/model/recipe-declaration.js

@@ -10,6 +10,7 @@ const operationBehaviors = {
     withResolution: "resolution",
     box: "solid",
     cylinder: "solid",
+    holeCutter: "solid",
     tube: "solid",
     sphere: "solid",
     torus: "solid",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamesh/modeling",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Scoped solid modeling and pure geometry foundations for Node and browsers.",
   "license": "Apache-2.0",
   "repository": {

package/dist/docs/reference/geometry/BoundsFromSizeOptions.md

@@ -1,24 +0,0 @@
-# BoundsFromSizeOptions
-
-Placement of bounds constructed from nonnegative millimetre dimensions.
-
-## Properties
-
-### center?
-
-
-
-`readonly` `optional` **center?**: `boolean`
-
-
-
-Center on the origin; false starts at the origin. Defaults to true.
-
-
-## Guides
-
-- [Measure and compare bounds](../../guides/concepts.md#measure-and-compare-bounds)
-- [Text from a Font parameter](../../guides/recipes.md#text-from-a-font-parameter)
-- [Solid inspection](../../guides/recipes.md#solid-inspection)
-
-Package: `@metamesh/modeling@0.16.0`.