three-text 0.3.4 → 0.4.0

package/dist/index.umd.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
@@ -200,7 +200,7 @@
         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();
@@ -231,7 +231,6 @@
             this.nodesByKey.set(key, node);
             return true;
         }
-        // Swap-and-pop removal
         deactivate(node) {
             if (!node.active)
                 return;
@@ -374,36 +373,66 @@
             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);
@@ -3046,15 +3075,12 @@
 
     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;
@@ -3063,7 +3089,10 @@
             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;
@@ -3073,11 +3102,9 @@
             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;
             }
@@ -3114,17 +3141,6 @@
                 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)
@@ -3149,32 +3165,6 @@
             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);
@@ -3185,7 +3175,6 @@
         resetStats() {
             this.stats = {
                 pointsRemovedByVisvalingam: 0,
-                pointsRemovedByColinear: 0,
                 originalPointCount: 0
             };
         }
@@ -3236,6 +3225,7 @@
     const RECURSION_LIMIT = 16;
     class Polygonizer {
         constructor(curveFidelityConfig) {
+            this.curveSteps = null;
             this.curveFidelityConfig = {
                 ...DEFAULT_CURVE_FIDELITY,
                 ...curveFidelityConfig
@@ -3247,18 +3237,77 @@
                 ...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;
@@ -3285,8 +3334,8 @@
                     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;
@@ -3671,6 +3720,9 @@
         setCurveFidelityConfig(config) {
             this.polygonizer.setCurveFidelityConfig(config);
         }
+        setCurveSteps(curveSteps) {
+            this.polygonizer.setCurveSteps(curveSteps);
+        }
         setGeometryOptimization(options) {
             this.pathOptimizer.setConfig({
                 ...DEFAULT_OPTIMIZATION_CONFIG,
@@ -3824,6 +3876,21 @@
             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);
@@ -3837,22 +3904,24 @@
             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
@@ -3906,15 +3975,20 @@
                         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;
                                 }
@@ -3928,17 +4002,52 @@
                             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) {
@@ -5369,7 +5478,13 @@
                     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) {
@@ -5599,6 +5714,7 @@
                                     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) {
@@ -5640,6 +5756,7 @@
                                     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) {
@@ -5740,7 +5857,6 @@
                     trianglesGenerated,
                     verticesGenerated,
                     pointsRemovedByVisvalingam: optimizationStats.pointsRemovedByVisvalingam,
-                    pointsRemovedByColinear: optimizationStats.pointsRemovedByColinear,
                     originalPointCount: optimizationStats.originalPointCount
                 },
                 query: (() => {