three-slug 1.0.0

package/GOAL.md

@@ -0,0 +1,32 @@
+Background:
+The Slug font rendering algorithm/tooling has recently been open sourced.
+There are C/C++ implementations available, but I want to create a first class Three.js library for it.
+I have 2 repos.. One is the open sourced repo, containing the HSLS code for rendering: Slug-main
+
+And a supporting repo by another person, which is a C++ implementation of the algorithm: Sluggish-master
+
+Role: You are an expert Computer Graphics Engineer specializing in Three.js, GLSL, and Font Geometry. Your goal is to help me port the "Sluggish" project (a toy implementation of the Slug Font Rendering algorithm) into a first-class Three.js library.
+
+Project Context:
+
+Core Algorithm: We are implementing the Slug algorithm (vector-based GPU text rendering).
+
+Legal Status: As of March 2026, the Slug patent is in the public domain. We are authorized to implement this without workarounds.
+
+Target Framework: Three.js (using BufferGeometry and ShaderMaterial).
+
+Technical Constraints:
+
+Data Layout: Translate C-style structs from the Sluggish generator into JavaScript InterleavedBuffer or Float32Array.
+
+Shaders: Port raw GLSL into Three.js-friendly code. We prioritize the Banded-Bézier approach to minimize per-pixel curve tests.
+
+Precision: We must handle "Floating Point Jitter" for large-scale coordinates (e.g., world-space text in a racing sim). (This may be less of an issue in JS, but we should be mindful of it.)
+
+Your Workflow:
+
+When I provide C code, explain the memory layout before writing the JS port.
+
+When writing shaders, ensure they are compatible with Three.js onBeforeCompile (and optionally the new Node Material (WebGPU) system, unless this is too much work.)
+
+Prioritize performance and usability.

package/README.md

@@ -0,0 +1,78 @@
+
+
+# three-slug: Native Three.js GPU Text Rendering
+
+`three-slug` is a Javascript and WebGL port of Eric Lengyel's **Slug** font rendering algorithm, implemented natively for **Three.js**.
+
+Unlike traditional MSDF (Multi-Channel Signed Distance Field) font rendering which can suffer from corner rounding and texture resolution limits, the Slug algorithm evaluates the quadratic bezier curves of the TrueType font directly within the fragment shader. This enables resolution-independent font rendering, sharp corners, and precise anti-aliasing.
+
+## Screenshots
+
+![three-slug Rendering Demo](screenshot.png)
+
+
+## Features
+
+- **Client-side Generation**: Parses `.ttf` and `.otf` data dynamically using `opentype.js` to compute curve layouts and spatial binning locally.
+- **Binary Format**: Serializes curves and bin maps to `.sluggish` file payloads for cache delivery.
+- **Instanced Rendering**: Passes coordinate frames and glyph indexing variables to WebGL vertex attributes backends.
+- **Typography Alignment**: Iterates layout structures utilizing metric scalars mapping direct width increments.
+
+### Phase 2: Native PBR & Shadow Integration
+- **Modular Shader Chunks**: The core Slug mathematical raytracer has been decoupled into distinct Three.js `#include` chunks (`slug_fragment_core`, `slug_fragment_standard`, `slug_pars_vertex`).
+- **Standard Material Hooks**: Utilizes `onBeforeCompile` to non-destructively splice the font rendering algorithm directly into native Three.js materials (e.g. `MeshStandardMaterial`, `MeshDepthMaterial`).
+- **Physical Lighting**: Evaluates vector glyphs securely under physically based rendering paradigms, seamlessly scattering Light arrays and mapping PBR Specular boundaries.
+- **Dynamic Occlusions**: Typography casts and receives accurate, anti-aliased shadows inside the active scene viewport using standard Depth buffer constraints and custom `MeshDistanceMaterial` definitions.
+
+## Quick Start Example
+
+```javascript
+import * as THREE from 'three';
+import { SlugLoader, SlugGeometry, injectSlug } from 'three-slug';
+
+// 1. Load the pre-compiled .sluggish binary font data
+new SlugLoader().load('path/to/font.sluggish', (slugData) => {
+    
+    // 2. Initialize the scalable vector geometry
+    const geometry = new SlugGeometry(1000); // Specify max glyph capacity
+    
+    // 3. Create a native Three.js Standard Material
+    const material = new THREE.MeshStandardMaterial({
+        color: 0xffcc00,
+        roughness: 1.0,
+        metalness: 0.0,
+        side: THREE.DoubleSide
+    });
+    
+    // 4. Spawn the finalized PBR Mesh
+    const slugMesh = new THREE.Mesh(geometry, material);
+
+    // 5. Inject the mathematical Slug raytracer and auto-bind Shadow caches seamlessly
+    injectSlug(slugMesh, material, slugData);
+    
+    // 6. Append your text
+    geometry.addText('MyString! WOOHOO!', slugData, {
+        fontScale: 0.5,
+        justify: 'center'
+    });
+
+    slugMesh.castShadow = true;
+    slugMesh.receiveShadow = true;
+    scene.add(slugMesh);
+});
+```
+
+## Usage
+
+1. Serve the repository locally (e.g., `npx http-server`).
+2. Open `demo/index.html`.
+3. Use the UI to load a standard `.ttf` file. The Javascript generator will parse the curves, initialize the GPU textures, and dynamically render standard PBR typography inside the demo viewer.
+4. Toggle the **RawShader Fallback** to swap between Native Standard Lighting graphs or unlit baseline GLSL debugging buffers.
+5. (Optional) Click **Download .sluggish** to cache the generated font data to a serialized binary array.
+
+## Credits & Acknowledgements
+
+*   **Eric Lengyel** for the [Slug Algorithm](http://sluglibrary.com/).
+*   **The Sluggish C++ Port** for providing the architectural reference for mapping Slug textures directly to generic WebGL buffer pipelines.
+*   **[opentype.js](https://github.com/opentypejs/opentype.js)** for providing the native Javascript TrueType parsing core.
+*   Ported to Javascript and Three.js by **[manthrax](https://github.com/manthrax)**.

package/demo/fonts/DejaVu Fonts License.txt

@@ -0,0 +1,97 @@
+Fonts are (c) Bitstream (see below). DejaVu changes are in public domain.
+Glyphs imported from Arev fonts are (c) Tavmjong Bah (see below)
+
+Bitstream Vera Fonts Copyright
+------------------------------
+
+Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. Bitstream Vera is
+a trademark of Bitstream, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of the fonts accompanying this license ("Fonts") and associated
+documentation files (the "Font Software"), to reproduce and distribute the
+Font Software, including without limitation the rights to use, copy, merge,
+publish, distribute, and/or sell copies of the Font Software, and to permit
+persons to whom the Font Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright and trademark notices and this permission notice shall
+be included in all copies of one or more of the Font Software typefaces.
+
+The Font Software may be modified, altered, or added to, and in particular
+the designs of glyphs or characters in the Fonts may be modified and
+additional glyphs or characters may be added to the Fonts, only if the fonts
+are renamed to names not containing either the words "Bitstream" or the word
+"Vera".
+
+This License becomes null and void to the extent applicable to Fonts or Font
+Software that has been modified and is distributed under the "Bitstream
+Vera" names.
+
+The Font Software may be sold as part of a larger software package but no
+copy of one or more of the Font Software typefaces may be sold by itself.
+
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME
+FOUNDATION BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING
+ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE
+FONT SOFTWARE.
+
+Except as contained in this notice, the names of Gnome, the Gnome
+Foundation, and Bitstream Inc., shall not be used in advertising or
+otherwise to promote the sale, use or other dealings in this Font Software
+without prior written authorization from the Gnome Foundation or Bitstream
+Inc., respectively. For further information, contact: fonts at gnome dot
+org. 
+
+Arev Fonts Copyright
+------------------------------
+
+Copyright (c) 2006 by Tavmjong Bah. All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the fonts accompanying this license ("Fonts") and
+associated documentation files (the "Font Software"), to reproduce
+and distribute the modifications to the Bitstream Vera Font Software,
+including without limitation the rights to use, copy, merge, publish,
+distribute, and/or sell copies of the Font Software, and to permit
+persons to whom the Font Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright and trademark notices and this permission notice
+shall be included in all copies of one or more of the Font Software
+typefaces.
+
+The Font Software may be modified, altered, or added to, and in
+particular the designs of glyphs or characters in the Fonts may be
+modified and additional glyphs or characters may be added to the
+Fonts, only if the fonts are renamed to names not containing either
+the words "Tavmjong Bah" or the word "Arev".
+
+This License becomes null and void to the extent applicable to Fonts
+or Font Software that has been modified and is distributed under the 
+"Tavmjong Bah Arev" names.
+
+The Font Software may be sold as part of a larger software package but
+no copy of one or more of the Font Software typefaces may be sold by
+itself.
+
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL
+TAVMJONG BAH BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+
+Except as contained in this notice, the name of Tavmjong Bah shall not
+be used in advertising or otherwise to promote the sale, use or other
+dealings in this Font Software without prior written authorization
+from Tavmjong Bah. For further information, contact: tavmjong @ free
+. fr.

package/demo/fonts/fonts.json

@@ -0,0 +1,12 @@
+[
+  "DejaVuSansMono.ttf",
+  "DejaVuSansMono-Bold.ttf",
+  "DejaVuSansMono-Oblique.ttf",
+  "DejaVuSansMono-BoldOblique.ttf",
+  "Roboto-VariableFont_wdth,wght.ttf",
+  "Roboto-Italic-VariableFont_wdth,wght.ttf",
+  "SpaceMono-Regular.ttf",
+  "SpaceMono-Bold.ttf",
+  "SpaceMono-Italic.ttf",
+  "SpaceMono-BoldItalic.ttf"
+]

package/demo/index.html

@@ -0,0 +1,103 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Slug Font Rendering Three.js</title>
+    <style>
+        body {
+            margin: 0;
+            overflow: hidden;
+            background-color: #004040;
+            color: white;
+            font-family: sans-serif;
+        }
+
+        #ui {
+            position: absolute;
+            top: 20px;
+            left: 20px;
+            z-index: 10;
+            background: rgba(10, 15, 20, 0.6);
+            backdrop-filter: blur(8px);
+            -webkit-backdrop-filter: blur(8px);
+            padding: 15px;
+            border-radius: 8px;
+            border: 1px solid rgba(255, 255, 255, 0.1);
+            box-shadow: 0 4px 16px rgba(0, 0, 0, 0.5);
+            max-width: 320px;
+        }
+
+        h3 {
+            margin-top: 0;
+            font-size: 1.2rem;
+            letter-spacing: 1px;
+            color: #ffcc00;
+        }
+
+        button,
+        input {
+            margin-bottom: 5px;
+            cursor: pointer;
+        }
+    </style>
+</head>
+
+<body>
+    <div id="ui">
+        <h3>Three-Slug</h3>
+        <div>
+            <label>Select Font:</label><br>
+            <select id="fontSelect"
+                style="width: 100%; margin-bottom: 10px; padding: 5px; background: #333; color: #fff; border: 1px solid #555;">
+                <!-- Dynamically populated from fonts.json -->
+            </select>
+        </div>
+        <hr style="border-color: #444; margin: 15px 0;">
+        <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 10px;">
+            <label><input type="checkbox" id="autoScroll" checked /> Auto Scroll</label>
+            <label><input type="checkbox" id="matrixGlitch" /> Matrix Glitch</label>
+            <label><input type="checkbox" id="useRawShader" /> RawShader Fallback</label>
+        </div>
+        <div style="margin-bottom: 15px;">
+            <label style="font-size: 0.9em; color:#ccc; display: block; margin-bottom: 5px;">Text Alignment:</label>
+            <select id="textJustify"
+                style="width: 100%; padding: 5px; background: #333; color: #fff; border: 1px solid #555;">
+                <option value="left" selected>Left</option>
+                <option value="center">Center</option>
+                <option value="right">Right</option>
+            </select>
+        </div>
+        <div>
+            <label>Load .ttf font:</label><br>
+            <input type="file" id="fileTtf" accept=".ttf"><br>
+            <button id="btnDownload">Download .sluggish</button>
+        </div>
+        <hr style="border-color: #444; margin: 15px 0;">
+        <div style="margin-bottom: 15px;">
+            <label style="font-size: 0.9em; color:#ccc;">Load .sluggish file:</label><br>
+            <input type="file" id="fileSluggish" accept=".sluggish" style="font-size: 0.8em;">
+        </div>
+        <hr>
+        <div>
+            <label>Text to Render:</label><br>
+            <textarea id="textInput" rows="4"
+                style="width: 100%; box-sizing: border-box; background: #222; color: #fff; border: 1px solid #444; padding: 5px;">The quick brown fox jumps over the lazy dog.
+SLUG!</textarea>
+        </div>
+    </div>
+
+    <script type="importmap">
+        {
+            "imports": {
+                "three": "https://unpkg.com/three@0.183.2/build/three.module.js",
+                "three/addons/": "https://unpkg.com/three@0.183.2/examples/jsm/",
+                "opentype.js": "https://unpkg.com/opentype.js@1.3.4/dist/opentype.module.js"
+            }
+        }
+    </script>
+    <script type="module" src="./main.js"></script>
+</body>
+
+</html>