three-text 0.2.5 → 0.2.6

package/dist/index.umd.js

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.2.5
+ * three-text v0.2.6
  * 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;
@@ -567,7 +567,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 +1182,40 @@
         }
     }
 
+    // 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 {
         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
@@ -1288,6 +1316,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 +1343,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 +1352,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 ') {
+                const offset = 12 + i * 16;
+                const tag = view.getUint32(offset);
+                if (tag === TABLE_TAG_CFF || tag === TABLE_TAG_CFF2) {
                     isCFF = true;
                 }
-                else if (tag === 'CFF2') {
-                    isCFF = true;
+                else if (tag === TABLE_TAG_HEAD) {
+                    headTableOffset = view.getUint32(offset + 8);
                 }
-                if (tag === 'head') {
-                    headTableOffset = view.getUint32(12 + i * 16 + 8);
+                else if (tag === TABLE_TAG_HHEA) {
+                    hheaTableOffset = view.getUint32(offset + 8);
                 }
-                if (tag === 'hhea') {
-                    hheaTableOffset = view.getUint32(12 + i * 16 + 8);
+                else if (tag === TABLE_TAG_OS2) {
+                    os2TableOffset = view.getUint32(offset + 8);
                 }
-                if (tag === 'OS/2') {
-                    os2TableOffset = view.getUint32(12 + i * 16 + 8);
+                else if (tag === TABLE_TAG_FVAR) {
+                    fvarTableOffset = view.getUint32(offset + 8);
                 }
-                if (tag === 'fvar') {
-                    fvarTableOffset = view.getUint32(12 + i * 16 + 8);
+                else if (tag === TABLE_TAG_STAT) {
+                    statTableOffset = view.getUint32(offset + 8);
                 }
-                if (tag === 'STAT') {
-                    statTableOffset = view.getUint32(12 + i * 16 + 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 +1416,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 +1708,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 +1737,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 +1775,7 @@
                         };
                     }
                 }
+                const featureData = FontMetadataExtractor.extractFeatureTags(fontBuffer);
                 return {
                     hb,
                     fontBlob,
@@ -1667,11 +1786,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 +1813,7 @@
                 }
             }
             catch (error) {
-                debugLogger.error('Error destroying font resources:', error);
+                logger.error('Error destroying font resources:', error);
             }
         }
     }
@@ -2096,7 +2217,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,19 +2227,19 @@
                 : 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
                 const boundaryResult = this.performTessellation(contours, 'boundary');
                 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
             const triangleResult = this.performTessellation(contours, 'triangles');
@@ -2126,7 +2247,7 @@
                 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 +2302,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);
@@ -3203,7 +3324,7 @@
                 }
             }
             catch (error) {
-                debugLogger.warn('Error destroying draw callbacks:', error);
+                logger.warn('Error destroying draw callbacks:', error);
             }
             this.collector = undefined;
         }
@@ -3493,7 +3614,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 = [];
@@ -3572,12 +3694,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 +4622,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 +4645,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 +4668,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 +4695,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 +4783,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 +5047,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 +5109,7 @@
                 FontLoader.destroyFont(currentFont);
             }
             catch (error) {
-                debugLogger.warn('Error destroying HarfBuzz objects:', error);
+                logger.warn('Error destroying HarfBuzz objects:', error);
             }
             finally {
                 this.loadedFont = undefined;