three-text 0.3.4 → 0.4.0

package/dist/index.d.ts

@@ -236,7 +236,6 @@ interface TextGeometryInfo {
         trianglesGenerated: number;
         verticesGenerated: number;
         pointsRemovedByVisvalingam: number;
-        pointsRemovedByColinear: number;
         originalPointCount: number;
     } & Partial<CacheStats & {
         hitRate: number;
@@ -300,6 +299,7 @@ interface TextOptions {
     };
     maxTextLength?: number;
     removeOverlaps?: boolean;
+    curveSteps?: number;
     curveFidelity?: CurveFidelityConfig;
     geometryOptimization?: GeometryOptimizationOptions;
     layout?: LayoutOptions;
@@ -315,8 +315,6 @@ interface CurveFidelityConfig {
 interface GeometryOptimizationOptions {
     enabled?: boolean;
     areaThreshold?: number;
-    colinearThreshold?: number;
-    minSegmentLength?: number;
 }
 interface LayoutOptions {
     width?: number;

package/dist/index.js

@@ -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
@@ -195,7 +195,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();
@@ -226,7 +226,6 @@ class ActiveNodeList {
         this.nodesByKey.set(key, node);
         return true;
     }
-    // Swap-and-pop removal
     deactivate(node) {
         if (!node.active)
             return;
@@ -369,36 +368,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);
@@ -3039,15 +3068,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;
@@ -3056,7 +3082,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;
@@ -3066,11 +3095,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;
         }
@@ -3107,17 +3134,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)
@@ -3142,32 +3158,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);
@@ -3178,7 +3168,6 @@ class PathOptimizer {
     resetStats() {
         this.stats = {
             pointsRemovedByVisvalingam: 0,
-            pointsRemovedByColinear: 0,
             originalPointCount: 0
         };
     }
@@ -3229,6 +3218,7 @@ const COLLINEARITY_EPSILON = 1e-6;
 const RECURSION_LIMIT = 16;
 class Polygonizer {
     constructor(curveFidelityConfig) {
+        this.curveSteps = null;
         this.curveFidelityConfig = {
             ...DEFAULT_CURVE_FIDELITY,
             ...curveFidelityConfig
@@ -3240,18 +3230,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;
@@ -3278,8 +3327,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;
@@ -3664,6 +3713,9 @@ class GlyphContourCollector {
     setCurveFidelityConfig(config) {
         this.polygonizer.setCurveFidelityConfig(config);
     }
+    setCurveSteps(curveSteps) {
+        this.polygonizer.setCurveSteps(curveSteps);
+    }
     setGeometryOptimization(options) {
         this.pathOptimizer.setConfig({
             ...DEFAULT_OPTIMIZATION_CONFIG,
@@ -3817,6 +3869,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);
@@ -3830,22 +3897,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
@@ -3899,15 +3968,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;
                             }
@@ -3921,17 +3995,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) {
@@ -5362,7 +5471,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) {
@@ -5592,6 +5707,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) {
@@ -5633,6 +5749,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) {
@@ -5733,7 +5850,6 @@ class Text {
                 trianglesGenerated,
                 verticesGenerated,
                 pointsRemovedByVisvalingam: optimizationStats.pointsRemovedByVisvalingam,
-                pointsRemovedByColinear: optimizationStats.pointsRemovedByColinear,
                 originalPointCount: optimizationStats.originalPointCount
             },
             query: (() => {