three-text 0.2.5 → 0.2.7

package/dist/index.umd.js

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.2.5
+ * three-text v0.2.7
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify
@@ -27,7 +27,7 @@
         }
         return false;
     })();
-    class DebugLogger {
+    class Logger {
         warn(message, ...args) {
             console.warn(message, ...args);
         }
@@ -38,7 +38,7 @@
             isLogEnabled && console.log(message, ...args);
         }
     }
-    const debugLogger = new DebugLogger();
+    const logger = new Logger();
 
     class PerformanceLogger {
         constructor() {
@@ -64,7 +64,7 @@
             const endTime = performance.now();
             const startTime = this.activeTimers.get(name);
             if (startTime === undefined) {
-                debugLogger.warn(`Performance timer "${name}" was not started`);
+                logger.warn(`Performance timer "${name}" was not started`);
                 return null;
             }
             const duration = endTime - startTime;
@@ -127,6 +127,9 @@
             this.metrics.length = 0;
             this.activeTimers.clear();
         }
+        reset() {
+            this.clear();
+        }
         time(name, fn, metadata) {
             if (!isLogEnabled)
                 return fn();
@@ -326,6 +329,8 @@
             const filteredPoints = hyphenPoints.filter((pos) => pos >= lefthyphenmin && word.length - pos >= righthyphenmin);
             return filteredPoints;
         }
+        // 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) {
             const items = [];
@@ -567,7 +572,7 @@
             let useHyphenation = hyphenate;
             if (useHyphenation &&
                 (!hyphenationPatterns || !hyphenationPatterns[language])) {
-                debugLogger.warn(`Hyphenation patterns for ${language} not available`);
+                logger.warn(`Hyphenation patterns for ${language} not available`);
                 useHyphenation = false;
             }
             // Calculate initial emergency stretch (TeX default: 0)
@@ -1182,12 +1187,43 @@
         }
     }
 
+    // Convert feature objects to HarfBuzz comma-separated format
+    function convertFontFeaturesToString(features) {
+        if (!features || Object.keys(features).length === 0) {
+            return undefined;
+        }
+        const featureStrings = [];
+        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.`);
+                continue;
+            }
+            if (value === false || value === 0) {
+                featureStrings.push(`${tag}=0`);
+            }
+            else if (value === true || value === 1) {
+                featureStrings.push(tag);
+            }
+            else if (typeof value === 'number' && value > 1) {
+                featureStrings.push(`${tag}=${Math.floor(value)}`);
+            }
+            else {
+                logger.warn(`Invalid value for feature "${tag}": ${value}. Expected boolean or positive number.`);
+            }
+        }
+        return featureStrings.length > 0 ? featureStrings.join(',') : undefined;
+    }
+
     class TextMeasurer {
+        // Measures text width including letter spacing
+        // Letter spacing is added uniformly after each glyph during measurement,
+        // so the widths given to the line-breaking algorithm already account for tracking
         static measureTextWidth(loadedFont, text, letterSpacing = 0) {
             const buffer = loadedFont.hb.createBuffer();
             buffer.addText(text);
             buffer.guessSegmentProperties();
-            loadedFont.hb.shape(loadedFont.font, buffer);
+            const featuresString = convertFontFeaturesToString(loadedFont.fontFeatures);
+            loadedFont.hb.shape(loadedFont.font, buffer, featuresString);
             const glyphInfos = buffer.json(loadedFont.font);
             const letterSpacingInFontUnits = letterSpacing * loadedFont.upem;
             // Calculate total advance width with letter spacing
@@ -1211,6 +1247,8 @@
             const { text, width, align, direction, hyphenate, language, respectExistingBreaks, tolerance, pretolerance, emergencyStretch, autoEmergencyStretch, hyphenationPatterns, lefthyphenmin, righthyphenmin, linepenalty, adjdemerits, hyphenpenalty, exhyphenpenalty, doublehyphendemerits, looseness, disableSingleWordDetection, letterSpacing } = options;
             let lines;
             if (width) {
+                // Line breaking uses a measureText function that already includes letterSpacing,
+                // so widths passed into LineBreak.breakText account for tracking
                 lines = LineBreak.breakText({
                     text,
                     width,
@@ -1234,7 +1272,8 @@
                     looseness,
                     disableSingleWordDetection,
                     unitsPerEm: this.loadedFont.upem,
-                    measureText: (textToMeasure) => TextMeasurer.measureTextWidth(this.loadedFont, textToMeasure, letterSpacing)
+                    measureText: (textToMeasure) => TextMeasurer.measureTextWidth(this.loadedFont, textToMeasure, letterSpacing // Letter spacing included in width measurements
+                    )
                 });
             }
             else {
@@ -1288,6 +1327,17 @@
     const FONT_SIGNATURE_TRUE_TYPE_COLLECTION = 0x74746366; // 'ttcf'
     const FONT_SIGNATURE_WOFF = 0x774f4646; // 'wOFF'
     const FONT_SIGNATURE_WOFF2 = 0x774f4632; // 'wOF2'
+    // Table Tags
+    const TABLE_TAG_HEAD = 0x68656164; // 'head'
+    const TABLE_TAG_HHEA = 0x68686561; // 'hhea'
+    const TABLE_TAG_OS2 = 0x4f532f32; // 'OS/2'
+    const TABLE_TAG_FVAR = 0x66766172; // 'fvar'
+    const TABLE_TAG_STAT = 0x53544154; // 'STAT'
+    const TABLE_TAG_NAME = 0x6e616d65; // 'name'
+    const TABLE_TAG_CFF = 0x43464620; // 'CFF '
+    const TABLE_TAG_CFF2 = 0x43464632; // 'CFF2'
+    const TABLE_TAG_GSUB = 0x47535542; // 'GSUB'
+    const TABLE_TAG_GPOS = 0x47504f53; // 'GPOS'
 
     class FontMetadataExtractor {
         static extractMetadata(fontBuffer) {
@@ -1304,7 +1354,6 @@
             if (!validSignatures.includes(sfntVersion)) {
                 throw new Error(`Invalid font format. Expected TrueType or OpenType, got signature: 0x${sfntVersion.toString(16)}`);
             }
-            const buffer = new Uint8Array(fontBuffer);
             const numTables = view.getUint16(4); // OpenType header - number of tables is at offset 4
             let isCFF = false;
             let headTableOffset = 0;
@@ -1314,30 +1363,28 @@
             let nameTableOffset = 0;
             let fvarTableOffset = 0;
             for (let i = 0; i < numTables; i++) {
-                const tag = new TextDecoder().decode(buffer.slice(12 + i * 16, 12 + i * 16 + 4));
-                if (tag === 'CFF ') {
-                    isCFF = true;
-                }
-                else if (tag === 'CFF2') {
+                const offset = 12 + i * 16;
+                const tag = view.getUint32(offset);
+                if (tag === TABLE_TAG_CFF || tag === TABLE_TAG_CFF2) {
                     isCFF = true;
                 }
-                if (tag === 'head') {
-                    headTableOffset = view.getUint32(12 + i * 16 + 8);
+                else if (tag === TABLE_TAG_HEAD) {
+                    headTableOffset = view.getUint32(offset + 8);
                 }
-                if (tag === 'hhea') {
-                    hheaTableOffset = view.getUint32(12 + i * 16 + 8);
+                else if (tag === TABLE_TAG_HHEA) {
+                    hheaTableOffset = view.getUint32(offset + 8);
                 }
-                if (tag === 'OS/2') {
-                    os2TableOffset = view.getUint32(12 + i * 16 + 8);
+                else if (tag === TABLE_TAG_OS2) {
+                    os2TableOffset = view.getUint32(offset + 8);
                 }
-                if (tag === 'fvar') {
-                    fvarTableOffset = view.getUint32(12 + i * 16 + 8);
+                else if (tag === TABLE_TAG_FVAR) {
+                    fvarTableOffset = view.getUint32(offset + 8);
                 }
-                if (tag === 'STAT') {
-                    statTableOffset = view.getUint32(12 + i * 16 + 8);
+                else if (tag === TABLE_TAG_STAT) {
+                    statTableOffset = view.getUint32(offset + 8);
                 }
-                if (tag === 'name') {
-                    nameTableOffset = view.getUint32(12 + i * 16 + 8);
+                else if (tag === TABLE_TAG_NAME) {
+                    nameTableOffset = view.getUint32(offset + 8);
                 }
             }
             const unitsPerEm = headTableOffset
@@ -1380,6 +1427,88 @@
                 axisNames
             };
         }
+        static extractFeatureTags(fontBuffer) {
+            const view = new DataView(fontBuffer);
+            const numTables = view.getUint16(4);
+            let gsubTableOffset = 0;
+            let gposTableOffset = 0;
+            let nameTableOffset = 0;
+            for (let i = 0; i < numTables; i++) {
+                const offset = 12 + i * 16;
+                const tag = view.getUint32(offset);
+                if (tag === TABLE_TAG_GSUB) {
+                    gsubTableOffset = view.getUint32(offset + 8);
+                }
+                else if (tag === TABLE_TAG_GPOS) {
+                    gposTableOffset = view.getUint32(offset + 8);
+                }
+                else if (tag === TABLE_TAG_NAME) {
+                    nameTableOffset = view.getUint32(offset + 8);
+                }
+            }
+            const features = new Set();
+            const featureNames = {};
+            try {
+                if (gsubTableOffset) {
+                    const gsubData = this.extractFeatureDataFromTable(view, gsubTableOffset, nameTableOffset);
+                    gsubData.features.forEach(f => features.add(f));
+                    Object.assign(featureNames, gsubData.names);
+                }
+                if (gposTableOffset) {
+                    const gposData = this.extractFeatureDataFromTable(view, gposTableOffset, nameTableOffset);
+                    gposData.features.forEach(f => features.add(f));
+                    Object.assign(featureNames, gposData.names);
+                }
+            }
+            catch (e) {
+                return undefined;
+            }
+            const featureArray = Array.from(features).sort();
+            if (featureArray.length === 0)
+                return undefined;
+            return {
+                tags: featureArray,
+                names: Object.keys(featureNames).length > 0 ? featureNames : {}
+            };
+        }
+        static extractFeatureDataFromTable(view, tableOffset, nameTableOffset) {
+            const featureListOffset = view.getUint16(tableOffset + 6);
+            const featureListStart = tableOffset + featureListOffset;
+            const featureCount = view.getUint16(featureListStart);
+            const features = [];
+            const names = {};
+            for (let i = 0; i < featureCount; i++) {
+                const recordOffset = featureListStart + 2 + i * 6;
+                // Decode feature tag
+                const tag = String.fromCharCode(view.getUint8(recordOffset), view.getUint8(recordOffset + 1), view.getUint8(recordOffset + 2), view.getUint8(recordOffset + 3));
+                features.push(tag);
+                // Extract feature name for stylistic sets and character variants
+                if (/^(ss\d{2}|cv\d{2})$/.test(tag) && nameTableOffset) {
+                    const featureOffset = view.getUint16(recordOffset + 4);
+                    const featureTableStart = featureListStart + featureOffset;
+                    // Feature table structure:
+                    // uint16 FeatureParams offset
+                    // uint16 LookupCount
+                    // uint16[LookupCount] LookupListIndex
+                    const featureParamsOffset = view.getUint16(featureTableStart);
+                    // FeatureParams for ss features:
+                    // uint16 Version (should be 0)
+                    // uint16 UINameID
+                    if (featureParamsOffset !== 0) {
+                        const paramsStart = featureTableStart + featureParamsOffset;
+                        const version = view.getUint16(paramsStart);
+                        if (version === 0) {
+                            const nameID = view.getUint16(paramsStart + 2);
+                            const name = this.getNameFromNameTable(view, nameTableOffset, nameID);
+                            if (name) {
+                                names[tag] = name;
+                            }
+                        }
+                    }
+                }
+            }
+            return { features, names };
+        }
         static extractAxisNames(view, statOffset, nameOffset) {
             try {
                 // STAT table structure
@@ -1590,7 +1719,7 @@
                 const padding = (4 - (table.origLength % 4)) % 4;
                 sfntOffset += padding;
             }
-            debugLogger.log('WOFF font decompressed successfully');
+            logger.log('WOFF font decompressed successfully');
             return sfntData.buffer.slice(0, sfntOffset);
         }
         static async decompressZlib(compressedData) {
@@ -1619,7 +1748,7 @@
             // Check if this is a WOFF font and decompress if needed
             const format = WoffConverter.detectFormat(fontBuffer);
             if (format === 'woff') {
-                debugLogger.log('WOFF font detected, decompressing...');
+                logger.log('WOFF font detected, decompressing...');
                 fontBuffer = await WoffConverter.decompressWoff(fontBuffer);
             }
             else if (format === 'woff2') {
@@ -1657,6 +1786,7 @@
                         };
                     }
                 }
+                const featureData = FontMetadataExtractor.extractFeatureTags(fontBuffer);
                 return {
                     hb,
                     fontBlob,
@@ -1667,11 +1797,13 @@
                     metrics,
                     fontVariations,
                     isVariable,
-                    variationAxes
+                    variationAxes,
+                    availableFeatures: featureData?.tags,
+                    featureNames: featureData?.names
                 };
             }
             catch (error) {
-                debugLogger.error('Failed to load font:', error);
+                logger.error('Failed to load font:', error);
                 throw error;
             }
             finally {
@@ -1692,7 +1824,7 @@
                 }
             }
             catch (error) {
-                debugLogger.error('Error destroying font resources:', error);
+                logger.error('Error destroying font resources:', error);
             }
         }
     }
@@ -2096,7 +2228,7 @@
             if (valid.length === 0) {
                 return { triangles: { vertices: [], indices: [] }, contours: [] };
             }
-            debugLogger.log(`Tessellator: removeOverlaps=${removeOverlaps}, processing ${valid.length} paths`);
+            logger.log(`Tessellator: removeOverlaps=${removeOverlaps}, processing ${valid.length} paths`);
             return this.tessellate(valid, removeOverlaps, isCFF);
         }
         tessellate(paths, removeOverlaps, isCFF) {
@@ -2106,27 +2238,35 @@
                 : paths;
             let contours = this.pathsToContours(normalizedPaths);
             if (removeOverlaps) {
-                debugLogger.log('Two-pass: boundary extraction then triangulation');
+                logger.log('Two-pass: boundary extraction then triangulation');
                 // Extract boundaries to remove overlaps
+                perfLogger.start('Tessellator.boundaryPass', {
+                    contourCount: contours.length
+                });
                 const boundaryResult = this.performTessellation(contours, 'boundary');
+                perfLogger.end('Tessellator.boundaryPass');
                 if (!boundaryResult) {
-                    debugLogger.warn('libtess returned empty result from boundary pass');
+                    logger.warn('libtess returned empty result from boundary pass');
                     return { triangles: { vertices: [], indices: [] }, contours: [] };
                 }
                 // Convert boundary elements back to contours
                 contours = this.boundaryToContours(boundaryResult);
-                debugLogger.log(`Boundary pass created ${contours.length} contours. Starting triangulation pass.`);
+                logger.log(`Boundary pass created ${contours.length} contours. Starting triangulation pass.`);
             }
             else {
-                debugLogger.log(`Single-pass triangulation for ${isCFF ? 'CFF' : 'TTF'}`);
+                logger.log(`Single-pass triangulation for ${isCFF ? 'CFF' : 'TTF'}`);
             }
             // Triangulate the contours
+            perfLogger.start('Tessellator.triangulationPass', {
+                contourCount: contours.length
+            });
             const triangleResult = this.performTessellation(contours, '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';
-                debugLogger.warn(warning);
+                logger.warn(warning);
                 return { triangles: { vertices: [], indices: [] }, contours };
             }
             return {
@@ -2181,7 +2321,7 @@
                 return idx;
             });
             tess.gluTessCallback(libtess_minExports.gluEnum.GLU_TESS_ERROR, (errno) => {
-                debugLogger.warn(`libtess error: ${errno}`);
+                logger.warn(`libtess error: ${errno}`);
             });
             tess.gluTessNormal(0, 0, 1);
             tess.gluTessBeginPolygon(null);
@@ -2308,10 +2448,16 @@
     class BoundaryClusterer {
         constructor() { }
         cluster(glyphContoursList, positions) {
+            perfLogger.start('BoundaryClusterer.cluster', {
+                glyphCount: glyphContoursList.length
+            });
             if (glyphContoursList.length === 0) {
+                perfLogger.end('BoundaryClusterer.cluster');
                 return [];
             }
-            return this.clusterSweepLine(glyphContoursList, positions);
+            const result = this.clusterSweepLine(glyphContoursList, positions);
+            perfLogger.end('BoundaryClusterer.cluster');
+            return result;
         }
         clusterSweepLine(glyphContoursList, positions) {
             const n = glyphContoursList.length;
@@ -2952,6 +3098,11 @@
             this.currentGlyphBounds.max.set(-Infinity, -Infinity);
             // Record position for this glyph
             this.glyphPositions.push(this.currentPosition.clone());
+            // Time polygonization + path optimization per glyph
+            perfLogger.start('Glyph.polygonizeAndOptimize', {
+                glyphId,
+                textIndex
+            });
         }
         finishGlyph() {
             if (this.currentPath) {
@@ -2975,6 +3126,8 @@
                 // Track textIndex separately
                 this.glyphTextIndices.push(this.currentTextIndex);
             }
+            // Stop timing for this glyph (even if it ended up empty)
+            perfLogger.end('Glyph.polygonizeAndOptimize');
             this.currentGlyphPaths = [];
         }
         onMoveTo(x, y) {
@@ -3203,12 +3356,190 @@
                 }
             }
             catch (error) {
-                debugLogger.warn('Error destroying draw callbacks:', error);
+                logger.warn('Error destroying draw callbacks:', error);
             }
             this.collector = undefined;
         }
     }
 
+    // Generic LRU (Least Recently Used) cache with optional memory-based eviction
+    class LRUCache {
+        constructor(options = {}) {
+            this.cache = new Map();
+            this.head = null;
+            this.tail = null;
+            this.stats = {
+                hits: 0,
+                misses: 0,
+                evictions: 0,
+                size: 0,
+                memoryUsage: 0
+            };
+            this.options = {
+                maxEntries: options.maxEntries ?? Infinity,
+                maxMemoryBytes: options.maxMemoryBytes ?? Infinity,
+                calculateSize: options.calculateSize ?? (() => 0),
+                onEvict: options.onEvict
+            };
+        }
+        get(key) {
+            const node = this.cache.get(key);
+            if (node) {
+                this.stats.hits++;
+                this.moveToHead(node);
+                return node.value;
+            }
+            else {
+                this.stats.misses++;
+                return undefined;
+            }
+        }
+        has(key) {
+            return this.cache.has(key);
+        }
+        set(key, value) {
+            // If key already exists, update it
+            const existingNode = this.cache.get(key);
+            if (existingNode) {
+                const oldSize = this.options.calculateSize(existingNode.value);
+                const newSize = this.options.calculateSize(value);
+                this.stats.memoryUsage = this.stats.memoryUsage - oldSize + newSize;
+                existingNode.value = value;
+                this.moveToHead(existingNode);
+                return;
+            }
+            const size = this.options.calculateSize(value);
+            // Evict entries if we exceed limits
+            this.evictIfNeeded(size);
+            // Create new node
+            const node = {
+                key,
+                value,
+                prev: null,
+                next: null
+            };
+            this.cache.set(key, node);
+            this.addToHead(node);
+            this.stats.size = this.cache.size;
+            this.stats.memoryUsage += size;
+        }
+        delete(key) {
+            const node = this.cache.get(key);
+            if (!node)
+                return false;
+            const size = this.options.calculateSize(node.value);
+            this.removeNode(node);
+            this.cache.delete(key);
+            this.stats.size = this.cache.size;
+            this.stats.memoryUsage -= size;
+            if (this.options.onEvict) {
+                this.options.onEvict(key, node.value);
+            }
+            return true;
+        }
+        clear() {
+            if (this.options.onEvict) {
+                for (const [key, node] of this.cache) {
+                    this.options.onEvict(key, node.value);
+                }
+            }
+            this.cache.clear();
+            this.head = null;
+            this.tail = null;
+            this.stats = {
+                hits: 0,
+                misses: 0,
+                evictions: 0,
+                size: 0,
+                memoryUsage: 0
+            };
+        }
+        getStats() {
+            const total = this.stats.hits + this.stats.misses;
+            const hitRate = total > 0 ? (this.stats.hits / total) * 100 : 0;
+            const memoryUsageMB = this.stats.memoryUsage / (1024 * 1024);
+            return {
+                ...this.stats,
+                hitRate,
+                memoryUsageMB
+            };
+        }
+        keys() {
+            const keys = [];
+            let current = this.head;
+            while (current) {
+                keys.push(current.key);
+                current = current.next;
+            }
+            return keys;
+        }
+        get size() {
+            return this.cache.size;
+        }
+        evictIfNeeded(requiredSize) {
+            // Evict by entry count
+            while (this.cache.size >= this.options.maxEntries && this.tail) {
+                this.evictTail();
+            }
+            // Evict by memory usage
+            if (this.options.maxMemoryBytes < Infinity) {
+                while (this.tail &&
+                    this.stats.memoryUsage + requiredSize > this.options.maxMemoryBytes) {
+                    this.evictTail();
+                }
+            }
+        }
+        evictTail() {
+            if (!this.tail)
+                return;
+            const nodeToRemove = this.tail;
+            const size = this.options.calculateSize(nodeToRemove.value);
+            this.removeTail();
+            this.cache.delete(nodeToRemove.key);
+            this.stats.size = this.cache.size;
+            this.stats.memoryUsage -= size;
+            this.stats.evictions++;
+            if (this.options.onEvict) {
+                this.options.onEvict(nodeToRemove.key, nodeToRemove.value);
+            }
+        }
+        addToHead(node) {
+            if (!this.head) {
+                this.head = this.tail = node;
+            }
+            else {
+                node.next = this.head;
+                this.head.prev = node;
+                this.head = node;
+            }
+        }
+        removeNode(node) {
+            if (node.prev) {
+                node.prev.next = node.next;
+            }
+            else {
+                this.head = node.next;
+            }
+            if (node.next) {
+                node.next.prev = node.prev;
+            }
+            else {
+                this.tail = node.prev;
+            }
+        }
+        removeTail() {
+            if (this.tail) {
+                this.removeNode(this.tail);
+            }
+        }
+        moveToHead(node) {
+            if (node === this.head)
+                return;
+            this.removeNode(node);
+            this.addToHead(node);
+        }
+    }
+
     class GlyphGeometryBuilder {
         constructor(cache, loadedFont) {
             this.fontId = 'default';
@@ -3221,6 +3552,16 @@
             this.collector = new GlyphContourCollector();
             this.drawCallbacks = new DrawCallbackHandler();
             this.drawCallbacks.createDrawFuncs(this.loadedFont, this.collector);
+            this.contourCache = new LRUCache({
+                maxEntries: 1000,
+                calculateSize: (contours) => {
+                    let size = 0;
+                    for (const path of contours.paths) {
+                        size += path.points.length * 16; // Vec2 = 2 floats * 8 bytes
+                    }
+                    return size + 64; // bounds overhead
+                }
+            });
         }
         getOptimizationStats() {
             return this.collector.getOptimizationStats();
@@ -3365,30 +3706,37 @@
             };
         }
         getContoursForGlyph(glyphId) {
+            const cached = this.contourCache.get(glyphId);
+            if (cached) {
+                return cached;
+            }
             this.collector.reset();
             this.collector.beginGlyph(glyphId, 0);
             this.loadedFont.module.exports.hb_font_draw_glyph(this.loadedFont.font.ptr, glyphId, this.drawCallbacks.getDrawFuncsPtr(), 0);
             this.collector.finishGlyph();
             const collected = this.collector.getCollectedGlyphs()[0];
-            // Return empty contours for glyphs with no paths (e.g., space, zero-width characters)
-            if (!collected) {
-                return {
-                    glyphId,
-                    paths: [],
-                    bounds: {
-                        min: { x: 0, y: 0 },
-                        max: { x: 0, y: 0 }
-                    }
-                };
-            }
-            return collected;
+            const contours = collected || {
+                glyphId,
+                paths: [],
+                bounds: {
+                    min: { x: 0, y: 0 },
+                    max: { x: 0, y: 0 }
+                }
+            };
+            this.contourCache.set(glyphId, contours);
+            return contours;
         }
         tessellateGlyphCluster(paths, depth, isCFF) {
             const processedGeometry = this.tessellator.process(paths, true, isCFF);
             return this.extrudeAndPackage(processedGeometry, depth);
         }
         extrudeAndPackage(processedGeometry, depth) {
+            perfLogger.start('Extruder.extrude', {
+                depth,
+                upem: this.loadedFont.upem
+            });
             const extrudedResult = this.extruder.extrude(processedGeometry, depth, this.loadedFont.upem);
+            perfLogger.end('Extruder.extrude');
             // Compute bounding box from vertices
             const vertices = extrudedResult.vertices;
             let minX = Infinity, minY = Infinity, minZ = Infinity;
@@ -3430,6 +3778,7 @@
                 pathCount: glyphContours.paths.length
             });
             const processedGeometry = this.tessellator.process(glyphContours.paths, removeOverlaps, isCFF);
+            perfLogger.end('GlyphGeometryBuilder.tessellateGlyph');
             return this.extrudeAndPackage(processedGeometry, depth);
         }
         updatePlaneBounds(glyphBounds, planeBounds) {
@@ -3493,7 +3842,8 @@
             }
             buffer.addText(lineInfo.text);
             buffer.guessSegmentProperties();
-            this.loadedFont.hb.shape(this.loadedFont.font, buffer);
+            const featuresString = convertFontFeaturesToString(this.loadedFont.fontFeatures);
+            this.loadedFont.hb.shape(this.loadedFont.font, buffer, featuresString);
             const glyphInfos = buffer.json(this.loadedFont.font);
             buffer.destroy();
             const clusters = [];
@@ -3501,6 +3851,7 @@
             let currentClusterText = '';
             let clusterStartPosition = new Vec3();
             let cursor = new Vec3(lineInfo.xOffset, -lineIndex * scaledLineHeight, 0);
+            // Apply letter spacing between glyphs (must match what was used in width measurements)
             const letterSpacingFU = letterSpacing * this.loadedFont.upem;
             const spaceAdjustment = this.calculateSpaceAdjustment(lineInfo, align, letterSpacing);
             for (let i = 0; i < glyphInfos.length; i++) {
@@ -3572,12 +3923,10 @@
                 const stretchFactor = SPACE_STRETCH_RATIO;
                 const shrinkFactor = SPACE_SHRINK_RATIO;
                 if (lineInfo.adjustmentRatio > 0) {
-                    spaceAdjustment =
-                        lineInfo.adjustmentRatio * width * stretchFactor;
+                    spaceAdjustment = lineInfo.adjustmentRatio * width * stretchFactor;
                 }
                 else if (lineInfo.adjustmentRatio < 0) {
-                    spaceAdjustment =
-                        lineInfo.adjustmentRatio * width * shrinkFactor;
+                    spaceAdjustment = lineInfo.adjustmentRatio * width * shrinkFactor;
                 }
             }
             return spaceAdjustment;
@@ -4502,12 +4851,16 @@
             const baseFontKey = typeof options.font === 'string'
                 ? options.font
                 : `buffer-${Text.generateFontContentHash(options.font)}`;
-            const fontKey = options.fontVariations
-                ? `${baseFontKey}_${JSON.stringify(options.fontVariations)}`
-                : baseFontKey;
+            let fontKey = baseFontKey;
+            if (options.fontVariations) {
+                fontKey += `_var_${JSON.stringify(options.fontVariations)}`;
+            }
+            if (options.fontFeatures) {
+                fontKey += `_feat_${JSON.stringify(options.fontFeatures)}`;
+            }
             let loadedFont = Text.fontCache.get(fontKey);
             if (!loadedFont) {
-                loadedFont = await Text.loadAndCacheFont(fontKey, options.font, options.fontVariations);
+                loadedFont = await Text.loadAndCacheFont(fontKey, options.font, options.fontVariations, options.fontFeatures);
             }
             const text = new Text({ maxCacheSizeMB: options.maxCacheSizeMB });
             text.setLoadedFont(loadedFont);
@@ -4521,12 +4874,11 @@
                 measureTextWidth: (textString, letterSpacing) => text.measureTextWidth(textString, letterSpacing)
             };
         }
-        static async loadAndCacheFont(fontKey, font, fontVariations) {
+        static async loadAndCacheFont(fontKey, font, fontVariations, fontFeatures) {
             const tempText = new Text();
-            await tempText.loadFont(font, fontVariations);
+            await tempText.loadFont(font, fontVariations, fontFeatures);
             const loadedFont = tempText.getLoadedFont();
             Text.fontCache.set(fontKey, loadedFont);
-            // Don't destroy tempText - the cached font references its HarfBuzz objects
             return loadedFont;
         }
         static generateFontContentHash(buffer) {
@@ -4545,10 +4897,13 @@
             const contentHash = Text.generateFontContentHash(loadedFont._buffer);
             this.currentFontId = `font_${contentHash}`;
             if (loadedFont.fontVariations) {
-                this.currentFontId += `_${JSON.stringify(loadedFont.fontVariations)}`;
+                this.currentFontId += `_var_${JSON.stringify(loadedFont.fontVariations)}`;
+            }
+            if (loadedFont.fontFeatures) {
+                this.currentFontId += `_feat_${JSON.stringify(loadedFont.fontFeatures)}`;
             }
         }
-        async loadFont(fontSrc, fontVariations) {
+        async loadFont(fontSrc, fontVariations, fontFeatures) {
             perfLogger.start('Text.loadFont', {
                 fontSrc: typeof fontSrc === 'string' ? fontSrc : `buffer(${fontSrc.byteLength})`
             });
@@ -4569,14 +4924,20 @@
                     this.destroy();
                 }
                 this.loadedFont = await this.fontLoader.loadFont(fontBuffer, fontVariations);
+                if (fontFeatures) {
+                    this.loadedFont.fontFeatures = fontFeatures;
+                }
                 const contentHash = Text.generateFontContentHash(fontBuffer);
                 this.currentFontId = `font_${contentHash}`;
                 if (fontVariations) {
-                    this.currentFontId += `_${JSON.stringify(fontVariations)}`;
+                    this.currentFontId += `_var_${JSON.stringify(fontVariations)}`;
+                }
+                if (fontFeatures) {
+                    this.currentFontId += `_feat_${JSON.stringify(fontFeatures)}`;
                 }
             }
             catch (error) {
-                debugLogger.error('Failed to load font:', error);
+                logger.error('Failed to load font:', error);
                 throw error;
             }
             finally {
@@ -4651,7 +5012,7 @@
                         };
                     }
                     catch (error) {
-                        debugLogger.warn(`Failed to load patterns for ${language}: ${error}`);
+                        logger.warn(`Failed to load patterns for ${language}: ${error}`);
                         return {
                             ...options,
                             layout: {
@@ -4915,7 +5276,7 @@
                         Text.patternCache.set(language, pattern);
                     }
                     catch (error) {
-                        debugLogger.warn(`Failed to pre-load patterns for ${language}: ${error}`);
+                        logger.warn(`Failed to pre-load patterns for ${language}: ${error}`);
                     }
                 }
             }));
@@ -4977,7 +5338,7 @@
                 FontLoader.destroyFont(currentFont);
             }
             catch (error) {
-                debugLogger.warn('Error destroying HarfBuzz objects:', error);
+                logger.warn('Error destroying HarfBuzz objects:', error);
             }
             finally {
                 this.loadedFont = undefined;