three-text 0.2.8 → 0.2.9

package/dist/index.umd.js

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.2.8
+ * three-text v0.2.9
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify
@@ -188,11 +188,11 @@
         FitnessClass[FitnessClass["VERY_LOOSE"] = 3] = "VERY_LOOSE";
     })(FitnessClass || (FitnessClass = {}));
     // ActiveNodeList maintains all currently viable breakpoints as we scan through the text.
-    // Each node represents a potential break with accumulated demerits (total "cost" from start).
+    // Each node represents a potential break with accumulated demerits (total "cost" from start)
     //
     // Demerits = cumulative penalty score from text start to this break, calculated as:
-    //   (line_penalty + badness)² + penalty² + flagged/fitness adjustments (tex.web §859)
-    // Lower demerits = better line breaks. TeX minimizes total demerits across the paragraph.
+    //   (line_penalty + badness)² + penalty² + flagged/fitness adjustments (tex.web line 16634)
+    // Lower demerits = better line breaks. TeX minimizes total demerits across the paragraph
     //
     // Implementation differs from TeX:
     // - Hash map for O(1) lookups by position+fitness
@@ -263,7 +263,7 @@
     const SHORT_LINE_WIDTH_THRESHOLD = 0.5; // Lines < 50% of width are problematic
     const SHORT_LINE_EMERGENCY_STRETCH_INCREMENT = 0.1; // Add 10% per iteration
     class LineBreak {
-        // Calculate badness according to TeX's formula (tex.web §108, line 2337)
+        // Calculate badness according to TeX's formula (tex.web line 2337)
         // Given t (desired adjustment) and s (available stretch/shrink)
         // Returns approximation to 100(t/s)³, representing how "bad" a line is
         // Constants are derived from TeX's fixed-point arithmetic:
@@ -812,19 +812,22 @@
                 // First pass: no hyphenation
                 let currentItems = allItems;
                 let breaks = LineBreak.findBreakpoints(currentItems, width, pretolerance, looseness, false, 0, context);
-                // Second pass: compute hyphenation only if needed
+                // Second pass: with hyphenation if first pass failed
                 if (breaks.length === 0 && useHyphenation) {
                     const itemsWithHyphenation = LineBreak.itemizeText(text, measureText, true, language, hyphenationPatterns, lefthyphenmin, righthyphenmin, context);
                     currentItems = itemsWithHyphenation;
                     breaks = LineBreak.findBreakpoints(currentItems, width, tolerance, looseness, false, 0, context);
                 }
-                // Emergency pass: use currentItems as-is (preserves hyphenation from pass 2 if it ran)
+                // Emergency pass: add emergency stretch to background stretchability
                 if (breaks.length === 0) {
-                    breaks = LineBreak.findBreakpoints(currentItems, width, INF_BAD + 1, looseness, true, currentEmergencyStretch, context);
+                    // For first emergency attempt, use initialEmergencyStretch
+                    // For subsequent iterations (short line detection), progressively increase
+                    currentEmergencyStretch = initialEmergencyStretch + (iteration * width * SHORT_LINE_EMERGENCY_STRETCH_INCREMENT);
+                    breaks = LineBreak.findBreakpoints(currentItems, width, tolerance, looseness, true, currentEmergencyStretch, context);
                 }
-                // Force with infinite tolerance if still no breaks found
+                // Last resort: allow higher badness (but not infinite)
                 if (breaks.length === 0) {
-                    breaks = LineBreak.findBreakpoints(currentItems, width, Infinity, looseness, true, currentEmergencyStretch, context);
+                    breaks = LineBreak.findBreakpoints(currentItems, width, INF_BAD, looseness, true, currentEmergencyStretch, context);
                 }
                 // Create lines from breaks
                 if (breaks.length > 0) {
@@ -834,9 +837,7 @@
                     if (shortLineDetectionEnabled &&
                         breaks.length > 1 &&
                         LineBreak.hasShortLines(currentItems, breaks, width, shortLineThreshold)) {
-                        // Increase emergency stretch and try again
-                        currentEmergencyStretch +=
-                            width * SHORT_LINE_EMERGENCY_STRETCH_INCREMENT;
+                        // Retry with more emergency stretch to push words to next line
                         iteration++;
                         continue;
                     }
@@ -868,11 +869,12 @@
         threshold = Infinity, // maximum badness allowed for a break
         looseness = 0, // desired line count adjustment
         isFinalPass = false, // whether this is the final pass
-        emergencyStretch = 0, // emergency stretch added to background stretchability
+        backgroundStretch = 0, // additional stretchability for all glue (emergency stretch)
         context) {
             // Pre-compute cumulative widths for fast range queries
             const cumulativeWidths = LineBreak.computeCumulativeWidths(items);
             const activeNodes = new ActiveNodeList();
+            const minimumDemerits = { value: Infinity };
             activeNodes.insert({
                 position: 0,
                 line: 0,
@@ -886,16 +888,16 @@
                 const item = items[i];
                 if (item.type === ItemType.PENALTY &&
                     item.penalty < Infinity) {
-                    LineBreak.considerBreak(items, activeNodes, i, lineWidth, threshold, emergencyStretch, cumulativeWidths, context);
+                    LineBreak.considerBreak(items, activeNodes, i, lineWidth, threshold, backgroundStretch, cumulativeWidths, context, isFinalPass, minimumDemerits);
                 }
                 if (item.type === ItemType.DISCRETIONARY &&
                     item.penalty < Infinity) {
-                    LineBreak.considerBreak(items, activeNodes, i, lineWidth, threshold, emergencyStretch, cumulativeWidths, context);
+                    LineBreak.considerBreak(items, activeNodes, i, lineWidth, threshold, backgroundStretch, cumulativeWidths, context, isFinalPass, minimumDemerits);
                 }
                 if (item.type === ItemType.GLUE &&
                     i > 0 &&
                     items[i - 1].type === ItemType.BOX) {
-                    LineBreak.considerBreak(items, activeNodes, i, lineWidth, threshold, emergencyStretch, cumulativeWidths, context);
+                    LineBreak.considerBreak(items, activeNodes, i, lineWidth, threshold, backgroundStretch, cumulativeWidths, context, isFinalPass, minimumDemerits);
                 }
                 LineBreak.deactivateNodes(activeNodes, i, lineWidth, cumulativeWidths.minWidths);
             }
@@ -962,7 +964,7 @@
             }
             return breakpoints;
         }
-        static considerBreak(items, activeNodes, breakpoint, lineWidth, threshold = Infinity, emergencyStretch = 0, cumulativeWidths, context) {
+        static considerBreak(items, activeNodes, breakpoint, lineWidth, threshold = Infinity, backgroundStretch = 0, cumulativeWidths, context, isFinalPass = false, minimumDemerits = { value: Infinity }) {
             const penalty = items[breakpoint].type === ItemType.PENALTY
                 ? items[breakpoint].penalty
                 : 0;
@@ -974,11 +976,11 @@
                     continue;
                 const adjustmentData = LineBreak.computeAdjustmentRatio(items, node.position, breakpoint, node.line, lineWidth, cumulativeWidths, context);
                 const { ratio: r, adjustment, stretch, shrink, totalWidth } = adjustmentData;
-                // Calculate badness according to TeX formula
+                // Calculate badness
                 let badness;
                 if (adjustment > 0) {
-                    // Add emergency stretch to the background stretchability
-                    const effectiveStretch = stretch + emergencyStretch;
+                    // backgroundStretch includes emergency stretch if in emergency pass
+                    const effectiveStretch = stretch + backgroundStretch;
                     if (effectiveStretch <= 0) {
                         // Overfull box - badness is infinite + 1
                         badness = INF_BAD + 1;
@@ -1003,26 +1005,32 @@
                 else {
                     badness = 0;
                 }
-                if (!isForcedBreak && r < -1) {
-                    // Too tight, skip unless forced
-                    continue;
+                // Artificial demerits: in final pass with no feasible solution yet
+                // and only one active node left, force this break as a last resort
+                const isLastResort = isFinalPass &&
+                    minimumDemerits.value === Infinity &&
+                    allActiveNodes.length === 1 &&
+                    node.active;
+                if (!isForcedBreak && !isLastResort && r < -1) {
+                    continue; // too tight
                 }
                 const fitnessClass = LineBreak.computeFitnessClass(badness, adjustment > 0);
-                if (!isForcedBreak && badness > threshold) {
+                if (!isForcedBreak && !isLastResort && badness > threshold) {
                     continue;
                 }
-                // Initialize demerits based on TeX formula with saturation check
+                // Initialize demerits with saturation check
                 let flaggedDemerits = 0;
                 let fitnessDemerits = 0;
                 const configuredLinePenalty = context?.linePenalty ?? 0;
                 let d = configuredLinePenalty + badness;
                 let demerits = Math.abs(d) >= 10000 ? 100000000 : d * d;
+                const artificialDemerits = isLastResort;
                 const breakpointPenalty = items[breakpoint].type === ItemType.PENALTY
                     ? items[breakpoint].penalty
                     : items[breakpoint].type === ItemType.DISCRETIONARY
                         ? items[breakpoint].penalty
                         : 0;
-                // TeX penalty handling: pi != 0 check, then positive/negative logic
+                // Penalty contribution to demerits
                 if (breakpointPenalty !== 0) {
                     if (breakpointPenalty > 0) {
                         demerits += breakpointPenalty * breakpointPenalty;
@@ -1048,10 +1056,13 @@
                     fitnessDemerits = context?.adjDemerits ?? 0;
                     demerits += fitnessDemerits;
                 }
-                if (isForcedBreak) {
+                if (isForcedBreak || artificialDemerits) {
                     demerits = 0;
                 }
                 const totalDemerits = node.totalDemerits + demerits;
+                if (totalDemerits < minimumDemerits.value) {
+                    minimumDemerits.value = totalDemerits;
+                }
                 let existingNode = activeNodes.findExisting(breakpoint, fitnessClass);
                 if (existingNode) {
                     if (totalDemerits < existingNode.totalDemerits) {
@@ -1189,7 +1200,6 @@
             return { widths, stretches, shrinks, minWidths };
         }
         // Deactivate nodes that can't lead to good line breaks
-        // TeX recalculates minWidth each time, we use cumulative arrays for lookup
         static deactivateNodes(activeNodeList, currentPosition, lineWidth, minWidths) {
             const activeNodes = activeNodeList.getAllActive();
             for (let i = activeNodes.length - 1; i >= 0; i--) {
@@ -1394,8 +1404,8 @@
 
     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
+        // (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);
@@ -3719,10 +3729,11 @@
         }
     }
 
+    const CONTOUR_CACHE_MAX_ENTRIES = 1000;
+    const WORD_CACHE_MAX_ENTRIES = 1000;
     class GlyphGeometryBuilder {
         constructor(cache, loadedFont) {
             this.fontId = 'default';
-            this.wordCache = new Map();
             this.cache = cache;
             this.loadedFont = loadedFont;
             this.tessellator = new Tessellator();
@@ -3732,7 +3743,7 @@
             this.drawCallbacks = new DrawCallbackHandler();
             this.drawCallbacks.createDrawFuncs(this.loadedFont, this.collector);
             this.contourCache = new LRUCache({
-                maxEntries: 1000,
+                maxEntries: CONTOUR_CACHE_MAX_ENTRIES,
                 calculateSize: (contours) => {
                     let size = 0;
                     for (const path of contours.paths) {
@@ -3741,6 +3752,15 @@
                     return size + 64; // bounds overhead
                 }
             });
+            this.wordCache = new LRUCache({
+                maxEntries: WORD_CACHE_MAX_ENTRIES,
+                calculateSize: (data) => {
+                    let size = data.vertices.length * 4;
+                    size += data.normals.length * 4;
+                    size += data.indices.length * data.indices.BYTES_PER_ELEMENT;
+                    return size;
+                }
+            });
         }
         getOptimizationStats() {
             return this.collector.getOptimizationStats();
@@ -4030,7 +4050,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)
+            // Apply letter spacing after each glyph to match width measurements used during line breaking
             const letterSpacingFU = letterSpacing * this.loadedFont.upem;
             const spaceAdjustment = this.calculateSpaceAdjustment(lineInfo, align, letterSpacing);
             const cjkAdjustment = this.calculateCJKAdjustment(lineInfo, align);
@@ -5068,6 +5088,54 @@
             if (!Text.hbInitPromise) {
                 Text.hbInitPromise = HarfBuzzLoader.getHarfBuzz();
             }
+            const loadedFont = await Text.resolveFont(options);
+            const text = new Text({ maxCacheSizeMB: options.maxCacheSizeMB });
+            text.setLoadedFont(loadedFont);
+            // Initial creation
+            const { font, maxCacheSizeMB, ...geometryOptions } = options;
+            const result = await text.createGeometry(geometryOptions);
+            // Recursive update function
+            const update = async (newOptions) => {
+                // Merge options - preserve font from original options if not provided
+                const mergedOptions = { ...options };
+                for (const key in newOptions) {
+                    const value = newOptions[key];
+                    if (value !== undefined) {
+                        mergedOptions[key] = value;
+                    }
+                }
+                // If font definition or configuration changed, reload font and reset helpers
+                if (newOptions.font !== undefined ||
+                    newOptions.fontVariations !== undefined ||
+                    newOptions.fontFeatures !== undefined) {
+                    const newLoadedFont = await Text.resolveFont(mergedOptions);
+                    text.setLoadedFont(newLoadedFont);
+                    // Reset geometry builder and shaper to use new font
+                    text.resetHelpers();
+                }
+                // Update closure options for next time
+                options = mergedOptions;
+                const { font, maxCacheSizeMB, ...currentGeometryOptions } = options;
+                const newResult = await text.createGeometry(currentGeometryOptions);
+                return {
+                    ...newResult,
+                    getLoadedFont: () => text.getLoadedFont(),
+                    getCacheStatistics: () => text.getCacheStatistics(),
+                    clearCache: () => text.clearCache(),
+                    measureTextWidth: (textString, letterSpacing) => text.measureTextWidth(textString, letterSpacing),
+                    update
+                };
+            };
+            return {
+                ...result,
+                getLoadedFont: () => text.getLoadedFont(),
+                getCacheStatistics: () => text.getCacheStatistics(),
+                clearCache: () => text.clearCache(),
+                measureTextWidth: (textString, letterSpacing) => text.measureTextWidth(textString, letterSpacing),
+                update
+            };
+        }
+        static async resolveFont(options) {
             const baseFontKey = typeof options.font === 'string'
                 ? options.font
                 : `buffer-${Text.generateFontContentHash(options.font)}`;
@@ -5082,17 +5150,7 @@
             if (!loadedFont) {
                 loadedFont = await Text.loadAndCacheFont(fontKey, options.font, options.fontVariations, options.fontFeatures);
             }
-            const text = new Text({ maxCacheSizeMB: options.maxCacheSizeMB });
-            text.setLoadedFont(loadedFont);
-            const { font, maxCacheSizeMB, ...geometryOptions } = options;
-            const result = await text.createGeometry(geometryOptions);
-            return {
-                ...result,
-                getLoadedFont: () => text.getLoadedFont(),
-                getCacheStatistics: () => text.getCacheStatistics(),
-                clearCache: () => text.clearCache(),
-                measureTextWidth: (textString, letterSpacing) => text.measureTextWidth(textString, letterSpacing)
-            };
+            return loadedFont;
         }
         static async loadAndCacheFont(fontKey, font, fontVariations, fontFeatures) {
             const tempText = new Text();
@@ -5550,6 +5608,11 @@
                 glyphLineIndex: glyphLineIndices
             };
         }
+        resetHelpers() {
+            this.geometryBuilder = undefined;
+            this.textShaper = undefined;
+            this.textLayout = undefined;
+        }
         destroy() {
             if (!this.loadedFont) {
                 return;