three-text 0.2.6 → 0.2.8

package/dist/index.cjs

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.2.6
+ * three-text v0.2.8
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify
@@ -257,15 +257,15 @@ const DEFAULT_RIGHT_HYPHEN_MIN = 4;
 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)
     // 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;
@@ -324,6 +324,8 @@ class LineBreak {
         const filteredPoints = hyphenPoints.filter((pos) => pos >= lefthyphenmin && word.length - pos >= righthyphenmin);
         return filteredPoints;
     }
+    // Converts text into items (boxes, glues, penalties) for line breaking
+    // The measureText function should return widths that include any letter spacing
     static itemizeText(text, measureText, // function to measure text width
     hyphenate = false, language = 'en-us', availablePatterns, lefthyphenmin = DEFAULT_LEFT_HYPHEN_MIN, righthyphenmin = DEFAULT_RIGHT_HYPHEN_MIN, context) {
         const items = [];
@@ -347,16 +349,214 @@ class LineBreak {
         });
         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,
@@ -369,22 +569,19 @@ class LineBreak {
                 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,
@@ -394,8 +591,6 @@ class LineBreak {
                         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;
@@ -413,23 +608,23 @@ class LineBreak {
                                 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;
@@ -443,10 +638,10 @@ class LineBreak {
                                     });
                                     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,
@@ -464,7 +659,6 @@ class LineBreak {
                                 });
                             }
                             else {
-                                // No hyphenation points, add as single box
                                 items.push({
                                     type: ItemType.BOX,
                                     width: measureText(segment),
@@ -474,7 +668,6 @@ class LineBreak {
                             }
                         }
                         else {
-                            // No hyphenation, add as single box
                             items.push({
                                 type: ItemType.BOX,
                                 width: measureText(segment),
@@ -490,27 +683,22 @@ class LineBreak {
         }
         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;
                 }
             }
@@ -525,7 +713,7 @@ class LineBreak {
             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');
@@ -604,39 +792,32 @@ class LineBreak {
                 }
             ];
         }
-        // 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: compute hyphenation only if needed
             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: use currentItems as-is (preserves hyphenation from pass 2 if it ran)
             if (breaks.length === 0) {
-                currentItems = allItems;
                 breaks = LineBreak.findBreakpoints(currentItems, width, INF_BAD + 1, looseness, true, currentEmergencyStretch, context);
             }
             // Force with infinite tolerance if still no breaks found
@@ -647,13 +828,13 @@ class LineBreak {
             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)) {
+                    LineBreak.hasShortLines(currentItems, breaks, width, shortLineThreshold)) {
                     // Increase emergency stretch and try again
                     currentEmergencyStretch +=
-                        width * SINGLE_WORD_EMERGENCY_STRETCH_INCREMENT;
+                        width * SHORT_LINE_EMERGENCY_STRETCH_INCREMENT;
                     iteration++;
                     continue;
                 }
@@ -987,6 +1168,8 @@ class LineBreak {
             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) {
@@ -1208,6 +1391,9 @@ function convertFontFeaturesToString(features) {
 }
 
 class TextMeasurer {
+    // Measures text width including letter spacing
+    // Letter spacing is added uniformly after each glyph during measurement,
+    // so the widths given to the line-breaking algorithm already account for tracking
     static measureTextWidth(loadedFont, text, letterSpacing = 0) {
         const buffer = loadedFont.hb.createBuffer();
         buffer.addText(text);
@@ -1234,9 +1420,11 @@ class TextLayout {
         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,
+            // so widths passed into LineBreak.breakText account for tracking
             lines = LineBreak.breakText({
                 text,
                 width,
@@ -1258,9 +1446,11 @@ class TextLayout {
                 exhyphenpenalty,
                 doublehyphendemerits,
                 looseness,
-                disableSingleWordDetection,
+                disableShortLineDetection,
+                shortLineThreshold,
                 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 {
@@ -2225,7 +2415,11 @@ class Tessellator {
         if (removeOverlaps) {
             logger.log('Two-pass: boundary extraction then triangulation');
             // Extract boundaries to remove overlaps
+            perfLogger.start('Tessellator.boundaryPass', {
+                contourCount: contours.length
+            });
             const boundaryResult = this.performTessellation(contours, 'boundary');
+            perfLogger.end('Tessellator.boundaryPass');
             if (!boundaryResult) {
                 logger.warn('libtess returned empty result from boundary pass');
                 return { triangles: { vertices: [], indices: [] }, contours: [] };
@@ -2238,7 +2432,11 @@ class Tessellator {
             logger.log(`Single-pass triangulation for ${isCFF ? 'CFF' : 'TTF'}`);
         }
         // Triangulate the contours
+        perfLogger.start('Tessellator.triangulationPass', {
+            contourCount: contours.length
+        });
         const triangleResult = this.performTessellation(contours, 'triangles');
+        perfLogger.end('Tessellator.triangulationPass');
         if (!triangleResult) {
             const warning = removeOverlaps
                 ? 'libtess returned empty result from triangulation pass'
@@ -2425,10 +2623,16 @@ const OVERLAP_EPSILON = 1e-3;
 class BoundaryClusterer {
     constructor() { }
     cluster(glyphContoursList, positions) {
+        perfLogger.start('BoundaryClusterer.cluster', {
+            glyphCount: glyphContoursList.length
+        });
         if (glyphContoursList.length === 0) {
+            perfLogger.end('BoundaryClusterer.cluster');
             return [];
         }
-        return this.clusterSweepLine(glyphContoursList, positions);
+        const result = this.clusterSweepLine(glyphContoursList, positions);
+        perfLogger.end('BoundaryClusterer.cluster');
+        return result;
     }
     clusterSweepLine(glyphContoursList, positions) {
         const n = glyphContoursList.length;
@@ -3069,6 +3273,11 @@ class GlyphContourCollector {
         this.currentGlyphBounds.max.set(-Infinity, -Infinity);
         // Record position for this glyph
         this.glyphPositions.push(this.currentPosition.clone());
+        // Time polygonization + path optimization per glyph
+        perfLogger.start('Glyph.polygonizeAndOptimize', {
+            glyphId,
+            textIndex
+        });
     }
     finishGlyph() {
         if (this.currentPath) {
@@ -3092,6 +3301,8 @@ class GlyphContourCollector {
             // Track textIndex separately
             this.glyphTextIndices.push(this.currentTextIndex);
         }
+        // Stop timing for this glyph (even if it ended up empty)
+        perfLogger.end('Glyph.polygonizeAndOptimize');
         this.currentGlyphPaths = [];
     }
     onMoveTo(x, y) {
@@ -3326,6 +3537,184 @@ class DrawCallbackHandler {
     }
 }
 
+// Generic LRU (Least Recently Used) cache with optional memory-based eviction
+class LRUCache {
+    constructor(options = {}) {
+        this.cache = new Map();
+        this.head = null;
+        this.tail = null;
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            evictions: 0,
+            size: 0,
+            memoryUsage: 0
+        };
+        this.options = {
+            maxEntries: options.maxEntries ?? Infinity,
+            maxMemoryBytes: options.maxMemoryBytes ?? Infinity,
+            calculateSize: options.calculateSize ?? (() => 0),
+            onEvict: options.onEvict
+        };
+    }
+    get(key) {
+        const node = this.cache.get(key);
+        if (node) {
+            this.stats.hits++;
+            this.moveToHead(node);
+            return node.value;
+        }
+        else {
+            this.stats.misses++;
+            return undefined;
+        }
+    }
+    has(key) {
+        return this.cache.has(key);
+    }
+    set(key, value) {
+        // If key already exists, update it
+        const existingNode = this.cache.get(key);
+        if (existingNode) {
+            const oldSize = this.options.calculateSize(existingNode.value);
+            const newSize = this.options.calculateSize(value);
+            this.stats.memoryUsage = this.stats.memoryUsage - oldSize + newSize;
+            existingNode.value = value;
+            this.moveToHead(existingNode);
+            return;
+        }
+        const size = this.options.calculateSize(value);
+        // Evict entries if we exceed limits
+        this.evictIfNeeded(size);
+        // Create new node
+        const node = {
+            key,
+            value,
+            prev: null,
+            next: null
+        };
+        this.cache.set(key, node);
+        this.addToHead(node);
+        this.stats.size = this.cache.size;
+        this.stats.memoryUsage += size;
+    }
+    delete(key) {
+        const node = this.cache.get(key);
+        if (!node)
+            return false;
+        const size = this.options.calculateSize(node.value);
+        this.removeNode(node);
+        this.cache.delete(key);
+        this.stats.size = this.cache.size;
+        this.stats.memoryUsage -= size;
+        if (this.options.onEvict) {
+            this.options.onEvict(key, node.value);
+        }
+        return true;
+    }
+    clear() {
+        if (this.options.onEvict) {
+            for (const [key, node] of this.cache) {
+                this.options.onEvict(key, node.value);
+            }
+        }
+        this.cache.clear();
+        this.head = null;
+        this.tail = null;
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            evictions: 0,
+            size: 0,
+            memoryUsage: 0
+        };
+    }
+    getStats() {
+        const total = this.stats.hits + this.stats.misses;
+        const hitRate = total > 0 ? (this.stats.hits / total) * 100 : 0;
+        const memoryUsageMB = this.stats.memoryUsage / (1024 * 1024);
+        return {
+            ...this.stats,
+            hitRate,
+            memoryUsageMB
+        };
+    }
+    keys() {
+        const keys = [];
+        let current = this.head;
+        while (current) {
+            keys.push(current.key);
+            current = current.next;
+        }
+        return keys;
+    }
+    get size() {
+        return this.cache.size;
+    }
+    evictIfNeeded(requiredSize) {
+        // Evict by entry count
+        while (this.cache.size >= this.options.maxEntries && this.tail) {
+            this.evictTail();
+        }
+        // Evict by memory usage
+        if (this.options.maxMemoryBytes < Infinity) {
+            while (this.tail &&
+                this.stats.memoryUsage + requiredSize > this.options.maxMemoryBytes) {
+                this.evictTail();
+            }
+        }
+    }
+    evictTail() {
+        if (!this.tail)
+            return;
+        const nodeToRemove = this.tail;
+        const size = this.options.calculateSize(nodeToRemove.value);
+        this.removeTail();
+        this.cache.delete(nodeToRemove.key);
+        this.stats.size = this.cache.size;
+        this.stats.memoryUsage -= size;
+        this.stats.evictions++;
+        if (this.options.onEvict) {
+            this.options.onEvict(nodeToRemove.key, nodeToRemove.value);
+        }
+    }
+    addToHead(node) {
+        if (!this.head) {
+            this.head = this.tail = node;
+        }
+        else {
+            node.next = this.head;
+            this.head.prev = node;
+            this.head = node;
+        }
+    }
+    removeNode(node) {
+        if (node.prev) {
+            node.prev.next = node.next;
+        }
+        else {
+            this.head = node.next;
+        }
+        if (node.next) {
+            node.next.prev = node.prev;
+        }
+        else {
+            this.tail = node.prev;
+        }
+    }
+    removeTail() {
+        if (this.tail) {
+            this.removeNode(this.tail);
+        }
+    }
+    moveToHead(node) {
+        if (node === this.head)
+            return;
+        this.removeNode(node);
+        this.addToHead(node);
+    }
+}
+
 class GlyphGeometryBuilder {
     constructor(cache, loadedFont) {
         this.fontId = 'default';
@@ -3338,6 +3727,16 @@ class GlyphGeometryBuilder {
         this.collector = new GlyphContourCollector();
         this.drawCallbacks = new DrawCallbackHandler();
         this.drawCallbacks.createDrawFuncs(this.loadedFont, this.collector);
+        this.contourCache = new LRUCache({
+            maxEntries: 1000,
+            calculateSize: (contours) => {
+                let size = 0;
+                for (const path of contours.paths) {
+                    size += path.points.length * 16; // Vec2 = 2 floats * 8 bytes
+                }
+                return size + 64; // bounds overhead
+            }
+        });
     }
     getOptimizationStats() {
         return this.collector.getOptimizationStats();
@@ -3482,30 +3881,37 @@ class GlyphGeometryBuilder {
         };
     }
     getContoursForGlyph(glyphId) {
+        const cached = this.contourCache.get(glyphId);
+        if (cached) {
+            return cached;
+        }
         this.collector.reset();
         this.collector.beginGlyph(glyphId, 0);
         this.loadedFont.module.exports.hb_font_draw_glyph(this.loadedFont.font.ptr, glyphId, this.drawCallbacks.getDrawFuncsPtr(), 0);
         this.collector.finishGlyph();
         const collected = this.collector.getCollectedGlyphs()[0];
-        // Return empty contours for glyphs with no paths (e.g., space, zero-width characters)
-        if (!collected) {
-            return {
-                glyphId,
-                paths: [],
-                bounds: {
-                    min: { x: 0, y: 0 },
-                    max: { x: 0, y: 0 }
-                }
-            };
-        }
-        return collected;
+        const contours = collected || {
+            glyphId,
+            paths: [],
+            bounds: {
+                min: { x: 0, y: 0 },
+                max: { x: 0, y: 0 }
+            }
+        };
+        this.contourCache.set(glyphId, contours);
+        return contours;
     }
     tessellateGlyphCluster(paths, depth, isCFF) {
         const processedGeometry = this.tessellator.process(paths, true, isCFF);
         return this.extrudeAndPackage(processedGeometry, depth);
     }
     extrudeAndPackage(processedGeometry, depth) {
+        perfLogger.start('Extruder.extrude', {
+            depth,
+            upem: this.loadedFont.upem
+        });
         const extrudedResult = this.extruder.extrude(processedGeometry, depth, this.loadedFont.upem);
+        perfLogger.end('Extruder.extrude');
         // Compute bounding box from vertices
         const vertices = extrudedResult.vertices;
         let minX = Infinity, minY = Infinity, minZ = Infinity;
@@ -3547,6 +3953,7 @@ class GlyphGeometryBuilder {
             pathCount: glyphContours.paths.length
         });
         const processedGeometry = this.tessellator.process(glyphContours.paths, removeOverlaps, isCFF);
+        perfLogger.end('GlyphGeometryBuilder.tessellateGlyph');
         return this.extrudeAndPackage(processedGeometry, depth);
     }
     updatePlaneBounds(glyphBounds, planeBounds) {
@@ -3619,8 +4026,10 @@ class TextShaper {
         let currentClusterText = '';
         let clusterStartPosition = new Vec3();
         let cursor = new Vec3(lineInfo.xOffset, -lineIndex * scaledLineHeight, 0);
+        // Apply letter spacing between glyphs (must match what was used in width measurements)
         const letterSpacingFU = letterSpacing * this.loadedFont.upem;
         const spaceAdjustment = this.calculateSpaceAdjustment(lineInfo, align, letterSpacing);
+        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]);
@@ -3666,6 +4075,29 @@ class TextShaper {
             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({
@@ -3698,6 +4130,23 @@ class TextShaper {
         }
         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();
     }
@@ -4815,7 +5264,7 @@ class Text {
             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);
@@ -4845,7 +5294,8 @@ class Text {
             exhyphenpenalty,
             doublehyphendemerits,
             looseness,
-            disableSingleWordDetection,
+            disableShortLineDetection,
+            shortLineThreshold,
             letterSpacing
         });
         const metrics = FontMetadataExtractor.getVerticalMetrics(this.loadedFont.metrics);