three-text 0.2.8 → 0.2.9

package/README.md

@@ -675,11 +675,34 @@ Creates text geometry with automatic font loading and HarfBuzz initialization
 - `getCacheStatistics()` - Cache performance data
 - `clearCache()` - Clear the glyph cache
 - `measureTextWidth(text, letterSpacing?)` - Measure text width
+- `update(options)` - Re-render with new options while preserving font/cache state
 
 **Three.js adapter (`three-text/three`) returns:**
 - `geometry: BufferGeometry` - Three.js geometry
 - Plus all the above except vertices/normals/indices/colors/glyphAttributes
 
+##### `update(options: Partial<TextOptions>): Promise<TextGeometryInfo>`
+
+Returns new geometry with updated options. Font and glyph data are cached globally by default, so performance is similar to calling `Text.create()` again; the method is provided for ergonomics when working with the same font configuration across multiple renders
+
+```javascript
+const text = await Text.create({
+  font: '/fonts/Font.ttf',
+  text: 'Hello',
+  size: 72
+});
+
+const mesh = new THREE.Mesh(text.geometry, material);
+scene.add(mesh);
+
+// Later, update the text
+const updated = await text.update({ text: 'World' });
+mesh.geometry.dispose();
+mesh.geometry = updated.geometry;
+```
+
+The method preserves custom cache instances if `maxCacheSizeMB` was specified. For most use cases, this is primarily an API convenience.
+
 ##### `Text.setHarfBuzzPath(path: string): void`
 
 **Required.** Sets the path for the HarfBuzz WASM binary. Must be called before `Text.create()`

package/dist/index.cjs

@@ -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
@@ -186,11 +186,11 @@ var FitnessClass;
     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
@@ -261,7 +261,7 @@ const DEFAULT_EMERGENCY_STRETCH_NO_HYPHEN = 0.1;
 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:
@@ -810,19 +810,22 @@ class LineBreak {
             // 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) {
@@ -832,9 +835,7 @@ class LineBreak {
                 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;
                 }
@@ -866,11 +867,12 @@ class LineBreak {
     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,
@@ -884,16 +886,16 @@ class LineBreak {
             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);
         }
@@ -960,7 +962,7 @@ class LineBreak {
         }
         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;
@@ -972,11 +974,11 @@ class LineBreak {
                 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;
@@ -1001,26 +1003,32 @@ class LineBreak {
             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;
@@ -1046,10 +1054,13 @@ class LineBreak {
                 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) {
@@ -1187,7 +1198,6 @@ class LineBreak {
         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--) {
@@ -1392,8 +1402,8 @@ 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
+    // (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);
@@ -3715,10 +3725,11 @@ class LRUCache {
     }
 }
 
+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();
@@ -3728,7 +3739,7 @@ class GlyphGeometryBuilder {
         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) {
@@ -3737,6 +3748,15 @@ class GlyphGeometryBuilder {
                 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();
@@ -4026,7 +4046,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)
+        // 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);
@@ -5064,6 +5084,54 @@ class Text {
         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)}`;
@@ -5078,17 +5146,7 @@ class Text {
         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();
@@ -5546,6 +5604,11 @@ class Text {
             glyphLineIndex: glyphLineIndices
         };
     }
+    resetHelpers() {
+        this.geometryBuilder = undefined;
+        this.textShaper = undefined;
+        this.textLayout = undefined;
+    }
     destroy() {
         if (!this.loadedFont) {
             return;

package/dist/index.d.ts

@@ -382,7 +382,12 @@ declare class Text {
     static setHarfBuzzPath(path: string): void;
     static setHarfBuzzBuffer(wasmBuffer: ArrayBuffer): void;
     static init(): Promise<HarfBuzzInstance>;
-    static create(options: TextOptions): Promise<TextGeometryInfo & Pick<Text, 'getLoadedFont' | 'getCacheStatistics' | 'clearCache' | 'measureTextWidth'>>;
+    static create(options: TextOptions): Promise<TextGeometryInfo & Pick<Text, 'getLoadedFont' | 'getCacheStatistics' | 'clearCache' | 'measureTextWidth'> & {
+        update: (options: Partial<TextOptions>) => Promise<TextGeometryInfo & Pick<Text, 'getLoadedFont' | 'getCacheStatistics' | 'clearCache' | 'measureTextWidth'> & {
+            update: (options: Partial<TextOptions>) => Promise<any>;
+        }>;
+    }>;
+    private static resolveFont;
     private static loadAndCacheFont;
     private static generateFontContentHash;
     private setLoadedFont;
@@ -402,6 +407,7 @@ declare class Text {
     getCacheStatistics(): GlyphCacheStats | null;
     clearCache(): void;
     private createGlyphAttributes;
+    private resetHelpers;
     destroy(): void;
 }