three-text 0.2.5 → 0.2.7

package/dist/index.cjs

@@ -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
@@ -25,7 +25,7 @@ const isLogEnabled = (() => {
     }
     return false;
 })();
-class DebugLogger {
+class Logger {
     warn(message, ...args) {
         console.warn(message, ...args);
     }
@@ -36,7 +36,7 @@ class DebugLogger {
         isLogEnabled && console.log(message, ...args);
     }
 }
-const debugLogger = new DebugLogger();
+const logger = new Logger();
 
 class PerformanceLogger {
     constructor() {
@@ -62,7 +62,7 @@ class PerformanceLogger {
         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;
@@ -125,6 +125,9 @@ class PerformanceLogger {
         this.metrics.length = 0;
         this.activeTimers.clear();
     }
+    reset() {
+        this.clear();
+    }
     time(name, fn, metadata) {
         if (!isLogEnabled)
             return fn();
@@ -324,6 +327,8 @@ class LineBreak {
         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 = [];
@@ -565,7 +570,7 @@ class LineBreak {
         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)
@@ -1180,12 +1185,43 @@ class LineBreak {
     }
 }
 
+// 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
@@ -1209,6 +1245,8 @@ class TextLayout {
         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,
@@ -1232,7 +1270,8 @@ class TextLayout {
                 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 {
@@ -1286,6 +1325,17 @@ const FONT_SIGNATURE_OPEN_TYPE_CFF = 0x4f54544f; // 'OTTO'
 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) {
@@ -1302,7 +1352,6 @@ class FontMetadataExtractor {
         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;
@@ -1312,30 +1361,28 @@ class FontMetadataExtractor {
         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
@@ -1378,6 +1425,88 @@ class FontMetadataExtractor {
             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
@@ -1588,7 +1717,7 @@ class WoffConverter {
             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) {
@@ -1617,7 +1746,7 @@ class FontLoader {
         // 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') {
@@ -1655,6 +1784,7 @@ class FontLoader {
                     };
                 }
             }
+            const featureData = FontMetadataExtractor.extractFeatureTags(fontBuffer);
             return {
                 hb,
                 fontBlob,
@@ -1665,11 +1795,13 @@ class FontLoader {
                 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 {
@@ -1690,7 +1822,7 @@ class FontLoader {
             }
         }
         catch (error) {
-            debugLogger.error('Error destroying font resources:', error);
+            logger.error('Error destroying font resources:', error);
         }
     }
 }
@@ -2092,7 +2224,7 @@ class Tessellator {
         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) {
@@ -2102,27 +2234,35 @@ class Tessellator {
             : 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 {
@@ -2177,7 +2317,7 @@ class Tessellator {
             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);
@@ -2304,10 +2444,16 @@ const OVERLAP_EPSILON = 1e-3;
 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;
@@ -2948,6 +3094,11 @@ class GlyphContourCollector {
         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) {
@@ -2971,6 +3122,8 @@ class GlyphContourCollector {
             // 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) {
@@ -3199,12 +3352,190 @@ class DrawCallbackHandler {
             }
         }
         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';
@@ -3217,6 +3548,16 @@ class GlyphGeometryBuilder {
         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();
@@ -3361,30 +3702,37 @@ class GlyphGeometryBuilder {
         };
     }
     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;
@@ -3426,6 +3774,7 @@ class GlyphGeometryBuilder {
             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) {
@@ -3489,7 +3838,8 @@ class TextShaper {
         }
         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 = [];
@@ -3497,6 +3847,7 @@ class TextShaper {
         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++) {
@@ -3568,12 +3919,10 @@ class TextShaper {
             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;
@@ -4498,12 +4847,16 @@ class Text {
         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);
@@ -4517,12 +4870,11 @@ class Text {
             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) {
@@ -4541,10 +4893,13 @@ class Text {
         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})`
         });
@@ -4565,14 +4920,20 @@ class Text {
                 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 {
@@ -4647,7 +5008,7 @@ class Text {
                     };
                 }
                 catch (error) {
-                    debugLogger.warn(`Failed to load patterns for ${language}: ${error}`);
+                    logger.warn(`Failed to load patterns for ${language}: ${error}`);
                     return {
                         ...options,
                         layout: {
@@ -4911,7 +5272,7 @@ class Text {
                     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}`);
                 }
             }
         }));
@@ -4973,7 +5334,7 @@ class Text {
             FontLoader.destroyFont(currentFont);
         }
         catch (error) {
-            debugLogger.warn('Error destroying HarfBuzz objects:', error);
+            logger.warn('Error destroying HarfBuzz objects:', error);
         }
         finally {
             this.loadedFont = undefined;