@metamesh/modeling 0.16.0 → 0.18.0

package/dist/geometry/primitive-resolvers.js

@@ -1,5 +1,6 @@
 import { edgeTreatmentPointCount, edgeTreatmentSetbacks, sampleEdgeTreatment, } from "./edge-finishing.js";
 import { GeometryError } from "./errors.js";
+import { vector3Data } from "./math/vector-value.js";
 import { assertMeshAllocationWithinLimits, resolveModelingLimits } from "./model-limits.js";
 import { resolveCircularPrimitiveSegments } from "./primitive-resolution.js";
 /** @internal Face pairs define the twelve nominal box edges in deterministic order. */
@@ -87,13 +88,9 @@ export function resolveBoxPrimitive(options) {
             operation,
         });
     }
-    if (typeof options.size !== "number" &&
-        (!Array.isArray(options.size) || options.size.length !== 3)) {
-        throw new GeometryError("INVALID_ARGUMENT", "size must be a number or an exact XYZ tuple.", {
-            operation,
-        });
-    }
-    const dimensions = typeof options.size === "number" ? [options.size, options.size, options.size] : options.size;
+    const dimensions = typeof options.size === "number"
+        ? [options.size, options.size, options.size]
+        : vector3Data(options.size);
     for (let axis = 0; axis < 3; axis += 1) {
         assertPositivePrimitive(dimensions[axis], `size[${axis}]`, operation);
     }
@@ -193,17 +190,48 @@ export function resolveBoxPrimitive(options) {
             },
         };
 }
-/** @internal Validates tube dimensions shared by both adapters before allocating cylinders. */
-export function resolveTubePrimitive(options) {
+/** @internal Resolves one complete radius or diameter pair before applying faceting compensation. */
+export function resolveTubeRadii(options) {
     assertPrimitiveOptions(options, "tube");
-    assertPositivePrimitive(options.innerRadius, "innerRadius", "tube");
-    assertPositivePrimitive(options.outerRadius, "outerRadius", "tube");
+    const radii = options.innerRadius !== undefined || options.outerRadius !== undefined;
+    const diameters = options.innerDiameter !== undefined || options.outerDiameter !== undefined;
+    if (radii === diameters)
+        throw new GeometryError("INVALID_ARGUMENT", "Supply one complete radius or diameter pair.", {
+            operation: "tube",
+        });
+    const innerRadius = radii ? options.innerRadius : options.innerDiameter / 2;
+    const outerRadius = radii ? options.outerRadius : options.outerDiameter / 2;
+    assertPositivePrimitive(innerRadius, "innerRadius", "tube");
+    assertPositivePrimitive(outerRadius, "outerRadius", "tube");
+    if (!(outerRadius > innerRadius))
+        throw new GeometryError("INVALID_ARGUMENT", "Outer size must be larger than inner size.", {
+            operation: "tube",
+        });
+    return { innerRadius, outerRadius };
+}
+/** @internal Resolves shared faceting so compensated inner and outer rings retain a positive wall. */
+export function resolveTubePrimitive(options) {
+    const { innerRadius, outerRadius } = resolveTubeRadii(options);
     assertPositivePrimitive(options.height, "height", "tube");
-    if (!(options.outerRadius > options.innerRadius)) {
-        throw new GeometryError("INVALID_ARGUMENT", "outerRadius must be larger than innerRadius.", {
+    if (options.center !== undefined && typeof options.center !== "boolean")
+        throw new GeometryError("INVALID_ARGUMENT", "center must be boolean when supplied.", {
             operation: "tube",
         });
-    }
+    const sizing = (value) => {
+        if (value !== undefined && value !== "vertex" && value !== "face")
+            throw new GeometryError("INVALID_ARGUMENT", "Tube sizing must be vertex or face.", {
+                operation: "tube",
+            });
+        return value ?? "vertex";
+    };
+    const innerSizing = sizing(options.innerSizing), outerSizing = sizing(options.outerSizing);
+    const segments = Math.max(resolveCircularPrimitiveSegments(innerRadius, { ...options, sizing: innerSizing }, "tube"), resolveCircularPrimitiveSegments(outerRadius, { ...options, sizing: outerSizing }, "tube"));
+    const cosine = Math.cos(Math.PI / segments);
+    const innerVertexRadius = innerSizing === "face" ? innerRadius / cosine : innerRadius;
+    const outerVertexRadius = outerSizing === "face" ? outerRadius / cosine : outerRadius;
+    if (!Number.isFinite(outerVertexRadius) || !(outerVertexRadius > innerVertexRadius))
+        throw new GeometryError("INVALID_ARGUMENT", "Tube sizing and sampling must leave a finite positive wall.", { operation: "tube" });
+    return { innerVertexRadius, outerVertexRadius, segments };
 }
 /** @internal Resolves sphere sampling shared by compiled and authored adapters. */
 export function resolveSpherePrimitive(options) {

package/dist/geometry/profiles/primitives/circle.js

@@ -0,0 +1,19 @@
+import { resolveCircularSampling } from "../../circular-sampling.js";
+import { requireProfileVertexCount } from "../validation.js";
+/**
+ * Creates an immutable centered CCW circle with +X seam and vertex or face radial sizing.
+ *
+ * @example Explicit circular point data
+ * ```ts
+ * circleContour({ diameter: 20, segments: 32 });
+ * ```
+ */
+export const circleContour = (options) => {
+    const operation = "circleContour";
+    const { segments, vertexRadius } = resolveCircularSampling(options);
+    requireProfileVertexCount(segments, 3, operation, options.limits);
+    return Object.freeze(Array.from({ length: segments }, (_, index) => {
+        const angle = (Math.PI * 2 * index) / segments;
+        return Object.freeze([vertexRadius * Math.cos(angle), vertexRadius * Math.sin(angle)]);
+    }));
+};

package/dist/geometry/profiles/{shapes.js → primitives/ellipse.js}

@@ -1,7 +1,8 @@
-import { GeometryError } from "../errors.js";
-import { resolveCircularPrimitiveSegments } from "../primitive-resolution.js";
-import { assertPrimitiveOptions } from "../primitive-resolvers.js";
-import { requireFiniteProfileValues, requireProfileVertexCount } from "./validation.js";
+import { GeometryError } from "../../errors.js";
+import { vector2Data } from "../../math/vector-value.js";
+import { resolveCircularPrimitiveSegments } from "../../primitive-resolution.js";
+import { assertPrimitiveOptions } from "../../primitive-resolvers.js";
+import { requireFiniteProfileValues, requireProfileVertexCount } from "../validation.js";
 /**
  * Creates an immutable centered CCW ellipse with +X seam within the selected sampling ceiling.
  *
@@ -17,12 +18,7 @@ export function ellipseContour(options) {
             operation: "ellipseContour",
         });
     }
-    const dimensions = options.radius ?? options.size;
-    if (!Array.isArray(dimensions) || dimensions.length !== 2) {
-        throw new GeometryError("INVALID_ARGUMENT", "Ellipse dimensions must be an exact XY tuple.", {
-            operation: "ellipseContour",
-        });
-    }
+    const dimensions = vector2Data(options.radius ?? options.size);
     const factor = options.radius === undefined ? 0.5 : 1;
     const radiusX = dimensions[0] * factor;
     const radiusY = dimensions[1] * factor;

package/dist/geometry/profiles/{rectangle.js → primitives/rectangle.js}

@@ -1,22 +1,20 @@
-import { edgeTreatmentPointCount, edgeTreatmentSetbacks, sampleEdgeTreatment, } from "../edge-finishing.js";
-import { GeometryError } from "../errors.js";
-import { resolveModelingLimits } from "../model-limits.js";
-import { assertPrimitiveOptions } from "../primitive-resolvers.js";
-import { resolveAlignedCircularSegments } from "../resolution.js";
-import { assertSamplingCount } from "../sampling-limits.js";
-import { requireFiniteProfileValues, requireProfileVertexCount } from "./validation.js";
+import { edgeTreatmentPointCount, edgeTreatmentSetbacks, sampleEdgeTreatment, } from "../../edge-finishing.js";
+import { GeometryError } from "../../errors.js";
+import { vector2Data } from "../../math/vector-value.js";
+import { resolveModelingLimits } from "../../model-limits.js";
+import { assertPrimitiveOptions } from "../../primitive-resolvers.js";
+import { resolveAlignedCircularSegments } from "../../resolution.js";
+import { assertSamplingCount } from "../../sampling-limits.js";
+import { requireFiniteProfileValues, requireProfileVertexCount } from "../validation.js";
 const fail = (operation, message) => {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation });
 };
 /** @internal Validates the shared rectangle family before native or pure allocation. */
 export function resolveRectangle(options, operation) {
     assertPrimitiveOptions(options, operation);
-    if (typeof options.size !== "number" &&
-        (!Array.isArray(options.size) || options.size.length !== 2))
-        fail(operation, "size must be a number or an exact XY tuple.");
     if (options.center !== undefined && typeof options.center !== "boolean")
         fail(operation, "center must be boolean.");
-    const [width, height] = typeof options.size === "number" ? [options.size, options.size] : options.size;
+    const [width, height] = typeof options.size === "number" ? [options.size, options.size] : vector2Data(options.size);
     requireFiniteProfileValues([width, height], operation);
     if (!(width > 0) || !(height > 0))
         fail(operation, "Rectangle dimensions must be positive.");
@@ -79,7 +77,11 @@ export function rectangleCornerSegments(corner, limits) {
     }) / 4);
 }
 /**
- * Creates an immutable sampled CCW rectangle boundary. Round radius zero is square; tangent saturated endpoints occur once.
+ * Creates an immutable sampled CCW rectangle boundary.
+ *
+ * @remarks
+ * A zero round radius leaves square corners. When rounded corners meet, their shared endpoints
+ * appear once.
  *
  * Use [rectangle](/docs/reference/model/rectangle) for a filled Section.
  *

package/dist/geometry/profiles/primitives/regular-polygon.js

@@ -0,0 +1,33 @@
+import { GeometryError } from "../../errors.js";
+import { requireFiniteProfileValues, requireProfileVertexCount } from "../validation.js";
+/**
+ * Creates an immutable centered CCW point loop with vertex or face radial sizing and an implicit seam.
+ *
+ * @example Hexagon sized to its faces
+ * ```ts
+ * regularPolygonContour({ radius: 10, sides: 6, sizing: "face" });
+ * ```
+ */
+export const regularPolygonContour = (options) => {
+    const operation = "regularPolygonContour";
+    const { radius, sides, rotation = 0, sizing = "vertex" } = options;
+    requireFiniteProfileValues([radius, rotation], operation);
+    if (!(radius > 0)) {
+        throw new GeometryError("INVALID_ARGUMENT", "Polygon radius must be positive.", { operation });
+    }
+    requireProfileVertexCount(sides, 3, operation, options.limits);
+    if (sizing !== "vertex" && sizing !== "face")
+        throw new GeometryError("INVALID_ARGUMENT", "Polygon sizing must be vertex or face.", {
+            operation,
+        });
+    const sampledRadius = sizing === "face" ? radius / Math.cos(Math.PI / sides) : radius;
+    requireFiniteProfileValues([sampledRadius], operation);
+    const rotationRadians = ((rotation % 360) * Math.PI) / 180;
+    return Object.freeze(Array.from({ length: sides }, (_, index) => {
+        const angle = rotationRadians + (Math.PI * 2 * index) / sides;
+        return Object.freeze([
+            sampledRadius * Math.cos(angle),
+            sampledRadius * Math.sin(angle),
+        ]);
+    }));
+};

package/dist/geometry/profiles/primitives/star.js

@@ -0,0 +1,28 @@
+import { GeometryError } from "../../errors.js";
+import { assertPrimitiveOptions } from "../../primitive-resolvers.js";
+import { requireFiniteProfileValues, requireProfileVertexCount } from "../validation.js";
+/**
+ * Creates an immutable centered CCW alternating-radius star within the selected profile sampling ceiling.
+ *
+ * @example Five-point outline
+ * ```ts
+ * starContour({ outerRadius: 12, innerRadius: 6, points: 5 });
+ * ```
+ */
+export const starContour = (options) => {
+    const operation = "starContour";
+    assertPrimitiveOptions(options, operation);
+    const { outerRadius, innerRadius, points, rotation = 0, limits } = options;
+    requireFiniteProfileValues([outerRadius, innerRadius, rotation], operation);
+    if (!(outerRadius > 0) || !(innerRadius > 0) || innerRadius >= outerRadius) {
+        throw new GeometryError("INVALID_ARGUMENT", "Star radii must be positive, with the inner radius smaller than the outer.", { operation });
+    }
+    requireProfileVertexCount(points, 3, operation, limits);
+    requireProfileVertexCount(points * 2, 6, operation, limits);
+    const rotationRadians = ((rotation % 360) * Math.PI) / 180;
+    return Object.freeze(Array.from({ length: points * 2 }, (_, index) => {
+        const radius = index % 2 === 0 ? outerRadius : innerRadius;
+        const angle = (Math.PI * index) / points + rotationRadians;
+        return Object.freeze([radius * Math.cos(angle), radius * Math.sin(angle)]);
+    }));
+};

package/dist/geometry/revolve/revolve-mesh.js

@@ -26,7 +26,7 @@ const AXIS_EPSILON = 1e-10;
  * @example Partial revolution with end caps
  * ```ts
  * // Each point is [radius, Z]; the profile seam is implicit.
- * revolveMesh([[0, 0], [12, 0], [8, 20], [0, 20]], { degrees: 270 });
+ * mesh.revolve([[0, 0], [12, 0], [8, 20], [0, 20]], { degrees: 270 });
  * ```
  */
 export const revolveMesh = (input, options = {}) => {

package/dist/geometry/{svg-import.js → svg/import.js}

@@ -1,16 +1,20 @@
 import { SaxesParser } from "saxes";
-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 { flattenSvgSubpaths, SvgVertexBudget } from "./svg/path.js";
+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 "./fill.js";
+import { inverseMatrix, multiplyMatrices as multiply, transformPoint } from "./matrix.js";
+import { flattenSvgSubpaths, SvgVertexBudget } from "./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/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/sweeps/sweep-mesh.js

@@ -10,7 +10,7 @@ import { buildOpenSweepMesh } from "./sweep-open.js";
  * @example Sweep point data along a bent path
  * ```ts
  * const profile = rectangleContour({ size: [6, 3] });
- * sweepMesh(profile, [[0, 0, 0], [0, 0, 15], [10, 0, 25]], {
+ * mesh.sweep(profile, [[0, 0, 0], [0, 0, 15], [10, 0, 25]], {
  *   orientation: { kind: "transport", initialNormal: [0, 1, 0] },
  * });
  * ```

package/dist/geometry/transform3.js

@@ -59,6 +59,35 @@ export function validateTransform3(transform, tolerance = {}) {
     }
     return transform;
 }
+/**
+ * Validates a proper rigid transform: finite translation and a right-handed orthonormal rotation.
+ * Scale, shear, reflection, and perspective are rejected within the default angular tolerance.
+ * Returns the original row-major 4x4 matrix without copying or normalizing it.
+ *
+ * @throws {@link GeometryError} For a malformed, non-finite, or non-rigid matrix.
+ */
+export function validateRigidTransform3(transform) {
+    if (!Array.isArray(transform) || transform.length !== 16)
+        throw new GeometryError("INVALID_ARGUMENT", "Rigid transforms require sixteen matrix entries.");
+    for (let index = 0; index < 16; index++) {
+        if (!Object.hasOwn(transform, index) || !Number.isFinite(transform[index]))
+            throw new GeometryError("NON_FINITE_VALUE", "Rigid transforms require sixteen finite values.");
+    }
+    validateTransform3(transform);
+    const tolerance = resolveGeometryTolerance().angular;
+    for (let row = 0; row < 3; row++) {
+        for (let other = row; other < 3; other++) {
+            let product = 0;
+            for (let column = 0; column < 3; column++)
+                product += transform[row * 4 + column] * transform[other * 4 + column];
+            if (Math.abs(product - (row === other ? 1 : 0)) > tolerance)
+                throw new GeometryError("INVALID_ARGUMENT", "Rigid placement permits only translation and rotation; scale and shear are not supported.");
+        }
+    }
+    if (Math.abs(transformDeterminant3(transform) - 1) > tolerance)
+        throw new GeometryError("INVALID_ARGUMENT", "Rigid placement does not support reflection.");
+    return transform;
+}
 /**
  * Creates an immutable translation transform.
  *