three-text 0.2.16 → 0.2.17

package/dist/index.umd.js

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.2.16
+ * three-text v0.2.17
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify
@@ -198,7 +198,7 @@
         FitnessClass[FitnessClass["LOOSE"] = 2] = "LOOSE";
         FitnessClass[FitnessClass["VERY_LOOSE"] = 3] = "VERY_LOOSE";
     })(FitnessClass || (FitnessClass = {}));
-    // ActiveNodeList maintains all currently viable breakpoints as we scan through the text.
+    // ActiveNodeList maintains all currently viable breakpoints as we scan through the text
     // Each node represents a potential break with accumulated demerits (total "cost" from start)
     //
     // Demerits = cumulative penalty score from text start to this break, calculated as:
@@ -340,9 +340,9 @@
         // Converts text into items (boxes, glues, penalties) for line breaking
         // The measureText function should return widths that include any letter spacing
         static itemizeText(text, measureText, // function to measure text width
-        hyphenate = false, language = 'en-us', availablePatterns, lefthyphenmin = DEFAULT_LEFT_HYPHEN_MIN, righthyphenmin = DEFAULT_RIGHT_HYPHEN_MIN, context) {
+        measureTextWidths, hyphenate = false, language = 'en-us', availablePatterns, lefthyphenmin = DEFAULT_LEFT_HYPHEN_MIN, righthyphenmin = DEFAULT_RIGHT_HYPHEN_MIN, context) {
             const items = [];
-            items.push(...this.itemizeParagraph(text, measureText, hyphenate, language, availablePatterns, lefthyphenmin, righthyphenmin, context));
+            items.push(...this.itemizeParagraph(text, measureText, measureTextWidths, hyphenate, language, availablePatterns, lefthyphenmin, righthyphenmin, context));
             // Final glue and penalty to end the paragraph
             // Use infinite stretch to fill the last line
             items.push({
@@ -447,9 +447,10 @@
             return (this.isCJClosingPunctuation(char) || this.isCJOpeningPunctuation(char));
         }
         // CJK (Chinese/Japanese/Korean) character-level itemization with inter-character glue
-        static itemizeCJKText(text, measureText, context, startOffset = 0, glueParams) {
+        static itemizeCJKText(text, measureText, measureTextWidths, context, startOffset = 0, glueParams) {
             const items = [];
             const chars = Array.from(text);
+            const widths = measureTextWidths ? measureTextWidths(text) : null;
             let textPosition = startOffset;
             // Inter-character glue parameters
             let glueWidth;
@@ -470,7 +471,7 @@
                 const char = chars[i];
                 const nextChar = i < chars.length - 1 ? chars[i + 1] : null;
                 if (/\s/.test(char)) {
-                    const width = measureText(char);
+                    const width = widths ? (widths[i] ?? measureText(char)) : measureText(char);
                     items.push({
                         type: ItemType.GLUE,
                         width,
@@ -484,7 +485,7 @@
                 }
                 items.push({
                     type: ItemType.BOX,
-                    width: measureText(char),
+                    width: widths ? (widths[i] ?? measureText(char)) : measureText(char),
                     text: char,
                     originIndex: textPosition
                 });
@@ -515,15 +516,21 @@
             }
             return items;
         }
-        static itemizeParagraph(text, measureText, hyphenate, language, availablePatterns, lefthyphenmin, righthyphenmin, context) {
+        static itemizeParagraph(text, measureText, measureTextWidths, hyphenate, language, availablePatterns, lefthyphenmin, righthyphenmin, context) {
             const items = [];
             const chars = Array.from(text);
-            // Calculate CJK glue parameters once for consistency across all segments
-            const baseCharWidth = measureText('字');
-            const cjkGlueParams = {
-                width: 0,
-                stretch: baseCharWidth * 0.04,
-                shrink: baseCharWidth * 0.04
+            // Calculate CJK glue parameters lazily and once for consistency across all segments
+            let cjkGlueParams;
+            const getCjkGlueParams = () => {
+                if (!cjkGlueParams) {
+                    const baseCharWidth = measureText('字');
+                    cjkGlueParams = {
+                        width: 0,
+                        stretch: baseCharWidth * 0.04,
+                        shrink: baseCharWidth * 0.04
+                    };
+                }
+                return cjkGlueParams;
             };
             let buffer = '';
             let bufferStart = 0;
@@ -533,7 +540,7 @@
                 if (buffer.length === 0)
                     return;
                 if (bufferScript === 'cjk') {
-                    const cjkItems = this.itemizeCJKText(buffer, measureText, context, bufferStart, cjkGlueParams);
+                    const cjkItems = this.itemizeCJKText(buffer, measureText, measureTextWidths, context, bufferStart, getCjkGlueParams());
                     items.push(...cjkItems);
                 }
                 else {
@@ -726,7 +733,7 @@
                 align: options.align || 'left',
                 hyphenate: options.hyphenate || false
             });
-            const { text, width, align = 'left', direction = 'ltr', hyphenate = false, language = 'en-us', respectExistingBreaks = true, measureText, hyphenationPatterns, unitsPerEm, letterSpacing = 0, tolerance = DEFAULT_TOLERANCE, pretolerance = DEFAULT_PRETOLERANCE, emergencyStretch = DEFAULT_EMERGENCY_STRETCH, autoEmergencyStretch, lefthyphenmin = DEFAULT_LEFT_HYPHEN_MIN, righthyphenmin = DEFAULT_RIGHT_HYPHEN_MIN, linepenalty = DEFAULT_LINE_PENALTY, adjdemerits = DEFAULT_FITNESS_DIFF_DEMERITS, hyphenpenalty = DEFAULT_HYPHEN_PENALTY, exhyphenpenalty = DEFAULT_EX_HYPHEN_PENALTY, doublehyphendemerits = DEFAULT_DOUBLE_HYPHEN_DEMERITS, looseness = 0, disableShortLineDetection = false, shortLineThreshold = SHORT_LINE_WIDTH_THRESHOLD } = options;
+            const { text, width, align = 'left', direction = 'ltr', hyphenate = false, language = 'en-us', respectExistingBreaks = true, measureText, measureTextWidths, hyphenationPatterns, unitsPerEm, letterSpacing = 0, tolerance = DEFAULT_TOLERANCE, pretolerance = DEFAULT_PRETOLERANCE, emergencyStretch = DEFAULT_EMERGENCY_STRETCH, autoEmergencyStretch, lefthyphenmin = DEFAULT_LEFT_HYPHEN_MIN, righthyphenmin = DEFAULT_RIGHT_HYPHEN_MIN, linepenalty = DEFAULT_LINE_PENALTY, adjdemerits = DEFAULT_FITNESS_DIFF_DEMERITS, hyphenpenalty = DEFAULT_HYPHEN_PENALTY, exhyphenpenalty = DEFAULT_EX_HYPHEN_PENALTY, doublehyphendemerits = DEFAULT_DOUBLE_HYPHEN_DEMERITS, looseness = 0, disableShortLineDetection = false, shortLineThreshold = SHORT_LINE_WIDTH_THRESHOLD } = options;
             // Handle multiple paragraphs by processing each independently
             if (respectExistingBreaks && text.includes('\n')) {
                 const paragraphs = text.split('\n');
@@ -789,9 +796,9 @@
                 exHyphenPenalty: exhyphenpenalty,
                 currentAlign: align,
                 unitsPerEm,
-                // measureText() includes trailing letter spacing after the final glyph of a token.
+                // measureText() includes trailing letter spacing after the final glyph of a token
                 // Shaping applies letter spacing only between glyphs, so we subtract one
-                // trailing letterSpacingFU per line segment (see computeAdjustmentRatio/createLines).
+                // trailing letterSpacingFU per line segment (see computeAdjustmentRatio/createLines)
                 letterSpacingFU: unitsPerEm ? letterSpacing * unitsPerEm : 0
             };
             if (!width || width === Infinity) {
@@ -810,7 +817,7 @@
                 ];
             }
             // Itemize without hyphenation first (TeX approach: only compute if needed)
-            const allItems = LineBreak.itemizeText(text, measureText, false, language, hyphenationPatterns, lefthyphenmin, righthyphenmin, context);
+            const allItems = LineBreak.itemizeText(text, measureText, measureTextWidths, false, language, hyphenationPatterns, lefthyphenmin, righthyphenmin, context);
             if (allItems.length === 0) {
                 return [];
             }
@@ -829,7 +836,7 @@
                 let breaks = LineBreak.findBreakpoints(currentItems, width, pretolerance, looseness, false, 0, context);
                 // Second pass: with hyphenation if first pass failed
                 if (breaks.length === 0 && useHyphenation) {
-                    const itemsWithHyphenation = LineBreak.itemizeText(text, measureText, true, language, hyphenationPatterns, lefthyphenmin, righthyphenmin, context);
+                    const itemsWithHyphenation = LineBreak.itemizeText(text, measureText, measureTextWidths, true, language, hyphenationPatterns, lefthyphenmin, righthyphenmin, context);
                     currentItems = itemsWithHyphenation;
                     breaks = LineBreak.findBreakpoints(currentItems, width, tolerance, looseness, false, 0, context);
                 }
@@ -1143,9 +1150,9 @@
                         ? items[lineEnd].width
                         : items[lineEnd].preBreakWidth;
             }
-            // Correct for trailing letter spacing at the end of the line segment.
+            // Correct for trailing letter spacing at the end of the line segment
             // Our token measurement includes letter spacing after the final glyph;
-            // shaping does not add letter spacing after the final glyph in a line.
+            // shaping does not add letter spacing after the final glyph in a line
             if (context?.letterSpacingFU && totalWidth !== 0) {
                 totalWidth -= context.letterSpacingFU;
             }
@@ -1311,7 +1318,7 @@
                     }
                 }
                 const lineText = lineTextParts.join('');
-                // Correct for trailing letter spacing at the end of the line.
+                // Correct for trailing letter spacing at the end of the line
                 if (context?.letterSpacingFU && naturalWidth !== 0) {
                     naturalWidth -= context.letterSpacingFU;
                 }
@@ -1368,7 +1375,7 @@
                     finalNaturalWidth += item.width;
                 }
                 const finalLineText = finalLineTextParts.join('');
-                // Correct for trailing letter spacing at the end of the final line.
+                // Correct for trailing letter spacing at the end of the final line
                 if (context?.letterSpacingFU && finalNaturalWidth !== 0) {
                     finalNaturalWidth -= context.letterSpacingFU;
                 }
@@ -1405,12 +1412,21 @@
         }
     }
 
+    // Memoize conversion per feature-object identity to avoid rebuilding the same
+    // comma-separated string on every HarfBuzz shape call
+    const featureStringCache = new WeakMap();
     // Convert feature objects to HarfBuzz comma-separated format
     function convertFontFeaturesToString(features) {
         if (!features || Object.keys(features).length === 0) {
             return undefined;
         }
+        const cached = featureStringCache.get(features);
+        if (cached !== undefined) {
+            return cached ?? undefined;
+        }
         const featureStrings = [];
+        // Preserve insertion order of the input object
+        // (The public API/tests expect this to be stable and predictable)
         for (const [tag, value] of Object.entries(features)) {
             if (!/^[a-zA-Z0-9]{4}$/.test(tag)) {
                 logger.warn(`Invalid OpenType feature tag: "${tag}". Tags must be exactly 4 alphanumeric characters.`);
@@ -1429,10 +1445,63 @@
                 logger.warn(`Invalid value for feature "${tag}": ${value}. Expected boolean or positive number.`);
             }
         }
-        return featureStrings.length > 0 ? featureStrings.join(',') : undefined;
+        const result = featureStrings.length > 0 ? featureStrings.join(',') : undefined;
+        featureStringCache.set(features, result ?? null);
+        return result;
     }
 
     class TextMeasurer {
+        // Shape once and return per-codepoint widths aligned with Array.from(text)
+        // Groups glyph advances by HarfBuzz cluster (cl)
+        // Includes trailing per-glyph letter spacing like measureTextWidth
+        static measureTextWidths(loadedFont, text, letterSpacing = 0) {
+            const chars = Array.from(text);
+            if (chars.length === 0)
+                return [];
+            // HarfBuzz clusters are UTF-16 code unit indices
+            const startToCharIndex = new Map();
+            let codeUnitIndex = 0;
+            for (let i = 0; i < chars.length; i++) {
+                startToCharIndex.set(codeUnitIndex, i);
+                codeUnitIndex += chars[i].length;
+            }
+            const widths = new Array(chars.length).fill(0);
+            const buffer = loadedFont.hb.createBuffer();
+            try {
+                buffer.addText(text);
+                buffer.guessSegmentProperties();
+                const featuresString = convertFontFeaturesToString(loadedFont.fontFeatures);
+                loadedFont.hb.shape(loadedFont.font, buffer, featuresString);
+                const glyphInfos = buffer.json(loadedFont.font);
+                const letterSpacingInFontUnits = letterSpacing * loadedFont.upem;
+                for (let i = 0; i < glyphInfos.length; i++) {
+                    const glyph = glyphInfos[i];
+                    const cl = glyph.cl ?? 0;
+                    let charIndex = startToCharIndex.get(cl);
+                    // Fallback if cl lands mid-codepoint
+                    if (charIndex === undefined) {
+                        // Find the closest start <= cl
+                        for (let back = cl; back >= 0; back--) {
+                            const candidate = startToCharIndex.get(back);
+                            if (candidate !== undefined) {
+                                charIndex = candidate;
+                                break;
+                            }
+                        }
+                    }
+                    if (charIndex === undefined)
+                        continue;
+                    widths[charIndex] += glyph.ax;
+                    if (letterSpacingInFontUnits !== 0) {
+                        widths[charIndex] += letterSpacingInFontUnits;
+                    }
+                }
+                return widths;
+            }
+            finally {
+                buffer.destroy();
+            }
+        }
         static measureTextWidth(loadedFont, text, letterSpacing = 0) {
             const buffer = loadedFont.hb.createBuffer();
             buffer.addText(text);
@@ -1489,7 +1558,8 @@
                     unitsPerEm: this.loadedFont.upem,
                     letterSpacing,
                     measureText: (textToMeasure) => TextMeasurer.measureTextWidth(this.loadedFont, textToMeasure, letterSpacing // Letter spacing included in width measurements
-                    )
+                    ),
+                    measureTextWidths: (textToMeasure) => TextMeasurer.measureTextWidths(this.loadedFont, textToMeasure, letterSpacing)
                 });
             }
             else {
@@ -1511,6 +1581,15 @@
             return { lines };
         }
         applyAlignment(vertices, options) {
+            const { offset, adjustedBounds } = this.computeAlignmentOffset(options);
+            if (offset !== 0) {
+                for (let i = 0; i < vertices.length; i += 3) {
+                    vertices[i] += offset;
+                }
+            }
+            return { offset, adjustedBounds };
+        }
+        computeAlignmentOffset(options) {
             const { width, align, planeBounds } = options;
             let offset = 0;
             const adjustedBounds = {
@@ -1522,17 +1601,13 @@
                 if (align === 'center') {
                     offset = (width - lineWidth) / 2 - planeBounds.min.x;
                 }
-                else if (align === 'right') {
+                else {
                     offset = width - planeBounds.max.x;
                 }
-                if (offset !== 0) {
-                    // Translate vertices
-                    for (let i = 0; i < vertices.length; i += 3) {
-                        vertices[i] += offset;
-                    }
-                    adjustedBounds.min.x += offset;
-                    adjustedBounds.max.x += offset;
-                }
+            }
+            if (offset !== 0) {
+                adjustedBounds.min.x += offset;
+                adjustedBounds.max.x += offset;
             }
             return { offset, adjustedBounds };
         }
@@ -2629,7 +2704,7 @@
     var libtess_minExports = libtess_min.exports;
 
     class Tessellator {
-        process(paths, removeOverlaps = true, isCFF = false) {
+        process(paths, removeOverlaps = true, isCFF = false, needsExtrusionContours = true) {
             if (paths.length === 0) {
                 return { triangles: { vertices: [], indices: [] }, contours: [] };
             }
@@ -2638,66 +2713,124 @@
                 return { triangles: { vertices: [], indices: [] }, contours: [] };
             }
             logger.log(`Tessellator: removeOverlaps=${removeOverlaps}, processing ${valid.length} paths`);
-            return this.tessellate(valid, removeOverlaps, isCFF);
-        }
-        tessellate(paths, removeOverlaps, isCFF) {
-            // TTF fonts have opposite winding from tessellator expectations
-            const normalizedPaths = !isCFF && !removeOverlaps
-                ? paths.map((p) => this.reverseWinding(p))
-                : paths;
-            let contours = this.pathsToContours(normalizedPaths);
+            return this.tessellate(valid, removeOverlaps, isCFF, needsExtrusionContours);
+        }
+        tessellate(paths, removeOverlaps, isCFF, needsExtrusionContours) {
+            // libtess expects CCW winding; TTF outer contours are CW
+            const needsWindingReversal = !isCFF && !removeOverlaps;
+            let originalContours;
+            let tessContours;
+            if (needsWindingReversal) {
+                tessContours = this.pathsToContours(paths, true);
+                if (removeOverlaps || needsExtrusionContours) {
+                    originalContours = this.pathsToContours(paths);
+                }
+            }
+            else {
+                originalContours = this.pathsToContours(paths);
+                tessContours = originalContours;
+            }
+            let extrusionContours = needsExtrusionContours
+                ? originalContours ?? this.pathsToContours(paths)
+                : [];
             if (removeOverlaps) {
                 logger.log('Two-pass: boundary extraction then triangulation');
-                // Extract boundaries to remove overlaps
                 perfLogger.start('Tessellator.boundaryPass', {
-                    contourCount: contours.length
+                    contourCount: tessContours.length
                 });
-                const boundaryResult = this.performTessellation(contours, 'boundary');
+                const boundaryResult = this.performTessellation(originalContours, 'boundary');
                 perfLogger.end('Tessellator.boundaryPass');
                 if (!boundaryResult) {
                     logger.warn('libtess returned empty result from boundary pass');
                     return { triangles: { vertices: [], indices: [] }, contours: [] };
                 }
-                // Convert boundary elements back to contours
-                contours = this.boundaryToContours(boundaryResult);
-                logger.log(`Boundary pass created ${contours.length} contours. Starting triangulation pass.`);
+                // Boundary pass normalizes winding (outer CCW, holes CW)
+                tessContours = this.boundaryToContours(boundaryResult);
+                if (needsExtrusionContours) {
+                    extrusionContours = tessContours;
+                }
+                logger.log(`Boundary pass created ${tessContours.length} contours. Starting triangulation pass.`);
             }
             else {
                 logger.log(`Single-pass triangulation for ${isCFF ? 'CFF' : 'TTF'}`);
+                // TTF contours may have inconsistent winding; check if we need normalization
+                if (needsExtrusionContours && !isCFF) {
+                    const needsNormalization = this.needsWindingNormalization(extrusionContours);
+                    if (needsNormalization) {
+                        logger.log('Complex topology detected, running boundary pass for winding normalization');
+                        perfLogger.start('Tessellator.windingNormalization', {
+                            contourCount: extrusionContours.length
+                        });
+                        const boundaryResult = this.performTessellation(extrusionContours, 'boundary');
+                        perfLogger.end('Tessellator.windingNormalization');
+                        if (boundaryResult) {
+                            extrusionContours = this.boundaryToContours(boundaryResult);
+                        }
+                    }
+                    else {
+                        logger.log('Simple topology, skipping winding normalization');
+                    }
+                }
             }
-            // Triangulate the contours
             perfLogger.start('Tessellator.triangulationPass', {
-                contourCount: contours.length
+                contourCount: tessContours.length
             });
-            const triangleResult = this.performTessellation(contours, 'triangles');
+            const triangleResult = this.performTessellation(tessContours, 'triangles');
             perfLogger.end('Tessellator.triangulationPass');
             if (!triangleResult) {
                 const warning = removeOverlaps
                     ? 'libtess returned empty result from triangulation pass'
                     : 'libtess returned empty result from single-pass triangulation';
                 logger.warn(warning);
-                return { triangles: { vertices: [], indices: [] }, contours };
+                return { triangles: { vertices: [], indices: [] }, contours: extrusionContours };
             }
             return {
                 triangles: {
                     vertices: triangleResult.vertices,
                     indices: triangleResult.indices || []
                 },
-                contours
+                contours: extrusionContours
             };
         }
-        pathsToContours(paths) {
-            return paths.map((path) => {
-                const contour = [];
-                for (const point of path.points) {
-                    contour.push(point.x, point.y);
+        pathsToContours(paths, reversePoints = false) {
+            const contours = new Array(paths.length);
+            for (let p = 0; p < paths.length; p++) {
+                const points = paths[p].points;
+                const pointCount = points.length;
+                // Clipper-style paths can be explicitly closed by repeating the first point at the end
+                // Normalize to a single closing vertex for stable side wall generation
+                const isClosed = pointCount > 1 &&
+                    points[0].x === points[pointCount - 1].x &&
+                    points[0].y === points[pointCount - 1].y;
+                const end = isClosed ? pointCount - 1 : pointCount;
+                // +1 to append a closing vertex
+                const contour = new Array((end + 1) * 2);
+                let i = 0;
+                if (reversePoints) {
+                    for (let k = end - 1; k >= 0; k--) {
+                        const pt = points[k];
+                        contour[i++] = pt.x;
+                        contour[i++] = pt.y;
+                    }
                 }
-                return contour;
-            });
+                else {
+                    for (let k = 0; k < end; k++) {
+                        const pt = points[k];
+                        contour[i++] = pt.x;
+                        contour[i++] = pt.y;
+                    }
+                }
+                // Some glyphs omit closePath, leaving gaps in extruded side walls
+                if (i >= 2) {
+                    contour[i++] = contour[0];
+                    contour[i++] = contour[1];
+                }
+                contours[p] = contour;
+            }
+            return contours;
         }
         performTessellation(contours, mode) {
             const tess = new libtess_minExports.GluTesselator();
-            // Set winding rule to NON-ZERO
             tess.gluTessProperty(libtess_minExports.gluEnum.GLU_TESS_WINDING_RULE, libtess_minExports.windingRule.GLU_TESS_WINDING_NONZERO);
             const vertices = [];
             const indices = [];
@@ -2720,7 +2853,7 @@
                 });
                 tess.gluTessCallback(libtess_minExports.gluEnum.GLU_TESS_END, () => {
                     if (currentContour.length > 0) {
-                        contourIndices.push([...currentContour]);
+                        contourIndices.push(currentContour);
                     }
                 });
             }
@@ -2765,7 +2898,6 @@
                     const vertIdx = idx * 2;
                     contour.push(boundaryResult.vertices[vertIdx], boundaryResult.vertices[vertIdx + 1]);
                 }
-                // Ensure contour is closed for side wall generation
                 if (contour.length > 2) {
                     if (contour[0] !== contour[contour.length - 2] ||
                         contour[1] !== contour[contour.length - 1]) {
@@ -2776,11 +2908,45 @@
             }
             return contours;
         }
-        reverseWinding(path) {
-            return {
-                ...path,
-                points: [...path.points].reverse()
-            };
+        // Check if contours need winding normalization via boundary pass
+        // Returns false if topology is simple enough to skip the expensive pass
+        needsWindingNormalization(contours) {
+            if (contours.length === 0)
+                return false;
+            // Heuristic 1: Single contour never needs normalization
+            if (contours.length === 1)
+                return false;
+            // Heuristic 2: All same winding = all outers, no holes
+            // Compute signed areas
+            let firstSign = null;
+            for (const contour of contours) {
+                const area = this.signedArea(contour);
+                const sign = area >= 0 ? 1 : -1;
+                if (firstSign === null) {
+                    firstSign = sign;
+                }
+                else if (sign !== firstSign) {
+                    // Mixed winding detected → might have holes or complex topology
+                    return true;
+                }
+            }
+            // All same winding → simple topology, no normalization needed
+            return false;
+        }
+        // Compute signed area (CCW = positive, CW = negative)
+        signedArea(contour) {
+            let area = 0;
+            const len = contour.length;
+            if (len < 6)
+                return 0; // Need at least 3 points
+            for (let i = 0; i < len; i += 2) {
+                const x1 = contour[i];
+                const y1 = contour[i + 1];
+                const x2 = contour[(i + 2) % len];
+                const y2 = contour[(i + 3) % len];
+                area += x1 * y2 - x2 * y1;
+            }
+            return area / 2;
         }
     }
 
@@ -2830,25 +2996,26 @@
             // Extruded geometry: front at z=0, back at z=depth
             const minBackOffset = unitsPerEm * 0.000025;
             const backZ = depth <= minBackOffset ? minBackOffset : depth;
-            // Cap at z=0, back face
-            for (let p = 0, vi = 0; p < points.length; p += 2, vi++) {
-                const base = vi * 3;
-                vertices[base] = points[p];
-                vertices[base + 1] = points[p + 1];
-                vertices[base + 2] = 0;
-                normals[base] = 0;
-                normals[base + 1] = 0;
-                normals[base + 2] = -1;
-            }
-            // Cap at z=depth, front face
+            // Generate both caps in one pass
             for (let p = 0, vi = 0; p < points.length; p += 2, vi++) {
-                const base = (numPoints + vi) * 3;
-                vertices[base] = points[p];
-                vertices[base + 1] = points[p + 1];
-                vertices[base + 2] = backZ;
-                normals[base] = 0;
-                normals[base + 1] = 0;
-                normals[base + 2] = 1;
+                const x = points[p];
+                const y = points[p + 1];
+                // Cap at z=0
+                const base0 = vi * 3;
+                vertices[base0] = x;
+                vertices[base0 + 1] = y;
+                vertices[base0 + 2] = 0;
+                normals[base0] = 0;
+                normals[base0 + 1] = 0;
+                normals[base0 + 2] = -1;
+                // Cap at z=depth
+                const baseD = (numPoints + vi) * 3;
+                vertices[baseD] = x;
+                vertices[baseD + 1] = y;
+                vertices[baseD + 2] = backZ;
+                normals[baseD] = 0;
+                normals[baseD + 1] = 0;
+                normals[baseD + 2] = 1;
             }
             // libtess outputs CCW triangles (viewed from +Z)
             // Z=0 cap faces -Z, reverse winding
@@ -3142,21 +3309,23 @@
                 return path;
             }
             this.stats.originalPointCount += path.points.length;
-            let points = [...path.points];
+            // Most paths are already immutable after collection; avoid copying large point arrays
+            // The optimizers below never mutate the input `points` array
+            const points = path.points;
             if (points.length < 5) {
                 return path;
             }
-            points = this.simplifyPathVW(points, this.config.areaThreshold);
-            if (points.length < 3) {
+            let optimized = this.simplifyPathVW(points, this.config.areaThreshold);
+            if (optimized.length < 3) {
                 return path;
             }
-            points = this.removeColinearPoints(points, this.config.colinearThreshold);
-            if (points.length < 3) {
+            optimized = this.removeColinearPoints(optimized, this.config.colinearThreshold);
+            if (optimized.length < 3) {
                 return path;
             }
             return {
                 ...path,
-                points
+                points: optimized
             };
         }
         // Visvalingam-Whyatt algorithm
@@ -3610,7 +3779,7 @@
             if (this.currentGlyphPaths.length > 0) {
                 this.collectedGlyphs.push({
                     glyphId: this.currentGlyphId,
-                    paths: [...this.currentGlyphPaths],
+                    paths: this.currentGlyphPaths,
                     bounds: {
                         min: {
                             x: this.currentGlyphBounds.min.x,
@@ -3662,11 +3831,10 @@
                 return;
             }
             const flattenedPoints = this.polygonizer.polygonizeQuadratic(start, control, end);
-            for (const point of flattenedPoints) {
-                this.updateBounds(point);
-            }
             for (let i = 0; i < flattenedPoints.length; i++) {
-                this.currentPath.points.push(flattenedPoints[i]);
+                const pt = flattenedPoints[i];
+                this.updateBounds(pt);
+                this.currentPath.points.push(pt);
             }
             this.currentPoint = end;
         }
@@ -3686,11 +3854,10 @@
                 return;
             }
             const flattenedPoints = this.polygonizer.polygonizeCubic(start, control1, control2, end);
-            for (const point of flattenedPoints) {
-                this.updateBounds(point);
-            }
             for (let i = 0; i < flattenedPoints.length; i++) {
-                this.currentPath.points.push(flattenedPoints[i]);
+                const pt = flattenedPoints[i];
+                this.updateBounds(pt);
+                this.currentPath.points.push(pt);
             }
             this.currentPoint = end;
         }
@@ -3880,6 +4047,7 @@
         constructor(cache, loadedFont) {
             this.fontId = 'default';
             this.cacheKeyPrefix = 'default';
+            this.emptyGlyphs = new Set();
             this.cache = cache;
             this.loadedFont = loadedFont;
             this.tessellator = new Tessellator();
@@ -3933,63 +4101,34 @@
         }
         // Build instanced geometry from glyph contours
         buildInstancedGeometry(clustersByLine, depth, removeOverlaps, isCFF, separateGlyphs = false, coloredTextIndices) {
-            perfLogger.start('GlyphGeometryBuilder.buildInstancedGeometry', {
-                lineCount: clustersByLine.length,
-                wordCount: clustersByLine.flat().length,
-                depth,
-                removeOverlaps
-            });
-            // Growable typed arrays; slice to final size at end
-            let vertexBuffer = new Float32Array(1024);
-            let normalBuffer = new Float32Array(1024);
-            let indexBuffer = new Uint32Array(1024);
-            let vertexPos = 0; // float index (multiple of 3)
-            let normalPos = 0; // float index (multiple of 3)
-            let indexPos = 0; // index count
-            const ensureFloatCapacity = (buffer, needed) => {
-                if (needed <= buffer.length)
-                    return buffer;
-                let nextSize = buffer.length;
-                while (nextSize < needed)
-                    nextSize *= 2;
-                const next = new Float32Array(nextSize);
-                next.set(buffer);
-                return next;
-            };
-            const ensureIndexCapacity = (buffer, needed) => {
-                if (needed <= buffer.length)
-                    return buffer;
-                let nextSize = buffer.length;
-                while (nextSize < needed)
-                    nextSize *= 2;
-                const next = new Uint32Array(nextSize);
-                next.set(buffer);
-                return next;
-            };
-            const appendGeometryToBuffers = (data, position, vertexOffset) => {
-                const v = data.vertices;
-                const n = data.normals;
-                const idx = data.indices;
-                // Grow buffers as needed
-                vertexBuffer = ensureFloatCapacity(vertexBuffer, vertexPos + v.length);
-                normalBuffer = ensureFloatCapacity(normalBuffer, normalPos + n.length);
-                indexBuffer = ensureIndexCapacity(indexBuffer, indexPos + idx.length);
-                // Vertices: translate by position
-                const px = position.x;
-                const py = position.y;
-                const pz = position.z;
-                for (let j = 0; j < v.length; j += 3) {
-                    vertexBuffer[vertexPos++] = v[j] + px;
-                    vertexBuffer[vertexPos++] = v[j + 1] + py;
-                    vertexBuffer[vertexPos++] = v[j + 2] + pz;
-                }
-                // Normals: straight copy
-                normalBuffer.set(n, normalPos);
-                normalPos += n.length;
-                // Indices: copy with vertex offset
-                for (let j = 0; j < idx.length; j++) {
-                    indexBuffer[indexPos++] = idx[j] + vertexOffset;
-                }
+            if (isLogEnabled) {
+                let wordCount = 0;
+                for (let i = 0; i < clustersByLine.length; i++) {
+                    wordCount += clustersByLine[i].length;
+                }
+                perfLogger.start('GlyphGeometryBuilder.buildInstancedGeometry', {
+                    lineCount: clustersByLine.length,
+                    wordCount,
+                    depth,
+                    removeOverlaps
+                });
+            }
+            else {
+                perfLogger.start('GlyphGeometryBuilder.buildInstancedGeometry');
+            }
+            const tasks = [];
+            let totalVertexFloats = 0;
+            let totalNormalFloats = 0;
+            let totalIndexCount = 0;
+            let vertexCursor = 0; // vertex offset (not float offset)
+            const pushTask = (data, px, py, pz) => {
+                const vertexStart = vertexCursor;
+                tasks.push({ data, px, py, pz, vertexStart });
+                totalVertexFloats += data.vertices.length;
+                totalNormalFloats += data.normals.length;
+                totalIndexCount += data.indices.length;
+                vertexCursor += data.vertices.length / 3;
+                return vertexStart;
             };
             const glyphInfos = [];
             const planeBounds = {
@@ -3999,6 +4138,9 @@
             for (let lineIndex = 0; lineIndex < clustersByLine.length; lineIndex++) {
                 const line = clustersByLine[lineIndex];
                 for (const cluster of line) {
+                    const clusterX = cluster.position.x;
+                    const clusterY = cluster.position.y;
+                    const clusterZ = cluster.position.z;
                     const clusterGlyphContours = [];
                     for (const glyph of cluster.glyphs) {
                         clusterGlyphContours.push(this.getContoursForGlyph(glyph.g));
@@ -4039,7 +4181,7 @@
                     // Use glyph-level caching when separateGlyphs is set or when cluster contains colored text
                     const forceSeparate = separateGlyphs || clusterHasColoredGlyphs;
                     // Iterate over the geometric groups identified by BoundaryClusterer
-                    // logical groups (words) are now split into geometric sub-groups (e.g. "aa", "XX", "bb")
+                    // logical groups (words) split into geometric sub-groups (e.g. "aa", "XX", "bb")
                     for (const groupIndices of boundaryGroups) {
                         const isOverlappingGroup = groupIndices.length > 1;
                         const shouldCluster = isOverlappingGroup && !forceSeparate;
@@ -4071,16 +4213,19 @@
                             // Calculate the absolute position of this sub-cluster based on its first glyph
                             // (since the cached geometry is relative to that first glyph)
                             const firstGlyphInGroup = subClusterGlyphs[0];
-                            const groupPosition = new Vec3(cluster.position.x + (firstGlyphInGroup.x ?? 0), cluster.position.y + (firstGlyphInGroup.y ?? 0), cluster.position.z);
-                            const vertexOffset = vertexPos / 3;
-                            appendGeometryToBuffers(cachedCluster, groupPosition, vertexOffset);
+                            const groupPosX = clusterX + (firstGlyphInGroup.x ?? 0);
+                            const groupPosY = clusterY + (firstGlyphInGroup.y ?? 0);
+                            const groupPosZ = clusterZ;
+                            const vertexStart = pushTask(cachedCluster, groupPosX, groupPosY, groupPosZ);
                             const clusterVertexCount = cachedCluster.vertices.length / 3;
                             for (let i = 0; i < groupIndices.length; i++) {
                                 const originalIndex = groupIndices[i];
                                 const glyph = cluster.glyphs[originalIndex];
                                 const glyphContours = clusterGlyphContours[originalIndex];
-                                const absoluteGlyphPosition = new Vec3(cluster.position.x + (glyph.x ?? 0), cluster.position.y + (glyph.y ?? 0), cluster.position.z);
-                                const glyphInfo = this.createGlyphInfo(glyph, vertexOffset, clusterVertexCount, absoluteGlyphPosition, glyphContours, depth);
+                                const glyphPosX = clusterX + (glyph.x ?? 0);
+                                const glyphPosY = clusterY + (glyph.y ?? 0);
+                                const glyphPosZ = clusterZ;
+                                const glyphInfo = this.createGlyphInfo(glyph, vertexStart, clusterVertexCount, glyphPosX, glyphPosY, glyphPosZ, glyphContours, depth);
                                 glyphInfos.push(glyphInfo);
                                 this.updatePlaneBounds(glyphInfo.bounds, planeBounds);
                             }
@@ -4090,24 +4235,26 @@
                             for (const i of groupIndices) {
                                 const glyph = cluster.glyphs[i];
                                 const glyphContours = clusterGlyphContours[i];
-                                const glyphPosition = new Vec3(cluster.position.x + (glyph.x ?? 0), cluster.position.y + (glyph.y ?? 0), cluster.position.z);
+                                const glyphPosX = clusterX + (glyph.x ?? 0);
+                                const glyphPosY = clusterY + (glyph.y ?? 0);
+                                const glyphPosZ = clusterZ;
                                 // Skip glyphs with no paths (spaces, zero-width characters, etc.)
                                 if (glyphContours.paths.length === 0) {
-                                    const glyphInfo = this.createGlyphInfo(glyph, 0, 0, glyphPosition, glyphContours, depth);
+                                    const glyphInfo = this.createGlyphInfo(glyph, 0, 0, glyphPosX, glyphPosY, glyphPosZ, glyphContours, depth);
                                     glyphInfos.push(glyphInfo);
                                     continue;
                                 }
-                                let cachedGlyph = this.cache.get(getGlyphCacheKey(this.cacheKeyPrefix, glyph.g, depth, removeOverlaps));
+                                const glyphCacheKey = getGlyphCacheKey(this.cacheKeyPrefix, glyph.g, depth, removeOverlaps);
+                                let cachedGlyph = this.cache.get(glyphCacheKey);
                                 if (!cachedGlyph) {
                                     cachedGlyph = this.tessellateGlyph(glyphContours, depth, removeOverlaps, isCFF);
-                                    this.cache.set(getGlyphCacheKey(this.cacheKeyPrefix, glyph.g, depth, removeOverlaps), cachedGlyph);
+                                    this.cache.set(glyphCacheKey, cachedGlyph);
                                 }
                                 else {
                                     cachedGlyph.useCount++;
                                 }
-                                const vertexOffset = vertexPos / 3;
-                                appendGeometryToBuffers(cachedGlyph, glyphPosition, vertexOffset);
-                                const glyphInfo = this.createGlyphInfo(glyph, vertexOffset, cachedGlyph.vertices.length / 3, glyphPosition, glyphContours, depth);
+                                const vertexStart = pushTask(cachedGlyph, glyphPosX, glyphPosY, glyphPosZ);
+                                const glyphInfo = this.createGlyphInfo(glyph, vertexStart, cachedGlyph.vertices.length / 3, glyphPosX, glyphPosY, glyphPosZ, glyphContours, depth);
                                 glyphInfos.push(glyphInfo);
                                 this.updatePlaneBounds(glyphInfo.bounds, planeBounds);
                             }
@@ -4115,10 +4262,33 @@
                     }
                 }
             }
-            // Slice to used lengths (avoid returning oversized buffers)
-            const vertexArray = vertexBuffer.slice(0, vertexPos);
-            const normalArray = normalBuffer.slice(0, normalPos);
-            const indexArray = indexBuffer.slice(0, indexPos);
+            // Allocate exact-sized buffers and fill once
+            const vertexArray = new Float32Array(totalVertexFloats);
+            const normalArray = new Float32Array(totalNormalFloats);
+            const indexArray = new Uint32Array(totalIndexCount);
+            let vertexPos = 0; // float index (multiple of 3)
+            let normalPos = 0; // float index (multiple of 3)
+            let indexPos = 0; // index count
+            for (let t = 0; t < tasks.length; t++) {
+                const task = tasks[t];
+                const v = task.data.vertices;
+                const n = task.data.normals;
+                const idx = task.data.indices;
+                const px = task.px;
+                const py = task.py;
+                const pz = task.pz;
+                for (let j = 0; j < v.length; j += 3) {
+                    vertexArray[vertexPos++] = v[j] + px;
+                    vertexArray[vertexPos++] = v[j + 1] + py;
+                    vertexArray[vertexPos++] = v[j + 2] + pz;
+                }
+                normalArray.set(n, normalPos);
+                normalPos += n.length;
+                const vertexStart = task.vertexStart;
+                for (let j = 0; j < idx.length; j++) {
+                    indexArray[indexPos++] = idx[j] + vertexStart;
+                }
+            }
             perfLogger.end('GlyphGeometryBuilder.buildInstancedGeometry');
             return {
                 vertices: vertexArray,
@@ -4143,7 +4313,7 @@
             const roundedDepth = Math.round(depth * 1000) / 1000;
             return `${this.cacheKeyPrefix}_${ids}_${roundedDepth}_${removeOverlaps}`;
         }
-        createGlyphInfo(glyph, vertexStart, vertexCount, position, contours, depth) {
+        createGlyphInfo(glyph, vertexStart, vertexCount, positionX, positionY, positionZ, contours, depth) {
             return {
                 textIndex: glyph.absoluteTextIndex,
                 lineIndex: glyph.lineIndex,
@@ -4151,19 +4321,30 @@
                 vertexCount,
                 bounds: {
                     min: {
-                        x: contours.bounds.min.x + position.x,
-                        y: contours.bounds.min.y + position.y,
-                        z: position.z
+                        x: contours.bounds.min.x + positionX,
+                        y: contours.bounds.min.y + positionY,
+                        z: positionZ
                     },
                     max: {
-                        x: contours.bounds.max.x + position.x,
-                        y: contours.bounds.max.y + position.y,
-                        z: position.z + depth
+                        x: contours.bounds.max.x + positionX,
+                        y: contours.bounds.max.y + positionY,
+                        z: positionZ + depth
                     }
                 }
             };
         }
         getContoursForGlyph(glyphId) {
+            // Fast path: skip HarfBuzz draw for known-empty glyphs (spaces, zero-width, etc)
+            if (this.emptyGlyphs.has(glyphId)) {
+                return {
+                    glyphId,
+                    paths: [],
+                    bounds: {
+                        min: { x: 0, y: 0 },
+                        max: { x: 0, y: 0 }
+                    }
+                };
+            }
             const key = `${this.cacheKeyPrefix}_${glyphId}`;
             const cached = this.contourCache.get(key);
             if (cached) {
@@ -4184,11 +4365,15 @@
                     max: { x: 0, y: 0 }
                 }
             };
+            // Mark glyph as empty for future fast-path
+            if (contours.paths.length === 0) {
+                this.emptyGlyphs.add(glyphId);
+            }
             this.contourCache.set(key, contours);
             return contours;
         }
         tessellateGlyphCluster(paths, depth, isCFF) {
-            const processedGeometry = this.tessellator.process(paths, true, isCFF);
+            const processedGeometry = this.tessellator.process(paths, true, isCFF, depth !== 0);
             return this.extrudeAndPackage(processedGeometry, depth);
         }
         extrudeAndPackage(processedGeometry, depth) {
@@ -4236,7 +4421,7 @@
                 glyphId: glyphContours.glyphId,
                 pathCount: glyphContours.paths.length
             });
-            const processedGeometry = this.tessellator.process(glyphContours.paths, removeOverlaps, isCFF);
+            const processedGeometry = this.tessellator.process(glyphContours.paths, removeOverlaps, isCFF, depth !== 0);
             perfLogger.end('GlyphGeometryBuilder.tessellateGlyph');
             return this.extrudeAndPackage(processedGeometry, depth);
         }
@@ -4306,8 +4491,11 @@
             const clusters = [];
             let currentClusterGlyphs = [];
             let currentClusterText = '';
-            let clusterStartPosition = new Vec3();
-            let cursor = new Vec3(lineInfo.xOffset, -lineIndex * scaledLineHeight, 0);
+            let clusterStartX = 0;
+            let clusterStartY = 0;
+            let cursorX = lineInfo.xOffset;
+            let cursorY = -lineIndex * scaledLineHeight;
+            const cursorZ = 0;
             // Apply letter spacing after each glyph to match width measurements used during line breaking
             const letterSpacingFU = letterSpacing * this.loadedFont.upem;
             const spaceAdjustment = this.calculateSpaceAdjustment(lineInfo, align, letterSpacing);
@@ -4332,31 +4520,31 @@
                         clusters.push({
                             text: currentClusterText,
                             glyphs: currentClusterGlyphs,
-                            position: clusterStartPosition.clone()
+                            position: new Vec3(clusterStartX, clusterStartY, cursorZ)
                         });
                         currentClusterGlyphs = [];
                         currentClusterText = '';
                     }
                 }
-                const absoluteGlyphPosition = cursor
-                    .clone()
-                    .add(new Vec3(glyph.dx, glyph.dy, 0));
+                const absoluteGlyphX = cursorX + glyph.dx;
+                const absoluteGlyphY = cursorY + glyph.dy;
                 if (!isWhitespace) {
                     if (currentClusterGlyphs.length === 0) {
-                        clusterStartPosition.copy(absoluteGlyphPosition);
+                        clusterStartX = absoluteGlyphX;
+                        clusterStartY = absoluteGlyphY;
                     }
-                    glyph.x = absoluteGlyphPosition.x - clusterStartPosition.x;
-                    glyph.y = absoluteGlyphPosition.y - clusterStartPosition.y;
+                    glyph.x = absoluteGlyphX - clusterStartX;
+                    glyph.y = absoluteGlyphY - clusterStartY;
                     currentClusterGlyphs.push(glyph);
                     currentClusterText += lineInfo.text[glyph.cl];
                 }
-                cursor.x += glyph.ax;
-                cursor.y += glyph.ay;
+                cursorX += glyph.ax;
+                cursorY += glyph.ay;
                 if (letterSpacingFU !== 0 && i < glyphInfos.length - 1) {
-                    cursor.x += letterSpacingFU;
+                    cursorX += letterSpacingFU;
                 }
                 if (isWhitespace) {
-                    cursor.x += spaceAdjustment;
+                    cursorX += spaceAdjustment;
                 }
                 // CJK glue adjustment (must match exactly where LineBreak adds glue)
                 if (cjkAdjustment !== 0 && i < glyphInfos.length - 1 && !isWhitespace) {
@@ -4377,7 +4565,7 @@
                             shouldApply = false;
                         }
                         if (shouldApply) {
-                            cursor.x += cjkAdjustment;
+                            cursorX += cjkAdjustment;
                         }
                     }
                 }
@@ -4386,7 +4574,7 @@
                 clusters.push({
                     text: currentClusterText,
                     glyphs: currentClusterGlyphs,
-                    position: clusterStartPosition.clone()
+                    position: new Vec3(clusterStartX, clusterStartY, cursorZ)
                 });
             }
             return clusters;
@@ -5213,9 +5401,8 @@
             const loadedFont = await Text.resolveFont(options);
             const text = new Text();
             text.setLoadedFont(loadedFont);
-            // Initial creation
-            const { font, maxCacheSizeMB, ...geometryOptions } = options;
-            const result = await text.createGeometry(geometryOptions);
+            // Pass full options so createGeometry honors maxCacheSizeMB etc
+            const result = await text.createGeometry(options);
             // Recursive update function
             const update = async (newOptions) => {
                 // Merge options - preserve font from original options if not provided
@@ -5237,8 +5424,7 @@
                 }
                 // Update closure options for next time
                 options = mergedOptions;
-                const { font, maxCacheSizeMB, ...currentGeometryOptions } = options;
-                const newResult = await text.createGeometry(currentGeometryOptions);
+                const newResult = await text.createGeometry(options);
                 return {
                     ...newResult,
                     getLoadedFont: () => text.getLoadedFont(),
@@ -5663,7 +5849,7 @@
             if (!this.textLayout) {
                 this.textLayout = new TextLayout(this.loadedFont);
             }
-            const alignmentResult = this.textLayout.applyAlignment(vertices, {
+            const alignmentResult = this.textLayout.computeAlignmentOffset({
                 width,
                 align,
                 planeBounds
@@ -5672,9 +5858,19 @@
             planeBounds.min.x = alignmentResult.adjustedBounds.min.x;
             planeBounds.max.x = alignmentResult.adjustedBounds.max.x;
             const finalScale = size / this.loadedFont.upem;
+            const offsetScaled = offset * finalScale;
             // Scale vertices only (normals are unit vectors, don't scale)
-            for (let i = 0; i < vertices.length; i++) {
-                vertices[i] *= finalScale;
+            if (offsetScaled === 0) {
+                for (let i = 0; i < vertices.length; i++) {
+                    vertices[i] *= finalScale;
+                }
+            }
+            else {
+                for (let i = 0; i < vertices.length; i += 3) {
+                    vertices[i] = vertices[i] * finalScale + offsetScaled;
+                    vertices[i + 1] *= finalScale;
+                    vertices[i + 2] *= finalScale;
+                }
             }
             planeBounds.min.x *= finalScale;
             planeBounds.min.y *= finalScale;
@@ -5684,14 +5880,10 @@
             planeBounds.max.z *= finalScale;
             for (let i = 0; i < glyphInfoArray.length; i++) {
                 const glyphInfo = glyphInfoArray[i];
-                if (offset !== 0) {
-                    glyphInfo.bounds.min.x += offset;
-                    glyphInfo.bounds.max.x += offset;
-                }
-                glyphInfo.bounds.min.x *= finalScale;
+                glyphInfo.bounds.min.x = glyphInfo.bounds.min.x * finalScale + offsetScaled;
                 glyphInfo.bounds.min.y *= finalScale;
                 glyphInfo.bounds.min.z *= finalScale;
-                glyphInfo.bounds.max.x *= finalScale;
+                glyphInfo.bounds.max.x = glyphInfo.bounds.max.x * finalScale + offsetScaled;
                 glyphInfo.bounds.max.y *= finalScale;
                 glyphInfo.bounds.max.z *= finalScale;
             }