@metamesh/modeling 0.18.0 → 0.20.0

package/dist/geometry/paths/traversal.js

@@ -0,0 +1,107 @@
+import { GeometryError } from "../errors.js";
+import { interpolateCoordinate } from "../math/interpolation.js";
+const fail = (message, code) => {
+    throw new GeometryError(code, message, { operation: "path" });
+};
+/** Internal finite edge length without a temporary vector. */
+export function pathEdgeLength(a, b) {
+    const length = Math.hypot(b[0] - a[0], b[1] - a[1], (b[2] ?? 0) - (a[2] ?? 0));
+    if (!Number.isFinite(length))
+        fail("Path extent exceeds finite arithmetic.", "NON_FINITE_VALUE");
+    return length;
+}
+/** Internal allocation-free measurement for paths that do not need an arc-length index. */
+export function measurePathLength(points, closed) {
+    let length = 0;
+    const count = closed ? points.length : Math.max(0, points.length - 1);
+    for (let edge = 0; edge < count; edge++) {
+        length += pathEdgeLength(points[edge], points[(edge + 1) % points.length]);
+        if (!Number.isFinite(length))
+            fail("Path length exceeds finite arithmetic.", "NON_FINITE_VALUE");
+    }
+    return length;
+}
+/** Internal index over already captured coordinates; no caller data is retained by public factories. */
+export function createPathTraversal(points, closed) {
+    const cumulative = [0];
+    const count = closed ? points.length : Math.max(0, points.length - 1);
+    let length = 0;
+    let lastNonzeroEdge = -1;
+    for (let edge = 0; edge < count; edge++) {
+        const edgeLength = pathEdgeLength(points[edge], points[(edge + 1) % points.length]);
+        if (edgeLength > 0)
+            lastNonzeroEdge = edge;
+        length += edgeLength;
+        if (!Number.isFinite(length))
+            fail("Path length exceeds finite arithmetic.", "NON_FINITE_VALUE");
+        cumulative.push(length);
+    }
+    return { points, closed, cumulative, length, lastNonzeroEdge };
+}
+/** Internal strict distance check; callers must not silently clamp authored ranges. */
+export function validatePathDistance(distance, length) {
+    if (!Number.isFinite(distance))
+        fail("Path distance must be finite.", "NON_FINITE_VALUE");
+    if (distance < 0 || distance > length)
+        fail("Path distance must be between zero and its total length.", "INVALID_ARGUMENT");
+}
+/**
+ * Internal outgoing-edge lookup. Zero-length edges are skipped; an open final endpoint uses its
+ * incoming edge, and a closed final endpoint uses the outgoing seam. A cursor keeps ordered scans linear.
+ */
+export function locatePathDistance(traversal, distance, cursor) {
+    const { cumulative, length, closed } = traversal;
+    validatePathDistance(distance, length);
+    if (length === 0)
+        fail("A zero-length path has no usable edge.", "DEGENERATE_GEOMETRY");
+    const count = cumulative.length - 1;
+    if (distance === length && !closed) {
+        return { edgeIndex: traversal.lastNonzeroEdge, fraction: 1 };
+    }
+    const target = distance === length ? 0 : distance;
+    let edgeIndex;
+    if (cursor !== undefined && target >= cumulative[cursor]) {
+        edgeIndex = cursor;
+        while (edgeIndex < count - 1 && cumulative[edgeIndex + 1] <= target)
+            edgeIndex++;
+    }
+    else {
+        // Upper bound selects the outgoing edge and skips repeated cumulative distances.
+        let low = 0, high = count - 1;
+        while (low < high) {
+            const middle = Math.floor((low + high) / 2);
+            if (cumulative[middle + 1] <= target)
+                low = middle + 1;
+            else
+                high = middle;
+        }
+        edgeIndex = low;
+    }
+    return {
+        edgeIndex,
+        fraction: (target - cumulative[edgeIndex]) / (cumulative[edgeIndex + 1] - cumulative[edgeIndex]),
+    };
+}
+/** Internal interpolation into owned scratch or output coordinates, preserving exact vertices. */
+export function writePathPoint(traversal, location, result) {
+    const a = traversal.points[location.edgeIndex], b = traversal.points[(location.edgeIndex + 1) % traversal.points.length];
+    for (let axis = 0; axis < 3; axis++)
+        result[axis] = interpolateCoordinate(a[axis] ?? 0, b[axis] ?? 0, location.fraction);
+}
+/** Internal unit edge tangent; coordinate units do not introduce a normalization threshold. */
+export function writePathTangent(traversal, location, result) {
+    const a = traversal.points[location.edgeIndex], b = traversal.points[(location.edgeIndex + 1) % traversal.points.length];
+    let length = pathEdgeLength(a, b);
+    let x = b[0] - a[0], y = b[1] - a[1], z = (b[2] ?? 0) - (a[2] ?? 0);
+    if (length < 2 ** -1022) {
+        // Subnormal hypotenuses lose relative precision; normalize their scaled components instead.
+        const maximum = Math.max(Math.abs(x), Math.abs(y), Math.abs(z));
+        x /= maximum;
+        y /= maximum;
+        z /= maximum;
+        length = Math.hypot(x, y, z);
+    }
+    result[0] = x / length;
+    result[1] = y / length;
+    result[2] = z / length;
+}

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;
+}