@metamesh/modeling 0.14.0 → 0.15.0

package/dist/model/immutable-generation-data.js

@@ -3,6 +3,13 @@ import { isImmutableMathValue } from "../geometry/math/immutable-value.js";
 import { geometryRecipe, isGeometryRecipe } from "./geometry-recipes.js";
 import { adoptImmutableBuffer, immutableBuffer, immutableBufferView, isImmutableBuffer, } from "./immutable-buffer.js";
 const mutableBufferMessage = "Generation data cannot contain mutable typed arrays or raw ArrayBuffers. Use immutableBuffer(array) or immutableMesh(mesh) before caching them or declaring dependencies.";
+const capturedMetadata = new WeakMap();
+const noChildren = Object.freeze([]);
+/** Reuses field accounting only for containers captured or deeply validated by this owner. */
+export function generationDataMetadata(value) {
+    return capturedMetadata.get(value);
+}
+const scalarBytes = (value) => (typeof value === "string" ? value.length * 2 : 8);
 /** Iterates plain fields; recipe capture may read each enumerable accessor once. */
 export function* generationDataEntries(value, captureAccessors = false) {
     const prototype = Object.getPrototypeOf(value);
@@ -45,9 +52,31 @@ export function generationValueBytes(values, ceiling) {
         if (seen.has(value))
             return;
         seen.add(value);
+        const metadata = capturedMetadata.get(value);
+        if (metadata !== undefined) {
+            if (depth === 128 && metadata.bytes > 0) {
+                bytes = Infinity;
+                return;
+            }
+            bytes += 32 + metadata.bytes;
+            for (const child of metadata.children)
+                visit(child, depth + 1);
+            return;
+        }
         if (isImmutableMathValue(value)) {
             bytes += 32;
-            visit(mathValueData(value), depth + 1);
+            const data = mathValueData(value);
+            visit(data, depth + 1);
+            if (typeof data === "object" &&
+                data !== null &&
+                "dimension" in data &&
+                (data.dimension === 2 || data.dimension === 3) &&
+                "points" in data &&
+                Array.isArray(data.points)) {
+                // A path retains private numerical tuples as well as its frozen interchange view.
+                // Charge both stores conservatively; the outer seen set still counts value aliases once.
+                bytes += 64 + data.points.length * (40 + 8 * data.dimension);
+            }
             return;
         }
         const array = isImmutableBuffer(value)
@@ -158,14 +187,21 @@ export function compareGenerationValues(left, right) {
 function mathValueData(value) {
     for (const name of ["toArray", "toMatrix"]) {
         const method = Reflect.get(value, name);
-        if (typeof method === "function")
-            return Reflect.apply(method, value, []);
+        if (typeof method === "function") {
+            const data = Reflect.apply(method, value, []);
+            // Closure and dimension change path behavior; tuple interchange omits both for empty paths.
+            const closed = Reflect.get(value, "closed");
+            return typeof closed === "boolean"
+                ? { dimension: Reflect.get(value, "dimension"), points: data, closed }
+                : data;
+        }
     }
     throw new TypeError("Immutable math values must expose their canonical numeric data.");
 }
 function captureValue(value, mode, readerAllowed = () => false, validated) {
     const recipeInputs = mode === "recipe";
     const seen = new Map();
+    const metadata = new Map();
     const copy = (input) => {
         if (typeof input === "function" && !recipeInputs && !readerAllowed(input))
             throw new GeometryError("INVALID_ARGUMENT", "Computed values and dependencies cannot contain arbitrary function closures.", { operation: "computed" });
@@ -191,20 +227,42 @@ function captureValue(value, mode, readerAllowed = () => false, validated) {
         if (input instanceof ArrayBuffer)
             throw new TypeError(mutableBufferMessage);
         const entries = generationDataEntries(input, recipeInputs);
+        let bytes = 0;
+        const children = [];
+        const recordField = (key, field) => {
+            bytes += 16 + key.length * 2;
+            if (typeof field === "object" && field !== null)
+                children.push(field);
+            else
+                bytes += scalarBytes(field);
+        };
         if (mode === "dependency") {
             if (!Object.isFrozen(input))
                 throw new GeometryError("INVALID_ARGUMENT", "Computed dependencies require deeply immutable objects and arrays. Read params inside the callback, use a computed value, or depend on individual scalar values.", { operation: "computed" });
             seen.set(input, input);
-            for (const [, field] of entries)
+            for (const [key, field] of entries) {
                 copy(field);
+                recordField(key, field);
+            }
+            metadata.set(input, {
+                bytes,
+                children: children.length ? Object.freeze(children) : noChildren,
+            });
             return input;
         }
         const result = Array.isArray(input)
             ? new Array(input.length)
             : Object.create(Object.getPrototypeOf(input) === null ? null : Object.prototype);
         seen.set(input, result);
-        for (const [key, field] of entries)
-            Object.defineProperty(result, key, { value: copy(field), enumerable: true });
+        for (const [key, field] of entries) {
+            const value = copy(field);
+            Object.defineProperty(result, key, { value, enumerable: true });
+            recordField(key, value);
+        }
+        metadata.set(result, {
+            bytes,
+            children: children.length ? Object.freeze(children) : noChildren,
+        });
         return Object.freeze(result);
     };
     const result = copy(value);
@@ -212,6 +270,8 @@ function captureValue(value, mode, readerAllowed = () => false, validated) {
     if (mode === "dependency")
         for (const input of seen.keys())
             validated?.add(input);
+    for (const [value, entry] of metadata)
+        capturedMetadata.set(value, entry);
     return result;
 }
 /** Validates while capturing immutable data; only explicitly allowed session readers may be functions. */

package/dist/model/operations.js

@@ -139,10 +139,6 @@ export function minkowskiSum(a, b) {
 export function solidFromMesh(mesh) {
     return invoke("solidFromMesh", [mesh]);
 }
-/** Copies a handle to manufacturing mesh buffers. */
-export function toTriangleMesh(solid) {
-    return invoke("toTriangleMesh", [solid]);
-}
 /**
  * Reads a copied, immutable named anchor from this exact active generation.
  *
@@ -171,7 +167,7 @@ export function polygon(input) {
 /**
  * Creates a centered-width native Section along a sampled XY path.
  *
- * Shares caps, joins and physical sampling with Geometry's strokePathRegion. Native union
+ * Shares caps, joins and physical sampling with Geometry's strokeRegionData. Native union
  * resolves overlapping stroke primitives. Session resolution and resource ceilings apply;
  * closed paths omit the duplicated seam. Returns an immutable deferred recipe.
  *
@@ -266,7 +262,7 @@ export function extrude(shape, options) {
  *
  * // Contour coordinates are [radius, Z].
  * const [profile] = matchProfiles([rectangleProfile({ size: [4, 16], center: false })]);
- * revolve(profile!, { revolveDegrees: 270 });
+ * revolve(profile!, { degrees: 270 });
  * ```
  */
 export function revolve(shape, options) {
@@ -276,7 +272,10 @@ export function revolve(shape, options) {
 export function loft(stations, options) {
     return invoke("loft", [stations, options]);
 }
-/** Explicit family matching on a shared physical span grid using session or operation resolution. */
+/**
+ * Matches a profile family using operation settings over host resolution and limits.
+ * Requires active synchronous model execution. Use Geometry's matchProfiles for standalone preparation.
+ */
 export function matchProfiles(profiles, options) {
     return invoke("matchProfiles", [profiles, options]);
 }
@@ -359,8 +358,8 @@ export function distance(solid, other) {
     return invoke("distance", [solid, other]);
 }
 /** Copies intersections along the finite directed origin-to-endpoint segment. */
-export function rayCast(solid, origin, endpoint) {
-    return invoke("rayCast", [solid, origin, endpoint]);
+export function castSegment(solid, origin, endpoint) {
+    return invoke("castSegment", [solid, origin, endpoint]);
 }
 export function components(shape) {
     return invoke("components", [shape]);
@@ -388,17 +387,17 @@ export function implicit(options) {
 export function heightfield(options) {
     return invoke("heightfield", [options]);
 }
-export function linearPattern(source, options) {
-    return invoke("linearPattern", [source, options]);
+export function linearPattern(...args) {
+    return invoke("linearPattern", args);
 }
-export function radialPattern(source, options) {
-    return invoke("radialPattern", [source, options]);
+export function radialPattern(...args) {
+    return invoke("radialPattern", args);
 }
-export function gridPattern(source, options) {
-    return invoke("gridPattern", [source, options]);
+export function gridPattern(...args) {
+    return invoke("gridPattern", args);
 }
-export function pathPattern(source, path, options) {
-    return invoke("pathPattern", [source, path, options]);
+export function pathPattern(...args) {
+    return invoke("pathPattern", args);
 }
 /** Helical ridge mesh construction. */
 export function threadRidge(options) {
@@ -410,9 +409,9 @@ export function threadRidge(options) {
  * @example Threaded rod
  * ```ts
  * import { threadedRod } from "@metamesh/modeling";
- * import { createThreadProfile } from "@metamesh/modeling/geometry";
+ * import { threadProfile } from "@metamesh/modeling/geometry";
  *
- * const profile = createThreadProfile({ kind: "triangular", pitch: 1.75 });
+ * const profile = threadProfile({ kind: "triangular", pitch: 1.75 });
  * threadedRod({ nominalMajorDiameter: 12, length: 24, profile, fit: "normal" });
  * ```
  */
@@ -425,8 +424,8 @@ export function threadedRod(options) {
  * @example Internal thread
  * ```ts
  * import { cylinder, internalThreadCutter } from "@metamesh/modeling";
- * import { createThreadProfile } from "@metamesh/modeling/geometry";
- * const profile = createThreadProfile({ kind: "triangular", pitch: 1.75 });
+ * import { threadProfile } from "@metamesh/modeling/geometry";
+ * const profile = threadProfile({ kind: "triangular", pitch: 1.75 });
  * const body = cylinder({ diameter: 20, height: 12, center: false });
  * const cutter = internalThreadCutter({ nominalMajorDiameter: 12, length: 12, profile });
  * body.subtract([cutter]);
@@ -441,24 +440,24 @@ export function internalThreadCutter(options) {
  * @example Threaded nut
  * ```ts
  * import { threadedNut } from "@metamesh/modeling";
- * import { createThreadProfile } from "@metamesh/modeling/geometry";
+ * import { threadProfile } from "@metamesh/modeling/geometry";
  *
- * const profile = createThreadProfile({ kind: "triangular", pitch: 1.75 });
+ * const profile = threadProfile({ kind: "triangular", pitch: 1.75 });
  * threadedNut({ nominalMajorDiameter: 12, thickness: 8, width: 20, shape: "hex", profile, fit: "normal" });
  * ```
  */
 export function threadedNut(options) {
     return invoke("threadedNut", [options]);
 }
-/** Allocation-free external-thread facts. */
+/** External-thread facts using host resolution and limits; requires active synchronous model execution. */
 export function preflightThreadedRod(options) {
     return invoke("preflightThreadedRod", [options]);
 }
-/** Allocation-free internal-thread facts. */
+/** Internal-thread facts using host resolution and limits; requires active synchronous model execution. */
 export function preflightInternalThreadCutter(options) {
     return invoke("preflightInternalThreadCutter", [options]);
 }
-/** Allocation-free nut/cutter facts. */
+/** Nut/cutter facts using host resolution and limits; requires active synchronous model execution. */
 export function preflightThreadedNut(options) {
     return invoke("preflightThreadedNut", [options]);
 }

package/dist/model/recipe-declaration.js

@@ -21,7 +21,7 @@ const operationBehaviors = {
     compose: "solid",
     minkowskiSum: "solid",
     solidFromMesh: "solid",
-    setTolerance: "solid",
+    withTolerance: "solid",
     threadRidge: "solid",
     threadedRod: "solid",
     threadedNut: "solid",
@@ -57,7 +57,7 @@ const operationBehaviors = {
     inspectSolid: "observation",
     isEmpty: "observation",
     distance: "observation",
-    rayCast: "observation",
+    castSegment: "observation",
     anchor: "observation",
     matchProfiles: "observation",
     preflightThreadedRod: "observation",
@@ -144,13 +144,19 @@ function inputKind(value) {
         return recipe.kind;
     if ("sections" in value)
         return "section";
-    if ("points" in value &&
-        Array.isArray(value.points) &&
-        Array.isArray(value.points[0]) &&
-        value.points[0].length === 2)
+    if ("points" in value && Array.isArray(value.points) && pointDimension(value.points[0]) === 2)
         return "section";
     return "solid";
 }
+function pointDimension(value) {
+    if (Array.isArray(value))
+        return value.length;
+    if (typeof value !== "object" || value === null || !("toArray" in value))
+        return undefined;
+    const method = value.toArray;
+    const points = typeof method === "function" ? Reflect.apply(method, value, []) : undefined;
+    return Array.isArray(points) ? points.length : undefined;
+}
 /** Runs every factory during declaration; each placed copy stays deferred until it is used. */
 function declarePattern(operation, resolution, supplied, declaration) {
     const plan = patternPlan(operation, supplied, declaration.limits);
@@ -171,7 +177,7 @@ function declarePattern(operation, resolution, supplied, declaration) {
                 operation,
             });
         kind = currentKind;
-        const matrix = plan.transformAt(index);
+        const matrix = plan.transformAt(index, kind === "section" ? 2 : 3);
         copies.push(declareRecipeOperation("transform", resolution, [shape, kind === "section" ? restrictTransform3(matrix) : matrix], declaration));
     }
     return Object.freeze(copies);

package/dist/model/shape-handles.js

@@ -26,8 +26,9 @@ const common = {
 };
 const solidPrototype = prototype({
     ...common,
+    toTriangleMesh: forward("toTriangleMesh"),
     attach: forward("attach"),
-    setTolerance: forward("setTolerance"),
+    withTolerance: forward("withTolerance"),
     projectSection: forward("projectSection"),
     sliceSection: forward("sliceSection"),
 });

package/dist/text/index.js

@@ -1,14 +1,15 @@
 import { SVGPathData, SVGPathDataTransformer } from "svg-pathdata";
+import { GeometryError } from "../geometry/errors.js";
 import { createVectorTextLayout } from "./vector-text-layout.js";
 /** Limits apply before parsing or shaping untrusted font data. */
 export const MAX_VECTOR_FONT_BYTES = 16 * 1024 * 1024;
-function fail(message) {
-    throw new Error(message);
+function fail(message, code = "INVALID_ARGUMENT") {
+    throw new GeometryError(code, message, { operation: "prepareVectorFont" });
 }
 function serializeVectorText({ paths, metrics }) {
     const bounds = metrics.bounds;
     if (bounds === null || paths.length === 0)
-        fail("The selected font produced no visible glyph outlines.");
+        throw new GeometryError("DEGENERATE_GEOMETRY", "The selected font produced no visible glyph outlines.", { operation: "VectorFont.toSvg" });
     const d = paths
         .map((path) => new SVGPathData(path).transform(SVGPathDataTransformer.MATRIX(1, 0, 0, -1, 0, 0)).encode())
         .join(" ");
@@ -16,11 +17,12 @@ function serializeVectorText({ paths, metrics }) {
     const height = Math.max(0.001, bounds.max[1] - bounds.min[1]);
     const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}mm" height="${height}mm" viewBox="${bounds.min[0]} ${-bounds.max[1]} ${width} ${height}"><path fill="black" fill-rule="nonzero" d="${d}"/></svg>`;
     if (svg.length > 256 * 1024)
-        fail("Text outlines exceed 256 KiB. Use fewer characters or a simpler font.");
+        throw new GeometryError("COMPLEXITY_LIMIT", "Text outlines exceed 256 KiB. Use fewer characters or a simpler font.", { operation: "VectorFont.toSvg" });
     return svg;
 }
 /**
  * Parses bounded font bytes using optional fontkit and WOFF2 peers; no font fetching occurs here.
+ * Argument and resource failures use GeometryError; parser and decoder exceptions propagate unchanged.
  *
  * @example Prepare a label before building geometry
  * ```ts
@@ -31,20 +33,24 @@ function serializeVectorText({ paths, metrics }) {
  * ```
  */
 export async function prepareVectorFont(bytes, options = {}) {
-    if (bytes.byteLength === 0 || bytes.byteLength > MAX_VECTOR_FONT_BYTES)
+    if (bytes.byteLength === 0)
         fail("Font files must be non-empty and at most 16 MiB.");
+    if (bytes.byteLength > MAX_VECTOR_FONT_BYTES)
+        fail("Font files must be non-empty and at most 16 MiB.", "COMPLEXITY_LIMIT");
     const staticWeight = options.staticWeight ?? 400;
     if (!Number.isInteger(staticWeight) || staticWeight < 1 || staticWeight > 1000)
-        fail("staticWeight must be an integer from 1 through 1000.");
+        fail("staticWeight must be an integer from 1 through 1000.", Number.isFinite(staticWeight) ? "INVALID_ARGUMENT" : "NON_FINITE_VALUE");
     // Own the original bytes: a caller mutating its buffer must not change later lazy font reads.
     let decoded = Uint8Array.from(bytes);
     if (bytes[0] === 0x77 && bytes[1] === 0x4f && bytes[2] === 0x46 && bytes[3] === 0x32) {
-        const { default: decompress } = await import("woff2-encoder/decompress").catch(() => fail("Install woff2-encoder to prepare WOFF2 fonts with @metamesh/modeling/text."));
+        const { default: decompress } = await import("woff2-encoder/decompress");
         decoded = await decompress(decoded);
-        if (decoded.byteLength === 0 || decoded.byteLength > 32 * 1024 * 1024)
+        if (decoded.byteLength === 0)
             fail("The decoded font must be non-empty and at most 32 MiB.");
+        if (decoded.byteLength > 32 * 1024 * 1024)
+            fail("The decoded font must be non-empty and at most 32 MiB.", "COMPLEXITY_LIMIT");
     }
-    const fontkit = await import("fontkit").catch(() => fail("Install fontkit to prepare fonts with @metamesh/modeling/text."));
+    const fontkit = await import("fontkit");
     const font = fontkit.create(decoded);
     if (!("layout" in font))
         fail("Font collections are not supported.");

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

@@ -1,19 +1,20 @@
 import { SVGPathData, SVGPathDataTransformer } from "svg-pathdata";
+import { GeometryError } from "../geometry/errors.js";
 const MAX_TEXT_LENGTH = 512;
 const MAX_TEXT_LINES = 16;
 const MAX_TEXT_GLYPHS = 2048;
 const MAX_TEXT_COMMANDS = 32000;
 const MAX_TEXT_PATH_BYTES = 1024 * 1024;
 const supportedText = /^[\p{Script=Latin}\p{Script=Greek}\p{Script=Cyrillic}\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}\p{Script=Common}\p{Script=Inherited}]*$/u;
-function fail(message) {
-    throw new Error(message);
+function fail(message, code = "INVALID_ARGUMENT") {
+    throw new GeometryError(code, message, { operation: "VectorFont.layout" });
 }
 function checkText(text) {
     if (text.length > MAX_TEXT_LENGTH)
-        fail("Text must contain at most 512 characters and 16 lines.");
+        fail("Text must contain at most 512 characters and 16 lines.", "COMPLEXITY_LIMIT");
     const lines = text.replaceAll("\r\n", "\n").replaceAll("\r", "\n").split("\n");
     if (lines.length > MAX_TEXT_LINES)
-        fail("Text must contain at most 512 characters and 16 lines.");
+        fail("Text must contain at most 512 characters and 16 lines.", "COMPLEXITY_LIMIT");
     if (!supportedText.test(text) ||
         /\p{Emoji_Presentation}|\p{Variation_Selector}|[\u200c-\u200f\u202a-\u202e\u2066-\u2069]/u.test(text))
         fail("This writing system or text direction is not supported yet. Use Latin, Greek, Cyrillic, or horizontal CJK text.");
@@ -27,9 +28,9 @@ function normalizeControls(options, staticWeight) {
         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.");
+            fail("Arc baseline radius must be positive and at most 10000 mm.", Number.isFinite(baseline.radius) ? "INVALID_ARGUMENT" : "NON_FINITE_VALUE");
+        if (baseline.centerAngle !== undefined && !Number.isFinite(baseline.centerAngle))
+            fail("Arc baseline centerAngle must be finite.", "NON_FINITE_VALUE");
         if (baseline.direction !== undefined &&
             baseline.direction !== "clockwise" &&
             baseline.direction !== "counterclockwise")
@@ -46,18 +47,18 @@ function normalizeControls(options, staticWeight) {
             ? undefined
             : {
                 radius: baseline.radius,
-                centerAngleDegrees: (((baseline.centerAngleDegrees ?? 90) % 360) + 360) % 360,
+                centerAngle: (((baseline.centerAngle ?? 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.");
+        fail("fontSize must be positive and at most 10000 mm.", Number.isFinite(controls.fontSize) ? "INVALID_ARGUMENT" : "NON_FINITE_VALUE");
     if (!Number.isInteger(controls.fontWeight) ||
         controls.fontWeight < 1 ||
         controls.fontWeight > 1000)
-        fail("fontWeight must be an integer from 1 through 1000.");
+        fail("fontWeight must be an integer from 1 through 1000.", Number.isFinite(controls.fontWeight) ? "INVALID_ARGUMENT" : "NON_FINITE_VALUE");
     if (!Number.isFinite(controls.letterSpacing) || Math.abs(controls.letterSpacing) > 100)
-        fail("letterSpacing must be finite and between -100 and 100 mm.");
+        fail("letterSpacing must be finite and between -100 and 100 mm.", Number.isFinite(controls.letterSpacing) ? "INVALID_ARGUMENT" : "NON_FINITE_VALUE");
     if (controls.align !== "left" && controls.align !== "center" && controls.align !== "right")
         fail("Invalid text alignment.");
     if (controls.verticalAlign !== "baseline" &&
@@ -69,7 +70,7 @@ function normalizeControls(options, staticWeight) {
         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.");
+        fail("lineHeight must be between 0.5 and 5.", Number.isFinite(controls.lineHeight) ? "INVALID_ARGUMENT" : "NON_FINITE_VALUE");
     return controls;
 }
 function selectFont(font, weight, staticWeight) {
@@ -130,8 +131,10 @@ function shapeLines(font, lines, controls) {
         // CSS tracking disables optional ligatures, retaining required shaping and combining marks.
         const run = font.layout(line, controls.letterSpacing === 0 ? undefined : { liga: false, clig: false });
         glyphs += run.glyphs.length;
-        if (run.glyphs.length !== run.positions.length || glyphs > MAX_TEXT_GLYPHS)
-            fail("The font returned an invalid or excessive glyph run.");
+        if (run.glyphs.length !== run.positions.length)
+            fail("The font returned an invalid glyph run.");
+        if (glyphs > MAX_TEXT_GLYPHS)
+            fail("The font returned an excessive glyph run.", "COMPLEXITY_LIMIT");
         let advance = 0;
         let spacingSteps = -1;
         for (let index = 0; index < run.glyphs.length; index++) {
@@ -139,14 +142,14 @@ function shapeLines(font, lines, controls) {
                 fail("The selected font shaped a missing glyph.");
             const position = run.positions[index];
             if (![position.xAdvance, position.yAdvance, position.xOffset, position.yOffset].every(Number.isFinite))
-                fail("The font returned a non-finite glyph position.");
+                fail("The font returned a non-finite glyph position.", "NON_FINITE_VALUE");
             if (index === 0 || position.xAdvance !== 0)
                 spacingSteps++;
             advance += position.xAdvance;
         }
         const advanceWidth = advance * scale + Math.max(0, spacingSteps) * controls.letterSpacing;
         if (!Number.isFinite(advanceWidth) || advanceWidth < 0)
-            fail("The shaped text advance must be finite and non-negative after letter spacing.");
+            fail("The shaped text advance must be finite and non-negative after letter spacing.", Number.isFinite(advanceWidth) ? "INVALID_ARGUMENT" : "NON_FINITE_VALUE");
         return { run, advanceWidth };
     });
 }
@@ -158,8 +161,10 @@ function convertCommand({ command, args }) {
             : command === "bezierCurveTo"
                 ? 6
                 : 2;
-    if (args.length !== argumentCount || !args.every(Number.isFinite))
+    if (args.length !== argumentCount)
         fail("The font returned invalid glyph path coordinates.");
+    if (!args.every(Number.isFinite))
+        fail("The font returned invalid glyph path coordinates.", "NON_FINITE_VALUE");
     switch (command) {
         case "moveTo":
             return { type: SVGPathData.MOVE_TO, relative: false, x: args[0], y: args[1] };
@@ -234,23 +239,23 @@ function buildLayout(font, fontMetrics, lines, controls) {
             const source = run.glyphs[index].path.commands;
             commands += source.length;
             if (commands > MAX_TEXT_COMMANDS)
-                fail("Text outlines exceed the supported complexity. Use fewer characters or a simpler font.");
+                fail("Text outlines exceed the supported complexity. Use fewer characters or a simpler font.", "COMPLEXITY_LIMIT");
             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));
                 let bounds = path.getBounds();
                 if (![bounds.minX, bounds.minY, bounds.maxX, bounds.maxY].every(Number.isFinite))
-                    fail("The font returned invalid glyph outline bounds.");
+                    fail("The font returned invalid glyph outline bounds.", "NON_FINITE_VALUE");
                 if (controls.baseline !== undefined) {
-                    const { radius, centerAngleDegrees, direction } = controls.baseline;
+                    const { radius, centerAngle, 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));
+                    const angleRadians = (centerAngle * Math.PI) / 180 + ((clockwise ? -1 : 1) * groupCenter) / radius;
+                    const rotationRadians = angleRadians + (clockwise ? -Math.PI / 2 : Math.PI / 2);
+                    const cosine = Math.cos(rotationRadians);
+                    const sine = Math.sin(rotationRadians);
+                    path.transform(SVGPathDataTransformer.MATRIX(cosine, sine, -sine, cosine, radius * Math.cos(angleRadians) - cosine * groupCenter, radius * Math.sin(angleRadians) - sine * groupCenter));
                     bounds = path.getBounds();
                 }
                 minX = Math.min(minX, bounds.minX);
@@ -278,7 +283,7 @@ function buildLayout(font, fontMetrics, lines, controls) {
         // Path commands and finite numeric coordinates are ASCII, so length is the encoded byte count.
         bytes += result.length;
         if (bytes > MAX_TEXT_PATH_BYTES)
-            fail("Text outlines exceed 1 MiB. Use fewer characters or a simpler font.");
+            fail("Text outlines exceed 1 MiB. Use fewer characters or a simpler font.", "COMPLEXITY_LIMIT");
         return result;
     });
     const metrics = Object.freeze({

package/package.json

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

package/dist/docs/reference/geometry/ClosestPointOnPathOptions.md

@@ -1,34 +0,0 @@
-# ClosestPointOnPathOptions
-
-Topology and work ceiling for a closest-point query on a sampled path.
-
-## Properties
-
-### closed?
-
-
-
-`readonly` `optional` **closed?**: `boolean`
-
-
-
-Include the last-to-first edge without duplicating the seam point. Defaults to false.
-
-***
-
-### limits?
-
-
-
-`readonly` `optional` **limits?**: `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\>
-
-
-
-Explicit path point ceiling; defaults to the package sampling limits.
-
-
-## Related APIs
-
-- [GeometrySamplingLimits](GeometrySamplingLimits.md)
-
-Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/geometry/ClosestPointOnPathResult.md

@@ -1,65 +0,0 @@
-# ClosestPointOnPathResult
-
-Closest position on a sampled path, measured in millimetres.
-
-## Type Parameters
-
-### Point
-
-`Point` *extends* [`Vector2Tuple`](Vector2Tuple.md) \| [`Vector3Tuple`](Vector3Tuple.md)
-
-## Properties
-
-### point
-
-
-
-`readonly` **point**: `Point`
-
-
-
-Copied position on the selected edge.
-
-***
-
-### distance
-
-
-
-`readonly` **distance**: `number`
-
-
-
-Euclidean distance from the query point to the path.
-
-***
-
-### edgeIndex
-
-
-
-`readonly` **edgeIndex**: `number`
-
-
-
-Zero-based starting vertex of the selected edge. Equal distances keep the first edge.
-
-***
-
-### fraction
-
-
-
-`readonly` **fraction**: `number`
-
-
-
-Clamped interpolation fraction from the edge's start to its end.
-
-
-## Related APIs
-
-- [Vector2Tuple](Vector2Tuple.md)
-- [Vector3Tuple](Vector3Tuple.md)
-
-Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/geometry/Path2.md

@@ -1,14 +0,0 @@
-# Path2
-
-An ordered, open sequence of two-dimensional points.
-
-**Path2** = readonly [`Vector2Tuple`](Vector2Tuple.md)[]
-
-
-
-
-## Related APIs
-
-- [Vector2Tuple](Vector2Tuple.md)
-
-Package: `@metamesh/modeling@0.14.0`.