three-text 0.2.6 → 0.2.7

package/dist/index.js

@@ -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
@@ -122,6 +122,9 @@ class PerformanceLogger {
         this.metrics.length = 0;
         this.activeTimers.clear();
     }
+    reset() {
+        this.clear();
+    }
     time(name, fn, metadata) {
         if (!isLogEnabled)
             return fn();
@@ -321,6 +324,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 = [];
@@ -1205,6 +1210,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);
@@ -1234,6 +1242,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,
@@ -1257,7 +1267,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 {
@@ -2222,7 +2233,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: [] };
@@ -2235,7 +2250,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'
@@ -2422,10 +2441,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;
@@ -3066,6 +3091,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) {
@@ -3089,6 +3119,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) {
@@ -3323,6 +3355,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';
@@ -3335,6 +3545,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();
@@ -3479,30 +3699,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;
@@ -3544,6 +3771,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) {
@@ -3616,6 +3844,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++) {