@metamesh/modeling 0.15.0 → 0.17.0

package/dist/engine/knuckle-hinge-operation.js

@@ -0,0 +1,128 @@
+import { GeometryError } from "../geometry/errors.js";
+import { resolveKnuckleHinge } from "../geometry/mechanical/knuckle-hinge.js";
+import { assertPrimitiveOptions } from "../geometry/primitive-resolvers.js";
+import { assertSamplingCount } from "../geometry/sampling-limits.js";
+/** Composes existing scoped operations after resolving both halves against one host policy. */
+export function createKnuckleHingeOperation(environment, operations) {
+    return (options) => {
+        environment.assertActive();
+        assertPrimitiveOptions(options, "knuckleHinge");
+        const resolved = environment.withResolutionDefaults(options);
+        const d = resolveKnuckleHinge(options, resolved);
+        assertSamplingCount(d.segments * d.spec.knuckleCount * 2, "knuckleHinge", resolved.limits.maxVertices);
+        const invalid = (message) => {
+            throw new GeometryError("INVALID_ARGUMENT", message, { operation: "knuckleHinge" });
+        };
+        const validateHalf = (half = {}) => {
+            assertPrimitiveOptions(half, "knuckleHinge");
+            const chamfer = half.chamfer ?? 0;
+            if (!Number.isFinite(chamfer) ||
+                chamfer < 0 ||
+                2 * chamfer >= d.knuckleLength ||
+                chamfer >= d.minimumBarrelWall)
+                invalid("chamfer must be nonnegative and leave a positive axial band and faceted barrel wall.");
+            const web = half.web;
+            if (web !== undefined) {
+                assertPrimitiveOptions(web, "knuckleHinge");
+                if (web.direction !== "positive-y" && web.direction !== "negative-y")
+                    invalid("Unknown web direction.");
+                if (!Number.isFinite(web.reach) ||
+                    web.reach <= 0 ||
+                    !Number.isFinite(web.thickness) ||
+                    web.thickness <= 0 ||
+                    !Number.isFinite(web.zMin) ||
+                    !Number.isFinite(web.zMin + web.thickness))
+                    invalid("Web dimensions must be finite, with positive reach and thickness.");
+                if (2 * chamfer >= web.thickness ||
+                    2 * Math.SQRT2 * chamfer >= Math.min(d.knuckleLength, web.reach))
+                    invalid("chamfer must leave a positive web band and noncollapsed end contours.");
+                const innerRadius = d.barrelRadius * Math.cos(Math.PI / d.segments);
+                if (web.zMin >= innerRadius || web.zMin + web.thickness <= -innerRadius)
+                    invalid("A web must overlap the interior of its barrel.");
+            }
+            return { chamfer, web };
+        };
+        // Validate both attachments before allocating either half.
+        const a = validateHalf(options.halfA);
+        const b = validateHalf(options.halfB);
+        const axial = (radius, start, length, bore = false, chamfer = 0) => operations.translate(operations.rotate(operations.cylinder({
+            radius,
+            height: length,
+            center: false,
+            segments: d.segments,
+            sizing: bore ? "face" : "vertex",
+            ...(chamfer === 0
+                ? {}
+                : {
+                    ends: {
+                        bottom: { kind: "chamfer", distance: chamfer },
+                        top: { kind: "chamfer", distance: chamfer },
+                    },
+                }),
+        }), [0, 90, 0]), [start, 0, 0]);
+        const buildHalf = (side, { chamfer, web }) => {
+            const features = [];
+            // Use the web bottom as the shared Float32 datum for barrel, web, and mounting bevels.
+            const baseZ = chamfer > 0 && web !== undefined ? web.zMin : 0;
+            const atBase = (solid) => operations.translate(solid, [0, 0, -baseZ]);
+            const webProfile = (web, inset) => {
+                // Parallel offsets finish the exposed tip; the two root corners stay square.
+                const corner = { kind: "chamfer", distance: chamfer + (Math.SQRT2 - 2) * inset };
+                const profile = operations.rectangle({
+                    size: [d.knuckleLength - 2 * inset, web.reach - inset],
+                    center: false,
+                    treatment: [corner, corner, { kind: "square" }, { kind: "square" }],
+                });
+                return operations.scale(operations.translate(profile, [inset, 0]), [
+                    1,
+                    web.direction === "positive-y" ? 1 : -1,
+                ]);
+            };
+            for (const interval of d.knuckles) {
+                if (interval.side !== side)
+                    continue;
+                features.push(atBase(axial(d.barrelRadius, interval.start, interval.length, false, chamfer)));
+                if (web !== undefined) {
+                    features.push(chamfer === 0
+                        ? operations.translate(operations.box({
+                            size: [interval.length, web.reach, web.thickness],
+                            center: false,
+                        }), [
+                            interval.start,
+                            web.direction === "positive-y" ? 0 : -web.reach,
+                            web.zMin - baseZ,
+                        ])
+                        : operations.loft([
+                            [chamfer, 0],
+                            [0, chamfer],
+                            [0, web.thickness - chamfer],
+                            [chamfer, web.thickness],
+                        ].map(([inset, z]) => ({
+                            profile: webProfile(web, inset),
+                            frame: {
+                                origin: [interval.start, 0, z],
+                                xAxis: [1, 0, 0],
+                                yAxis: [0, 1, 0],
+                                zAxis: [0, 0, 1],
+                            },
+                        }))));
+                }
+            }
+            if (side === "a" && d.pin !== null)
+                features.push(atBase(axial(d.pinRadius, d.pin.start, d.pin.length)));
+            // Match the kernel cylinders to the same mesh precision as the explicit web stations.
+            const solid = operations.union(features.map((feature) => chamfer === 0 || web === undefined
+                ? feature
+                : operations.solidFromMesh(environment.analyzedMeshFor(feature).mesh)));
+            // Overtravel is numerical cutter extent, independent of the physical radial/axial allowances.
+            const overtravel = Math.min(d.knuckleLength, d.barrelRadius) * 0.01;
+            const result = side === "a" && d.pin !== null
+                ? solid
+                : operations.subtract(solid, [
+                    atBase(axial(d.boreRadius, -d.spec.length / 2 - overtravel, d.spec.length + 2 * overtravel, true)),
+                ]);
+            return operations.translate(result, [0, 0, baseZ]);
+        };
+        return Object.freeze({ halfA: buildHalf("a", a), halfB: buildHalf("b", b), axis: d.axis });
+    };
+}

package/dist/engine/loft-operations.js

@@ -8,7 +8,7 @@ import { assertSamplingCount } from "../geometry/sampling-limits.js";
 import { correspondingPrimitiveProfiles, rectangularPrimitiveFamily, } from "./primitive-profiles.js";
 import { buildProfileLoftMesh } from "./profile-mesh.js";
 const explicitProfile = (value) => typeof value === "object" && value !== null && "components" in value;
-const pointProfile = (value) => Array.isArray(value) || (typeof value === "object" && value !== null && "toArray" in value);
+const pointProfile = (value) => Array.isArray(value) || (typeof value === "object" && value !== null && "toData" in value);
 const fail = (message) => {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation: "loft" });
 };

package/dist/engine/mechanical-operations.js

@@ -1,6 +1,7 @@
+import { createKnuckleHingeOperation } from "./knuckle-hinge-operation.js";
 import * as kernel from "./native/index.js";
 /** Internal host-bound mechanical operations. */
-export function createMechanicalOperations(environment) {
+export function createMechanicalOperations(environment, construction) {
     const { resolution } = environment;
     const { scope, assertActive, wrapSolid, withResolutionDefaults } = environment;
     const nutOptions = (value) => ({
@@ -9,6 +10,7 @@ export function createMechanicalOperations(environment) {
     });
     // Explicit preflight preserves the stable error operation names exposed by these constructors.
     const operations = {
+        knuckleHinge: createKnuckleHingeOperation(environment, construction),
         threadRidge: (value) => {
             assertActive();
             return wrapSolid(kernel.threadRidge(scope, withResolutionDefaults(value)));

package/dist/engine/modeling-context.js

@@ -1,5 +1,6 @@
 import { resolveGeometryResolution } from "../geometry/resolution.js";
 import { createConstructionOperations } from "./construction-operations.js";
+import { createHoleCutterOperation } from "./hole-cutter-operation.js";
 import { createInspectionOperations } from "./inspection-operations.js";
 import { createMechanicalOperations } from "./mechanical-operations.js";
 import { createOperationEnvironment } from "./operation-environment.js";
@@ -15,7 +16,18 @@ export function createModelingContext(owner, initialResolution) {
         const sections = createSectionOperations(environment, transforms);
         const primitives = createPrimitiveOperations(environment, transforms, sections);
         const construction = createConstructionOperations(environment, sections);
-        const mechanical = createMechanicalOperations(environment);
+        const mechanical = createMechanicalOperations(environment, {
+            cylinder: primitives.cylinder,
+            box: primitives.box,
+            rectangle: primitives.rectangle,
+            scale: transforms.operations.scale,
+            solidFromMesh: construction.solidFromMesh,
+            loft: construction.loft,
+            union: construction.union,
+            rotate: transforms.operations.rotate,
+            translate: transforms.operations.translate,
+            subtract: construction.subtract,
+        });
         const patterns = createPatternOperations(environment, transforms);
         const inspection = createInspectionOperations(environment);
         return Object.freeze({
@@ -27,6 +39,13 @@ export function createModelingContext(owner, initialResolution) {
             ...sections,
             ...primitives,
             ...construction,
+            holeCutter: createHoleCutterOperation(environment, {
+                cylinder: primitives.cylinder,
+                extrude: construction.extrude,
+                loft: construction.loft,
+                translate: transforms.operations.translate,
+                union: construction.union,
+            }),
             ...mechanical,
             ...patterns,
             ...inspection,

package/dist/engine/primitive-operations.js

@@ -1,3 +1,4 @@
+import { resolveCircularSampling } from "../geometry/circular-sampling.js";
 import { resolveCylinderRadii } from "../geometry/cylinder.js";
 import { resolveModelingLimits } from "../geometry/model-limits.js";
 import { assertPrimitiveOptions } from "../geometry/primitive-resolvers.js";
@@ -48,7 +49,15 @@ export function createPrimitiveOperations(environment, transforms, sections) {
             if (value.sizing !== "face")
                 return placedSolid(value, () => kernel.cylinder(scope, resolved), () => cylinderAnchors(value));
             const radii = resolveCylinderRadii(value);
-            const count = resolveCircularSegments(Math.max(...radii), value), correction = 1 / Math.cos(Math.PI / count);
+            const maximumRadius = Math.max(...radii);
+            const sampling = resolveCircularSampling({
+                radius: maximumRadius,
+                sizing: "face",
+                ...(resolved.segments === undefined ? {} : { segments: resolved.segments }),
+                resolution: resolved.resolution,
+                limits: resolved.limits,
+            });
+            const count = sampling.segments, correction = sampling.vertexRadius / maximumRadius;
             return placedSolid(value, () => kernel.cylinder(scope, {
                 height: resolved.height,
                 radius: [radii[0] * correction, radii[1] * correction],
@@ -106,12 +115,16 @@ export function createPrimitiveOperations(environment, transforms, sections) {
                 throwGeometryError("INVALID_ARGUMENT", "circle", "Specify exactly one radius or diameter.");
             const radius = value.radius ?? value.diameter / 2;
             requirePositiveNumber(radius, "circle");
-            const count = resolveCircularSegments(radius, value);
-            requireProfileVertexCount(count, 3, "circle", withResolutionDefaults(value).limits);
-            if (value.sizing !== undefined && value.sizing !== "vertex" && value.sizing !== "face")
-                throwGeometryError("INVALID_ARGUMENT", "circle", "sizing must be vertex or face.");
-            const section = ownSection(module.CrossSection.circle(value.sizing === "face" ? radius / Math.cos(Math.PI / count) : radius, count));
             const resolved = withResolutionDefaults(value);
+            const { segments: count, vertexRadius } = resolveCircularSampling({
+                radius,
+                sizing: value.sizing ?? "vertex",
+                ...(resolved.segments === undefined ? {} : { segments: resolved.segments }),
+                resolution: resolved.resolution,
+                limits: resolved.limits,
+            });
+            requireProfileVertexCount(count, 3, "circle", resolved.limits);
+            const section = ownSection(module.CrossSection.circle(vertexRadius, count));
             environment.rememberAnchors(section, planarAnchors([2 * radius, 2 * radius]));
             return environment.rememberPrimitiveProfile(section, ellipticalSectionProfile([radius, radius], value, resolved.resolution, resolved.limits, value.sizing === "face"));
         }),

package/dist/engine/recipe-realization.js

@@ -36,7 +36,7 @@ export class RecipeRealization {
         const args = this.resolveValue(call.args, true);
         return this.duringNative(() => Reflect.apply(operation, undefined, args));
     }
-    /** Split/component handles share one operation result, even when selected separately. */
+    /** Joint/split/component handles share one operation result, even when selected separately. */
     evaluate(call) {
         if (!this.resolvedCalls.has(call))
             this.resolvedCalls.set(call, this.invoke(call));
@@ -76,7 +76,9 @@ export class RecipeRealization {
             return retained;
         }
         const result = this.evaluate(recipe.call);
-        const selected = recipe.index === undefined ? result : result[recipe.index];
+        const selected = recipe.index === undefined
+            ? result
+            : result[recipe.index];
         this.realized.set(shape, selected);
         return selected;
     }

package/dist/engine/section-operations.js

@@ -43,7 +43,7 @@ export function createSectionOperations(environment, transforms) {
         polygon: (input) => {
             assertActive();
             if (Array.isArray(input) ||
-                (typeof input === "object" && input !== null && "toArray" in input))
+                (typeof input === "object" && input !== null && ("toData" in input || "dimension" in input)))
                 return fromContours([input]);
             if (typeof input !== "object" || input === null)
                 throwGeometryError("INVALID_ARGUMENT", "polygon", "Use an outline or polygon options.");
@@ -118,7 +118,7 @@ export function createSectionOperations(environment, transforms) {
         },
         svgSection: (svg, value = {}) => {
             let result = wrapSection(kernel.regionToCrossSection(scope, preflightSvgRegion(svg, { ...withResolutionDefaults(value), origin: "document" }).region, limits));
-            if ((value.origin ?? "center") === "center") {
+            if (value.fit === undefined && (value.origin ?? "center") === "center") {
                 const bounds = nativeSection(result).bounds();
                 result = translate(result, [
                     -(bounds.min[0] + bounds.max[0]) / 2,

package/dist/engine/transform-operations.js

@@ -1,8 +1,8 @@
 import { attachmentTransform3 } from "../geometry/anchors.js";
 import { vector2Data, vector3Data, } from "../geometry/math/vector-value.js";
 import { assertPrimitiveOptions } from "../geometry/primitive-resolvers.js";
-import { transform2, transform3, } from "../geometry/transform-chain.js";
 import { readTransformMatrix } from "../geometry/transform-matrix.js";
+import { transform2, transform3, } from "../geometry/transform-value.js";
 import { eulerTransform3, scaleTransform3, translationTransform3, validateTransform3, } from "../geometry/transform3.js";
 import * as kernel from "./native/index.js";
 import { transformPrimitiveSectionProfile } from "./primitive-profiles.js";
@@ -160,8 +160,8 @@ export function createTransformOperations(environment) {
     const transform = ((value, placement) => {
         const native = resolveHandle(value);
         const matrix = native.kind === "solid"
-            ? transform3(readTransformMatrix(placement, 3)).toMatrix()
-            : transform2(readTransformMatrix(placement, 2)).toMatrix();
+            ? transform3(readTransformMatrix(placement, 3)).toData()
+            : transform2(readTransformMatrix(placement, 2)).toData();
         if (native.kind === "solid") {
             validateCoordinates(matrix, 16, "transform");
             return environment.preserveAnchors(value, wrapSolid(kernel.transform(scope, native.value, matrix)), matrix);

package/dist/geometry/bounds-value.js

@@ -0,0 +1,121 @@
+import { boundsCenter, boundsSize, containsBounds, validateBounds } from "./bounds.js";
+import { GeometryError } from "./errors.js";
+import { immutableMathClass } from "./math/immutable-value.js";
+import { vector2, vector3 } from "./math/vector-value.js";
+function fail(dimension, message) {
+    throw new GeometryError("INVALID_ARGUMENT", message, { operation: `bounds${dimension}` });
+}
+function snapshot(input, dimension) {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        fail(dimension, "Bounds require extrema or size.");
+    const { size, center } = input;
+    let min, max;
+    // Existing immutable bounds expose size()/center(); only a size value selects construction.
+    if ("size" in input && typeof size !== "function") {
+        if ("min" in input || "max" in input)
+            fail(dimension, "Supply size or min/max, never both.");
+        if (!Array.isArray(size) || size.length !== dimension)
+            fail(dimension, `Size requires ${dimension}D coordinates.`);
+        if (center !== undefined && typeof center !== "boolean")
+            fail(dimension, "center must be boolean.");
+        const coordinates = size;
+        const dimensions = Array.from({ length: dimension }, (_, axis) => {
+            const value = coordinates[axis];
+            if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+                fail(dimension, "Size must be finite and nonnegative.");
+            return value;
+        });
+        const centered = center ?? true;
+        min = dimensions.map((value) => (centered ? -value / 2 : 0));
+        max = dimensions.map((value) => (centered ? value / 2 : value));
+    }
+    else {
+        if (center !== undefined && typeof center !== "function")
+            fail(dimension, "center requires size construction.");
+        const extrema = input;
+        min = extrema.min;
+        max = extrema.max;
+    }
+    if (!Array.isArray(min) ||
+        !Array.isArray(max) ||
+        min.length !== dimension ||
+        max.length !== dimension)
+        fail(dimension, `Bounds require matching ${dimension}D minimum and maximum tuples.`);
+    const copy = (source) => Object.freeze(Array.from({ length: dimension }, (_, axis) => {
+        const value = source[axis];
+        return value === 0 ? 0 : value;
+    }));
+    const data = Object.freeze({ min: copy(min), max: copy(max) });
+    validateBounds(data, `bounds${dimension}`);
+    return data;
+}
+const PlanarBounds = /* @__PURE__ */ immutableMathClass(class PlanarBounds {
+    #data;
+    min;
+    max;
+    constructor(data) {
+        this.#data = data;
+        this.min = data.min;
+        this.max = data.max;
+        Object.freeze(this);
+    }
+    size() {
+        return vector2(boundsSize(this));
+    }
+    center() {
+        return vector2(boundsCenter(this));
+    }
+    containsBounds(other) {
+        return containsBounds(this, other);
+    }
+    toData() {
+        return this.#data;
+    }
+});
+const SpatialBounds = /* @__PURE__ */ immutableMathClass(class SpatialBounds {
+    #data;
+    min;
+    max;
+    constructor(data) {
+        this.#data = data;
+        this.min = data.min;
+        this.max = data.max;
+        Object.freeze(this);
+    }
+    size() {
+        return vector3(boundsSize(this));
+    }
+    center() {
+        return vector3(boundsCenter(this));
+    }
+    containsBounds(other) {
+        return containsBounds(this, other);
+    }
+    toData() {
+        return this.#data;
+    }
+});
+/**
+ * Constructs immutable finite XY bounds from ordered extrema or nonnegative size in millimetres.
+ *
+ * Zero extents are valid. Invalid dimensions, nonfinite coordinates, reversed bounds and
+ * overflowing extents throw `INVALID_ARGUMENT` GeometryError. Use `toData()` for plain records.
+ * Size construction centers on the origin unless `center` is false. Size and extrema are exclusive.
+ * Compiled Generator packages passing these values to host recipes or computed data require
+ * runtime 9.0.0 or newer in major 9.
+ */
+export function bounds2(input) {
+    return new PlanarBounds(snapshot(input, 2));
+}
+/**
+ * Constructs immutable finite XYZ bounds from ordered extrema or nonnegative size in millimetres.
+ *
+ * Zero extents are valid. Invalid dimensions, nonfinite coordinates, reversed bounds and
+ * overflowing extents throw `INVALID_ARGUMENT` GeometryError. Use `toData()` for plain records.
+ * Size construction centers on the origin unless `center` is false. Size and extrema are exclusive.
+ * Compiled Generator packages passing these values to host recipes or computed data require
+ * runtime 9.0.0 or newer in major 9.
+ */
+export function bounds3(input) {
+    return new SpatialBounds(snapshot(input, 3));
+}

package/dist/geometry/bounds.js

@@ -13,7 +13,8 @@ function vector(values, operation) {
         ? Object.freeze([normalized[0], normalized[1]])
         : Object.freeze([normalized[0], normalized[1], normalized[2]]);
 }
-function validate(bounds, operation) {
+/** Internal shared validation for tuple algorithms and immutable bounds snapshots. */
+export function validateBounds(bounds, operation) {
     if (typeof bounds !== "object" ||
         bounds === null ||
         !isArray(bounds.min) ||
@@ -36,41 +37,24 @@ function size(bounds) {
 function center(bounds) {
     return bounds.min.map((value, axis) => value / 2 + bounds.max[axis] / 2);
 }
-export function boundsFromSize(dimensions, options = {}) {
-    const operation = "boundsFromSize";
-    if (!isArray(dimensions) ||
-        (dimensions.length !== 2 && dimensions.length !== 3) ||
-        Array.from(dimensions).some((value) => !Number.isFinite(value) || value < 0))
-        fail(operation, "Bounds dimensions require two or three finite nonnegative values.");
-    if (typeof options !== "object" ||
-        options === null ||
-        isArray(options) ||
-        (options.center !== undefined && typeof options.center !== "boolean"))
-        fail(operation, "Bounds placement requires an optional boolean center value.");
-    const centered = options.center ?? true;
-    return Object.freeze({
-        min: vector(dimensions.map((value) => (centered ? -value / 2 : 0)), operation),
-        max: vector(dimensions.map((value) => (centered ? value / 2 : value)), operation),
-    });
-}
 export function boundsSize(bounds) {
-    validate(bounds, "boundsSize");
+    validateBounds(bounds, "boundsSize");
     return vector(size(bounds), "boundsSize");
 }
 export function boundsCenter(bounds) {
-    validate(bounds, "boundsCenter");
+    validateBounds(bounds, "boundsCenter");
     return vector(center(bounds), "boundsCenter");
 }
 export function containsBounds(outer, inner) {
-    const dimension = validate(outer, "containsBounds");
-    if (validate(inner, "containsBounds") !== dimension)
+    const dimension = validateBounds(outer, "containsBounds");
+    if (validateBounds(inner, "containsBounds") !== dimension)
         fail("containsBounds", "Contained bounds must have the same dimension.");
     return outer.min.every((value, axis) => inner.min[axis] >= value && inner.max[axis] <= outer.max[axis]);
 }
 export function fitBounds(source, target, options = {}) {
     const operation = "fitBounds";
-    const dimension = validate(source, operation);
-    if (validate(target, operation) !== dimension)
+    const dimension = validateBounds(source, operation);
+    if (validateBounds(target, operation) !== dimension)
         fail(operation, "Source and target bounds must have the same dimension.");
     if (typeof options !== "object" || options === null || isArray(options))
         fail(operation, "Fitting options must be an object.");
@@ -94,6 +78,7 @@ export function fitBounds(source, target, options = {}) {
 }
 /**
  * Returns immutable translations for a +X row of finite XYZ bounds with a nonnegative gap.
+ *
  * Each minimum Y/Z becomes zero, and the first minimum X becomes zero. Supply bounds after
  * any intended part rotation; translations apply to those bounds. An empty input returns [].
  */
@@ -106,7 +91,7 @@ export function layoutRow(bounds, options = {}) {
         fail(operation, "Row gap must be finite and nonnegative.");
     let nextX = 0;
     return Object.freeze(Array.from(bounds, (item) => {
-        if (validate(item, operation) !== 3)
+        if (validateBounds(item, operation) !== 3)
             fail(operation, "Row layout requires XYZ bounds.");
         const position = vector([nextX - item.min[0], -item.min[1], -item.min[2]], operation);
         nextX += item.max[0] - item.min[0] + gap;

package/dist/geometry/circular-sampling.js

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

package/dist/geometry/convex-offset.js

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

package/dist/geometry/curves/sampling.js

@@ -237,8 +237,7 @@ export function sampleCurve3(curve, options = {}) {
     return sampleCurve(curve, options, createSpatialSampleWriter);
 }
 /** Samples a planar curve with the same guarantees and policy as spatial sampling.
- * @remarks Private spatial scratch math is shared, while only final planar vectors are copied and
- * frozen. At stationary tangents, outgoing secants are preferred and endpoints use a backward fallback.
+ * @remarks Returned planar points and tangents are copied and frozen. At stationary tangents, outgoing secants are preferred and endpoints use a backward fallback.
  * @example
  * ```ts
  * const turn = sampleCurve2({kind: "arc", center: [0,0], radius: 10, sweepAngle: 90});

package/dist/geometry/errors.js

@@ -50,6 +50,7 @@ export class GeometryError extends Error {
 }
 /**
  * Recognizes structured geometry errors from separately bundled Modeling copies in the same realm.
+ *
  * Ordinary errors and unmarked code-shaped objects are rejected. The marker is execution-local and
  * does not survive structured cloning; worker protocols carry their own serialized error envelope.
  */

package/dist/geometry/heightfield.js

@@ -77,16 +77,27 @@ function planHeightfield(options, limits) {
         facts: Object.freeze({ sampleCount, vertexCount, triangleCount, byteCount }),
     };
 }
-/** Checks grid dimensions, coordinate precision, and allocation bounds before evaluating heights. */
+/**
+ * Checks grid options, Float32 axis precision, and output limits; returns exact mesh buffer counts.
+ *
+ * This pure operation needs no engine and neither evaluates `height` nor allocates mesh buffers.
+ * Successful preflight leaves height values, Float32 base storage, and generated mesh validity to
+ * construction. `byteCount` covers position and index buffers, not total working memory.
+ *
+ * @see {@link heightfieldMesh}
+ */
 export function preflightHeightfield(options, limits = {}) {
     return planHeightfield(options, limits).facts;
 }
 /**
  * Builds a closed indexed mesh from a rectilinear top, matched boundary walls, and flat base.
+ *
  * Heights run once per grid point after preflight; center-error adds one evaluation per cell.
  * Top winding is +Z, the base is -Z, and sides face outward. Coordinates and heights must fit
  * Float32 storage. Explicit axes are captured before sampling; shared wall vertices prevent cracks.
  *
+ * @see {@link preflightHeightfield}
+ *
  * @example Sample a closed wavy mesh
  * ```ts
  * heightfieldMesh({