three-text 0.2.11 → 0.2.13

package/dist/index.umd.js

@@ -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
@@ -2590,7 +2590,6 @@
                 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]);
             }
@@ -2641,18 +2640,21 @@
             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;
@@ -2672,7 +2674,6 @@
                 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;
                 }
@@ -2688,8 +2689,6 @@
             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 &&
@@ -2706,10 +2705,12 @@
             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());
         }
@@ -3762,6 +3763,10 @@
                     return size;
                 }
             });
+            this.clusteringCache = new LRUCache({
+                maxEntries: 2000,
+                calculateSize: () => 1
+            });
         }
         getOptimizationStats() {
             return this.collector.getOptimizationStats();
@@ -3776,7 +3781,7 @@
             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,
@@ -3800,64 +3805,115 @@
                         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);
                         }
                     }
                 }
@@ -3874,6 +3930,21 @@
                 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);
@@ -3998,6 +4069,7 @@
         clearCache() {
             this.cache.clear();
             this.wordCache.clear();
+            this.clusteringCache.clear();
         }
     }
 
@@ -4012,30 +4084,14 @@
             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');
@@ -4068,8 +4124,9 @@
                     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,
@@ -5256,7 +5313,35 @@
                 // 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) {