@stevejtrettel/shader-sandbox 0.1.2 → 0.1.4

package/README.md

@@ -1,105 +1,83 @@
 # Shader Sandbox
 
-A lightweight, Shadertoy-compatible GLSL shader playground built for teaching and learning shader programming.
+A lightweight, Shadertoy-compatible GLSL shader development environment. Copy shaders directly from Shadertoy and run them locally with live editing.
 
 ## Features
 
 - **Shadertoy Compatibility** - Copy/paste shaders directly from Shadertoy
-- **Full Shadertoy Uniforms** - `iTime`, `iResolution`, `iFrame`, `iMouse`, `iTimeDelta`, `iChannel0-3`
+- **Full Shadertoy Uniforms** - `iTime`, `iResolution`, `iFrame`, `iMouse`, `iTimeDelta`, `iDate`, `iFrameRate`, `iChannel0-3`
 - **Multi-Buffer Rendering** - BufferA-D passes with correct ping-pong semantics
-- **Texture Support** - Load external images with configurable filtering and wrapping
-- **Keyboard Input** - Full keyboard state via Shadertoy-compatible texture
+- **Texture Support** - Load images (including cubemaps) with configurable filtering and wrapping
+- **Keyboard Input** - Full keyboard state via texture. In standard mode, key constants (`KEY_A`–`KEY_Z`, `KEY_SPACE`, etc.) and helpers (`isKeyDown`, `keyToggle`) are auto-injected
+- **Audio Input** - Microphone FFT spectrum and waveform as a texture, as in shadertoy
+- **Webcam & Video** - Live webcam or video files as channel inputs, as in shadertoy
+- **Custom Uniforms** - Float, int, bool, vec2, vec3, vec4 sliders and color pickers via config. *An extension beyond shadertoy*
+- **UBO Array Uniforms** - Large data arrays (positions, colors, matrices) via Uniform Buffer Objects. *An extension beyond shadertoy*
+- **Scripting API** - JavaScript hooks for per-frame computation, texture upload, and GPU readback. *An extension beyond shadertoy*
+- **Touch Support** - Multi-touch, pinch, and gesture uniforms for mobile
+- **Live Code Editing** - Edit shaders in the browser with instant recompilation
+- **Multiple Layouts** - Fullscreen, split-view, or tabbed code display
 - **Playback Controls** - Play/pause, reset, and screenshot capture
-- **Multiple Layout Modes** - Fullscreen, default, split-view, or tabbed code display
-- **Zero Runtime Dependencies** - Pure WebGL2
-- **Tiny Builds** - ~26KB JS (gzipped)
+- **Themes** - Light, dark, or system-following theme
 
 ## Quick Start
 
 ```bash
-npm install
-npm run new my-shader
-npm run dev:demo my-shader
-```
-
-Open `http://localhost:3000` to see your shader.
-
----
-
-## Use as NPM Package
+# Create a new shader project
+npx @stevejtrettel/shader-sandbox create my-shaders
 
-Create your own shader collection:
-
-```bash
-# Create a new project (does everything in one step)
-npx shader-sandbox create my-shaders
-
-# Run a shader
+# Enter the project
 cd my-shaders
+
+# Run an example shader
 shader dev example-gradient
 ```
 
-That's it! The `create` command sets up the directory, installs dependencies, and creates example shaders.
+Open http://localhost:3000 to see your shader running.
 
-### CLI Commands
+## CLI Commands
 
 ```bash
-shader create <name>     # Create a new shader project (recommended)
-shader init              # Initialize shaders in current directory
-shader list              # List all shaders
-shader dev <name>        # Run shader in development mode
+shader create <name>     # Create a new shader project
+shader dev <name>        # Run shader with live reload
 shader build <name>      # Build shader for production
 shader new <name>        # Create a new shader
+shader list              # List all shaders
+shader init              # Initialize shaders in current directory
 ```
 
-### Project Structure
+## Project Structure
 
-After `shader create`:
+After running `shader create my-shaders`:
 
 ```
 my-shaders/
 ├── shaders/
 │   ├── example-gradient/
-│   │   ├── image.glsl      # Main shader
-│   │   └── config.json     # Optional config
+│   │   ├── image.glsl       # Main shader code
+│   │   └── config.json      # Optional configuration
 │   └── example-buffer/
-│       ├── image.glsl
-│       ├── bufferA.glsl    # Feedback buffer
+│       ├── image.glsl       # Final output
+│       ├── bufferA.glsl     # Feedback buffer
 │       └── config.json
-├── main.ts
-├── vite.config.js
+├── main.ts                  # Entry point
+├── vite.config.js           # Vite configuration
 └── package.json
 ```
 
-### Adding a New Shader
-
-```bash
-shader new my-cool-shader
-# Creates shaders/my-cool-shader/image.glsl
-
-shader dev my-cool-shader
-# Opens browser with live reload
-```
+## Creating Shaders
 
----
+### Simple Shader
 
-## Common Setups
-
-### 1. Simple Shader (just image.glsl)
-
-The simplest setup - no config needed.
+Create a new shader with just an image pass:
 
 ```bash
-npm run new my-shader
+shader new my-shader
+shader dev my-shader
 ```
 
-**Files:**
-```
-demos/my-shader/
-└── image.glsl
-```
+Edit `shaders/my-shader/image.glsl`:
 
-**image.glsl:**
 ```glsl
 void mainImage(out vec4 fragColor, in vec2 fragCoord) {
     vec2 uv = fragCoord / iResolution.xy;
@@ -108,45 +86,26 @@ void mainImage(out vec4 fragColor, in vec2 fragCoord) {
 }
 ```
 
----
+### Copy from Shadertoy
 
-### 2. One Buffer (feedback/trails)
+1. Find a shader on [Shadertoy](https://www.shadertoy.com)
+2. Copy the code from the "Image" tab
+3. Paste into `shaders/my-shader/image.glsl`
+4. Run `shader dev my-shader`
 
-For effects that accumulate over time (trails, paint, fluid).
+Most single-pass shaders work immediately. For multi-buffer shaders, you'll need to create the buffer files and config.
 
-```bash
-npm run new my-shader 1
-```
+### Multi-Buffer Shaders
 
-**Files:**
-```
-demos/my-shader/
-├── bufferA.glsl
-├── image.glsl
-└── config.json
-```
-
-**config.json:**
-```json
-{
-  "BufferA": {
-    "iChannel0": "BufferA"
-  },
-  "Image": {
-    "iChannel0": "BufferA"
-  }
-}
-```
+For feedback effects (trails, fluid, etc.), create a buffer:
 
-**bufferA.glsl:**
+**shaders/my-effect/bufferA.glsl:**
 ```glsl
 void mainImage(out vec4 fragColor, in vec2 fragCoord) {
     vec2 uv = fragCoord / iResolution.xy;
+    vec4 prev = texture(iChannel0, uv) * 0.98;  // Previous frame with fade
 
-    // Read previous frame with fade
-    vec4 prev = texture(iChannel0, uv) * 0.98;
-
-    // Draw at mouse
+    // Draw at mouse position
     vec2 mouse = iMouse.xy / iResolution.xy;
     float d = length(uv - mouse);
     float spot = smoothstep(0.05, 0.0, d);
@@ -155,7 +114,7 @@ void mainImage(out vec4 fragColor, in vec2 fragCoord) {
 }
 ```
 
-**image.glsl:**
+**shaders/my-effect/image.glsl:**
 ```glsl
 void mainImage(out vec4 fragColor, in vec2 fragCoord) {
     vec2 uv = fragCoord / iResolution.xy;
@@ -163,228 +122,293 @@ void mainImage(out vec4 fragColor, in vec2 fragCoord) {
 }
 ```
 
----
-
-### 3. Multiple Buffers (interacting simulations)
-
-For reaction-diffusion, fluid dynamics, etc. All buffers can read all other buffers.
-
-```bash
-npm run new my-shader 2
-```
-
-**Files:**
-```
-demos/my-shader/
-├── bufferA.glsl
-├── bufferB.glsl
-├── image.glsl
-└── config.json
-```
-
-**config.json:**
+**shaders/my-effect/config.json:**
 ```json
 {
   "BufferA": {
-    "iChannel0": "BufferA",
-    "iChannel1": "BufferB"
-  },
-  "BufferB": {
-    "iChannel0": "BufferA",
-    "iChannel1": "BufferB"
+    "iChannel0": "BufferA"
   },
   "Image": {
-    "iChannel0": "BufferA",
-    "iChannel1": "BufferB"
+    "iChannel0": "BufferA"
   }
 }
 ```
 
-**Channel mapping:** `iChannel0` = BufferA, `iChannel1` = BufferB, etc.
-
----
+### Using Textures
 
-### 4. Texture + Image (image processing)
+Place an image in your shader folder and reference it in config:
 
-Load an image and process it.
-
-**Files:**
-```
-demos/my-shader/
-├── image.glsl
-├── photo.jpg
-└── config.json
+```json
+{
+  "Image": {
+    "iChannel0": "photo.jpg"
+  }
+}
 ```
 
-**config.json:**
+With options:
 ```json
 {
   "Image": {
-    "iChannel0": "photo.jpg"
+    "iChannel0": {
+      "texture": "photo.jpg",
+      "filter": "nearest",
+      "wrap": "clamp"
+    }
   }
 }
 ```
 
-**image.glsl:**
-```glsl
-void mainImage(out vec4 fragColor, in vec2 fragCoord) {
-    vec2 uv = fragCoord / iResolution.xy;
-    vec4 img = texture(iChannel0, uv);
+### Custom Uniforms (Slider Controls)
 
-    // Example: grayscale
-    float gray = dot(img.rgb, vec3(0.299, 0.587, 0.114));
+Add interactive controls to your shader by defining uniforms in config:
 
-    fragColor = vec4(vec3(gray), 1.0);
+```json
+{
+  "controls": true,
+  "uniforms": {
+    "uSpeed": { "type": "float", "value": 1.0, "min": 0.0, "max": 5.0, "label": "Speed" },
+    "uColor": { "type": "vec3", "value": [1.0, 0.5, 0.2], "color": true, "label": "Color" },
+    "uAnimate": { "type": "bool", "value": true, "label": "Animate" }
+  },
+  "Image": {}
 }
 ```
 
-**Texture options (all optional):**
-```json
-{ "texture": "photo.jpg", "filter": "linear", "wrap": "repeat", "type": "2d" }
-```
-- `filter`: `"linear"` (smooth, default) or `"nearest"` (pixelated)
-- `wrap`: `"repeat"` (tile, default) or `"clamp"` (stretch edges)
-- `type`: `"2d"` (standard, default) or `"cubemap"` (equirectangular environment map)
+Uniforms declared in config are **auto-injected** into your shader code — you don't need to write `uniform` declarations. Just use them directly:
 
-**Cubemap textures:** Use `"type": "cubemap"` for equirectangular environment maps (360° panoramas). The engine will automatically convert 3D direction lookups to 2D coordinates:
-```json
-{ "texture": "environment.jpg", "type": "cubemap" }
-```
 ```glsl
-// In your shader, sample with a 3D direction:
-vec3 dir = normalize(rayDirection);
-vec4 sky = texture(iChannel0, dir);  // Automatically converted
+void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+    vec2 uv = fragCoord / iResolution.xy;
+    float t = uAnimate ? iTime * uSpeed : 0.0;
+    vec3 col = uColor * (0.5 + 0.5 * sin(uv.x * 10.0 - t));
+    fragColor = vec4(col, 1.0);
+}
 ```
 
----
+#### Supported Uniform Types
 
-### 5. Texture + Buffers (image + feedback)
+| Type | UI Control | Config Fields |
+|------|-----------|---------------|
+| `float` | Slider | `value`, `min` (0), `max` (1), `step` (0.01) |
+| `int` | Discrete slider | `value`, `min` (0), `max` (10), `step` (1) |
+| `bool` | Toggle | `value` |
+| `vec2` | XY pad | `value`, `min` ([0,0]), `max` ([1,1]) |
+| `vec3` | 3 sliders or color picker | `value`, `color` (false), `min`, `max`, `step` |
+| `vec4` | 4 sliders or color+alpha picker | `value`, `color` (false), `min`, `max`, `step` |
 
-Combine textures with buffer feedback for effects like painting on an image.
+Set `"hidden": true` on any scalar uniform to exclude it from the UI panel (useful for script-controlled values).
 
-**Files:**
-```
-demos/my-shader/
-├── bufferA.glsl
-├── image.glsl
-├── photo.jpg
-└── config.json
-```
+#### Array Uniforms (UBOs)
+
+For large data arrays (positions, matrices, etc.), use array uniforms backed by Uniform Buffer Objects:
 
-**config.json:**
 ```json
 {
-  "BufferA": {
-    "iChannel0": "BufferA",
-    "iChannel1": "photo.jpg"
-  },
-  "Image": {
-    "iChannel0": "BufferA",
-    "iChannel1": "photo.jpg"
+  "uniforms": {
+    "matrices": { "type": "mat3", "count": 128 },
+    "matrixCount": { "type": "int", "value": 1, "hidden": true }
   }
 }
 ```
 
-**bufferA.glsl:**
+Array uniforms support types: `float`, `vec2`, `vec3`, `vec4`, `mat3`, `mat4`. They have no UI — data is provided from JavaScript via `engine.setUniformValue()`.
+
+In the compiled shader, array uniforms are wrapped in a `layout(std140)` uniform block with a `_ub_` prefix (e.g., `_ub_matrices`). The array variable itself uses the original name, so you reference it directly in GLSL:
+
 ```glsl
+// Auto-injected by the engine (you don't write this):
+// layout(std140) uniform _ub_matrices {
+//   mat3 matrices[128];
+// };
+
 void mainImage(out vec4 fragColor, in vec2 fragCoord) {
-    vec2 uv = fragCoord / iResolution.xy;
+    for (int i = 0; i < matrixCount; i++) {
+        vec3 p = matrices[i] * vec3(fragCoord, 1.0);
+        // ...
+    }
+}
+```
 
-    vec4 prev = texture(iChannel0, uv);      // Previous frame
-    vec4 img = texture(iChannel1, uv);        // Original image
+See the [Configuration Reference](docs/learn/configuration.md) for all uniform types.
 
-    // Paint with mouse
-    vec2 mouse = iMouse.xy / iResolution.xy;
-    float d = length(uv - mouse);
-    float brush = smoothstep(0.05, 0.0, d);
+### Scripting (JavaScript Hooks)
 
-    // Blend: painted areas persist, unpainted fade to original
-    fragColor = mix(mix(prev, img, 0.01), prev + brush, brush);
+For computed data that changes every frame, add a `script.js` to your shader folder:
+
+**shaders/my-shader/script.js:**
+```js
+const COUNT = 32;
+
+export function onFrame(engine, time) {
+  const data = new Float32Array(COUNT * 4);
+  for (let i = 0; i < COUNT; i++) {
+    const phase = (i / COUNT) * Math.PI * 2.0;
+    data[i * 4 + 0] = 0.5 + Math.cos(time + phase) * 0.3;  // x
+    data[i * 4 + 1] = 0.5 + Math.sin(time + phase) * 0.3;  // y
+    data[i * 4 + 2] = 0.02;                                  // radius
+    data[i * 4 + 3] = i / COUNT;                              // hue
+  }
+  engine.setUniformValue('positions', data);
 }
 ```
 
----
-
-## Buffer Execution & Frame Timing
+Scripts can export `setup(engine)` (called once) and/or `onFrame(engine, time, deltaTime, frame)` (called every frame).
 
-**Execution order:** BufferA → BufferB → BufferC → BufferD → Image
+The script API provides:
+- `engine.setUniformValue(name, value)` — set any uniform
+- `engine.getUniformValue(name)` — read current value
+- `engine.updateTexture(name, width, height, data)` — upload a texture from JS
+- `engine.readPixels(passName, x, y, w, h)` — read pixels from a buffer (GPU readback)
+- `engine.width` / `engine.height` — canvas dimensions
 
-All buffer reads default to the **previous frame**. This is safe for all cases:
-- Self-reference (feedback effects)
-- Reading buffers that haven't run yet this frame
-- Reading buffers that have already run (you get their latest output)
+## Channel Types
 
-Use `{ "buffer": "BufferA", "current": true }` only if you specifically need the in-progress current frame (rare).
+Channels can be bound using string shortcuts or full objects:
 
----
+| Shorthand | Object Form | Description |
+|-----------|-------------|-------------|
+| `"BufferA"` | `{ "buffer": "BufferA" }` | Buffer pass output |
+| `"photo.jpg"` | `{ "texture": "photo.jpg" }` | Image texture |
+| `"keyboard"` | `{ "keyboard": true }` | Keyboard state |
+| `"audio"` | `{ "audio": true }` | Microphone FFT + waveform |
+| `"webcam"` | `{ "webcam": true }` | Live webcam feed |
+| — | `{ "video": "clip.mp4" }` | Video file |
+| — | `{ "script": "myData" }` | Script-uploaded texture |
 
 ## Layouts
 
-Control how the shader is displayed with the `layout` option in `config.json`:
+Control how the shader is displayed in `config.json`:
 
 ```json
 {
-  "layout": "split",
-  "BufferA": { ... },
-  "Image": { ... }
+  "layout": "split"
 }
 ```
 
-| Layout | Description | Best for |
-|--------|-------------|----------|
-| `fullscreen` | Canvas fills entire viewport | Immersive art, games, installations |
-| `default` | Canvas centered with max-width | General viewing (default without config) |
-| `tabbed` | Tabs to switch between shader and code | Exploring/debugging |
-| `split` | Side-by-side: shader left, code right | Teaching, presentations, tutorials |
+| Layout | Description |
+|--------|-------------|
+| `fullscreen` | Canvas fills the viewport |
+| `default` | Centered canvas with controls |
+| `tabbed` | Tabs to switch between shader and code |
+| `split` | Side-by-side shader and code editor |
 
-**`fullscreen`** - No chrome, canvas fills the screen:
-```json
-{ "layout": "fullscreen" }
-```
+## Shadertoy Uniforms
 
-**`default`** - Clean centered view with rounded corners:
-```json
-{ "layout": "default" }
-```
+All standard Shadertoy uniforms are supported:
 
-**`tabbed`** - Click tabs to switch between live shader and source code:
-```json
-{ "layout": "tabbed" }
-```
+| Uniform | Type | Description |
+|---------|------|-------------|
+| `iResolution` | `vec3` | Viewport resolution (width, height, 1) |
+| `iTime` | `float` | Elapsed time in seconds |
+| `iTimeDelta` | `float` | Time since last frame |
+| `iFrame` | `int` | Frame counter |
+| `iFrameRate` | `float` | Frames per second |
+| `iMouse` | `vec4` | Mouse position and click state |
+| `iChannel0-3` | `sampler2D` | Input textures/buffers |
+| `iChannelResolution[4]` | `vec3[]` | Resolution of each channel |
+| `iDate` | `vec4` | Year, month, day, time in seconds |
 
-**`split`** - See shader and code simultaneously (code panel has tabs for multi-file projects):
-```json
-{ "layout": "split" }
-```
+### Touch Uniforms (Mobile / Multi-touch)
 
----
+| Uniform | Type | Description |
+|---------|------|-------------|
+| `iTouchCount` | `int` | Number of active touches |
+| `iTouch0-2` | `vec4` | Per-touch position and state |
+| `iPinch` | `float` | Current pinch distance |
+| `iPinchDelta` | `float` | Change in pinch distance |
+| `iPinchCenter` | `vec2` | Center point between pinch fingers |
 
 ## Keyboard Shortcuts
 
 | Key | Action |
 |-----|--------|
 | **S** | Save screenshot (PNG) |
-| **Space** | Play/Pause (when controls enabled) |
-| **R** | Reset to frame 0 (when controls enabled) |
+| **Space** | Play/Pause |
+| **R** | Reset to frame 0 |
 
----
+## Recording and Export
 
-## NPM Scripts
+### Video Recording
 
-```bash
-npm run new <name> [buffers]   # Create new shader project
-npm run dev:demo <name>        # Development server with hot reload
-npm run build:demo <name>      # Production build to dist/
+When `controls: true`, click the record button (or use the controls menu) to capture your shader as a WebM video. Recording uses the browser's `MediaRecorder` API at 60fps with VP9 encoding. Click the stop button to end recording — the video downloads automatically.
+
+### HTML Export
+
+Click the export button in the controls menu to generate a standalone HTML file with your shader embedded. The exported file includes:
+- All shader passes and common code
+- Current custom uniform values baked in
+- Full WebGL2 rendering pipeline (no dependencies)
+- Mouse interaction support
+- Resize handling
+
+**Limitations:** Array uniforms (UBOs), audio, webcam, video, and script hooks are not included in the export. Textures are replaced with a procedural checkerboard pattern.
+
+## Embedding as a Library
+
+The package exports its core classes for use in custom applications:
+
+```typescript
+import { App, createLayout, loadDemo } from '@stevejtrettel/shader-sandbox';
+import type { ShaderProject, LayoutMode } from '@stevejtrettel/shader-sandbox';
 ```
 
----
+### Exports
+
+| Export | Description |
+|--------|-------------|
+| `App` | Main application class — creates canvas, engine, and animation loop |
+| `createLayout(mode, options)` | Factory to create a layout (fullscreen, default, split, tabbed) |
+| `applyTheme(mode)` | Apply a theme (light, dark, system) |
+| `loadDemo(files)` | Load a shader project from bundled file data |
+
+### Example: Embedding a shader
+
+```typescript
+import { App, createLayout } from '@stevejtrettel/shader-sandbox';
+
+const project = /* your ShaderProject object */;
 
-## Documentation
+const layout = createLayout(project.layout, {
+  container: document.getElementById('shader-container'),
+  project,
+});
+
+const app = new App({
+  container: layout.getCanvasContainer(),
+  project,
+});
+
+if (!app.hasErrors()) {
+  app.start();
+}
+
+// Clean up when done
+app.dispose();
+```
+
+### Embed entry point
+
+For build-time embedding of a specific shader, the package also provides an `embed()` function:
+
+```typescript
+import { embed } from '@stevejtrettel/shader-sandbox/embed';
+
+const { app, destroy } = await embed({
+  container: '#my-container',  // CSS selector or HTMLElement
+  pixelRatio: window.devicePixelRatio,
+});
+
+// Later: destroy() to clean up
+```
+
+## Building for Production
+
+```bash
+shader build my-shader
+```
 
-- [Getting Started](docs/learn/getting-started.md) - Your first shader
-- [Buffers and Channels](docs/learn/buffers-and-channels.md) - Multi-pass rendering
-- [Configuration](docs/learn/configuration.md) - Full config reference
-- [Architecture](docs/dev/architecture.md) - How the engine works
+Output is in `dist/` - a single HTML file with embedded JavaScript that can be hosted anywhere.
 
 ## License