three-text 0.2.10 → 0.2.12

package/README.md

@@ -396,7 +396,7 @@ The Knuth-Plass algorithm provides extensive control over line breaking quality:
 - **emergencyStretch** (0): Additional stretchability for difficult paragraphs
 - **autoEmergencyStretch** (0.1): Emergency stretch as percentage of line width (e.g., 0.1 = 10%). Defaults to 10% for non-hyphenated text
 - **disableShortLineDetection** (false): Disable automatic prevention of short lines
-- **shortLineThreshold** (0.5): Width ratio threshold for short line detection (0.0 to 1.0)
+- **shortLineThreshold** (0.7): Width ratio threshold for short line detection (0.0 to 1.0)
 
 #### Advanced parameters
 
@@ -419,7 +419,7 @@ Lower penalty/tolerance values produce tighter spacing but may fail to find acce
 
 #### Short line detection
 
-By default, the library detects and prevents short lines (lines occupying less than 50% of the target width on non-final lines) by iteratively applying emergency stretch. This can be customized or disabled:
+By default, the library detects and prevents short lines (lines occupying less than 70% of the target width on non-final lines) by iteratively applying emergency stretch. This can be customized or disabled:
 
 ```javascript
 const text = await Text.create({
@@ -783,7 +783,7 @@ interface LayoutOptions {
   emergencyStretch?: number; // Additional stretchability for difficult paragraphs
   autoEmergencyStretch?: number; // Emergency stretch as percentage of line width (defaults to 10% for non-hyphenated)
   disableShortLineDetection?: boolean; // Disable automatic short line prevention (default: false)
-  shortLineThreshold?: number; // Width ratio threshold for short line detection (default: 0.5)
+  shortLineThreshold?: number; // Width ratio threshold for short line detection (default: 0.7)
   lefthyphenmin?: number; // Minimum characters before hyphen (default: 2)
   righthyphenmin?: number; // Minimum characters after hyphen (default: 4)
   linepenalty?: number; // Base penalty per line (default: 10)

package/dist/index.cjs

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.2.10
+ * three-text v0.2.12
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify
@@ -258,7 +258,7 @@ 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: Short line detection thresholds
-const SHORT_LINE_WIDTH_THRESHOLD = 0.5; // Lines < 50% of width are problematic
+const SHORT_LINE_WIDTH_THRESHOLD = 0.7; // Lines < 70% 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 line 2337)
@@ -3772,7 +3772,7 @@ class GlyphGeometryBuilder {
         this.fontId = fontId;
     }
     // Build instanced geometry from glyph contours
-    buildInstancedGeometry(clustersByLine, depth, removeOverlaps, isCFF, separateGlyphs = false) {
+    buildInstancedGeometry(clustersByLine, depth, removeOverlaps, isCFF, separateGlyphs = false, coloredTextIndices) {
         perfLogger.start('GlyphGeometryBuilder.buildInstancedGeometry', {
             lineCount: clustersByLine.length,
             wordCount: clustersByLine.flat().length,
@@ -3798,7 +3798,13 @@ class GlyphGeometryBuilder {
                 // Step 2: Check for overlaps within the cluster
                 const relativePositions = cluster.glyphs.map((g) => new Vec3(g.x, g.y, 0));
                 const boundaryGroups = this.clusterer.cluster(clusterGlyphContours, relativePositions);
-                const hasOverlaps = separateGlyphs
+                const clusterHasColoredGlyphs = coloredTextIndices &&
+                    cluster.glyphs.some((g) => coloredTextIndices.has(g.absoluteTextIndex));
+                // Force glyph-level caching if:
+                // - separateGlyphs flag is set (for shader attributes), OR
+                // - cluster contains selectively colored text (needs separate vertex ranges per glyph)
+                const forceSeparate = separateGlyphs || clusterHasColoredGlyphs;
+                const hasOverlaps = forceSeparate
                     ? false
                     : boundaryGroups.some((group) => group.length > 1);
                 if (hasOverlaps) {
@@ -4008,30 +4014,14 @@ class TextShaper {
         perfLogger.start('TextShaper.shapeLines', {
             lineCount: lineInfos.length
         });
-        // Calculate color boundaries once for the entire text before line processing
-        const colorBoundaries = new Set();
-        if (color &&
-            typeof color === 'object' &&
-            'byText' in color &&
-            color.byText &&
-            originalText) {
-            for (const textToColor of Object.keys(color.byText)) {
-                let index = 0;
-                while ((index = originalText.indexOf(textToColor, index)) !== -1) {
-                    colorBoundaries.add(index);
-                    colorBoundaries.add(index + textToColor.length);
-                    index += textToColor.length;
-                }
-            }
-        }
         const clustersByLine = [];
         lineInfos.forEach((lineInfo, lineIndex) => {
-            const clusters = this.shapeLineIntoClusters(lineInfo, lineIndex, scaledLineHeight, letterSpacing, align, direction, colorBoundaries);
+            const clusters = this.shapeLineIntoClusters(lineInfo, lineIndex, scaledLineHeight, letterSpacing, align, direction);
             clustersByLine.push(clusters);
         });
         return clustersByLine;
     }
-    shapeLineIntoClusters(lineInfo, lineIndex, scaledLineHeight, letterSpacing, align, direction, colorBoundaries) {
+    shapeLineIntoClusters(lineInfo, lineIndex, scaledLineHeight, letterSpacing, align, direction) {
         const buffer = this.loadedFont.hb.createBuffer();
         if (direction === 'rtl') {
             buffer.setDirection('rtl');
@@ -4064,8 +4054,9 @@ class TextShaper {
                 glyph.absoluteTextIndex = lineInfo.originalStart + glyph.cl;
             }
             glyph.lineIndex = lineIndex;
-            const isBoundary = colorBoundaries.has(glyph.absoluteTextIndex);
-            if (isWhitespace || isBoundary) {
+            // Cluster boundaries are based on whitespace only.
+            // Coloring is applied later via vertex colors and must never affect shaping/kerning.
+            if (isWhitespace) {
                 if (currentClusterGlyphs.length > 0) {
                     clusters.push({
                         text: currentClusterText,
@@ -5252,7 +5243,35 @@ class Text {
             // Allow manual override via options.removeOverlaps
             const shouldRemoveOverlaps = options.removeOverlaps ?? this.loadedFont.isVariable ?? false;
             const clustersByLine = this.textShaper.shapeLines(layoutData.lines, layoutData.scaledLineHeight, layoutData.letterSpacing, layoutData.align, layoutData.direction, options.color, options.text);
-            const shapedResult = this.geometryBuilder.buildInstancedGeometry(clustersByLine, layoutData.depth, shouldRemoveOverlaps, this.loadedFont.metrics.isCFF, options.separateGlyphsWithAttributes || false);
+            // Pre-compute which character indices will be colored. This allows geometry building
+            // to selectively use glyph-level caching (separate vertices) only for clusters containing
+            // colored text, while non-colored clusters can still use fast cluster-level merging
+            let coloredTextIndices;
+            if (options.color && typeof options.color === 'object' && !Array.isArray(options.color)) {
+                if (options.color.byText || options.color.byCharRange) {
+                    // Build the set manually since glyphs don't exist yet
+                    coloredTextIndices = new Set();
+                    if (options.color.byText) {
+                        for (const pattern of Object.keys(options.color.byText)) {
+                            let index = 0;
+                            while ((index = options.text.indexOf(pattern, index)) !== -1) {
+                                for (let i = index; i < index + pattern.length; i++) {
+                                    coloredTextIndices.add(i);
+                                }
+                                index += pattern.length;
+                            }
+                        }
+                    }
+                    if (options.color.byCharRange) {
+                        for (const range of options.color.byCharRange) {
+                            for (let i = range.start; i < range.end; i++) {
+                                coloredTextIndices.add(i);
+                            }
+                        }
+                    }
+                }
+            }
+            const shapedResult = this.geometryBuilder.buildInstancedGeometry(clustersByLine, layoutData.depth, shouldRemoveOverlaps, this.loadedFont.metrics.isCFF, options.separateGlyphsWithAttributes || false, coloredTextIndices);
             const cacheStats = this.geometryBuilder.getCacheStats();
             const result = this.finalizeGeometry(shapedResult.vertices, shapedResult.normals, shapedResult.indices, shapedResult.glyphInfos, shapedResult.planeBounds, options, cacheStats, options.text);
             if (options.separateGlyphsWithAttributes) {

package/dist/index.js

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.2.10
+ * three-text v0.2.12
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify
@@ -255,7 +255,7 @@ 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: Short line detection thresholds
-const SHORT_LINE_WIDTH_THRESHOLD = 0.5; // Lines < 50% of width are problematic
+const SHORT_LINE_WIDTH_THRESHOLD = 0.7; // Lines < 70% 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 line 2337)
@@ -3769,7 +3769,7 @@ class GlyphGeometryBuilder {
         this.fontId = fontId;
     }
     // Build instanced geometry from glyph contours
-    buildInstancedGeometry(clustersByLine, depth, removeOverlaps, isCFF, separateGlyphs = false) {
+    buildInstancedGeometry(clustersByLine, depth, removeOverlaps, isCFF, separateGlyphs = false, coloredTextIndices) {
         perfLogger.start('GlyphGeometryBuilder.buildInstancedGeometry', {
             lineCount: clustersByLine.length,
             wordCount: clustersByLine.flat().length,
@@ -3795,7 +3795,13 @@ class GlyphGeometryBuilder {
                 // Step 2: Check for overlaps within the cluster
                 const relativePositions = cluster.glyphs.map((g) => new Vec3(g.x, g.y, 0));
                 const boundaryGroups = this.clusterer.cluster(clusterGlyphContours, relativePositions);
-                const hasOverlaps = separateGlyphs
+                const clusterHasColoredGlyphs = coloredTextIndices &&
+                    cluster.glyphs.some((g) => coloredTextIndices.has(g.absoluteTextIndex));
+                // Force glyph-level caching if:
+                // - separateGlyphs flag is set (for shader attributes), OR
+                // - cluster contains selectively colored text (needs separate vertex ranges per glyph)
+                const forceSeparate = separateGlyphs || clusterHasColoredGlyphs;
+                const hasOverlaps = forceSeparate
                     ? false
                     : boundaryGroups.some((group) => group.length > 1);
                 if (hasOverlaps) {
@@ -4005,30 +4011,14 @@ class TextShaper {
         perfLogger.start('TextShaper.shapeLines', {
             lineCount: lineInfos.length
         });
-        // Calculate color boundaries once for the entire text before line processing
-        const colorBoundaries = new Set();
-        if (color &&
-            typeof color === 'object' &&
-            'byText' in color &&
-            color.byText &&
-            originalText) {
-            for (const textToColor of Object.keys(color.byText)) {
-                let index = 0;
-                while ((index = originalText.indexOf(textToColor, index)) !== -1) {
-                    colorBoundaries.add(index);
-                    colorBoundaries.add(index + textToColor.length);
-                    index += textToColor.length;
-                }
-            }
-        }
         const clustersByLine = [];
         lineInfos.forEach((lineInfo, lineIndex) => {
-            const clusters = this.shapeLineIntoClusters(lineInfo, lineIndex, scaledLineHeight, letterSpacing, align, direction, colorBoundaries);
+            const clusters = this.shapeLineIntoClusters(lineInfo, lineIndex, scaledLineHeight, letterSpacing, align, direction);
             clustersByLine.push(clusters);
         });
         return clustersByLine;
     }
-    shapeLineIntoClusters(lineInfo, lineIndex, scaledLineHeight, letterSpacing, align, direction, colorBoundaries) {
+    shapeLineIntoClusters(lineInfo, lineIndex, scaledLineHeight, letterSpacing, align, direction) {
         const buffer = this.loadedFont.hb.createBuffer();
         if (direction === 'rtl') {
             buffer.setDirection('rtl');
@@ -4061,8 +4051,9 @@ class TextShaper {
                 glyph.absoluteTextIndex = lineInfo.originalStart + glyph.cl;
             }
             glyph.lineIndex = lineIndex;
-            const isBoundary = colorBoundaries.has(glyph.absoluteTextIndex);
-            if (isWhitespace || isBoundary) {
+            // Cluster boundaries are based on whitespace only.
+            // Coloring is applied later via vertex colors and must never affect shaping/kerning.
+            if (isWhitespace) {
                 if (currentClusterGlyphs.length > 0) {
                     clusters.push({
                         text: currentClusterText,
@@ -5249,7 +5240,35 @@ class Text {
             // Allow manual override via options.removeOverlaps
             const shouldRemoveOverlaps = options.removeOverlaps ?? this.loadedFont.isVariable ?? false;
             const clustersByLine = this.textShaper.shapeLines(layoutData.lines, layoutData.scaledLineHeight, layoutData.letterSpacing, layoutData.align, layoutData.direction, options.color, options.text);
-            const shapedResult = this.geometryBuilder.buildInstancedGeometry(clustersByLine, layoutData.depth, shouldRemoveOverlaps, this.loadedFont.metrics.isCFF, options.separateGlyphsWithAttributes || false);
+            // Pre-compute which character indices will be colored. This allows geometry building
+            // to selectively use glyph-level caching (separate vertices) only for clusters containing
+            // colored text, while non-colored clusters can still use fast cluster-level merging
+            let coloredTextIndices;
+            if (options.color && typeof options.color === 'object' && !Array.isArray(options.color)) {
+                if (options.color.byText || options.color.byCharRange) {
+                    // Build the set manually since glyphs don't exist yet
+                    coloredTextIndices = new Set();
+                    if (options.color.byText) {
+                        for (const pattern of Object.keys(options.color.byText)) {
+                            let index = 0;
+                            while ((index = options.text.indexOf(pattern, index)) !== -1) {
+                                for (let i = index; i < index + pattern.length; i++) {
+                                    coloredTextIndices.add(i);
+                                }
+                                index += pattern.length;
+                            }
+                        }
+                    }
+                    if (options.color.byCharRange) {
+                        for (const range of options.color.byCharRange) {
+                            for (let i = range.start; i < range.end; i++) {
+                                coloredTextIndices.add(i);
+                            }
+                        }
+                    }
+                }
+            }
+            const shapedResult = this.geometryBuilder.buildInstancedGeometry(clustersByLine, layoutData.depth, shouldRemoveOverlaps, this.loadedFont.metrics.isCFF, options.separateGlyphsWithAttributes || false, coloredTextIndices);
             const cacheStats = this.geometryBuilder.getCacheStats();
             const result = this.finalizeGeometry(shapedResult.vertices, shapedResult.normals, shapedResult.indices, shapedResult.glyphInfos, shapedResult.planeBounds, options, cacheStats, options.text);
             if (options.separateGlyphsWithAttributes) {