three-text 0.2.7 → 0.2.9

package/dist/index.umd.js

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.2.7
+ * three-text v0.2.9
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify
@@ -127,9 +127,6 @@
             this.metrics.length = 0;
             this.activeTimers.clear();
         }
-        reset() {
-            this.clear();
-        }
         time(name, fn, metadata) {
             if (!isLogEnabled)
                 return fn();
@@ -191,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
@@ -262,15 +259,15 @@
     const INF_BAD = 10000;
     // Non TeX default: emergency stretch for non-hyphenated text (10% of line width)
     const DEFAULT_EMERGENCY_STRETCH_NO_HYPHEN = 0.1;
-    // Another non TeX default: Single-word line detection thresholds
-    const SINGLE_WORD_WIDTH_THRESHOLD = 0.5; // Lines < 50% of width are problematic
-    const SINGLE_WORD_EMERGENCY_STRETCH_INCREMENT = 0.1; // Add 10% per iteration
+    // Another non TeX default: Short line detection thresholds
+    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:
-        //   297³ ≈ 100×2¹⁸, so (297t/s)³/2¹⁸ ≈ 100(t/s)³
+        // 297³ ≈ 100×2¹⁸, so (297t/s)³/2¹⁸ ≈ 100(t/s)³
         static badness(t, s) {
             if (t === 0)
                 return 0;
@@ -329,8 +326,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.
+        // 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 = [];
@@ -354,16 +351,214 @@
             });
             return items;
         }
+        // Chinese, Japanese, and Korean character ranges
+        static isCJK(char) {
+            const code = char.codePointAt(0);
+            if (code === undefined)
+                return false;
+            return (
+            // CJK Unified Ideographs
+            (code >= 0x4e00 && code <= 0x9fff) ||
+                // CJK Extension A
+                (code >= 0x3400 && code <= 0x4dbf) ||
+                // CJK Extension B
+                (code >= 0x20000 && code <= 0x2a6df) ||
+                // CJK Extension C
+                (code >= 0x2a700 && code <= 0x2b73f) ||
+                // CJK Extension D
+                (code >= 0x2b740 && code <= 0x2b81f) ||
+                // CJK Extension E
+                (code >= 0x2b820 && code <= 0x2ceaf) ||
+                // CJK Compatibility Ideographs
+                (code >= 0xf900 && code <= 0xfaff) ||
+                // Hiragana
+                (code >= 0x3040 && code <= 0x309f) ||
+                // Katakana
+                (code >= 0x30a0 && code <= 0x30ff) ||
+                // Hangul Syllables
+                (code >= 0xac00 && code <= 0xd7af) ||
+                // Hangul Jamo
+                (code >= 0x1100 && code <= 0x11ff) ||
+                // Hangul Compatibility Jamo
+                (code >= 0x3130 && code <= 0x318f) ||
+                // Hangul Jamo Extended-A
+                (code >= 0xa960 && code <= 0xa97f) ||
+                // Hangul Jamo Extended-B
+                (code >= 0xd7b0 && code <= 0xd7ff) ||
+                // Halfwidth and Fullwidth Forms (Korean)
+                (code >= 0xffa0 && code <= 0xffdc));
+        }
+        // Closing punctuation where line breaks are prohibited (UAX #14 LB30, JIS X 4051)
+        static isCJClosingPunctuation(char) {
+            const code = char.charCodeAt(0);
+            return (code === 0x3001 || // 、
+                code === 0x3002 || // 。
+                code === 0xff0c || // ，
+                code === 0xff0e || // ．
+                code === 0xff1a || // ：
+                code === 0xff1b || // ；
+                code === 0xff01 || // ！
+                code === 0xff1f || // ？
+                code === 0xff09 || // ）
+                code === 0x3011 || // 】
+                code === 0xff5d || // ｝
+                code === 0x300d || // 」
+                code === 0x300f || // 』
+                code === 0x3009 || // 〉
+                code === 0x300b || // 》
+                code === 0x3015 || // 〕
+                code === 0x3017 || // 〗
+                code === 0x3019 || // 〙
+                code === 0x301b || // 〛
+                code === 0x30fc || // ー
+                code === 0x2014 || // —
+                code === 0x2026 || // …
+                code === 0x2025 // ‥
+            );
+        }
+        // Opening punctuation where line breaks are prohibited (UAX #14 LB30a, JIS X 4051)
+        static isCJOpeningPunctuation(char) {
+            const code = char.charCodeAt(0);
+            return (code === 0xff08 || // （
+                code === 0x3010 || // 【
+                code === 0xff5b || // ｛
+                code === 0x300c || // 「
+                code === 0x300e || // 『
+                code === 0x3008 || // 〈
+                code === 0x300a || // 《
+                code === 0x3014 || // 〔
+                code === 0x3016 || // 〖
+                code === 0x3018 || // 〘
+                code === 0x301a // 〚
+            );
+        }
+        static isCJPunctuation(char) {
+            return (this.isCJClosingPunctuation(char) || this.isCJOpeningPunctuation(char));
+        }
+        // CJK (Chinese/Japanese/Korean) character-level itemization with inter-character glue
+        static itemizeCJKText(text, measureText, context, startOffset = 0, glueParams) {
+            const items = [];
+            const chars = Array.from(text);
+            let textPosition = startOffset;
+            // Inter-character glue parameters
+            let glueWidth;
+            let glueStretch;
+            let glueShrink;
+            if (glueParams) {
+                glueWidth = glueParams.width;
+                glueStretch = glueParams.stretch;
+                glueShrink = glueParams.shrink;
+            }
+            else {
+                const baseCharWidth = measureText('字');
+                glueWidth = 0;
+                glueStretch = baseCharWidth * 0.04;
+                glueShrink = baseCharWidth * 0.04;
+            }
+            for (let i = 0; i < chars.length; i++) {
+                const char = chars[i];
+                const nextChar = i < chars.length - 1 ? chars[i + 1] : null;
+                if (/\s/.test(char)) {
+                    const width = measureText(char);
+                    items.push({
+                        type: ItemType.GLUE,
+                        width,
+                        stretch: width * SPACE_STRETCH_RATIO,
+                        shrink: width * SPACE_SHRINK_RATIO,
+                        text: char,
+                        originIndex: textPosition
+                    });
+                    textPosition += char.length;
+                    continue;
+                }
+                items.push({
+                    type: ItemType.BOX,
+                    width: measureText(char),
+                    text: char,
+                    originIndex: textPosition
+                });
+                textPosition += char.length;
+                // Glue after a box creates a break opportunity
+                // Must not add glue where breaks are prohibited by Chinese/Japanese line breaking rules
+                if (nextChar && !/\s/.test(nextChar)) {
+                    let canBreak = true;
+                    if (this.isCJClosingPunctuation(nextChar)) {
+                        canBreak = false;
+                    }
+                    if (this.isCJOpeningPunctuation(char)) {
+                        canBreak = false;
+                    }
+                    // Avoid stretch between consecutive punctuation (？" or 。」)
+                    const isPunctPair = this.isCJPunctuation(char) && this.isCJPunctuation(nextChar);
+                    if (canBreak && !isPunctPair) {
+                        items.push({
+                            type: ItemType.GLUE,
+                            width: glueWidth,
+                            stretch: glueStretch,
+                            shrink: glueShrink,
+                            text: '',
+                            originIndex: textPosition
+                        });
+                    }
+                }
+            }
+            return items;
+        }
         static itemizeParagraph(text, measureText, hyphenate, language, availablePatterns, lefthyphenmin, righthyphenmin, context) {
             const items = [];
-            // First split into words and spaces
+            const chars = Array.from(text);
+            // Calculate CJK glue parameters once for consistency across all segments
+            const baseCharWidth = measureText('字');
+            const cjkGlueParams = {
+                width: 0,
+                stretch: baseCharWidth * 0.04,
+                shrink: baseCharWidth * 0.04
+            };
+            let buffer = '';
+            let bufferStart = 0;
+            let bufferScript = null;
+            let textPosition = 0;
+            const flushBuffer = () => {
+                if (buffer.length === 0)
+                    return;
+                if (bufferScript === 'cjk') {
+                    const cjkItems = this.itemizeCJKText(buffer, measureText, context, bufferStart, cjkGlueParams);
+                    items.push(...cjkItems);
+                }
+                else {
+                    const wordItems = this.itemizeWordBased(buffer, bufferStart, measureText, hyphenate, language, availablePatterns, lefthyphenmin, righthyphenmin, context);
+                    items.push(...wordItems);
+                }
+                buffer = '';
+                bufferScript = null;
+            };
+            for (let i = 0; i < chars.length; i++) {
+                const char = chars[i];
+                const isCJKChar = this.isCJK(char);
+                const currentScript = isCJKChar ? 'cjk' : 'word';
+                if (bufferScript !== null && bufferScript !== currentScript) {
+                    flushBuffer();
+                    bufferStart = textPosition;
+                }
+                if (bufferScript === null) {
+                    bufferScript = currentScript;
+                    bufferStart = textPosition;
+                }
+                buffer += char;
+                textPosition += char.length;
+            }
+            flushBuffer();
+            return items;
+        }
+        // Word-based itemization for alphabetic scripts (Latin, Cyrillic, Greek, etc.)
+        static itemizeWordBased(text, startOffset, measureText, hyphenate, language, availablePatterns, lefthyphenmin, righthyphenmin, context) {
+            const items = [];
             const tokens = text.match(/\S+|\s+/g) || [];
             let currentIndex = 0;
             for (let i = 0; i < tokens.length; i++) {
                 const token = tokens[i];
-                const tokenStartIndex = currentIndex;
+                const tokenStartIndex = startOffset + currentIndex;
                 if (/\s+/.test(token)) {
-                    // Handle spaces
                     const width = measureText(token);
                     items.push({
                         type: ItemType.GLUE,
@@ -376,22 +571,19 @@
                     currentIndex += token.length;
                 }
                 else {
-                    // Process word, splitting on explicit hyphens
-                    // Split on hyphens while keeping them in the result
                     const segments = token.split(/(-)/);
                     let segmentIndex = tokenStartIndex;
                     for (let j = 0; j < segments.length; j++) {
                         const segment = segments[j];
                         if (!segment)
-                            continue; // Skip empty segments
+                            continue;
                         if (segment === '-') {
-                            // Handle explicit hyphen as discretionary break
                             items.push({
                                 type: ItemType.DISCRETIONARY,
-                                width: measureText('-'), // Width of hyphen in normal flow
-                                preBreak: '-', // Hyphen appears before break
-                                postBreak: '', // Nothing after break
-                                noBreak: '-', // Hyphen if no break
+                                width: measureText('-'),
+                                preBreak: '-',
+                                postBreak: '',
+                                noBreak: '-',
                                 preBreakWidth: measureText('-'),
                                 penalty: context?.exHyphenPenalty ?? DEFAULT_EX_HYPHEN_PENALTY,
                                 flagged: true,
@@ -401,8 +593,6 @@
                             segmentIndex += 1;
                         }
                         else {
-                            // Process non-hyphen segment
-                            // First handle soft hyphens (U+00AD)
                             if (segment.includes('\u00AD')) {
                                 const partsWithMarkers = segment.split('\u00AD');
                                 let runningIndex = 0;
@@ -420,23 +610,23 @@
                                     if (k < partsWithMarkers.length - 1) {
                                         items.push({
                                             type: ItemType.DISCRETIONARY,
-                                            width: 0, // No width in normal flow
-                                            preBreak: '-', // Hyphen appears before break
-                                            postBreak: '', // Nothing after break
-                                            noBreak: '', // Nothing if no break (word continues)
+                                            width: 0,
+                                            preBreak: '-',
+                                            postBreak: '',
+                                            noBreak: '',
                                             preBreakWidth: measureText('-'),
                                             penalty: context?.hyphenPenalty ?? DEFAULT_HYPHEN_PENALTY,
                                             flagged: true,
                                             text: '',
                                             originIndex: segmentIndex + runningIndex
                                         });
-                                        runningIndex += 1; // Account for the soft hyphen character
+                                        runningIndex += 1;
                                     }
                                 }
                             }
                             else if (hyphenate &&
-                                segment.length >= lefthyphenmin + righthyphenmin) {
-                                // Apply hyphenation patterns only to segments between explicit hyphens
+                                segment.length >= lefthyphenmin + righthyphenmin &&
+                                /^\p{L}+$/u.test(segment)) {
                                 const hyphenPoints = LineBreak.findHyphenationPoints(segment, language, availablePatterns, lefthyphenmin, righthyphenmin);
                                 if (hyphenPoints.length > 0) {
                                     let lastPoint = 0;
@@ -450,10 +640,10 @@
                                         });
                                         items.push({
                                             type: ItemType.DISCRETIONARY,
-                                            width: 0, // No width in normal flow
-                                            preBreak: '-', // Hyphen appears before break
-                                            postBreak: '', // Nothing after break
-                                            noBreak: '', // Nothing if no break (word continues)
+                                            width: 0,
+                                            preBreak: '-',
+                                            postBreak: '',
+                                            noBreak: '',
                                             preBreakWidth: measureText('-'),
                                             penalty: context?.hyphenPenalty ?? DEFAULT_HYPHEN_PENALTY,
                                             flagged: true,
@@ -471,7 +661,6 @@
                                     });
                                 }
                                 else {
-                                    // No hyphenation points, add as single box
                                     items.push({
                                         type: ItemType.BOX,
                                         width: measureText(segment),
@@ -481,7 +670,6 @@
                                 }
                             }
                             else {
-                                // No hyphenation, add as single box
                                 items.push({
                                     type: ItemType.BOX,
                                     width: measureText(segment),
@@ -497,27 +685,22 @@
             }
             return items;
         }
-        // Detect if breakpoints create problematic single-word lines
-        static hasSingleWordLines(items, breakpoints, lineWidth) {
+        // Detect if breakpoints create problematic short lines
+        static hasShortLines(items, breakpoints, lineWidth, threshold) {
             // Check each line segment (except the last, which can naturally be short)
             let lineStart = 0;
             for (let i = 0; i < breakpoints.length - 1; i++) {
                 const breakpoint = breakpoints[i];
-                // Count glue items (spaces) between line start and breakpoint
-                let glueCount = 0;
                 let totalWidth = 0;
                 for (let j = lineStart; j < breakpoint; j++) {
-                    if (items[j].type === ItemType.GLUE) {
-                        glueCount++;
-                    }
                     if (items[j].type !== ItemType.PENALTY) {
                         totalWidth += items[j].width;
                     }
                 }
-                // Single word line = no glue items
-                if (glueCount === 0 && totalWidth > 0) {
+                // Check if line is narrow relative to target width
+                if (totalWidth > 0) {
                     const widthRatio = totalWidth / lineWidth;
-                    if (widthRatio < SINGLE_WORD_WIDTH_THRESHOLD) {
+                    if (widthRatio < threshold) {
                         return true;
                     }
                 }
@@ -532,7 +715,7 @@
                 align: options.align || 'left',
                 hyphenate: options.hyphenate || false
             });
-            const { text, width, align = 'left', direction = 'ltr', hyphenate = false, language = 'en-us', respectExistingBreaks = true, measureText, hyphenationPatterns, unitsPerEm, tolerance = DEFAULT_TOLERANCE, pretolerance = DEFAULT_PRETOLERANCE, emergencyStretch = DEFAULT_EMERGENCY_STRETCH, autoEmergencyStretch, lefthyphenmin = DEFAULT_LEFT_HYPHEN_MIN, righthyphenmin = DEFAULT_RIGHT_HYPHEN_MIN, linepenalty = DEFAULT_LINE_PENALTY, adjdemerits = DEFAULT_FITNESS_DIFF_DEMERITS, hyphenpenalty = DEFAULT_HYPHEN_PENALTY, exhyphenpenalty = DEFAULT_EX_HYPHEN_PENALTY, doublehyphendemerits = DEFAULT_DOUBLE_HYPHEN_DEMERITS, looseness = 0, disableSingleWordDetection = false } = options;
+            const { text, width, align = 'left', direction = 'ltr', hyphenate = false, language = 'en-us', respectExistingBreaks = true, measureText, hyphenationPatterns, unitsPerEm, tolerance = DEFAULT_TOLERANCE, pretolerance = DEFAULT_PRETOLERANCE, emergencyStretch = DEFAULT_EMERGENCY_STRETCH, autoEmergencyStretch, lefthyphenmin = DEFAULT_LEFT_HYPHEN_MIN, righthyphenmin = DEFAULT_RIGHT_HYPHEN_MIN, linepenalty = DEFAULT_LINE_PENALTY, adjdemerits = DEFAULT_FITNESS_DIFF_DEMERITS, hyphenpenalty = DEFAULT_HYPHEN_PENALTY, exhyphenpenalty = DEFAULT_EX_HYPHEN_PENALTY, doublehyphendemerits = DEFAULT_DOUBLE_HYPHEN_DEMERITS, looseness = 0, disableShortLineDetection = false, shortLineThreshold = SHORT_LINE_WIDTH_THRESHOLD } = options;
             // Handle multiple paragraphs by processing each independently
             if (respectExistingBreaks && text.includes('\n')) {
                 const paragraphs = text.split('\n');
@@ -611,56 +794,50 @@
                     }
                 ];
             }
-            // Itemize text once, including all potential hyphenation points
-            const allItems = LineBreak.itemizeText(text, measureText, useHyphenation, language, hyphenationPatterns, lefthyphenmin, righthyphenmin, context);
+            // Itemize without hyphenation first (TeX approach: only compute if needed)
+            const allItems = LineBreak.itemizeText(text, measureText, false, language, hyphenationPatterns, lefthyphenmin, righthyphenmin, context);
             if (allItems.length === 0) {
                 return [];
             }
-            // Iteratively increase emergency stretch to eliminate short single-word lines.
-            // Post-processing approach preserves TeX algorithm integrity while itemization
-            // (the expensive part) happens once
             const MAX_ITERATIONS = 5;
             let iteration = 0;
             let currentEmergencyStretch = initialEmergencyStretch;
             let resultLines = null;
-            const singleWordDetectionEnabled = !disableSingleWordDetection;
+            const shortLineDetectionEnabled = !disableShortLineDetection;
             while (iteration < MAX_ITERATIONS) {
-                // Three-pass approach for optimal line breaking:
-                // First pass: Try without hyphenation using pretolerance (fast)
-                // Second pass: Enable hyphenation if available, use tolerance (quality)
-                // Final pass: Emergency stretch for difficult paragraphs (last resort)
+                // Three-pass approach matching TeX:
+                // First pass: without hyphenation (pretolerance)
+                // Second pass: with hyphenation, only if first pass fails (tolerance)
+                // Emergency pass: additional stretch as last resort
                 // First pass: no hyphenation
-                let currentItems = useHyphenation
-                    ? allItems.filter((item) => item.type !== ItemType.DISCRETIONARY ||
-                        item.penalty !==
-                            (context?.hyphenPenalty ?? DEFAULT_HYPHEN_PENALTY))
-                    : allItems;
+                let currentItems = allItems;
                 let breaks = LineBreak.findBreakpoints(currentItems, width, pretolerance, looseness, false, 0, context);
-                // Second pass: with hyphenation
+                // Second pass: with hyphenation if first pass failed
                 if (breaks.length === 0 && useHyphenation) {
-                    currentItems = allItems;
+                    const itemsWithHyphenation = LineBreak.itemizeText(text, measureText, true, language, hyphenationPatterns, lefthyphenmin, righthyphenmin, context);
+                    currentItems = itemsWithHyphenation;
                     breaks = LineBreak.findBreakpoints(currentItems, width, tolerance, looseness, false, 0, context);
                 }
-                // Final pass: emergency stretch
+                // Emergency pass: add emergency stretch to background stretchability
                 if (breaks.length === 0) {
-                    currentItems = allItems;
-                    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) {
                     const cumulativeWidths = LineBreak.computeCumulativeWidths(currentItems);
                     resultLines = LineBreak.createLines(text, currentItems, breaks, width, align, direction, cumulativeWidths, context);
-                    // Check for single-word lines if detection is enabled
-                    if (singleWordDetectionEnabled &&
+                    // Check for short lines if detection is enabled
+                    if (shortLineDetectionEnabled &&
                         breaks.length > 1 &&
-                        LineBreak.hasSingleWordLines(currentItems, breaks, width)) {
-                        // Increase emergency stretch and try again
-                        currentEmergencyStretch +=
-                            width * SINGLE_WORD_EMERGENCY_STRETCH_INCREMENT;
+                        LineBreak.hasShortLines(currentItems, breaks, width, shortLineThreshold)) {
+                        // Retry with more emergency stretch to push words to next line
                         iteration++;
                         continue;
                     }
@@ -692,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,
@@ -710,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);
             }
@@ -786,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;
@@ -798,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;
@@ -827,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;
@@ -872,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) {
@@ -994,6 +1181,8 @@
                 const item = items[i];
                 widths[i + 1] = widths[i] + item.width;
                 if (item.type === ItemType.PENALTY) {
+                    stretches[i + 1] = stretches[i];
+                    shrinks[i + 1] = shrinks[i];
                     minWidths[i + 1] = minWidths[i];
                 }
                 else if (item.type === ItemType.GLUE) {
@@ -1011,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--) {
@@ -1216,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);
@@ -1244,7 +1432,7 @@
             this.loadedFont = loadedFont;
         }
         computeLines(options) {
-            const { text, width, align, direction, hyphenate, language, respectExistingBreaks, tolerance, pretolerance, emergencyStretch, autoEmergencyStretch, hyphenationPatterns, lefthyphenmin, righthyphenmin, linepenalty, adjdemerits, hyphenpenalty, exhyphenpenalty, doublehyphendemerits, looseness, disableSingleWordDetection, letterSpacing } = options;
+            const { text, width, align, direction, hyphenate, language, respectExistingBreaks, tolerance, pretolerance, emergencyStretch, autoEmergencyStretch, hyphenationPatterns, lefthyphenmin, righthyphenmin, linepenalty, adjdemerits, hyphenpenalty, exhyphenpenalty, doublehyphendemerits, looseness, disableShortLineDetection, shortLineThreshold, letterSpacing } = options;
             let lines;
             if (width) {
                 // Line breaking uses a measureText function that already includes letterSpacing,
@@ -1270,7 +1458,8 @@
                     exhyphenpenalty,
                     doublehyphendemerits,
                     looseness,
-                    disableSingleWordDetection,
+                    disableShortLineDetection,
+                    shortLineThreshold,
                     unitsPerEm: this.loadedFont.upem,
                     measureText: (textToMeasure) => TextMeasurer.measureTextWidth(this.loadedFont, textToMeasure, letterSpacing // Letter spacing included in width measurements
                     )
@@ -3540,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();
@@ -3553,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) {
@@ -3562,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();
@@ -3851,9 +4050,10 @@
             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);
             for (let i = 0; i < glyphInfos.length; i++) {
                 const glyph = glyphInfos[i];
                 const isWhitespace = /\s/.test(lineInfo.text[glyph.cl]);
@@ -3899,6 +4099,29 @@
                 if (isWhitespace) {
                     cursor.x += spaceAdjustment;
                 }
+                // CJK glue adjustment (must match exactly where LineBreak adds glue)
+                if (cjkAdjustment !== 0 && i < glyphInfos.length - 1 && !isWhitespace) {
+                    const currentChar = lineInfo.text[glyph.cl];
+                    const nextGlyph = glyphInfos[i + 1];
+                    const nextChar = lineInfo.text[nextGlyph.cl];
+                    const isCJKChar = LineBreak.isCJK(currentChar);
+                    const nextIsCJKChar = nextChar && LineBreak.isCJK(nextChar);
+                    if (isCJKChar && nextIsCJKChar) {
+                        let shouldApply = true;
+                        if (LineBreak.isCJClosingPunctuation(nextChar)) {
+                            shouldApply = false;
+                        }
+                        if (LineBreak.isCJOpeningPunctuation(currentChar)) {
+                            shouldApply = false;
+                        }
+                        if (LineBreak.isCJPunctuation(currentChar) && LineBreak.isCJPunctuation(nextChar)) {
+                            shouldApply = false;
+                        }
+                        if (shouldApply) {
+                            cursor.x += cjkAdjustment;
+                        }
+                    }
+                }
             }
             if (currentClusterGlyphs.length > 0) {
                 clusters.push({
@@ -3931,6 +4154,23 @@
             }
             return spaceAdjustment;
         }
+        calculateCJKAdjustment(lineInfo, align) {
+            if (lineInfo.adjustmentRatio === undefined ||
+                align !== 'justify' ||
+                lineInfo.isLastLine) {
+                return 0;
+            }
+            const baseCharWidth = this.loadedFont.upem;
+            const glueStretch = baseCharWidth * 0.04;
+            const glueShrink = baseCharWidth * 0.04;
+            if (lineInfo.adjustmentRatio > 0) {
+                return lineInfo.adjustmentRatio * glueStretch;
+            }
+            else if (lineInfo.adjustmentRatio < 0) {
+                return lineInfo.adjustmentRatio * glueShrink;
+            }
+            return 0;
+        }
         clearCache() {
             this.geometryBuilder.clearCache();
         }
@@ -4848,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)}`;
@@ -4862,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();
@@ -5048,7 +5326,7 @@
                 throw new Error('Font not loaded. Use Text.create() with a font option');
             }
             const { text, size = 72, depth = 0, lineHeight = 1.0, letterSpacing = 0, layout = {} } = options;
-            const { width, direction = 'ltr', align = direction === 'rtl' ? 'right' : 'left', respectExistingBreaks = true, hyphenate = true, language = 'en-us', tolerance = DEFAULT_TOLERANCE, pretolerance = DEFAULT_PRETOLERANCE, emergencyStretch = DEFAULT_EMERGENCY_STRETCH, autoEmergencyStretch, hyphenationPatterns, lefthyphenmin, righthyphenmin, linepenalty, adjdemerits, hyphenpenalty, exhyphenpenalty, doublehyphendemerits, looseness, disableSingleWordDetection } = layout;
+            const { width, direction = 'ltr', align = direction === 'rtl' ? 'right' : 'left', respectExistingBreaks = true, hyphenate = true, language = 'en-us', tolerance = DEFAULT_TOLERANCE, pretolerance = DEFAULT_PRETOLERANCE, emergencyStretch = DEFAULT_EMERGENCY_STRETCH, autoEmergencyStretch, hyphenationPatterns, lefthyphenmin, righthyphenmin, linepenalty, adjdemerits, hyphenpenalty, exhyphenpenalty, doublehyphendemerits, looseness, disableShortLineDetection, shortLineThreshold } = layout;
             let widthInFontUnits;
             if (width !== undefined) {
                 widthInFontUnits = width * (this.loadedFont.upem / size);
@@ -5078,7 +5356,8 @@
                 exhyphenpenalty,
                 doublehyphendemerits,
                 looseness,
-                disableSingleWordDetection,
+                disableShortLineDetection,
+                shortLineThreshold,
                 letterSpacing
             });
             const metrics = FontMetadataExtractor.getVerticalMetrics(this.loadedFont.metrics);
@@ -5329,6 +5608,11 @@
                 glyphLineIndex: glyphLineIndices
             };
         }
+        resetHelpers() {
+            this.geometryBuilder = undefined;
+            this.textShaper = undefined;
+            this.textLayout = undefined;
+        }
         destroy() {
             if (!this.loadedFont) {
                 return;