three-text 0.2.11 → 0.2.13

package/README.md

@@ -317,7 +317,7 @@ The library uses a hybrid caching strategy to maximize performance while ensurin
 
 By default, it operates with glyph-level cache. The geometry for each unique character (`a`, `b`, `c`...) is generated only once and stored for reuse, avoiding redundant computation
 
-For text with tight tracking, connected scripts, or complex kerning pairs, individual glyphs can overlap. When an overlap within a word is found, the entire word is treated as a single unit and escalated to a word-level cache. All of its glyphs are tessellated together to correctly resolve the overlaps, and the resulting geometry for the word is cached
+For text with tight tracking, connected scripts, or complex kerning pairs, individual glyphs can overlap. The system detects overlaps within each word and handles them at the sub-cluster level: only the specific glyphs that overlap are tessellated together as a group, while non-overlapping glyphs in the same word continue to use individual glyph caching
 
 
 #### Flat geometry mode

package/dist/index.cjs

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.2.11
+ * three-text v0.2.13
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify
@@ -2586,7 +2586,6 @@ class Extruder {
             vertices.push(points[i], points[i + 1], 0);
             normals.push(0, 0, -1);
         }
-        // Add triangle indices
         for (let i = 0; i < triangleIndices.length; i++) {
             indices.push(baseIndex + triangleIndices[i]);
         }
@@ -2637,18 +2636,21 @@ class BoundaryClusterer {
         perfLogger.start('BoundaryClusterer.cluster', {
             glyphCount: glyphContoursList.length
         });
-        if (glyphContoursList.length === 0) {
+        const n = glyphContoursList.length;
+        if (n === 0) {
             perfLogger.end('BoundaryClusterer.cluster');
             return [];
         }
+        if (n === 1) {
+            perfLogger.end('BoundaryClusterer.cluster');
+            return [[0]];
+        }
         const result = this.clusterSweepLine(glyphContoursList, positions);
         perfLogger.end('BoundaryClusterer.cluster');
         return result;
     }
     clusterSweepLine(glyphContoursList, positions) {
         const n = glyphContoursList.length;
-        if (n <= 1)
-            return n === 0 ? [] : [[0]];
         const bounds = new Array(n);
         const events = new Array(2 * n);
         let eventIndex = 0;
@@ -2668,7 +2670,6 @@ class BoundaryClusterer {
             const py = find(y);
             if (px === py)
                 return;
-            // Union by rank, attach smaller tree under larger tree
             if (rank[px] < rank[py]) {
                 parent[px] = py;
             }
@@ -2684,8 +2685,6 @@ class BoundaryClusterer {
         for (const [, eventType, glyphIndex] of events) {
             if (eventType === 0) {
                 const bounds1 = bounds[glyphIndex];
-                // Check y-overlap with all currently active glyphs
-                // (x-overlap is guaranteed by the sweep line)
                 for (const activeIndex of active) {
                     const bounds2 = bounds[activeIndex];
                     if (bounds1.minY < bounds2.maxY + OVERLAP_EPSILON &&
@@ -2702,10 +2701,12 @@ class BoundaryClusterer {
         const clusters = new Map();
         for (let i = 0; i < n; i++) {
             const root = find(i);
-            if (!clusters.has(root)) {
-                clusters.set(root, []);
+            let list = clusters.get(root);
+            if (!list) {
+                list = [];
+                clusters.set(root, list);
             }
-            clusters.get(root).push(i);
+            list.push(i);
         }
         return Array.from(clusters.values());
     }
@@ -3758,6 +3759,10 @@ class GlyphGeometryBuilder {
                 return size;
             }
         });
+        this.clusteringCache = new LRUCache({
+            maxEntries: 2000,
+            calculateSize: () => 1
+        });
     }
     getOptimizationStats() {
         return this.collector.getOptimizationStats();
@@ -3772,7 +3777,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,
@@ -3796,64 +3801,115 @@ class GlyphGeometryBuilder {
                     clusterGlyphContours.push(this.getContoursForGlyph(glyph.g));
                 }
                 // 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
-                    ? false
-                    : boundaryGroups.some((group) => group.length > 1);
-                if (hasOverlaps) {
-                    // Cluster-level caching
-                    const clusterKey = `${this.fontId}_${cluster.text}_${depth}_${removeOverlaps}`;
-                    let cachedCluster = this.wordCache.get(clusterKey);
-                    if (!cachedCluster) {
-                        const clusterPaths = [];
-                        for (let i = 0; i < clusterGlyphContours.length; i++) {
-                            const glyphContours = clusterGlyphContours[i];
-                            const glyph = cluster.glyphs[i];
-                            for (const path of glyphContours.paths) {
-                                clusterPaths.push({
-                                    ...path,
-                                    points: path.points.map((p) => new Vec2(p.x + (glyph.x ?? 0), p.y + (glyph.y ?? 0)))
-                                });
+                let boundaryGroups;
+                if (cluster.glyphs.length <= 1) {
+                    boundaryGroups = [[0]];
+                }
+                else {
+                    // Check clustering cache (same text + glyph IDs = same overlap groups)
+                    const cacheKey = cluster.text;
+                    const cached = this.clusteringCache.get(cacheKey);
+                    let isValid = false;
+                    if (cached && cached.glyphIds.length === cluster.glyphs.length) {
+                        isValid = true;
+                        for (let i = 0; i < cluster.glyphs.length; i++) {
+                            if (cached.glyphIds[i] !== cluster.glyphs[i].g) {
+                                isValid = false;
+                                break;
                             }
                         }
-                        cachedCluster = this.tessellateGlyphCluster(clusterPaths, depth, isCFF);
-                        this.wordCache.set(clusterKey, cachedCluster);
                     }
-                    const vertexOffset = vertices.length / 3;
-                    this.appendGeometry(vertices, normals, indices, cachedCluster, cluster.position, vertexOffset);
-                    const clusterVertexCount = cachedCluster.vertices.length / 3;
-                    for (let i = 0; i < cluster.glyphs.length; i++) {
-                        const glyph = cluster.glyphs[i];
-                        const glyphContours = clusterGlyphContours[i];
-                        const absoluteGlyphPosition = new Vec3(cluster.position.x + (glyph.x ?? 0), cluster.position.y + (glyph.y ?? 0), cluster.position.z);
-                        const glyphInfo = this.createGlyphInfo(glyph, vertexOffset, clusterVertexCount, absoluteGlyphPosition, glyphContours, depth);
-                        glyphInfos.push(glyphInfo);
-                        this.updatePlaneBounds(glyphInfo.bounds, planeBounds);
+                    if (isValid && cached) {
+                        boundaryGroups = cached.groups;
+                    }
+                    else {
+                        const relativePositions = cluster.glyphs.map((g) => new Vec3(g.x, g.y, 0));
+                        boundaryGroups = this.clusterer.cluster(clusterGlyphContours, relativePositions);
+                        this.clusteringCache.set(cacheKey, {
+                            glyphIds: cluster.glyphs.map(g => g.g),
+                            groups: boundaryGroups
+                        });
                     }
                 }
-                else {
-                    // Glyph-level caching
-                    for (let i = 0; i < cluster.glyphs.length; i++) {
-                        const glyph = cluster.glyphs[i];
-                        const glyphContours = clusterGlyphContours[i];
-                        const glyphPosition = new Vec3(cluster.position.x + (glyph.x ?? 0), cluster.position.y + (glyph.y ?? 0), cluster.position.z);
-                        // Skip glyphs with no paths (spaces, zero-width characters, etc.)
-                        if (glyphContours.paths.length === 0) {
-                            const glyphInfo = this.createGlyphInfo(glyph, 0, 0, glyphPosition, glyphContours, depth);
+                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;
+                // Iterate over the geometric groups identified by BoundaryClusterer
+                // logical groups (words) are now split into geometric sub-groups (e.g. "aa", "XX", "bb")
+                for (const groupIndices of boundaryGroups) {
+                    const isOverlappingGroup = groupIndices.length > 1;
+                    const shouldCluster = isOverlappingGroup && !forceSeparate;
+                    if (shouldCluster) {
+                        // Cluster-level caching for this specific group of overlapping glyphs
+                        const subClusterGlyphs = groupIndices.map((i) => cluster.glyphs[i]);
+                        const clusterKey = this.getClusterKey(subClusterGlyphs, depth, removeOverlaps);
+                        let cachedCluster = this.wordCache.get(clusterKey);
+                        if (!cachedCluster) {
+                            const clusterPaths = [];
+                            const refX = subClusterGlyphs[0].x ?? 0;
+                            const refY = subClusterGlyphs[0].y ?? 0;
+                            for (let i = 0; i < groupIndices.length; i++) {
+                                const originalIndex = groupIndices[i];
+                                const glyphContours = clusterGlyphContours[originalIndex];
+                                const glyph = cluster.glyphs[originalIndex];
+                                // Position relative to the sub-cluster start
+                                const relX = (glyph.x ?? 0) - refX;
+                                const relY = (glyph.y ?? 0) - refY;
+                                for (const path of glyphContours.paths) {
+                                    clusterPaths.push({
+                                        ...path,
+                                        points: path.points.map((p) => new Vec2(p.x + relX, p.y + relY))
+                                    });
+                                }
+                            }
+                            cachedCluster = this.tessellateGlyphCluster(clusterPaths, depth, isCFF);
+                            this.wordCache.set(clusterKey, cachedCluster);
+                        }
+                        // Calculate the absolute position of this sub-cluster based on its first glyph
+                        // (since the cached geometry is relative to that first glyph)
+                        const firstGlyphInGroup = subClusterGlyphs[0];
+                        const groupPosition = new Vec3(cluster.position.x + (firstGlyphInGroup.x ?? 0), cluster.position.y + (firstGlyphInGroup.y ?? 0), cluster.position.z);
+                        const vertexOffset = vertices.length / 3;
+                        this.appendGeometry(vertices, normals, indices, cachedCluster, groupPosition, vertexOffset);
+                        const clusterVertexCount = cachedCluster.vertices.length / 3;
+                        // Register glyph infos for all glyphs in this sub-cluster
+                        // They all point to the same merged geometry
+                        for (let i = 0; i < groupIndices.length; i++) {
+                            const originalIndex = groupIndices[i];
+                            const glyph = cluster.glyphs[originalIndex];
+                            const glyphContours = clusterGlyphContours[originalIndex];
+                            const absoluteGlyphPosition = new Vec3(cluster.position.x + (glyph.x ?? 0), cluster.position.y + (glyph.y ?? 0), cluster.position.z);
+                            const glyphInfo = this.createGlyphInfo(glyph, vertexOffset, clusterVertexCount, absoluteGlyphPosition, glyphContours, depth);
                             glyphInfos.push(glyphInfo);
-                            continue;
+                            this.updatePlaneBounds(glyphInfo.bounds, planeBounds);
                         }
-                        let cachedGlyph = this.cache.get(this.fontId, glyph.g, depth, removeOverlaps);
-                        if (!cachedGlyph) {
-                            cachedGlyph = this.tessellateGlyph(glyphContours, depth, removeOverlaps, isCFF);
-                            this.cache.set(this.fontId, glyph.g, depth, removeOverlaps, cachedGlyph);
+                    }
+                    else {
+                        // Glyph-level caching (standard path for isolated glyphs or when forced separate)
+                        for (const i of groupIndices) {
+                            const glyph = cluster.glyphs[i];
+                            const glyphContours = clusterGlyphContours[i];
+                            const glyphPosition = new Vec3(cluster.position.x + (glyph.x ?? 0), cluster.position.y + (glyph.y ?? 0), cluster.position.z);
+                            // Skip glyphs with no paths (spaces, zero-width characters, etc.)
+                            if (glyphContours.paths.length === 0) {
+                                const glyphInfo = this.createGlyphInfo(glyph, 0, 0, glyphPosition, glyphContours, depth);
+                                glyphInfos.push(glyphInfo);
+                                continue;
+                            }
+                            let cachedGlyph = this.cache.get(this.fontId, glyph.g, depth, removeOverlaps);
+                            if (!cachedGlyph) {
+                                cachedGlyph = this.tessellateGlyph(glyphContours, depth, removeOverlaps, isCFF);
+                                this.cache.set(this.fontId, glyph.g, depth, removeOverlaps, cachedGlyph);
+                            }
+                            const vertexOffset = vertices.length / 3;
+                            this.appendGeometry(vertices, normals, indices, cachedGlyph, glyphPosition, vertexOffset);
+                            const glyphInfo = this.createGlyphInfo(glyph, vertexOffset, cachedGlyph.vertices.length / 3, glyphPosition, glyphContours, depth);
+                            glyphInfos.push(glyphInfo);
+                            this.updatePlaneBounds(glyphInfo.bounds, planeBounds);
                         }
-                        const vertexOffset = vertices.length / 3;
-                        this.appendGeometry(vertices, normals, indices, cachedGlyph, glyphPosition, vertexOffset);
-                        const glyphInfo = this.createGlyphInfo(glyph, vertexOffset, cachedGlyph.vertices.length / 3, glyphPosition, glyphContours, depth);
-                        glyphInfos.push(glyphInfo);
-                        this.updatePlaneBounds(glyphInfo.bounds, planeBounds);
                     }
                 }
             }
@@ -3870,6 +3926,21 @@ class GlyphGeometryBuilder {
             planeBounds
         };
     }
+    getClusterKey(glyphs, depth, removeOverlaps) {
+        if (glyphs.length === 0)
+            return '';
+        // Normalize positions relative to the first glyph in the cluster
+        const refX = glyphs[0].x ?? 0;
+        const refY = glyphs[0].y ?? 0;
+        const parts = glyphs.map((g) => {
+            const relX = (g.x ?? 0) - refX;
+            const relY = (g.y ?? 0) - refY;
+            return `${g.g}:${relX},${relY}`;
+        });
+        const ids = parts.join('|');
+        const roundedDepth = Math.round(depth * 1000) / 1000;
+        return `${this.fontId}_${ids}_${roundedDepth}_${removeOverlaps}`;
+    }
     appendGeometry(vertices, normals, indices, data, position, offset) {
         for (let j = 0; j < data.vertices.length; j += 3) {
             vertices.push(data.vertices[j] + position.x, data.vertices[j + 1] + position.y, data.vertices[j + 2] + position.z);
@@ -3994,6 +4065,7 @@ class GlyphGeometryBuilder {
     clearCache() {
         this.cache.clear();
         this.wordCache.clear();
+        this.clusteringCache.clear();
     }
 }
 
@@ -4008,30 +4080,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 +4120,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 +5309,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) {