@metamesh/modeling 0.18.0 → 0.20.0

package/dist/export/glb.js

@@ -0,0 +1,214 @@
+import { GeometryError } from "../geometry/errors.js";
+import { renderValidatedMesh } from "../geometry/mesh/render-buffers.js";
+import { captureExport } from "./capture.js";
+import { collectExport, createExportWriter } from "./writer.js";
+const alignedLength = (length) => Math.ceil(length / 4) * 4;
+const linearChannel = (value) => value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+function baseColor(color) {
+    return [
+        linearChannel(Number.parseInt(color.slice(1, 3), 16) / 255),
+        linearChannel(Number.parseInt(color.slice(3, 5), 16) / 255),
+        linearChannel(Number.parseInt(color.slice(5, 7), 16) / 255),
+        1,
+    ];
+}
+/**
+ * Serializes captured local meshes as uncompressed glTF 2.0 binary, in metres and Y-up.
+ * Preserves named parts, placement, shared geometry and display appearance. Authored normals take
+ * precedence over crease-aware shading; no engine, renderer or optional compression codec is loaded.
+ *
+ * @param parts - Parts in output order, with local geometry in millimetres and Z-up.
+ */
+export function exportGlb(parts, options = {}) {
+    return collectExport((sink) => writeGlb(parts, sink, options));
+}
+/**
+ * Writes owned GLB chunks with backpressure, cancellation and explicit output limits.
+ * Plans accessor and container lengths before writing, then emits bounded binary chunks.
+ * Hosts own sink completion, scheduling and recovery after a partially written failure.
+ *
+ * @param parts - Parts in output order; mutable geometry is copied before writing.
+ * @param sink - Receives each chunk; return a promise to pause writing.
+ */
+export async function writeGlb(parts, sink, options = {}) {
+    const captured = captureExport(parts, options, "glb");
+    const creaseAngle = options.creaseAngle ?? 20;
+    if (!Number.isFinite(creaseAngle) || creaseAngle < 0 || creaseAngle > 180)
+        throw new GeometryError("INVALID_ARGUMENT", "Crease angle must be from 0 through 180 degrees.", {
+            operation: "exportGlb",
+        });
+    const writer = createExportWriter(captured, sink, "glb");
+    const accessors = [];
+    const bufferViews = [];
+    const attributes = [];
+    const materials = [];
+    const meshes = [];
+    const nodes = [];
+    const geometryAccessors = new Map();
+    const materialIndices = new Map();
+    const meshIndices = new Map();
+    let binaryLength = 0;
+    let lastYield = performance.now();
+    const addAttribute = (data, componentType, type, bounds) => {
+        const byteLength = data.length * (componentType === 5123 ? 2 : 4);
+        const bufferView = bufferViews.length;
+        bufferViews.push({
+            buffer: 0,
+            byteOffset: binaryLength,
+            byteLength,
+            target: type === "SCALAR" ? 34963 : 34962,
+        });
+        binaryLength += alignedLength(byteLength);
+        if (binaryLength > captured.limits.maxOutputBytes || binaryLength >= 0x1_0000_0000)
+            throw new GeometryError("COMPLEXITY_LIMIT", "GLB binary data exceeds the output limits.", {
+                operation: "exportGlb",
+            });
+        attributes.push({ data, componentType, byteLength });
+        const accessor = accessors.length;
+        accessors.push({
+            bufferView,
+            componentType,
+            count: data.length / (type === "VEC3" ? 3 : 1),
+            type,
+            ...bounds,
+        });
+        return accessor;
+    };
+    for (const part of captured.parts) {
+        captured.signal?.throwIfAborted();
+        let geometry = geometryAccessors.get(part.geometry);
+        if (geometry === undefined) {
+            const rendered = part.geometry.normals === undefined
+                ? renderValidatedMesh(part.geometry, creaseAngle)
+                : { ...part.geometry, normals: part.geometry.normals };
+            const min = [Infinity, Infinity, Infinity];
+            const max = [-Infinity, -Infinity, -Infinity];
+            for (let index = 0; index < rendered.positions.length; index += 3)
+                for (let axis = 0; axis < 3; axis += 1) {
+                    min[axis] = Math.min(min[axis], rendered.positions[index + axis]);
+                    max[axis] = Math.max(max[axis], rendered.positions[index + axis]);
+                }
+            const position = addAttribute(rendered.positions, 5126, "VEC3", { min, max });
+            const normal = addAttribute(rendered.normals, 5126, "VEC3");
+            let maximumIndex = 0;
+            for (const index of rendered.indices)
+                maximumIndex = Math.max(maximumIndex, index);
+            // glTF reserves the component type's largest integer for primitive restart.
+            const indices = addAttribute(rendered.indices, maximumIndex < 65_535 ? 5123 : 5125, "SCALAR");
+            geometry = { position, normal, indices };
+            geometryAccessors.set(part.geometry, geometry);
+        }
+        const color = part.color ?? "#ffffff";
+        const materialKey = `${part.materialId ?? ""}:${color.toLowerCase()}`;
+        let material = materialIndices.get(materialKey);
+        if (material === undefined) {
+            material = materials.length;
+            materials.push({
+                ...(part.materialId === undefined
+                    ? {}
+                    : { name: part.materialId, extras: { materialId: part.materialId } }),
+                pbrMetallicRoughness: {
+                    baseColorFactor: baseColor(color),
+                    metallicFactor: 0,
+                    roughnessFactor: 1,
+                },
+            });
+            materialIndices.set(materialKey, material);
+        }
+        const meshKey = `${geometry.position}:${material}`;
+        let mesh = meshIndices.get(meshKey);
+        if (mesh === undefined) {
+            mesh = meshes.length;
+            meshes.push({
+                primitives: [
+                    {
+                        attributes: { POSITION: geometry.position, NORMAL: geometry.normal },
+                        indices: geometry.indices,
+                        material,
+                    },
+                ],
+            });
+            meshIndices.set(meshKey, mesh);
+        }
+        const transform = part.transform;
+        const matrix = Array.from({ length: 16 }, (_, index) => transform[(index % 4) * 4 + Math.floor(index / 4)]);
+        nodes.push({ name: part.id, mesh, matrix });
+        if (performance.now() - lastYield >= 16) {
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            lastYield = performance.now();
+        }
+    }
+    captured.signal?.throwIfAborted();
+    const rootNode = nodes.length;
+    nodes.push({
+        name: captured.name,
+        // Column-major matrix: x'=x/1000, y'=z/1000, z'=-y/1000.
+        matrix: [0.001, 0, 0, 0, 0, 0, -0.001, 0, 0, 0.001, 0, 0, 0, 0, 0, 1],
+        children: Array.from({ length: rootNode }, (_, index) => index),
+    });
+    const json = new TextEncoder().encode(JSON.stringify({
+        asset: { version: "2.0", generator: "MetaMesh" },
+        scene: 0,
+        scenes: [{ name: captured.name, nodes: [rootNode] }],
+        nodes,
+        meshes,
+        materials,
+        accessors,
+        bufferViews,
+        buffers: [{ byteLength: binaryLength }],
+    }));
+    const paddedJsonLength = alignedLength(json.byteLength);
+    const fileLength = 12 + 8 + paddedJsonLength + 8 + binaryLength;
+    if (fileLength >= 0x1_0000_0000 || fileLength > captured.limits.maxOutputBytes)
+        throw new GeometryError("COMPLEXITY_LIMIT", "GLB container exceeds the output limits.", {
+            operation: "exportGlb",
+        });
+    const header = new Uint8Array(20);
+    const headerView = new DataView(header.buffer);
+    headerView.setUint32(0, 0x46546c67, true);
+    headerView.setUint32(4, 2, true);
+    headerView.setUint32(8, fileLength, true);
+    headerView.setUint32(12, paddedJsonLength, true);
+    headerView.setUint32(16, 0x4e4f534a, true);
+    await writer.write(header);
+    const paddedJson = new Uint8Array(paddedJsonLength).fill(0x20);
+    paddedJson.set(json);
+    for (let start = 0; start < paddedJson.length; start += 65_536)
+        await writer.write(paddedJson.slice(start, start + 65_536));
+    const binaryHeader = new Uint8Array(8);
+    const binaryHeaderView = new DataView(binaryHeader.buffer);
+    binaryHeaderView.setUint32(0, binaryLength, true);
+    binaryHeaderView.setUint32(4, 0x004e4942, true);
+    await writer.write(binaryHeader);
+    for (const attribute of attributes) {
+        const width = attribute.componentType === 5123 ? 2 : 4;
+        const elementsPerChunk = 65_536 / width;
+        for (let start = 0; start < attribute.data.length; start += elementsPerChunk) {
+            const count = Math.min(elementsPerChunk, attribute.data.length - start);
+            const chunk = new Uint8Array(count * width);
+            const view = new DataView(chunk.buffer);
+            for (let index = 0; index < count; index += 1) {
+                const value = attribute.data[start + index];
+                if (attribute.componentType === 5126)
+                    view.setFloat32(index * width, value, true);
+                else if (attribute.componentType === 5123)
+                    view.setUint16(index * width, value, true);
+                else
+                    view.setUint32(index * width, value, true);
+            }
+            await writer.write(chunk);
+        }
+        const padding = alignedLength(attribute.byteLength) - attribute.byteLength;
+        if (padding > 0)
+            await writer.write(new Uint8Array(padding));
+    }
+    const diagnostics = [];
+    const assigned = captured.parts.filter((part) => part.materialId !== undefined);
+    if (assigned.length > 0)
+        diagnostics.push({
+            code: "MATERIAL_ASSIGNMENTS_DROPPED",
+            message: "GLB preserves material identities as metadata and appearance, without print material assignment semantics.",
+            partIds: assigned.map((part) => part.id),
+        });
+    return writer.report(diagnostics);
+}

package/dist/export/index.js

@@ -0,0 +1,5 @@
+/** Runtime-independent completed-mesh export. All input coordinates are millimetres, right-handed, and Z-up. @packageDocumentation */
+export { export3mf, write3mf } from "./3mf.js";
+export { exportStl, writeStl } from "./stl.js";
+export { exportGlb, writeGlb } from "./glb.js";
+export { defaultExportLimits } from "./limits.js";

package/dist/export/limits.js

@@ -0,0 +1,18 @@
+import { GeometryError } from "../geometry/errors.js";
+/** Default standalone export policy: 64 parts, one million vertices, two million triangles, 96 MiB input, 512 MiB output. */
+export const defaultExportLimits = Object.freeze({
+    maxParts: 64,
+    maxVertices: 1_000_000,
+    maxTriangles: 2_000_000,
+    maxBytes: 96 * 1024 * 1024,
+    maxOutputBytes: 512 * 1024 * 1024,
+});
+export function resolveExportLimits(overrides = {}) {
+    if (typeof overrides !== "object" || overrides === null || Array.isArray(overrides))
+        throw new GeometryError("INVALID_ARGUMENT", "Export limits must be an object.");
+    const limits = { ...defaultExportLimits, ...overrides };
+    for (const key of Object.keys(defaultExportLimits))
+        if (!Number.isSafeInteger(limits[key]) || limits[key] < 1)
+            throw new GeometryError("INVALID_ARGUMENT", `${key} must be a positive safe integer.`);
+    return Object.freeze(limits);
+}

package/dist/export/stl.js

@@ -0,0 +1,120 @@
+import { GeometryError } from "../geometry/errors.js";
+import { IDENTITY_TRANSFORM3 } from "../geometry/transforms/affine3.js";
+import { captureExport } from "./capture.js";
+import { collectExport, createExportWriter } from "./writer.js";
+const TRIANGLES_PER_CHUNK = 1_024;
+/**
+ * Serializes a captured model as binary STL in millimetres and Z-up coordinates.
+ * Placement is baked into triangles. Diagnostics describe dropped names, appearance and materials.
+ * Mutable input is captured before the first await; no engine or renderer is needed.
+ *
+ * @param parts - Parts in output order, with local geometry in millimetres.
+ */
+export function exportStl(parts, options = {}) {
+    return collectExport((sink) => writeStl(parts, sink, options));
+}
+/**
+ * Writes owned binary STL chunks to a sink, awaiting backpressure after each bounded chunk.
+ * The host owns sink completion and recovery after failure. Honors cancellation and output limits.
+ *
+ * @param parts - Parts in output order; mutable geometry is copied before writing.
+ * @param sink - Receives each chunk; return a promise to pause writing.
+ */
+export async function writeStl(parts, sink, options = {}) {
+    const captured = captureExport(parts, options, "stl");
+    const writer = createExportWriter(captured, sink, "stl");
+    const triangleCount = captured.parts.reduce((total, part) => total + part.geometry.indices.length / 3, 0);
+    const byteLength = 84 + triangleCount * 50;
+    if (triangleCount >= 0x1_0000_0000 || byteLength > captured.limits.maxOutputBytes)
+        throw new GeometryError("COMPLEXITY_LIMIT", "Binary STL exceeds the output limits.", {
+            operation: "exportStl",
+        });
+    const header = new Uint8Array(84);
+    header.set(new TextEncoder().encode(`MetaMesh ${captured.name}`).subarray(0, 80));
+    new DataView(header.buffer).setUint32(80, triangleCount, true);
+    await writer.write(header);
+    let chunk = new Uint8Array(Math.min(TRIANGLES_PER_CHUNK, triangleCount) * 50);
+    let view = new DataView(chunk.buffer);
+    let writtenTriangles = 0;
+    let chunkTriangles = 0;
+    const triangle = new Float32Array(9);
+    for (const part of captured.parts) {
+        const { positions, indices } = part.geometry;
+        const matrix = part.transform;
+        const identity = matrix.every((value, index) => Object.is(value, IDENTITY_TRANSFORM3[index]));
+        for (let offset = 0; offset < indices.length; offset += 3) {
+            for (let corner = 0; corner < 3; corner += 1) {
+                const index = indices[offset + corner] * 3;
+                const x = positions[index];
+                const y = positions[index + 1];
+                const z = positions[index + 2];
+                if (identity) {
+                    // Capture already validated these Float32 values. Match the identity dot product's
+                    // positive zero without repeating its arithmetic for every indexed triangle corner.
+                    triangle[corner * 3] = x === 0 ? 0 : x;
+                    triangle[corner * 3 + 1] = y === 0 ? 0 : y;
+                    triangle[corner * 3 + 2] = z === 0 ? 0 : z;
+                }
+                else
+                    for (let axis = 0; axis < 3; axis += 1) {
+                        const row = axis * 4;
+                        const value = Math.fround(matrix[row] * x + matrix[row + 1] * y + matrix[row + 2] * z + matrix[row + 3]);
+                        if (!Number.isFinite(value))
+                            throw new GeometryError("NON_FINITE_VALUE", "Placed STL positions must fit finite Float32 coordinates.", { operation: "exportStl" });
+                        triangle[corner * 3 + axis] = value;
+                    }
+            }
+            const ux = triangle[3] - triangle[0];
+            const uy = triangle[4] - triangle[1];
+            const uz = triangle[5] - triangle[2];
+            const vx = triangle[6] - triangle[0];
+            const vy = triangle[7] - triangle[1];
+            const vz = triangle[8] - triangle[2];
+            const nx = uy * vz - uz * vy;
+            const ny = uz * vx - ux * vz;
+            const nz = ux * vy - uy * vx;
+            const length = Math.hypot(nx, ny, nz);
+            if (length === 0)
+                throw new GeometryError("DEGENERATE_GEOMETRY", "Placed STL triangles must retain nonzero area in Float32 coordinates.", { operation: "exportStl" });
+            const target = chunkTriangles * 50;
+            view.setFloat32(target, nx === 0 ? 0 : nx / length, true);
+            view.setFloat32(target + 4, ny === 0 ? 0 : ny / length, true);
+            view.setFloat32(target + 8, nz === 0 ? 0 : nz / length, true);
+            for (let index = 0; index < 9; index += 1)
+                view.setFloat32(target + 12 + index * 4, triangle[index], true);
+            view.setUint16(target + 48, 0, true);
+            chunkTriangles += 1;
+            writtenTriangles += 1;
+            if (chunkTriangles * 50 === chunk.byteLength) {
+                await writer.write(chunk);
+                chunkTriangles = 0;
+                if (writtenTriangles < triangleCount) {
+                    chunk = new Uint8Array(Math.min(TRIANGLES_PER_CHUNK, triangleCount - writtenTriangles) * 50);
+                    view = new DataView(chunk.buffer);
+                }
+            }
+        }
+    }
+    const diagnostics = [
+        {
+            code: "PART_NAMES_DROPPED",
+            message: "Binary STL stores triangles without semantic part names.",
+            partIds: captured.parts.map((part) => part.id),
+        },
+    ];
+    const colored = captured.parts.filter((part) => part.color !== undefined);
+    if (colored.length > 0)
+        diagnostics.push({
+            code: "APPEARANCE_DROPPED",
+            message: "Portable binary STL does not preserve display colors.",
+            partIds: colored.map((part) => part.id),
+        });
+    const assigned = captured.parts.filter((part) => part.materialId !== undefined);
+    if (assigned.length > 0)
+        diagnostics.push({
+            code: "MATERIAL_ASSIGNMENTS_DROPPED",
+            message: "Binary STL does not preserve print material assignments.",
+            partIds: assigned.map((part) => part.id),
+        });
+    return writer.report(diagnostics);
+}

package/dist/export/writer.js

@@ -0,0 +1,54 @@
+import { GeometryError } from "../geometry/errors.js";
+const mediaTypes = {
+    "3mf": "model/3mf",
+    stl: "model/stl",
+    glb: "model/gltf-binary",
+};
+/** Shared output accounting and backpressure. Input resources are never passed to the host sink. */
+export function createExportWriter(captured, sink, format) {
+    if (typeof sink !== "function")
+        throw new TypeError("An export sink must be a function.");
+    let byteLength = 0;
+    let lastYield = performance.now();
+    return {
+        async write(chunk) {
+            captured.signal?.throwIfAborted();
+            const chunkLength = chunk.byteLength;
+            if (byteLength + chunkLength > captured.limits.maxOutputBytes)
+                throw new GeometryError("COMPLEXITY_LIMIT", "Encoded export exceeds maxOutputBytes.", {
+                    operation: `export${format}`,
+                });
+            await sink(chunk);
+            // The sink owns this chunk and may transfer/detach its buffer before resolving.
+            byteLength += chunkLength;
+            // Yield to the host's task queue so a Worker can receive cancellation while writing.
+            if (performance.now() - lastYield >= 16) {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+                lastYield = performance.now();
+            }
+            captured.signal?.throwIfAborted();
+        },
+        report(diagnostics = []) {
+            return Object.freeze({
+                mediaType: mediaTypes[format],
+                extension: format,
+                byteLength,
+                diagnostics: Object.freeze([...diagnostics]),
+            });
+        },
+    };
+}
+/** Buffered convenience over the same streaming implementation; allocation is bounded by the writer's output ceiling. */
+export async function collectExport(write) {
+    const chunks = [];
+    const report = await write((chunk) => {
+        chunks.push(chunk);
+    });
+    const bytes = new Uint8Array(report.byteLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return Object.freeze({ ...report, bytes });
+}

package/dist/geometry/{bounds.js → bounds/operations.js}

@@ -1,4 +1,4 @@
-import { GeometryError } from "./errors.js";
+import { GeometryError } from "../errors.js";
 function fail(operation, message) {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation });
 }
@@ -81,6 +81,8 @@ export function fitBounds(source, target, options = {}) {
  *
  * 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 [].
+ *
+ * @param bounds - XYZ bounds in row order, after any part rotation.
  */
 export function layoutRow(bounds, options = {}) {
     const operation = "layoutRow";

package/dist/geometry/{bounds-value.js → bounds/value.js}

@@ -1,7 +1,7 @@
-import { boundsCenter, boundsSize, containsBounds, validateBounds } from "./bounds.js";
-import { GeometryError, isGeometryError } from "./errors.js";
-import { immutableMathClass } from "./math/immutable-value.js";
-import { vector2, vector2Data, vector3, vector3Data, } from "./math/vector-value.js";
+import { GeometryError, isGeometryError } from "../errors.js";
+import { immutableMathClass } from "../math/immutable-value.js";
+import { vector2, vector2Data, vector3, vector3Data, } from "../math/vector-value.js";
+import { boundsCenter, boundsSize, containsBounds, validateBounds } from "./operations.js";
 function fail(dimension, message) {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation: `bounds${dimension}` });
 }
@@ -64,19 +64,19 @@ const PlanarBounds = /* @__PURE__ */ immutableMathClass(class PlanarBounds {
     min;
     max;
     constructor(data) {
-        this.#data = data;
-        this.min = data.min;
-        this.max = data.max;
+        this.min = vector2(data.min);
+        this.max = vector2(data.max);
+        this.#data = Object.freeze({ min: this.min.toData(), max: this.max.toData() });
         Object.freeze(this);
     }
     size() {
-        return vector2(boundsSize(this));
+        return vector2(boundsSize(this.#data));
     }
     center() {
-        return vector2(boundsCenter(this));
+        return vector2(boundsCenter(this.#data));
     }
     containsBounds(other) {
-        return containsBounds(this, other);
+        return containsBounds(this.#data, snapshot(other, 2));
     }
     toData() {
         return this.#data;
@@ -87,19 +87,19 @@ const SpatialBounds = /* @__PURE__ */ immutableMathClass(class SpatialBounds {
     min;
     max;
     constructor(data) {
-        this.#data = data;
-        this.min = data.min;
-        this.max = data.max;
+        this.min = vector3(data.min);
+        this.max = vector3(data.max);
+        this.#data = Object.freeze({ min: this.min.toData(), max: this.max.toData() });
         Object.freeze(this);
     }
     size() {
-        return vector3(boundsSize(this));
+        return vector3(boundsSize(this.#data));
     }
     center() {
-        return vector3(boundsCenter(this));
+        return vector3(boundsCenter(this.#data));
     }
     containsBounds(other) {
-        return containsBounds(this, other);
+        return containsBounds(this.#data, snapshot(other, 3));
     }
     toData() {
         return this.#data;
@@ -111,8 +111,10 @@ const SpatialBounds = /* @__PURE__ */ immutableMathClass(class SpatialBounds {
  * 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 10.0.0 or newer in major 10.
+ * Compiled Generator packages passing these values to host recipes or memo data require
+ * the current Modeling runtime.
+ *
+ * @param input - Ordered extrema, nonnegative size, or an existing XY bounds value to snapshot.
  */
 export function bounds2(input) {
     return new PlanarBounds(snapshot(input, 2));
@@ -123,8 +125,10 @@ export function bounds2(input) {
  * 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 10.0.0 or newer in major 10.
+ * Compiled Generator packages passing these values to host recipes or memo data require
+ * the current Modeling runtime.
+ *
+ * @param input - Ordered extrema, nonnegative size, or an existing XYZ bounds value to snapshot.
  */
 export function bounds3(input) {
     return new SpatialBounds(snapshot(input, 3));

package/dist/geometry/curves/evaluation.js

@@ -1,6 +1,6 @@
 import { GeometryError } from "../errors.js";
 // This parameter-space probe only resolves stationary tangent direction; it does not control
-// geometric sampling tolerance or move output points. Retain its established one-sided behavior.
+// geometric sampling tolerance or move output points.
 const STATIONARY_TANGENT_PROBE = 0.000001;
 /** @internal Shared structured failures for evaluation and sampling. */
 export function curveFailure(code, message) {
@@ -34,7 +34,7 @@ export function curveDistance(a, b) {
         curveFailure("NON_FINITE_VALUE", "Curve extent exceeds finite arithmetic.");
     return result;
 }
-/** @internal Weighted interpolation preserves finite large coordinates and the existing operation order. */
+/** @internal Weighted interpolation avoids overflow between finite large coordinates. */
 export function interpolateCurvePoint(a, b, t, result) {
     result[0] = a[0] * (1 - t) + b[0] * t;
     result[1] = a[1] * (1 - t) + b[1] * t;
@@ -59,7 +59,7 @@ export function curveDirection(a, b, result) {
     result[2] = b[2] - a[2];
     normalizeCurveDirection(result, result);
 }
-/** @internal Bounding distance to the finite chord, using the existing arithmetic order. */
+/** @internal Bounds deviation from the finite chord rather than its infinite supporting line. */
 export function distanceToCurveChord(point, start, end) {
     const extent = curveDistance(start, end);
     if (extent === 0)
@@ -120,8 +120,7 @@ export class CubicEvaluator {
         interpolateCurvePoint(this.#d, this.#e, t, result);
     }
     tangent(t, point, result) {
-        // Profile correspondence needs points only. Tangent-bearing curves calculate these once,
-        // retaining the established derivative arithmetic without allocating unused controls.
+        // Profile correspondence needs points only; calculate derivative controls only for tangents.
         const control = this.#control;
         const derivative = (this.#derivative ??= [
             [control[1][0] - control[0][0], control[1][1] - control[0][1], control[1][2] - control[0][2]],
@@ -136,7 +135,7 @@ export class CubicEvaluator {
             return;
         }
         // At stationary endpoints or cusps, use an outgoing one-sided secant when available.
-        // A fixed small parameter probe retains the previous fallback without an output-spacing dependency.
+        // A fixed parameter probe keeps the fallback independent of output spacing.
         if (t < 1) {
             this.point(Math.min(1, t + STATIONARY_TANGENT_PROBE), this.#probe);
             if (curveDistance(point, this.#probe) > 0) {

package/dist/geometry/curves/sampling.js

@@ -1,5 +1,5 @@
-import { resolveArcSegments, resolveGeometryResolution, } from "../resolution.js";
-import { assertSamplingCount, resolveGeometrySamplingLimits } from "../sampling-limits.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits } from "../sampling/limits.js";
+import { resolveArcSegments, resolveGeometryResolution, } from "../sampling/resolution.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() {
@@ -125,8 +125,8 @@ function sampleArc(curve, options, maximum, createWriter) {
     }
     return writer.finish();
 }
-/** @internal The control hull bounds curve deviation and each sampled edge's physical length. */
-export function cubicControlMeetsPolicy(control, policy) {
+// The control hull bounds curve deviation and each sampled edge's physical length.
+function cubicControlMeetsPolicy(control, policy) {
     const length = curveDistance(control[0], control[1]) +
         curveDistance(control[1], control[2]) +
         curveDistance(control[2], control[3]);
@@ -134,7 +134,8 @@ export function cubicControlMeetsPolicy(control, policy) {
     return (flat <= policy.maxChordError &&
         (policy.maxSegmentLength === undefined || length <= policy.maxSegmentLength));
 }
-/** @internal Profiles use a checked uniform parameter grid instead of an adaptive leaf count.
+/**
+ * @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.
  */
@@ -192,6 +193,20 @@ function resolveCubicParameters(control, options, maximum) {
     }
     return parameters;
 }
+/** @internal Point-only cubic sampling reuses physical subdivision without discarded tangent calculations. */
+export function sampleCubicControlPoints(control, options, append) {
+    for (const point of control)
+        validateCurvePoint3(point);
+    const parameters = resolveCubicParameters(control, options, resolveSamplingBudget(options));
+    const evaluator = new CubicEvaluator(control);
+    const point = [0, 0, 0];
+    // The caller already retains this span's first waypoint.
+    for (let index = 1; index < parameters.length; index++) {
+        const t = parameters[index];
+        evaluator.point(t, point);
+        append(point, t === 1);
+    }
+}
 function sampleCubicBezier(curve, options, maximum, createWriter) {
     const control = [
         validateCurvePoint3(curve.start),
@@ -226,6 +241,10 @@ function sampleCurve(curve, options, createWriter) {
 }
 /**
  * Samples a spatial curve, preserving endpoints and directed unit tangents.
+ *
+ * @param curve - XYZ curve in millimetres; arc angles use degrees.
+ * @param options - Physical sampling or an exact interval count, within vertex limits.
+ *
  * @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
@@ -236,7 +255,12 @@ function sampleCurve(curve, options, createWriter) {
 export function sampleCurve3(curve, options = {}) {
     return sampleCurve(curve, options, createSpatialSampleWriter);
 }
-/** Samples a planar curve with the same guarantees and policy as spatial sampling.
+/**
+ * Samples a planar curve with the same guarantees and policy as spatial sampling.
+ *
+ * @param curve - XY curve in millimetres; arc angles use degrees.
+ * @param options - Physical sampling or an exact interval count, within vertex limits.
+ *
  * @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