three-text 0.2.6 → 0.2.7

package/dist/index.umd.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
@@ -127,6 +127,9 @@
             this.metrics.length = 0;
             this.activeTimers.clear();
         }
+        reset() {
+            this.clear();
+        }
         time(name, fn, metadata) {
             if (!isLogEnabled)
                 return fn();
@@ -326,6 +329,8 @@
             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 = [];
@@ -1210,6 +1215,9 @@
     }
 
     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);
@@ -1239,6 +1247,8 @@
             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,
@@ -1262,7 +1272,8 @@
                     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 {
@@ -2229,7 +2240,11 @@
             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: [] };
@@ -2242,7 +2257,11 @@
                 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'
@@ -2429,10 +2448,16 @@
     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;
@@ -3073,6 +3098,11 @@
             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) {
@@ -3096,6 +3126,8 @@
                 // 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) {
@@ -3330,6 +3362,184 @@
         }
     }
 
+    // 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';
@@ -3342,6 +3552,16 @@
             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();
@@ -3486,30 +3706,37 @@
             };
         }
         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;
@@ -3551,6 +3778,7 @@
                 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) {
@@ -3623,6 +3851,7 @@
             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++) {