three-text 0.2.6 → 0.2.8

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)
 
@@ -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,7 +298,7 @@ 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
@@ -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
 
@@ -395,7 +395,8 @@ The Knuth-Plass algorithm provides extensive control over line breaking quality:
 - **tolerance** (800): Maximum badness for the second pass with hyphenation
 - **emergencyStretch** (0): Additional stretchability for difficult paragraphs
 - **autoEmergencyStretch** (0.1): Emergency stretch as percentage of line width (e.g., 0.1 = 10%). Defaults to 10% for non-hyphenated text
-- **disableSingleWordDetection** (false): Disable automatic prevention of short single-word lines
+- **disableShortLineDetection** (false): Disable automatic prevention of short lines
+- **shortLineThreshold** (0.5): Width ratio threshold for short line detection (0.0 to 1.0)
 
 #### Advanced parameters
 
@@ -416,9 +417,9 @@ The Knuth-Plass algorithm provides extensive control over line breaking quality:
 
 Lower penalty/tolerance values produce tighter spacing but may fail to find acceptable breaks for challenging text
 
-#### Single-word line detection
+#### Short line detection
 
-By default, the library detects and prevents short single-word lines (words occupying less than 50% of the line width on non-final lines) by iteratively applying emergency stretch. This can be disabled if needed:
+By default, the library detects and prevents short lines (lines occupying less than 50% of the target width on non-final lines) by iteratively applying emergency stretch. This can be customized or disabled:
 
 ```javascript
 const text = await Text.create({
@@ -426,7 +427,9 @@ const text = await Text.create({
   font: '/fonts/Font.ttf',
   layout: {
     width: 1000,
-    disableSingleWordDetection: true,
+    shortLineThreshold: 0.6,  // Only flag lines < 60% width (more lenient)
+    // Or disable entirely:
+    // disableShortLineDetection: true,
   },
 });
 ```
@@ -754,9 +757,9 @@ interface LayoutOptions {
   pretolerance?: number; // Maximum badness for first pass (default: 100)
   emergencyStretch?: number; // Additional stretchability for difficult paragraphs
   autoEmergencyStretch?: number; // Emergency stretch as percentage of line width (defaults to 10% for non-hyphenated)
-  disableSingleWordDetection?: boolean; // Disable automatic single-word line prevention (default: false)
-  lefthyphenmin?: number; // Minimum character
-  // s before hyphen (default: 2)
+  disableShortLineDetection?: boolean; // Disable automatic short line prevention (default: false)
+  shortLineThreshold?: number; // Width ratio threshold for short line detection (default: 0.5)
+  lefthyphenmin?: number; // Minimum characters before hyphen (default: 2)
   righthyphenmin?: number; // Minimum characters after hyphen (default: 4)
   linepenalty?: number; // Base penalty per line (default: 10)
   adjdemerits?: number; // Penalty for incompatible fitness classes (default: 10000)
@@ -940,9 +943,9 @@ While `three-text` runs on all modern browsers, performance varies significantly
 
 **Chrome** provides the best experience
 
-**Firefox** also delivers great performance but may exhibit less responsive mouse interactions in WebGL contexts due to the way it handles events
+**Firefox** also delivers great performance but may exhibit less responsive mouse interactions
 
-**Safari** for macOS shows reduced performance, which is likely due to the platform's conservative resource management, particularly around battery life; 120FPS is not acheivable
+**Safari** for macOS shows reduced performance, which is likely due to the platform's conservative resource management; 120FPS is not acheivable
 
 The library was also tested on a Brightsign 223HD, which took a long time to generate the initial geometry but seemed fine after that
 
@@ -958,6 +961,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