three-text 0.2.5 → 0.2.6

package/README.md

@@ -235,7 +235,7 @@ Then navigate to `http://localhost:3000`
 
 ## Why three-text?
 
-three-text generates high-fidelity 3D mesh geometry from font files. Unlike texture-based approaches, it produces true geometry that can be lit, shaded, and manipulated like any 3D model.
+three-text generates high-fidelity 3D mesh geometry from font files. Unlike texture-based approaches, it produces true geometry that can be lit, shaded, and manipulated like any 3D model
 
 Existing solutions take different approaches:
 
@@ -305,7 +305,7 @@ To optimize performance, three-text generates the geometry for each unique glyph
 3. **Geometry optimization**:
    - **Visvalingam-Whyatt simplification**: removes vertices that contribute the least to the overall shape, preserving sharp corners and subtle curves
    - **Colinear point removal**: eliminates redundant points that lie on straight lines within angle tolerances
-4. **Overlap removal**: removes self-intersections and resolves overlapping paths between glyphs, preserving correct winding rules for triangulation.
+4. **Overlap removal**: removes self-intersections and resolves overlapping paths between glyphs, preserving correct winding rules for triangulation
 5. **Triangulation**: converts cleaned 2D shapes into triangles using libtess2 with non-zero winding rule
 6. **Mesh construction**: generates 2D or 3D geometry with front faces and optional depth/extrusion (back faces and side walls)
 
@@ -334,7 +334,7 @@ The library converts bezier curves into line segments by recursively subdividing
 - `distanceTolerance`: The maximum allowed deviation of the curve from a straight line segment, measured in font units. Lower values produce higher fidelity and more vertices. Default is `0.5`, which is nearly imperceptable without extrusion
 - `angleTolerance`: The maximum angle in radians between segments at a join. This helps preserve sharp corners. Default is `0.2`
 
-In general, this step helps more with time to first render than ongoing interactions in the scene.
+In general, this step helps more with time to first render than ongoing interactions in the scene
 
 ```javascript
 // Using the default configuration
@@ -466,25 +466,6 @@ const text = await Text.create({
 });
 ```
 
-### Per-glyph animation attributes
-
-For shader-based animations and interactive effects, the library can generate per-vertex attributes that identify which glyph each vertex belongs to:
-
-```javascript
-const text = await Text.create({
-  text: 'Sample text',
-  font: '/fonts/Font.ttf',
-  separateGlyphsWithAttributes: true,
-});
-
-// Geometry includes these vertex attributes:
-// - glyphCenter (vec3): center point of each glyph
-// - glyphIndex (float): sequential glyph index
-// - glyphLineIndex (float): line number
-```
-
-This option bypasses overlap-based clustering and adds vertex attributes suitable for per-character manipulation in vertex shaders. Each unique glyph is still tessellated only once and cached for reuse. The tradeoff is potential visual artifacts where glyphs actually overlap (tight kerning, cursive scripts)
-
 ### Variable fonts
 
 Variable fonts allow dynamic adjustment of typographic characteristics through variation axes:
@@ -537,6 +518,47 @@ const text = await Text.create({
 });
 ```
 
+### OpenType features
+
+The `fontFeatures` option controls OpenType layout features using 4-character tags from the [feature registry](https://learn.microsoft.com/en-us/typography/opentype/spec/featuretags):
+
+```javascript
+const text = await Text.create({
+  text: 'Difficult ffi ffl',
+  font: '/fonts/Font.ttf',
+  fontFeatures: {
+    liga: true,
+    dlig: true,
+    kern: false,
+    ss01: 1,
+    cv01: 3,
+  },
+});
+```
+
+Values can be boolean (`true`/`false`) to enable or disable, or numeric for features accepting variant indices. Explicitly disabling a feature overrides the font's defaults
+
+Common tags include [`liga`](https://learn.microsoft.com/en-us/typography/opentype/spec/features_ko#liga) (ligatures), [`kern`](https://learn.microsoft.com/en-us/typography/opentype/spec/features_ko#kern) (kerning), [`calt`](https://learn.microsoft.com/en-us/typography/opentype/spec/features_ae#calt) (contextual alternates), and [`smcp`](https://learn.microsoft.com/en-us/typography/opentype/spec/features_pt#smcp) (small capitals). Number styling uses [`lnum`](https://learn.microsoft.com/en-us/typography/opentype/spec/features_ko#lnum)/[`onum`](https://learn.microsoft.com/en-us/typography/opentype/spec/features_ko#onum)/[`tnum`](https://learn.microsoft.com/en-us/typography/opentype/spec/features_pt#tnum). Stylistic alternates are [`ss01`-`ss20`](https://learn.microsoft.com/en-us/typography/opentype/spec/features_pt#ss01--ss20) and [`cv01`-`cv99`](https://learn.microsoft.com/en-us/typography/opentype/spec/features_ae#cv01--cv99). Feature availability depends on the font
+
+### Per-glyph attributes
+
+For shader-based animations and interactive effects, the library can generate per-vertex attributes that identify which glyph each vertex belongs to:
+
+```javascript
+const text = await Text.create({
+  text: 'Sample text',
+  font: '/fonts/Font.ttf',
+  separateGlyphsWithAttributes: true,
+});
+
+// Geometry includes these vertex attributes:
+// - glyphCenter (vec3): center point of each glyph
+// - glyphIndex (float): sequential glyph index
+// - glyphLineIndex (float): line number
+```
+
+This option bypasses overlap-based clustering and adds vertex attributes suitable for per-character manipulation in vertex shaders. Each unique glyph is still tessellated only once and cached for reuse. The tradeoff is potential visual artifacts where glyphs actually overlap (tight kerning, cursive scripts)
+
 ## Querying text content
 
 After creating text geometry, use the `query()` method to find text ranges:
@@ -634,7 +656,7 @@ The library's full TypeScript definitions are the most complete source of truth
 
 #### `Text.create(options: TextOptions): Promise<TextGeometryInfo>`
 
-Creates text geometry with automatic font loading and HarfBuzz initialization.
+Creates text geometry with automatic font loading and HarfBuzz initialization
 
 **Core (`three-text`) returns:**
 - `vertices: Float32Array` - Vertex positions
@@ -694,6 +716,7 @@ interface TextOptions {
   lineHeight?: number; // Line height multiplier (default: 1.0)
   letterSpacing?: number; // Letter spacing as a fraction of em (e.g., 0.05)
   fontVariations?: { [key: string]: number }; // Variable font axis settings
+  fontFeatures?: { [tag: string]: boolean | number }; // OpenType feature settings
   removeOverlaps?: boolean; // Override default overlap removal (auto-enabled for VF only)
   separateGlyphsWithAttributes?: boolean; // Force individual glyph tessellation and add shader attributes
   color?: [number, number, number] | ColorOptions; // Text coloring (simple or complex)

package/dist/index.cjs

@@ -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
@@ -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;
@@ -565,7 +565,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 +1180,40 @@ 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
@@ -1286,6 +1314,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 +1341,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 +1350,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 +1414,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 +1706,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 +1735,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 +1773,7 @@ class FontLoader {
                     };
                 }
             }
+            const featureData = FontMetadataExtractor.extractFeatureTags(fontBuffer);
             return {
                 hb,
                 fontBlob,
@@ -1665,11 +1784,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 +1811,7 @@ class FontLoader {
             }
         }
         catch (error) {
-            debugLogger.error('Error destroying font resources:', error);
+            logger.error('Error destroying font resources:', error);
         }
     }
 }
@@ -2092,7 +2213,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 +2223,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 +2243,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 +2298,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 +3320,7 @@ class DrawCallbackHandler {
             }
         }
         catch (error) {
-            debugLogger.warn('Error destroying draw callbacks:', error);
+            logger.warn('Error destroying draw callbacks:', error);
         }
         this.collector = undefined;
     }
@@ -3489,7 +3610,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 = [];
@@ -3568,12 +3690,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 +4618,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 +4641,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 +4664,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 +4691,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 +4779,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 +5043,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 +5105,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;

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;