@metamesh/modeling 0.18.0 → 0.20.0

package/dist/geometry/{extrusion.js → extrusion/controls.js}

@@ -1,12 +1,27 @@
-import { GeometryError } from "./errors.js";
-import { vector2Data } from "./math/vector-value.js";
-import { assertPositivePrimitive, assertPrimitiveOptions } from "./primitive-resolvers.js";
-import { resolveGeometryResolution } from "./resolution.js";
-import { assertSamplingCount, resolveGeometrySamplingLimits } from "./sampling-limits.js";
+import { GeometryError } from "../errors.js";
+import { vector2Data } from "../math/vector-value.js";
+import { assertPositivePrimitive, assertPrimitiveOptions } from "../primitives/resolvers.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits } from "../sampling/limits.js";
+import { resolveGeometryResolution } from "../sampling/resolution.js";
 const isArray = (value) => Array.isArray(value);
+const extrusionKeys = new Set([
+    "height",
+    "center",
+    "ends",
+    "slices",
+    "limits",
+    "resolution",
+    "scale",
+    "twist",
+]);
 /** @internal Validates shared extrusion controls and expands top scale before kernel allocation. */
 export function resolveExtrusionControls(height, options, operation) {
     assertPrimitiveOptions(options, operation);
+    for (const key of Object.keys(options))
+        if (!extrusionKeys.has(key))
+            throw new GeometryError("INVALID_ARGUMENT", `Unsupported extrusion option: ${key}.`, {
+                operation,
+            });
     assertPositivePrimitive(height, "height", operation);
     if (options.center !== undefined && typeof options.center !== "boolean") {
         throw new GeometryError("INVALID_ARGUMENT", "center must be boolean when supplied.", {
@@ -17,40 +32,46 @@ export function resolveExtrusionControls(height, options, operation) {
     if (!Number.isFinite(twist)) {
         throw new GeometryError("NON_FINITE_VALUE", "twist must be finite.", { operation });
     }
-    const scaleTop = options.scaleTop ?? 1;
-    const values = typeof scaleTop === "number" ? [scaleTop, scaleTop] : vector2Data(scaleTop);
+    const scale = options.scale ?? 1;
+    const values = typeof scale === "number" ? [scale, scale] : vector2Data(scale);
     const scales = [values[0], values[1]];
     if (!Number.isFinite(scales[0]) || !Number.isFinite(scales[1])) {
-        throw new GeometryError("NON_FINITE_VALUE", "scaleTop values must be finite.", { operation });
+        throw new GeometryError("NON_FINITE_VALUE", "scale values must be finite.", { operation });
     }
-    if (options.divisions !== undefined &&
-        (!Number.isSafeInteger(options.divisions) || options.divisions < 0)) {
-        throw new GeometryError("INVALID_ARGUMENT", "divisions must be a nonnegative safe integer.", {
+    if (scales.some((value) => value < 0) || (scales[0] === 0) !== (scales[1] === 0))
+        throw new GeometryError("INVALID_ARGUMENT", "scale must be positive on both axes or zero on both axes for an apex.", { operation });
+    if (options.slices !== undefined &&
+        (!Number.isSafeInteger(options.slices) || options.slices < 1)) {
+        throw new GeometryError("INVALID_ARGUMENT", "slices must be a positive safe integer.", {
             operation,
         });
     }
-    if (options.divisions !== undefined)
-        assertSamplingCount(options.divisions + 2, operation, resolveGeometrySamplingLimits(options.limits).maxPathPoints);
+    if (options.slices !== undefined)
+        assertSamplingCount(options.slices + 1, operation, resolveGeometrySamplingLimits(options.limits).maxPathPoints);
     return { scales, twist, center: options.center ?? false };
 }
 /**
- * Resolves intermediate profile copies for linear extrusion from physical curve resolution.
+ * Resolves longitudinal intervals for ordinary linear extrusion from physical curve resolution.
  *
  * Accepts one XY loop or a filled XY region, including every hole and disconnected component.
- * Exact `divisions`, including zero, override physical sampling. Otherwise chord error bounds
+ * End treatments are unsupported; native finishing inserts its own treatment stations.
+ * Explicit positive `slices` override physical sampling. Otherwise chord error bounds
  * the triangulated side surface, including rotation across each profile edge. Optional segment
- * length bounds station travel including Z. Straight extrusions need no intermediate copies by default.
+ * length bounds station travel including Z. Straight extrusions use one interval by default.
  * Exceeding the selected maxPathPoints ceiling raises `COMPLEXITY_LIMIT` instead of reducing fidelity.
  *
  * @param profile - Ordered XY millimetre contours with implicit closing edges.
  * @param height - Positive extrusion height in millimetres.
- * @param options - Twist, scale, exact divisions, and physical resolution controls.
- * @returns Number of intermediate copies, excluding the two end profiles.
+ * @param options - Twist, scale, exact slices, and physical resolution controls.
+ * @returns Positive interval count, creating one more profile layer than intervals.
  */
-export function resolveExtrusionDivisions(profile, height, options = {}) {
+export function resolveExtrusionSlices(profile, height, options = {}) {
+    assertPrimitiveOptions(options, "resolveExtrusionSlices");
+    if ("ends" in options)
+        throw new GeometryError("INVALID_ARGUMENT", "resolveExtrusionSlices does not support end treatments.", { operation: "resolveExtrusionSlices" });
     if (!isArray(profile) || profile.length === 0)
         throw new GeometryError("INVALID_ARGUMENT", "Extrusion sampling needs an XY loop or region.", {
-            operation: "resolveExtrusionDivisions",
+            operation: "resolveExtrusionSlices",
         });
     const contours = [];
     if (Array.isArray(profile[0]))
@@ -64,25 +85,25 @@ export function resolveExtrusionDivisions(profile, height, options = {}) {
                 !isArray(component.outer) ||
                 !isArray(component.holes))
                 throw new GeometryError("INVALID_ARGUMENT", "Extrusion regions need outer and hole contours.", {
-                    operation: "resolveExtrusionDivisions",
+                    operation: "resolveExtrusionSlices",
                 });
-            assertSamplingCount(count + 3 * (component.holes.length + 1), "resolveExtrusionDivisions", maximum);
+            assertSamplingCount(count + 3 * (component.holes.length + 1), "resolveExtrusionSlices", maximum);
             for (const contour of [component.outer, ...component.holes]) {
                 if (!isArray(contour) || contour.length < 3)
                     throw new GeometryError("INVALID_ARGUMENT", "Extrusion contours need at least three XY points.", {
-                        operation: "resolveExtrusionDivisions",
+                        operation: "resolveExtrusionSlices",
                     });
                 count += contour.length;
-                assertSamplingCount(count, "resolveExtrusionDivisions", maximum);
+                assertSamplingCount(count, "resolveExtrusionSlices", maximum);
                 contours.push(contour);
             }
         }
     }
-    return resolveExtrusionContourDivisions(contours, height, options);
+    return resolveExtrusionContourSlices(contours, height, options);
 }
 /** @internal Shared sampling preflight over explicit contours, without rebuilding filled topology. */
-export function resolveExtrusionContourDivisions(contours, height, options) {
-    const operation = "resolveExtrusionDivisions";
+export function resolveExtrusionContourSlices(contours, height, options) {
+    const operation = "resolveExtrusionSlices";
     const { scales, twist } = resolveExtrusionControls(height, options, operation);
     const limits = resolveGeometrySamplingLimits(options.limits);
     let radius = 0, maximumEdgeLength = 0, profileCount = 0;
@@ -109,8 +130,8 @@ export function resolveExtrusionContourDivisions(contours, height, options) {
             maximumEdgeLength = Math.max(maximumEdgeLength, Math.hypot(next[0] - point[0], next[1] - point[1]));
         }
     }
-    if (options.divisions !== undefined)
-        return options.divisions;
+    if (options.slices !== undefined)
+        return options.slices;
     const policy = resolveGeometryResolution(options.resolution, options.limits);
     const angle = (Math.abs(twist) * Math.PI) / 180;
     const maximumScale = Math.max(1, Math.abs(scales[0]), Math.abs(scales[1]));
@@ -122,11 +143,13 @@ export function resolveExtrusionContourDivisions(contours, height, options) {
     // Uniform untwisted taper is planar. Anisotropic taper can introduce a
     // mixed edge/station derivative even when the vertex trajectories are straight.
     b = (maximumEdgeLength * (maximumScale * angle + Math.abs(scales[0] - scales[1]))) / 4;
-    const chordSegments = policy.circularSegments === undefined
-        ? Math.max(1, Math.ceil((b + Math.hypot(b, 2 * Math.sqrt(a * policy.maxChordError))) /
-            (2 * policy.maxChordError)), Math.ceil((policy.minSegments * Math.abs(twist)) / 360))
-        : Math.max(1, Math.ceil((policy.circularSegments * Math.abs(twist)) / 360));
-    const angularCap = Math.max(1, scales[0] === scales[1] ? 0 : policy.maxSegments, Math.ceil((policy.maxSegments * Math.abs(twist)) / 360));
+    const physicalSlices = Math.max(1, Math.ceil((b + Math.hypot(b, 2 * Math.sqrt(a * policy.maxChordError))) / (2 * policy.maxChordError)));
+    const angularSlices = Math.max(1, Math.ceil(((policy.circularSegments ?? policy.minSegments) * Math.abs(twist)) / 360));
+    // An exact angular schedule does not waive the surface error caused by changing scale.
+    const chordSegments = policy.circularSegments === undefined || scaleChange > 0
+        ? Math.max(physicalSlices, angularSlices)
+        : angularSlices;
+    const angularCap = Math.max(1, scaleChange === 0 ? 0 : policy.maxSegments, Math.ceil((policy.maxSegments * Math.abs(twist)) / 360));
     if (chordSegments > angularCap) {
         throw new GeometryError("COMPLEXITY_LIMIT", "Extrusion surface refinement exceeds the full-circle interval safety limit.", {
             operation,
@@ -143,5 +166,5 @@ export function resolveExtrusionContourDivisions(contours, height, options) {
     const lengthSegments = policy.maxSegmentLength === undefined ? 1 : Math.ceil(travel / policy.maxSegmentLength);
     const segments = Math.max(1, chordSegments, lengthSegments);
     assertSamplingCount(segments + 1, operation, resolveGeometrySamplingLimits(options.limits).maxPathPoints);
-    return segments - 1;
+    return segments;
 }

package/dist/geometry/extrusion/mesh.js

@@ -0,0 +1,92 @@
+import { GeometryError } from "../errors.js";
+import { assertMeshAllocationWithinLimits, resolveModelingLimits } from "../limits.js";
+import { loftMesh } from "../loft/mesh.js";
+import { validateTriangleMesh } from "../mesh/operations.js";
+import { writeMeshVertex } from "../mesh/write-vertex.js";
+import { path2InputData } from "../paths/value.js";
+import { assertPrimitiveOptions } from "../primitives/resolvers.js";
+import { normalizeContour } from "../regions/operations.js";
+import { triangulateContour } from "../regions/triangulation.js";
+import { assertSamplingCount } from "../sampling/limits.js";
+import { resolveExtrusionControls, resolveExtrusionSlices, } from "./controls.js";
+/**
+ * Linearly extrudes one simple profile along +Z with robust ear-clipped caps.
+ * Path2 profiles must be closed; raw point collections have an implicit closing edge.
+ * End treatments are unsupported and reject at runtime. Use Section.extrude for finished ends.
+ *
+ * @param input - Closed XY path or simple contour, in millimetres.
+ *
+ * @example Extrude point data without an engine
+ * ```ts
+ * const outline = rectangleContour({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
+ * mesh.extrude(outline, { height: 8 });
+ * ```
+ */
+export function extrudeMesh(input, options) {
+    assertPrimitiveOptions(options, "extrudeMesh");
+    const { height } = options;
+    const { center, scales, twist } = resolveExtrusionControls(height, options, "extrudeMesh");
+    if ("ends" in options)
+        throw new GeometryError("INVALID_ARGUMENT", "extrudeMesh does not support end treatments. Use Section.extrude instead.", { operation: "extrudeMesh" });
+    if (!Number.isFinite(height) || height <= 0) {
+        throw new GeometryError("INVALID_ARGUMENT", "Extrusion height must be finite and positive.", {
+            operation: "extrudeMesh",
+            details: { height },
+        });
+    }
+    const bottom = center ? -height / 2 : 0;
+    const limits = resolveModelingLimits(options.limits);
+    const profile = path2InputData(input, true, { maxPathPoints: limits.maxProfilePoints }).points;
+    assertSamplingCount(profile.length, "extrudeMesh", limits.maxProfilePoints);
+    const slices = resolveExtrusionSlices(profile, height, options);
+    const count = profile.length * (slices + 1);
+    const triangles = slices * profile.length * 2 + (profile.length - 2) * 2;
+    assertMeshAllocationWithinLimits(count, triangles, (count + triangles) * 12, "extrudeMesh", limits);
+    if (scales[0] === 0) {
+        // A single logical apex is intentional extrusion topology, not a collapsed loft cap.
+        const outline = normalizeContour(profile, true), n = outline.length;
+        const positions = new Float32Array((n * slices + 1) * 3);
+        const indices = new Uint32Array((2 * n * slices - 2) * 3);
+        let cursor = 0;
+        for (let layer = 0; layer < slices; layer++) {
+            const t = layer / slices, angle = ((twist * Math.PI) / 180) * t;
+            const c = Math.cos(angle), s = Math.sin(angle), scale = 1 - t;
+            outline.forEach(([x, y], index) => writeMeshVertex(positions, (layer * n + index) * 3, [scale * (x * c - y * s), scale * (x * s + y * c), bottom + height * t], "extrudeMesh"));
+        }
+        const apex = n * slices;
+        writeMeshVertex(positions, apex * 3, [0, 0, bottom + height], "extrudeMesh");
+        const triangle = (a, b, c) => {
+            indices[cursor++] = a;
+            indices[cursor++] = b;
+            indices[cursor++] = c;
+        };
+        for (let layer = 0; layer < slices; layer++)
+            for (let index = 0; index < n; index++) {
+                const next = (index + 1) % n, a = layer * n + index, b = layer * n + next;
+                if (layer === slices - 1)
+                    triangle(a, b, apex);
+                else {
+                    triangle(a, b, b + n);
+                    triangle(a, b + n, a + n);
+                }
+            }
+        const cap = triangulateContour(outline);
+        for (let i = 0; i < cap.length; i += 3)
+            triangle(cap[i], cap[i + 2], cap[i + 1]);
+        return validateTriangleMesh({ positions, indices: indices.slice(0, cursor) }, { requireClosed: true });
+    }
+    const stations = Array.from({ length: slices + 1 }, (_, index) => {
+        const amount = index / slices;
+        const angle = ((twist * Math.PI) / 180) * amount;
+        const cosine = Math.cos(angle), sine = Math.sin(angle);
+        const sx = 1 + (scales[0] - 1) * amount, sy = 1 + (scales[1] - 1) * amount;
+        return {
+            z: bottom + height * amount,
+            profile: profile.map(([x, y]) => [
+                x * sx * cosine - y * sy * sine,
+                x * sx * sine + y * sy * cosine,
+            ]),
+        };
+    });
+    return loftMesh(stations, { correspondence: "direct", limits });
+}

package/dist/geometry/extrusion/stations.js

@@ -0,0 +1,35 @@
+import { GeometryError } from "../errors.js";
+import { assertSamplingCount } from "../sampling/limits.js";
+/** @internal Combines the requested base intervals with required finishing stations. */
+export function mergeExtrusionStations(height, slices, required, interpolate, limits) {
+    assertSamplingCount(slices + 1, "extrude", limits.maxPathPoints);
+    assertSamplingCount(required.length, "extrude", limits.maxPathPoints);
+    const heights = Array.from({ length: slices + 1 }, (_, i) => ({
+        z: (height * i) / slices,
+        value: undefined,
+    }));
+    for (const value of required) {
+        const { z } = value;
+        if (!Number.isFinite(z) || z < 0 || z > height)
+            throw new GeometryError("INVALID_ARGUMENT", "Extrusion stations must lie within its height.", { operation: "extrude" });
+        heights.push({ z, value });
+    }
+    heights.sort((a, b) => a.z - b.z);
+    const selected = [];
+    const roundoff = Number.EPSILON * Math.max(1, height) * 8;
+    for (const station of heights) {
+        const previous = selected.at(-1);
+        if (previous !== undefined &&
+            (previous.value === undefined || station.value === undefined) &&
+            station.z - previous.z <= roundoff) {
+            // Treatment knots remain authoritative when the base grid lands on the same
+            // mathematical height through a different floating-point expression.
+            if (station.value !== undefined)
+                selected[selected.length - 1] = station;
+        }
+        else
+            selected.push(station);
+    }
+    assertSamplingCount(selected.length, "extrude", limits.maxPathPoints);
+    return selected.map(({ z, value }) => value ?? interpolate(z));
+}

package/dist/geometry/extrusion/twisted-chamfer.js

@@ -0,0 +1,265 @@
+import { GeometryError } from "../errors.js";
+import { assertMeshAllocationWithinLimits } from "../limits.js";
+import { dot2 } from "../math/vector2.js";
+import { planRegionOffsets } from "../regions/offset.js";
+import { assertSamplingCount } from "../sampling/limits.js";
+import { resolveGeometryResolution } from "../sampling/resolution.js";
+import { mergeExtrusionStations } from "./stations.js";
+const fail = (message) => {
+    throw new GeometryError("DEGENERATE_GEOMETRY", message, { operation: "extrude" });
+};
+const segmentDistance = (p, a, b) => {
+    const x = b[0] - a[0], y = b[1] - a[1], squared = x * x + y * y;
+    const t = squared === 0 ? 0 : Math.max(0, Math.min(1, ((p[0] - a[0]) * x + (p[1] - a[1]) * y) / squared));
+    return Math.hypot(p[0] - a[0] - t * x, p[1] - a[1] - t * y);
+};
+/** Intersects the helical wall with a normal section; ds and dz differentiate along the rim and depth. */
+function side(edge, s, depth, rate) {
+    const angle = rate * depth, c = Math.cos(angle), t = Math.tan(angle);
+    return { x: edge.a / c + s * t, ds: t, dz: rate * ((edge.a * t) / c + s / (c * c)) };
+}
+/** Solves the wall's normal-section chord setback and differentiates the resulting bevel slope. */
+function ramp(edge, s, end) {
+    let lo = 0, hi = end.side;
+    let v = end.side / Math.hypot(1, end.rate * s);
+    // Keep Newton steps inside the physical setback bracket; bisect when a step would leave it.
+    for (let i = 0; i < 32; i++) {
+        const point = side(edge, s, v, end.rate), x = point.x - edge.a;
+        const residual = x * x + v * v - end.side * end.side;
+        const derivative = v + x * point.dz;
+        if (!(derivative > 0))
+            fail("Twisted chamfer normal sections fold; reduce twist or chamfer distance.");
+        if (Math.abs(residual) <= end.side * end.side * 1e-12) {
+            const slope = (x + end.width) / v;
+            const dv = (-x * point.ds) / derivative;
+            return { value: slope, derivative: (point.ds + (point.dz - slope) * dv) / v };
+        }
+        if (residual > 0)
+            hi = v;
+        else
+            lo = v;
+        const next = v - residual / (2 * derivative);
+        v = next > lo && next < hi ? next : (lo + hi) / 2;
+    }
+    return fail("Twisted chamfer normal-section setback did not converge.");
+}
+/** Clips the bevel ruling to the helical wall, retaining the active boundary's rim derivative. */
+function limit(edge, s, depth, end) {
+    const wall = side(edge, s, depth, end.rate);
+    if (depth >= end.side)
+        return { value: wall.x, derivative: wall.ds };
+    if (depth === 0)
+        return { value: edge.a - end.width, derivative: 0 };
+    const bevel = ramp(edge, s, end);
+    const value = edge.a - end.width + depth * bevel.value;
+    return value < wall.x
+        ? { value, derivative: depth * bevel.derivative }
+        : { value: wall.x, derivative: wall.ds };
+}
+/** Intersects adjacent clipped strips with a two-variable Newton solve seeded by the inset cap. */
+function corner(a, b, start, depth, end) {
+    let x = start[0], y = start[1];
+    for (let i = 0; i < 24; i++) {
+        const p = [x, y];
+        const av = limit(a, dot2(p, a.t), depth, end), bv = limit(b, dot2(p, b.t), depth, end);
+        const ar = dot2(p, a.n) - av.value, br = dot2(p, b.n) - bv.value;
+        if (Math.max(Math.abs(ar), Math.abs(br)) < 1e-9)
+            return p;
+        const ax = a.n[0] - av.derivative * a.t[0], ay = a.n[1] - av.derivative * a.t[1];
+        const bx = b.n[0] - bv.derivative * b.t[0], by = b.n[1] - bv.derivative * b.t[1];
+        const determinant = ax * by - ay * bx;
+        if (Math.abs(determinant) < 1e-8)
+            fail("Twisted chamfer corner folds; reduce twist or chamfer distance.");
+        x -= (ar * by - br * ay) / determinant;
+        y -= (ax * br - bx * ar) / determinant;
+        if (!Number.isFinite(x + y))
+            break;
+    }
+    return fail("Twisted chamfer corner did not converge; reduce twist or chamfer distance.");
+}
+/** Retains physical corners so redundant logical slots cannot create degenerate side intersections. */
+function physical(source) {
+    const points = source.points.filter((p, i) => {
+        const previous = source.points[(i + source.points.length - 1) % source.points.length];
+        return p[0] !== previous[0] || p[1] !== previous[1];
+    });
+    const retained = points.flatMap((p, i) => {
+        const a = points[(i + points.length - 1) % points.length], b = points[(i + 1) % points.length];
+        const cross = (p[0] - a[0]) * (b[1] - p[1]) - (p[1] - a[1]) * (b[0] - p[0]);
+        const forward = (p[0] - a[0]) * (b[0] - p[0]) + (p[1] - a[1]) * (b[1] - p[1]);
+        return forward <= 0 ||
+            Math.abs(cross) >
+                1e-12 * Math.hypot(p[0] - a[0], p[1] - a[1]) * Math.hypot(b[0] - p[0], b[1] - p[1])
+            ? [p]
+            : [];
+    });
+    return { ...source, points: retained, spans: retained.map((_, i) => `edge-${i}`) };
+}
+/**
+ * Private finished-rim chamfers. Distances are measured in sections normal to each original
+ * rim edge: on the cap and as a straight-line distance to the actual helical wall. Adjacent
+ * strips intersect at their miter; the wall clips each strip at its physical side setback.
+ * No rotated inset-profile approximation or correspondence search is used.
+ * End sizes are [cap setback, normal-section wall setback] in millimetres.
+ * @internal
+ */
+export function twistedChamferStations(input, options, limits, bottomSize, topSize) {
+    const rate = (options.twist * Math.PI) / 180 / options.height;
+    if (Math.abs(rate) * Math.max(bottomSize[1], topSize[1]) > Math.PI / 8)
+        fail("Twisted chamfers need a regular end collar; reduce twist or chamfer distance.");
+    const profile = {
+        components: input.components.map((c) => ({
+            ...c,
+            outer: physical(c.outer),
+            holes: c.holes.map(physical),
+        })),
+    };
+    const offset = planRegionOffsets(profile, [0, Math.max(bottomSize[0], topSize[0])], "extrude", limits);
+    // End caps are fixed seeds for every nonlinear collar solve, including adaptive probes.
+    const prepareEnd = ([width, side], rate) => ({
+        width,
+        side,
+        rate,
+        cap: side === 0 ? [] : offset.profileAt(width).components.flatMap((c) => [c.outer, ...c.holes]),
+    });
+    const bottom = prepareEnd(bottomSize, -rate), top = prepareEnd(topSize, rate);
+    const policy = resolveGeometryResolution(options.resolution, limits);
+    const contours = profile.components.flatMap((c) => [c.outer, ...c.holes]);
+    const radius = contours.reduce((radius, c) => c.points.reduce((radius, p) => Math.max(radius, Math.hypot(...p)), radius), 0);
+    const angleStep = Math.min(Math.PI / 16, Math.sqrt((2 * policy.maxChordError) / Math.max(radius, 1e-12)));
+    // Vertex-arc error <= error/4; the mixed edge/height term <= error/2.
+    // Splitting both axes avoids spending hundreds of axial stations on long flats.
+    const edgeStep = Math.min((policy.maxSegmentLength ?? Infinity) / 2, (2 * policy.maxChordError) / angleStep);
+    const boundaries = contours.map((source) => ({
+        source,
+        edges: source.points.map((p, i) => {
+            const q = source.points[(i + 1) % source.points.length], dx = q[0] - p[0], dy = q[1] - p[1];
+            const length = Math.hypot(dx, dy), t = [dx / length, dy / length], n = [t[1], -t[0]];
+            return { n, t, a: dot2(n, p), length };
+        }),
+        count: [],
+    }));
+    for (const b of boundaries)
+        b.count = b.edges.map((e) => Math.max(1, Math.ceil(e.length / edgeStep)));
+    let intervals = options.slices ??
+        (policy.circularSegments !== undefined
+            ? Math.max(1, Math.ceil((policy.circularSegments * Math.abs(options.twist)) / 360))
+            : Math.max(1, Math.ceil((Math.abs(options.twist) * Math.PI) / 180 / angleStep), Math.ceil((policy.minSegments * Math.abs(options.twist)) / 360)));
+    if (options.slices === undefined &&
+        intervals > Math.max(1, Math.ceil((policy.maxSegments * Math.abs(options.twist)) / 360)))
+        throw new GeometryError("COMPLEXITY_LIMIT", "Twisted extrusion surface refinement exceeds the full-circle interval safety limit.", { operation: "extrude" });
+    if (options.slices === undefined && policy.maxSegmentLength !== undefined)
+        intervals = Math.max(intervals, Math.ceil((options.height * Math.hypot(1, rate * radius) * 2) / policy.maxSegmentLength));
+    let heights = mergeExtrusionStations(options.height, intervals, [
+        ...new Set([
+            0,
+            bottom.side / 2,
+            bottom.side,
+            options.height - top.side,
+            options.height - top.side / 2,
+            options.height,
+        ]),
+    ].map((z) => ({ z })), (z) => ({ z }), limits).map(({ z }) => z);
+    let work = 0;
+    const row = (z) => {
+        if (++work > 2_000_000)
+            throw new GeometryError("COMPLEXITY_LIMIT", "Twisted chamfer sampling exceeds its work ceiling.", { operation: "extrude" });
+        const end = z < bottom.side ? bottom : z > options.height - top.side ? top : undefined;
+        const depth = end === bottom ? z : options.height - z;
+        // Solve each collar in its end-cap frame; the untreated body follows the continuous twist.
+        const angle = end === top ? rate * options.height : end === bottom ? 0 : rate * z;
+        const c = Math.cos(angle), s = Math.sin(angle);
+        const rotate = ([x, y]) => [c * x - s * y, s * x + c * y];
+        return boundaries.map((b, bi) => {
+            const corners = end === undefined
+                ? b.source.points
+                : b.edges.map((edge, i) => corner(b.edges[(i + b.edges.length - 1) % b.edges.length], edge, end.cap[bi].points[i], depth, end));
+            return (edge, u) => {
+                const a = corners[edge], q = corners[(edge + 1) % corners.length];
+                if (end === undefined)
+                    return rotate([a[0] + (q[0] - a[0]) * u, a[1] + (q[1] - a[1]) * u]);
+                const e = b.edges[edge], t = dot2(a, e.t) * (1 - u) + dot2(q, e.t) * u;
+                const n = limit(e, t, depth, end).value;
+                return rotate([e.n[0] * n + e.t[0] * t, e.n[1] * n + e.t[1] * t]);
+            };
+        });
+    };
+    // Check the actual triangulated cells, including mixed edge/height error. Refine the
+    // shared grid, never independently resample rows and move a corner to another slot.
+    for (let iteration = 0; iteration < 20; iteration++) {
+        const points = boundaries.reduce((sum, b) => sum + b.count.reduce((a, b) => a + b, 0), 0);
+        assertSamplingCount(points, "extrude", limits.maxProfilePoints);
+        assertSamplingCount(heights.length, "extrude", limits.maxPathPoints);
+        assertMeshAllocationWithinLimits(points * heights.length, 2 * points * heights.length + 4 * contours.length, 36 * points * heights.length + 48 * contours.length, "extrude", limits);
+        const rows = heights.map(row), split = new Set(), refine = boundaries.map((b) => b.count.map(() => false));
+        for (let zi = 0; zi < heights.length - 1; zi++) {
+            const z0 = heights[zi], z1 = heights[zi + 1];
+            // The untreated screw surface already satisfies the curvature + mixed-error
+            // bound above. Only the nonlinear chamfer collars need adaptive probes.
+            if (z0 >= bottom.side && z1 <= options.height - top.side)
+                continue;
+            const probes = [0.25, 0.5, 0.75].map((t) => ({ t, at: row(z0 + t * (z1 - z0)) }));
+            boundaries.forEach((b, bi) => b.edges.forEach((_, ei) => {
+                for (let j = 0; j < b.count[ei]; j++) {
+                    if (++work > 2_000_000)
+                        throw new GeometryError("COMPLEXITY_LIMIT", "Twisted chamfer sampling exceeds its work ceiling.", { operation: "extrude" });
+                    const u0 = j / b.count[ei], u1 = (j + 1) / b.count[ei], um = (u0 + u1) / 2;
+                    const a = rows[zi][bi](ei, u0), d = rows[zi][bi](ei, u1);
+                    const b0 = rows[zi + 1][bi](ei, u0), c = rows[zi + 1][bi](ei, u1);
+                    const interpolate = (a, b, t) => [
+                        a[0] + t * (b[0] - a[0]),
+                        a[1] + t * (b[1] - a[1]),
+                    ];
+                    let error = 0;
+                    for (const probe of probes) {
+                        // Each triangle cuts this horizontal plane in one of these two segments.
+                        const diagonal = interpolate(a, c, probe.t), left = interpolate(a, b0, probe.t), right = interpolate(d, c, probe.t);
+                        for (const fraction of [0.25, 0.5, 0.75]) {
+                            const actual = probe.at[bi](ei, u0 + fraction * (u1 - u0));
+                            error = Math.max(error, Math.min(segmentDistance(actual, left, diagonal), segmentDistance(actual, diagonal, right)));
+                        }
+                    }
+                    // Ring error refines edge intervals; cell error drives the axial splits below.
+                    const horizontal = Math.max(segmentDistance(rows[zi][bi](ei, um), a, d), segmentDistance(rows[zi + 1][bi](ei, um), b0, c));
+                    const longEdge = policy.maxSegmentLength !== undefined &&
+                        Math.max(Math.hypot(d[0] - a[0], d[1] - a[1]), Math.hypot(c[0] - b0[0], c[1] - b0[1])) > policy.maxSegmentLength;
+                    if (horizontal > policy.maxChordError / 2 || longEdge)
+                        refine[bi][ei] = true;
+                    if (error > policy.maxChordError * 0.75 ||
+                        (policy.maxSegmentLength !== undefined &&
+                            Math.max(Math.hypot(c[0] - a[0], c[1] - a[1], z1 - z0), Math.hypot(b0[0] - a[0], b0[1] - a[1], z1 - z0), Math.hypot(c[0] - d[0], c[1] - d[1], z1 - z0)) > policy.maxSegmentLength))
+                        split.add(zi);
+                }
+            }));
+        }
+        if (split.size === 0 && !refine.some((b) => b.some(Boolean)))
+            return heights.map((z, zi) => {
+                let bi = 0;
+                const contour = (source) => {
+                    const index = bi++, boundary = boundaries[index], points = [], spans = [];
+                    boundary.count.forEach((count, edge) => {
+                        for (let j = 0; j < count; j++) {
+                            points.push(rows[zi][index](edge, j / count));
+                            spans.push(source.spans[edge]);
+                        }
+                    });
+                    return { id: source.id, points, spans };
+                };
+                return {
+                    z: options.center ? z - options.height / 2 : z,
+                    profile: {
+                        components: profile.components.map((c) => ({
+                            ...c,
+                            outer: contour(c.outer),
+                            holes: c.holes.map(contour),
+                        })),
+                    },
+                };
+            });
+        heights = heights.flatMap((z, i) => (split.has(i) ? [z, (z + heights[i + 1]) / 2] : [z]));
+        boundaries.forEach((b, bi) => {
+            b.count = b.count.map((count, ei) => (refine[bi][ei] ? count * 2 : count));
+        });
+    }
+    throw new GeometryError("COMPLEXITY_LIMIT", "Twisted chamfer refinement did not converge at the requested physical resolution.", { operation: "extrude" });
+}

package/dist/geometry/immutable-buffer.js

@@ -5,9 +5,12 @@ const ownedBuffers = new WeakMap();
 const adopted = new WeakMap();
 /**
  * Copies numeric data once into private storage. This pure helper needs no active generation.
+ *
+ * @param source - Caller-owned numeric data; copied into private storage.
+ *
  * @example
  * ```ts
- * import { immutableBuffer } from "@metamesh/modeling";
+ * import { immutableBuffer } from "@metamesh/modeling/geometry";
  * const heights = immutableBuffer(new Float32Array([2, 4, 6]));
  * const count = heights.length;
  * const first = heights.at(0);
@@ -50,16 +53,17 @@ export function ownImmutableBuffer(owned) {
 }
 /**
  * Copies mesh buffers into immutable data; geometric validation still occurs when modeling or finalizing.
+ *
+ * @param mesh - Triangle buffers to copy; the consumer validates topology.
+ *
  * @example
  * ```ts
  * import { generate } from "@metamesh/modeling";
  * import * as mesh from "@metamesh/modeling/geometry/mesh";
- * const model = generate(({ computed, part }) => {
- *   const surface = computed("surface", () => mesh.immutable(mesh.heightfield({
- *     size: [10, 10], segments: [8, 8], height: () => 2,
- *   })));
- *   return [part("surface", surface)];
- * });
+ * const buildSurface = () => mesh.immutable(mesh.heightfield({
+ *   size: [10, 10], segments: [8, 8], height: () => 2,
+ * }));
+ * const model = generate(({ memo, part }) => part("surface", memo(buildSurface)));
  * ```
  */
 export function immutableMesh(mesh) {