@metamesh/modeling 0.19.0 → 0.20.0

package/dist/geometry/paths/{path-value.js → value.js}

@@ -1,11 +1,13 @@
-import { bounds2, bounds3 } from "../bounds-value.js";
+import { bounds2, bounds3 } from "../bounds/value.js";
 import { GeometryError } from "../errors.js";
 import { immutableMathClass } from "../math/immutable-value.js";
 import { vector2, vector2Data, vector3, vector3Data, } from "../math/vector-value.js";
-import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
-import { transformPath2, transformPath3 } from "../transform-geometry.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling/limits.js";
+import { transformPath2, transformPath3 } from "../transforms/apply.js";
 import { closestPointOnValidatedPath } from "./closest-point.js";
+import { splitPathPoints, subdividePathPoints, trimPathPoints } from "./editing.js";
 import { resamplePath2Points, resamplePath3Points } from "./resampling.js";
+import { createPathTraversal, locatePathDistance, measurePathLength, writePathPoint, writePathTangent, } from "./traversal.js";
 const fail = (message, code = "INVALID_ARGUMENT") => {
     throw new GeometryError(code, message, { operation: "path" });
 };
@@ -90,17 +92,45 @@ function measuredLength(owner) {
     const cached = state.length;
     if (cached !== undefined)
         return cached;
-    const points = state.points;
-    let total = 0;
-    const count = owner.closed ? points.length : Math.max(0, points.length - 1);
-    for (let index = 0; index < count; index++) {
-        const a = points[index], b = points[(index + 1) % points.length];
-        total += Math.hypot(b[0] - a[0], b[1] - a[1], (b[2] ?? 0) - (a[2] ?? 0));
-        if (!Number.isFinite(total))
-            fail("Path length exceeds finite arithmetic.", "NON_FINITE_VALUE");
-    }
-    state.length = total;
-    return total;
+    return (state.length = measurePathLength(state.points, owner.closed));
+}
+function traversalOf(owner) {
+    const state = stateOf(owner);
+    const traversal = (state.traversal ??= createPathTraversal(state.points, owner.closed));
+    state.length = traversal.length;
+    return traversal;
+}
+function editingTraversal(owner, limits = {}) {
+    const maximum = resolveGeometrySamplingLimits(limits).maxPathPoints;
+    assertSamplingCount(stateOf(owner).points.length, "path", maximum);
+    return { traversal: traversalOf(owner), maximum };
+}
+function fractionDistance(owner, fraction) {
+    if (!Number.isFinite(fraction))
+        fail("Path fraction must be finite.", "NON_FINITE_VALUE");
+    if (fraction < 0 || fraction > 1)
+        fail("Path fraction must lie between zero and one.");
+    return measuredLength(owner) * fraction;
+}
+function station(owner, distance) {
+    const traversal = traversalOf(owner);
+    const location = locatePathDistance(traversal, distance);
+    const point = [], tangent = [];
+    writePathPoint(traversal, location, point);
+    writePathTangent(traversal, location, tangent);
+    return owner.dimension === 2
+        ? Object.freeze({
+            ...location,
+            offset: distance,
+            point: vector2([point[0], point[1]]),
+            tangent: vector2([tangent[0], tangent[1]]),
+        })
+        : Object.freeze({
+            ...location,
+            offset: distance,
+            point: vector3([point[0], point[1], point[2]]),
+            tangent: vector3([tangent[0], tangent[1], tangent[2]]),
+        });
 }
 function measuredBounds(points) {
     if (points.length === 0)
@@ -129,6 +159,7 @@ const PlanarPath = /* @__PURE__ */ immutableMathClass(class PlanarPath {
     dimension = 2;
     constructor(points, closed) {
         this.closed = closed;
+        validateClosure(points, closed);
         pathStates.set(this, { points });
         Object.freeze(this);
     }
@@ -139,12 +170,32 @@ const PlanarPath = /* @__PURE__ */ immutableMathClass(class PlanarPath {
         return measuredLength(this);
     }
     bounds() {
-        return measuredBounds(points2(this));
+        return (stateOf(this).bounds ??= measuredBounds(points2(this)));
     }
     closestPoint(point) {
         const location = closestPointOnValidatedPath(points2(this), vector2Data(point), this.closed);
         return Object.freeze({ ...location, point: vector2(location.point) });
     }
+    atDistance(distance) {
+        return station(this, distance);
+    }
+    atFraction(fraction) {
+        return station(this, fractionDistance(this, fraction));
+    }
+    splitAt(distance, limits) {
+        const { traversal, maximum } = editingTraversal(this, limits);
+        const [first, second] = splitPathPoints(traversal, distance, maximum);
+        return Object.freeze([new PlanarPath(first, false), new PlanarPath(second, false)]);
+    }
+    trim(start, end, limits) {
+        const { traversal, maximum } = editingTraversal(this, limits);
+        return new PlanarPath(trimPathPoints(traversal, start, end, maximum), false);
+    }
+    subdivide(options) {
+        validateOptions(options);
+        const { traversal, maximum } = editingTraversal(this, options.limits);
+        return new PlanarPath(subdividePathPoints(traversal, options.maxSegmentLength, maximum), this.closed);
+    }
     transform(placement) {
         return new PlanarPath(transformPath2(points2(this), placement), this.closed);
     }
@@ -161,6 +212,7 @@ const SpatialPath = /* @__PURE__ */ immutableMathClass(class SpatialPath {
     dimension = 3;
     constructor(points, closed) {
         this.closed = closed;
+        validateClosure(points, closed);
         pathStates.set(this, { points });
         Object.freeze(this);
     }
@@ -171,12 +223,35 @@ const SpatialPath = /* @__PURE__ */ immutableMathClass(class SpatialPath {
         return measuredLength(this);
     }
     bounds() {
-        return measuredBounds(points3(this));
+        return (stateOf(this).bounds ??= measuredBounds(points3(this)));
     }
     closestPoint(point) {
         const location = closestPointOnValidatedPath(points3(this), vector3Data(point), this.closed);
         return Object.freeze({ ...location, point: vector3(location.point) });
     }
+    atDistance(distance) {
+        return station(this, distance);
+    }
+    atFraction(fraction) {
+        return station(this, fractionDistance(this, fraction));
+    }
+    splitAt(distance, limits) {
+        const { traversal, maximum } = editingTraversal(this, limits);
+        const [first, second] = splitPathPoints(traversal, distance, maximum);
+        return Object.freeze([
+            new SpatialPath(first, false),
+            new SpatialPath(second, false),
+        ]);
+    }
+    trim(start, end, limits) {
+        const { traversal, maximum } = editingTraversal(this, limits);
+        return new SpatialPath(trimPathPoints(traversal, start, end, maximum), false);
+    }
+    subdivide(options) {
+        validateOptions(options);
+        const { traversal, maximum } = editingTraversal(this, options.limits);
+        return new SpatialPath(subdividePathPoints(traversal, options.maxSegmentLength, maximum), this.closed);
+    }
     transform(placement) {
         return new SpatialPath(transformPath3(points3(this), placement), this.closed);
     }
@@ -198,13 +273,15 @@ const SpatialPath = /* @__PURE__ */ immutableMathClass(class SpatialPath {
  * A path input retains its closure. Limits bound construction only; resampling takes its own limits.
  *
  * Use `toData()` for a frozen record that restores coordinates, closure, and dimension together.
+ *
+ * @param input - XY path or finite millimetre coordinates to copy.
+ * @param options - Closure for raw points and construction limits.
  */
 export function path2(input, options = {}) {
     validateOptions(options);
     const limits = resolveGeometrySamplingLimits(options.limits);
     const source = pathSource(input, options.closed, 2);
     const points = snapshot(source.points, 2, limits);
-    validateClosure(points, source.closed);
     return new PlanarPath(points, source.closed);
 }
 /**
@@ -213,6 +290,9 @@ export function path2(input, options = {}) {
  *
  * Use `toData()` for a frozen record that restores coordinates, closure, and dimension together.
  *
+ * @param input - XYZ path or finite millimetre coordinates to copy.
+ * @param options - Closure for raw points and construction limits.
+ *
  * @see {@link path2} for shared construction rules.
  */
 export function path3(input, options = {}) {
@@ -220,7 +300,6 @@ export function path3(input, options = {}) {
     const limits = resolveGeometrySamplingLimits(options.limits);
     const source = pathSource(input, options.closed, 3);
     const points = snapshot(source.points, 3, limits);
-    validateClosure(points, source.closed);
     return new SpatialPath(points, source.closed);
 }
 function validateOptions(options) {

package/dist/geometry/patterns/placements.js

@@ -1,14 +1,14 @@
 import { GeometryError } from "../errors.js";
 import { vector3Data } from "../math/vector-value.js";
 import { cross3, dot3, scale3 } from "../math/vector3.js";
-import { path2InputData, path3InputData, } from "../paths/path-value.js";
-import { distributeAlongPath } from "../paths/planar.js";
-import { restrictTransform3 } from "../transform2.js";
-import { composeTransform3, frameTransform3, IDENTITY_TRANSFORM3, rotationTransform3, translationTransform3, } from "../transform3.js";
+import { distributeAlongPath } from "../paths/distribution.js";
+import { path2InputData, path3InputData, } from "../paths/value.js";
+import { frameTransform3, IDENTITY_TRANSFORM3, multiplyTransform3, rotationTransform3, translationTransform3, } from "../transforms/affine3.js";
+import { restrictTransform3 } from "../transforms/dimensions.js";
 const fail = (operation, message) => {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation });
 };
-export function patternCount(count, operation) {
+function patternCount(count, operation) {
     if (!Number.isSafeInteger(count) || count < 1)
         fail(operation, "Pattern count must be a positive safe integer.");
     if (count > 100_000)
@@ -139,29 +139,30 @@ export function radialPatternPlan(options) {
                 requireDimension(pivot.length, dimension, operation);
             return index === 0
                 ? IDENTITY_TRANSFORM3
-                : composeTransform3(after, composeTransform3(rotationTransform3(axis, { radians: angleRadians * index }), before));
+                : multiplyTransform3(after, multiplyTransform3(rotationTransform3(axis, { radians: angleRadians * index }), before));
         },
     };
 }
 export function gridPatternPlan(options) {
     const operation = "gridPattern";
     optionsObject(options, operation);
-    const dimensions = options.count?.length;
-    if (!Array.isArray(options.count) ||
-        !Array.isArray(options.spacing) ||
-        (dimensions !== 2 && dimensions !== 3) ||
-        options.spacing?.length !== dimensions)
-        fail(operation, "Grid count and spacing require matching XY or XYZ tuples.");
+    const suppliedCounts = options.count;
+    const dimensions = suppliedCounts?.length;
+    if (!Array.isArray(suppliedCounts) || (dimensions !== 2 && dimensions !== 3))
+        fail(operation, "Grid count requires an XY or XYZ integer tuple.");
+    const suppliedSpacing = coordinates(options.spacing, operation);
+    if (suppliedSpacing.length !== dimensions)
+        fail(operation, "Grid spacing must match the count dimension.");
     if (options.center !== undefined && typeof options.center !== "boolean")
         fail(operation, "Grid center must be a boolean.");
     const centered = options.center === true;
-    const counts = [options.count[0], options.count[1], dimensions === 3 ? options.count[2] : 1];
+    const counts = [suppliedCounts[0], suppliedCounts[1], dimensions === 3 ? suppliedCounts[2] : 1];
     counts.forEach((count) => patternCount(count, operation));
     const count = patternCount(counts[0] * counts[1] * counts[2], operation);
     const spacing = [
-        options.spacing[0],
-        options.spacing[1],
-        dimensions === 3 ? options.spacing[2] : 0,
+        suppliedSpacing[0],
+        suppliedSpacing[1],
+        dimensions === 3 ? suppliedSpacing[2] : 0,
     ];
     const extent = spacing.map((distance, axis) => {
         finite(distance, operation);
@@ -169,16 +170,6 @@ export function gridPatternPlan(options) {
             fail(operation, "Repeated grid axes require nonzero spacing.");
         return finite(distance * (counts[axis] - 1), operation);
     });
-    if (options.frame !== undefined) {
-        optionsObject(options.frame, operation);
-        for (const coordinates of [
-            options.frame.origin,
-            options.frame.xAxis,
-            options.frame.yAxis,
-            options.frame.zAxis,
-        ])
-            vector(coordinates, operation);
-    }
     const frame = options.frame === undefined ? IDENTITY_TRANSFORM3 : frameTransform3(options.frame);
     return {
         count,
@@ -193,7 +184,7 @@ export function gridPatternPlan(options) {
                 Math.floor(index / (counts[0] * counts[1])),
             ];
             const offset = coordinates.map((value, axis) => value * spacing[axis] - (centered ? extent[axis] / 2 : 0));
-            return composeTransform3(frame, translationTransform3(offset));
+            return multiplyTransform3(frame, translationTransform3(offset));
         },
     };
 }
@@ -246,7 +237,7 @@ export function pathPatternPlan(input, options, limits) {
                 return translation;
             const tangent = placement.tangent;
             if (dimension === 2)
-                return composeTransform3(translation, rotationTransform3([0, 0, 1], {
+                return multiplyTransform3(translation, rotationTransform3([0, 0, 1], {
                     radians: Math.atan2(tangent[1], tangent[0]),
                 }));
             const cosine = Math.max(-1, Math.min(1, dot3([0, 0, 1], tangent)));
@@ -257,7 +248,7 @@ export function pathPatternPlan(input, options, limits) {
                 : cosine < 0
                     ? rotationTransform3([1, 0, 0], { radians: Math.PI })
                     : IDENTITY_TRANSFORM3;
-            return composeTransform3(translation, rotation);
+            return multiplyTransform3(translation, rotation);
         },
     };
 }

package/dist/geometry/{patterns.js → patterns/transforms.js}

@@ -1,9 +1,10 @@
-import { gridPatternPlan, linearPatternPlan, pathPatternPlan, radialPatternPlan, } from "./patterns/placements.js";
-import { resolveGeometrySamplingLimits } from "./sampling-limits.js";
+import { resolveGeometrySamplingLimits } from "../sampling/limits.js";
+import { transform3 } from "../transforms/value.js";
+import { gridPatternPlan, linearPatternPlan, pathPatternPlan, radialPatternPlan, } from "./placements.js";
 function transforms(plan) {
-    return Object.freeze(Array.from({ length: plan.count }, (_, index) => Object.freeze(plan.transformAt(index))));
+    return Object.freeze(Array.from({ length: plan.count }, (_, index) => transform3(plan.transformAt(index))));
 }
-/** Spatial XYZ matrix placements in millimetres, including the original at the origin. */
+/** Immutable XYZ placements in millimetres, including the original at the origin. */
 export function linearPatternTransforms(options) {
     return transforms(linearPatternPlan(options));
 }
@@ -11,16 +12,19 @@ export function linearPatternTransforms(options) {
 export function radialPatternTransforms(options) {
     return transforms(radialPatternPlan(options));
 }
-/** Spatial XYZ matrices for an XY or XYZ grid, in X-fastest order. */
+/** Immutable XYZ placements for an XY or XYZ grid, in X-fastest order. */
 export function gridPatternTransforms(options) {
     return transforms(gridPatternPlan(options));
 }
 /**
  * Equal physical arc-length placements along a sampled XYZ path.
  *
- * Tangent orientation maps +Z
- * onto the local path tangent; fixed orientation only translates. Closed paths omit a repeated seam.
+ * Tangent orientation maps +Z onto the local path tangent; fixed orientation only translates.
+ * Closed paths omit a repeated seam.
  * Explicit sampling ceilings bound both input points and output placements.
+ *
+ * @param path - XYZ path or points in millimetres; path values supply closure.
+ * @param limits - Limits on input points and output placements.
  */
 export function pathPatternTransforms(path, options, limits) {
     return transforms(pathPatternPlan(path, options, resolveGeometrySamplingLimits(limits)));

package/dist/geometry/primitives/cutters.js

@@ -0,0 +1,70 @@
+import { GeometryError } from "../errors.js";
+import { assertSamplingCount } from "../sampling/limits.js";
+import { edgeTreatmentPointCount, sampleEdgeTreatment } from "./edges.js";
+/** @internal Validates numerical face extension without treating it as a fit allowance. */
+export function cutterExcess(value, operation) {
+    if (!Number.isFinite(value) || value < 0)
+        throw new GeometryError("INVALID_ARGUMENT", "excess must be finite and nonnegative.", {
+            operation,
+        });
+    return value;
+}
+/** @internal Samples only the material-removal side of a convex edge; exterior overlap preserves the treatment. */
+export function edgeCutterContour(treatment, angle, excess, resolution, limits) {
+    const operation = "edgeCutter";
+    if (!Number.isFinite(angle) || angle <= 0 || angle >= 180)
+        throw new GeometryError("INVALID_ARGUMENT", "angle must be strictly between 0 and 180 degrees.", {
+            operation,
+        });
+    cutterExcess(excess, operation);
+    const radians = (angle * Math.PI) / 180;
+    const sampling = { angle: radians, resolution, limits };
+    const count = edgeTreatmentPointCount(treatment, operation, sampling);
+    if (count === 1)
+        return [];
+    assertSamplingCount(count + (excess === 0 ? 1 : 3), operation, limits.maxProfilePoints);
+    const points = sampleEdgeTreatment(treatment, operation, sampling);
+    // A monotone profile passing through the sharp corner leaves both faces unchanged.
+    if (points.some(([first, second]) => first === 0 && second === 0))
+        return [];
+    const cosine = Math.cos(radians), sine = Math.sin(radians);
+    const contour = points.map(([first, second]) => [
+        first + second * cosine,
+        second * sine,
+    ]);
+    if (excess === 0)
+        contour.unshift([0, 0]);
+    else {
+        const first = contour[0], last = contour.at(-1);
+        contour.unshift([-excess * ((1 + cosine) / sine), -excess], [first[0], -excess]);
+        contour.push([last[0] - excess * sine, last[1] + excess * cosine]);
+    }
+    if (contour.some((point) => point.some((coordinate) => !Number.isFinite(coordinate))))
+        throw new GeometryError("INVALID_ARGUMENT", "Cutter coordinates must remain finite.", {
+            operation,
+        });
+    return contour;
+}
+/** @internal Convex corner-removal polytope, capped at each matching edge's setback. */
+export function chamferCornerCutterPoints(distance, excess) {
+    const operation = "cornerCutter";
+    if (!Number.isFinite(distance) || distance < 0)
+        throw new GeometryError("INVALID_ARGUMENT", "Chamfer distance must be finite and nonnegative.", {
+            operation,
+        });
+    cutterExcess(excess, operation);
+    if (distance === 0)
+        return [];
+    return [
+        [-excess, -excess, -excess],
+        [distance, -excess, -excess],
+        [distance, distance, -excess],
+        [-excess, distance, -excess],
+        [-excess, -excess, distance],
+        [distance, -excess, distance],
+        [-excess, distance, distance],
+        [distance, distance, 0],
+        [distance, 0, distance],
+        [0, distance, distance],
+    ];
+}

package/dist/geometry/{cylinder.js → primitives/cylinder.js}

@@ -1,7 +1,7 @@
-import { edgeTreatmentPointCount, edgeTreatmentSetbacks, sampleEdgeTreatment, } from "./edge-finishing.js";
-import { GeometryError } from "./errors.js";
-import { resolveCircularPrimitiveSegments } from "./primitive-resolution.js";
-import { assertSamplingCount, resolveGeometrySamplingLimits } from "./sampling-limits.js";
+import { GeometryError } from "../errors.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits } from "../sampling/limits.js";
+import { edgeTreatmentPointCount, edgeTreatmentSetbacks, sampleEdgeTreatment } from "./edges.js";
+import { resolveCircularPrimitiveSegments } from "./sampling.js";
 const invalid = (message) => {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation: "cylinder" });
 };

package/dist/geometry/{edge-finishing.js → primitives/edges.js}

@@ -1,8 +1,8 @@
-import { GeometryError } from "./errors.js";
-import { resolveModelingLimits } from "./model-limits.js";
-import { resolveCircularPrimitiveSegments } from "./primitive-resolution.js";
-import { resolveGeometryResolution } from "./resolution.js";
-import { assertSamplingCount, resolveGeometrySamplingLimits, } from "./sampling-limits.js";
+import { GeometryError } from "../errors.js";
+import { resolveModelingLimits } from "../limits.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling/limits.js";
+import { resolveGeometryResolution } from "../sampling/resolution.js";
+import { resolveCircularPrimitiveSegments } from "./sampling.js";
 const fail = (operation, message) => {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation });
 };

package/dist/geometry/{primitive-resolvers.js → primitives/resolvers.js}

@@ -1,10 +1,10 @@
-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";
+import { GeometryError } from "../errors.js";
+import { assertMeshAllocationWithinLimits, resolveModelingLimits } from "../limits.js";
+import { vector3Data } from "../math/vector-value.js";
+import { edgeTreatmentPointCount, edgeTreatmentSetbacks, sampleEdgeTreatment } from "./edges.js";
+import { resolveCircularPrimitiveSegments, resolveSphericalPrimitiveSegments } from "./sampling.js";
 /** @internal Face pairs define the twelve nominal box edges in deterministic order. */
-export const boxEdges = [
+const boxEdges = [
     "top-front",
     "top-back",
     "top-left",
@@ -68,7 +68,7 @@ export function assertPositivePrimitive(value, name, operation) {
     }
 }
 /** @internal Resolves one positive scalar radial dimension before sampling or allocation. */
-export function resolvePrimitiveRadius(options, operation) {
+function resolvePrimitiveRadius(options, operation) {
     assertPrimitiveOptions(options, operation);
     if ((options.radius === undefined) === (options.diameter === undefined)) {
         throw new GeometryError("INVALID_ARGUMENT", "Specify exactly one radius or diameter.", {
@@ -186,7 +186,7 @@ export function resolveBoxPrimitive(options) {
                 kind: "round",
                 inner,
                 radius: distance,
-                segments: resolveCircularPrimitiveSegments(distance, treatment, operation),
+                segments: resolveSphericalPrimitiveSegments(distance, treatment, operation),
             },
         };
 }
@@ -236,7 +236,7 @@ export function resolveTubePrimitive(options) {
 /** @internal Resolves sphere sampling shared by compiled and authored adapters. */
 export function resolveSpherePrimitive(options) {
     const radius = resolvePrimitiveRadius(options, "sphere");
-    return { radius, segments: resolveCircularPrimitiveSegments(radius, options, "sphere") };
+    return { radius, segments: resolveSphericalPrimitiveSegments(radius, options, "sphere") };
 }
 /** @internal Resolves torus profile and sweep sampling before allocating kernel geometry. */
 export function resolveTorusPrimitive(options) {

package/dist/geometry/primitives/sampling.js

@@ -0,0 +1,41 @@
+import { GeometryError } from "../errors.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits } from "../sampling/limits.js";
+import { resolveCircularSegments, resolveGeometryResolution } from "../sampling/resolution.js";
+/**
+ * Resolves a circular primitive's exact or adaptive segment count.
+ *
+ * @internal Exact counts override physical sampling, while explicit allocation ceilings still apply.
+ */
+export function resolveCircularPrimitiveSegments(radius, options, operation) {
+    if (options.segments === undefined) {
+        return resolveCircularSegments(radius, {
+            ...options.resolution,
+            sizing: options.sizing ?? "vertex",
+        }, options.limits);
+    }
+    if (!Number.isSafeInteger(options.segments) || options.segments < 3)
+        throw new GeometryError("INVALID_ARGUMENT", "segments must be a safe integer of at least three.", { operation, details: { value: options.segments } });
+    assertSamplingCount(options.segments, operation, resolveGeometrySamplingLimits(options.limits).maxCircularSegments);
+    return options.segments;
+}
+/** @internal Budgets native octahedral sphere triangles, preserving deliberate faceting overrides. */
+export function resolveSphericalPrimitiveSegments(radius, options, operation) {
+    const segments = resolveCircularPrimitiveSegments(radius, options, operation);
+    const limits = resolveGeometrySamplingLimits(options.limits);
+    if (options.segments !== undefined || options.resolution?.circularSegments !== undefined) {
+        const refined = 4 * Math.ceil(segments / 4);
+        assertSamplingCount(refined, operation, limits.maxCircularSegments);
+        return refined;
+    }
+    const policy = resolveGeometryResolution(options.resolution, limits);
+    const error = policy.maxChordError / radius;
+    const diameter = Math.min(error >= 1 ? Infinity : Math.sqrt(3 * error * (2 - error)), policy.maxSegmentLength === undefined ? Infinity : policy.maxSegmentLength / radius);
+    // Manifold 3.5.4 maps each octahedral grid face through sin(pi*x/2), then normalizes.
+    // Its norm is at least sqrt(3)/2, so an edge arc is <= pi*sqrt(2/3)*r/frequency.
+    // A spherical triangle of diameter D stays within r-sqrt(r*r-D*D/3) of the sphere.
+    // https://github.com/elalish/manifold/blob/v3.5.4/src/constructors.cpp#L162-L175
+    const frequency = Math.max(Math.ceil(segments / 4), Math.ceil((Math.PI * Math.sqrt(2 / 3)) / diameter));
+    const refined = 4 * frequency;
+    assertSamplingCount(refined, operation, Math.min(policy.maxSegments, limits.maxCircularSegments));
+    return refined;
+}

package/dist/geometry/profiles/contour.js

@@ -1,12 +1,24 @@
-import { sampleCurve2 } from "../curves/sampling.js";
+import { planarCubicControl } from "../curves/evaluation.js";
+import { sampleCubicControlPoints, sampleCurve2 } from "../curves/sampling.js";
 import { GeometryError } from "../errors.js";
-import { normalizeContour } from "../regions.js";
-import { resolveGeometrySamplingLimits } from "../sampling-limits.js";
+import { normalizeContour } from "../regions/operations.js";
+import { resolveGeometrySamplingLimits } from "../sampling/limits.js";
 import { requireProfileVertexCount } from "./validation.js";
 const OPERATION = "sampleContour";
 function invalid(message) {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation: OPERATION });
 }
+function sampleSpanPoints(span, options) {
+    if (span.kind !== "cubic")
+        return sampleCurve2(span, options).points;
+    const control = planarCubicControl(span);
+    // Constant curves still need the shared sampler's degenerate-tangent rejection.
+    if (control.every((point) => point.every((value, axis) => value === control[0][axis])))
+        return sampleCurve2(span, options).points;
+    const points = [span.start];
+    sampleCubicControlPoints(control, options, (point) => points.push([point[0], point[1]]));
+    return points;
+}
 /**
  * Samples 2–32 connected line/cubic segments into a simple, nonzero-area, immutable CCW XY loop.
  *
@@ -16,8 +28,8 @@ function invalid(message) {
  * `normalizeContour`; this is a single contour without holes. No editor modes or normalized
  * coordinate range are required. No native engine, SDK, or ambient resolution is used.
  *
- * @param curve - Closed contour in millimetres unless positive scales convert its coordinates.
- * @param options - Physical resolution and unique vertex budget; defaults to min(4096, maxProfilePoints).
+ * @param curve - Closed contour in millimetres, or coordinates converted by the selected scales.
+ * @param options - Coordinate scales, physical sampling, and vertex limits.
  * @returns Frozen counterclockwise loop in millimetres, without a repeated seam endpoint.
  * @throws {@link GeometryError} for invalid data, topology, scale, or exceeded sampling budgets.
  *
@@ -89,11 +101,11 @@ export function sampleContour(curve, options = {}) {
         else {
             invalid("Cross-section segments must be lines or cubics.");
         }
-        const sampled = sampleCurve2(span, {
+        const sampled = sampleSpanPoints(span, {
             ...(options.resolution === undefined ? {} : { resolution: options.resolution }),
             maxVertices: remainingVertices,
             limits,
-        }).points;
+        });
         const endIndex = sampled.length - (closed ? 1 : 0);
         for (let pointIndex = 1; pointIndex < endIndex; pointIndex++)
             output.push(sampled[pointIndex]);

package/dist/geometry/profiles/{match-profiles.js → matching.js}

@@ -1,9 +1,9 @@
 import { planarCubicControl } from "../curves/evaluation.js";
 import { resolveLineSegmentCount, resolveUniformCubicSegments } from "../curves/sampling.js";
 import { GeometryError } from "../errors.js";
-import { normalizeRegion, signedContourArea } from "../regions.js";
-import { resolveArcSegments, resolveGeometryResolution } from "../resolution.js";
-import { assertSamplingCount, resolveGeometrySamplingLimits } from "../sampling-limits.js";
+import { normalizeRegion, signedContourArea } from "../regions/operations.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits } from "../sampling/limits.js";
+import { resolveArcSegments, resolveGeometryResolution } from "../sampling/resolution.js";
 import { createProfileSpanSampler } from "./span-sampling.js";
 const isArray = (value) => Array.isArray(value);
 const fail = (message) => {
@@ -62,6 +62,7 @@ const contours = (component) => [
     component.outer,
     ...component.holes,
 ];
+const contourAt = (component, index) => index === 0 ? component.outer : component.holes[index - 1];
 /**
  * Explicitly matches identified component/contour/span topology across a family.
  *
@@ -70,6 +71,8 @@ const contours = (component) => [
  * Input order and winding are preserved. Collapsed spans retain repeated logical slots, which
  * the engine maps to shared physical vertices while omitting degenerate faces.
  *
+ * @param profiles - 1–1000 profiles with matching component, contour, and span IDs, in order.
+ *
  * @example Match named rectangle landmarks
  * ```ts
  * matchProfiles([
@@ -115,7 +118,7 @@ export function matchProfiles(profiles, options = {}) {
             if (component.id !== expected.id || component.holes.length !== expected.holes.length)
                 fail("Profile component identities and hole counts must retain the same order.");
             contours(component).forEach((contour, contourIndex) => {
-                const paired = contours(expected)[contourIndex];
+                const paired = contourAt(expected, contourIndex);
                 if (contour.id !== paired.id ||
                     contour.spans.length !== paired.spans.length ||
                     contour.spans.some((span, index) => span.id !== paired.spans[index].id))
@@ -126,7 +129,7 @@ export function matchProfiles(profiles, options = {}) {
     let pointsPerProfile = 0;
     const sampling = first.components.map((component, componentIndex) => contours(component).map((contour, contourIndex) => contour.spans.map((_, spanIndex) => {
         let count = Math.max(...profiles.map((profile) => {
-            const span = contours(profile.components[componentIndex])[contourIndex].spans[spanIndex];
+            const span = contourAt(profile.components[componentIndex], contourIndex).spans[spanIndex];
             if (span.segments !== undefined)
                 return span.segments;
             const selectedResolution = resolveGeometryResolution({ ...resolution, ...span.resolution }, limits);
@@ -143,7 +146,7 @@ export function matchProfiles(profiles, options = {}) {
         while (true) {
             let checkedCount = count;
             for (const profile of profiles) {
-                const span = contours(profile.components[componentIndex])[contourIndex].spans[spanIndex];
+                const span = contourAt(profile.components[componentIndex], contourIndex).spans[spanIndex];
                 if (span.kind === "cubic" && span.segments === undefined)
                     checkedCount = Math.max(checkedCount, resolveUniformCubicSegments(planarCubicControl(span), resolveGeometryResolution({ ...resolution, ...span.resolution }, limits), cubicBudget, count));
             }

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

@@ -1,4 +1,4 @@
-import { resolveCircularSampling } from "../../circular-sampling.js";
+import { resolveCircularSampling } from "../../sampling/circular.js";
 import { requireProfileVertexCount } from "../validation.js";
 /**
  * Creates an immutable centered CCW circle with +X seam and vertex or face radial sizing.