@metamesh/modeling 0.0.0-stage → 0.7.0

package/dist/text/index.js

@@ -0,0 +1,58 @@
+import { SVGPathData, SVGPathDataTransformer } from "svg-pathdata";
+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 serializeVectorText({ paths, metrics }) {
+    const bounds = metrics.bounds;
+    if (bounds === null || paths.length === 0)
+        fail("The selected font produced no visible glyph outlines.");
+    const d = paths
+        .map((path) => new SVGPathData(path).transform(SVGPathDataTransformer.MATRIX(1, 0, 0, -1, 0, 0)).encode())
+        .join(" ");
+    const width = Math.max(0.001, bounds.max[0] - bounds.min[0]);
+    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.");
+    return svg;
+}
+/**
+ * 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.");
+    const staticWeight = options.staticWeight ?? 400;
+    if (!Number.isInteger(staticWeight) || staticWeight < 1 || staticWeight > 1000)
+        fail("staticWeight must be an integer from 1 through 1000.");
+    // 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."));
+        decoded = await decompress(decoded);
+        if (decoded.byteLength === 0 || decoded.byteLength > 32 * 1024 * 1024)
+            fail("The decoded font must be non-empty and at most 32 MiB.");
+    }
+    const fontkit = await import("fontkit").catch(() => fail("Install fontkit to prepare fonts with @metamesh/modeling/text."));
+    const font = fontkit.create(decoded);
+    if (!("layout" in font))
+        fail("Font collections are not supported.");
+    const layout = createVectorTextLayout(font, staticWeight);
+    const prepared = {
+        layout,
+        measure: (text, controls) => layout(text, controls).metrics,
+        toSvg: (text, controls) => serializeVectorText(layout(text, controls)),
+    };
+    return Object.freeze(prepared);
+}

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

@@ -0,0 +1,279 @@
+import { SVGPathData, SVGPathDataTransformer } from "svg-pathdata";
+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 checkText(text) {
+    if (text.length > MAX_TEXT_LENGTH)
+        fail("Text must contain at most 512 characters and 16 lines.");
+    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.");
+    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.");
+    if (lines.some((line) => /\p{Control}/u.test(line)))
+        fail("Control characters such as tabs are not supported in text layout.");
+    return lines;
+}
+function normalizeControls(options, staticWeight) {
+    const controls = {
+        fontSize: options.fontSize,
+        fontWeight: options.fontWeight ?? staticWeight,
+        letterSpacing: options.letterSpacing ?? 0,
+        align: options.align ?? "left",
+        verticalAlign: options.verticalAlign ?? "baseline",
+        lineHeight: options.lineHeight,
+    };
+    if (!Number.isFinite(controls.fontSize) || controls.fontSize <= 0 || controls.fontSize > 10000)
+        fail("fontSize must be positive and at most 10000 mm.");
+    if (!Number.isInteger(controls.fontWeight) ||
+        controls.fontWeight < 1 ||
+        controls.fontWeight > 1000)
+        fail("fontWeight must be an integer from 1 through 1000.");
+    if (!Number.isFinite(controls.letterSpacing) || Math.abs(controls.letterSpacing) > 100)
+        fail("letterSpacing must be finite and between -100 and 100 mm.");
+    if (controls.align !== "left" && controls.align !== "center" && controls.align !== "right")
+        fail("Invalid text alignment.");
+    if (controls.verticalAlign !== "baseline" &&
+        controls.verticalAlign !== "top" &&
+        controls.verticalAlign !== "center" &&
+        controls.verticalAlign !== "bottom")
+        fail("Invalid vertical text 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.");
+    return controls;
+}
+function selectFont(font, weight, staticWeight) {
+    const axis = font.variationAxes.wght;
+    if (axis === undefined) {
+        if (weight !== staticWeight)
+            fail("The selected static face does not support this weight.");
+        return font;
+    }
+    if (weight < axis.min || weight > axis.max)
+        fail(`fontWeight must be between ${axis.min} and ${axis.max} for this font.`);
+    return font.getVariation({
+        ...Object.fromEntries(Object.entries(font.variationAxes).flatMap(([tag, value]) => value === undefined ? [] : [[tag, value.default]])),
+        wght: weight,
+    });
+}
+function readFontMetrics(font) {
+    if (!Number.isFinite(font.unitsPerEm) || font.unitsPerEm <= 0)
+        fail("The font has invalid units-per-em metadata.");
+    // OpenType USE_TYPO_METRICS selects OS/2 values; fontkit's public getters always read hhea.
+    const os2 = "OS/2" in font ? font["OS/2"] : undefined;
+    let { ascent, descent, lineGap } = font;
+    if (typeof os2 === "object" &&
+        os2 !== null &&
+        "fsSelection" in os2 &&
+        typeof os2.fsSelection === "object" &&
+        os2.fsSelection !== null &&
+        "useTypoMetrics" in os2.fsSelection &&
+        os2.fsSelection.useTypoMetrics === true) {
+        if (!("typoAscender" in os2) ||
+            typeof os2.typoAscender !== "number" ||
+            !("typoDescender" in os2) ||
+            typeof os2.typoDescender !== "number" ||
+            !("typoLineGap" in os2) ||
+            typeof os2.typoLineGap !== "number")
+            fail("The selected font has invalid typographic metrics.");
+        ascent = os2.typoAscender;
+        descent = os2.typoDescender;
+        lineGap = os2.typoLineGap;
+    }
+    const lineHeight = ascent - descent + Math.max(0, lineGap);
+    if (![ascent, descent, lineGap, lineHeight].every(Number.isFinite) ||
+        ascent < 0 ||
+        descent > 0 ||
+        lineHeight <= 0)
+        fail("The selected font has invalid vertical metrics.");
+    return { ascent, descent: -descent, lineHeight };
+}
+function shapeLines(font, lines, controls) {
+    const scale = controls.fontSize / font.unitsPerEm;
+    let glyphs = 0;
+    return lines.map((line) => {
+        for (const character of line) {
+            const code = character.codePointAt(0);
+            if (!font.hasGlyphForCodePoint(code))
+                fail(`The selected font does not contain glyph U+${code.toString(16).toUpperCase().padStart(4, "0")}.`);
+        }
+        // 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.");
+        let advance = 0;
+        let spacingSteps = -1;
+        for (let index = 0; index < run.glyphs.length; index++) {
+            if (run.glyphs[index].id === 0)
+                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.");
+            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.");
+        return { run, advanceWidth };
+    });
+}
+function convertCommand({ command, args }) {
+    const argumentCount = command === "closePath"
+        ? 0
+        : command === "quadraticCurveTo"
+            ? 4
+            : command === "bezierCurveTo"
+                ? 6
+                : 2;
+    if (args.length !== argumentCount || !args.every(Number.isFinite))
+        fail("The font returned invalid glyph path coordinates.");
+    switch (command) {
+        case "moveTo":
+            return { type: SVGPathData.MOVE_TO, relative: false, x: args[0], y: args[1] };
+        case "lineTo":
+            return { type: SVGPathData.LINE_TO, relative: false, x: args[0], y: args[1] };
+        case "quadraticCurveTo":
+            return {
+                type: SVGPathData.QUAD_TO,
+                relative: false,
+                x1: args[0],
+                y1: args[1],
+                x: args[2],
+                y: args[3],
+            };
+        case "bezierCurveTo":
+            return {
+                type: SVGPathData.CURVE_TO,
+                relative: false,
+                x1: args[0],
+                y1: args[1],
+                x2: args[2],
+                y2: args[3],
+                x: args[4],
+                y: args[5],
+            };
+        case "closePath":
+            return { type: SVGPathData.CLOSE_PATH };
+        default:
+            return fail("The font returned an unsupported glyph path command.");
+    }
+}
+function freezeBounds(minX, minY, maxX, maxY) {
+    return Object.freeze({
+        min: Object.freeze([minX, minY]),
+        max: Object.freeze([maxX, maxY]),
+    });
+}
+function buildLayout(font, fontMetrics, lines, controls) {
+    const scale = controls.fontSize / font.unitsPerEm;
+    const lineHeight = controls.lineHeight === undefined
+        ? fontMetrics.lineHeight * scale
+        : controls.lineHeight * controls.fontSize;
+    const shaped = shapeLines(font, lines, controls);
+    const paths = [];
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    let commands = 0;
+    for (let lineIndex = 0; lineIndex < shaped.length; lineIndex++) {
+        const { run, advanceWidth } = shaped[lineIndex];
+        const lineX = controls.align === "center"
+            ? -advanceWidth / 2
+            : controls.align === "right"
+                ? -advanceWidth
+                : 0;
+        let x = 0;
+        let y = 0;
+        let spacingSteps = -1;
+        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)
+                spacingSteps++;
+            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.");
+            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();
+                if (![bounds.minX, bounds.minY, bounds.maxX, bounds.maxY].every(Number.isFinite))
+                    fail("The font returned invalid glyph outline bounds.");
+                minX = Math.min(minX, bounds.minX);
+                minY = Math.min(minY, bounds.minY);
+                maxX = Math.max(maxX, bounds.maxX);
+                maxY = Math.max(maxY, bounds.maxY);
+                paths.push(path);
+            }
+            x += position.xAdvance;
+            y += position.yAdvance;
+        }
+    }
+    const offsetY = paths.length === 0 || controls.verticalAlign === "baseline"
+        ? 0
+        : controls.verticalAlign === "top"
+            ? -maxY
+            : controls.verticalAlign === "bottom"
+                ? -minY
+                : -(minY + maxY) / 2;
+    let bytes = 0;
+    const encoded = paths.map((path) => {
+        if (offsetY !== 0)
+            path.transform(SVGPathDataTransformer.TRANSLATE(0, offsetY));
+        const result = path.encode();
+        // 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.");
+        return result;
+    });
+    const metrics = Object.freeze({
+        bounds: paths.length === 0 ? null : freezeBounds(minX, minY + offsetY, maxX, maxY + offsetY),
+        advance: Object.freeze([
+            shaped.at(-1).advanceWidth,
+            lines.length === 1 ? 0 : -(lines.length - 1) * lineHeight,
+        ]),
+        logicalWidth: Math.max(...shaped.map((line) => line.advanceWidth)),
+        ascent: fontMetrics.ascent * scale,
+        descent: fontMetrics.descent * scale,
+        lineHeight,
+        lineCount: lines.length,
+    });
+    return Object.freeze({ paths: Object.freeze(encoded), metrics });
+}
+/** One retained variation and one immutable layout bound work and memory per prepared font. */
+export function createVectorTextLayout(font, staticWeight) {
+    let selected;
+    let previous;
+    return (text, options) => {
+        const lines = checkText(text);
+        const controls = normalizeControls(options, staticWeight);
+        const key = JSON.stringify([lines, controls]);
+        if (previous?.key === key)
+            return previous.layout;
+        if (selected?.weight !== controls.fontWeight) {
+            const variation = selectFont(font, controls.fontWeight, staticWeight);
+            selected = {
+                weight: controls.fontWeight,
+                font: variation,
+                metrics: readFontMetrics(variation),
+            };
+        }
+        const layout = buildLayout(selected.font, selected.metrics, lines, controls);
+        previous = { key, layout };
+        return layout;
+    };
+}

package/package.json

@@ -1,6 +1,103 @@
 {
   "name": "@metamesh/modeling",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.7.0",
+  "description": "Scoped solid modeling and pure geometry foundations for Node and browsers.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JasonKoolman/metamesh.git",
+    "directory": "packages/modeling"
+  },
+  "homepage": "https://github.com/JasonKoolman/metamesh#readme",
+  "bugs": {
+    "url": "https://github.com/JasonKoolman/metamesh/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "CHANGELOG.md",
+    "dist/**/*.js",
+    "dist/api/*.d.ts",
+    "THIRD_PARTY_NOTICES.md",
+    "dist/**/*.wasm",
+    "dist/engine/kernel/LICENSE",
+    "!dist/geometry-module.js",
+    "!dist/modeling-module.js"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/api/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./geometry": {
+      "types": "./dist/api/geometry.d.ts",
+      "import": "./dist/geometry/index.js"
+    },
+    "./engine": {
+      "types": "./dist/api/engine.d.ts",
+      "import": "./dist/engine/index.js"
+    },
+    "./text": {
+      "types": "./dist/api/text.d.ts",
+      "import": "./dist/text/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "polygon-clipping": "^0.15.7",
+    "saxes": "^6.0.0",
+    "svg-pathdata": "^9.0.0",
+    "fflate": "^0.8.3"
+  },
+  "devDependencies": {
+    "@metamesh/config": "0.0.0",
+    "@microsoft/api-extractor": "^7.59.4",
+    "@types/fontkit": "^2.0.9",
+    "@vitest/coverage-v8": "^5.0.3",
+    "esbuild": "^0.28.2",
+    "fast-check": "4.10.2",
+    "typedoc": "0.28.20",
+    "typedoc-plugin-markdown": "4.13.1",
+    "typescript": "6.0.3",
+    "vitest": "^5.0.3",
+    "manifold-3d": "3.5.4",
+    "fontkit": "^2.0.4",
+    "woff2-encoder": "2.0.0"
+  },
+  "peerDependencies": {
+    "fontkit": "^2.0.4",
+    "woff2-encoder": "2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "fontkit": {
+      "optional": true
+    },
+    "woff2-encoder": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "api:extract:check": "api-extractor run --config config/api-extractor.root.json && api-extractor run --config config/api-extractor.geometry.json && api-extractor run --config config/api-extractor.engine.json && api-extractor run --config config/api-extractor.text.json && node scripts/build-engine-declarations.mjs && node scripts/check-model-declarations.mjs",
+    "api:extract:update": "api-extractor run --local --config config/api-extractor.root.json && api-extractor run --local --config config/api-extractor.geometry.json && api-extractor run --local --config config/api-extractor.engine.json && api-extractor run --local --config config/api-extractor.text.json && node scripts/build-engine-declarations.mjs && node scripts/check-model-declarations.mjs",
+    "build": "pnpm run build:declarations && pnpm run api:extract:check && pnpm run runtime:verify",
+    "build:update-api": "pnpm run build:declarations && pnpm run api:extract:update && pnpm run runtime:verify",
+    "build:declarations": "node ../../scripts/clean-dist.mjs && node scripts/build-kernel-assets.mjs && tsc -p tsconfig.build.json && node scripts/build-geometry-module.mjs && node scripts/build-modeling-module.mjs",
+    "coverage": "node scripts/build-kernel-assets.mjs && vitest run src --coverage",
+    "docs": "pnpm run build && typedoc --options typedoc.json",
+    "docs:reference:generate": "pnpm run build:update-api && pnpm run docs:reference:test && node scripts/generate-reference-docs.mjs",
+    "docs:reference:check": "pnpm run build && pnpm run docs:reference:verify",
+    "docs:reference:test": "node --test scripts/reference-model.spec.mjs",
+    "docs:reference:verify": "pnpm run docs:reference:test && node scripts/generate-reference-docs.mjs --check",
+    "fixtures:check": "pnpm run build && pnpm run fixtures:verify",
+    "fixtures:verify": "tsc -p fixtures/tsconfig.json --pretty false && node scripts/check-pure-virtual-module.mjs",
+    "lint": "node scripts/check-import-boundaries.mjs && eslint .",
+    "runtime:verify": "node scripts/check-runtime-entrypoints.mjs",
+    "test": "node scripts/build-kernel-assets.mjs && vitest run src",
+    "test:mesh-snapshots": "vitest run src/geometry/mechanical/mesh-regression.spec.ts",
+    "test:mesh-snapshots:update": "vitest run src/geometry/mechanical/mesh-regression.spec.ts -u",
+    "typecheck": "tsc --noEmit --pretty false"
+  }
 }