three-text 0.3.4 → 0.4.0

package/README.md

@@ -13,7 +13,7 @@ High fidelity 3D mesh font geometry and text layout engine for the web
 ## Overview
 
 > [!CAUTION]
-> three-text is an alpha release and the API may break rapidly. This warning will last at least through the end of 2025. If API stability is important to you, consider pinning your version. Community feedback is encouraged; please open an issue if you have any suggestions or feedback, thank you
+> three-text is an alpha release and the API may break rapidly. This warning will likely last until the end of March 2026. If API stability is important to you, consider pinning your version. Community feedback is encouraged; please open an issue if you have any suggestions or feedback, thank you
 
 **three-text** is a 3D mesh font geometry and text layout library for the web. It supports TTF, OTF, and WOFF font files. For layout, it uses [TeX](https://en.wikipedia.org/wiki/TeX)-based parameters for breaking text into paragraphs across multiple lines and supports CJK and RTL scripts. three-text caches the geometries it generates for low CPU overhead in languages with lots of repeating glyphs. Variable fonts are supported as static instances at a given axis coordinate, and can be animated by re-drawing each frame with new coordinates
 
@@ -248,10 +248,10 @@ three-text generates high-fidelity 3D mesh geometry from font files. Unlike text
 Existing solutions take different approaches:
 
 - **Three.js native TextGeometry** uses fonts converted by facetype.js to JSON format. It creates 3D text by extruding flat 2D character outlines. While this produces true 3D geometry with depth, there is no support for real fonts or OpenType features needed for many of the world's scripts
-- **three-bmfont-text** is a 2D approach for Three.js, using pre-rendered bitmap fonts with SDF support. Texture atlases are generated at specific sizes, and artifacts are apparent up close
-- **troika-three-text** uses MSDF, which improves quality, and like three-text, it is built on HarfBuzz, which provides substantial language coverage, but is ultimately a 2D technique in image space. For flat text that does not need formatting or extrusion, and where artifacts are acceptable up close, troika works well
+- **three-bmfont-text** renders from pre-generated SDF atlas textures. Atlases are built offline at fixed sizes
+- **troika-three-text** generates SDF glyphs at runtime from font files via HarfBuzz. More flexible than bmfont, but still a 2D image-space technique with artifacts up close
 
-three-text generates true 3D geometry from font files via HarfBuzz. It is sharper at close distances than bitmap approaches when flat, and produces real mesh data that can be used with any rendering system. The library caches glyph geometry, so a paragraph of 1000 words might only require 50 unique glyphs to be processed. This makes it well-suited to longer texts. In addition to performance considerations, three-text provides control over typesetting and paragraph justification via TeX-based parameters
+three-text generates true 3D geometry from font files via HarfBuzz. It is sharper at close distances than bitmap approaches, and produces mesh data that can be used with any rendering system. The library caches glyph geometry, so a paragraph of 1000 words might only require 50 unique glyphs to be processed. This makes it well-suited to longer texts. three-text also provides control over typesetting and paragraph justification via TeX-based parameters
 
 ## Library structure
 
@@ -309,15 +309,14 @@ Hyphenation uses patterns derived from the Tex hyphenation project, converted in
 The geometry pipeline runs once per unique glyph (or glyph cluster), with intermediate results cached to avoid redundant work:
 
 1. **Path collection**: HarfBuzz callbacks provide low level drawing operations
-2. **Curve polygonization**: Uses Anti-Grain Geometry's recursive subdivision to convert bezier curves into polygons, concentrating points where curvature is high
+2. **Curve polygonization**: Flattens bezier curves into line segments, placing more points where curves are tight
 3. **Geometry optimization**:
-   - **Visvalingam-Whyatt simplification**: removes vertices that contribute the least to the overall shape, preserving sharp corners and subtle curves
-   - **Colinear point removal**: eliminates redundant points that lie on straight lines within angle tolerances
+   - **Visvalingam-Whyatt simplification**: removes vertices that form tiny triangles with their neighbors, smoothing out subtle bumps while preserving sharp corners
 4. **Overlap removal**: removes self-intersections and resolves overlapping paths between glyphs, preserving correct winding rules for triangulation
 5. **Triangulation**: converts cleaned 2D shapes into triangles using libtess2 with non-zero winding rule
 6. **Mesh construction**: generates 2D or 3D geometry with front faces and optional depth/extrusion (back faces and side walls)
 
-The multi-stage geometry approach (curve polygonization followed by cleanup, then triangulation) can reduce triangle counts while maintaining high visual fidelity and removing overlaps in variable fonts
+The multi-stage geometry approach (curve polygonization followed by cleanup, then triangulation) reduces triangle counts and removes overlaps in variable fonts
 
 #### Glyph caching
 
@@ -340,54 +339,49 @@ When `depth` is 0, the library generates single-sided geometry, reducing triangl
 
 ### Curve fidelity
 
-The library converts bezier curves into line segments by recursively subdividing curves until they meet specified quality thresholds. This is based on the AGG library, attempting to place vertices only where they are needed to maintain the integrity of the curve. You can control curve fidelity with `distanceTolerance` and `angleTolerance`
+Font outlines are bezier curves, but screens render curves flattened into many line segments. The library uses one of two modes:
 
-- `distanceTolerance`: The maximum allowed deviation of the curve from a straight line segment, measured in font units. Lower values produce higher fidelity and more vertices. Default is `0.5`, which is nearly imperceptable without extrusion
-- `angleTolerance`: The maximum angle in radians between segments at a join. This helps preserve sharp corners. Default is `0.2`
+**Adaptive (default)** - The algorithm splits each curve at its midpoint, checks if the resulting line segment is close enough to the true curve, and recurses until it is. Tight curves get more segments; gentle curves get fewer. Two tolerances control when to stop subdividing:
 
-In general, this step helps more with time to first render than ongoing interactions in the scene
+- `distanceTolerance`: how far the line segment can stray from the true curve, in font units. Lower values trace the curve more faithfully (default: `0.5`)
+- `angleTolerance`: the maximum angle between adjacent segments, in radians. Smaller values preserve sharp corners better (default: `0.2`)
+
+**Fixed-step** - Divides each curve into exactly `curveSteps` segments, regardless of curvature. Simpler and predictable. Overrides adaptive mode when set
 
 ```javascript
+// Adaptive (default)
 const text = await Text.create({
-  text: 'Sample text',
+  text: 'Sample',
   font: '/fonts/Font.ttf',
-  curveFidelity: {
+  curveFidelity: { 
     distanceTolerance: 0.2,
-    angleTolerance: 0.1,
+    angleTolerance: 0.1
   },
 });
-```
-
-### Geometry optimization
 
-`three-text` uses a line simplification algorithm after creating lines to reduce the complexity of the shapes as well, which can be combined with `curveFidelity` for different types of control. It is enabled by default:
-
-
-```javascript
-// Default optimization (automatic)
+// Fixed-step: 8 segments per curve
 const text = await Text.create({
-  text: 'Sample text',
+  text: 'Sample',
   font: '/fonts/Font.ttf',
+  curveSteps: 8,
 });
+```
+
+### Geometry optimization
+
+After curve polygonization, the library applies Visvalingam-Whyatt simplification. Unlike curve flattening, which operates on each bezier independently, V-W sees the complete assembled path. The algorithm looks at each vertex and the triangle it forms with its two neighbors. Vertices that form tiny triangles - nearly collinear with their neighbors - are removed first. The process repeats until no triangle is smaller than `areaThreshold`, measured in square font units. Sharp corners form large triangles, so they survive; subtle bumps form small ones and get smoothed out:
 
-// Custom optimization settings
 ```javascript
 const text = await Text.create({
   text: 'Sample text',
   font: '/fonts/Font.ttf',
   geometryOptimization: {
-    areaThreshold: 1.0,         // Default: 1.0 (remove triangles < 1 font unit²)
-    colinearThreshold: 0.0087,  // Default: ~0.5° in radians
-    minSegmentLength: 10,       // Default: 10 font units
+    areaThreshold: 1.0,  // remove triangles < 1 font unit²
   },
 });
 ```
 
-**The Visvalingam-Whyatt simplification** removes vertices whose removal creates triangles with area below the threshold
-
-**Colinear point removal** eliminates redundant vertices that lie on straight lines within the specified angle tolerance
-
-The default settings provide a significant reduction while maintaining high visual quality, but won't be perfect for every font. Adjust thresholds based on your quality requirements, performance constraints, and testing
+Defaults work well for most fonts. Adjust thresholds based on quality requirements and testing
 
 ### Line breaking parameters
 
@@ -637,6 +631,8 @@ const text = await Text.create({
 
 Text matching occurs after layout processing, so patterns like "connection" will be found even if hyphenation splits them across lines. The `coloredRanges` property on the returned object contains the resolved color assignments for programmatic access to the colored parts of the geometry
 
+When using selective coloring with `byText` or `byCharRange`, colored glyphs are kept geometrically separate from adjacent non-colored glyphs. This ensures accurate vertex coloring while still allowing overlap removal between glyphs of the same color status, e.g. two adjacent colored letters that overlap will still be properly merged
+
 ## API reference
 
 The library's full TypeScript definitions are the most complete source of truth for the API. The core data structures and configuration options can be found in `src/core/types.ts`
@@ -738,6 +734,7 @@ interface TextOptions {
   removeOverlaps?: boolean; // Override default overlap removal (auto-enabled for VF only)
   perGlyphAttributes?: boolean; // Keep per-glyph identity and add per-glyph shader attributes
   color?: [number, number, number] | ColorOptions; // Text coloring (simple or complex)
+  curveSteps?: number; // Fixed segments per curve; overrides curveFidelity when set
   curveFidelity?: CurveFidelityConfig;
   geometryOptimization?: GeometryOptimizationOptions;
   layout?: LayoutOptions;
@@ -794,12 +791,10 @@ interface CurveFidelityConfig {
 
 ```typescript
 interface GeometryOptimizationOptions {
-  enabled?: boolean; // Enable geometry optimization (default: true)
-  areaThreshold?: number; // Min triangle area for Visvalingam-Whyatt (default: 1.0)
-  colinearThreshold?: number; // Max angle for colinear removal in radians (default: 0.0087)
-  minSegmentLength?: number; // Min segment length in font units (default: 10)
+  enabled?: boolean;      // Enable optimization (default: true)
+  areaThreshold?: number; // Min triangle area in font units² (default: 1.0)
 }
-````
+```
 
 #### TextGeometryInfo (Core)
 
@@ -825,7 +820,6 @@ interface TextGeometryInfo {
     trianglesGenerated: number;
     verticesGenerated: number;
     pointsRemovedByVisvalingam: number;
-    pointsRemovedByColinear: number;
     originalPointCount: number;
   };
   query(options: TextQueryOptions): TextRange[];

package/dist/index.cjs

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.3.4
+ * three-text v0.4.0
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify
@@ -198,7 +198,7 @@ var FitnessClass;
     FitnessClass[FitnessClass["DECENT"] = 2] = "DECENT";
     FitnessClass[FitnessClass["TIGHT"] = 3] = "TIGHT"; // lines shrinking 0.5 to 1.0 of their shrinkability
 })(FitnessClass || (FitnessClass = {}));
-// Fast active node management with O(1) operations
+// Active node management with Map for O(1) lookup by (position, fitness)
 class ActiveNodeList {
     constructor() {
         this.nodesByKey = new Map();
@@ -229,7 +229,6 @@ class ActiveNodeList {
         this.nodesByKey.set(key, node);
         return true;
     }
-    // Swap-and-pop removal
     deactivate(node) {
         if (!node.active)
             return;
@@ -372,36 +371,66 @@ class LineBreak {
         const code = char.codePointAt(0);
         if (code === undefined)
             return false;
-        return ((code >= 0x4e00 && code <= 0x9fff) ||
-            (code >= 0x3400 && code <= 0x4dbf) ||
-            (code >= 0x20000 && code <= 0x2a6df) ||
-            (code >= 0x2a700 && code <= 0x2b73f) ||
-            (code >= 0x2b740 && code <= 0x2b81f) ||
-            (code >= 0x2b820 && code <= 0x2ceaf) ||
-            (code >= 0xf900 && code <= 0xfaff) ||
-            (code >= 0x3040 && code <= 0x309f) ||
-            (code >= 0x30a0 && code <= 0x30ff) ||
-            (code >= 0xac00 && code <= 0xd7af) ||
-            (code >= 0x1100 && code <= 0x11ff) ||
-            (code >= 0x3130 && code <= 0x318f) ||
-            (code >= 0xa960 && code <= 0xa97f) ||
-            (code >= 0xd7b0 && code <= 0xd7ff) ||
-            (code >= 0xffa0 && code <= 0xffdc));
-    }
+        return ((code >= 0x4e00 && code <= 0x9fff) || // CJK Unified Ideographs
+            (code >= 0x3400 && code <= 0x4dbf) || // CJK Extension A
+            (code >= 0x20000 && code <= 0x2a6df) || // CJK Extension B
+            (code >= 0x2a700 && code <= 0x2b73f) || // CJK Extension C
+            (code >= 0x2b740 && code <= 0x2b81f) || // CJK Extension D
+            (code >= 0x2b820 && code <= 0x2ceaf) || // CJK Extension E
+            (code >= 0xf900 && code <= 0xfaff) || // CJK Compatibility Ideographs
+            (code >= 0x3040 && code <= 0x309f) || // Hiragana
+            (code >= 0x30a0 && code <= 0x30ff) || // Katakana
+            (code >= 0xac00 && code <= 0xd7af) || // Hangul Syllables
+            (code >= 0x1100 && code <= 0x11ff) || // Hangul Jamo
+            (code >= 0x3130 && code <= 0x318f) || // Hangul Compatibility Jamo
+            (code >= 0xa960 && code <= 0xa97f) || // Hangul Jamo Extended-A
+            (code >= 0xd7b0 && code <= 0xd7ff) || // Hangul Jamo Extended-B
+            (code >= 0xffa0 && code <= 0xffdc) // Halfwidth Hangul
+        );
+    }
+    // Closing punctuation - no line break before (UAX #14 CL, JIS X 4051)
     static isCJClosingPunctuation(char) {
         const code = char.charCodeAt(0);
-        return (code === 0x3001 || code === 0x3002 || code === 0xff0c || code === 0xff0e ||
-            code === 0xff1a || code === 0xff1b || code === 0xff01 || code === 0xff1f ||
-            code === 0xff09 || code === 0x3011 || code === 0xff5d || code === 0x300d ||
-            code === 0x300f || code === 0x3009 || code === 0x300b || code === 0x3015 ||
-            code === 0x3017 || code === 0x3019 || code === 0x301b || code === 0x30fc ||
-            code === 0x2014 || code === 0x2026 || code === 0x2025);
-    }
+        return (code === 0x3001 || // 、
+            code === 0x3002 || // 。
+            code === 0xff0c || // ，
+            code === 0xff0e || // ．
+            code === 0xff1a || // ：
+            code === 0xff1b || // ；
+            code === 0xff01 || // ！
+            code === 0xff1f || // ？
+            code === 0xff09 || // ）
+            code === 0x3011 || // 】
+            code === 0xff5d || // ｝
+            code === 0x300d || // 」
+            code === 0x300f || // 』
+            code === 0x3009 || // 〉
+            code === 0x300b || // 》
+            code === 0x3015 || // 〕
+            code === 0x3017 || // 〗
+            code === 0x3019 || // 〙
+            code === 0x301b || // 〛
+            code === 0x30fc || // ー
+            code === 0x2014 || // —
+            code === 0x2026 || // …
+            code === 0x2025 // ‥
+        );
+    }
+    // Opening punctuation - no line break after (UAX #14 OP, JIS X 4051)
     static isCJOpeningPunctuation(char) {
         const code = char.charCodeAt(0);
-        return (code === 0xff08 || code === 0x3010 || code === 0xff5b || code === 0x300c ||
-            code === 0x300e || code === 0x3008 || code === 0x300a || code === 0x3014 ||
-            code === 0x3016 || code === 0x3018 || code === 0x301a);
+        return (code === 0xff08 || // （
+            code === 0x3010 || // 【
+            code === 0xff5b || // ｛
+            code === 0x300c || // 「
+            code === 0x300e || // 『
+            code === 0x3008 || // 〈
+            code === 0x300a || // 《
+            code === 0x3014 || // 〔
+            code === 0x3016 || // 〖
+            code === 0x3018 || // 〘
+            code === 0x301a // 〚
+        );
     }
     static isCJPunctuation(char) {
         return this.isCJClosingPunctuation(char) || this.isCJOpeningPunctuation(char);
@@ -3042,15 +3071,12 @@ class MinHeap {
 
 const DEFAULT_OPTIMIZATION_CONFIG = {
     enabled: true,
-    areaThreshold: 1.0, // Remove triangles smaller than 1 square font unit
-    colinearThreshold: 0.0087, // ~0.5 degrees in radians
-    minSegmentLength: 10
+    areaThreshold: 1.0 // Remove triangles smaller than 1 square font unit
 };
 class PathOptimizer {
     constructor(config) {
         this.stats = {
             pointsRemovedByVisvalingam: 0,
-            pointsRemovedByColinear: 0,
             originalPointCount: 0
         };
         this.config = config;
@@ -3059,7 +3085,10 @@ class PathOptimizer {
         this.config = config;
     }
     optimizePath(path) {
-        if (!this.config.enabled || path.points.length <= 2) {
+        if (path.points.length <= 2) {
+            return path;
+        }
+        if (!this.config.enabled) {
             return path;
         }
         this.stats.originalPointCount += path.points.length;
@@ -3069,11 +3098,9 @@ class PathOptimizer {
         if (points.length < 5) {
             return path;
         }
-        let optimized = this.simplifyPathVW(points, this.config.areaThreshold);
-        if (optimized.length < 3) {
-            return path;
-        }
-        optimized = this.removeColinearPoints(optimized, this.config.colinearThreshold);
+        let optimized = points;
+        // Visvalingam-Whyatt simplification
+        optimized = this.simplifyPathVW(optimized, this.config.areaThreshold);
         if (optimized.length < 3) {
             return path;
         }
@@ -3110,17 +3137,6 @@ class PathOptimizer {
             if (!p || p.area > areaThreshold) {
                 break;
             }
-            if (this.config.minSegmentLength > 0 && p.prev && p.next) {
-                const prevPoint = points[p.prev.index];
-                const currentPoint = points[p.index];
-                const nextPoint = points[p.next.index];
-                const len1 = prevPoint.distanceTo(currentPoint);
-                const len2 = currentPoint.distanceTo(nextPoint);
-                if (len1 < this.config.minSegmentLength ||
-                    len2 < this.config.minSegmentLength) {
-                    continue;
-                }
-            }
             if (p.prev)
                 p.prev.next = p.next;
             if (p.next)
@@ -3145,32 +3161,6 @@ class PathOptimizer {
         this.stats.pointsRemovedByVisvalingam += pointsRemoved;
         return simplifiedPoints;
     }
-    removeColinearPoints(points, threshold) {
-        if (points.length <= 2)
-            return points;
-        const result = [points[0]];
-        for (let i = 1; i < points.length - 1; i++) {
-            const prev = points[i - 1];
-            const current = points[i];
-            const next = points[i + 1];
-            const v1x = current.x - prev.x;
-            const v1y = current.y - prev.y;
-            const v2x = next.x - current.x;
-            const v2y = next.y - current.y;
-            const angle = Math.abs(Math.atan2(v1x * v2y - v1y * v2x, v1x * v2x + v1y * v2y));
-            const v1LenSq = v1x * v1x + v1y * v1y;
-            const v2LenSq = v2x * v2x + v2y * v2y;
-            const minLenSq = this.config.minSegmentLength * this.config.minSegmentLength;
-            if (angle > threshold || v1LenSq < minLenSq || v2LenSq < minLenSq) {
-                result.push(current);
-            }
-            else {
-                this.stats.pointsRemovedByColinear++;
-            }
-        }
-        result.push(points[points.length - 1]);
-        return result;
-    }
     // Shoelace formula
     calculateTriangleArea(p1, p2, p3) {
         return Math.abs((p1.x * (p2.y - p3.y) + p2.x * (p3.y - p1.y) + p3.x * (p1.y - p2.y)) / 2);
@@ -3181,7 +3171,6 @@ class PathOptimizer {
     resetStats() {
         this.stats = {
             pointsRemovedByVisvalingam: 0,
-            pointsRemovedByColinear: 0,
             originalPointCount: 0
         };
     }
@@ -3232,6 +3221,7 @@ const COLLINEARITY_EPSILON = 1e-6;
 const RECURSION_LIMIT = 16;
 class Polygonizer {
     constructor(curveFidelityConfig) {
+        this.curveSteps = null;
         this.curveFidelityConfig = {
             ...DEFAULT_CURVE_FIDELITY,
             ...curveFidelityConfig
@@ -3243,18 +3233,77 @@ class Polygonizer {
             ...curveFidelityConfig
         };
     }
+    // Fixed-step subdivision; overrides adaptive curveFidelity when set
+    setCurveSteps(curveSteps) {
+        if (curveSteps === undefined || curveSteps === null) {
+            this.curveSteps = null;
+            return;
+        }
+        if (!Number.isFinite(curveSteps)) {
+            this.curveSteps = null;
+            return;
+        }
+        const stepsInt = Math.round(curveSteps);
+        this.curveSteps = stepsInt >= 1 ? stepsInt : null;
+    }
     polygonizeQuadratic(start, control, end) {
+        if (this.curveSteps !== null) {
+            return this.polygonizeQuadraticFixedSteps(start, control, end, this.curveSteps);
+        }
         const points = [];
         this.recursiveQuadratic(start.x, start.y, control.x, control.y, end.x, end.y, points);
         this.addPoint(end.x, end.y, points);
         return points;
     }
     polygonizeCubic(start, control1, control2, end) {
+        if (this.curveSteps !== null) {
+            return this.polygonizeCubicFixedSteps(start, control1, control2, end, this.curveSteps);
+        }
         const points = [];
         this.recursiveCubic(start.x, start.y, control1.x, control1.y, control2.x, control2.y, end.x, end.y, points);
         this.addPoint(end.x, end.y, points);
         return points;
     }
+    lerp(a, b, t) {
+        return a + (b - a) * t;
+    }
+    polygonizeQuadraticFixedSteps(start, control, end, steps) {
+        const points = [];
+        // Emit intermediate points; caller already has start
+        for (let i = 1; i <= steps; i++) {
+            const t = i / steps;
+            const x12 = this.lerp(start.x, control.x, t);
+            const y12 = this.lerp(start.y, control.y, t);
+            const x23 = this.lerp(control.x, end.x, t);
+            const y23 = this.lerp(control.y, end.y, t);
+            const x = this.lerp(x12, x23, t);
+            const y = this.lerp(y12, y23, t);
+            this.addPoint(x, y, points);
+        }
+        return points;
+    }
+    polygonizeCubicFixedSteps(start, control1, control2, end, steps) {
+        const points = [];
+        // Emit intermediate points; caller already has start
+        for (let i = 1; i <= steps; i++) {
+            const t = i / steps;
+            // De Casteljau
+            const x12 = this.lerp(start.x, control1.x, t);
+            const y12 = this.lerp(start.y, control1.y, t);
+            const x23 = this.lerp(control1.x, control2.x, t);
+            const y23 = this.lerp(control1.y, control2.y, t);
+            const x34 = this.lerp(control2.x, end.x, t);
+            const y34 = this.lerp(control2.y, end.y, t);
+            const x123 = this.lerp(x12, x23, t);
+            const y123 = this.lerp(y12, y23, t);
+            const x234 = this.lerp(x23, x34, t);
+            const y234 = this.lerp(y23, y34, t);
+            const x = this.lerp(x123, x234, t);
+            const y = this.lerp(y123, y234, t);
+            this.addPoint(x, y, points);
+        }
+        return points;
+    }
     recursiveQuadratic(x1, y1, x2, y2, x3, y3, points, level = 0) {
         if (level > RECURSION_LIMIT)
             return;
@@ -3281,8 +3330,8 @@ class Polygonizer {
                 const angleTolerance = this.curveFidelityConfig.angleTolerance ??
                     DEFAULT_CURVE_FIDELITY.angleTolerance;
                 if (angleTolerance > 0) {
-                    // Angle between segments (p1->p2) and (p2->p3).
-                    // Using atan2(cross, dot) avoids computing 2 separate atan2() values + wrap logic.
+                    // Angle between segments (p1->p2) and (p2->p3)
+                    // atan2(cross, dot) avoids computing 2 separate atan2() values
                     const v1x = x2 - x1;
                     const v1y = y2 - y1;
                     const v2x = x3 - x2;
@@ -3667,6 +3716,9 @@ class GlyphContourCollector {
     setCurveFidelityConfig(config) {
         this.polygonizer.setCurveFidelityConfig(config);
     }
+    setCurveSteps(curveSteps) {
+        this.polygonizer.setCurveSteps(curveSteps);
+    }
     setGeometryOptimization(options) {
         this.pathOptimizer.setConfig({
             ...DEFAULT_OPTIMIZATION_CONFIG,
@@ -3820,6 +3872,21 @@ class GlyphGeometryBuilder {
         this.collector.setCurveFidelityConfig(config);
         this.updateCacheKeyPrefix();
     }
+    setCurveSteps(curveSteps) {
+        // Normalize: unset for undefined/null/non-finite/<=0
+        if (curveSteps === undefined || curveSteps === null) {
+            this.curveSteps = undefined;
+        }
+        else if (!Number.isFinite(curveSteps)) {
+            this.curveSteps = undefined;
+        }
+        else {
+            const stepsInt = Math.round(curveSteps);
+            this.curveSteps = stepsInt >= 1 ? stepsInt : undefined;
+        }
+        this.collector.setCurveSteps(this.curveSteps);
+        this.updateCacheKeyPrefix();
+    }
     setGeometryOptimization(options) {
         this.geometryOptimizationOptions = options;
         this.collector.setGeometryOptimization(options);
@@ -3833,22 +3900,24 @@ class GlyphGeometryBuilder {
         this.cacheKeyPrefix = `${this.fontId}__${this.getGeometryConfigSignature()}`;
     }
     getGeometryConfigSignature() {
-        const distanceTolerance = this.curveFidelityConfig?.distanceTolerance ??
-            DEFAULT_CURVE_FIDELITY.distanceTolerance;
-        const angleTolerance = this.curveFidelityConfig?.angleTolerance ??
-            DEFAULT_CURVE_FIDELITY.angleTolerance;
+        const curveSignature = (() => {
+            if (this.curveSteps !== undefined) {
+                return `cf:steps:${this.curveSteps}`;
+            }
+            const distanceTolerance = this.curveFidelityConfig?.distanceTolerance ??
+                DEFAULT_CURVE_FIDELITY.distanceTolerance;
+            const angleTolerance = this.curveFidelityConfig?.angleTolerance ??
+                DEFAULT_CURVE_FIDELITY.angleTolerance;
+            return `cf:${distanceTolerance.toFixed(4)},${angleTolerance.toFixed(4)}`;
+        })();
         const enabled = this.geometryOptimizationOptions?.enabled ??
             DEFAULT_OPTIMIZATION_CONFIG.enabled;
         const areaThreshold = this.geometryOptimizationOptions?.areaThreshold ??
             DEFAULT_OPTIMIZATION_CONFIG.areaThreshold;
-        const colinearThreshold = this.geometryOptimizationOptions?.colinearThreshold ??
-            DEFAULT_OPTIMIZATION_CONFIG.colinearThreshold;
-        const minSegmentLength = this.geometryOptimizationOptions?.minSegmentLength ??
-            DEFAULT_OPTIMIZATION_CONFIG.minSegmentLength;
         // Use fixed precision to keep cache keys stable and avoid float noise
         return [
-            `cf:${distanceTolerance.toFixed(4)},${angleTolerance.toFixed(4)}`,
-            `opt:${enabled ? 1 : 0},${areaThreshold.toFixed(4)},${colinearThreshold.toFixed(6)},${minSegmentLength.toFixed(4)}`
+            curveSignature,
+            `opt:${enabled ? 1 : 0},${areaThreshold.toFixed(4)}`
         ].join('|');
     }
     // Build instanced geometry from glyph contours
@@ -3902,15 +3971,20 @@ class GlyphGeometryBuilder {
                     boundaryGroups = [[0]];
                 }
                 else {
-                    // Check clustering cache (same text + glyph IDs = same overlap groups)
+                    // Check clustering cache (same text + glyph IDs + positions = same overlap groups)
                     // Key must be font-specific; glyph ids/bounds differ between fonts
+                    // Positions must match since overlap detection depends on relative glyph placement
                     const cacheKey = `${this.cacheKeyPrefix}_${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) {
+                            const glyph = cluster.glyphs[i];
+                            const cachedPos = cached.positions[i];
+                            if (cached.glyphIds[i] !== glyph.g ||
+                                cachedPos.x !== (glyph.x ?? 0) ||
+                                cachedPos.y !== (glyph.y ?? 0)) {
                                 isValid = false;
                                 break;
                             }
@@ -3924,17 +3998,52 @@ class GlyphGeometryBuilder {
                         boundaryGroups = this.clusterer.cluster(clusterGlyphContours, relativePositions);
                         this.clusteringCache.set(cacheKey, {
                             glyphIds: cluster.glyphs.map((g) => g.g),
+                            positions: cluster.glyphs.map((g) => ({
+                                x: g.x ?? 0,
+                                y: g.y ?? 0
+                            })),
                             groups: boundaryGroups
                         });
                     }
                 }
-                const clusterHasColoredGlyphs = coloredTextIndices &&
-                    cluster.glyphs.some((g) => coloredTextIndices.has(g.absoluteTextIndex));
-                // Use glyph-level caching when separateGlyphs is set or when cluster contains colored text
-                const forceSeparate = separateGlyphs || clusterHasColoredGlyphs;
+                // Only force separate tessellation when explicitly requested via separateGlyphs
+                const forceSeparate = separateGlyphs;
+                // Split boundary groups so colored and non-colored glyphs don't merge together
+                // This preserves overlap removal within each color class while keeping
+                // geometry separate for accurate vertex coloring
+                let finalGroups = boundaryGroups;
+                if (coloredTextIndices && coloredTextIndices.size > 0) {
+                    finalGroups = [];
+                    for (const group of boundaryGroups) {
+                        if (group.length <= 1) {
+                            finalGroups.push(group);
+                        }
+                        else {
+                            // Split group into colored and non-colored sub-groups
+                            const coloredIndices = [];
+                            const nonColoredIndices = [];
+                            for (const idx of group) {
+                                const glyph = cluster.glyphs[idx];
+                                if (coloredTextIndices.has(glyph.absoluteTextIndex)) {
+                                    coloredIndices.push(idx);
+                                }
+                                else {
+                                    nonColoredIndices.push(idx);
+                                }
+                            }
+                            // Add non-empty sub-groups
+                            if (coloredIndices.length > 0) {
+                                finalGroups.push(coloredIndices);
+                            }
+                            if (nonColoredIndices.length > 0) {
+                                finalGroups.push(nonColoredIndices);
+                            }
+                        }
+                    }
+                }
                 // Iterate over the geometric groups identified by BoundaryClusterer
                 // logical groups (words) split into geometric sub-groups
-                for (const groupIndices of boundaryGroups) {
+                for (const groupIndices of finalGroups) {
                     const isOverlappingGroup = groupIndices.length > 1;
                     const shouldCluster = isOverlappingGroup && !forceSeparate;
                     if (shouldCluster) {
@@ -5365,7 +5474,13 @@ class Text {
                 this.geometryBuilder = new GlyphGeometryBuilder(globalGlyphCache, this.loadedFont);
                 this.geometryBuilder.setFontId(this.currentFontId);
             }
-            this.geometryBuilder.setCurveFidelityConfig(options.curveFidelity);
+            // Curve flattening: either use fixed-step De Casteljau (`curveSteps`) OR
+            // adaptive AGG-style tolerances (`curveFidelity`)
+            const useCurveSteps = options.curveSteps !== undefined &&
+                options.curveSteps !== null &&
+                options.curveSteps > 0;
+            this.geometryBuilder.setCurveSteps(options.curveSteps);
+            this.geometryBuilder.setCurveFidelityConfig(useCurveSteps ? undefined : options.curveFidelity);
             this.geometryBuilder.setGeometryOptimization(options.geometryOptimization);
             this.loadedFont.font.setScale(this.loadedFont.upem, this.loadedFont.upem);
             if (!this.textShaper) {
@@ -5595,6 +5710,7 @@ class Text {
                                 else {
                                     lineGroups.set(glyph.lineIndex, [glyph]);
                                 }
+                                // Color vertices owned by this glyph
                                 for (let v = 0; v < glyph.vertexCount; v++) {
                                     const vertexIndex = (glyph.vertexStart + v) * 3;
                                     if (vertexIndex >= 0 && vertexIndex < colors.length) {
@@ -5636,6 +5752,7 @@ class Text {
                                 else {
                                     lineGroups.set(glyph.lineIndex, [glyph]);
                                 }
+                                // Color vertices owned by this glyph
                                 for (let v = 0; v < glyph.vertexCount; v++) {
                                     const vertexIndex = (glyph.vertexStart + v) * 3;
                                     if (vertexIndex >= 0 && vertexIndex < colors.length) {
@@ -5736,7 +5853,6 @@ class Text {
                 trianglesGenerated,
                 verticesGenerated,
                 pointsRemovedByVisvalingam: optimizationStats.pointsRemovedByVisvalingam,
-                pointsRemovedByColinear: optimizationStats.pointsRemovedByColinear,
                 originalPointCount: optimizationStats.originalPointCount
             },
             query: (() => {