@metamesh/modeling 0.18.0 → 0.20.0

package/dist/geometry/mechanical/gear-motion.js

@@ -1,5 +1,5 @@
 import { GeometryError } from "../errors.js";
-import { polygonClipping } from "../polygon-clipping.js";
+import { polygonClipping } from "../regions/clipping.js";
 import { resolveCylindricalGearPair, sampleCylindricalGearOutline, sampleInternalCylindricalGearSpaceOutline, } from "./gears.js";
 const DEFAULT_MOTION_SAMPLES = 24;
 const MAXIMUM_MOTION_SAMPLES = 360;
@@ -51,10 +51,12 @@ const multiPolygonArea = (multiPolygon) => multiPolygon.reduce((total, polygon)
  * Measures sampled kinematic interference over one tooth cycle of an internal gear pair.
  *
  * The driver and ring start with half-tooth offsets for odd tooth counts, then rotate in the
- * same direction at their resolved tooth-count ratio. Each
- * sampled pinion outline is subtracted from the ring's center-and-space opening; remaining area is
- * solid overlap. This catches involute, tip, and trimming interference that a single assembled pose
- * misses. It is a deterministic model check, not a certified gear-rating calculation.
+ * same direction at their resolved tooth-count ratio. Subtracting the ring's center-and-space
+ * opening from each sampled pinion outline leaves the area overlapping ring material. This detects
+ * involute, tip, and trimming interference that a single assembled pose misses.
+ * It is a deterministic model check, not a certified gear-rating calculation.
+ *
+ * @param spec - Internal pair: external driver pinion and internal driven ring.
  */
 export function measureInternalCylindricalGearPairMotion(spec, options = {}) {
     if (spec.mesh !== "internal") {

package/dist/geometry/mechanical/gears.js

@@ -1,7 +1,7 @@
 import { GeometryError } from "../errors.js";
-import { signedContourArea } from "../regions.js";
-import { resolveCircularSegments, resolveGeometryResolution, } from "../resolution.js";
-import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
+import { signedContourArea } from "../regions/operations.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling/limits.js";
+import { resolveCircularSegments, resolveGeometryResolution, } from "../sampling/resolution.js";
 const DEFAULT_PRESSURE_ANGLE_DEGREES = 20;
 const DEFAULT_CLEARANCE_FACTOR = 0.25;
 const MAXIMUM_TOOTH_COUNT = 1_000;
@@ -31,6 +31,8 @@ const freezePoints = (points) => {
  *
  * The normal-plane limit is `2 / sin²(alpha_n)`. Helical gears use the standard virtual tooth
  * count `z_v = z / cos³(beta)`, so increasing helix angle can reduce the physical tooth count.
+ *
+ * @param spec - Pressure and signed helix angles in degrees; defaults are 20 and zero.
  */
 export function minimumCylindricalGearToothCountWithoutUndercut(spec = {}) {
     const pressureAngle = finite(spec.pressureAngle ?? DEFAULT_PRESSURE_ANGLE_DEGREES, "Pressure angle", "minimumCylindricalGearToothCountWithoutUndercut");
@@ -177,6 +179,8 @@ const resolveCylindricalGearDimensions = (spec, profile) => {
  * The gear axis is +Z and the returned radii describe its XY pitch plane. Inputs below the
  * pressure- and helix-dependent no-undercut tooth count are rejected because profile shift is not
  * currently supported.
+ *
+ * @param spec - Nominal gear dimensions in millimetres and degrees.
  */
 export function resolveCylindricalGear(spec) {
     return resolveCylindricalGearDimensions(spec, "external");
@@ -187,6 +191,8 @@ export function resolveCylindricalGear(spec) {
  * Both gears must use the same normal module, pressure angle, and helix-angle
  * magnitude. An external pair uses opposite helix hands; an internal pair uses
  * the same hand. The function validates those conjugate pitch invariants.
+ *
+ * @param spec - Driver and driven gears using the same normal pitch system.
  */
 export function resolveCylindricalGearPair(spec) {
     if (spec.mesh !== "external" && spec.mesh !== "internal") {
@@ -413,6 +419,8 @@ const sampleResolvedCylindricalGearOutline = (dimensions, options, operation) =>
  * The returned loop is counter-clockwise, closed implicitly without a repeated
  * seam point, and contains no holes. Its center is the origin and its axis is
  * +Z. Bore, hub, keyway, twist, and face-width choices remain generator-owned.
+ *
+ * @param spec - External gear dimensions in millimetres and degrees; undercut profiles reject.
  */
 export function sampleCylindricalGearOutline(spec, options = {}) {
     return sampleResolvedCylindricalGearOutline(resolveCylindricalGear(spec), options, "sampleCylindricalGearOutline");
@@ -424,11 +432,17 @@ export function sampleCylindricalGearOutline(spec, options = {}) {
  * dedendum above it. At the pitch circle, positive backlash widens each sampled space
  * tangentially. The returned CCW loop encloses the center and is intended to be reversed
  * when used as a region hole.
+ *
+ * @param spec - Internal ring dimensions in millimetres and degrees; backlash widens tooth spaces.
  */
 export function sampleInternalCylindricalGearSpaceOutline(spec, options = {}) {
     return sampleResolvedCylindricalGearOutline(internalCylindricalGearSpaceDimensions(resolveCylindricalGearDimensions(spec, "internal")), options, "sampleInternalCylindricalGearSpaceOutline");
 }
-/** Resolves a rack segment that is conjugate with the same normal cylindrical pitch system. */
+/**
+ * Resolves a rack segment that is conjugate with the same normal cylindrical pitch system.
+ *
+ * @param spec - Rack dimensions in millimetres and degrees.
+ */
 export function resolveRackPitch(spec) {
     const reference = resolveCylindricalGear({
         ...(spec.backlash === undefined ? {} : { backlash: spec.backlash }),
@@ -464,6 +478,9 @@ export function resolveRackPitch(spec) {
  * The path begins and ends on the root line, omits duplicate adjacent points,
  * and leaves base thickness, mounting features, extrusion, and helical sweep to
  * the owning generator.
+ *
+ * @param spec - Rack dimensions in millimetres and degrees, along +X.
+ * @param limits - Sampling limits; exceeding them throws without coarsening.
  */
 export function sampleRackToothPath(spec, limits = {}) {
     const dimensions = resolveRackPitch(spec);

package/dist/geometry/mechanical/knuckle-hinge.js

@@ -1,7 +1,7 @@
 import { GeometryError } from "../errors.js";
-import { assertPositivePrimitive, assertPrimitiveOptions } from "../primitive-resolvers.js";
-import { resolveAlignedCircularSegments } from "../resolution.js";
-import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
+import { assertPositivePrimitive, assertPrimitiveOptions } from "../primitives/resolvers.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling/limits.js";
+import { resolveAlignedCircularSegments } from "../sampling/resolution.js";
 /** @internal Shared fixed frame; ordinary transforms place the joint in a model. */
 export const knuckleHingeAxis = Object.freeze({
     position: Object.freeze([0, 0, 0]),
@@ -19,9 +19,11 @@ const invalid = (message) => {
  * bounds; an insufficient ceiling rejects instead of reducing quality. Exact counts are intentional
  * facets. Zero allowances describe ideal contact, not a printable running fit.
  *
- * Rejects nonfinite or nonpositive dimensions, invalid mode/count combinations, exhausted axial
- * length, missing/excessive lift-off engagement, and nonpositive conservative faceted barrel walls.
+ * Rejects non-finite or non-positive dimensions, invalid mode/count combinations, exhausted axial
+ * length, missing/excessive lift-off engagement, and non-positive conservative faceted barrel walls.
  * Manufacturing minima, strength, mounting, retention, handedness, and motion remain caller policy.
+ *
+ * @param spec - Joint dimensions in millimetres, mode, and knuckle count.
  */
 export function resolveKnuckleHinge(spec, options = {}) {
     assertPrimitiveOptions(spec, "resolveKnuckleHinge");

package/dist/geometry/mechanical/threads/fit.js

@@ -1,5 +1,5 @@
 import { GeometryError } from "../../errors.js";
-import { resolveCircularSegments, resolveGeometryResolution, } from "../../resolution.js";
+import { resolveCircularSegments, resolveGeometryResolution, } from "../../sampling/resolution.js";
 import { resolveGeometryTolerance } from "../../tolerance.js";
 import { compensateThreadProfileForFaceting } from "./profiles.js";
 const frozenFit = (maleRadialInset, femaleRadialOutset, axialBacklash) => Object.freeze({ axialBacklash, femaleRadialOutset, maleRadialInset });
@@ -32,7 +32,11 @@ const validateFitPolicy = (policy) => {
     }
     return Object.freeze({ axialBacklash: axial, femaleRadialOutset: female, maleRadialInset: male });
 };
-/** Resolves and validates a named or caller-defined print-fit policy. */
+/**
+ * Resolves and validates a named or caller-defined print-fit policy.
+ *
+ * @param fit - Named fit or non-negative per-side radial and total axial allowances, in millimetres.
+ */
 export function resolvePrintableThreadFitPolicy(fit = "normal") {
     if (typeof fit !== "string")
         return validateFitPolicy(fit);
@@ -82,6 +86,8 @@ export function compensateThreadDiameters(options) {
  *
  * An exact `circularSegments` value must already be divisible by `starts`; it is never silently
  * raised. Adaptive policies align upward and fail if that would exceed `maxSegments`.
+ *
+ * @param options - Nominal diameter, uncompensated profile, and shared mating resolution.
  */
 export function resolveThreadCircularSegments(options) {
     const operation = "resolveThreadCircularSegments";

package/dist/geometry/mechanical/threads/helices.js

@@ -1,10 +1,12 @@
 /** Conventional thread helix sampling, independent of surface construction. */
 import { GeometryError } from "../../errors.js";
-import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../../sampling-limits.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../../sampling/limits.js";
 import { assertFiniteThreadNumber } from "./profiles.js";
 /**
  * Samples evenly phased thread helices with finite `lead = pitch * starts`.
- * All starts together respect maxPathPoints (default 100000); excessive counts fail before allocation.
+ * All starts together respect `maxPathPoints`; excessive counts fail before allocation.
+ *
+ * @param options - Dimensions in millimetres; lead is pitch multiplied by starts.
  */
 export function sampleConventionalThreadHelices(options) {
     const operation = "sampleThreadHelices";

package/dist/geometry/mechanical/threads/mesh-plan.js

@@ -1,7 +1,7 @@
 /** Thread input resolution, end/bevel boundaries, and allocation preflight. */
 import { GeometryError } from "../../errors.js";
-import { assertMeshAllocationWithinLimits, resolveModelingLimits, } from "../../model-limits.js";
-import { resolveCircularSegments, resolveGeometryResolution, } from "../../resolution.js";
+import { assertMeshAllocationWithinLimits, resolveModelingLimits, } from "../../limits.js";
+import { resolveCircularSegments, resolveGeometryResolution, } from "../../sampling/resolution.js";
 import { resolveGeometryTolerance } from "../../tolerance.js";
 import { resolveBevel } from "./bevel.js";
 import { assertFiniteThreadNumber, createThreadRidgeSection, freezeThreadProfilePoints, MAX_THREAD_PROFILE_POINTS, } from "./profiles.js";
@@ -341,6 +341,8 @@ export const resolveHelicalThreadSolidMeshPreflight = (options, operation) => {
  * Successful preflight leaves generated coordinate and topology checks to mesh construction.
  *
  * See `mesh.threadSolid` for standalone mesh construction.
+ *
+ * @param options - Dimensions in millimetres and a validated profile; apply any fit compensation first.
  */
 export function preflightThreadSolidMesh(options) {
     return resolveHelicalThreadSolidMeshPreflight(options, "preflightThreadSolidMesh").preflight;

package/dist/geometry/mechanical/threads/mesh.js

@@ -1,7 +1,8 @@
 /** Closed ridge and complete-solid mesh construction from resolved thread plans. */
-import { triangulateContour } from "../../loft/loft.js";
-import { analyzeTriangleMesh, joinTriangleMeshes, reverseTriangleMesh, validateTriangleMesh, } from "../../mesh/mesh.js";
-import { assertMeshAllocationWithinLimits, resolveModelingLimits } from "../../model-limits.js";
+import { assertMeshAllocationWithinLimits, resolveModelingLimits } from "../../limits.js";
+import { analyzeTriangleMesh, joinTriangleMeshes, } from "../../mesh/operations.js";
+import { reverseOwnedTriangleWinding } from "../../mesh/winding.js";
+import { triangulateContour } from "../../regions/triangulation.js";
 import { resolveHelicalThreadMeshOptions, resolveHelicalThreadSolidMeshPreflight, } from "./mesh-plan.js";
 import { buildThreadSurfaceColumn, stitchThreadSurfaceColumns } from "./surface.js";
 const MINIMUM_TAPERED_RIDGE_HEIGHT = 0.0005;
@@ -56,13 +57,12 @@ const buildThreadRidgeComponent = (options) => {
     };
     cap(0, false);
     cap(spans, true);
-    let mesh = {
+    const mesh = {
         positions: new Float32Array(positions),
         indices: new Uint32Array(indices),
     };
-    validateTriangleMesh(mesh, { requireClosed: true });
     if (analyzeTriangleMesh(mesh, { requireClosed: true }).signedVolume < 0)
-        mesh = reverseTriangleMesh(mesh);
+        reverseOwnedTriangleWinding(mesh.indices);
     return mesh;
 };
 /**
@@ -73,6 +73,8 @@ const buildThreadRidgeComponent = (options) => {
  * monotone strip, with optional intermediate rows bounded by physical `maxSegmentLength`. A
  * conservative pre-allocation estimate rejects excessive meshes before constructing position
  * arrays.
+ *
+ * @param options - Dimensions in millimetres and a validated profile; apply any fit compensation first.
  */
 export function threadSolidMesh(options) {
     const operation = "threadSolidMesh";
@@ -98,13 +100,12 @@ export function threadSolidMesh(options) {
         indices.push(bottomCenter, nextBottom, bottom, topCenter, top, nextTop);
     }
     assertMeshAllocationWithinLimits(positions.length / 3, indices.length / 3, (positions.length + indices.length) * 4, operation, resolveModelingLimits(options.limits));
-    let mesh = {
+    const mesh = {
         positions: new Float32Array(positions),
         indices: new Uint32Array(indices),
     };
-    validateTriangleMesh(mesh, { requireClosed: true });
     if (analyzeTriangleMesh(mesh, { requireClosed: true }).signedVolume < 0) {
-        mesh = reverseTriangleMesh(mesh);
+        reverseOwnedTriangleWinding(mesh.indices);
     }
     return mesh;
 }
@@ -112,6 +113,8 @@ export function threadSolidMesh(options) {
  * Builds closed thread-ridge components with every profile locked to the
  * shaft's radial/axial frame. The mesh is intended for union with its
  * minor-envelope cylinder and never owns WASM objects.
+ *
+ * @param options - Dimensions in millimetres and a validated profile; apply any fit compensation first.
  */
 export function threadRidgeMesh(options) {
     const operation = "threadRidgeMesh";

package/dist/geometry/mechanical/threads/profiles.js

@@ -1,6 +1,6 @@
 /** Periodic thread profiles and axial/radial fit compensation. */
 import { GeometryError } from "../../errors.js";
-import { triangulateContour } from "../../loft/loft.js";
+import { triangulateContour } from "../../regions/triangulation.js";
 import { resolveGeometryTolerance } from "../../tolerance.js";
 const BUTTRESS_DEFAULT_DEPTH_RATIO = 0.66271;
 const BUTTRESS_CREST_FLAT_RATIO = 0.16316;
@@ -11,9 +11,13 @@ export const MAX_THREAD_PROFILE_POINTS = 1_024;
 /**
  * Applies axial fit allowance to a validated periodic profile.
  *
- * Male crests/ridges narrow by the requested backlash; female cutter ridges
- * widen by it. Periodic root endpoints remain fixed so pitch and lead do not
- * change. The returned profile is a new deeply immutable value.
+ * Each flank moves by one quarter of the mating pair's total backlash: male ridges narrow and
+ * female cutter ridges widen. Periodic root endpoints remain fixed, preserving pitch and lead.
+ * Changed profiles are deeply immutable; zero backlash returns the input unchanged.
+ *
+ * @param profile - Validated `[axial, radial]` profile in millimetres.
+ * @param axialBacklash - Nonnegative total pair allowance in millimetres, below half the pitch.
+ * @param role - Male ridge to narrow or female cutter ridge to widen.
  */
 export function compensateThreadProfileAxially(profile, axialBacklash, role) {
     const operation = "compensateThreadProfileAxially";
@@ -92,6 +96,12 @@ export function scaleThreadProfileRadially(profile, scale) {
  * This helper distributes the full conservative flank clearance between the male crest and female
  * root according to their available flat widths, and rejects a resolution that cannot represent
  * it exactly.
+ *
+ * @param profile - Uncompensated `[axial, radial]` profile in millimetres.
+ * @param axialBacklash - Nonnegative total pair allowance in millimetres, below half the pitch.
+ * @param role - Male ridge or female cutter receiving its share of the allowances.
+ * @param starts - Integer start count from 1 through 32.
+ * @param circularSegments - Full-circle facet count, at least 3 and divisible by starts.
  */
 export function compensateThreadProfileForFaceting(profile, axialBacklash, role, starts, circularSegments) {
     const operation = "compensateThreadProfileForFaceting";
@@ -235,8 +245,12 @@ const standardProfile = (kind, pitch, depth, root, crest, leftRun, rightRun) =>
  * values point toward the shaft. Custom paths must be finite, axially
  * non-decreasing, periodic at their endpoints, and reach radial zero.
  *
+ * @param spec - Profile family or custom one-pitch `[axial, radial]` path, in millimetres.
+ *
  * @example Printable triangular thread profile
  * ```ts
+ * import { threadProfile } from "@metamesh/modeling/geometry/mechanical";
+ *
  * threadProfile({ kind: "triangular", pitch: 1.75 });
  * ```
  */

package/dist/geometry/mechanical/threads/solids.js

@@ -1,8 +1,9 @@
 import { GeometryError } from "../../errors.js";
-import { resolveCircularSegments } from "../../resolution.js";
+import { resolveCircularSegments } from "../../sampling/resolution.js";
 import { resolveGeometryTolerance } from "../../tolerance.js";
-import { compensateThreadDiameters, preflightThreadSolidMesh, resolveThreadCircularSegments, } from "../index.js";
 import { resolveBevel } from "./bevel.js";
+import { compensateThreadDiameters, resolveThreadCircularSegments, } from "./fit.js";
+import { preflightThreadSolidMesh, } from "./mesh-plan.js";
 import { compensateThreadProfileForFaceting, scaleThreadProfileRadially } from "./profiles.js";
 const THREAD_FACETING_MARGIN = 0.001;
 const resolveCompensatedThreadBevelSize = (role, compensated, style, depth) => {
@@ -11,6 +12,7 @@ const resolveCompensatedThreadBevelSize = (role, compensated, style, depth) => {
     const envelopeDiameter = role === "female" ? compensated.majorDiameter : compensated.minorDiameter;
     return envelopeDiameter / 12;
 };
+/** @internal Applies shared mating allowances before role-specific bevel and mesh planning. */
 export const resolveCompensatedThreadSolidMesh = (options, role) => {
     const compensated = compensateThreadDiameters({
         nominalMajorDiameter: options.nominalMajorDiameter,
@@ -97,6 +99,8 @@ const preflightCompensatedThreadSolid = (options, role) => preflightThreadSolidM
  *
  * See `mesh.preflightThreadSolid` for standalone mesh estimates.
  * See `mesh.threadSolid` for standalone mesh construction.
+ *
+ * @param options - Nominal rod dimensions in millimetres, fit, and sampling controls.
  */
 export function preflightThreadedRodSolid(options) {
     return preflightCompensatedThreadSolid(options, "male");
@@ -111,6 +115,8 @@ export function preflightThreadedRodSolid(options) {
  *
  * See `mesh.preflightThreadSolid` for standalone mesh estimates.
  * See `mesh.threadSolid` for standalone mesh construction.
+ *
+ * @param options - Nominal cavity dimensions in millimetres, before fit and face extension.
  */
 export function preflightInternalThreadCutterSolid(options) {
     return preflightCompensatedThreadSolid(options, "female");
@@ -121,6 +127,7 @@ const throwInvalidNutScalar = (label, parameter, requirement, operation) => {
         details: { parameter },
     });
 };
+/** @internal Checks nut faces and plans the compensated cutter before native allocation. */
 export const resolveThreadedNutSolid = (options, operation) => {
     // Keep these public boundary checks ahead of resolution and all Manifold body construction.
     if (!Number.isFinite(options.width) || !(options.width > 0)) {
@@ -218,6 +225,8 @@ export const resolveThreadedNutSolid = (options, operation) => {
  * Successful preflight leaves mesh validity, native construction, and manufacturing fit to later checks.
  *
  * See `mesh.preflightThreadSolid` for standalone mesh estimates.
+ *
+ * @param options - Nominal nut dimensions in millimetres, fit, and sampling controls.
  */
 export function preflightThreadedNutSolid(options) {
     return resolveThreadedNutSolid(options, "preflightThreadedNutSolid").preflight;

package/dist/geometry/mechanical-api.js

@@ -0,0 +1,10 @@
+/** Pure mechanical dimensions, fit policies, standards, and preflight calculations. @packageDocumentation */
+export { preflightThreadedRodSolid as preflightThreadedRod, preflightInternalThreadCutterSolid as preflightInternalThreadCutter, preflightThreadedNutSolid as preflightThreadedNut, } from "./mechanical/threads/solids.js";
+export { minimumCylindricalGearToothCountWithoutUndercut, resolveCylindricalGear, resolveCylindricalGearPair, resolveRackPitch, sampleCylindricalGearOutline, sampleInternalCylindricalGearSpaceOutline, sampleRackToothPath, } from "./mechanical/gears.js";
+export { measureInternalCylindricalGearPairMotion, } from "./mechanical/gear-motion.js";
+export { METRIC_FASTENER_STANDARDS, getMetricClearanceHoleDiameter, getMetricFastenerStandard, } from "./mechanical/fastener-standards.js";
+export { compensateThreadProfileAxially, compensateThreadProfileForFaceting, threadProfile, } from "./mechanical/threads/profiles.js";
+export {} from "./mechanical/threads/mesh-plan.js";
+export { sampleConventionalThreadHelices as sampleThreadHelices, } from "./mechanical/threads/helices.js";
+export { PRINTABLE_THREAD_FIT_POLICIES, compensateThreadDiameters, resolvePrintableThreadFitPolicy, resolveThreadCircularSegments, } from "./mechanical/threads/fit.js";
+export { resolveKnuckleHinge, } from "./mechanical/knuckle-hinge.js";

package/dist/geometry/mesh/{mesh-centroid.js → centroid.js}

@@ -1,6 +1,6 @@
 import { GeometryError } from "../errors.js";
 import { immutableMeshView } from "../immutable-buffer.js";
-import { analyzeTriangleMesh } from "./mesh.js";
+import { analyzeTriangleMesh } from "./operations.js";
 /**
  * Computes the uniform-density volume centroid of an oriented closed solid, including cavity shells.
  *
@@ -16,6 +16,7 @@ export function computeTriangleMeshCentroid(mesh) {
     const facts = analyzeTriangleMesh(source, { requireClosed: true });
     if (!(facts.signedVolume > 0))
         throw new GeometryError("INVALID_TOPOLOGY", "A volume centroid requires positive oriented volume.", { operation: "computeTriangleMeshCentroid" });
+    // Translate tetrahedra near the mesh before summing moments to limit cancellation at large offsets.
     const origin = facts.bounds.min;
     const totals = [0, 0, 0], corrections = [0, 0, 0];
     for (let offset = 0; offset < source.indices.length; offset += 3) {

package/dist/geometry/{heightfield.js → mesh/heightfield.js}

@@ -1,8 +1,8 @@
-import { GeometryError } from "./errors.js";
-import { vector2Data } from "./math/vector-value.js";
-import { validateTriangleMesh } from "./mesh/mesh.js";
-import { assertMeshAllocationWithinLimits, resolveModelingLimits, } from "./model-limits.js";
-import { writeMeshVertex } from "./numeric.js";
+import { GeometryError } from "../errors.js";
+import { assertMeshAllocationWithinLimits, resolveModelingLimits, } from "../limits.js";
+import { vector2Data } from "../math/vector-value.js";
+import { validateTriangleMesh } from "./operations.js";
+import { writeMeshVertex } from "./write-vertex.js";
 function planHeightfield(options, limits) {
     const operation = "preflightHeightfield";
     if (typeof options !== "object" ||
@@ -82,6 +82,8 @@ function planHeightfield(options, limits) {
  * Successful preflight leaves height values, Float32 base storage, and generated mesh validity to
  * construction. `byteCount` covers position and index buffers, not total working memory.
  *
+ * @param options - Grid in millimetres; the height callback is not evaluated.
+ *
  * @see `mesh.heightfield`
  */
 export function preflightHeightfield(options, limits = {}) {
@@ -94,6 +96,8 @@ export function preflightHeightfield(options, limits = {}) {
  * Top winding is +Z, the base is -Z, and sides face outward. Coordinates and heights must fit
  * Float32 storage. Explicit axes are captured before sampling; shared wall vertices prevent cracks.
  *
+ * @param options - Grid and absolute height callback in millimetres.
+ *
  * @see `mesh.preflightHeightfield`
  *
  * @example Sample a closed wavy mesh