three-text 0.4.5 → 0.4.7

package/README.md

@@ -15,7 +15,7 @@ High fidelity 3D mesh font geometry and text layout engine for the web
 > [!CAUTION]
 > three-text is an alpha release and the API may break rapidly. This warning will likely last until the end of March 2026. 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** is a 3D mesh font geometry and text layout library for the web. It supports TTF, OTF, and WOFF font files. For layout, it uses [TeX](https://en.wikipedia.org/wiki/TeX)-based parameters for breaking text into paragraphs across multiple lines and supports CJK and RTL scripts. three-text caches the geometries it generates for low CPU overhead in languages with lots of repeating glyphs. Variable fonts are supported as static instances at a given axis coordinate, and can be animated by re-drawing each frame with new coordinates
+**three-text** is a 3D mesh font geometry and text layout library for the web. It supports TTF, OTF, WOFF, and WOFF2 font files. For layout, it uses [TeX](https://en.wikipedia.org/wiki/TeX)-based parameters for breaking text into paragraphs across multiple lines and supports CJK and RTL scripts. three-text caches the geometries it generates for low CPU overhead in languages with lots of repeating glyphs. Variable fonts are supported as static instances at a given axis coordinate, and can be animated by re-drawing each frame with new coordinates
 
 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)
 
@@ -63,14 +63,15 @@ npm install three
 
 three-text has a framework-agnostic core that processes fonts and generates geometry data. Lightweight adapters convert this data to framework-specific formats:
 
-- **`three-text`** - Core (returns raw arrays)
-- **`three-text/three`** - Three.js (returns BufferGeometry)
+- **`three-text`** - Three.js adapter (default export, returns BufferGeometry)
+- **`three-text/three`** - Same as above (explicit alias)
 - **`three-text/three/react`** - React Three Fiber component
+- **`three-text/core`** - Framework-agnostic core (returns raw arrays)
 - **`three-text/webgl`** - WebGL buffer utility
 - **`three-text/webgpu`** - WebGPU buffer utility
 - **`three-text/p5`** - p5.js adapter
 
-Choose the import that matches your stack. Most users will use `three-text/three` or `three-text/p5`
+Most users will just `import { Text } from 'three-text'` for Three.js projects
 
 ### Basic Usage
 
@@ -78,13 +79,14 @@ Choose the import that matches your stack. Most users will use `three-text/three
 
 ```javascript
 import { Text } from 'three-text/three';
+import { decode } from 'woff2-decode'; // Optional
 import * as THREE from 'three';
 
 Text.setHarfBuzzPath('/hb/hb.wasm');
-
+Text.enableWoff2(decode); // Enabling WOFF2 support adds ~45kb to the bundle
 const result = await Text.create({
   text: 'Hello World',
-  font: '/fonts/Font.woff',
+  font: '/fonts/Font.woff2',
   size: 72
 });
 
@@ -116,13 +118,15 @@ function App() {
 
 ```javascript
 import 'three-text/p5';
+import { decode } from 'woff2-decode';
 
 let font;
 let textResult;
 
 function preload() {
   loadThreeTextShaper('/hb/hb.wasm');
-  font = loadThreeTextFont('/fonts/Font.woff');
+  enableThreeTextWoff2(decode); // Optional, adds ~45KB to bundle
+  font = loadThreeTextFont('/fonts/Font.woff2');
 }
 
 async function setup() {
@@ -730,7 +734,7 @@ Below are the most important configuration interfaces. For a complete list of al
 ```typescript
 interface TextOptions {
   text: string; // Text content to render
-  font: string | ArrayBuffer; // Font file path or buffer (TTF, OTF, or WOFF)
+  font: string | ArrayBuffer; // Font file path or buffer (TTF, OTF, WOFF, or WOFF2)
   size?: number; // Font size in scene units (default: 72)
   depth?: number; // Extrusion depth (default: 0)
   lineHeight?: number; // Line height multiplier (default: 1.0)
@@ -913,7 +917,9 @@ The library requires WebAssembly support for HarfBuzz text shaping:
 - Safari 16.4+
 - Edge 80+
 
-WOFF fonts are automatically decompressed to TTF/OTF using the browser's native decompression with zero bundle cost. For older browsers, use TTF or OTF fonts directly
+WOFF fonts are automatically decompressed to TTF/OTF using the browser's native `DecompressionStream` API with zero bundle cost. For older browsers without `DecompressionStream`, use TTF or OTF fonts directly
+
+**WOFF2 font support** is opt-in (see [Basic Usage](#basic-usage))
 
 **ES modules** (recommended) are supported in:
 

package/dist/index.cjs

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.4.5
+ * three-text v0.4.7
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify
@@ -1469,7 +1469,7 @@ class FontMetadataExtractor {
             FONT_SIGNATURE_OPEN_TYPE_CFF
         ];
         if (!validSignatures.includes(sfntVersion)) {
-            throw new Error(`Invalid font format. Expected TTF/OTF (or WOFF), got signature: 0x${sfntVersion.toString(16)}`);
+            throw new Error(`Invalid font format. Expected TTF/OTF/WOFF/WOFF2, got signature: 0x${sfntVersion.toString(16)}`);
         }
         const tableDirectory = parseTableDirectory(view);
         const isCFF = tableDirectory.has(TABLE_TAG_CFF) || tableDirectory.has(TABLE_TAG_CFF2);
@@ -1658,7 +1658,7 @@ class FontMetadataExtractor {
             FONT_SIGNATURE_OPEN_TYPE_CFF
         ];
         if (!validSignatures.includes(sfntVersion)) {
-            throw new Error(`Invalid font format. Expected TTF/OTF (or WOFF), got signature: 0x${sfntVersion.toString(16)}`);
+            throw new Error(`Invalid font format. Expected TTF/OTF/WOFF/WOFF2, got signature: 0x${sfntVersion.toString(16)}`);
         }
         const tableDirectory = parseTableDirectory(view);
         const nameTableOffset = tableDirectory.get(TABLE_TAG_NAME)?.offset ?? 0;
@@ -1892,6 +1892,10 @@ class FontMetadataExtractor {
     }
 }
 
+let woff2Decoder = null;
+function setWoff2Decoder(decoder) {
+    woff2Decoder = decoder;
+}
 // Uses DecompressionStream to decompress WOFF (WOFF is just zlib compressed TTF/OTF so we can use deflate)
 class WoffConverter {
     static detectFormat(buffer) {
@@ -1993,6 +1997,21 @@ class WoffConverter {
         logger.log('WOFF font decompressed successfully');
         return sfntData.buffer.slice(0, sfntOffset);
     }
+    static async decompressWoff2(woff2Buffer) {
+        const view = new DataView(woff2Buffer);
+        const signature = view.getUint32(0);
+        if (signature !== FONT_SIGNATURE_WOFF2) {
+            throw new Error('Not a valid WOFF2 font');
+        }
+        if (!woff2Decoder) {
+            throw new Error('WOFF2 fonts require enabling the decoder. Add to your code:\n' +
+                "  import { decode } from 'woff2-decode';\n" +
+                '  Text.enableWoff2(decode);');
+        }
+        const decoded = await woff2Decoder(woff2Buffer);
+        logger.log('WOFF2 font decompressed successfully');
+        return decoded.buffer;
+    }
     static async decompressZlib(compressedData) {
         const stream = new ReadableStream({
             start(controller) {
@@ -2023,7 +2042,8 @@ class FontLoader {
             fontBuffer = await WoffConverter.decompressWoff(fontBuffer);
         }
         else if (format === 'woff2') {
-            throw new Error('WOFF2 fonts are not yet supported. Please use WOFF or TTF/OTF format.');
+            logger.log('WOFF2 font detected, decompressing...');
+            fontBuffer = await WoffConverter.decompressWoff2(fontBuffer);
         }
         const view = new DataView(fontBuffer);
         const sfntVersion = view.getUint32(0);
@@ -2032,7 +2052,7 @@ class FontLoader {
             FONT_SIGNATURE_OPEN_TYPE_CFF
         ];
         if (!validSignatures.includes(sfntVersion)) {
-            throw new Error(`Invalid font format. Expected TTF/OTF (or WOFF), got signature: 0x${sfntVersion.toString(16)}`);
+            throw new Error(`Invalid font format. Expected TTF/OTF/WOFF/WOFF2, got signature: 0x${sfntVersion.toString(16)}`);
         }
         const { hb, module } = await this.getHarfBuzzInstance();
         try {
@@ -5582,6 +5602,11 @@ class Text {
     static { this.fontCacheMemoryBytes = 0; }
     static { this.maxFontCacheMemoryBytes = Infinity; }
     static { this.fontIdCounter = 0; }
+    // Enable WOFF2 font support (adds ~45KB to bundle if imported)
+    // Usage: import { decode } from 'woff2-decode'; Text.enableWoff2(decode);
+    static enableWoff2(decoder) {
+        setWoff2Decoder(decoder);
+    }
     // Stringify with sorted keys for cache stability
     static stableStringify(obj) {
         const keys = Object.keys(obj).sort();

package/dist/index.d.ts

@@ -352,6 +352,7 @@ declare class Text {
     private static fontCacheMemoryBytes;
     private static maxFontCacheMemoryBytes;
     private static fontIdCounter;
+    static enableWoff2(decoder: (data: ArrayBuffer | Uint8Array) => Uint8Array | Promise<Uint8Array>): void;
     private static stableStringify;
     private fontLoader;
     private loadedFont?;

package/dist/index.js

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.4.5
+ * three-text v0.4.7
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify
@@ -1466,7 +1466,7 @@ class FontMetadataExtractor {
             FONT_SIGNATURE_OPEN_TYPE_CFF
         ];
         if (!validSignatures.includes(sfntVersion)) {
-            throw new Error(`Invalid font format. Expected TTF/OTF (or WOFF), got signature: 0x${sfntVersion.toString(16)}`);
+            throw new Error(`Invalid font format. Expected TTF/OTF/WOFF/WOFF2, got signature: 0x${sfntVersion.toString(16)}`);
         }
         const tableDirectory = parseTableDirectory(view);
         const isCFF = tableDirectory.has(TABLE_TAG_CFF) || tableDirectory.has(TABLE_TAG_CFF2);
@@ -1655,7 +1655,7 @@ class FontMetadataExtractor {
             FONT_SIGNATURE_OPEN_TYPE_CFF
         ];
         if (!validSignatures.includes(sfntVersion)) {
-            throw new Error(`Invalid font format. Expected TTF/OTF (or WOFF), got signature: 0x${sfntVersion.toString(16)}`);
+            throw new Error(`Invalid font format. Expected TTF/OTF/WOFF/WOFF2, got signature: 0x${sfntVersion.toString(16)}`);
         }
         const tableDirectory = parseTableDirectory(view);
         const nameTableOffset = tableDirectory.get(TABLE_TAG_NAME)?.offset ?? 0;
@@ -1889,6 +1889,10 @@ class FontMetadataExtractor {
     }
 }
 
+let woff2Decoder = null;
+function setWoff2Decoder(decoder) {
+    woff2Decoder = decoder;
+}
 // Uses DecompressionStream to decompress WOFF (WOFF is just zlib compressed TTF/OTF so we can use deflate)
 class WoffConverter {
     static detectFormat(buffer) {
@@ -1990,6 +1994,21 @@ class WoffConverter {
         logger.log('WOFF font decompressed successfully');
         return sfntData.buffer.slice(0, sfntOffset);
     }
+    static async decompressWoff2(woff2Buffer) {
+        const view = new DataView(woff2Buffer);
+        const signature = view.getUint32(0);
+        if (signature !== FONT_SIGNATURE_WOFF2) {
+            throw new Error('Not a valid WOFF2 font');
+        }
+        if (!woff2Decoder) {
+            throw new Error('WOFF2 fonts require enabling the decoder. Add to your code:\n' +
+                "  import { decode } from 'woff2-decode';\n" +
+                '  Text.enableWoff2(decode);');
+        }
+        const decoded = await woff2Decoder(woff2Buffer);
+        logger.log('WOFF2 font decompressed successfully');
+        return decoded.buffer;
+    }
     static async decompressZlib(compressedData) {
         const stream = new ReadableStream({
             start(controller) {
@@ -2020,7 +2039,8 @@ class FontLoader {
             fontBuffer = await WoffConverter.decompressWoff(fontBuffer);
         }
         else if (format === 'woff2') {
-            throw new Error('WOFF2 fonts are not yet supported. Please use WOFF or TTF/OTF format.');
+            logger.log('WOFF2 font detected, decompressing...');
+            fontBuffer = await WoffConverter.decompressWoff2(fontBuffer);
         }
         const view = new DataView(fontBuffer);
         const sfntVersion = view.getUint32(0);
@@ -2029,7 +2049,7 @@ class FontLoader {
             FONT_SIGNATURE_OPEN_TYPE_CFF
         ];
         if (!validSignatures.includes(sfntVersion)) {
-            throw new Error(`Invalid font format. Expected TTF/OTF (or WOFF), got signature: 0x${sfntVersion.toString(16)}`);
+            throw new Error(`Invalid font format. Expected TTF/OTF/WOFF/WOFF2, got signature: 0x${sfntVersion.toString(16)}`);
         }
         const { hb, module } = await this.getHarfBuzzInstance();
         try {
@@ -5579,6 +5599,11 @@ class Text {
     static { this.fontCacheMemoryBytes = 0; }
     static { this.maxFontCacheMemoryBytes = Infinity; }
     static { this.fontIdCounter = 0; }
+    // Enable WOFF2 font support (adds ~45KB to bundle if imported)
+    // Usage: import { decode } from 'woff2-decode'; Text.enableWoff2(decode);
+    static enableWoff2(decoder) {
+        setWoff2Decoder(decoder);
+    }
     // Stringify with sorted keys for cache stability
     static stableStringify(obj) {
         const keys = Object.keys(obj).sort();