meshwriter-cudu 3.0.0

package/dist/meshwriter.esm.js

@@ -0,0 +1,2606 @@
+import { Vector2, Vector3 } from '@babylonjs/core/Maths/math.vector';
+import { Color3 } from '@babylonjs/core/Maths/math.color';
+import { Path2, Curve3 } from '@babylonjs/core/Maths/math.path';
+import { Mesh } from '@babylonjs/core/Meshes/mesh';
+import { VertexData } from '@babylonjs/core/Meshes/mesh.vertexData';
+import { PolygonMeshBuilder } from '@babylonjs/core/Meshes/polygonMesh';
+import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial';
+import { MaterialPluginBase } from '@babylonjs/core/Materials/materialPluginBase';
+import { SolidParticleSystem } from '@babylonjs/core/Particles/solidParticleSystem';
+import { CSG as CSG$1 } from '@babylonjs/core/Meshes/csg';
+import { IsCSG2Ready as IsCSG2Ready$1, InitializeCSG2Async as InitializeCSG2Async$1, CSG2 as CSG2$1 } from '@babylonjs/core/Meshes/csg2';
+import earcutModule from '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$1;
+let CSG2 = CSG2$1;
+let InitializeCSG2Async = InitializeCSG2Async$1;
+let IsCSG2Ready = IsCSG2Ready$1;
+
+// 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 {
+    /**
+     * @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 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("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("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.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(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(name, scene);
+    var vertexData = new 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 Vector2(round(point.x), round(point.y));
+}
+
+/**
+ * Merge array of meshes
+ */
+function merge(arrayOfMeshes) {
+    return arrayOfMeshes.length === 1
+        ? arrayOfMeshes[0]
+        : 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 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 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 (!Path2 || !Path2.prototype) {
+        return;
+    }
+
+    /** @type {any} */
+    const proto = 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 Vector3(lastPoint.x, lastPoint.y, 0);
+        const control = new Vector3(redX, redY, 0);
+        const destination = new Vector3(blueX, blueY, 0);
+
+        const curve = 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 Vector3(lastPoint.x, lastPoint.y, 0);
+        const control1 = new Vector3(redX, redY, 0);
+        const control2 = new Vector3(greenX, greenY, 0);
+        const destination = new Vector3(blueX, blueY, 0);
+
+        const nbPoints = Math.floor(0.3 + curveSampleSize * 1.5);
+        const curve = 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 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
+};
+
+export { CONTRAST_LEVELS, MeshWriter, TextFogPlugin, adjustForContrast, clearFonts, codeList, contrastRatio, createMeshWriter, createMeshWriterAsync, decodeList as decodeFontData, decodeList, MeshWriter as default, deriveEdgeColors, codeList as encodeFontData, findNearestWeight, getBakedFontManifest, getCSGVersion, getFont, getRegisteredFonts, hexToRgb, hslToRgb, initCSGModule, isCSGReady, isFontRegistered, loadBakedFont, loadBakedFontsFromManifest, markCSGInitialized as markCSGReady, onCSGReady, registerFont, registerFontAliases, relativeLuminance, rgbToHex, rgbToHsl, setCSGInitializer, setCSGReadyCheck, unregisterFont };
+//# sourceMappingURL=meshwriter.esm.js.map