three-text 0.5.1 → 0.5.2

package/README.md

@@ -71,10 +71,10 @@ three-text has a framework-agnostic core that processes fonts and generates geom
 - **`three-text/mesh/webgpu`** - WebGPU mesh buffer utility
 - **`three-text/mesh/p5`** - p5.js adapter
 - **`three-text/core`** - Framework-agnostic core (returns raw arrays)
-- **`three-text/vector`** - Vector rendering (Loop-Blinn and Kokojima stencil fill, resolution-independent)
+- **`three-text/vector`** - Vector rendering (Loop-Blinn curve eval + Kokojima stencil fill), `Text.create()` returns a `THREE.Group` ready for `scene.add()`
 - **`three-text/vector/react`** - React Three Fiber component for vector text
-- **`three-text/vector/webgl`** - WebGL vector renderer
-- **`three-text/vector/webgpu`** - WebGPU vector renderer
+- **`three-text/vector/webgl`** - Raw WebGL2 vector renderer (no Three.js dependency)
+- **`three-text/vector/webgpu`** - Raw WebGPU vector renderer (no Three.js dependency)
 - **`three-text/webgl`** - Deprecated, use `three-text/mesh/webgl`
 - **`three-text/webgpu`** - Deprecated, use `three-text/mesh/webgpu`
 - **`three-text/p5`** - Deprecated, use `three-text/mesh/p5`
@@ -121,20 +121,18 @@ Resolution-independent outlines via Loop-Blinn stencil passes (see [Vector rende
 
 ```javascript
 import { Text } from 'three-text/vector';
-import { woff2Decode } from 'woff-lib/woff2/decode';
 
 Text.setHarfBuzzPath('/hb/hb.wasm');
-Text.enableWoff2(woff2Decode);
 const result = await Text.create({
   text: 'Hello Vector',
   font: '/fonts/Font.woff2',
-  size: 72
+  size: 72,
+  color: '#ffffff'
 });
-
-const vectorData = result.geometryData;
+scene.add(result.group);
 ```
 
-Use `createVectorMeshes(vectorData)` from `three-text/vector` for TSL / `WebGPURenderer`, or build your own stencil materials (see [Vector rendering](#vector-rendering))
+`Text.create()` handles stencil setup, render ordering, and geometry centering internally. Pass `positionNode` and `colorNode` for TSL animation/styling. For raw WebGL2 or WebGPU without Three.js, see [Vector rendering](#vector-rendering)
 
 #### Mesh + vector in one scene
 
@@ -142,7 +140,7 @@ Alias one import to avoid the name collision between `Text` components. The entr
 
 ```javascript
 import { Text as MeshText } from 'three-text';
-import { Text as VectorText, createVectorMeshes } from 'three-text/vector';
+import { Text as VectorText } from 'three-text/vector';
 
 MeshText.setHarfBuzzPath('/hb/hb.wasm');
 
@@ -156,10 +154,10 @@ scene.add(new THREE.Mesh(heading.geometry, material));
 const caption = await VectorText.create({
   text: 'Caption text',
   font: '/fonts/Font.woff2',
-  size: 24
+  size: 24,
+  color: '#ffffff'
 });
-const { interiorMesh, curveMesh, fillMesh } = createVectorMeshes(caption.geometryData);
-scene.add(interiorMesh, curveMesh, fillMesh);
+scene.add(caption.group);
 ```
 
 #### React Three Fiber — mesh
@@ -477,8 +475,9 @@ three-text/
 │   │   ├── react.tsx           # React component export
 │   │   └── ThreeText.tsx       # React Three Fiber component
 │   ├── vector/                 # Vector rendering (Loop-Blinn)
-│   │   ├── index.ts            # Vector entry point and TSL re-exports
-│   │   ├── loopBlinnTSL.ts                # TSL adapter for Three.js WebGPURenderer
+│   │   ├── index.ts            # Main entry point (wraps core + Three.js integration)
+│   │   ├── core.ts             # Three.js-free layout engine (used by raw WebGL/WebGPU)
+│   │   ├── loopBlinnTSL.ts                # TSL stencil materials and mesh construction
 │   │   ├── LoopBlinnGeometry.ts           # Fan triangulation + curve extraction
 │   │   ├── GlyphVectorGeometryBuilder.ts  # Outline collection and geometry packing
 │   │   ├── GlyphOutlineCollector.ts       # Collects draw callbacks for vector path
@@ -537,7 +536,7 @@ The multi-stage geometry approach (curve polygonization followed by cleanup, the
 
 The vector pipeline (`three-text/vector`) renders glyphs directly from their mathematical outlines without tessellation or curve flattening. Text stays sharp at any zoom level and the geometry footprint is small -- just the control points of each curve
 
-Curves use the [Loop-Blinn](https://www.microsoft.com/en-us/research/wp-content/uploads/2005/01/p1000-loop.pdf) technique: each quadratic curve is rendered as a triangle whose fragment shader evaluates `u² - v` to resolve inside/outside, with screen-space derivatives producing a signed distance that feeds alpha-to-coverage for smooth MSAA edges. Glyph interiors use [Kokojima et al.](https://dl.acm.org/doi/10.1145/1179849.1179997) stencil filling: fan-triangulate, stencil XOR, fill where nonzero
+Curves use the [Loop-Blinn](https://www.microsoft.com/en-us/research/wp-content/uploads/2005/01/p1000-loop.pdf) technique: each quadratic curve is rendered as a triangle whose fragment shader evaluates `u² - v` to resolve inside/outside, with screen-space derivatives producing a signed distance that feeds alpha-to-coverage for smooth MSAA edges. Glyph interiors use [Kokojima et al.](https://dl.acm.org/doi/10.1145/1179849.1179997) stencil filling with a nonzero winding rule (`INCR_WRAP`/`DECR_WRAP`), which correctly handles overlapping contours in variable fonts and connected scripts
 
 An alternative for this sort of resolution-independent rendering is [Slug](https://github.com/EricLengyel/Slug) by Eric Lengyel, which casts rays against all curves per fragment to compute winding numbers. Loop-Blinn was chosen here because it integrates with hardware MSAA and alpha-to-coverage directly, without the overhead of adaptive supersampling that Slug requires for comparable antialiasing
 

package/dist/index.cjs

@@ -1,6 +1,6 @@
 /*!
  * @license
- * three-text v0.5.1
+ * three-text v0.5.2
  * Copyright © 2025-2026 Jeremy Tribby, Countertype LLC
  * SPDX-License-Identifier: MIT
  */
@@ -3263,6 +3263,8 @@ class Text {
     static { this.patternCache = new Map(); }
     static { this.hbInitPromise = null; }
     static { this.fontCache = new Map(); }
+    static { this.fontLoadPromises = new Map(); }
+    static { this.fontRefCounts = new Map(); }
     static { this.fontCacheMemoryBytes = 0; }
     static { this.maxFontCacheMemoryBytes = Infinity; }
     static { this.fontIdCounter = 0; }
@@ -3307,9 +3309,9 @@ class Text {
         if (!Text.hbInitPromise) {
             Text.hbInitPromise = HarfBuzzLoader.getHarfBuzz();
         }
-        const loadedFont = await Text.resolveFont(options);
+        const { loadedFont, fontKey } = await Text.resolveFont(options);
         const text = new Text();
-        text.setLoadedFont(loadedFont);
+        text.setLoadedFont(loadedFont, fontKey);
         const result = await text.createLayout(options);
         const update = async (newOptions) => {
             const mergedOptions = { ...options };
@@ -3322,8 +3324,8 @@ class Text {
             if (newOptions.font !== undefined ||
                 newOptions.fontVariations !== undefined ||
                 newOptions.fontFeatures !== undefined) {
-                const newLoadedFont = await Text.resolveFont(mergedOptions);
-                text.setLoadedFont(newLoadedFont);
+                const { loadedFont: newLoadedFont, fontKey: newFontKey } = await Text.resolveFont(mergedOptions);
+                text.setLoadedFont(newLoadedFont, newFontKey);
                 text.resetHelpers();
             }
             options = mergedOptions;
@@ -3344,6 +3346,22 @@ class Text {
             dispose: () => text.destroy()
         };
     }
+    static retainFont(fontKey) {
+        Text.fontRefCounts.set(fontKey, (Text.fontRefCounts.get(fontKey) ?? 0) + 1);
+    }
+    static releaseFont(fontKey, loadedFont) {
+        const nextCount = (Text.fontRefCounts.get(fontKey) ?? 0) - 1;
+        if (nextCount > 0) {
+            Text.fontRefCounts.set(fontKey, nextCount);
+            return;
+        }
+        Text.fontRefCounts.delete(fontKey);
+        // Cached fonts stay alive while present in the cache. If a font has been
+        // evicted, destroy it once the last live handle releases it.
+        if (!Text.fontCache.has(fontKey)) {
+            FontLoader.destroyFont(loadedFont);
+        }
+    }
     static async resolveFont(options) {
         const baseFontKey = typeof options.font === 'string'
             ? options.font
@@ -3357,9 +3375,17 @@ class Text {
         }
         let loadedFont = Text.fontCache.get(fontKey);
         if (!loadedFont) {
-            loadedFont = await Text.loadAndCacheFont(fontKey, options.font, options.fontVariations, options.fontFeatures);
+            let loadPromise = Text.fontLoadPromises.get(fontKey);
+            if (!loadPromise) {
+                loadPromise = Text.loadAndCacheFont(fontKey, options.font, options.fontVariations, options.fontFeatures).finally(() => {
+                    Text.fontLoadPromises.delete(fontKey);
+                });
+                Text.fontLoadPromises.set(fontKey, loadPromise);
+            }
+            loadedFont = await loadPromise;
         }
-        return loadedFont;
+        Text.retainFont(fontKey);
+        return { loadedFont, fontKey };
     }
     static async loadAndCacheFont(fontKey, font, fontVariations, fontFeatures) {
         const tempText = new Text();
@@ -3391,8 +3417,12 @@ class Text {
             const firstKey = Text.fontCache.keys().next().value;
             if (firstKey === undefined)
                 break;
+            const font = Text.fontCache.get(firstKey);
             Text.trackFontCacheRemove(firstKey);
             Text.fontCache.delete(firstKey);
+            if ((Text.fontRefCounts.get(firstKey) ?? 0) <= 0 && font) {
+                FontLoader.destroyFont(font);
+            }
         }
     }
     static generateFontContentHash(buffer) {
@@ -3414,8 +3444,12 @@ class Text {
             return `c${++Text.fontIdCounter}`;
         }
     }
-    setLoadedFont(loadedFont) {
+    setLoadedFont(loadedFont, fontKey) {
+        if (this.loadedFont && this.loadedFont !== loadedFont) {
+            this.releaseCurrentFont();
+        }
         this.loadedFont = loadedFont;
+        this.currentFontCacheKey = fontKey;
         const contentHash = Text.generateFontContentHash(loadedFont._buffer);
         this.currentFontId = `font_${contentHash}`;
         if (loadedFont.fontVariations) {
@@ -3425,6 +3459,29 @@ class Text {
             this.currentFontId += `_feat_${Text.stableStringify(loadedFont.fontFeatures)}`;
         }
     }
+    releaseCurrentFont() {
+        if (!this.loadedFont)
+            return;
+        const currentFont = this.loadedFont;
+        const currentFontKey = this.currentFontCacheKey;
+        try {
+            if (currentFontKey) {
+                Text.releaseFont(currentFontKey, currentFont);
+            }
+            else {
+                FontLoader.destroyFont(currentFont);
+            }
+        }
+        catch (error) {
+            logger.warn('Error destroying HarfBuzz objects:', error);
+        }
+        finally {
+            this.loadedFont = undefined;
+            this.currentFontCacheKey = undefined;
+            this.textLayout = undefined;
+            this.textShaper = undefined;
+        }
+    }
     async loadFont(fontSrc, fontVariations, fontFeatures) {
         perfLogger.start('Text.loadFont', {
             fontSrc: typeof fontSrc === 'string' ? fontSrc : `buffer(${fontSrc.byteLength})`
@@ -3644,18 +3701,7 @@ class Text {
         if (!this.loadedFont) {
             return;
         }
-        const currentFont = this.loadedFont;
-        try {
-            FontLoader.destroyFont(currentFont);
-        }
-        catch (error) {
-            logger.warn('Error destroying HarfBuzz objects:', error);
-        }
-        finally {
-            this.loadedFont = undefined;
-            this.textLayout = undefined;
-            this.textShaper = undefined;
-        }
+        this.releaseCurrentFont();
     }
 }
 

package/dist/index.d.ts

@@ -457,6 +457,8 @@ declare class Text {
     private static patternCache;
     private static hbInitPromise;
     private static fontCache;
+    private static fontLoadPromises;
+    private static fontRefCounts;
     private static fontCacheMemoryBytes;
     private static maxFontCacheMemoryBytes;
     private static fontIdCounter;
@@ -465,6 +467,7 @@ declare class Text {
     private fontLoader;
     private loadedFont?;
     private currentFontId;
+    private currentFontCacheKey?;
     private textShaper?;
     private textLayout?;
     private constructor();
@@ -472,6 +475,8 @@ declare class Text {
     static setHarfBuzzBuffer(wasmBuffer: ArrayBuffer): void;
     static init(): Promise<HarfBuzzInstance>;
     static create(options: TextOptions): Promise<TextLayoutHandle>;
+    private static retainFont;
+    private static releaseFont;
     private static resolveFont;
     private static loadAndCacheFont;
     private static trackFontCacheAdd;
@@ -479,6 +484,7 @@ declare class Text {
     private static enforceFontCacheMemoryLimit;
     private static generateFontContentHash;
     private setLoadedFont;
+    private releaseCurrentFont;
     private loadFont;
     private createLayout;
     private prepareHyphenation;

package/dist/index.js

@@ -1,6 +1,6 @@
 /*!
  * @license
- * three-text v0.5.1
+ * three-text v0.5.2
  * Copyright © 2025-2026 Jeremy Tribby, Countertype LLC
  * SPDX-License-Identifier: MIT
  */
@@ -3260,6 +3260,8 @@ class Text {
     static { this.patternCache = new Map(); }
     static { this.hbInitPromise = null; }
     static { this.fontCache = new Map(); }
+    static { this.fontLoadPromises = new Map(); }
+    static { this.fontRefCounts = new Map(); }
     static { this.fontCacheMemoryBytes = 0; }
     static { this.maxFontCacheMemoryBytes = Infinity; }
     static { this.fontIdCounter = 0; }
@@ -3304,9 +3306,9 @@ class Text {
         if (!Text.hbInitPromise) {
             Text.hbInitPromise = HarfBuzzLoader.getHarfBuzz();
         }
-        const loadedFont = await Text.resolveFont(options);
+        const { loadedFont, fontKey } = await Text.resolveFont(options);
         const text = new Text();
-        text.setLoadedFont(loadedFont);
+        text.setLoadedFont(loadedFont, fontKey);
         const result = await text.createLayout(options);
         const update = async (newOptions) => {
             const mergedOptions = { ...options };
@@ -3319,8 +3321,8 @@ class Text {
             if (newOptions.font !== undefined ||
                 newOptions.fontVariations !== undefined ||
                 newOptions.fontFeatures !== undefined) {
-                const newLoadedFont = await Text.resolveFont(mergedOptions);
-                text.setLoadedFont(newLoadedFont);
+                const { loadedFont: newLoadedFont, fontKey: newFontKey } = await Text.resolveFont(mergedOptions);
+                text.setLoadedFont(newLoadedFont, newFontKey);
                 text.resetHelpers();
             }
             options = mergedOptions;
@@ -3341,6 +3343,22 @@ class Text {
             dispose: () => text.destroy()
         };
     }
+    static retainFont(fontKey) {
+        Text.fontRefCounts.set(fontKey, (Text.fontRefCounts.get(fontKey) ?? 0) + 1);
+    }
+    static releaseFont(fontKey, loadedFont) {
+        const nextCount = (Text.fontRefCounts.get(fontKey) ?? 0) - 1;
+        if (nextCount > 0) {
+            Text.fontRefCounts.set(fontKey, nextCount);
+            return;
+        }
+        Text.fontRefCounts.delete(fontKey);
+        // Cached fonts stay alive while present in the cache. If a font has been
+        // evicted, destroy it once the last live handle releases it.
+        if (!Text.fontCache.has(fontKey)) {
+            FontLoader.destroyFont(loadedFont);
+        }
+    }
     static async resolveFont(options) {
         const baseFontKey = typeof options.font === 'string'
             ? options.font
@@ -3354,9 +3372,17 @@ class Text {
         }
         let loadedFont = Text.fontCache.get(fontKey);
         if (!loadedFont) {
-            loadedFont = await Text.loadAndCacheFont(fontKey, options.font, options.fontVariations, options.fontFeatures);
+            let loadPromise = Text.fontLoadPromises.get(fontKey);
+            if (!loadPromise) {
+                loadPromise = Text.loadAndCacheFont(fontKey, options.font, options.fontVariations, options.fontFeatures).finally(() => {
+                    Text.fontLoadPromises.delete(fontKey);
+                });
+                Text.fontLoadPromises.set(fontKey, loadPromise);
+            }
+            loadedFont = await loadPromise;
         }
-        return loadedFont;
+        Text.retainFont(fontKey);
+        return { loadedFont, fontKey };
     }
     static async loadAndCacheFont(fontKey, font, fontVariations, fontFeatures) {
         const tempText = new Text();
@@ -3388,8 +3414,12 @@ class Text {
             const firstKey = Text.fontCache.keys().next().value;
             if (firstKey === undefined)
                 break;
+            const font = Text.fontCache.get(firstKey);
             Text.trackFontCacheRemove(firstKey);
             Text.fontCache.delete(firstKey);
+            if ((Text.fontRefCounts.get(firstKey) ?? 0) <= 0 && font) {
+                FontLoader.destroyFont(font);
+            }
         }
     }
     static generateFontContentHash(buffer) {
@@ -3411,8 +3441,12 @@ class Text {
             return `c${++Text.fontIdCounter}`;
         }
     }
-    setLoadedFont(loadedFont) {
+    setLoadedFont(loadedFont, fontKey) {
+        if (this.loadedFont && this.loadedFont !== loadedFont) {
+            this.releaseCurrentFont();
+        }
         this.loadedFont = loadedFont;
+        this.currentFontCacheKey = fontKey;
         const contentHash = Text.generateFontContentHash(loadedFont._buffer);
         this.currentFontId = `font_${contentHash}`;
         if (loadedFont.fontVariations) {
@@ -3422,6 +3456,29 @@ class Text {
             this.currentFontId += `_feat_${Text.stableStringify(loadedFont.fontFeatures)}`;
         }
     }
+    releaseCurrentFont() {
+        if (!this.loadedFont)
+            return;
+        const currentFont = this.loadedFont;
+        const currentFontKey = this.currentFontCacheKey;
+        try {
+            if (currentFontKey) {
+                Text.releaseFont(currentFontKey, currentFont);
+            }
+            else {
+                FontLoader.destroyFont(currentFont);
+            }
+        }
+        catch (error) {
+            logger.warn('Error destroying HarfBuzz objects:', error);
+        }
+        finally {
+            this.loadedFont = undefined;
+            this.currentFontCacheKey = undefined;
+            this.textLayout = undefined;
+            this.textShaper = undefined;
+        }
+    }
     async loadFont(fontSrc, fontVariations, fontFeatures) {
         perfLogger.start('Text.loadFont', {
             fontSrc: typeof fontSrc === 'string' ? fontSrc : `buffer(${fontSrc.byteLength})`
@@ -3641,18 +3698,7 @@ class Text {
         if (!this.loadedFont) {
             return;
         }
-        const currentFont = this.loadedFont;
-        try {
-            FontLoader.destroyFont(currentFont);
-        }
-        catch (error) {
-            logger.warn('Error destroying HarfBuzz objects:', error);
-        }
-        finally {
-            this.loadedFont = undefined;
-            this.textLayout = undefined;
-            this.textShaper = undefined;
-        }
+        this.releaseCurrentFont();
     }
 }