three-text 0.2.12 → 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.12
+ * 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();
@@ -3796,70 +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);
+                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;
+                            }
+                        }
+                    }
+                    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
+                        });
+                    }
+                }
                 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) {
-                    // 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)))
-                                });
+                // 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);
                         }
-                        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);
-                    }
-                }
-                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);
+                        // 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);
                     }
                 }
             }
@@ -3876,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);
@@ -4000,6 +4065,7 @@ class GlyphGeometryBuilder {
     clearCache() {
         this.cache.clear();
         this.wordCache.clear();
+        this.clusteringCache.clear();
     }
 }
 

package/dist/index.js

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.2.12
+ * three-text v0.2.13
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify
@@ -2583,7 +2583,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]);
         }
@@ -2634,18 +2633,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;
@@ -2665,7 +2667,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;
             }
@@ -2681,8 +2682,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 &&
@@ -2699,10 +2698,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());
     }
@@ -3755,6 +3756,10 @@ class GlyphGeometryBuilder {
                 return size;
             }
         });
+        this.clusteringCache = new LRUCache({
+            maxEntries: 2000,
+            calculateSize: () => 1
+        });
     }
     getOptimizationStats() {
         return this.collector.getOptimizationStats();
@@ -3793,70 +3798,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);
+                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;
+                            }
+                        }
+                    }
+                    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
+                        });
+                    }
+                }
                 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) {
-                    // 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)))
-                                });
+                // 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);
                         }
-                        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);
-                    }
-                }
-                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);
+                        // 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);
                     }
                 }
             }
@@ -3873,6 +3923,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);
@@ -3997,6 +4062,7 @@ class GlyphGeometryBuilder {
     clearCache() {
         this.cache.clear();
         this.wordCache.clear();
+        this.clusteringCache.clear();
     }
 }