three-text 0.2.6 → 0.2.7

package/README.md

@@ -15,7 +15,7 @@ A high fidelity 3D font renderer and text layout engine for the web
 > [!CAUTION]
 > three-text is an alpha release and the API may break rapidly. This warning will last at least through the end of 2025. If API stability is important to you, consider pinning your version. Community feedback is encouraged; please open an issue if you have any suggestions or feedback, thank you
 
-**three-text** renders and formats text from TTF, OTF, and WOFF font files as 3D geometry. It uses [TeX](https://en.wikipedia.org/wiki/TeX)-based parameters for breaking text into paragraphs across multiple lines, and turns font outlines into 3D shapes on the fly, caching their geometries for low CPU overhead in languages with lots of repeating glyphs. Variable fonts are supported as static instances at a given axis coordinate
+**three-text** renders and formats text from TTF, OTF, and WOFF font files as 3D geometry. It uses [TeX](https://en.wikipedia.org/wiki/TeX)-based parameters for breaking text into paragraphs across multiple lines, and turns font outlines into 3D shapes on the fly. Glyph geometry is cached for low CPU overhead, especially in languages with lots of repeating glyphs. Variable fonts are supported as static instances at a given axis coordinate
 
 The library has a framework-agnostic core that returns raw vertex data, with lightweight adapters for [Three.js](https://threejs.org), [React Three Fiber](https://docs.pmnd.rs/react-three-fiber), [p5.js](https://p5js.org), [WebGL](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API), and [WebGPU](https://developer.mozilla.org/en-US/docs/Web/API/WebGPU_API)
 
@@ -243,7 +243,7 @@ Existing solutions take different approaches:
 - **three-bmfont-text** is a 2D approach for Three.js, using pre-rendered bitmap fonts with SDF support. Texture atlases are generated at specific sizes, and artifacts are apparent up close
 - **troika-three-text** uses MSDF, which improves quality, and like three-text, it is built on HarfBuzz, which provides substantial language coverage, but is ultimately a 2D technique in image space. For flat text that does not need formatting or extrusion, and where artifacts are acceptable up close, troika works well
 
-three-text generates true 3D geometry from font files via HarfBuzz. It is sharper at close distances than bitmap approaches when flat, and produces real mesh data that can be used with any rendering system. The library caches tessellated glyphs, so a paragraph of 1000 words might only require 50 tessellations depending on the language. This makes it well-suited to longer texts. In addition to performance considerations, three-text provides control over typesetting and paragraph justification via TeX-based parameters
+three-text generates true 3D geometry from font files via HarfBuzz. It is sharper at close distances than bitmap approaches when flat, and produces real mesh data that can be used with any rendering system. The library caches glyph geometry, so a paragraph of 1000 words might only require 50 unique glyphs to be processed. This makes it well-suited to longer texts. In addition to performance considerations, three-text provides control over typesetting and paragraph justification via TeX-based parameters
 
 ## Library structure
 
@@ -298,7 +298,7 @@ Hyphenation uses patterns derived from the Tex hyphenation project, converted in
 
 ### Geometry generation and optimization
 
-To optimize performance, three-text generates the geometry for each unique glyph or glyph cluster only once. The result is stored in a cache for reuse. This initial geometry creation is a multi-stage pipeline:
+The geometry pipeline runs once per unique glyph (or glyph cluster), with intermediate results cached to avoid redundant work:
 
 1. **Path collection**: HarfBuzz callbacks provide low level drawing operations
 2. **Curve polygonization**: Uses Anti-Grain Geometry's recursive subdivision to convert bezier curves into polygons, concentrating points where curvature is high
@@ -315,7 +315,7 @@ The multi-stage geometry approach (curve polygonization followed by cleanup, the
 
 The library uses a hybrid caching strategy to maximize performance while ensuring visual correctness
 
-By default, it operates with glyph-level cache. The geometry for each unique character (`a`, `b`, `c`...) is generated only once and stored for reuse to avoiding redundant computation
+By default, it operates with glyph-level cache. The geometry for each unique character (`a`, `b`, `c`...) is generated only once and stored for reuse, avoiding redundant computation
 
 For text with tight tracking, connected scripts, or complex kerning pairs, individual glyphs can overlap. When an overlap within a word is found, the entire word is treated as a single unit and escalated to a word-level cache. All of its glyphs are tessellated together to correctly resolve the overlaps, and the resulting geometry for the word is cached
 
@@ -958,6 +958,23 @@ npm test -- --coverage # Coverage report
 
 Tests use mocked HarfBuzz and tessellation libraries for fast execution without requiring WASM files
 
+### Benchmarking
+
+For performance of the real pipeline using HarfBuzz, including shaping, layout, tessellation, extrusion, there is a dedicated benchmark:
+
+```bash
+npm run benchmark
+```
+
+This runs a Node/Vitest scenario that:
+
+- initializes HarfBuzz from `hb.wasm` via `Text.setHarfBuzzBuffer`
+- loads Nimbus Sans and tests the example paragraph from the demos
+- performs a small number of cold runs followed by warm runs of `Text.create()` with justification and hyphenation enabled
+- prints a per-stage timing table (font load, line breaking, polygonization, tessellation, extrusion, and overall geometry creation)
+
+Use this to compare changes locally; it is meant as a sanity check on real work rather than a reliable micro-benchmark
+
 ## Build system
 
 ### Development

package/dist/index.cjs

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.2.6
+ * three-text v0.2.7
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify
@@ -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 = [];
@@ -1208,6 +1213,9 @@ function convertFontFeaturesToString(features) {
 }
 
 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);
@@ -1237,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,
@@ -1260,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 {
@@ -2225,7 +2236,11 @@ class Tessellator {
         if (removeOverlaps) {
             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) {
                 logger.warn('libtess returned empty result from boundary pass');
                 return { triangles: { vertices: [], indices: [] }, contours: [] };
@@ -2238,7 +2253,11 @@ class Tessellator {
             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'
@@ -2425,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;
@@ -3069,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) {
@@ -3092,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) {
@@ -3326,6 +3358,184 @@ class DrawCallbackHandler {
     }
 }
 
+// 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';
@@ -3338,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();
@@ -3482,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;
@@ -3547,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) {
@@ -3619,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++) {