three-text 0.2.1 → 0.2.3

package/README.md

@@ -17,7 +17,7 @@ A high fidelity 3D font renderer and text layout engine for the web
 
 **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
 
-The library has a framework-agnostic core that returns raw vertex data, with lightweight adapters for Three.js, React Three Fiber, p5.js, WebGL, and WebGPU
+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)
 
 Under the hood, three-text relies on [HarfBuzz](https://github.com/harfbuzz/harfbuzzjs) for text shaping, [Knuth-Plass](http://www.eprg.org/G53DOC/pdfs/knuth-plass-breaking.pdf) line breaking, [Liang](https://tug.org/docs/liang/liang-thesis.pdf) hyphenation, [libtess2](https://github.com/memononen/libtess2) (based on the [OpenGL Utility Library (GLU) tessellator](https://www.songho.ca/opengl/gl_tessellation.html) by Eric Veach) for removing overlaps and triangulation, bezier curve polygonization from Maxim Shemanarev's [Anti-Grain Geometry](https://web.archive.org/web/20060128212843/http://www.antigrain.com/research/adaptive_bezier/index.html), and [Visvalingam-Whyatt](https://hull-repository.worktribe.com/preview/376364/000870493786962263.pdf) [line simplification](https://bost.ocks.org/mike/simplify/).
 
@@ -25,12 +25,9 @@ Under the hood, three-text relies on [HarfBuzz](https://github.com/harfbuzz/harf
 
 - [Overview](#overview)
 - [Getting started](#getting-started)
-  - [Three.js](#threejs-usage)
-  - [React Three Fiber](#react-three-fiber-usage)
-  - [WebGL](#webgl-usage)
-  - [WebGPU](#webgpu-usage)
-  - [p5.js](#p5js-usage)
-  - [Core (framework-agnostic)](#core-usage)
+  - [Three.js](#threejs)
+  - [React Three Fiber](#react-three-fiber)
+  - [p5.js](#p5js)
 - [Development and examples](#development-and-examples)
 - [Architecture](#architecture)
 - [Why three-text?](#why-three-text)
@@ -70,7 +67,7 @@ three-text has a framework-agnostic core that processes fonts and generates geom
 - **`three-text/three/react`** - React Three Fiber component
 - **`three-text/webgl`** - WebGL buffer utility
 - **`three-text/webgpu`** - WebGPU buffer utility
-- **`three-text/p5`** - p5.js geometry converter
+- **`three-text/p5`** - p5.js adapter
 
 Choose the import that matches your stack. Most users will use `three-text/three` or `three-text/p5`
 
@@ -94,34 +91,58 @@ const mesh = new THREE.Mesh(result.geometry, material);
 scene.add(mesh);
 ```
 
+#### React Three Fiber
+
+```jsx
+import { Canvas } from '@react-three/fiber';
+import { Text } from 'three-text/three/react';
+
+Text.setHarfBuzzPath('/hb/hb.wasm');
+
+function App() {
+  return (
+    <Canvas>
+      <ambientLight />
+      <Text font="/fonts/Font.woff" size={72} depth={10}>
+        Hello React
+      </Text>
+    </Canvas>
+  );
+}
+```
+
 #### p5.js
 
 ```javascript
-import { Text } from 'three-text';
-import { createP5Geometry } from 'three-text/p5';
+import 'three-text/p5';
+
+let font;
+let textResult;
 
-let textGeom;
+function preload() {
+  loadThreeTextShaper('/hb/hb.wasm');
+  font = loadThreeTextFont('/fonts/Font.woff');
+}
 
 async function setup() {
   createCanvas(400, 400, WEBGL);
-  Text.setHarfBuzzPath('/hb/hb.wasm');
-  
-  const data = await Text.create({
-    text: 'Hello p5!',
-    font: '/fonts/Font.woff',
-    size: 72
+  textResult = await createThreeTextGeometry('Hello p5!', {
+    font: font,
+    size: 72,
+    depth: 30
   });
-  
-  textGeom = createP5Geometry(window, data);
 }
 
 function draw() {
   background(200);
   lights();
-  model(textGeom);
+  if (textResult) model(textResult.geometry);
 }
 ```
 
+`createThreeTextGeometry()` accepts all the same options as Three.js (`layout`, `fontVariations`, `depth`, etc.) and returns `{ geometry, planeBounds, glyphs }`. Use `planeBounds` to center the text
+
+
 ### Setup
 
 The library bundles harfbuzzjs but requires the WASM binary to be available at runtime. You have two options for providing it:
@@ -244,7 +265,7 @@ three-text/
 │   │   └── ThreeText.tsx       # React Three Fiber component
 │   ├── webgl/                  # WebGL buffer utility
 │   ├── webgpu/                 # WebGPU buffer utility
-│   ├── p5/                     # p5.js geometry converter
+│   ├── p5/                     # p5.js adapter
 │   ├── hyphenation/            # Language-specific hyphenation patterns
 │   └── utils/                  # Performance logging, data structures
 ├── examples/                   # Demos for all adapters
@@ -961,14 +982,14 @@ The build generates multiple module formats for core and all adapters:
 - `dist/three/react.js` - React component
 - `dist/webgl/` - WebGL utility
 - `dist/webgpu/` - WebGPU utility
-- `dist/p5/` - p5.js converter
+- `dist/p5/` - p5.js adapter
 
 **Patterns:**
 - `dist/patterns/` - Hyphenation patterns (ESM and UMD)
 
 ## Acknowledgements
 
-`three-text` is built on HarfBuzz and TeX, and this library would not exist without the authors and communities who contribute to, support, and steward these projects. Thanks to Theo Honohan and Yasi Perera for advice on graphics
+`three-text` is built on HarfBuzz and TeX, and started as a Three.js project; this library would not exist without the authors and communities who contribute to, support, and steward these projects. Thanks to Theo Honohan and Yasi Perera for the advice on graphics
 
 ## License
 

package/dist/index.cjs

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.2.1
+ * three-text v0.2.3
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify

package/dist/index.js

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.2.1
+ * three-text v0.2.3
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify

package/dist/index.min.cjs

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.2.1
+ * three-text v0.2.3
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify

package/dist/index.min.js

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.2.1
+ * three-text v0.2.3
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify

package/dist/index.umd.js

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.2.1
+ * three-text v0.2.3
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify

package/dist/index.umd.min.js

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.2.1
+ * three-text v0.2.3
  * Copyright (C) 2025 Countertype LLC
  * 
  * This program is free software: you can redistribute it and/or modify

package/dist/p5/index.cjs

@@ -1,21 +1,30 @@
 'use strict';
 
-// p5.js adapter - converts core geometry to p5.Geometry
-function createP5Geometry(p5Instance, textGeometry) {
-    // In global mode, p5.Geometry exists but createVector is global
-    // In instance mode, both are on the instance
-    const P5Geometry = p5Instance.Geometry || window.p5?.Geometry;
-    const createVec = p5Instance.createVector || window.createVector;
-    if (!P5Geometry || !createVec) {
-        throw new Error('p5.js not found. Make sure p5.js is loaded before calling this function.');
-    }
-    const geom = new P5Geometry();
+var Text = require('../index.cjs');
+
+// p5.js adapter
+function convertToP5Geometry(p5Instance, textGeometry) {
     const { vertices, normals, indices } = textGeometry;
-    // Convert vertices (flip Y for p5.js coordinate system)
+    const P5GeometryClass = p5Instance.constructor?.Geometry ||
+        (typeof window !== 'undefined' && window.p5?.Geometry);
+    if (!P5GeometryClass) {
+        throw new Error('p5.Geometry not found. Ensure p5.js is loaded.');
+    }
+    const geom = new P5GeometryClass();
+    const createVec = (x, y, z) => {
+        if (typeof p5Instance.createVector === 'function') {
+            return p5Instance.createVector(x, y, z);
+        }
+        const globalCreateVector = (typeof window !== 'undefined' && window.createVector);
+        if (globalCreateVector) {
+            return globalCreateVector(x, y, z);
+        }
+        throw new Error('createVector not found');
+    };
+    // p5 uses +Y up, we use +Y down
     for (let i = 0; i < vertices.length; i += 3) {
         geom.vertices.push(createVec(vertices[i], -vertices[i + 1], vertices[i + 2]));
     }
-    // Convert normals (flip Y)
     for (let i = 0; i < normals.length; i += 3) {
         geom.vertexNormals.push(createVec(normals[i], -normals[i + 1], normals[i + 2]));
     }
@@ -29,5 +38,75 @@ function createP5Geometry(p5Instance, textGeometry) {
     }
     return geom;
 }
+let shaperInitialized = false;
+if (typeof window !== 'undefined' && window.p5) {
+    const p5 = window.p5;
+    p5.prototype.loadThreeTextShaper = function (wasmPath) {
+        if (shaperInitialized) {
+            return;
+        }
+        Text.Text.setHarfBuzzPath(wasmPath);
+        shaperInitialized = true;
+        Text.Text.init()
+            .then(() => {
+            this._decrementPreload();
+        })
+            .catch((err) => {
+            console.error('Failed to load text shaper:', err);
+            this._decrementPreload();
+        });
+    };
+    p5.prototype.loadThreeTextFont = function (fontPath, fontVariations) {
+        const fontRef = {
+            buffer: null,
+            path: fontPath,
+            variations: fontVariations
+        };
+        fetch(fontPath)
+            .then(res => {
+            if (!res.ok) {
+                throw new Error(`Failed to load font: HTTP ${res.status}`);
+            }
+            return res.arrayBuffer();
+        })
+            .then(buffer => {
+            fontRef.buffer = buffer;
+            this._decrementPreload();
+        })
+            .catch((err) => {
+            console.error(`Failed to load font ${fontPath}:`, err);
+            this._decrementPreload();
+        });
+        return fontRef;
+    };
+    p5.prototype.createThreeTextGeometry = async function (text, options) {
+        if (!options.font || !options.font.buffer) {
+            console.error('Font not loaded. Use loadThreeTextFont() in preload().');
+            return null;
+        }
+        const { font, ...coreOptions } = options;
+        try {
+            const result = await Text.Text.create({
+                text,
+                font: font.buffer,
+                fontVariations: font.variations,
+                ...coreOptions
+            });
+            const p5Instance = this;
+            const geometry = convertToP5Geometry(p5Instance, result);
+            return {
+                geometry,
+                planeBounds: result.planeBounds,
+                glyphs: result.glyphs
+            };
+        }
+        catch (err) {
+            console.error('Failed to create text geometry:', err);
+            return null;
+        }
+    };
+    p5.prototype.registerPreloadMethod('loadThreeTextShaper', p5.prototype);
+    p5.prototype.registerPreloadMethod('loadThreeTextFont', p5.prototype);
+}
 
-exports.createP5Geometry = createP5Geometry;
+exports.createP5Geometry = convertToP5Geometry;

package/dist/p5/index.d.ts

@@ -13,7 +13,13 @@ interface P5Geometry {
 interface P5Instance {
     Geometry: new () => P5Geometry;
     createVector(x: number, y: number, z: number): P5Vector;
+    _decrementPreload(): void;
 }
-declare function createP5Geometry(p5Instance: P5Instance | any, textGeometry: TextGeometryInfo): P5Geometry;
+declare global {
+    interface Window {
+        p5?: any;
+    }
+}
+declare function convertToP5Geometry(p5Instance: P5Instance, textGeometry: TextGeometryInfo): P5Geometry;
 
-export { createP5Geometry };
+export { convertToP5Geometry as createP5Geometry };

package/dist/p5/index.js

@@ -1,19 +1,28 @@
-// p5.js adapter - converts core geometry to p5.Geometry
-function createP5Geometry(p5Instance, textGeometry) {
-    // In global mode, p5.Geometry exists but createVector is global
-    // In instance mode, both are on the instance
-    const P5Geometry = p5Instance.Geometry || window.p5?.Geometry;
-    const createVec = p5Instance.createVector || window.createVector;
-    if (!P5Geometry || !createVec) {
-        throw new Error('p5.js not found. Make sure p5.js is loaded before calling this function.');
-    }
-    const geom = new P5Geometry();
+import { Text } from '../index.js';
+
+// p5.js adapter
+function convertToP5Geometry(p5Instance, textGeometry) {
     const { vertices, normals, indices } = textGeometry;
-    // Convert vertices (flip Y for p5.js coordinate system)
+    const P5GeometryClass = p5Instance.constructor?.Geometry ||
+        (typeof window !== 'undefined' && window.p5?.Geometry);
+    if (!P5GeometryClass) {
+        throw new Error('p5.Geometry not found. Ensure p5.js is loaded.');
+    }
+    const geom = new P5GeometryClass();
+    const createVec = (x, y, z) => {
+        if (typeof p5Instance.createVector === 'function') {
+            return p5Instance.createVector(x, y, z);
+        }
+        const globalCreateVector = (typeof window !== 'undefined' && window.createVector);
+        if (globalCreateVector) {
+            return globalCreateVector(x, y, z);
+        }
+        throw new Error('createVector not found');
+    };
+    // p5 uses +Y up, we use +Y down
     for (let i = 0; i < vertices.length; i += 3) {
         geom.vertices.push(createVec(vertices[i], -vertices[i + 1], vertices[i + 2]));
     }
-    // Convert normals (flip Y)
     for (let i = 0; i < normals.length; i += 3) {
         geom.vertexNormals.push(createVec(normals[i], -normals[i + 1], normals[i + 2]));
     }
@@ -27,5 +36,75 @@ function createP5Geometry(p5Instance, textGeometry) {
     }
     return geom;
 }
+let shaperInitialized = false;
+if (typeof window !== 'undefined' && window.p5) {
+    const p5 = window.p5;
+    p5.prototype.loadThreeTextShaper = function (wasmPath) {
+        if (shaperInitialized) {
+            return;
+        }
+        Text.setHarfBuzzPath(wasmPath);
+        shaperInitialized = true;
+        Text.init()
+            .then(() => {
+            this._decrementPreload();
+        })
+            .catch((err) => {
+            console.error('Failed to load text shaper:', err);
+            this._decrementPreload();
+        });
+    };
+    p5.prototype.loadThreeTextFont = function (fontPath, fontVariations) {
+        const fontRef = {
+            buffer: null,
+            path: fontPath,
+            variations: fontVariations
+        };
+        fetch(fontPath)
+            .then(res => {
+            if (!res.ok) {
+                throw new Error(`Failed to load font: HTTP ${res.status}`);
+            }
+            return res.arrayBuffer();
+        })
+            .then(buffer => {
+            fontRef.buffer = buffer;
+            this._decrementPreload();
+        })
+            .catch((err) => {
+            console.error(`Failed to load font ${fontPath}:`, err);
+            this._decrementPreload();
+        });
+        return fontRef;
+    };
+    p5.prototype.createThreeTextGeometry = async function (text, options) {
+        if (!options.font || !options.font.buffer) {
+            console.error('Font not loaded. Use loadThreeTextFont() in preload().');
+            return null;
+        }
+        const { font, ...coreOptions } = options;
+        try {
+            const result = await Text.create({
+                text,
+                font: font.buffer,
+                fontVariations: font.variations,
+                ...coreOptions
+            });
+            const p5Instance = this;
+            const geometry = convertToP5Geometry(p5Instance, result);
+            return {
+                geometry,
+                planeBounds: result.planeBounds,
+                glyphs: result.glyphs
+            };
+        }
+        catch (err) {
+            console.error('Failed to create text geometry:', err);
+            return null;
+        }
+    };
+    p5.prototype.registerPreloadMethod('loadThreeTextShaper', p5.prototype);
+    p5.prototype.registerPreloadMethod('loadThreeTextFont', p5.prototype);
+}
 
-export { createP5Geometry };
+export { convertToP5Geometry as createP5Geometry };

package/dist/three/index.cjs

@@ -19,8 +19,8 @@ class Text {
         const geometry = new three.BufferGeometry();
         geometry.setAttribute('position', new three.Float32BufferAttribute(coreResult.vertices, 3));
         geometry.setAttribute('normal', new three.Float32BufferAttribute(coreResult.normals, 3));
-        geometry.setIndex(Array.from(coreResult.indices));
-        // Add optional attributes
+        geometry.setIndex(new three.Uint32BufferAttribute(coreResult.indices, 1));
+        // Add optional color attribute (only if provided)
         if (coreResult.colors) {
             geometry.setAttribute('color', new three.Float32BufferAttribute(coreResult.colors, 3));
         }

package/dist/three/index.js

@@ -1,4 +1,4 @@
-import { BufferGeometry, Float32BufferAttribute } from 'three';
+import { BufferGeometry, Float32BufferAttribute, Uint32BufferAttribute } from 'three';
 import { Text as Text$1 } from '../index.js';
 
 // Three.js adapter - wraps core text processing and returns BufferGeometry
@@ -17,8 +17,8 @@ class Text {
         const geometry = new BufferGeometry();
         geometry.setAttribute('position', new Float32BufferAttribute(coreResult.vertices, 3));
         geometry.setAttribute('normal', new Float32BufferAttribute(coreResult.normals, 3));
-        geometry.setIndex(Array.from(coreResult.indices));
-        // Add optional attributes
+        geometry.setIndex(new Uint32BufferAttribute(coreResult.indices, 1));
+        // Add optional color attribute (only if provided)
         if (coreResult.colors) {
             geometry.setAttribute('color', new Float32BufferAttribute(coreResult.colors, 3));
         }

package/dist/three/react.cjs

@@ -72,13 +72,6 @@ const Text$1 = react.forwardRef(function Text(props, ref) {
                     font,
                     ...memoizedTextOptions,
                 });
-                if (text.geometry &&
-                    !text.geometry.attributes.color &&
-                    vertexColors) {
-                    const vertexCount = text.geometry.attributes.position.count;
-                    const colors = new Float32Array(vertexCount * 3).fill(1.0);
-                    text.geometry.setAttribute("color", new THREE__namespace.BufferAttribute(colors, 3));
-                }
                 if (!cancelled) {
                     setGeometry(text.geometry);
                     if (onLoad)

package/dist/three/react.js

@@ -51,13 +51,6 @@ const Text$1 = forwardRef(function Text(props, ref) {
                     font,
                     ...memoizedTextOptions,
                 });
-                if (text.geometry &&
-                    !text.geometry.attributes.color &&
-                    vertexColors) {
-                    const vertexCount = text.geometry.attributes.position.count;
-                    const colors = new Float32Array(vertexCount * 3).fill(1.0);
-                    text.geometry.setAttribute("color", new THREE.BufferAttribute(colors, 3));
-                }
                 if (!cancelled) {
                     setGeometry(text.geometry);
                     if (onLoad)

package/dist/types/p5/index.d.ts

@@ -12,6 +12,12 @@ interface P5Geometry {
 interface P5Instance {
     Geometry: new () => P5Geometry;
     createVector(x: number, y: number, z: number): P5Vector;
+    _decrementPreload(): void;
 }
-export declare function createP5Geometry(p5Instance: P5Instance | any, textGeometry: TextGeometryInfo): P5Geometry;
-export {};
+declare global {
+    interface Window {
+        p5?: any;
+    }
+}
+declare function convertToP5Geometry(p5Instance: P5Instance, textGeometry: TextGeometryInfo): P5Geometry;
+export { convertToP5Geometry as createP5Geometry };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-text",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "3D font rendering and text layout engine for the web",
   "main": "dist/index.cjs",
   "module": "dist/index.js",