three-text 0.2.4 → 0.2.6

package/dist/index.d.ts

@@ -62,10 +62,17 @@ interface LoadedFont {
     fontVariations?: {
         [key: string]: number;
     };
+    fontFeatures?: {
+        [tag: string]: boolean | number;
+    };
     isVariable?: boolean;
     variationAxes?: {
         [key: string]: VariationAxis;
     };
+    availableFeatures?: string[];
+    featureNames?: {
+        [tag: string]: string;
+    };
     _buffer?: ArrayBuffer;
 }
 interface HarfBuzzModule {
@@ -84,7 +91,7 @@ interface HarfBuzzAPI {
     createFace: (blob: HarfBuzzBlob, index: number) => HarfBuzzFace;
     createFont: (face: HarfBuzzFace) => HarfBuzzFont;
     createBuffer: () => HarfBuzzBuffer;
-    shape: (font: HarfBuzzFont, buffer: HarfBuzzBuffer) => void;
+    shape: (font: HarfBuzzFont, buffer: HarfBuzzBuffer, features?: string) => void;
 }
 interface HarfBuzzBlob {
     destroy: () => void;
@@ -263,6 +270,9 @@ interface TextOptions {
     fontVariations?: {
         [key: string]: number;
     };
+    fontFeatures?: {
+        [tag: string]: boolean | number;
+    };
     maxTextLength?: number;
     removeOverlaps?: boolean;
     curveFidelity?: CurveFidelityConfig;
@@ -436,6 +446,13 @@ declare const DEFAULT_CURVE_FIDELITY: CurveFidelityConfig;
 
 declare class FontMetadataExtractor {
     static extractMetadata(fontBuffer: ArrayBuffer): ExtractedMetrics;
+    static extractFeatureTags(fontBuffer: ArrayBuffer): {
+        tags: string[];
+        names: {
+            [tag: string]: string;
+        };
+    } | undefined;
+    private static extractFeatureDataFromTable;
     private static extractAxisNames;
     private static getNameFromNameTable;
     static getVerticalMetrics(metrics: ExtractedMetrics): VerticalMetrics;

package/dist/index.js

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.2.4
+ * three-text v0.2.6
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify
@@ -22,7 +22,7 @@ const isLogEnabled = (() => {
     }
     return false;
 })();
-class DebugLogger {
+class Logger {
     warn(message, ...args) {
         console.warn(message, ...args);
     }
@@ -33,7 +33,7 @@ class DebugLogger {
         isLogEnabled && console.log(message, ...args);
     }
 }
-const debugLogger = new DebugLogger();
+const logger = new Logger();
 
 class PerformanceLogger {
     constructor() {
@@ -59,7 +59,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;
@@ -562,7 +562,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)
@@ -1177,22 +1177,47 @@ 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 {
     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
         let totalWidth = 0;
-        glyphInfos.forEach((glyph, index) => {
+        glyphInfos.forEach((glyph) => {
             totalWidth += glyph.ax;
-            // Spaces measured alone need letter spacing to match final rendering
-            const isLastChar = index === glyphInfos.length - 1;
-            const isSingleSpace = text === ' ' || text === '  ' || /^\s+$/.test(text);
-            if (letterSpacingInFontUnits !== 0 && (!isLastChar || isSingleSpace)) {
+            if (letterSpacingInFontUnits !== 0) {
                 totalWidth += letterSpacingInFontUnits;
             }
         });
@@ -1247,7 +1272,7 @@ class TextLayout {
                     originalEnd: currentIndex + line.length - 1,
                     xOffset: 0
                 });
-                currentIndex += line.length + 1; // +1 for the newline character
+                currentIndex += line.length + 1;
             }
         }
         return { lines };
@@ -1268,7 +1293,7 @@ class TextLayout {
                 offset = width - planeBounds.max.x;
             }
             if (offset !== 0) {
-                // Translate vertices directly
+                // Translate vertices
                 for (let i = 0; i < vertices.length; i += 3) {
                     vertices[i] += offset;
                 }
@@ -1286,6 +1311,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 +1338,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 +1347,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 ') {
+            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
@@ -1378,6 +1411,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 +1703,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 +1732,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 +1770,7 @@ class FontLoader {
                     };
                 }
             }
+            const featureData = FontMetadataExtractor.extractFeatureTags(fontBuffer);
             return {
                 hb,
                 fontBlob,
@@ -1665,11 +1781,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 +1808,7 @@ class FontLoader {
             }
         }
         catch (error) {
-            debugLogger.error('Error destroying font resources:', error);
+            logger.error('Error destroying font resources:', error);
         }
     }
 }
@@ -2092,7 +2210,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,19 +2220,19 @@ 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
             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');
@@ -2122,7 +2240,7 @@ class Tessellator {
             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 +2295,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);
@@ -3199,7 +3317,7 @@ class DrawCallbackHandler {
             }
         }
         catch (error) {
-            debugLogger.warn('Error destroying draw callbacks:', error);
+            logger.warn('Error destroying draw callbacks:', error);
         }
         this.collector = undefined;
     }
@@ -3489,7 +3607,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 = [];
@@ -3564,15 +3683,14 @@ class TextShaper {
                 naturalSpaceWidth = TextMeasurer.measureTextWidth(this.loadedFont, ' ', letterSpacing);
                 this.cachedSpaceWidth.set(letterSpacing, naturalSpaceWidth);
             }
+            const width = naturalSpaceWidth;
             const stretchFactor = SPACE_STRETCH_RATIO;
             const shrinkFactor = SPACE_SHRINK_RATIO;
             if (lineInfo.adjustmentRatio > 0) {
-                spaceAdjustment =
-                    lineInfo.adjustmentRatio * naturalSpaceWidth * stretchFactor;
+                spaceAdjustment = lineInfo.adjustmentRatio * width * stretchFactor;
             }
             else if (lineInfo.adjustmentRatio < 0) {
-                spaceAdjustment =
-                    lineInfo.adjustmentRatio * naturalSpaceWidth * shrinkFactor;
+                spaceAdjustment = lineInfo.adjustmentRatio * width * shrinkFactor;
             }
         }
         return spaceAdjustment;
@@ -4497,12 +4615,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);
@@ -4516,12 +4638,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) {
@@ -4540,10 +4661,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})`
         });
@@ -4564,14 +4688,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 {
@@ -4646,7 +4776,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: {
@@ -4910,7 +5040,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}`);
                 }
             }
         }));
@@ -4972,7 +5102,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;