@metamesh/modeling 0.6.0 → 0.8.0

package/dist/geometry/profiles/profiles.js

@@ -3,7 +3,14 @@ import { resolveCircularPrimitiveSegments } from "../primitive-resolution.js";
 import { assertPrimitiveOptions } from "../primitive-resolvers.js";
 import { requireFiniteProfileValues, requireProfileVertexCount } from "./validation.js";
 export { rectangleLoop } from "./rectangle.js";
-/** Creates an immutable centered CCW circle with +X seam and vertex or face radial sizing. */
+/**
+ * Creates an immutable centered CCW circle with +X seam and vertex or face radial sizing.
+ *
+ * @example Explicit circular point data
+ * ```ts
+ * circleLoop({ diameter: 20, segments: 32 });
+ * ```
+ */
 export const circleLoop = (options) => {
     const operation = "circleLoop";
     assertPrimitiveOptions(options, operation);
@@ -32,7 +39,14 @@ export const circleLoop = (options) => {
         return Object.freeze([sampledRadius * Math.cos(angle), sampledRadius * Math.sin(angle)]);
     }));
 };
-/** Creates a centered CCW point loop with vertex or face radial sizing and an implicit seam. */
+/**
+ * Creates a centered CCW point loop with vertex or face radial sizing and an implicit seam.
+ *
+ * @example Hexagon sized to its faces
+ * ```ts
+ * regularPolygonLoop({ radius: 10, sides: 6, sizing: "face" });
+ * ```
+ */
 export const regularPolygonLoop = (options) => {
     const operation = "regularPolygonLoop";
     const { radius, sides, rotationDegrees = 0, sizing = "vertex" } = options;
@@ -53,7 +67,14 @@ export const regularPolygonLoop = (options) => {
         return [sampledRadius * Math.cos(angle), sampledRadius * Math.sin(angle)];
     });
 };
-/** Creates a centered CCW alternating-radius star within the selected profile sampling ceiling. */
+/**
+ * Creates a centered CCW alternating-radius star within the selected profile sampling ceiling.
+ *
+ * @example Five-point outline
+ * ```ts
+ * starLoop(12, 5, 6);
+ * ```
+ */
 export const starLoop = (outerRadius, points, innerRadius = outerRadius / 2, limits = {}) => {
     const operation = "starLoop";
     requireFiniteProfileValues([outerRadius, innerRadius], operation);

package/dist/geometry/profiles/rectangle.js

@@ -78,7 +78,14 @@ export function rectangleCornerSegments(corner, limits) {
         limits: selected,
     }) / 4);
 }
-/** Creates an immutable CCW rectangle loop. Round radius zero is square; tangent saturated endpoints occur once. */
+/**
+ * Creates an immutable CCW rectangle loop. Round radius zero is square; tangent saturated endpoints occur once.
+ *
+ * @example Rounded rectangle outline
+ * ```ts
+ * rectangleLoop({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
+ * ```
+ */
 export function rectangleLoop(options) {
     const { width, height, corners, limits } = resolveRectangle(options, "rectangleLoop");
     const counts = corners.map((corner) => {
@@ -138,7 +145,14 @@ export function rectangleLoop(options) {
         clean.pop();
     return Object.freeze(clean.map(([px, py]) => Object.freeze(options.center === false ? [px + x, py + y] : [px, py])));
 }
-/** Creates an identified rectangle whose edge/corner spans survive zero and saturated round radii. Outer winding is CCW. */
+/**
+ * Creates an identified rectangle whose edge/corner spans survive zero and saturated round radii. Outer winding is CCW.
+ *
+ * @example Retain rectangle landmarks
+ * ```ts
+ * rectangleProfile({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
+ * ```
+ */
 export function rectangleProfile(options) {
     const { width, height, corners, setbacks, limits } = resolveRectangle(options, "rectangleProfile");
     const id = options.id ?? "body";

package/dist/geometry/profiles/shapes.js

@@ -2,7 +2,14 @@ import { GeometryError } from "../errors.js";
 import { resolveCircularPrimitiveSegments } from "../primitive-resolution.js";
 import { assertPrimitiveOptions } from "../primitive-resolvers.js";
 import { requireFiniteProfileValues, requireProfileVertexCount } from "./validation.js";
-/** Creates an immutable centered CCW ellipse with +X seam within the selected sampling ceiling. */
+/**
+ * Creates an immutable centered CCW ellipse with +X seam within the selected sampling ceiling.
+ *
+ * @example Ellipse by full dimensions
+ * ```ts
+ * ellipseLoop({ size: [30, 20] });
+ * ```
+ */
 export function ellipseLoop(options) {
     assertPrimitiveOptions(options, "ellipseLoop");
     if ((options.radius === undefined) === (options.size === undefined)) {

package/dist/geometry/revolve/revolve-mesh.js

@@ -20,6 +20,12 @@ const AXIS_EPSILON = 1e-10;
  * @param profile - Closed CCW `[radius, z]` profile without a duplicated seam point.
  * @param options - Optional physical or exact circumferential sampling controls. Defaults to `{}`.
  * @returns A closed indexed triangle mesh revolved counter-clockwise around +Z.
+ *
+ * @example Partial revolution with end caps
+ * ```ts
+ * // Each point is [radius, Z]; the profile seam is implicit.
+ * revolveMesh([[0, 0], [12, 0], [8, 20], [0, 20]], { revolveDegrees: 270 });
+ * ```
  */
 export const revolveMesh = (profile, options = {}) => {
     if (typeof options !== "object" || options === null || Array.isArray(options))

package/dist/geometry/sweeps/sweep-closed.js

@@ -7,12 +7,12 @@ import { computeSweepFrames, validateSweepOptions } from "./orientation.js";
 import { planSweepStations, refineSweepStations } from "./stations.js";
 import { assertSweepAllocation, normalizeSweepPath, normalizeSweepProfile, writeSweepVertex, } from "./validation.js";
 /** @internal Checks host allocation policy before frames or manufacturing buffers. */
-export const buildClosedSweepMesh = (profile, path, options = {}, allocationGuard) => {
+export const buildClosedSweepMesh = (profile, path, options = {}) => {
     const operation = "sweep";
     validateSweepOptions(options);
     profile = normalizeSweepProfile(profile, operation, options.limits);
     path = normalizeSweepPath(path, true, operation, options.limits);
-    assertSweepAllocation(path.length, profile.length, true, operation, allocationGuard, options.limits);
+    assertSweepAllocation(path.length, profile.length, true, operation, options.limits);
     let scales = resolveSweepScales(options.scale, path.length);
     const seamProfileOffset = options.seamProfileOffset ?? 0;
     if (!Number.isSafeInteger(seamProfileOffset)) {
@@ -44,13 +44,13 @@ export const buildClosedSweepMesh = (profile, path, options = {}, allocationGuar
     }
     if (twistRadians !== 0) {
         const plan = planSweepStations([profile], path, scales, options);
-        assertSweepAllocation(plan.stationCount, profile.length, true, operation, allocationGuard, options.limits);
+        assertSweepAllocation(plan.stationCount, profile.length, true, operation, options.limits);
     }
     let transportedFrames = computeSweepFrames(path, options);
     let twists;
     if (twistRadians !== 0) {
         const plan = planSweepStations([profile], path, scales, options, transportedFrames);
-        assertSweepAllocation(plan.stationCount, profile.length, true, operation, allocationGuard, options.limits);
+        assertSweepAllocation(plan.stationCount, profile.length, true, operation, options.limits);
         const refined = refineSweepStations(path, scales, transportedFrames, options, plan);
         path = refined.path;
         scales = refined.scales;

package/dist/geometry/sweeps/sweep-mesh.js

@@ -2,19 +2,25 @@ import { GeometryError } from "../errors.js";
 import { validateSweepOptions } from "./orientation.js";
 import { buildClosedSweepMesh } from "./sweep-closed.js";
 import { buildOpenSweepMesh } from "./sweep-open.js";
-/** Sweeps one explicitly ordered point loop, with caps or a geometrically matching closed seam. */
+/**
+ * Sweeps one explicitly ordered point loop, with caps or a geometrically matching closed seam.
+ *
+ * @example Sweep point data along a bent path
+ * ```ts
+ * const profile = rectangleLoop({ size: [6, 3] });
+ * sweepMesh(profile, [[0, 0, 0], [0, 0, 15], [10, 0, 25]], {
+ *   orientation: { kind: "transport", initialNormal: [0, 1, 0] },
+ * });
+ * ```
+ */
 export function sweepMesh(profile, path, options = {}) {
-    return buildSweepMesh(profile, path, options);
-}
-/** @internal Applies host ceilings before frames, caps, or manufacturing buffers. */
-export function buildSweepMesh(profile, path, options = {}, allocationGuard) {
     validateSweepOptions(options);
     if (options.closed === true) {
-        return buildClosedSweepMesh(profile, path, options, allocationGuard);
+        return buildClosedSweepMesh(profile, path, options);
     }
     if ((options.seamProfileOffset ?? 0) !== 0)
         throw new GeometryError("INVALID_ARGUMENT", "A seamProfileOffset requires a closed path.", {
             operation: "sweep",
         });
-    return buildOpenSweepMesh(profile, path, options, allocationGuard);
+    return buildOpenSweepMesh(profile, path, options);
 }

package/dist/geometry/sweeps/sweep-open.js

@@ -6,23 +6,23 @@ import { computeSweepFrames, validateSweepOptions } from "./orientation.js";
 import { planSweepStations, refineSweepStations } from "./stations.js";
 import { assertSweepAllocation, normalizeSweepPath, normalizeSweepProfile, writeSweepVertex, } from "./validation.js";
 /** @internal Checks host allocation policy before frames, caps or manufacturing buffers. */
-export const buildOpenSweepMesh = (profile, path, options = {}, allocationGuard) => {
+export const buildOpenSweepMesh = (profile, path, options = {}) => {
     const operation = "sweep";
     validateSweepOptions(options);
     profile = normalizeSweepProfile(profile, operation, options.limits);
     path = normalizeSweepPath(path, false, operation, options.limits);
-    assertSweepAllocation(path.length, profile.length, false, operation, allocationGuard, options.limits);
+    assertSweepAllocation(path.length, profile.length, false, operation, options.limits);
     let scales = resolveSweepScales(options.scale, path.length);
     const twistRadians = ((options.twistDegrees ?? 0) / 180) * Math.PI;
     if (twistRadians !== 0) {
         const plan = planSweepStations([profile], path, scales, options);
-        assertSweepAllocation(plan.stationCount, profile.length, false, operation, allocationGuard, options.limits);
+        assertSweepAllocation(plan.stationCount, profile.length, false, operation, options.limits);
     }
     let frames = computeSweepFrames(path, options);
     let twists;
     if (twistRadians !== 0) {
         const plan = planSweepStations([profile], path, scales, options, frames);
-        assertSweepAllocation(plan.stationCount, profile.length, false, operation, allocationGuard, options.limits);
+        assertSweepAllocation(plan.stationCount, profile.length, false, operation, options.limits);
         const refined = refineSweepStations(path, scales, frames, options, plan);
         path = refined.path;
         scales = refined.scales;

package/dist/geometry/sweeps/validation.js

@@ -87,11 +87,10 @@ export function normalizeSweepPath(path, closed, operation, limits = {}) {
     return Object.freeze(cleaned);
 }
 /** @internal Checks output allocation before creating frames or buffers. */
-export function assertSweepAllocation(pathCount, profileCount, closed, operation, allocationGuard, limits = {}) {
+export function assertSweepAllocation(pathCount, profileCount, closed, operation, limits = {}) {
     const vertexCount = pathCount * profileCount;
     const triangleCount = (closed ? pathCount : pathCount - 1) * profileCount * 2 + (closed ? 0 : (profileCount - 2) * 2);
     assertMeshAllocationWithinLimits(vertexCount, triangleCount, (vertexCount + triangleCount) * 12, operation, resolveModelingLimits(limits));
-    allocationGuard?.(vertexCount, triangleCount, (vertexCount + triangleCount) * 12, operation);
 }
 /** @internal Rejects coordinates that cannot be represented in manufacturing mesh buffers. */
 export function writeSweepVertex(positions, offset, point, operation) {

package/dist/model/operations.js

@@ -3,8 +3,6 @@ function operation(name) {
     const invoke = (...args) => {
         const context = currentModelContext(name);
         const method = context[name];
-        if (typeof method !== "function")
-            throw new Error(`Unknown modeling operation "${name}".`);
         return Reflect.apply(method, undefined, args);
     };
     return invoke;
@@ -14,14 +12,16 @@ export const matchProfiles =
 /* @__PURE__ */ operation("matchProfiles");
 /** Copies intersections along a finite directed ray segment during the active build. */
 export const rayCast = /* @__PURE__ */ operation("rayCast");
-/** Returns bound local operations, optionally with derived resolution, without changing imported operations. */
+/**
+ * Returns bound local operations, optionally with derived resolution, without changing imported operations.
+ */
 export function modelingFunctions(resolution) {
     const context = currentModelContext("modelingFunctions");
     return resolution === undefined ? context : context.withResolution(resolution);
 }
 /** Host-bound box operation. Valid only during a synchronous build. */
 export const box = /* @__PURE__ */ operation("box");
-/** Constructs a closed regularly sampled heightfield during the active synchronous build. */
+/** Constructs a closed rectilinear heightfield during the active synchronous build. */
 export const heightfield = /* @__PURE__ */ operation("heightfield");
 /** Returns an immutable copy with the explicit native millimetre tolerance. */
 export const setTolerance = 
@@ -40,6 +40,11 @@ export const union = /* @__PURE__ */ operation("union");
 export const subtract = /* @__PURE__ */ operation("subtract");
 /** Host-bound intersect operation. Valid only during a synchronous build. */
 export const intersect = /* @__PURE__ */ operation("intersect");
+/** Returns intersection and difference with a same-build cutter, including empty results. */
+export const split = /* @__PURE__ */ operation("split");
+/** Splits a solid into the normal-side and opposite-side halves of a world-space plane. */
+export const splitByPlane = 
+/* @__PURE__ */ operation("splitByPlane");
 /** Host-bound compose operation. Valid only during a synchronous build. */
 export const compose = /* @__PURE__ */ operation("compose");
 /** Host-bound hull operation. Valid only during a synchronous build. */
@@ -96,6 +101,10 @@ export const inspectSection =
 /** Host-bound inspectSolid operation. Valid only during a synchronous build. */
 export const inspectSolid = 
 /* @__PURE__ */ operation("inspectSolid");
+/** Tests a solid or filled section in the active build, including expected empty Boolean results. */
+export const isEmpty = /* @__PURE__ */ operation("isEmpty");
+/** Measures the minimum separation between two nonempty solids in millimetres. */
+export const distance = /* @__PURE__ */ operation("distance");
 /** Host-bound components operation. Valid only during a synchronous build. */
 export const components = /* @__PURE__ */ operation("components");
 /** Host-bound simplify operation. Valid only during a synchronous build. */

package/dist/text/index.js

@@ -19,7 +19,17 @@ function serializeVectorText({ paths, metrics }) {
         fail("Text outlines exceed 256 KiB. Use fewer characters or a simpler font.");
     return svg;
 }
-/** Parses bounded font bytes using optional fontkit and WOFF2 peers; no font fetching occurs here. */
+/**
+ * Parses bounded font bytes using optional fontkit and WOFF2 peers; no font fetching occurs here.
+ *
+ * @example Prepare a label before building geometry
+ * ```ts
+ * async function prepareLabel(fontBytes: Uint8Array) {
+ *   const font = await prepareVectorFont(fontBytes);
+ *   return font.layout("MetaMesh", { fontSize: 8 });
+ * }
+ * ```
+ */
 export async function prepareVectorFont(bytes, options = {}) {
     if (bytes.byteLength === 0 || bytes.byteLength > MAX_VECTOR_FONT_BYTES)
         fail("Font files must be non-empty and at most 16 MiB.");

package/dist/text/vector-text-layout.js

@@ -22,13 +22,33 @@ function checkText(text) {
     return lines;
 }
 function normalizeControls(options, staticWeight) {
+    const baseline = options.baseline;
+    if (baseline !== undefined) {
+        if (typeof baseline !== "object" || baseline === null || baseline.kind !== "arc")
+            fail("Invalid text baseline; use an arc or omit baseline for horizontal text.");
+        if (!Number.isFinite(baseline.radius) || baseline.radius <= 0 || baseline.radius > 10000)
+            fail("Arc baseline radius must be positive and at most 10000 mm.");
+        if (baseline.centerAngleDegrees !== undefined && !Number.isFinite(baseline.centerAngleDegrees))
+            fail("Arc baseline centerAngleDegrees must be finite.");
+        if (baseline.direction !== undefined &&
+            baseline.direction !== "clockwise" &&
+            baseline.direction !== "counterclockwise")
+            fail("Invalid arc baseline direction.");
+    }
     const controls = {
         fontSize: options.fontSize,
         fontWeight: options.fontWeight ?? staticWeight,
         letterSpacing: options.letterSpacing ?? 0,
-        align: options.align ?? "left",
+        align: options.align ?? (baseline === undefined ? "left" : "center"),
         verticalAlign: options.verticalAlign ?? "baseline",
         lineHeight: options.lineHeight,
+        baseline: baseline === undefined
+            ? undefined
+            : {
+                radius: baseline.radius,
+                centerAngleDegrees: (((baseline.centerAngleDegrees ?? 90) % 360) + 360) % 360,
+                direction: baseline.direction ?? "clockwise",
+            },
     };
     if (!Number.isFinite(controls.fontSize) || controls.fontSize <= 0 || controls.fontSize > 10000)
         fail("fontSize must be positive and at most 10000 mm.");
@@ -45,6 +65,8 @@ function normalizeControls(options, staticWeight) {
         controls.verticalAlign !== "center" &&
         controls.verticalAlign !== "bottom")
         fail("Invalid vertical text alignment.");
+    if (controls.baseline !== undefined && controls.verticalAlign !== "baseline")
+        fail("Arc text requires baseline vertical alignment.");
     if (controls.lineHeight !== undefined &&
         (!Number.isFinite(controls.lineHeight) || controls.lineHeight < 0.5 || controls.lineHeight > 5))
         fail("lineHeight must be between 0.5 and 5.");
@@ -189,6 +211,8 @@ function buildLayout(font, fontMetrics, lines, controls) {
     let commands = 0;
     for (let lineIndex = 0; lineIndex < shaped.length; lineIndex++) {
         const { run, advanceWidth } = shaped[lineIndex];
+        if (controls.baseline !== undefined && advanceWidth / controls.baseline.radius >= Math.PI * 2)
+            fail("Arc text must span less than one full revolution. Increase radius or reduce text size or spacing.");
         const lineX = controls.align === "center"
             ? -advanceWidth / 2
             : controls.align === "right"
@@ -197,11 +221,16 @@ function buildLayout(font, fontMetrics, lines, controls) {
         let x = 0;
         let y = 0;
         let spacingSteps = -1;
+        let groupCenter = 0;
         for (let index = 0; index < run.glyphs.length; index++) {
             const position = run.positions[index];
             // Zero-advance marks retain their base glyph's tracking offset.
-            if (index === 0 || position.xAdvance !== 0)
+            if (index === 0 || position.xAdvance !== 0) {
                 spacingSteps++;
+                // Keep zero-advance marks on the same rigid frame as their advancing base glyph.
+                groupCenter =
+                    (x + position.xAdvance / 2) * scale + spacingSteps * controls.letterSpacing + lineX;
+            }
             const source = run.glyphs[index].path.commands;
             commands += source.length;
             if (commands > MAX_TEXT_COMMANDS)
@@ -209,9 +238,21 @@ function buildLayout(font, fontMetrics, lines, controls) {
             if (source.length > 0) {
                 // Preserve full precision: fontkit's toSVG() rounds before scaling and reparsing it wastes work.
                 const path = new SVGPathData(source.map(convertCommand)).transform(SVGPathDataTransformer.MATRIX(scale, 0, 0, scale, (x + position.xOffset) * scale + spacingSteps * controls.letterSpacing + lineX, (y + position.yOffset) * scale - lineIndex * lineHeight));
-                const bounds = path.getBounds();
+                let bounds = path.getBounds();
                 if (![bounds.minX, bounds.minY, bounds.maxX, bounds.maxY].every(Number.isFinite))
                     fail("The font returned invalid glyph outline bounds.");
+                if (controls.baseline !== undefined) {
+                    const { radius, centerAngleDegrees, direction } = controls.baseline;
+                    const clockwise = direction === "clockwise";
+                    if (clockwise ? radius + bounds.minY <= 0 : radius - bounds.maxY <= 0)
+                        fail("Arc glyph outlines cross the circle's center axis. Increase the radius or reduce text size.");
+                    const angle = (centerAngleDegrees * Math.PI) / 180 + ((clockwise ? -1 : 1) * groupCenter) / radius;
+                    const rotation = angle + (clockwise ? -Math.PI / 2 : Math.PI / 2);
+                    const cosine = Math.cos(rotation);
+                    const sine = Math.sin(rotation);
+                    path.transform(SVGPathDataTransformer.MATRIX(cosine, sine, -sine, cosine, radius * Math.cos(angle) - cosine * groupCenter, radius * Math.sin(angle) - sine * groupCenter));
+                    bounds = path.getBounds();
+                }
                 minX = Math.min(minX, bounds.minX);
                 minY = Math.min(minY, bounds.minY);
                 maxX = Math.max(maxX, bounds.maxX);
@@ -261,6 +302,8 @@ export function createVectorTextLayout(font, staticWeight) {
     return (text, options) => {
         const lines = checkText(text);
         const controls = normalizeControls(options, staticWeight);
+        if (controls.baseline !== undefined && lines.length !== 1)
+            fail("Arc text supports exactly one line.");
         const key = JSON.stringify([lines, controls]);
         if (previous?.key === key)
             return previous.layout;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamesh/modeling",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Scoped solid modeling and pure geometry foundations for Node and browsers.",
   "license": "Apache-2.0",
   "repository": {