textmode.synth.js 1.0.0-beta.1 → 1.0.0-beta.3

package/README.md

@@ -1,15 +1,33 @@
 # textmode.synth.js
 
-A `hydra`-inspired chainable visual synthesis system for `textmode.js`. Create procedural ASCII/text animations with simple, expressive code.
+**A derivative work of [hydra-synth](https://github.com/hydra-synth/hydra-synth) by [Olivia Jack](https://github.com/ojack), adapted for the [textmode.js](https://github.com/humanbydefinition/textmode.js) ecosystem.**
+
+Create procedural ASCII/text animations with a `hydra`-inspired, chainable visual synthesis system.
+
+> [!NOTE]
+> This project is work-in-progress and not yet ready for production use.
+>
+> `textmode.synth.js` becomes usable once `textmode.js` v0.9.0 is released.
 
 ## Features
 
-- 🎨 **Procedural Generation**: Generate characters, colors, and patterns using oscillators, noise, voronoi, and more
-- 🔗 **Method Chaining**: Hydra-style fluent API for building complex visual effects
-- 🎯 **Three-Texture System**: Independent control over characters, character colors, and cell backgrounds
-- ⚡ **WebGL Powered**: Compiled to optimized GLSL shaders for real-time performance
-- 🔄 **Feedback Loops**: Create trails, motion blur, and recursive patterns
-- 📦 **Compositional API**: Start with any aspect (char, color, background) and build from there
+- 🎨 **Procedural generation** - Oscillators, noise, voronoi, and more
+- 🔗 **Method chaining** - Hydra-style fluent API for complex visuals
+- 🎯 **Three-texture system** - Independent control over characters, foreground, and background
+- ⚡ **WebGL powered** - Compiled to optimized GLSL shaders
+- 🔄 **Feedback loops** - Trails, motion blur, and recursive patterns
+- 📦 **Compositional API** - Start from any aspect and build organically
+- 📚 **Extensible** - Add your own sources, transforms, and more
+
+## Try it online first
+
+> [!NOTE]
+> The live coding environment is not yet live. It will be available in the next few days.
+
+To go along with the release of this library, we've created a **live coding environment** where you can explore everything in the browser: [synth.textmode.art](https://synth.textmode.art)
+
+It features IntelliSense & auto-completion, documentation on hover, curated examples to explore, and a lot more. The whole `textmode.js` ecosystem is available at your fingertips.
+
 
 ## Installation
 
@@ -17,164 +35,129 @@ A `hydra`-inspired chainable visual synthesis system for `textmode.js`. Create p
 npm install textmode.synth.js
 ```
 
-## Quick Start
+## Quick start
 
 ```javascript
 import { textmode } from 'textmode.js';
-import { SynthPlugin, char, osc, noise, solid } from 'textmode.synth.js';
+import { SynthPlugin, char, osc } from 'textmode.synth.js';
 
 const t = textmode.create({
-  width: 800,
-  height: 600,
-  fontSize: 12,
+  width: window.innerWidth,
+  height: window.innerHeight,
+  fontSize: 16,
   plugins: [SynthPlugin]
 });
 
-// Create a simple animated pattern
-const pattern = osc(10, 0.1, 1.5);
+const charChain = osc(1, -0.1, 0.5).kaleid(50);
+const colorChain = osc(25, -0.1, 0.5).kaleid(50);
+
 t.layers.base.synth(
-  char(pattern)
+  char(charChain)
     .charMap('@#%*+=-:. ')
-    .charColor(pattern.clone())
-    .cellColor(pattern.clone().invert())
+    .charColor(colorChain)
+    .cellColor(colorChain.clone().invert())
 );
+
+t.windowResized(() => {
+  t.resizeCanvas(window.innerWidth, window.innerHeight);
+});
 ```
 
-## Core Concepts
+## Core concepts
 
-### The New Compositional API
+### Compositional API
 
-textmode.synth.js provides three standalone functions for defining different aspects of your visual:
+`textmode.js` renders to three textures: characters, foreground colors, and background colors. `textmode.synth.js` provides functions to drive each independently:
 
-- **`char(source, charCount?)`** - Define which pattern drives character generation
-- **`charColor(source)`** - Define character foreground colors
-- **`cellColor(source)`** - Define cell background colors
+| Function | Purpose |
+|----------|---------|
+| `char(source, charCount?)` | Character generation |
+| `charColor(source)` | Foreground color |
+| `cellColor(source)` | Background color |
+| `paint(source)` | Both foreground & background |
 
-You can start with any of these and chain the others:
+Start from any entry point and chain the others:
 
 ```javascript
-// Start with character generation
-char(noise(10), 16)
-  .charMap('@#%*+=-:. ')
-  .charColor(osc(5))
-  .cellColor(solid(0, 0, 0, 0.5));
-
-// Start with colors
-charColor(voronoi(5).mult(osc(20)))
-  .char(noise(10), 16)
-  .cellColor(gradient(0.5));
-
-// Start with background
-cellColor(solid(0, 0, 0, 0.8))
-  .char(noise(10))
-  .charColor(osc(5).kaleid(4));
-```
+// From characters
+char(noise(10)).charColor(osc(5)).cellColor(solid(0,0,0,0.5));
 
-### Source Generators
+// From colors
+charColor(voronoi(5)).char(noise(10)).cellColor(gradient(0.5));
 
-Create patterns using these generators:
+// Shorthand for pixel art style
+paint(noise(10));
+```
 
-- `osc(frequency, sync, offset)` - Oscillating sine wave patterns
-- `noise(scale, offset)` - Perlin noise
-- `voronoi(scale, speed, blending)` - Cellular/voronoi patterns
-- `gradient(speed)` - Rotating radial gradient
-- `shape(sides, radius, smoothing)` - Geometric shapes
-- `solid(r, g, b, a)` - Solid colors
+### Pixel art mode
 
-### Transforms
+Use `paint()` to color both foreground and background identically, effectively hiding the characters:
 
-Chain transforms to modify patterns:
+```javascript
+t.fontSize(16);
+t.layers.base.synth(paint(noise(10)));
+```
 
-**Geometry:** `rotate()`, `scale()`, `scroll()`, `pixelate()`, `repeat()`, `kaleid()`
-**Color:** `brightness()`, `contrast()`, `invert()`, `hue()`, `saturate()`, `colorama()`
-**Blend:** `add()`, `sub()`, `mult()`, `blend()`, `diff()`, `layer()`, `mask()`
-**Modulate:** `modulate()`, `modulateScale()`, `modulateRotate()`, `modulateScrollX()`, etc.
+> **Tip:** With `t.fontSize(1)`, you can recreate most hydra visuals 1:1.
 
-### Character Mapping
+### Direct source usage
 
-Use `.charMap()` to define which characters to display:
+You can also pass a source directly to `.synth()` without any wrapper function:
 
 ```javascript
-char(noise(10))
-  .charMap('@#%*+=-:. ')      // ASCII gradient
-  .charColor(osc(5));
-
-char(voronoi(5))
-  .charMap('█▓▒░ ')            // Block characters
-  .charColor(gradient(0.5));
+t.layers.base.synth(noise(10));
 ```
 
-## Examples
+This drives both characters *and* foreground colors from the same source *(background defaults to black)*. In practice, using separate sources for characters often looks better - character cycling is more rapid than color changes.
 
-### Same Pattern for Everything
-```javascript
-const pattern = osc([10, 30, 60].fast(2), 0.1);
-layer.synth(
-  char(pattern)
-    .charMap('@#%*+=-:. ')
-    .charColor(pattern.clone())
-    .cellColor(pattern.clone().invert())
-);
-```
+### Source generators
 
-### Different Patterns for Each Aspect
-```javascript
-const charPattern = noise(5);
-const colorPattern = voronoi(10, 0.5).mult(osc(20));
-const bgPattern = gradient(0.2);
-
-layer.synth(
-  char(charPattern, 16)
-    .charMap(' .:-=+*#%@')
-    .charColor(colorPattern)
-    .cellColor(bgPattern.invert())
-);
-```
-
-### Feedback Loop
-```javascript
-// Classic hydra-style feedback
-layer.synth(
-  src()
-    .modulate(noise(3), 0.005)
-    .blend(shape(4), 0.01)
-);
-```
+| Generator | Description |
+|-----------|-------------|
+| `osc(freq, sync, offset)` | Sine wave patterns |
+| `noise(scale, offset)` | Perlin noise |
+| `voronoi(scale, speed, blend)` | Cellular patterns |
+| `gradient(speed)` | Radial gradient |
+| `shape(sides, radius, smooth)` | Geometric polygons |
+| `solid(r, g, b, a)` | Solid colors |
+| `src(layer?)` | Feedback / cross-layer sampling |
+| `...` | ...and many more..? |
 
-### Array Modulation
-```javascript
-// Animate between multiple values
-layer.synth(
-  char(osc([1, 10, 50, 100].fast(2), 0.1), 16)
-    .charMap('@#%*+=-:. ')
-    .charColor(osc([1, 10, 50, 100].fast(2), 0.1))
-);
-```
+### Transforms
 
-## Documentation
+Chain transforms to modify patterns:
 
-- [Full API Documentation](./api/index.md)
-- [Compositional API Guide](./docs/COMPOSITIONAL-API.md)
-- [Examples](./examples/)
+| Category | Methods |
+|----------|---------|
+| **Geometry** | `rotate`, `scale`, `scroll`, `pixelate`, `repeat`, `kaleid`, ... |
+| **Color** | `brightness`, `contrast`, `invert`, `hue`, `saturate`, `colorama`, ... |
+| **Blend** | `add`, `sub`, `mult`, `blend`, `diff`, `layer`, `mask`, ... |
+| **Modulate** | `modulate`, `modulateScale`, `modulateRotate`, `modulateKaleid`, ... |
 
-## Backward Compatibility
+### Character mapping
 
-The old `charOsc()`, `charNoise()`, etc. functions still work:
+Use `.charMap()` to define the character set. By default, all characters available in the layer's font are used.
 
 ```javascript
-// Old style (still works)
-charOsc(10, 0.1, 0, 16)
-  .charColor(osc(10, 0.1));
-
-// New style (recommended)
-char(osc(10, 0.1), 16)
-  .charColor(osc(10, 0.1));
+char(noise(10)).charMap('@#%*+=-:. ');  // ASCII gradient
+char(voronoi(5)).charMap('█▓▒░ ');       // Block characters
 ```
 
+## Documentation
+
+There's a lot more to explore beyond this overview:
+
+- **[Online documentation](https://code.textmode.art/docs/synth)** - Full guides and tutorials
+- **[API reference](./api/index.md)** - Complete API documentation
+- **[synth.textmode.art](https://synth.textmode.art)** - Live coding environment
+
 ## License
 
-MIT
+Distributed under the **AGPL-3.0** License. See [LICENSE](./LICENSE) for more information.
 
 ## Credits
 
-Inspired by [hydra-synth](https://github.com/hydra-synth/hydra-synth) by Olivia Jack.
+This project is a derivative work of [hydra-synth](https://github.com/hydra-synth/hydra-synth) by [Olivia Jack](https://github.com/ojack), adapted for the [textmode.js](https://github.com/humanbydefinition/textmode.js) ecosystem.
+
+- **hydra-synth**: Core synthesis logic, GLSL shader generation, and functional API design.
+- **Modifications**: Adapted for `textmode.js`'s three-texture rendering pipeline *(characters, foreground colors, background colors)* and plugin system.