three-text 0.4.4 → 0.4.6

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)
 
@@ -78,13 +78,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 +117,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() {
@@ -195,6 +198,12 @@ self.onmessage = (e) => {
 
 The library will prioritize the buffer if both a path and a buffer have been set
 
+#### Platform-specific notes
+
+**NW.js with CommonJS:** If using `require()` to load the CJS build in NW.js, use Option 2 (buffer-based loading). NW.js's [dual-context architecture](https://docs.nwjs.io/For%20Users/Advanced/JavaScript%20Contexts%20in%20NW.js/#separate-context-mode) causes path resolution issues in this specific scenario. ESM imports and bundled code work normally
+
+**Electron with `file://` protocol:** If loading HTML directly from the filesystem (not via a dev server), use Option 2 (buffer-based loading) or enable `nodeIntegration` in your BrowserWindow
+
 ### Hyphenation patterns
 
 **For ES Modules (recommended):** Import and register only the languages you need:
@@ -724,7 +733,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)
@@ -907,7 +916,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.4
+ * three-text v0.4.6
  * 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 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 = 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 = 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 {
@@ -2212,7 +2232,6 @@ async function loadPattern(language, patternsPath) {
     }
 }
 
-// Bector and bounding box types for core
 // 2D Vector
 class Vec2 {
     constructor(x = 0, y = 0) {
@@ -4811,6 +4830,41 @@ class TextShaper {
     }
 }
 
+// Fetch with fs fallback for Electron file:// and Node.js environments
+async function loadBinary(filePath) {
+    try {
+        const res = await fetch(filePath);
+        if (!res.ok) {
+            throw new Error(`HTTP ${res.status}`);
+        }
+        return await res.arrayBuffer();
+    }
+    catch (fetchError) {
+        const req = globalThis.require;
+        if (typeof req !== 'function') {
+            throw new Error(`Failed to fetch ${filePath}: ${fetchError}`);
+        }
+        try {
+            const fs = req('fs');
+            const nodePath = req('path');
+            // file:// URLs need path resolution relative to the HTML document
+            let resolvedPath = filePath;
+            if (typeof window !== 'undefined' &&
+                window.location?.protocol === 'file:') {
+                const dir = nodePath.dirname(window.location.pathname);
+                resolvedPath = nodePath.join(dir, filePath);
+            }
+            const buffer = fs.readFileSync(resolvedPath);
+            if (buffer instanceof ArrayBuffer)
+                return buffer;
+            return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+        }
+        catch (fsError) {
+            throw new Error(`Failed to load ${filePath}: fetch failed (${fetchError}), fs.readFileSync failed (${fsError})`);
+        }
+    }
+}
+
 var hb = {exports: {}};
 
 var fs = {};
@@ -5401,11 +5455,9 @@ try {
 var hbjsExports = hbjs$2.exports;
 var hbjs$1 = /*@__PURE__*/getDefaultExportFromCjs(hbjsExports);
 
-// These will be bundled by Rollup
-// @ts-expect-error - no declarations for harfbuzzjs/hb.js
 let harfbuzzPromise = null;
 let wasmPath = null;
-let wasmBuffer = null; // Add buffer option
+let wasmBuffer = null;
 const HarfBuzzLoader = {
     setWasmPath(path) {
         wasmPath = path;
@@ -5428,12 +5480,7 @@ const HarfBuzzLoader = {
                     moduleConfig.wasmBinary = wasmBuffer;
                 }
                 else if (wasmPath) {
-                    moduleConfig.locateFile = (path, scriptDirectory) => {
-                        if (path.endsWith('.wasm')) {
-                            return wasmPath;
-                        }
-                        return scriptDirectory + path;
-                    };
+                    moduleConfig.wasmBinary = await loadBinary(wasmPath);
                 }
                 else {
                     throw new Error('HarfBuzz WASM path or buffer must be set before initialization.');
@@ -5555,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();
@@ -5730,14 +5782,7 @@ class Text {
             Text.hbInitPromise = HarfBuzzLoader.getHarfBuzz();
         }
         await Text.hbInitPromise;
-        const fontBuffer = typeof fontSrc === 'string'
-            ? await fetch(fontSrc).then((res) => {
-                if (!res.ok) {
-                    throw new Error(`Failed to load font from ${fontSrc}: HTTP ${res.status} ${res.statusText}`);
-                }
-                return res.arrayBuffer();
-            })
-            : fontSrc;
+        const fontBuffer = typeof fontSrc === 'string' ? await loadBinary(fontSrc) : fontSrc;
         try {
             if (this.loadedFont) {
                 this.destroy();

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): void;
     private static stableStringify;
     private fontLoader;
     private loadedFont?;

package/dist/index.js

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.4.4
+ * three-text v0.4.6
  * 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 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 = 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 = 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 {
@@ -2209,7 +2229,6 @@ async function loadPattern(language, patternsPath) {
     }
 }
 
-// Bector and bounding box types for core
 // 2D Vector
 class Vec2 {
     constructor(x = 0, y = 0) {
@@ -4808,6 +4827,41 @@ class TextShaper {
     }
 }
 
+// Fetch with fs fallback for Electron file:// and Node.js environments
+async function loadBinary(filePath) {
+    try {
+        const res = await fetch(filePath);
+        if (!res.ok) {
+            throw new Error(`HTTP ${res.status}`);
+        }
+        return await res.arrayBuffer();
+    }
+    catch (fetchError) {
+        const req = globalThis.require;
+        if (typeof req !== 'function') {
+            throw new Error(`Failed to fetch ${filePath}: ${fetchError}`);
+        }
+        try {
+            const fs = req('fs');
+            const nodePath = req('path');
+            // file:// URLs need path resolution relative to the HTML document
+            let resolvedPath = filePath;
+            if (typeof window !== 'undefined' &&
+                window.location?.protocol === 'file:') {
+                const dir = nodePath.dirname(window.location.pathname);
+                resolvedPath = nodePath.join(dir, filePath);
+            }
+            const buffer = fs.readFileSync(resolvedPath);
+            if (buffer instanceof ArrayBuffer)
+                return buffer;
+            return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+        }
+        catch (fsError) {
+            throw new Error(`Failed to load ${filePath}: fetch failed (${fetchError}), fs.readFileSync failed (${fsError})`);
+        }
+    }
+}
+
 var hb = {exports: {}};
 
 var fs = {};
@@ -5398,11 +5452,9 @@ try {
 var hbjsExports = hbjs$2.exports;
 var hbjs$1 = /*@__PURE__*/getDefaultExportFromCjs(hbjsExports);
 
-// These will be bundled by Rollup
-// @ts-expect-error - no declarations for harfbuzzjs/hb.js
 let harfbuzzPromise = null;
 let wasmPath = null;
-let wasmBuffer = null; // Add buffer option
+let wasmBuffer = null;
 const HarfBuzzLoader = {
     setWasmPath(path) {
         wasmPath = path;
@@ -5425,12 +5477,7 @@ const HarfBuzzLoader = {
                     moduleConfig.wasmBinary = wasmBuffer;
                 }
                 else if (wasmPath) {
-                    moduleConfig.locateFile = (path, scriptDirectory) => {
-                        if (path.endsWith('.wasm')) {
-                            return wasmPath;
-                        }
-                        return scriptDirectory + path;
-                    };
+                    moduleConfig.wasmBinary = await loadBinary(wasmPath);
                 }
                 else {
                     throw new Error('HarfBuzz WASM path or buffer must be set before initialization.');
@@ -5552,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();
@@ -5727,14 +5779,7 @@ class Text {
             Text.hbInitPromise = HarfBuzzLoader.getHarfBuzz();
         }
         await Text.hbInitPromise;
-        const fontBuffer = typeof fontSrc === 'string'
-            ? await fetch(fontSrc).then((res) => {
-                if (!res.ok) {
-                    throw new Error(`Failed to load font from ${fontSrc}: HTTP ${res.status} ${res.statusText}`);
-                }
-                return res.arrayBuffer();
-            })
-            : fontSrc;
+        const fontBuffer = typeof fontSrc === 'string' ? await loadBinary(fontSrc) : fontSrc;
         try {
             if (this.loadedFont) {
                 this.destroy();