meshwriter-cudu 3.0.0

package/dist/meshwriter.cjs.js

@@ -0,0 +1,2645 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var math_vector = require('@babylonjs/core/Maths/math.vector');
+var math_color = require('@babylonjs/core/Maths/math.color');
+var math_path = require('@babylonjs/core/Maths/math.path');
+var mesh = require('@babylonjs/core/Meshes/mesh');
+var mesh_vertexData = require('@babylonjs/core/Meshes/mesh.vertexData');
+var polygonMesh = require('@babylonjs/core/Meshes/polygonMesh');
+var standardMaterial = require('@babylonjs/core/Materials/standardMaterial');
+var materialPluginBase = require('@babylonjs/core/Materials/materialPluginBase');
+var solidParticleSystem = require('@babylonjs/core/Particles/solidParticleSystem');
+var csg = require('@babylonjs/core/Meshes/csg');
+var csg2 = require('@babylonjs/core/Meshes/csg2');
+var earcutModule = require('earcut');
+
+/**
+ * MeshWriter Utility Functions
+ * Pure helper functions with no external dependencies
+ */
+
+const floor$2 = Math.floor;
+
+// Type checking functions
+function isPositiveNumber(mn) {
+    return typeof mn === "number" && !isNaN(mn) ? 0 < mn : false;
+}
+
+function isNumber(mn) {
+    return typeof mn === "number";
+}
+
+function isBoolean(mn) {
+    return typeof mn === "boolean";
+}
+
+function isAmplitude(ma) {
+    return typeof ma === "number" && !isNaN(ma) ? 0 <= ma && ma <= 1 : false;
+}
+
+function isObject(mo) {
+    return mo != null && typeof mo === "object" || typeof mo === "function";
+}
+
+function isPromiseLike(mo) {
+    return isObject(mo) && typeof mo.then === "function";
+}
+
+function isArray(ma) {
+    return ma != null && typeof ma === "object" && ma.constructor === Array;
+}
+
+function isString(ms) {
+    return typeof ms === "string" ? ms.length > 0 : false;
+}
+
+function isRelativeLength(l) {
+    return l === 3 || l === 5 || l === 7;
+}
+
+// Math utilities
+function round(n) {
+    return floor$2(0.3 + n * 1000000) / 1000000;
+}
+
+function weeid() {
+    return Math.floor(Math.random() * 1000000);
+}
+
+// Option handling
+function setOption(opts, field, tst, defalt) {
+    return tst(opts[field]) ? opts[field] : defalt;
+}
+
+/**
+ * MeshWriter Font Compression/Decompression
+ * Base-128 encoding for font data compression (~50% size reduction)
+ */
+
+
+const floor$1 = Math.floor;
+
+// Encoding arrays (initialized once at module load)
+let b128back;
+let b128digits;
+
+/**
+ * Initialize encoding arrays for base-128 conversion
+ * Called once when module loads
+ */
+function prepArray() {
+    let pntr = -1;
+    let n;
+    b128back = new Uint8Array(256);
+    b128digits = new Array(128);
+
+    while (160 > pntr++) {
+        if (pntr < 128) {
+            n = fr128to256(pntr);
+            b128digits[pntr] = String.fromCharCode(n);
+            b128back[n] = pntr;
+        } else {
+            if (pntr === 128) {
+                b128back[32] = pntr;
+            } else {
+                b128back[pntr + 71] = pntr;
+            }
+        }
+    }
+
+    function fr128to256(n) {
+        if (n < 92) {
+            return n < 58 ? n < 6 ? n + 33 : n + 34 : n + 35;
+        } else {
+            return n + 69;
+        }
+    }
+}
+
+// Initialize on module load
+prepArray();
+
+/**
+ * Convert base-128 encoded string to number
+ */
+function frB128(s) {
+    let result = 0;
+    let i = -1;
+    const l = s.length - 1;
+    while (i++ < l) {
+        result = result * 128 + b128back[s.charCodeAt(i)];
+    }
+    return result;
+}
+
+/**
+ * Convert number to base-128 encoded string
+ */
+function toB128(i) {
+    let s = b128digits[(i % 128)];
+    i = floor$1(i / 128);
+    while (i > 0) {
+        s = b128digits[(i % 128)] + s;
+        i = floor$1(i / 128);
+    }
+    return s;
+}
+
+/**
+ * Decode a compressed command list string
+ * @param {string} str - Compressed string (space-separated encoded commands)
+ * @returns {Array} - Array of decoded command arrays
+ */
+function decodeList(str) {
+    const split = str.split(" ");
+    const list = [];
+
+    split.forEach(function(cmds) {
+        if (cmds.length === 12) { list.push(decode6(cmds)); }
+        if (cmds.length === 8) { list.push(decode4(cmds)); }
+        if (cmds.length === 4) { list.push(decode2(cmds)); }
+    });
+
+    return list;
+
+    function decode6(s) {
+        return [
+            decode1(s, 0, 2), decode1(s, 2, 4), decode1(s, 4, 6),
+            decode1(s, 6, 8), decode1(s, 8, 10), decode1(s, 10, 12)
+        ];
+    }
+    function decode4(s) {
+        return [decode1(s, 0, 2), decode1(s, 2, 4), decode1(s, 4, 6), decode1(s, 6, 8)];
+    }
+    function decode2(s) {
+        return [decode1(s, 0, 2), decode1(s, 2, 4)];
+    }
+    function decode1(s, start, end) {
+        return (frB128(s.substring(start, end)) - 4000) / 2;
+    }
+}
+
+/**
+ * Encode a command list to compressed string
+ * @param {Array} list - Array of command arrays
+ * @returns {string} - Compressed string
+ */
+function codeList(list) {
+    let str = "";
+    let xtra = "";
+
+    if (isArray(list)) {
+        list.forEach(function(cmds) {
+            if (cmds.length === 6) { str += xtra + code6(cmds); xtra = " "; }
+            if (cmds.length === 4) { str += xtra + code4(cmds); xtra = " "; }
+            if (cmds.length === 2) { str += xtra + code2(cmds); xtra = " "; }
+        });
+    }
+
+    return str;
+
+    function code6(a) {
+        return code1(a[0]) + code1(a[1]) + code1(a[2]) + code1(a[3]) + code1(a[4]) + code1(a[5]);
+    }
+    function code4(a) {
+        return code1(a[0]) + code1(a[1]) + code1(a[2]) + code1(a[3]);
+    }
+    function code2(a) {
+        return code1(a[0]) + code1(a[1]);
+    }
+    function code1(n) {
+        return toB128((n + n) + 4000);
+    }
+}
+
+/**
+ * MeshWriter Font Registry
+ * Manages font registration and lookup
+ */
+
+
+// Private font storage
+const FONTS = {};
+
+/**
+ * Register a font for use with MeshWriter
+ * @param {string} name - Font name (case-sensitive, used in "font-family" option)
+ * @param {Function|Object} fontData - Font factory function or pre-initialized font object
+ *
+ * @example
+ * // Register a font factory (receives codeList for encoding)
+ * import helvetica from 'meshwriter/fonts/helvetica';
+ * registerFont('Helvetica', helvetica);
+ *
+ * // Register with aliases
+ * registerFont('Arial', helvetica);
+ * registerFont('sans-serif', helvetica);
+ */
+function registerFont(name, fontData) {
+    if (typeof fontData === 'function') {
+        // Font is a factory function expecting codeList
+        FONTS[name] = fontData(codeList);
+    } else if (isObject(fontData)) {
+        // Font is already initialized
+        FONTS[name] = fontData;
+    } else {
+        throw new Error(`MeshWriter: Invalid font data for "${name}"`);
+    }
+}
+
+/**
+ * Register multiple font aliases pointing to the same font
+ * @param {string} targetName - Name of already-registered font
+ * @param {...string} aliases - Alias names to register
+ *
+ * @example
+ * registerFont('Helvetica', helveticaData);
+ * registerFontAliases('Helvetica', 'Arial', 'sans-serif');
+ */
+function registerFontAliases(targetName, ...aliases) {
+    if (!FONTS[targetName]) {
+        throw new Error(`MeshWriter: Cannot create aliases: font "${targetName}" not registered`);
+    }
+    aliases.forEach(alias => {
+        FONTS[alias] = FONTS[targetName];
+    });
+}
+
+/**
+ * Get a registered font by name
+ * @param {string} name - Font name
+ * @returns {Object|undefined} - Font object or undefined if not found
+ */
+function getFont(name) {
+    return FONTS[name];
+}
+
+/**
+ * Check if a font is registered
+ * @param {string} name - Font name
+ * @returns {boolean}
+ */
+function isFontRegistered(name) {
+    return isObject(FONTS[name]);
+}
+
+/**
+ * Get list of all registered font names
+ * @returns {string[]}
+ */
+function getRegisteredFonts() {
+    return Object.keys(FONTS);
+}
+
+/**
+ * Unregister a font (mainly for testing)
+ * @param {string} name - Font name to remove
+ */
+function unregisterFont(name) {
+    delete FONTS[name];
+}
+
+/**
+ * Clear all registered fonts (mainly for testing)
+ */
+function clearFonts() {
+    Object.keys(FONTS).forEach(key => delete FONTS[key]);
+}
+
+/**
+ * MeshWriter CSG Module
+ * Handles CSG version detection, async initialization, and ready state management
+ */
+
+
+// CSG libraries - initialized from Babylon imports or external source
+let CSG = csg.CSG;
+let CSG2 = csg2.CSG2;
+let InitializeCSG2Async = csg2.InitializeCSG2Async;
+let IsCSG2Ready = csg2.IsCSG2Ready;
+
+// State
+let csgVersion = null;        // 'CSG2', 'CSG', or null
+let csgReady = false;
+const csgReadyListeners = [];
+let externalCSGInitializer = null;
+let externalCSGReadyCheck = null;
+
+/**
+ * Initialize CSG module with Babylon.js CSG classes
+ * Must be called before using any CSG functionality
+ * @param {Object} babylon - Object containing CSG, CSG2, InitializeCSG2Async, IsCSG2Ready
+ */
+function initCSGModule(babylon) {
+    if (isObject(babylon)) {
+        CSG = babylon.CSG || null;
+        CSG2 = babylon.CSG2 || null;
+        InitializeCSG2Async = babylon.InitializeCSG2Async || null;
+        IsCSG2Ready = babylon.IsCSG2Ready || null;
+    }
+    csgVersion = detectCSGVersion();
+
+    // Legacy CSG is immediately ready
+    if (csgVersion === 'CSG') {
+        markCSGInitialized();
+    } else if (csgVersion === 'CSG2') {
+        // Check if CSG2 is already initialized
+        csgReady = false;
+        if (runCSGReadyCheck()) {
+            markCSGInitialized();
+        }
+    }
+}
+
+/**
+ * Detect which CSG implementation is available
+ * @returns {'CSG2'|'CSG'|null}
+ */
+function detectCSGVersion() {
+    // Prefer CSG2 (Babylon 7.31+)
+    if (isObject(CSG2) && typeof InitializeCSG2Async === 'function') {
+        return 'CSG2';
+    }
+    // Fall back to legacy CSG
+    if (isObject(CSG) && typeof CSG.FromMesh === 'function') {
+        return 'CSG';
+    }
+    return null;
+}
+
+/**
+ * Mark CSG as ready and notify all listeners
+ */
+function markCSGInitialized() {
+    if (csgReady) {
+        return;
+    }
+    csgReady = true;
+
+    // Notify all waiting listeners
+    if (csgReadyListeners.length) {
+        csgReadyListeners.splice(0).forEach(function(listener) {
+            try {
+                listener();
+            } catch (err) {
+                console.error("MeshWriter: onCSGReady listener failed", err);
+            }
+        });
+    }
+}
+
+/**
+ * Check if CSG is ready for use
+ * @returns {boolean}
+ */
+function isCSGReady() {
+    if (csgVersion === 'CSG2') {
+        refreshCSGReadyState();
+        return csgReady;
+    }
+    return csgVersion === 'CSG';
+}
+
+/**
+ * Refresh CSG2 ready state from external checks
+ */
+function refreshCSGReadyState() {
+    if (csgVersion !== 'CSG2' || csgReady) {
+        return;
+    }
+    if (runCSGReadyCheck()) {
+        markCSGInitialized();
+    }
+}
+
+/**
+ * Run CSG ready check (external or native)
+ */
+function runCSGReadyCheck() {
+    // Try external ready check first
+    if (typeof externalCSGReadyCheck === "function") {
+        try {
+            if (externalCSGReadyCheck()) {
+                return true;
+            }
+        } catch (err) {
+            console.warn("MeshWriter: external CSG ready check failed", err);
+        }
+    }
+
+    // Check native IsCSG2Ready
+    if (typeof IsCSG2Ready === "function" && IsCSG2Ready()) {
+        return true;
+    }
+
+    return false;
+}
+
+/**
+ * Initialize CSG2 asynchronously
+ * @returns {Promise<void>}
+ */
+async function initializeCSG2() {
+    if (csgVersion !== 'CSG2') {
+        return;
+    }
+    if (csgReady) {
+        return;
+    }
+
+    const initializer = externalCSGInitializer || InitializeCSG2Async;
+    if (typeof initializer !== "function") {
+        throw new Error(
+            "MeshWriter: No CSG2 initializer available. " +
+            "Use MeshWriter.setCSGInitializer() or ensure BABYLON.InitializeCSG2Async is available."
+        );
+    }
+
+    const result = initializer();
+    if (isPromiseLike(result)) {
+        await result;
+    }
+    markCSGInitialized();
+}
+
+// Public API
+
+/**
+ * Get the current CSG version being used
+ * @returns {'CSG2'|'CSG'|null}
+ */
+function getCSGVersion() {
+    return csgVersion;
+}
+
+/**
+ * Set an external CSG2 initializer function
+ * @param {Function} fn - Async function that initializes CSG2
+ */
+function setCSGInitializer(fn) {
+    if (typeof fn === "function") {
+        externalCSGInitializer = fn;
+    }
+}
+
+/**
+ * Set an external CSG2 ready check function
+ * @param {Function} fn - Function that returns true when CSG2 is ready
+ */
+function setCSGReadyCheck(fn) {
+    if (typeof fn === "function") {
+        externalCSGReadyCheck = fn;
+        refreshCSGReadyState();
+    }
+}
+
+/**
+ * Register a callback to be called when CSG is ready
+ * If CSG is already ready, callback is called immediately
+ * @param {Function} listener
+ */
+function onCSGReady(listener) {
+    if (typeof listener !== "function") {
+        return;
+    }
+    if (isCSGReady()) {
+        listener();
+    } else {
+        csgReadyListeners.push(listener);
+    }
+}
+
+/**
+ * Get the CSG library to use for operations
+ * @returns {Object} - CSG or CSG2 class
+ */
+function getCSGLib() {
+    return csgVersion === 'CSG2' ? CSG2 : CSG;
+}
+
+/**
+ * TextFogPlugin - MaterialPluginBase that applies fog to emissive color
+ *
+ * Babylon's standard fog only affects diffuse/ambient channels.
+ * This plugin recalculates fog blending for the final color output,
+ * ensuring emissive text fades properly with distance fog.
+ */
+
+
+/**
+ * Plugin that applies scene fog to text materials by modifying
+ * the final fragment color before output.
+ */
+class TextFogPlugin extends materialPluginBase.MaterialPluginBase {
+    /**
+     * @param {import('@babylonjs/core/Materials/material').Material} material
+     */
+    constructor(material) {
+        var priority = 300; // Run after standard material processing
+        var defines = { 'MESHWRITER_TEXT_FOG': false };
+        super(material, 'TextFogPlugin', priority, defines);
+        this._enable(true);
+    }
+
+    /**
+     * Set the define based on whether scene fog is enabled
+     * @param {object} defines
+     * @param {import('@babylonjs/core/scene').Scene} scene
+     * @param {import('@babylonjs/core/Meshes/mesh').Mesh} mesh
+     */
+    prepareDefines(defines, scene, mesh) {
+        // Enable when scene has any fog mode set (1=LINEAR, 2=EXP, 3=EXP2)
+        defines['MESHWRITER_TEXT_FOG'] = scene.fogMode !== 0;
+    }
+
+    getClassName() {
+        return 'TextFogPlugin';
+    }
+
+    getUniforms() {
+        // We use Babylon's built-in fog uniforms (vFogInfos, vFogColor)
+        // which are already available in the standard material
+        return { ubo: [] };
+    }
+
+    /**
+     * Clean up the plugin
+     */
+    dispose() {
+        super.dispose();
+    }
+
+    /**
+     * Inject shader code to apply fog to emissive color
+     * @param {string} shaderType - 'vertex' or 'fragment'
+     */
+    getCustomCode(shaderType) {
+        if (shaderType === 'fragment') {
+            return {
+                // This injection point runs just before gl_FragColor is finalized
+                // At this point, standard fog has been applied to diffuse/ambient
+                // but emissive contribution bypasses fog, so we re-apply fog
+                // to the entire output to properly fade text into fog
+                'CUSTOM_FRAGMENT_BEFORE_FRAGCOLOR': `
+                    #ifdef MESHWRITER_TEXT_FOG
+                    #ifdef FOG
+                    // Recalculate fog for the full fragment color including emissive
+                    // vFogInfos: x=fogMode, y=fogStart, z=fogEnd, w=fogDensity
+                    // vFogColor: fog RGB color
+                    // vFogDistance: vec3 distance from camera (set by vertex shader)
+
+                    float textFogFactor = 1.0;
+                    float textFogDist = length(vFogDistance);
+
+                    if (FOGMODE_LINEAR == vFogInfos.x) {
+                        // Linear fog: factor = (end - dist) / (end - start)
+                        textFogFactor = clamp((vFogInfos.z - textFogDist) / (vFogInfos.z - vFogInfos.y), 0.0, 1.0);
+                    } else if (FOGMODE_EXP == vFogInfos.x) {
+                        // Exponential fog: factor = exp(-dist * density)
+                        textFogFactor = clamp(exp(-textFogDist * vFogInfos.w), 0.0, 1.0);
+                    } else if (FOGMODE_EXP2 == vFogInfos.x) {
+                        // Exponential squared fog: factor = exp(-(dist * density)^2)
+                        float fogDistDensity = textFogDist * vFogInfos.w;
+                        textFogFactor = clamp(exp(-fogDistDensity * fogDistDensity), 0.0, 1.0);
+                    }
+
+                    // Blend the entire fragment (including emissive) toward fog color
+                    // textFogFactor: 1.0 = no fog (full color), 0.0 = full fog
+                    color.rgb = mix(vFogColor, color.rgb, textFogFactor);
+                    #endif
+                    #endif
+                `,
+            };
+        }
+        return null;
+    }
+}
+
+/**
+ * MeshWriter Material Creation
+ * Creates StandardMaterial for text rendering
+ */
+
+
+/** @typedef {import('@babylonjs/core/scene').Scene} Scene */
+
+const floor = Math.floor;
+
+/**
+ * Convert hex color string to Babylon Color3
+ * @param {string} rgb - Hex color string (e.g., "#FF0000" or "FF0000")
+ * @returns {Color3}
+ */
+function rgb2Color3(rgb) {
+    rgb = rgb.replace("#", "");
+    return new math_color.Color3(
+        convert(rgb.substring(0, 2)),
+        convert(rgb.substring(2, 4)),
+        convert(rgb.substring(4, 6))
+    );
+
+    function convert(x) {
+        const parsed = parseInt(x, 16);
+        const val = isNaN(parsed) ? 0 : parsed;
+        return floor(1000 * Math.max(0, Math.min(val / 255, 1))) / 1000;
+    }
+}
+
+/**
+ * Create a StandardMaterial for text
+ * @param {Scene} scene - Babylon scene
+ * @param {string} letters - Text string (used for material naming)
+ * @param {string} emissive - Hex color for emissive
+ * @param {string} ambient - Hex color for ambient
+ * @param {string} specular - Hex color for specular
+ * @param {string} diffuse - Hex color for diffuse
+ * @param {number} opac - Opacity (0-1)
+ * @param {boolean} [emissiveOnly=false] - If true, disables lighting (only emissive color shows)
+ * @param {boolean} [fogEnabled=true] - If true, the material is affected by scene fog
+ * @returns {StandardMaterial}
+ */
+function makeMaterial(scene, letters, emissive, ambient, specular, diffuse, opac, emissiveOnly = false, fogEnabled = true) {
+    const material = new standardMaterial.StandardMaterial("mw-matl-" + letters + "-" + weeid(), scene);
+    material.diffuseColor = rgb2Color3(diffuse);
+    material.specularColor = rgb2Color3(specular);
+    material.ambientColor = rgb2Color3(ambient);
+    material.emissiveColor = rgb2Color3(emissive);
+    material.alpha = opac;
+
+    // When emissiveOnly is true, disable lighting so only emissive color shows
+    // This gives a "self-lit" appearance that ignores scene lights
+    if (emissiveOnly) {
+        material.disableLighting = true;
+    }
+
+    // Emissive-only materials should be self-lit and not affected by fog
+    if (emissiveOnly) {
+        material.fogEnabled = false;
+    } else {
+        material.fogEnabled = fogEnabled;
+        // Attach fog plugin to properly blend emissive color with fog
+        // Babylon's standard fog only affects diffuse/ambient, not emissive.
+        // The plugin re-fogs the entire fragment output so emissive fades properly.
+        // (The slight double-fog on diffuse/ambient is negligible since text is primarily emissive)
+        if (fogEnabled) {
+            material._textFogPlugin = new TextFogPlugin(material);
+        }
+    }
+
+    return material;
+}
+
+/**
+ * Create a dedicated emissive material for front faces.
+ * This keeps the face self-lit while still respecting fog settings.
+ * @param {Scene} scene
+ * @param {string} letters
+ * @param {string} emissive
+ * @param {number} opac
+ * @param {boolean} fogEnabled
+ * @returns {StandardMaterial}
+ */
+function makeFaceMaterial(scene, letters, emissive, opac, fogEnabled = true) {
+    const material = new standardMaterial.StandardMaterial("mw-face-matl-" + letters + "-" + weeid(), scene);
+    const black = rgb2Color3("#000000");
+    material.diffuseColor = black;
+    material.specularColor = black;
+    material.ambientColor = black;
+    material.emissiveColor = rgb2Color3(emissive);
+    material.disableLighting = true;
+    material.alpha = opac;
+    material.backFaceCulling = false;
+    material.fogEnabled = fogEnabled;
+    if (fogEnabled) {
+        material._textFogPlugin = new TextFogPlugin(material);
+    }
+    return material;
+}
+
+/**
+ * MeshWriter SPS (Solid Particle System) Helpers
+ * Converts letter meshes into an efficient SPS
+ */
+
+
+/** @typedef {import('@babylonjs/core/scene').Scene} Scene */
+/** @typedef {import('@babylonjs/core/Materials/material').Material} Material */
+/** @typedef {import('@babylonjs/core/Meshes/mesh').Mesh} BabylonMesh */
+/** @typedef {(any[] & { faceMeshes?: BabylonMesh[] })} MeshCollection */
+/**
+ * @typedef {[SolidParticleSystem | undefined, BabylonMesh | undefined] & {
+ *   face: [SolidParticleSystem | undefined, BabylonMesh | undefined];
+ * }} SPSCombo
+ */
+
+/**
+ * Create an SPS from letter meshes
+ * @param {Scene} scene - Babylon scene
+ * @param {MeshCollection} meshesAndBoxes - [meshes, boxes, origins] with optional face geometry
+ * @param {Material} material - Material to apply to SPS mesh
+ * @returns {SPSCombo} - Combined SPS + emissive face SPS
+ */
+function makeSPS(scene, meshesAndBoxes, material) {
+    const rimMeshes = meshesAndBoxes[0] || [];
+    const faceMeshes = meshesAndBoxes.faceMeshes || [];
+    const lettersOrigins = meshesAndBoxes[2] || [];
+
+    const rim = buildSystem("sps_rim", rimMeshes, lettersOrigins, scene, material);
+
+    // Use Mesh.MergeMeshes for face instead of SPS - SPS has issues with face geometry
+    const face = buildFaceMesh("sps_face", faceMeshes, lettersOrigins);
+
+    /** @type {SPSCombo} */
+    const combo = /** @type {any} */ ([rim.sps, rim.mesh]);
+    combo.face = [undefined, face.mesh]; // No SPS for face, just merged mesh
+    return combo;
+}
+
+/**
+ * Build face mesh using Mesh.MergeMeshes instead of SPS
+ * @param {string} name - Mesh name
+ * @param {BabylonMesh[]} meshes - Face meshes to merge
+ * @param {Array} lettersOrigins - Letter origin positions
+ * @param {Scene} scene - Babylon scene
+ * @returns {{ mesh: BabylonMesh | undefined }}
+ */
+function buildFaceMesh(name, meshes, lettersOrigins, scene) {
+    const validMeshes = meshes.filter(m => m != null);
+    if (!validMeshes.length) {
+        return { mesh: undefined };
+    }
+
+    // Position each mesh according to letter origins before merging
+    validMeshes.forEach((mesh, ix) => {
+        if (lettersOrigins[ix]) {
+            mesh.position.x = lettersOrigins[ix][0] + lettersOrigins[ix][1];
+            mesh.position.z = lettersOrigins[ix][2];
+        }
+    });
+
+    // Merge all face meshes into one
+    const merged = mesh.Mesh.MergeMeshes(validMeshes, true, true, undefined, false, true);
+    if (merged) {
+        merged.name = name;
+    }
+
+    return { mesh: merged };
+}
+
+function buildSystem(name, meshes, lettersOrigins, scene, material) {
+    // Pre-filter null meshes to avoid repeated null checks in hot loop
+    const validMeshes = meshes
+        .map((mesh, ix) => mesh ? { mesh, origins: lettersOrigins[ix] } : null)
+        .filter(item => item !== null);
+
+    if (!validMeshes.length) {
+        return { sps: undefined, mesh: undefined };
+    }
+
+    const sps = new solidParticleSystem.SolidParticleSystem(name, scene, {});
+    validMeshes.forEach(function(item) {
+        sps.addShape(item.mesh, 1, {
+            positionFunction: makePositionParticle(item.origins)
+        });
+        item.mesh.dispose();
+    });
+
+    const spsMesh = sps.buildMesh();
+
+    if (spsMesh && material) {
+        spsMesh.material = material;
+    }
+    sps.setParticles();
+
+    return { sps, mesh: spsMesh };
+}
+
+function makePositionParticle(letterOrigins) {
+    return function positionParticle(particle) {
+        if (!letterOrigins) return;
+        particle.position.x = letterOrigins[0] + letterOrigins[1];
+        particle.position.z = letterOrigins[2];
+    };
+}
+
+/**
+ * Split a mesh into two meshes: emissive face geometry and lit rim geometry.
+ * @param {import('@babylonjs/core').Mesh} mesh
+ * @param {import('@babylonjs/core').Scene} scene
+ * @returns {{ rimMesh: import('@babylonjs/core').Mesh, faceMesh: import('@babylonjs/core').Mesh | null }}
+ */
+function splitMeshByFaceNormals(mesh, scene) {
+    var geometry = mesh.geometry;
+    if (!geometry) {
+        return { rimMesh: mesh, faceMesh: null }
+    }
+
+    var positions = geometry.getVerticesData('position');
+    var normals = geometry.getVerticesData('normal');
+    var uvs = geometry.getVerticesData('uv');
+    var indices = geometry.getIndices();
+
+    if (!positions || !normals || !indices || positions.length === 0) {
+        return { rimMesh: mesh, faceMesh: null }
+    }
+
+    var faceData = createEmptyData();
+    var rimData = createEmptyData();
+
+    var axisInfo = detectFaceAxisFromGeometry(positions, normals, indices);
+    if (!axisInfo) {
+        axisInfo = detectFaceAxis(normals);
+    }
+    if (!axisInfo) {
+        axisInfo = detectExtrudeAxisFromPositions(positions);
+    }
+
+    for (var i = 0; i < indices.length; i += 3) {
+        var i0 = indices[i];
+        var i1 = indices[i + 1];
+        var i2 = indices[i + 2];
+        var isFace = triangleIsFrontFace(i0, i1, i2, positions, normals, axisInfo);
+        var target = isFace ? faceData : rimData;
+        var v0 = appendVertex(target, i0, positions, normals, uvs);
+        var v1 = appendVertex(target, i1, positions, normals, uvs);
+        var v2 = appendVertex(target, i2, positions, normals, uvs);
+        target.indices.push(v0, v1, v2);
+    }
+
+    mesh.dispose();
+
+    var rimMesh = buildMesh(mesh.name + '_rim', rimData, scene);
+    var faceMesh = buildMesh(mesh.name + '_face', faceData, scene);
+
+    if (!faceMesh) {
+        return { rimMesh: rimMesh || mesh, faceMesh: null }
+    }
+    if (!rimMesh) {
+        return { rimMesh: faceMesh, faceMesh: null }
+    }
+    return { rimMesh, faceMesh }
+}
+
+function detectFaceAxisFromGeometry(positions, normals, indices) {
+    if (!positions || !indices) return null
+
+    var min = [Infinity, Infinity, Infinity];
+    var max = [-Infinity, -Infinity, -Infinity];
+    for (var i = 0; i < positions.length; i += 3) {
+        var x = positions[i];
+        var y = positions[i + 1];
+        var z = positions[i + 2];
+        if (x < min[0]) min[0] = x;
+        if (x > max[0]) max[0] = x;
+        if (y < min[1]) min[1] = y;
+        if (y > max[1]) max[1] = y;
+        if (z < min[2]) min[2] = z;
+        if (z > max[2]) max[2] = z;
+    }
+
+    var epsilons = [
+        Math.max((max[0] - min[0]) * 0.15, 0.001),
+        Math.max((max[1] - min[1]) * 0.15, 0.001),
+        Math.max((max[2] - min[2]) * 0.15, 0.001)
+    ];
+
+    var counts = [
+        { min: 0, max: 0, sumMin: 0, sumMax: 0 },
+        { min: 0, max: 0, sumMin: 0, sumMax: 0 },
+        { min: 0, max: 0, sumMin: 0, sumMax: 0 }
+    ];
+
+    for (var idx = 0; idx < indices.length; idx += 3) {
+        var i0 = indices[idx];
+        var i1 = indices[idx + 1];
+        var i2 = indices[idx + 2];
+
+        for (var axis = 0; axis < 3; axis++) {
+            var epsilon = epsilons[axis];
+            if (epsilon <= 0) continue
+            var minVal = min[axis];
+            var maxVal = max[axis];
+
+            var c0 = positions[i0 * 3 + axis];
+            var c1 = positions[i1 * 3 + axis];
+            var c2 = positions[i2 * 3 + axis];
+
+            var nearMin = Math.abs(c0 - minVal) < epsilon &&
+                Math.abs(c1 - minVal) < epsilon &&
+                Math.abs(c2 - minVal) < epsilon;
+            var nearMax = Math.abs(c0 - maxVal) < epsilon &&
+                Math.abs(c1 - maxVal) < epsilon &&
+                Math.abs(c2 - maxVal) < epsilon;
+
+            if (nearMin) {
+                counts[axis].min++;
+                if (normals) {
+                    counts[axis].sumMin += normals[i0 * 3 + axis] + normals[i1 * 3 + axis] + normals[i2 * 3 + axis];
+                }
+            } else if (nearMax) {
+                counts[axis].max++;
+                if (normals) {
+                    counts[axis].sumMax += normals[i0 * 3 + axis] + normals[i1 * 3 + axis] + normals[i2 * 3 + axis];
+                }
+            }
+        }
+    }
+
+    var bestAxis = -1;
+    var bestCount = 0;
+    for (var axisIdx = 0; axisIdx < 3; axisIdx++) {
+        var total = counts[axisIdx].min + counts[axisIdx].max;
+        if (total > bestCount) {
+            bestCount = total;
+            bestAxis = axisIdx;
+        }
+    }
+
+    if (bestAxis === -1 || bestCount === 0) {
+        return null
+    }
+
+    // For 3D text, extrusion is typically along Y axis (axis=1).
+    // If Y axis has any face triangles and the detected axis is different,
+    // prefer Y unless the detected axis has significantly more triangles.
+    var yTotal = counts[1].min + counts[1].max;
+    if (bestAxis !== 1 && yTotal > 0) {
+        // Only switch away from Y if another axis has 2x more triangles
+        if (bestCount < yTotal * 2) {
+            bestAxis = 1;
+            bestCount = yTotal;
+        }
+    }
+
+    var chosen = counts[bestAxis];
+    var frontSide;
+    // For PolygonMeshBuilder extrusions: geometry goes from Y=0 (base) to Y=-depth (extruded end)
+    // After rotation -PI/2 around X: Y=0 → Z=0 (front, facing camera), Y=-depth → Z=+depth (back)
+    // So Y=max (Y=0) is the FRONT face, Y=min (Y=-depth) is the BACK face
+    var maxHasOutwardNormals = chosen.sumMax > 0;
+    var minHasOutwardNormals = chosen.sumMin < 0;
+
+    // Select MAX as front (the base at Y=0 which faces camera after rotation)
+    if (maxHasOutwardNormals) {
+        frontSide = 'max';
+    } else if (minHasOutwardNormals) {
+        frontSide = 'min';
+    } else {
+        // Fallback to max (the base)
+        frontSide = 'max';
+    }
+
+    return {
+        axis: bestAxis,
+        strategy: 'positions',
+        min: min[bestAxis],
+        max: max[bestAxis],
+        epsilon: epsilons[bestAxis],
+        frontSide
+    }
+}
+
+function detectFaceAxis(normals) {
+    if (!normals || normals.length === 0) {
+        return null
+    }
+    var sumsAbs = [0, 0, 0];
+    var sumsSigned = [0, 0, 0];
+    for (var i = 0; i < normals.length; i += 3) {
+        var nx = normals[i];
+        var ny = normals[i + 1];
+        var nz = normals[i + 2];
+        sumsAbs[0] += Math.abs(nx);
+        sumsAbs[1] += Math.abs(ny);
+        sumsAbs[2] += Math.abs(nz);
+        sumsSigned[0] += nx;
+        sumsSigned[1] += ny;
+        sumsSigned[2] += nz;
+    }
+    var axis = 0;
+    var maxSum = sumsAbs[0];
+    for (var j = 1; j < 3; j++) {
+        if (sumsAbs[j] > maxSum) {
+            maxSum = sumsAbs[j];
+            axis = j;
+        }
+    }
+    if (maxSum === 0) {
+        return null
+    }
+    var frontSign = sumsSigned[axis] >= 0 ? 1 : -1;
+    return {
+        axis,
+        frontSign,
+        strategy: 'normals',
+        min: 0,
+        max: 0,
+        epsilon: 0,
+        frontSide: 'max'
+    }
+}
+
+function detectExtrudeAxisFromPositions(positions) {
+    if (!positions || positions.length === 0) {
+        return null
+    }
+    var min = [Infinity, Infinity, Infinity];
+    var max = [-Infinity, -Infinity, -Infinity];
+    for (var i = 0; i < positions.length; i += 3) {
+        var x = positions[i];
+        var y = positions[i + 1];
+        var z = positions[i + 2];
+        if (x < min[0]) min[0] = x;
+        if (x > max[0]) max[0] = x;
+        if (y < min[1]) min[1] = y;
+        if (y > max[1]) max[1] = y;
+        if (z < min[2]) min[2] = z;
+        if (z > max[2]) max[2] = z;
+    }
+    var ranges = [
+        max[0] - min[0],
+        max[1] - min[1],
+        max[2] - min[2]
+    ];
+    var axis = 0;
+    var minRange = ranges[0];
+    for (var j = 1; j < 3; j++) {
+        if (ranges[j] < minRange) {
+            minRange = ranges[j];
+            axis = j;
+        }
+    }
+    var epsilon = Math.max(minRange * 0.05, 0.0001);
+    return {
+        axis,
+        strategy: 'positions',
+        min: min[axis],
+        max: max[axis],
+        epsilon,
+        frontSide: 'max'
+    }
+}
+
+function triangleIsFrontFace(i0, i1, i2, positions, normals, axisInfo) {
+    if (!axisInfo) return false
+    var axis = axisInfo.axis || 1;
+
+    if (axisInfo.strategy === 'normals' && normals) {
+        var frontSign = axisInfo.frontSign || 1;
+        var threshold = 0.5;
+        var n0 = normals[i0 * 3 + axis] * frontSign;
+        var n1 = normals[i1 * 3 + axis] * frontSign;
+        var n2 = normals[i2 * 3 + axis] * frontSign;
+        return (n0 > threshold && n1 > threshold && n2 > threshold)
+    }
+
+    if (axisInfo.strategy === 'positions' && positions) {
+        var epsilon = axisInfo.epsilon;
+        var limitVal = axisInfo.frontSide === 'min' ? axisInfo.min : axisInfo.max;
+        var c0 = positions[i0 * 3 + axis];
+        var c1 = positions[i1 * 3 + axis];
+        var c2 = positions[i2 * 3 + axis];
+        return (
+            Math.abs(c0 - limitVal) < epsilon &&
+            Math.abs(c1 - limitVal) < epsilon &&
+            Math.abs(c2 - limitVal) < epsilon
+        )
+    }
+
+    return false
+}
+
+function createEmptyData() {
+    return {
+        positions: [],
+        normals: [],
+        uvs: [],
+        indices: [],
+        nextIndex: 0
+    }
+}
+
+function appendVertex(target, originalIndex, positions, normals, uvs) {
+    var posOffset = originalIndex * 3;
+    var uvOffset = originalIndex * 2;
+
+    target.positions.push(
+        positions[posOffset],
+        positions[posOffset + 1],
+        positions[posOffset + 2]
+    );
+    target.normals.push(
+        normals[posOffset],
+        normals[posOffset + 1],
+        normals[posOffset + 2]
+    );
+
+    if (uvs && uvs.length) {
+        target.uvs.push(uvs[uvOffset], uvs[uvOffset + 1]);
+    } else {
+        target.uvs.push(0, 0);
+    }
+
+    var newIndex = target.nextIndex;
+    target.nextIndex += 1;
+    return newIndex
+}
+
+function buildMesh(name, data, scene) {
+    if (!data.positions.length) return null
+    var newMesh = new mesh.Mesh(name, scene);
+    var vertexData = new mesh_vertexData.VertexData();
+    vertexData.positions = data.positions;
+    vertexData.normals = data.normals;
+    vertexData.indices = data.indices;
+    vertexData.uvs = data.uvs;
+    vertexData.applyToMesh(newMesh, true);
+    newMesh.refreshBoundingInfo();
+    return newMesh
+}
+
+/**
+ * MeshWriter Letter Mesh Construction
+ * Builds 3D letter meshes from font specifications
+ */
+
+
+/** @typedef {import('@babylonjs/core/scene').Scene} Scene */
+/** @typedef {import('@babylonjs/core/Materials/material').Material} Material */
+
+// Handle both CJS default export and ESM module export
+const earcut = earcutModule.default || earcutModule;
+
+// Constants
+const naturalLetterHeight = 1000;
+
+/**
+ * Get kerning value between two characters
+ * @param {Object} fontSpec - Font specification object
+ * @param {string} left - Left character
+ * @param {string} right - Right character
+ * @returns {number} - Kerning adjustment value (0 if none)
+ */
+function getKerning(fontSpec, left, right) {
+    if (!fontSpec.kern) return 0;
+    const key = `${left},${right}`;
+    return fontSpec.kern[key] || 0;
+}
+
+/**
+ * Decompress font letter on first use (lazy decompression)
+ * @param {Object} fontSpec - Font specification object
+ * @param {string} letter - Character to get spec for
+ * @returns {Object|undefined} - Letter specification
+ */
+function makeLetterSpec(fontSpec, letter) {
+    const letterSpec = fontSpec[letter];
+
+    if (isObject(letterSpec)) {
+        // Decompress shape commands if compressed
+        if (!isArray(letterSpec.shapeCmds) && isArray(letterSpec.sC)) {
+            letterSpec.shapeCmds = letterSpec.sC.map(cmds => decodeList(cmds));
+            letterSpec.sC = null;
+        }
+        // Decompress hole commands if compressed
+        if (!isArray(letterSpec.holeCmds) && isArray(letterSpec.hC)) {
+            letterSpec.holeCmds = letterSpec.hC.map(cmdslists =>
+                isArray(cmdslists) ? cmdslists.map(cmds => decodeList(cmds)) : cmdslists
+            );
+            letterSpec.hC = null;
+        }
+    }
+    return letterSpec;
+}
+
+/**
+ * Convert point to Vector2
+ */
+function point2Vector(point) {
+    return new math_vector.Vector2(round(point.x), round(point.y));
+}
+
+/**
+ * Merge array of meshes
+ */
+function merge(arrayOfMeshes) {
+    return arrayOfMeshes.length === 1
+        ? arrayOfMeshes[0]
+        : mesh.Mesh.MergeMeshes(arrayOfMeshes, true);
+}
+
+/**
+ * @typedef {Object} LetterPolygonsResult
+ * @property {number} xWidth - Total width of all letters
+ * @property {number} count - Number of valid letter meshes
+ */
+/**
+ * @typedef {(any[] & LetterPolygonsResult) & { faceMeshes: Mesh[] }} LetterPolygonsCollection
+ */
+
+/**
+ * Construct meshes for all letters in a string
+ * @param {string} letters - Text string
+ * @param {Object} fontSpec - Font specification
+ * @param {number} xOffset - X offset
+ * @param {number} yOffset - Y offset (unused, kept for API compatibility)
+ * @param {number} zOffset - Z offset
+ * @param {number} letterScale - Scale factor for letters
+ * @param {number} thickness - Letter thickness (depth)
+ * @param {Material} material - Material (unused in this function)
+ * @param {string} meshOrigin - "letterCenter" or "fontOrigin"
+ * @param {Scene} scene - Babylon scene
+ * @param {Object} [spacingOpts] - Optional spacing options
+ * @param {number} [spacingOpts.letterSpacing=0] - Extra spacing between letters (world units, added after kerning)
+ * @param {number} [spacingOpts.wordSpacing=0] - Extra spacing for spaces (world units, added to space width)
+ * @returns {any[] & LetterPolygonsResult} - [meshes, boxes, origins] with xWidth and count properties
+ */
+function constructLetterPolygons(
+    letters, fontSpec, xOffset, yOffset, zOffset,
+    letterScale, thickness, material, meshOrigin, scene, spacingOpts = {}
+) {
+    // Extract spacing options (already in world units)
+    const letterSpacing = isNumber(spacingOpts.letterSpacing) ? spacingOpts.letterSpacing : 0;
+    const wordSpacing = isNumber(spacingOpts.wordSpacing) ? spacingOpts.wordSpacing : 0;
+
+    let letterOffsetX = 0;
+    const lettersOrigins = new Array(letters.length);
+    const lettersBoxes = new Array(letters.length);
+    const lettersMeshes = new Array(letters.length);
+    const faceMeshes = new Array(letters.length);
+    let ix = 0;
+
+    for (let i = 0; i < letters.length; i++) {
+        const letter = letters[i];
+        const letterSpec = makeLetterSpec(fontSpec, letter);
+
+        if (isObject(letterSpec)) {
+            const lists = buildLetterMeshes(
+                letter, i, letterSpec, fontSpec.reverseShapes, fontSpec.reverseHoles,
+                meshOrigin, letterScale, xOffset, zOffset, letterOffsetX, thickness, scene
+            );
+
+            const shapesList = lists[0];
+            const holesList = lists[1];
+            const letterBox = lists[2];
+            const letterOrigins = lists[3];
+            let newOffsetX = lists[4];
+
+            // Apply kerning with next letter (if any)
+            if (i < letters.length - 1) {
+                const nextLetter = letters[i + 1];
+                const kernValue = getKerning(fontSpec, letter, nextLetter);
+                if (kernValue !== 0) {
+                    newOffsetX += kernValue * letterScale;
+                }
+                // Apply letter spacing after kerning (not after last letter)
+                if (letterSpacing !== 0) {
+                    newOffsetX += letterSpacing;
+                }
+            }
+
+            // Apply extra word spacing for space characters
+            if (letter === ' ' && wordSpacing !== 0) {
+                newOffsetX += wordSpacing;
+            }
+
+            letterOffsetX = newOffsetX;
+
+            const letterMeshes = punchHolesInShapes(shapesList, holesList, letter, i, scene);
+
+            if (letterMeshes.length) {
+                const merged = merge(letterMeshes);
+                const split = splitMeshByFaceNormals(merged, scene);
+
+                lettersMeshes[ix] = split.rimMesh;
+                faceMeshes[ix] = split.faceMesh;
+                lettersOrigins[ix] = letterOrigins;
+                lettersBoxes[ix] = letterBox;
+                ix++;
+            }
+        }
+    }
+
+    /** @type {LetterPolygonsCollection} */
+    const meshesAndBoxes = /** @type {any} */ ([lettersMeshes, lettersBoxes, lettersOrigins]);
+    meshesAndBoxes.faceMeshes = faceMeshes;
+    meshesAndBoxes.xWidth = round(letterOffsetX);
+    meshesAndBoxes.count = ix;
+    return meshesAndBoxes;
+}
+
+/**
+ * Build meshes for a single letter
+ * @returns {Array} - [shapesList, holesList, letterBox, letterOrigins, newOffsetX]
+ */
+function buildLetterMeshes(
+    letter, index, spec, reverseShapes, reverseHoles,
+    meshOrigin, letterScale, xOffset, zOffset, letterOffsetX, thickness, scene
+) {
+    // Offset calculations
+    const balanced = meshOrigin === "letterCenter";
+    const centerX = (spec.xMin + spec.xMax) / 2;
+    const centerZ = (spec.yMin + spec.yMax) / 2;
+    const xFactor = isNumber(spec.xFactor) ? spec.xFactor : 1;
+    const zFactor = isNumber(spec.yFactor) ? spec.yFactor : 1;
+    const xShift = isNumber(spec.xShift) ? spec.xShift : 0;
+    const zShift = isNumber(spec.yShift) ? spec.yShift : 0;
+    const reverseShape = isBoolean(spec.reverseShape) ? spec.reverseShape : reverseShapes;
+    const reverseHole = isBoolean(spec.reverseHole) ? spec.reverseHole : reverseHoles;
+    const offX = xOffset - (balanced ? centerX : 0);
+    const offZ = zOffset - (balanced ? centerZ : 0);
+    const shapeCmdsLists = isArray(spec.shapeCmds) ? spec.shapeCmds : [];
+    const holeCmdsListsArray = isArray(spec.holeCmds) ? spec.holeCmds : [];
+
+    // Tracking for relative coordinates
+    let thisX, lastX, thisZ, lastZ;
+
+    // Scaling functions
+    const adjX = makeAdjust(letterScale, xFactor, offX, 0, false, true);
+    const adjZ = makeAdjust(letterScale, zFactor, offZ, 0, false, false);
+    const adjXfix = makeAdjust(letterScale, xFactor, offX, xShift, false, true);
+    const adjZfix = makeAdjust(letterScale, zFactor, offZ, zShift, false, false);
+    const adjXrel = makeAdjust(letterScale, xFactor, offX, xShift, true, true);
+    const adjZrel = makeAdjust(letterScale, zFactor, offZ, zShift, true, false);
+
+    const letterBox = [adjX(spec.xMin), adjX(spec.xMax), adjZ(spec.yMin), adjZ(spec.yMax)];
+    const letterOrigins = [round(letterOffsetX), -1 * adjX(0), -1 * adjZ(0)];
+
+    // Update letterOffsetX for next letter
+    const newOffsetX = letterOffsetX + spec.wdth * letterScale;
+
+    const shapesList = shapeCmdsLists.map(makeCmdsToMesh(reverseShape));
+    const holesList = holeCmdsListsArray.map(meshesFromCmdsListArray);
+
+    return [shapesList, holesList, letterBox, letterOrigins, newOffsetX];
+
+    function meshesFromCmdsListArray(cmdsListArray) {
+        return cmdsListArray.map(makeCmdsToMesh(reverseHole));
+    }
+
+    function makeCmdsToMesh(reverse) {
+        return function cmdsToMesh(cmdsList) {
+            let cmd = getCmd(cmdsList, 0);
+            /** @type {any} */
+            const path = new math_path.Path2(adjXfix(cmd[0]), adjZfix(cmd[1]));
+
+            // Process path commands
+            for (let j = 1; j < cmdsList.length; j++) {
+                cmd = getCmd(cmdsList, j);
+
+                // Line (2 coords = absolute, 3 = relative)
+                if (cmd.length === 2) {
+                    path.addLineTo(adjXfix(cmd[0]), adjZfix(cmd[1]));
+                }
+                if (cmd.length === 3) {
+                    path.addLineTo(adjXrel(cmd[1]), adjZrel(cmd[2]));
+                }
+
+                // Quadratic curve (4 = absolute, 5 = relative)
+                if (cmd.length === 4) {
+                    path.addQuadraticCurveTo(
+                        adjXfix(cmd[0]), adjZfix(cmd[1]),
+                        adjXfix(cmd[2]), adjZfix(cmd[3])
+                    );
+                }
+                if (cmd.length === 5) {
+                    path.addQuadraticCurveTo(
+                        adjXrel(cmd[1]), adjZrel(cmd[2]),
+                        adjXrel(cmd[3]), adjZrel(cmd[4])
+                    );
+                }
+
+                // Cubic curve (6 = absolute, 7 = relative)
+                if (cmd.length === 6) {
+                    path.addCubicCurveTo(
+                        adjXfix(cmd[0]), adjZfix(cmd[1]),
+                        adjXfix(cmd[2]), adjZfix(cmd[3]),
+                        adjXfix(cmd[4]), adjZfix(cmd[5])
+                    );
+                }
+                if (cmd.length === 7) {
+                    path.addCubicCurveTo(
+                        adjXrel(cmd[1]), adjZrel(cmd[2]),
+                        adjXrel(cmd[3]), adjZrel(cmd[4]),
+                        adjXrel(cmd[5]), adjZrel(cmd[6])
+                    );
+                }
+            }
+
+            // Convert path to array and process
+            let array = path.getPoints().map(point2Vector);
+
+            // Remove redundant start/end points
+            const first = 0;
+            const last = array.length - 1;
+            if (array[first].x === array[last].x && array[first].y === array[last].y) {
+                array = array.slice(1);
+            }
+            if (reverse) {
+                array.reverse();
+            }
+
+            const meshBuilder = new polygonMesh.PolygonMeshBuilder(
+                "MeshWriter-" + letter + index + "-" + weeid(),
+                array,
+                scene,
+                earcut
+            );
+            return meshBuilder.build(true, thickness);
+        };
+    }
+
+    function getCmd(list, ix) {
+        lastX = thisX;
+        lastZ = thisZ;
+        const cmd = list[ix];
+        const len = cmd.length;
+        thisX = isRelativeLength(len)
+            ? round((cmd[len - 2] * xFactor) + thisX)
+            : round(cmd[len - 2] * xFactor);
+        thisZ = isRelativeLength(len)
+            ? round((cmd[len - 1] * zFactor) + thisZ)
+            : round(cmd[len - 1] * zFactor);
+        return cmd;
+    }
+
+    function makeAdjust(letterScale, factor, off, shift, relative, xAxis) {
+        if (relative) {
+            if (xAxis) {
+                return val => round(letterScale * ((val * factor) + shift + lastX + off));
+            } else {
+                return val => round(letterScale * ((val * factor) + shift + lastZ + off));
+            }
+        } else {
+            return val => round(letterScale * ((val * factor) + shift + off));
+        }
+    }
+}
+
+/**
+ * Punch holes in letter shapes using CSG operations
+ * @param {Array} shapesList - Array of shape meshes
+ * @param {Array} holesList - Array of arrays of hole meshes
+ * @param {string} letter - Letter character (for naming)
+ * @param {number} letterIndex - Index of letter (for naming)
+ * @param {Scene} scene - Babylon scene
+ * @returns {Array} - Array of final letter meshes
+ */
+function punchHolesInShapes(shapesList, holesList, letter, letterIndex, scene) {
+    const csgVersion = getCSGVersion();
+
+    // Validate CSG is available and initialized
+    if (csgVersion === 'CSG2' && !isCSGReady()) {
+        throw new Error(
+            "MeshWriter: CSG2 not initialized. " +
+            "Use 'await MeshWriter.createAsync(scene, prefs)', call " +
+            "'await BABYLON.InitializeCSG2Async()', or configure " +
+            "MeshWriter.setCSGInitializer before creating MeshWriter."
+        );
+    }
+    if (csgVersion === null) {
+        throw new Error(
+            "MeshWriter: No CSG implementation found. " +
+            "Ensure BABYLON.CSG or BABYLON.CSG2 is available."
+        );
+    }
+
+    const letterMeshes = [];
+    const csgLib = getCSGLib();
+
+    // Handle special case: single shape with multiple hole arrays
+    // (e.g., "B" has 1 shape but 2 holes - top and bottom)
+    // In this case, all holes should be punched into the single shape
+    if (shapesList.length === 1 && holesList.length > 1) {
+        const shape = shapesList[0];
+        // Flatten all hole arrays into a single array
+        const allHoles = holesList.flat();
+
+        if (allHoles.length > 0) {
+            letterMeshes.push(punchHolesInShape(shape, allHoles, letter, letterIndex, csgLib, csgVersion, scene));
+        } else {
+            letterMeshes.push(shape);
+        }
+        return letterMeshes;
+    }
+
+    // Standard case: 1:1 correspondence between shapes and hole arrays
+    for (let j = 0; j < shapesList.length; j++) {
+        const shape = shapesList[j];
+        const holes = holesList[j];
+
+        if (isArray(holes) && holes.length) {
+            letterMeshes.push(punchHolesInShape(shape, holes, letter, letterIndex, csgLib, csgVersion, scene));
+        } else {
+            // PolygonMeshBuilder creates meshes with correct normals by default
+            // No flipFaces needed for shapes without holes
+            letterMeshes.push(shape);
+        }
+    }
+
+    return letterMeshes;
+}
+
+/**
+ * Punch holes in a single shape
+ */
+function punchHolesInShape(shape, holes, letter, letterIndex, csgLib, csgVersion, scene) {
+    const meshName = "Net-" + letter + letterIndex + "-" + weeid();
+
+    let csgShape = csgLib.FromMesh(shape);
+    for (let k = 0; k < holes.length; k++) {
+        csgShape = csgShape.subtract(csgLib.FromMesh(holes[k]));
+    }
+
+    const resultMesh = csgVersion === 'CSG2'
+        ? csgShape.toMesh(meshName, scene, { centerMesh: false, rebuildNormals: true })
+        : csgShape.toMesh(meshName, null, scene);
+
+    // CSG2 with rebuildNormals: true produces correct normals
+    // No flipFaces needed
+
+    // Cleanup
+    holes.forEach(h => h.dispose());
+    shape.dispose();
+
+    return resultMesh;
+}
+
+/**
+ * MeshWriter Curve Extensions
+ * Optimized Path2 curve methods for better performance
+ */
+
+
+/**
+ * Extended Path2 interface with MeshWriter curve methods
+ * @typedef {Object} Path2Extensions
+ * @property {(redX: number, redY: number, blueX: number, blueY: number) => Path2} addQuadraticCurveTo
+ * @property {(redX: number, redY: number, greenX: number, greenY: number, blueX: number, blueY: number) => Path2} addCubicCurveTo
+ */
+
+// Optimized segment count for curves
+// Native Babylon 6+ uses 36 segments which causes slowdown
+// MeshWriter uses 6 for better performance
+const curveSampleSize = 6;
+
+/**
+ * Install optimized curve methods on Path2 prototype
+ * Must be called after Babylon.js is loaded
+ */
+function installCurveExtensions() {
+    if (!math_path.Path2 || !math_path.Path2.prototype) {
+        return;
+    }
+
+    /** @type {any} */
+    const proto = math_path.Path2.prototype;
+
+    // Quadratic Bezier with optimized segment count
+    proto.addQuadraticCurveTo = function(redX, redY, blueX, blueY) {
+        const points = this.getPoints();
+        const lastPoint = points[points.length - 1];
+        const origin = new math_vector.Vector3(lastPoint.x, lastPoint.y, 0);
+        const control = new math_vector.Vector3(redX, redY, 0);
+        const destination = new math_vector.Vector3(blueX, blueY, 0);
+
+        const curve = math_path.Curve3.CreateQuadraticBezier(origin, control, destination, curveSampleSize);
+        const curvePoints = curve.getPoints();
+
+        for (let i = 1; i < curvePoints.length; i++) {
+            this.addLineTo(curvePoints[i].x, curvePoints[i].y);
+        }
+        return this; // Return this for method chaining
+    };
+
+    // Cubic Bezier with optimized segment count
+    proto.addCubicCurveTo = function(redX, redY, greenX, greenY, blueX, blueY) {
+        const points = this.getPoints();
+        const lastPoint = points[points.length - 1];
+        const origin = new math_vector.Vector3(lastPoint.x, lastPoint.y, 0);
+        const control1 = new math_vector.Vector3(redX, redY, 0);
+        const control2 = new math_vector.Vector3(greenX, greenY, 0);
+        const destination = new math_vector.Vector3(blueX, blueY, 0);
+
+        const nbPoints = Math.floor(0.3 + curveSampleSize * 1.5);
+        const curve = math_path.Curve3.CreateCubicBezier(origin, control1, control2, destination, nbPoints);
+        const curvePoints = curve.getPoints();
+
+        for (let i = 1; i < curvePoints.length; i++) {
+            this.addLineTo(curvePoints[i].x, curvePoints[i].y);
+        }
+        return this; // Return this for method chaining
+    };
+}
+
+/**
+ * MeshWriter Core Class
+ * Main MeshWriter implementation for 3D text rendering in Babylon.js
+ */
+
+
+/** @typedef {import('@babylonjs/core/scene').Scene} Scene */
+
+/**
+ * @typedef {Object} MeshWriterPreferences
+ * @property {string} [defaultFont] - Default font family
+ * @property {number} [scale=1] - Scale factor
+ * @property {string} [meshOrigin="letterCenter"] - "letterCenter" or "fontOrigin"
+ * @property {boolean} [debug=false] - Enable debug logging
+ * @property {Object} [babylon] - Babylon.js namespace object with CSG classes (for ES module builds)
+ */
+
+// Constants
+const defaultColor = "#808080";
+const defaultOpac = 1;
+
+/**
+ * Create a MeshWriter factory configured for a scene
+ * @param {Scene} scene - Babylon.js scene
+ * @param {MeshWriterPreferences} [preferences={}] - Configuration options
+ * @returns {Function} - MeshWriter constructor
+ */
+function createMeshWriter(scene, preferences = {}) {
+    // Install curve extensions for Path2
+    installCurveExtensions();
+
+    const defaultFont = isFontRegistered(preferences.defaultFont)
+        ? preferences.defaultFont
+        : (isFontRegistered("Helvetica") ? "Helvetica" : "HelveticaNeue-Medium");
+    const meshOrigin = preferences.meshOrigin === "fontOrigin"
+        ? "fontOrigin"
+        : "letterCenter";
+    const scale = isNumber(preferences.scale) ? preferences.scale : 1;
+    isBoolean(preferences.debug) ? preferences.debug : false;
+
+    /**
+     * MeshWriter constructor - creates 3D text
+     * @param {string} lttrs - Text to render
+     * @param {Object} opt - Options
+     */
+    function MeshWriter(lttrs, opt) {
+        const options = isObject(opt) ? opt : {};
+        const position = setOption(options, "position", isObject, {});
+        const colors = setOption(options, "colors", isObject, {});
+        const fontFamily = setOption(options, "font-family", isSupportedFont, defaultFont);
+        const anchor = setOption(options, "anchor", isSupportedAnchor, "left");
+        const rawheight = setOption(options, "letter-height", isPositiveNumber, 100);
+        const rawThickness = setOption(options, "letter-thickness", isPositiveNumber, 1);
+        const basicColor = setOption(options, "color", isString, defaultColor);
+        const opac = setOption(options, "alpha", isAmplitude, defaultOpac);
+        const y = setOption(position, "y", isNumber, 0);
+        const x = setOption(position, "x", isNumber, 0);
+        const z = setOption(position, "z", isNumber, 0);
+        const diffuse = setOption(colors, "diffuse", isString, "#404040");    // Dark gray - lets emissive show
+        const specular = setOption(colors, "specular", isString, "#000000");
+        const ambient = setOption(colors, "ambient", isString, "#202020");    // Very dark - minimal ambient response
+        const emissive = setOption(colors, "emissive", isString, basicColor);
+        const emissiveOnly = setOption(options, "emissive-only", isBoolean, false);
+        const fogEnabled = setOption(options, "fog-enabled", isBoolean, true);
+        const letterSpacingRaw = setOption(options, "letter-spacing", isNumber, 0);
+        const wordSpacingRaw = setOption(options, "word-spacing", isNumber, 0);
+        const fontSpec = getFont(fontFamily);
+        const letterScale = round(scale * rawheight / naturalLetterHeight);
+        const thickness = round(scale * rawThickness);
+        const letters = isString(lttrs) ? lttrs : "";
+        // Scale spacing values to match letter scale
+        const letterSpacing = letterSpacingRaw * scale;
+        const wordSpacing = wordSpacingRaw * scale;
+
+        // Create material
+        const material = makeMaterial(scene, letters, emissive, ambient, specular, diffuse, opac, emissiveOnly, fogEnabled);
+
+        // Create letter meshes
+        const meshesAndBoxes = constructLetterPolygons(
+            letters, fontSpec, 0, 0, 0, letterScale, thickness, material, meshOrigin, scene,
+            { letterSpacing, wordSpacing }
+        );
+        meshesAndBoxes[0];
+        const lettersBoxes = meshesAndBoxes[1];
+        const lettersOrigins = meshesAndBoxes[2];
+        const xWidth = meshesAndBoxes.xWidth;
+
+        // Convert to SPS
+        const combo = makeSPS(scene, meshesAndBoxes, material);
+        const sps = combo[0];
+        const mesh = combo[1];
+        const faceCombo = combo.face || [];
+        const faceSps = faceCombo[0];
+        const faceMesh = faceCombo[1];
+        let faceMaterial;
+
+        if (faceMesh) {
+            faceMaterial = makeFaceMaterial(scene, letters, emissive, opac, fogEnabled);
+            faceMesh.material = faceMaterial;
+            if (mesh) {
+                faceMesh.parent = mesh;
+                faceMesh.layerMask = mesh.layerMask;
+                faceMesh.renderingGroupId = mesh.renderingGroupId;
+            }
+            // Tiny offset to prevent z-fighting without leaving a visible gap
+            // rotation.x=-PI/2 maps: +Y → -Z (toward camera), -Y → +Z (away)
+            // We want face IN FRONT of rim, so use POSITIVE Y
+            faceMesh.position.y = 0.001;
+            faceMesh.isPickable = false;
+        }
+
+        // Position mesh based on anchor
+        const offsetX = anchor === "right"
+            ? (0 - xWidth)
+            : (anchor === "center" ? (0 - xWidth / 2) : 0);
+
+        if (mesh) {
+            mesh.position.x = scale * x + offsetX;
+            mesh.position.y = scale * y;
+            mesh.position.z = scale * z;
+        }
+
+        // Instance methods
+        let color = basicColor;
+        this.getSPS = () => sps;
+        this.getMesh = () => mesh;
+        this.getMaterial = () => material;
+        this.getFaceMesh = () => faceMesh;
+        this.getFaceMaterial = () => faceMaterial;
+        this.getFaceSPS = () => faceSps;
+        this.getOffsetX = () => offsetX;
+        this.getLettersBoxes = () => lettersBoxes;
+        this.getLettersOrigins = () => lettersOrigins;
+        this.color = c => isString(c) ? color = c : color;
+        this.alpha = o => isAmplitude(o) ? opac : opac;
+        // Track disposed state to prevent double-disposal
+        let _disposed = false;
+
+        this.clearall = function() {
+            // Mark as disposed - getters will return null after this
+            _disposed = true;
+        };
+
+        this.isDisposed = function() {
+            return _disposed;
+        };
+    }
+
+    // Prototype methods
+    MeshWriter.prototype.setColor = function(color) {
+        const material = this.getMaterial();
+        if (material && isString(color)) {
+            const next = rgb2Color3(this.color(color));
+            material.emissiveColor = next;
+            const faceMaterial = this.getFaceMaterial && this.getFaceMaterial();
+            if (faceMaterial) {
+                faceMaterial.emissiveColor = next;
+            }
+        }
+    };
+
+    MeshWriter.prototype.setAlpha = function(alpha) {
+        const material = this.getMaterial();
+        if (material && isAmplitude(alpha)) {
+            const next = this.alpha(alpha);
+            material.alpha = next;
+            const faceMaterial = this.getFaceMaterial && this.getFaceMaterial();
+            if (faceMaterial) {
+                faceMaterial.alpha = next;
+            }
+        }
+    };
+
+    MeshWriter.prototype.overrideAlpha = function(alpha) {
+        const material = this.getMaterial();
+        if (material && isAmplitude(alpha)) {
+            material.alpha = alpha;
+            const faceMaterial = this.getFaceMaterial && this.getFaceMaterial();
+            if (faceMaterial) {
+                faceMaterial.alpha = alpha;
+            }
+        }
+    };
+
+    MeshWriter.prototype.resetAlpha = function() {
+        const material = this.getMaterial();
+        const alpha = this.alpha();
+        if (material) {
+            material.alpha = alpha;
+        }
+        const faceMaterial = this.getFaceMaterial && this.getFaceMaterial();
+        if (faceMaterial) {
+            faceMaterial.alpha = alpha;
+        }
+    };
+
+    MeshWriter.prototype.getLetterCenter = function(ix) {
+        return new math_vector.Vector2(0, 0);
+    };
+
+    MeshWriter.prototype.dispose = function() {
+        // Prevent double-disposal
+        if (this.isDisposed && this.isDisposed()) {
+            return;
+        }
+
+        // Dispose TextFogPlugin before materials to break circular references
+        const material = this.getMaterial();
+        if (material) {
+            if (material._textFogPlugin && typeof material._textFogPlugin.dispose === 'function') {
+                material._textFogPlugin.dispose();
+            }
+            material.dispose();
+        }
+
+        const faceMaterial = this.getFaceMaterial && this.getFaceMaterial();
+        if (faceMaterial) {
+            if (faceMaterial._textFogPlugin && typeof faceMaterial._textFogPlugin.dispose === 'function') {
+                faceMaterial._textFogPlugin.dispose();
+            }
+            faceMaterial.dispose();
+        }
+
+        // Dispose SolidParticleSystem (which also disposes its mesh)
+        const sps = this.getSPS();
+        if (sps) {
+            sps.dispose();
+        }
+
+        // Dispose face mesh (merged mesh, not SPS-based)
+        const faceMesh = this.getFaceMesh && this.getFaceMesh();
+        if (faceMesh && typeof faceMesh.dispose === 'function') {
+            faceMesh.dispose();
+        }
+
+        // Mark as disposed
+        this.clearall();
+    };
+
+    return MeshWriter;
+
+    // Helper functions
+    function isSupportedFont(ff) {
+        return isFontRegistered(ff);
+    }
+
+    function isSupportedAnchor(a) {
+        return a === "left" || a === "right" || a === "center";
+    }
+}
+
+/**
+ * Async factory for Babylon 8+ with CSG2
+ * Handles CSG2 initialization automatically
+ * @param {Scene} scene - Babylon.js scene
+ * @param {MeshWriterPreferences} [preferences={}] - Configuration options
+ * @returns {Promise<Function>} - MeshWriter constructor
+ */
+async function createMeshWriterAsync(scene, preferences = {}) {
+    // Initialize CSG module with Babylon methods
+    if (preferences.babylon) {
+        initCSGModule(preferences.babylon);
+    } else {
+        // Check for BABYLON global (UMD bundle usage)
+        /** @type {any} */
+        const globalBabylon = typeof globalThis !== 'undefined' ? globalThis.BABYLON : undefined;
+        if (globalBabylon) {
+            initCSGModule(globalBabylon);
+        }
+    }
+
+    // Initialize CSG2 if needed
+    if (getCSGVersion() === 'CSG2' && !isCSGReady()) {
+        await initializeCSG2();
+    }
+
+    return createMeshWriter(scene, preferences);
+}
+
+/**
+ * MeshWriter Baked Font Loader
+ * Loads pre-baked FontSpec JSON files at runtime.
+ * Zero dependencies - just fetch and use.
+ */
+
+/**
+ * Load a pre-baked font from a JSON file
+ * @param {string} url - URL to the baked FontSpec JSON file
+ * @returns {Promise<object>} - FontSpec object ready for use with MeshWriter
+ *
+ * @example
+ * const fontSpec = await loadBakedFont('/fonts/baked/atkinson-hyperlegible-next-400.json');
+ * registerFont('Atkinson400', fontSpec);
+ */
+async function loadBakedFont(url) {
+    const response = await fetch(url);
+
+    if (!response.ok) {
+        throw new Error(`MeshWriter: Failed to load baked font from ${url} (HTTP ${response.status})`);
+    }
+
+    const fontSpec = await response.json();
+
+    // Validate it looks like a FontSpec
+    if (typeof fontSpec !== 'object' || fontSpec === null) {
+        throw new Error(`MeshWriter: Invalid baked font data from ${url}`);
+    }
+
+    return fontSpec;
+}
+
+/**
+ * Load multiple pre-baked weights from a manifest
+ * @param {string} manifestUrl - URL to the manifest.json file
+ * @param {number[]} [weights] - Specific weights to load (loads all if omitted)
+ * @returns {Promise<Map<number, object>>} - Map of weight -> FontSpec
+ *
+ * @example
+ * const fonts = await loadBakedFontsFromManifest('/fonts/baked/manifest.json', [400, 450]);
+ * const fontSpec = fonts.get(400);
+ */
+async function loadBakedFontsFromManifest(manifestUrl, weights) {
+    const response = await fetch(manifestUrl);
+
+    if (!response.ok) {
+        throw new Error(`MeshWriter: Failed to load manifest from ${manifestUrl} (HTTP ${response.status})`);
+    }
+
+    const manifest = await response.json();
+    const baseUrl = manifestUrl.substring(0, manifestUrl.lastIndexOf('/') + 1);
+
+    // Determine which weights to load
+    const weightsToLoad = weights
+        ? weights.filter(w => manifest.weights.includes(w))
+        : manifest.weights;
+
+    if (weights && weightsToLoad.length !== weights.length) {
+        const missing = weights.filter(w => !manifest.weights.includes(w));
+        console.warn(`MeshWriter: Requested weights not available: ${missing.join(', ')}`);
+        console.warn(`MeshWriter: Available weights: ${manifest.weights.join(', ')}`);
+    }
+
+    // Load all requested weights in parallel
+    const results = await Promise.all(
+        weightsToLoad.map(async (weight) => {
+            const idx = manifest.weights.indexOf(weight);
+            const file = manifest.files[idx];
+            const fontSpec = await loadBakedFont(baseUrl + file);
+            return { weight, fontSpec };
+        })
+    );
+
+    // Build map
+    const fontMap = new Map();
+    for (const { weight, fontSpec } of results) {
+        fontMap.set(weight, fontSpec);
+    }
+
+    return fontMap;
+}
+
+/**
+ * Find the nearest available weight from a set of baked weights
+ * @param {number} targetWeight - Desired weight
+ * @param {number[]} availableWeights - Array of available weights
+ * @returns {number} - Nearest available weight
+ *
+ * @example
+ * const nearest = findNearestWeight(425, [400, 450, 500]);
+ * // Returns 450 (closest to 425)
+ */
+function findNearestWeight(targetWeight, availableWeights) {
+    if (!availableWeights || availableWeights.length === 0) {
+        throw new Error('MeshWriter: No available weights provided');
+    }
+
+    let nearest = availableWeights[0];
+    let minDiff = Math.abs(targetWeight - nearest);
+
+    for (const weight of availableWeights) {
+        const diff = Math.abs(targetWeight - weight);
+        if (diff < minDiff) {
+            minDiff = diff;
+            nearest = weight;
+        }
+    }
+
+    return nearest;
+}
+
+/**
+ * Get manifest info without loading fonts
+ * @param {string} manifestUrl - URL to the manifest.json file
+ * @returns {Promise<object>} - Manifest object with fontName, weights, etc.
+ */
+async function getBakedFontManifest(manifestUrl) {
+    const response = await fetch(manifestUrl);
+
+    if (!response.ok) {
+        throw new Error(`MeshWriter: Failed to load manifest from ${manifestUrl} (HTTP ${response.status})`);
+    }
+
+    return response.json();
+}
+
+/**
+ * Color Contrast Utilities for WCAG Compliance
+ * Provides color manipulation for dyslexia accessibility
+ */
+
+// ============================================
+// Color Conversion Utilities
+// ============================================
+
+/**
+ * Convert hex color string to RGB object (0-1 range)
+ * @param {string} hex - Hex color string (e.g., "#FF0000" or "FF0000")
+ * @returns {{r: number, g: number, b: number}}
+ */
+function hexToRgb(hex) {
+    hex = hex.replace("#", "");
+    return {
+        r: parseInt(hex.substring(0, 2), 16) / 255,
+        g: parseInt(hex.substring(2, 4), 16) / 255,
+        b: parseInt(hex.substring(4, 6), 16) / 255
+    };
+}
+
+/**
+ * Convert RGB object (0-1 range) to hex color string
+ * @param {{r: number, g: number, b: number}} rgb
+ * @returns {string}
+ */
+function rgbToHex(rgb) {
+    var r = Math.round(Math.max(0, Math.min(1, rgb.r)) * 255);
+    var g = Math.round(Math.max(0, Math.min(1, rgb.g)) * 255);
+    var b = Math.round(Math.max(0, Math.min(1, rgb.b)) * 255);
+    return "#" + ((1 << 24) + (r << 16) + (g << 8) + b).toString(16).slice(1).toUpperCase();
+}
+
+/**
+ * Convert RGB to HSL
+ * @param {number} r - Red (0-1)
+ * @param {number} g - Green (0-1)
+ * @param {number} b - Blue (0-1)
+ * @returns {{h: number, s: number, l: number}} - h in degrees (0-360), s and l in 0-1
+ */
+function rgbToHsl(r, g, b) {
+    var max = Math.max(r, g, b);
+    var min = Math.min(r, g, b);
+    var l = (max + min) / 2;
+    var h, s;
+
+    if (max === min) {
+        h = s = 0; // achromatic
+    } else {
+        var d = max - min;
+        s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+
+        switch (max) {
+            case r:
+                h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
+                break;
+            case g:
+                h = ((b - r) / d + 2) / 6;
+                break;
+            case b:
+                h = ((r - g) / d + 4) / 6;
+                break;
+        }
+        h *= 360;
+    }
+
+    return { h: h, s: s, l: l };
+}
+
+/**
+ * Convert HSL to RGB
+ * @param {number} h - Hue in degrees (0-360)
+ * @param {number} s - Saturation (0-1)
+ * @param {number} l - Lightness (0-1)
+ * @returns {{r: number, g: number, b: number}}
+ */
+function hslToRgb(h, s, l) {
+    var r, g, b;
+
+    if (s === 0) {
+        r = g = b = l; // achromatic
+    } else {
+        function hue2rgb(p, q, t) {
+            if (t < 0) t += 1;
+            if (t > 1) t -= 1;
+            if (t < 1 / 6) return p + (q - p) * 6 * t;
+            if (t < 1 / 2) return q;
+            if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+            return p;
+        }
+
+        var q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+        var p = 2 * l - q;
+        var hNorm = h / 360;
+
+        r = hue2rgb(p, q, hNorm + 1 / 3);
+        g = hue2rgb(p, q, hNorm);
+        b = hue2rgb(p, q, hNorm - 1 / 3);
+    }
+
+    return { r: r, g: g, b: b };
+}
+
+// ============================================
+// WCAG Luminance Calculations
+// ============================================
+
+/**
+ * Linearize an sRGB channel value
+ * @param {number} c - Channel value (0-1)
+ * @returns {number} - Linearized value
+ */
+function linearize(c) {
+    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+
+/**
+ * Calculate relative luminance per WCAG 2.1
+ * @param {number} r - Red (0-1)
+ * @param {number} g - Green (0-1)
+ * @param {number} b - Blue (0-1)
+ * @returns {number} - Relative luminance (0-1)
+ */
+function relativeLuminance(r, g, b) {
+    var rLin = linearize(r);
+    var gLin = linearize(g);
+    var bLin = linearize(b);
+    return 0.2126 * rLin + 0.7152 * gLin + 0.0722 * bLin;
+}
+
+/**
+ * Calculate WCAG contrast ratio between two luminance values
+ * @param {number} L1 - Luminance of first color (0-1)
+ * @param {number} L2 - Luminance of second color (0-1)
+ * @returns {number} - Contrast ratio (1-21)
+ */
+function contrastRatio(L1, L2) {
+    var lighter = Math.max(L1, L2);
+    var darker = Math.min(L1, L2);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+
+// ============================================
+// Luminance Adjustment
+// ============================================
+
+/**
+ * Adjust color to target luminance while preserving hue
+ * Uses binary search in HSL space
+ * Desaturates significantly at low lightness for better visual contrast
+ * @param {{r: number, g: number, b: number}} rgb
+ * @param {number} targetLum - Target relative luminance (0-1)
+ * @returns {{r: number, g: number, b: number}}
+ */
+function adjustToLuminance(rgb, targetLum) {
+    var hsl = rgbToHsl(rgb.r, rgb.g, rgb.b);
+
+    // Binary search to find lightness that achieves target luminance
+    var minL = 0;
+    var maxL = 1;
+    var iterations = 20;
+    var finalL;
+
+    for (var i = 0; i < iterations; i++) {
+        var midL = (minL + maxL) / 2;
+        var testRgb = hslToRgb(hsl.h, hsl.s, midL);
+        var testLum = relativeLuminance(testRgb.r, testRgb.g, testRgb.b);
+
+        if (testLum < targetLum) {
+            minL = midL;
+        } else {
+            maxL = midL;
+        }
+    }
+
+    finalL = (minL + maxL) / 2;
+
+    // Desaturate significantly at low lightness for better visual contrast
+    // Dark saturated colors (e.g., dark yellow) don't look distinct enough
+    // Scale saturation based on lightness: below 0.3 lightness, reduce saturation
+    var finalS = hsl.s;
+    if (finalL < 0.3) {
+        // Linear ramp: at L=0.3, keep 100% saturation; at L=0, keep 20% saturation
+        var saturationScale = 0.2 + (finalL / 0.3) * 0.8;
+        finalS = hsl.s * saturationScale;
+    }
+
+    return hslToRgb(hsl.h, finalS, finalL);
+}
+
+// ============================================
+// Auto-Derive Edge Colors
+// ============================================
+
+/**
+ * Auto-derive edge colors (diffuse/ambient) from emissive color
+ * Creates high-contrast edges for text legibility
+ *
+ * INVERTED APPROACH: Since emissive adds to all surfaces equally,
+ * we flip the strategy - put bright color in diffuse (shows on lit surfaces)
+ * and dark color in emissive (base for unlit surfaces).
+ * Returns modified emissive along with diffuse/ambient.
+ *
+ * @param {string} emissiveHex - Hex color string for desired face color
+ * @param {number} [targetContrast=4.5] - Target WCAG contrast ratio
+ * @returns {{diffuse: string, ambient: string, emissive: string}}
+ */
+function deriveEdgeColors(emissiveHex, targetContrast) {
+    targetContrast = targetContrast || 4.5;
+
+    var rgb = hexToRgb(emissiveHex);
+    var faceLum = relativeLuminance(rgb.r, rgb.g, rgb.b);
+
+    // Calculate target luminance for dark areas to achieve contrast
+    var darkLum;
+    if (faceLum > 0.5) {
+        // Bright face needs dark edges
+        darkLum = (faceLum + 0.05) / targetContrast - 0.05;
+        darkLum = Math.max(darkLum, 0.0);
+    } else {
+        // Dark face needs light edges (invert the logic)
+        darkLum = targetContrast * (faceLum + 0.05) - 0.05;
+        darkLum = Math.min(darkLum, 1.0);
+    }
+
+    // Handle edge cases
+    if (faceLum > 0.95) {
+        darkLum = Math.min(0.1, darkLum);
+    } else if (faceLum < 0.05) {
+        darkLum = Math.max(0.5, darkLum);
+    }
+
+    // Generate dark color (desaturated at low lightness)
+    var darkRgb = adjustToLuminance(rgb, darkLum);
+
+    // INVERTED APPROACH:
+    // - diffuse = bright (the user's desired face color) - shows on lit surfaces
+    // - emissive = dark - base color for all surfaces (unlit areas show this)
+    // - ambient = very dark - shadowed areas
+    var ambientLum = darkLum * 0.5;
+    var ambientRgb = adjustToLuminance(rgb, Math.max(0, ambientLum));
+
+    return {
+        diffuse: emissiveHex,           // Bright color for lit surfaces
+        ambient: rgbToHex(ambientRgb),  // Very dark for shadows
+        emissive: rgbToHex(darkRgb)     // Dark base for unlit areas
+    };
+}
+
+// ============================================
+// High-Contrast Adjustment Algorithm
+// ============================================
+
+/**
+ * Adjust color by a factor (lightness change with optional hue shift)
+ * @param {{r: number, g: number, b: number}} rgb
+ * @param {number} factor - Adjustment factor (-1 to 1, negative = darken)
+ * @param {boolean} allowHueShift
+ * @returns {{r: number, g: number, b: number}}
+ */
+function adjustColorByFactor(rgb, factor, allowHueShift) {
+    var hsl = rgbToHsl(rgb.r, rgb.g, rgb.b);
+
+    // Adjust lightness
+    var newL = hsl.l + factor;
+    newL = Math.max(0, Math.min(1, newL));
+
+    // Optionally shift hue for extreme adjustments
+    var newH = hsl.h;
+    if (allowHueShift && Math.abs(factor) > 0.2) {
+        // Slight hue shift toward yellow (high luminance) or blue (low luminance)
+        var hueTarget = factor > 0 ? 60 : 240;
+        newH = hsl.h + (hueTarget - hsl.h) * Math.abs(factor) * 0.1;
+        newH = ((newH % 360) + 360) % 360;
+    }
+
+    // Reduce saturation at extreme lightness for natural look
+    var newS = hsl.s;
+    if (newL > 0.9 || newL < 0.1) {
+        newS *= 0.5;
+    }
+
+    return hslToRgb(newH, newS, newL);
+}
+
+/**
+ * Oscillate edge colors to find best contrast
+ * @param {{r: number, g: number, b: number}} emissive
+ * @param {{r: number, g: number, b: number}} diffuse
+ * @param {{r: number, g: number, b: number}} ambient
+ * @param {object} options
+ * @returns {{diffuse: object, ambient: object, achieved: number}}
+ */
+function oscillateEdges(emissive, diffuse, ambient, options) {
+    var emissiveLum = relativeLuminance(emissive.r, emissive.g, emissive.b);
+    var diffuseLum = relativeLuminance(diffuse.r, diffuse.g, diffuse.b);
+    var currentContrast = contrastRatio(emissiveLum, diffuseLum);
+
+    var bestResult = { diffuse: diffuse, ambient: ambient, achieved: currentContrast };
+
+    // Determine direction: edges should go opposite to emissive luminance
+    var direction = emissiveLum > 0.5 ? -1 : 1;
+
+    var steps = 10;
+    for (var i = 1; i <= steps; i++) {
+        var factor = (i / steps) * options.range;
+
+        // Primary direction
+        var testDiffuse = adjustColorByFactor(diffuse, direction * factor, options.allowHueShift);
+        var testAmbient = adjustColorByFactor(ambient, direction * factor * 0.8, options.allowHueShift);
+
+        var testLum = relativeLuminance(testDiffuse.r, testDiffuse.g, testDiffuse.b);
+        var contrast = contrastRatio(emissiveLum, testLum);
+
+        if (contrast > bestResult.achieved) {
+            bestResult = { diffuse: testDiffuse, ambient: testAmbient, achieved: contrast };
+        }
+
+        if (contrast >= options.targetContrast) break;
+
+        // Try opposite direction for edge cases
+        testDiffuse = adjustColorByFactor(diffuse, -direction * factor, options.allowHueShift);
+        testAmbient = adjustColorByFactor(ambient, -direction * factor * 0.8, options.allowHueShift);
+
+        testLum = relativeLuminance(testDiffuse.r, testDiffuse.g, testDiffuse.b);
+        contrast = contrastRatio(emissiveLum, testLum);
+
+        if (contrast > bestResult.achieved) {
+            bestResult = { diffuse: testDiffuse, ambient: testAmbient, achieved: contrast };
+        }
+    }
+
+    return bestResult;
+}
+
+/**
+ * Oscillate face color to find better contrast
+ * @param {{r: number, g: number, b: number}} emissive
+ * @param {{r: number, g: number, b: number}} diffuse
+ * @param {object} options
+ * @returns {{emissive: object, achieved: number}}
+ */
+function oscillateFace(emissive, diffuse, options) {
+    var diffuseLum = relativeLuminance(diffuse.r, diffuse.g, diffuse.b);
+    var emissiveLum = relativeLuminance(emissive.r, emissive.g, emissive.b);
+    var currentContrast = contrastRatio(emissiveLum, diffuseLum);
+
+    var bestResult = { emissive: emissive, achieved: currentContrast };
+
+    // Face should move opposite to edges
+    var direction = diffuseLum > 0.5 ? -1 : 1;
+
+    var steps = 10;
+    for (var i = 1; i <= steps; i++) {
+        var factor = (i / steps) * options.range;
+
+        var testEmissive = adjustColorByFactor(emissive, direction * factor, options.allowHueShift);
+        var testLum = relativeLuminance(testEmissive.r, testEmissive.g, testEmissive.b);
+        var contrast = contrastRatio(testLum, diffuseLum);
+
+        if (contrast > bestResult.achieved) {
+            bestResult = { emissive: testEmissive, achieved: contrast };
+        }
+
+        if (contrast >= options.targetContrast) break;
+    }
+
+    return bestResult;
+}
+
+/**
+ * Adjust colors to achieve WCAG contrast while preserving user intent
+ * Priority: prefer edge modifications over face modifications
+ *
+ * @param {object} colors - User-provided colors
+ * @param {string} colors.emissive - Face color (hex)
+ * @param {string} colors.diffuse - Edge lit color (hex)
+ * @param {string} [colors.ambient] - Edge shadow color (hex)
+ * @param {object} [options]
+ * @param {number} [options.targetContrast=4.5] - Target contrast ratio
+ * @param {number} [options.edgeRange=0.4] - Max edge modification (0-1)
+ * @param {number} [options.faceRange=0.1] - Max face modification (0-1)
+ * @param {boolean} [options.allowHueShift=true] - Allow hue modifications
+ * @returns {{emissive: string, diffuse: string, ambient: string, achieved: number}}
+ */
+function adjustForContrast(colors, options) {
+    options = options || {};
+    var targetContrast = options.targetContrast || 4.5;
+    var edgeRange = options.edgeRange || 0.4;
+    var faceRange = options.faceRange || 0.1;
+    var allowHueShift = options.allowHueShift !== false;
+
+    var emissive = hexToRgb(colors.emissive);
+    var diffuse = hexToRgb(colors.diffuse);
+    var ambient = colors.ambient ? hexToRgb(colors.ambient) : { r: diffuse.r * 0.5, g: diffuse.g * 0.5, b: diffuse.b * 0.5 };
+
+    var emissiveLum = relativeLuminance(emissive.r, emissive.g, emissive.b);
+    var diffuseLum = relativeLuminance(diffuse.r, diffuse.g, diffuse.b);
+    var currentContrast = contrastRatio(emissiveLum, diffuseLum);
+
+    // Already meets target?
+    if (currentContrast >= targetContrast) {
+        return {
+            emissive: colors.emissive,
+            diffuse: colors.diffuse,
+            ambient: colors.ambient || rgbToHex(ambient),
+            achieved: currentContrast
+        };
+    }
+
+    // Phase 1: Try edge modification only
+    var edgeResult = oscillateEdges(emissive, diffuse, ambient, {
+        targetContrast: targetContrast,
+        range: edgeRange,
+        allowHueShift: allowHueShift
+    });
+
+    if (edgeResult.achieved >= targetContrast) {
+        return {
+            emissive: colors.emissive,
+            diffuse: rgbToHex(edgeResult.diffuse),
+            ambient: rgbToHex(edgeResult.ambient),
+            achieved: edgeResult.achieved
+        };
+    }
+
+    // Phase 2: Try face modification
+    var faceResult = oscillateFace(emissive, edgeResult.diffuse, {
+        targetContrast: targetContrast,
+        range: faceRange,
+        allowHueShift: allowHueShift
+    });
+
+    if (faceResult.achieved >= targetContrast) {
+        return {
+            emissive: rgbToHex(faceResult.emissive),
+            diffuse: rgbToHex(edgeResult.diffuse),
+            ambient: rgbToHex(edgeResult.ambient),
+            achieved: faceResult.achieved
+        };
+    }
+
+    // Phase 3: Oscillate both until convergence
+    var maxIterations = 5;
+    var currentEmissive = faceResult.emissive;
+    var currentDiffuse = edgeResult.diffuse;
+    var currentAmbient = edgeResult.ambient;
+    var bestAchieved = faceResult.achieved;
+
+    for (var iter = 0; iter < maxIterations; iter++) {
+        // Try more edge adjustment
+        var newEdgeResult = oscillateEdges(currentEmissive, currentDiffuse, currentAmbient, {
+            targetContrast: targetContrast,
+            range: edgeRange * 0.5,
+            allowHueShift: allowHueShift
+        });
+
+        if (newEdgeResult.achieved >= targetContrast) {
+            return {
+                emissive: rgbToHex(currentEmissive),
+                diffuse: rgbToHex(newEdgeResult.diffuse),
+                ambient: rgbToHex(newEdgeResult.ambient),
+                achieved: newEdgeResult.achieved
+            };
+        }
+
+        // Try more face adjustment
+        var newFaceResult = oscillateFace(currentEmissive, newEdgeResult.diffuse, {
+            targetContrast: targetContrast,
+            range: faceRange * 0.5,
+            allowHueShift: allowHueShift
+        });
+
+        if (newFaceResult.achieved >= targetContrast) {
+            return {
+                emissive: rgbToHex(newFaceResult.emissive),
+                diffuse: rgbToHex(newEdgeResult.diffuse),
+                ambient: rgbToHex(newEdgeResult.ambient),
+                achieved: newFaceResult.achieved
+            };
+        }
+
+        // Update for next iteration
+        if (newFaceResult.achieved > bestAchieved) {
+            bestAchieved = newFaceResult.achieved;
+            currentEmissive = newFaceResult.emissive;
+            currentDiffuse = newEdgeResult.diffuse;
+            currentAmbient = newEdgeResult.ambient;
+        } else {
+            // No improvement, stop
+            break;
+        }
+    }
+
+    // Return best result even if target not achieved
+    return {
+        emissive: rgbToHex(currentEmissive),
+        diffuse: rgbToHex(currentDiffuse),
+        ambient: rgbToHex(currentAmbient),
+        achieved: bestAchieved
+    };
+}
+
+// ============================================
+// Constants
+// ============================================
+
+var CONTRAST_LEVELS = {
+    AA_NORMAL: 4.5,
+    AA_LARGE: 3.0,
+    AAA_NORMAL: 7.0,
+    AAA_LARGE: 4.5
+};
+
+/**
+ * MeshWriter - 3D Text Rendering for Babylon.js
+ *
+ * @example
+ * // ES Module usage
+ * import { MeshWriter, registerFont } from 'meshwriter';
+ * import helvetica from 'meshwriter/fonts/helvetica';
+ *
+ * registerFont('Helvetica', helvetica);
+ * const Writer = await MeshWriter.createAsync(scene);
+ * const text = new Writer("Hello World", { "letter-height": 20 });
+ */
+
+
+const MeshWriter = {
+    /**
+     * Create MeshWriter async (recommended for Babylon 8+)
+     */
+    createAsync: createMeshWriterAsync,
+
+    /**
+     * Create MeshWriter sync (for Babylon < 8 or when CSG2 is pre-initialized)
+     */
+    create: createMeshWriter,
+
+    // Static CSG methods
+    isReady: isCSGReady,
+    getCSGVersion,
+    setCSGInitializer,
+    setCSGReadyCheck,
+    onCSGReady,
+    markCSGReady: markCSGInitialized,
+    initCSGModule,
+
+    // Font methods
+    registerFont,
+    registerFontAliases,
+    getFont,
+    isFontRegistered,
+
+    // Encoding utilities
+    codeList,
+    decodeList,
+
+    // Baked font methods (lightweight alternative to variable fonts)
+    loadBakedFont,
+    loadBakedFontsFromManifest,
+    findNearestWeight,
+    getBakedFontManifest
+};
+
+exports.CONTRAST_LEVELS = CONTRAST_LEVELS;
+exports.MeshWriter = MeshWriter;
+exports.TextFogPlugin = TextFogPlugin;
+exports.adjustForContrast = adjustForContrast;
+exports.clearFonts = clearFonts;
+exports.codeList = codeList;
+exports.contrastRatio = contrastRatio;
+exports.createMeshWriter = createMeshWriter;
+exports.createMeshWriterAsync = createMeshWriterAsync;
+exports.decodeFontData = decodeList;
+exports.decodeList = decodeList;
+exports.default = MeshWriter;
+exports.deriveEdgeColors = deriveEdgeColors;
+exports.encodeFontData = codeList;
+exports.findNearestWeight = findNearestWeight;
+exports.getBakedFontManifest = getBakedFontManifest;
+exports.getCSGVersion = getCSGVersion;
+exports.getFont = getFont;
+exports.getRegisteredFonts = getRegisteredFonts;
+exports.hexToRgb = hexToRgb;
+exports.hslToRgb = hslToRgb;
+exports.initCSGModule = initCSGModule;
+exports.isCSGReady = isCSGReady;
+exports.isFontRegistered = isFontRegistered;
+exports.loadBakedFont = loadBakedFont;
+exports.loadBakedFontsFromManifest = loadBakedFontsFromManifest;
+exports.markCSGReady = markCSGInitialized;
+exports.onCSGReady = onCSGReady;
+exports.registerFont = registerFont;
+exports.registerFontAliases = registerFontAliases;
+exports.relativeLuminance = relativeLuminance;
+exports.rgbToHex = rgbToHex;
+exports.rgbToHsl = rgbToHsl;
+exports.setCSGInitializer = setCSGInitializer;
+exports.setCSGReadyCheck = setCSGReadyCheck;
+exports.unregisterFont = unregisterFont;
+//# sourceMappingURL=meshwriter.cjs.js.map