@metamesh/modeling 0.0.0-stage → 0.7.0

package/dist/geometry/curves/sampling.js

@@ -0,0 +1,266 @@
+import { resolveArcSegments, resolveGeometryResolution, } from "../resolution.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits } from "../sampling-limits.js";
+import { CubicEvaluator, curveDirection, curveDistance, curveFailure, distanceToCurveChord, interpolateCurvePoint, liftPointTo3D, normalizeCurveDirection, planarCubicControl, splitCubicControl, validateCurvePoint3, } from "./evaluation.js";
+/** @internal Final planar results never create a discarded immutable 3D snapshot. */
+export function createPlanarSampleWriter() {
+    const points = [];
+    const tangents = [];
+    return {
+        append(point, tangent) {
+            points.push(Object.freeze([point[0], point[1]]));
+            tangents.push(Object.freeze([tangent[0], tangent[1]]));
+        },
+        finish: () => Object.freeze({ points: Object.freeze(points), tangents: Object.freeze(tangents) }),
+    };
+}
+/** @internal Scratch buffers and caller-owned endpoints cannot escape through the returned vectors. */
+export function createSpatialSampleWriter() {
+    const points = [];
+    const tangents = [];
+    return {
+        append(point, tangent) {
+            points.push(Object.freeze([...point]));
+            tangents.push(Object.freeze([...tangent]));
+        },
+        finish: () => Object.freeze({ points: Object.freeze(points), tangents: Object.freeze(tangents) }),
+    };
+}
+/** @internal Exact counts override physical resolution, but never the finite output budget. */
+export function resolveSamplingBudget(options) {
+    const selected = resolveGeometrySamplingLimits(options.limits).maxPathPoints;
+    const maximum = options.maximumVertices ?? selected;
+    if (options.maximumVertices !== undefined &&
+        (!Number.isSafeInteger(maximum) || maximum < 2 || maximum > selected))
+        curveFailure("INVALID_ARGUMENT", "maximumVertices must be at least two and cannot raise maxPathPoints.");
+    if (options.segments !== undefined &&
+        (!Number.isSafeInteger(options.segments) || options.segments < 1))
+        curveFailure("INVALID_ARGUMENT", "segments must be a positive safe integer.");
+    return maximum;
+}
+/** @internal Count actual output vertices explicitly, including or omitting the seam as appropriate. */
+export function assertSampleVertexCount(vertexCount, maximum) {
+    assertSamplingCount(vertexCount, "sampleCurve", maximum, "Curve sampling exceeds its selected vertex allocation ceiling.");
+}
+/** @internal A shared physical interval count for straight curves and identified spans. */
+export function resolveLineSegmentCount(length, maximumSegmentLength) {
+    return maximumSegmentLength === undefined
+        ? 1
+        : Math.max(1, Math.ceil(length / maximumSegmentLength));
+}
+function sampleLine(curve, options, maximum, createWriter) {
+    const start = validateCurvePoint3(curve.start);
+    const end = validateCurvePoint3(curve.end);
+    const length = curveDistance(start, end);
+    const tangent = [0, 0, 0];
+    curveDirection(start, end, tangent);
+    const policy = options.segments === undefined
+        ? resolveGeometryResolution(options.resolution, options.limits)
+        : undefined;
+    const segments = options.segments ?? resolveLineSegmentCount(length, policy?.maxSegmentLength);
+    assertSampleVertexCount(segments + 1, maximum);
+    const writer = createWriter();
+    const point = [0, 0, 0];
+    for (let i = 0; i <= segments; i++) {
+        if (i === 0 || i === segments)
+            writer.append(i === 0 ? start : end, tangent);
+        else {
+            interpolateCurvePoint(start, end, i / segments, point);
+            writer.append(point, tangent);
+        }
+    }
+    return writer.finish();
+}
+function validateArc(curve) {
+    validateCurvePoint3(curve.center);
+    validateCurvePoint3(curve.xAxis);
+    validateCurvePoint3(curve.yAxis);
+    if (!Number.isFinite(curve.radius) ||
+        curve.radius <= 0 ||
+        !Number.isFinite(curve.sweepDegrees) ||
+        curve.sweepDegrees === 0 ||
+        Math.abs(curve.sweepDegrees) > 360 ||
+        !Number.isFinite(curve.startDegrees ?? 0))
+        curveFailure("INVALID_ARGUMENT", "Arc radius must be positive and its nonzero degree sweep at most 360.");
+    if (Math.abs(Math.hypot(...curve.xAxis) - 1) > 1e-10 ||
+        Math.abs(Math.hypot(...curve.yAxis) - 1) > 1e-10 ||
+        Math.abs(curve.xAxis[0] * curve.yAxis[0] +
+            curve.xAxis[1] * curve.yAxis[1] +
+            curve.xAxis[2] * curve.yAxis[2]) > 1e-10)
+        curveFailure("INVALID_ARGUMENT", "Spatial arc axes must be orthogonal unit directions.");
+}
+function sampleArc(curve, options, maximum, createWriter) {
+    validateArc(curve);
+    const segments = options.segments ??
+        resolveArcSegments(curve.radius, curve.sweepDegrees, options.resolution, options.limits);
+    assertSampleVertexCount(segments + 1, maximum);
+    const writer = createWriter();
+    const point = [0, 0, 0];
+    const tangent = [0, 0, 0];
+    const firstPoint = [0, 0, 0];
+    const sign = Math.sign(curve.sweepDegrees);
+    for (let i = 0; i <= segments; i++) {
+        const angle = (((curve.startDegrees ?? 0) + (curve.sweepDegrees * i) / segments) * Math.PI) / 180;
+        const cos = Math.cos(angle), sin = Math.sin(angle);
+        if (i === segments && Math.abs(curve.sweepDegrees) === 360) {
+            point[0] = firstPoint[0];
+            point[1] = firstPoint[1];
+            point[2] = firstPoint[2];
+        }
+        else {
+            point[0] = curve.center[0] + curve.radius * (curve.xAxis[0] * cos + curve.yAxis[0] * sin);
+            point[1] = curve.center[1] + curve.radius * (curve.xAxis[1] * cos + curve.yAxis[1] * sin);
+            point[2] = curve.center[2] + curve.radius * (curve.xAxis[2] * cos + curve.yAxis[2] * sin);
+            validateCurvePoint3(point);
+            if (i === 0) {
+                firstPoint[0] = point[0];
+                firstPoint[1] = point[1];
+                firstPoint[2] = point[2];
+            }
+        }
+        tangent[0] = sign * (-curve.xAxis[0] * sin + curve.yAxis[0] * cos);
+        tangent[1] = sign * (-curve.xAxis[1] * sin + curve.yAxis[1] * cos);
+        tangent[2] = sign * (-curve.xAxis[2] * sin + curve.yAxis[2] * cos);
+        normalizeCurveDirection(tangent, tangent);
+        writer.append(point, tangent);
+    }
+    return writer.finish();
+}
+/** @internal The control hull bounds curve deviation and each sampled edge's physical length. */
+export function cubicControlMeetsPolicy(control, policy) {
+    const length = curveDistance(control[0], control[1]) +
+        curveDistance(control[1], control[2]) +
+        curveDistance(control[2], control[3]);
+    const flat = Math.max(distanceToCurveChord(control[1], control[0], control[3]), distanceToCurveChord(control[2], control[0], control[3]));
+    return (flat <= policy.maxChordError &&
+        (policy.maxSegmentLength === undefined || length <= policy.maxSegmentLength));
+}
+/** @internal Profiles use a checked uniform parameter grid instead of an adaptive leaf count.
+ * Every control interval must meet the physical policy, including flatter regions subdivided to
+ * match curved ones. The depth-first traversal retains only one bounded stack, without output points.
+ */
+export function resolveUniformCubicSegments(control, policy, maximum, minimumSegments = 1) {
+    let segments = minimumSegments;
+    for (let depth = 0; depth <= 32; depth += 1) {
+        assertSampleVertexCount(segments, maximum);
+        const pending = [{ control, intervals: segments }];
+        let accepted = true;
+        while (pending.length > 0) {
+            const part = pending.pop();
+            if (part.intervals === 1) {
+                if (!cubicControlMeetsPolicy(part.control, policy)) {
+                    accepted = false;
+                    break;
+                }
+            }
+            else {
+                const leftIntervals = Math.floor(part.intervals / 2);
+                const [left, right] = splitCubicControl(part.control, leftIntervals / part.intervals);
+                pending.push({ control: right, intervals: part.intervals - leftIntervals }, { control: left, intervals: leftIntervals });
+            }
+        }
+        if (accepted)
+            return segments;
+        segments *= 2;
+    }
+    return curveFailure("COMPLEXITY_LIMIT", "Bézier correspondence cannot meet its physical tolerance.");
+}
+function resolveCubicParameters(control, options, maximum) {
+    const parameters = [0];
+    if (options.segments !== undefined) {
+        assertSampleVertexCount(options.segments + 1, maximum);
+        for (let i = 1; i <= options.segments; i++)
+            parameters.push(i / options.segments);
+        return parameters;
+    }
+    const policy = resolveGeometryResolution(options.resolution, options.limits);
+    const pending = [{ control, start: 0, end: 1, depth: 0 }];
+    while (pending.length > 0) {
+        const part = pending.pop();
+        if (cubicControlMeetsPolicy(part.control, policy)) {
+            assertSampleVertexCount(parameters.length + 1, maximum);
+            parameters.push(part.end);
+        }
+        else {
+            // Depth bounds pathological subdivision and parameter midpoints that lose precision.
+            if (part.depth >= 32 || parameters.length + pending.length + 2 > maximum)
+                curveFailure("COMPLEXITY_LIMIT", "Bézier sampling cannot meet the requested physical tolerance within its budget.");
+            const [left, right] = splitCubicControl(part.control);
+            const middle = (part.start + part.end) / 2;
+            // The LIFO stack visits the left interval first, preserving increasing output parameters.
+            pending.push({ control: right, start: middle, end: part.end, depth: part.depth + 1 }, { control: left, start: part.start, end: middle, depth: part.depth + 1 });
+        }
+    }
+    return parameters;
+}
+function sampleCubicBezier(curve, options, maximum, createWriter) {
+    const control = [
+        validateCurvePoint3(curve.start),
+        validateCurvePoint3(curve.control1),
+        validateCurvePoint3(curve.control2),
+        validateCurvePoint3(curve.end),
+    ];
+    const parameters = resolveCubicParameters(control, options, maximum);
+    assertSampleVertexCount(parameters.length, maximum);
+    const evaluator = new CubicEvaluator(control);
+    const writer = createWriter();
+    const point = [0, 0, 0], tangent = [0, 0, 0];
+    for (const t of parameters) {
+        evaluator.point(t, point);
+        evaluator.tangent(t, point, tangent);
+        writer.append(point, tangent);
+    }
+    return writer.finish();
+}
+function sampleCurve(curve, options, createWriter) {
+    const maximum = resolveSamplingBudget(options);
+    switch (curve.kind) {
+        case "line":
+            return sampleLine(curve, options, maximum, createWriter);
+        case "arc":
+            return sampleArc(curve, options, maximum, createWriter);
+        case "cubic":
+            return sampleCubicBezier(curve, options, maximum, createWriter);
+        default:
+            return curveFailure("INVALID_ARGUMENT", "Unsupported curve kind.");
+    }
+}
+/**
+ * Samples a spatial curve, preserving endpoints and directed unit tangents.
+ * @remarks Exact counts use uniform curve parameters, not equal physical distances. Adaptive cubics
+ * bound the full control hull. Full-circle arcs repeat their endpoint; closed polylines do not.
+ * @example
+ * ```ts
+ * const path = sampleCurve3({kind: "cubic", start: [0,0,0], control1: [5,0,0], control2: [5,5,5], end: [10,5,5]});
+ * ```
+ */
+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.
+ * @example
+ * ```ts
+ * const turn = sampleCurve2({kind: "arc", center: [0,0], radius: 10, sweepDegrees: 90});
+ * ```
+ */
+export function sampleCurve2(curve, options = {}) {
+    switch (curve.kind) {
+        case "line":
+            return sampleCurve({ ...curve, start: liftPointTo3D(curve.start), end: liftPointTo3D(curve.end) }, options, createPlanarSampleWriter);
+        case "arc":
+            return sampleCurve({ ...curve, center: liftPointTo3D(curve.center), xAxis: [1, 0, 0], yAxis: [0, 1, 0] }, options, createPlanarSampleWriter);
+        case "cubic": {
+            const [start, control1, control2, end] = planarCubicControl(curve);
+            return sampleCurve({
+                ...curve,
+                start,
+                control1,
+                control2,
+                end,
+            }, options, createPlanarSampleWriter);
+        }
+        default:
+            return curveFailure("INVALID_ARGUMENT", "Unsupported curve kind.");
+    }
+}

package/dist/geometry/curves/types.js

@@ -0,0 +1 @@
+export {};

package/dist/geometry/cylinder.js

@@ -0,0 +1,117 @@
+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";
+const invalid = (message) => {
+    throw new GeometryError("INVALID_ARGUMENT", message, { operation: "cylinder" });
+};
+/** @internal Resolves exactly one cylinder radius or diameter dimension before faceting correction. */
+export const resolveCylinderRadii = (options) => {
+    if ((options.radius === undefined) === (options.diameter === undefined)) {
+        return invalid("Specify exactly one radius or diameter.");
+    }
+    const dimension = options.radius ?? options.diameter;
+    const factor = options.radius === undefined ? 0.5 : 1;
+    if (typeof dimension === "number")
+        return [dimension * factor, dimension * factor];
+    if (!Array.isArray(dimension) || dimension.length !== 2) {
+        return invalid("radius or diameter must be a number or an exact [bottom, top] tuple.");
+    }
+    return [dimension[0] * factor, dimension[1] * factor];
+};
+const pushDistinct = (profile, point) => {
+    const previous = profile.at(-1);
+    if (previous?.[0] !== point[0] || previous[1] !== point[1])
+        profile.push(point);
+};
+/**
+ * Validates and resolves the canonical cylinder contract without allocating kernel objects.
+ *
+ * Exact `segments` are resolved against package limits only and deliberately ignore both an
+ * operation-level `resolution` object and the ambient resolution scope. Treatments use cap inset
+ * and sloped-side setback coordinates; circular roundovers account for the actual corner angle.
+ *
+ * @internal
+ */
+export function resolveCylinderPrimitive(options) {
+    if (typeof options !== "object" || options === null || Array.isArray(options)) {
+        invalid("options must be an object.");
+    }
+    if (!Number.isFinite(options.height) || options.height <= 0) {
+        invalid("height must be finite and positive.");
+    }
+    if (options.center !== undefined && typeof options.center !== "boolean") {
+        invalid("center must be boolean when supplied.");
+    }
+    const [bottomRadius, topRadius] = resolveCylinderRadii(options);
+    if (!Number.isFinite(bottomRadius) ||
+        !Number.isFinite(topRadius) ||
+        bottomRadius < 0 ||
+        topRadius < 0 ||
+        (bottomRadius === 0 && topRadius === 0)) {
+        invalid("radius values must be finite and non-negative, with at least one positive value.");
+    }
+    if (options.ends !== undefined &&
+        (typeof options.ends !== "object" || options.ends === null || Array.isArray(options.ends)))
+        invalid("ends must be an object when supplied.");
+    const radialChange = topRadius - bottomRadius;
+    const sideLength = Math.hypot(radialChange, options.height);
+    if (!Number.isFinite(radialChange) || !Number.isFinite(sideLength))
+        invalid("Cylinder side dimensions must remain finite.");
+    const sideX = radialChange / sideLength, sideZ = options.height / sideLength;
+    const bottomAngle = Math.acos(-sideX), topAngle = Math.acos(sideX);
+    const bottom = options.ends?.bottom, top = options.ends?.top;
+    const bottomSetbacks = bottom === undefined
+        ? [0, 0]
+        : edgeTreatmentSetbacks(bottom, "cylinder", bottomAngle, options.limits);
+    const topSetbacks = top === undefined ? [0, 0] : edgeTreatmentSetbacks(top, "cylinder", topAngle, options.limits);
+    if ((bottom && bottomRadius === 0) || (top && topRadius === 0))
+        invalid("A zero-radius cone apex cannot receive an end treatment.");
+    if ((bottom && bottomSetbacks[0] >= bottomRadius) || (top && topSetbacks[0] >= topRadius))
+        invalid("Each cap setback must be smaller than its corresponding end radius.");
+    if (bottomSetbacks[1] + topSetbacks[1] >= sideLength)
+        invalid("End treatment setbacks must leave positive length on the sloped side.");
+    const maximumRadius = Math.max(bottomRadius, topRadius);
+    const segments = resolveCircularPrimitiveSegments(maximumRadius, options, "cylinder");
+    const center = options.center ?? true;
+    if (bottom === undefined && top === undefined)
+        return { bottomRadius, center, height: options.height, segments, topRadius };
+    const sampling = {
+        ...(options.resolution === undefined ? {} : { resolution: options.resolution }),
+        ...(options.limits === undefined ? {} : { limits: options.limits }),
+    };
+    const profileCount = 2 +
+        (bottom === undefined
+            ? 1
+            : edgeTreatmentPointCount(bottom, "cylinder", { ...sampling, angle: bottomAngle })) +
+        (top === undefined
+            ? 1
+            : edgeTreatmentPointCount(top, "cylinder", { ...sampling, angle: topAngle }));
+    assertSamplingCount(profileCount, "cylinder", resolveGeometrySamplingLimits(options.limits).maxProfilePoints);
+    const bottomPoints = bottom === undefined
+        ? [[0, 0]]
+        : sampleEdgeTreatment(bottom, "cylinder", { ...sampling, angle: bottomAngle });
+    const topPoints = top === undefined
+        ? [[0, 0]]
+        : sampleEdgeTreatment(top, "cylinder", { ...sampling, angle: topAngle });
+    assertSamplingCount(bottomPoints.length + topPoints.length + 2, "cylinder", resolveGeometrySamplingLimits(options.limits).maxProfilePoints);
+    const bottomZ = center ? -options.height / 2 : 0;
+    const topZ = bottomZ + options.height;
+    const profile = [];
+    pushDistinct(profile, [0, bottomZ]);
+    for (const [cap, side] of bottomPoints)
+        pushDistinct(profile, [bottomRadius - cap + sideX * side, bottomZ + sideZ * side]);
+    for (const [cap, side] of [...topPoints].reverse())
+        pushDistinct(profile, [topRadius - cap - sideX * side, topZ - sideZ * side]);
+    pushDistinct(profile, [0, topZ]);
+    if (profile.some(([radius, z]) => !Number.isFinite(radius) || !Number.isFinite(z) || radius < 0))
+        invalid("End treatment profile must remain finite and cannot cross the revolution axis.");
+    return {
+        bottomRadius,
+        center,
+        height: options.height,
+        profile,
+        segments,
+        topRadius,
+    };
+}

package/dist/geometry/edge-finishing.js

@@ -0,0 +1,160 @@
+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";
+const fail = (operation, message) => {
+    throw new GeometryError("INVALID_ARGUMENT", message, { operation });
+};
+const isArray = (value) => Array.isArray(value);
+/** @internal Resolves the actual tangent setbacks before allocation or fit checks. */
+export function edgeTreatmentSetbacks(treatment, operation, angle = Math.PI / 2, limits) {
+    if (typeof treatment !== "object" || treatment === null || Array.isArray(treatment))
+        fail(operation, "An edge treatment must be an object.");
+    let result;
+    if (treatment.kind === "round") {
+        if (!Number.isFinite(treatment.radius))
+            throw new GeometryError("NON_FINITE_VALUE", "Round radius must be finite.", { operation });
+        if (treatment.radius < 0)
+            fail(operation, "Round radius must be nonnegative.");
+        const setback = angle === Math.PI / 2 ? treatment.radius : treatment.radius / Math.tan(angle / 2);
+        result = [setback, setback];
+    }
+    else if (treatment.kind === "chamfer" || treatment.kind === "smooth") {
+        const distance = treatment.distance;
+        if (typeof distance !== "number" && (!Array.isArray(distance) || distance.length !== 2))
+            fail(operation, "Treatment distance must be a number or an exact [first, second] tuple.");
+        result = typeof distance === "number" ? [distance, distance] : distance;
+        if (result.some((value) => !Number.isFinite(value)))
+            throw new GeometryError("NON_FINITE_VALUE", "Treatment setbacks must be finite.", {
+                operation,
+            });
+        if (result.some((value) => value <= 0))
+            fail(operation, "Treatment setbacks must be positive.");
+    }
+    else if (treatment.kind === "profile") {
+        const points = treatment.profile;
+        if (!isArray(points) || points.length < 2)
+            fail(operation, "A treatment profile needs at least two points.");
+        assertSamplingCount(points.length, operation, resolveGeometrySamplingLimits(limits).maxProfilePoints);
+        let previous;
+        for (const point of points) {
+            if (!isArray(point) || point.length !== 2)
+                fail(operation, "Treatment profile points must be XY pairs.");
+            if (point.some((value) => !Number.isFinite(value)))
+                throw new GeometryError("NON_FINITE_VALUE", "Treatment profile points must be finite.", {
+                    operation,
+                });
+            if (point.some((value) => value < 0))
+                fail(operation, "Treatment profile coordinates must be nonnegative.");
+            if (previous &&
+                (point[0] > previous[0] ||
+                    point[1] < previous[1] ||
+                    (point[0] === previous[0] && point[1] === previous[1])))
+                fail(operation, "Treatment profile must decrease its first setback and increase its second without repeated points.");
+            previous = point;
+        }
+        const first = points[0], last = points.at(-1);
+        if (!(first[0] > 0) || first[1] !== 0 || last[0] !== 0 || !(last[1] > 0))
+            fail(operation, "Treatment profile must run from [positive, 0] to [0, positive].");
+        result = [first[0], last[1]];
+    }
+    else
+        return fail(operation, "Unsupported edge treatment kind.");
+    if (result.some((value) => !Number.isFinite(value)))
+        throw new GeometryError("NON_FINITE_VALUE", "Treatment setbacks must remain finite.", {
+            operation,
+        });
+    return result;
+}
+/** @internal Plans one corner before profile or mesh arrays are allocated. */
+export function edgeTreatmentPointCount(treatment, operation, options = {}) {
+    const angle = options.angle ?? Math.PI / 2;
+    if (!Number.isFinite(angle) || angle <= 0 || angle >= Math.PI)
+        fail(operation, "Treatment corner angle must be strictly between zero and 180 degrees.");
+    const [first, second] = edgeTreatmentSetbacks(treatment, operation, angle, options.limits);
+    const limits = resolveGeometrySamplingLimits(options.limits);
+    if (treatment.kind === "profile") {
+        assertSamplingCount(treatment.profile.length, operation, limits.maxProfilePoints);
+        return treatment.profile.length;
+    }
+    if (first === 0 && second === 0)
+        return 1;
+    if (treatment.kind === "chamfer")
+        return 2;
+    const selectedResolution = { ...options.resolution, ...treatment.resolution };
+    const magnification = options.magnification ?? 1;
+    if (!Number.isFinite(magnification) || magnification < 1)
+        fail(operation, "Treatment magnification must be finite and at least one.");
+    selectedResolution.maxChordError = (selectedResolution.maxChordError ?? 0.05) / magnification;
+    if (selectedResolution.maxSegmentLength !== undefined)
+        selectedResolution.maxSegmentLength /= magnification;
+    const selected = {
+        ...treatment,
+        resolution: selectedResolution,
+        limits: resolveModelingLimits(treatment.limits, resolveModelingLimits(limits)),
+    };
+    let intervals;
+    if (treatment.kind === "round") {
+        const full = resolveCircularPrimitiveSegments(Math.max(treatment.radius, Number.MIN_VALUE), selected, operation);
+        intervals = Math.max(1, Math.ceil((full * (Math.PI - angle)) / (2 * Math.PI)));
+    }
+    else {
+        const exact = treatment.segments;
+        const cubicResolution = { ...selected.resolution };
+        delete cubicResolution.circularSegments;
+        const policy = exact === undefined ? resolveGeometryResolution(cubicResolution, selected.limits) : undefined;
+        const curvature = 6 * Math.hypot(first, second); // cubic second derivative bounded by this norm
+        intervals =
+            exact === undefined
+                ? Math.max(1, Math.ceil(Math.sqrt(curvature / (8 * policy.maxChordError))), policy.maxSegmentLength === undefined
+                    ? 1
+                    : Math.ceil((3 * Math.hypot(first, second)) / policy.maxSegmentLength))
+                : exact;
+        if (!Number.isSafeInteger(intervals) || intervals < 1)
+            fail(operation, "Smooth treatment segments must be a positive safe integer.");
+        assertSamplingCount(intervals, operation, Math.min(policy?.maximumSegments ?? selected.limits.maxCircularSegments, selected.limits.maxCircularSegments));
+    }
+    assertSamplingCount(intervals + 1, operation, selected.limits.maxProfilePoints);
+    return intervals + 1;
+}
+/** @internal Samples a convex corner in its two inward surface directions, preserving endpoints. */
+export function sampleEdgeTreatment(treatment, operation, options = {}) {
+    const count = edgeTreatmentPointCount(treatment, operation, options);
+    const angle = options.angle ?? Math.PI / 2;
+    const [first, second] = edgeTreatmentSetbacks(treatment, operation, angle, options.limits);
+    if (treatment.kind === "profile")
+        return treatment.profile.map(([x, y]) => [x, y]);
+    if (count === 1)
+        return [[0, 0]];
+    if (treatment.kind === "chamfer")
+        return [
+            [first, 0],
+            [0, second],
+        ];
+    const intervals = count - 1;
+    const points = [];
+    const cosine = Math.cos(angle), sine = Math.sin(angle);
+    const cx = first, cy = (first * (1 - cosine)) / sine;
+    const start = Math.atan2(-cy, first - cx);
+    for (let index = 0; index <= intervals; index++) {
+        if (index === 0) {
+            points.push([first, 0]);
+            continue;
+        }
+        if (index === intervals) {
+            points.push([0, second]);
+            continue;
+        }
+        const t = index / intervals;
+        if (treatment.kind === "smooth")
+            points.push([first * (1 - t) ** 3, second * t ** 3]);
+        else {
+            const theta = start - t * (Math.PI - angle);
+            const x = cx + treatment.radius * Math.cos(theta), y = cy + treatment.radius * Math.sin(theta);
+            const b = y / sine;
+            points.push([x - b * cosine, b]);
+        }
+    }
+    return points;
+}

package/dist/geometry/errors.js

@@ -0,0 +1,76 @@
+const geometryErrorKey = Symbol.for("@metamesh/modeling/error/2");
+const geometryErrorCodes = {
+    COMPLEXITY_LIMIT: true,
+    DEGENERATE_GEOMETRY: true,
+    INVALID_ARGUMENT: true,
+    INVALID_MESH: true,
+    INVALID_TOPOLOGY: true,
+    INVALID_TOLERANCE: true,
+    NON_FINITE_VALUE: true,
+    SELF_INTERSECTION: true,
+    SINGULAR_TRANSFORM: true,
+    UNSUPPORTED_RUNTIME: true,
+};
+/**
+ * Error raised when a geometry precondition or invariant is not satisfied.
+ *
+ * Callers may use `code` for coarse recovery decisions. Human-facing details
+ * remain in `message`; messages are descriptive but are not a stable API.
+ *
+ * @example
+ * ```ts
+ * const error = new GeometryError("INVALID_ARGUMENT", "Radius must be positive.", {
+ *   operation: "example",
+ *   details: { radius: 0 },
+ * });
+ * ```
+ */
+export class GeometryError extends Error {
+    /** Machine-readable failure category. */
+    code;
+    /** Operation and scalar facts associated with the failure. */
+    context;
+    /**
+     * Creates a geometry error with a stable category, operation, and descriptive message.
+     *
+     * @param code - Machine-readable failure category.
+     * @param message - Human-readable diagnostic message.
+     * @param context - Operation and optional scalar facts. Defaults to `{ operation: "geometry" }`.
+     */
+    constructor(code, message, context = { operation: "geometry" }) {
+        super(message);
+        Object.defineProperty(this, geometryErrorKey, { value: 2 });
+        this.name = "GeometryError";
+        this.code = code;
+        this.context = Object.freeze({
+            ...context,
+            ...(context.details === undefined ? {} : { details: Object.freeze({ ...context.details }) }),
+        });
+    }
+}
+/**
+ * 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.
+ */
+export function isGeometryError(value) {
+    if (!(value instanceof Error))
+        return false;
+    const candidate = value;
+    if (candidate[geometryErrorKey] !== 2 ||
+        typeof candidate.code !== "string" ||
+        !Object.hasOwn(geometryErrorCodes, candidate.code) ||
+        typeof candidate.context !== "object" ||
+        candidate.context === null ||
+        Array.isArray(candidate.context))
+        return false;
+    const context = candidate.context;
+    if (typeof context.operation !== "string")
+        return false;
+    if (context.details === undefined)
+        return true;
+    return (typeof context.details === "object" &&
+        context.details !== null &&
+        !Array.isArray(context.details) &&
+        Object.values(context.details).every((detail) => typeof detail === "boolean" || typeof detail === "number" || typeof detail === "string"));
+}