three-text 0.2.5 → 0.2.7

package/README.md

@@ -15,7 +15,7 @@ A high fidelity 3D font renderer and text layout engine for the web
 > [!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** renders and formats text from TTF, OTF, and WOFF font files as 3D geometry. It uses [TeX](https://en.wikipedia.org/wiki/TeX)-based parameters for breaking text into paragraphs across multiple lines, and turns font outlines into 3D shapes on the fly, caching their geometries for low CPU overhead in languages with lots of repeating glyphs. Variable fonts are supported as static instances at a given axis coordinate
+**three-text** renders and formats text from TTF, OTF, and WOFF font files as 3D geometry. It uses [TeX](https://en.wikipedia.org/wiki/TeX)-based parameters for breaking text into paragraphs across multiple lines, and turns font outlines into 3D shapes on the fly. Glyph geometry is cached for low CPU overhead, especially in languages with lots of repeating glyphs. Variable fonts are supported as static instances at a given axis coordinate
 
 The library has a framework-agnostic core that returns raw vertex data, with lightweight adapters for [Three.js](https://threejs.org), [React Three Fiber](https://docs.pmnd.rs/react-three-fiber), [p5.js](https://p5js.org), [WebGL](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API), and [WebGPU](https://developer.mozilla.org/en-US/docs/Web/API/WebGPU_API)
 
@@ -235,7 +235,7 @@ Then navigate to `http://localhost:3000`
 
 ## Why three-text?
 
-three-text generates high-fidelity 3D mesh geometry from font files. Unlike texture-based approaches, it produces true geometry that can be lit, shaded, and manipulated like any 3D model.
+three-text generates high-fidelity 3D mesh geometry from font files. Unlike texture-based approaches, it produces true geometry that can be lit, shaded, and manipulated like any 3D model
 
 Existing solutions take different approaches:
 
@@ -243,7 +243,7 @@ Existing solutions take different approaches:
 - **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-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 tessellated glyphs, so a paragraph of 1000 words might only require 50 tessellations depending on the language. 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 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
 
 ## Library structure
 
@@ -298,14 +298,14 @@ Hyphenation uses patterns derived from the Tex hyphenation project, converted in
 
 ### Geometry generation and optimization
 
-To optimize performance, three-text generates the geometry for each unique glyph or glyph cluster only once. The result is stored in a cache for reuse. This initial geometry creation is a multi-stage pipeline:
+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
 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
-4. **Overlap removal**: removes self-intersections and resolves overlapping paths between glyphs, preserving correct winding rules for triangulation.
+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)
 
@@ -315,7 +315,7 @@ The multi-stage geometry approach (curve polygonization followed by cleanup, the
 
 The library uses a hybrid caching strategy to maximize performance while ensuring visual correctness
 
-By default, it operates with glyph-level cache. The geometry for each unique character (`a`, `b`, `c`...) is generated only once and stored for reuse to avoiding redundant computation
+By default, it operates with glyph-level cache. The geometry for each unique character (`a`, `b`, `c`...) is generated only once and stored for reuse, avoiding redundant computation
 
 For text with tight tracking, connected scripts, or complex kerning pairs, individual glyphs can overlap. When an overlap within a word is found, the entire word is treated as a single unit and escalated to a word-level cache. All of its glyphs are tessellated together to correctly resolve the overlaps, and the resulting geometry for the word is cached
 
@@ -334,7 +334,7 @@ The library converts bezier curves into line segments by recursively subdividing
 - `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`
 
-In general, this step helps more with time to first render than ongoing interactions in the scene.
+In general, this step helps more with time to first render than ongoing interactions in the scene
 
 ```javascript
 // Using the default configuration
@@ -466,25 +466,6 @@ const text = await Text.create({
 });
 ```
 
-### Per-glyph animation attributes
-
-For shader-based animations and interactive effects, the library can generate per-vertex attributes that identify which glyph each vertex belongs to:
-
-```javascript
-const text = await Text.create({
-  text: 'Sample text',
-  font: '/fonts/Font.ttf',
-  separateGlyphsWithAttributes: true,
-});
-
-// Geometry includes these vertex attributes:
-// - glyphCenter (vec3): center point of each glyph
-// - glyphIndex (float): sequential glyph index
-// - glyphLineIndex (float): line number
-```
-
-This option bypasses overlap-based clustering and adds vertex attributes suitable for per-character manipulation in vertex shaders. Each unique glyph is still tessellated only once and cached for reuse. The tradeoff is potential visual artifacts where glyphs actually overlap (tight kerning, cursive scripts)
-
 ### Variable fonts
 
 Variable fonts allow dynamic adjustment of typographic characteristics through variation axes:
@@ -537,6 +518,47 @@ const text = await Text.create({
 });
 ```
 
+### OpenType features
+
+The `fontFeatures` option controls OpenType layout features using 4-character tags from the [feature registry](https://learn.microsoft.com/en-us/typography/opentype/spec/featuretags):
+
+```javascript
+const text = await Text.create({
+  text: 'Difficult ffi ffl',
+  font: '/fonts/Font.ttf',
+  fontFeatures: {
+    liga: true,
+    dlig: true,
+    kern: false,
+    ss01: 1,
+    cv01: 3,
+  },
+});
+```
+
+Values can be boolean (`true`/`false`) to enable or disable, or numeric for features accepting variant indices. Explicitly disabling a feature overrides the font's defaults
+
+Common tags include [`liga`](https://learn.microsoft.com/en-us/typography/opentype/spec/features_ko#liga) (ligatures), [`kern`](https://learn.microsoft.com/en-us/typography/opentype/spec/features_ko#kern) (kerning), [`calt`](https://learn.microsoft.com/en-us/typography/opentype/spec/features_ae#calt) (contextual alternates), and [`smcp`](https://learn.microsoft.com/en-us/typography/opentype/spec/features_pt#smcp) (small capitals). Number styling uses [`lnum`](https://learn.microsoft.com/en-us/typography/opentype/spec/features_ko#lnum)/[`onum`](https://learn.microsoft.com/en-us/typography/opentype/spec/features_ko#onum)/[`tnum`](https://learn.microsoft.com/en-us/typography/opentype/spec/features_pt#tnum). Stylistic alternates are [`ss01`-`ss20`](https://learn.microsoft.com/en-us/typography/opentype/spec/features_pt#ss01--ss20) and [`cv01`-`cv99`](https://learn.microsoft.com/en-us/typography/opentype/spec/features_ae#cv01--cv99). Feature availability depends on the font
+
+### Per-glyph attributes
+
+For shader-based animations and interactive effects, the library can generate per-vertex attributes that identify which glyph each vertex belongs to:
+
+```javascript
+const text = await Text.create({
+  text: 'Sample text',
+  font: '/fonts/Font.ttf',
+  separateGlyphsWithAttributes: true,
+});
+
+// Geometry includes these vertex attributes:
+// - glyphCenter (vec3): center point of each glyph
+// - glyphIndex (float): sequential glyph index
+// - glyphLineIndex (float): line number
+```
+
+This option bypasses overlap-based clustering and adds vertex attributes suitable for per-character manipulation in vertex shaders. Each unique glyph is still tessellated only once and cached for reuse. The tradeoff is potential visual artifacts where glyphs actually overlap (tight kerning, cursive scripts)
+
 ## Querying text content
 
 After creating text geometry, use the `query()` method to find text ranges:
@@ -634,7 +656,7 @@ The library's full TypeScript definitions are the most complete source of truth
 
 #### `Text.create(options: TextOptions): Promise<TextGeometryInfo>`
 
-Creates text geometry with automatic font loading and HarfBuzz initialization.
+Creates text geometry with automatic font loading and HarfBuzz initialization
 
 **Core (`three-text`) returns:**
 - `vertices: Float32Array` - Vertex positions
@@ -694,6 +716,7 @@ interface TextOptions {
   lineHeight?: number; // Line height multiplier (default: 1.0)
   letterSpacing?: number; // Letter spacing as a fraction of em (e.g., 0.05)
   fontVariations?: { [key: string]: number }; // Variable font axis settings
+  fontFeatures?: { [tag: string]: boolean | number }; // OpenType feature settings
   removeOverlaps?: boolean; // Override default overlap removal (auto-enabled for VF only)
   separateGlyphsWithAttributes?: boolean; // Force individual glyph tessellation and add shader attributes
   color?: [number, number, number] | ColorOptions; // Text coloring (simple or complex)
@@ -935,6 +958,23 @@ npm test -- --coverage # Coverage report
 
 Tests use mocked HarfBuzz and tessellation libraries for fast execution without requiring WASM files
 
+### Benchmarking
+
+For performance of the real pipeline using HarfBuzz, including shaping, layout, tessellation, extrusion, there is a dedicated benchmark:
+
+```bash
+npm run benchmark
+```
+
+This runs a Node/Vitest scenario that:
+
+- initializes HarfBuzz from `hb.wasm` via `Text.setHarfBuzzBuffer`
+- loads Nimbus Sans and tests the example paragraph from the demos
+- performs a small number of cold runs followed by warm runs of `Text.create()` with justification and hyphenation enabled
+- prints a per-stage timing table (font load, line breaking, polygonization, tessellation, extrusion, and overall geometry creation)
+
+Use this to compare changes locally; it is meant as a sanity check on real work rather than a reliable micro-benchmark
+
 ## Build system
 
 ### Development