three-text 0.2.1 → 0.2.2

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,12 @@ 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)
+  - [p5.js](#p5js)
+  - [React Three Fiber](#react-three-fiber)
+  - [WebGL](#webgl)
+  - [WebGPU](#webgpu)
+  - [Core](#core)
 - [Development and examples](#development-and-examples)
 - [Architecture](#architecture)
 - [Why three-text?](#why-three-text)
@@ -70,7 +70,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`
 
@@ -97,28 +97,29 @@ scene.add(mesh);
 #### p5.js
 
 ```javascript
-import { Text } from 'three-text';
-import { createP5Geometry } from 'three-text/p5';
+import 'three-text/p5';
 
-let textGeom;
+let font;
+let textResult;
+
+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);
 }
 ```
 
@@ -244,7 +245,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,7 +962,7 @@ 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)

package/dist/index.cjs

@@ -1,5 +1,5 @@
 /*!
- * three-text v0.2.1
+ * three-text v0.2.2
  * 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.2
  * 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.2
  * 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.2
  * 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.2
  * 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.2
  * 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/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.2",
   "description": "3D font rendering and text layout engine for the web",
   "main": "dist/index.cjs",
   "module": "dist/index.js",