lfocomp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-28
+
+### Added
+- 7 waveform shapes: sine, triangle, saw, rsaw, square, S&H, smooth random
+- Drag-to-assign handle with pointer capture and cross-element detection
+- LFO chaining — drag onto another LFO's Rate or Depth slider; rate modulation is multiplicative so it never reaches zero
+- Per-cycle jitter and waveform skew parameters
+- ModIndicator badges with drag-adjustable depth and range arc overlay
+- Modulation matrix with live depth sliders and one-click delete
+- Bipolar / unipolar toggle (BI/UNI button)
+- Click-to-type on any param value readout; Enter commits, Escape cancels
+- Float32Array ring buffer oscilloscope with fixed wall-clock time axis
+- Log-scaled rate slider (0.01 Hz – 10 Hz)
+- Zero runtime dependencies
+
+[Unreleased]: https://github.com/KUSH42/lfocomp/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/KUSH42/lfocomp/releases/tag/v0.1.0

package/README.md

@@ -0,0 +1,179 @@
+# lfocomp
+
+**Drop an LFO onto any HTML input. Done.**
+
+![lfocomp demo](docs/demo.gif)
+
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)]()
+[![ES modules](https://img.shields.io/badge/module-ESM-f7df1e.svg)]()
+[![npm](https://img.shields.io/badge/npm-not%20yet%20published-lightgrey.svg)]()
+
+**[Live demo](https://kush42.github.io/lfo.html)**
+
+---
+
+## What it is
+
+A zero-dependency ES module that adds Ableton/Bitwig-style LFO modulation to any `<input type=range>` or `<input type=number>`. Drag the assign handle onto a slider. It modulates. That's it.
+
+No npm install at runtime. No bundler. No framework. Serve the files, open the page, wire things up.
+
+---
+
+## Why this exists
+
+Every existing approach is either:
+
+- A full synthesizer library pulling in 400 KB of irrelevant code
+- A half-finished CodePen someone wrote at 2am
+- Something that requires a bundler, a framework, and three config files to get "hello sine wave"
+
+lfocomp is one import, three files, and you're live.
+
+---
+
+## Install
+
+### npm *(coming soon)*
+```bash
+npm install lfocomp
+```
+```js
+import { createLFO } from 'lfocomp';
+```
+
+### CDN (no install)
+```html
+<script type="module">
+  import { createLFO } from 'https://cdn.jsdelivr.net/npm/lfocomp/lfo-comp.js';
+</script>
+```
+
+### Self-hosted
+Download `lfo-comp.js`, `lfo-engine.js`, and `lfo-ui.js` into the same directory.
+No build step required.
+
+---
+
+## Quick start
+
+```bash
+git clone https://github.com/KUSH42/lfocomp
+cd lfocomp
+npm run serve        # python3 -m http.server 8080
+# open http://localhost:8080/demo.html
+```
+
+```js
+import { createLFO } from './lfo-comp.js';
+
+const { widget } = createLFO(document.querySelector('#lfo-panel'));
+
+// Drag the ⊕ handle onto any slider — or wire programmatically:
+widget.connect(document.querySelector('#my-slider'), { depth: 0.7 });
+```
+
+---
+
+## Features
+
+- **7 waveforms** — Sine, Triangle, Saw, Reverse Saw, Square, Sample & Hold, Smooth Random
+- **Drag-to-assign** — pointer-captured drag wire, highlights valid targets on hover
+- **LFO chaining** — drag LFO B's handle onto LFO A's Rate or Depth slider to chain them. Rate modulation is multiplicative (`rate × (1 + src × depth)`), so it never goes to zero
+- **Per-cycle jitter** — randomises each cycle's duration independently; visible as variable-width cycles in the waveform view
+- **Waveform skew** — warps the phase midpoint, turning a sine into something between a shark fin and a reverse ramp
+- **Modulation matrix** — live table of all active routes with adjustable depth sliders and one-click delete
+- **ModIndicator badges** — floating badges anchored to each connected input with drag-to-adjust depth and a range arc showing the sweep zone
+- **Bipolar / unipolar toggle** — BI/UNI button on the widget switches output between ±1 and 0–1
+- **Click-to-type param values** — click any value readout to type an exact number; Enter commits, Escape cancels
+
+---
+
+## Technical deep dive: the oscilloscope buffer
+
+Most LFO visualisers recompute the waveform from the current phase on every frame. That approach has two problems: it can't show jitter (because jitter is stochastic per-cycle, not a formula), and it makes speed changes look instant instead of gradual.
+
+lfocomp records the *actual output value* on every engine tick into a `Float32Array` ring buffer:
+
+```js
+// Engine tick → subscribe callback → _recordSample(currentValue)
+this._wfHistory.copyWithin(0, intShift);          // shift left, O(1) typed-array copy
+for (let i = 0; i < intShift; i++) {
+  const t = (i + 1) / intShift;
+  this._wfHistory[W - intShift + i] = prev + (cur - prev) * t;  // linear interpolation
+}
+```
+
+The cursor advances at a fixed wall-clock rate (`W / 4` px/sec — always a 4-second window) regardless of LFO rate, so a 0.1 Hz LFO and a 10 Hz LFO both scroll at the same speed. Only the cycle density changes.
+
+The visible canvas is composited from an offscreen `willReadFrequently` buffer. Only `intShift` new columns are painted per frame via `getImageData`/`putImageData` — no full redraws at 60 fps.
+
+---
+
+## API
+
+```js
+// Create
+const { lfoId, widget } = createLFO(containerEl, {
+  shape:   'sine',   // 'sine'|'triangle'|'saw'|'rsaw'|'square'|'random'|'smooth'
+  rate:    1.0,      // Hz (0.01–10)
+  depth:   1.0,      // 0–1
+  phase:   0.0,      // 0–1 (0.5 = 180° offset)
+  offset:  0.0,      // DC offset, -1–1
+  bipolar: true,     // true = ±1 output, false = 0–1
+  color:   '#00d4ff',
+  label:   'LFO 1',
+});
+
+// Connect
+const routeId = widget.connect(element, { depth: 0.5 });
+
+// Disconnect
+disconnect(routeId);
+
+// Inspect
+getRoutes();           // → RouteState[]
+engine.getLFO(lfoId);  // → full LFO state object
+engine.getAllRoutes();
+```
+
+### LFO chain routes (programmatic)
+
+```js
+// LFO 2 modulates LFO 1's rate at 40% depth
+engine.addRoute(lfo2Id, 'lfo', lfo1Id, 'rate',  { depth: 0.4 });
+engine.addRoute(lfo2Id, 'lfo', lfo1Id, 'depth', { depth: 0.3 });
+```
+
+---
+
+## File structure
+
+```
+lfocomp/
+├── lfo-engine.js   Core: LFO state machine, tick loop, route graph
+├── lfo-ui.js       DOM: canvas widget, ModIndicator badge, drag wire
+├── lfo-comp.js     Public API: createLFO(), connect(), disconnect()
+├── demo.html       Interactive demo — open after npm run serve
+├── tests/          Unit tests (vitest, jsdom)
+```
+
+The three files are fully independent of each other except in one direction: `lfo-ui.js` imports from `lfo-engine.js`, and `lfo-comp.js` imports from both. Nothing imports from the outside.
+
+---
+
+## Running tests
+
+```bash
+npm test            # vitest run
+npm run test:watch  # watch mode
+```
+
+91 tests across three files: `engine.test.js` (math, tick loop, route graph), `widget.test.js` (LFOWidget lifecycle, drag cancel, ModIndicator, stale-route pruning), and `comp.test.js` (public API factory, color cycling, connect/disconnect helpers).
+
+---
+
+## License
+
+MIT

package/lfo-comp.js

@@ -0,0 +1,140 @@
+/**
+ * lfo-comp.js — Public API for the LFO modulation component.
+ *
+ * Quick start:
+ *
+ *   import { createLFO } from './lfo-comp.js';
+ *
+ *   // 1. Create an LFO panel in a container element:
+ *   const { widget } = createLFO(document.querySelector('#lfo-panel'));
+ *
+ *   // 2. Drag the "⊕ drag to assign" handle onto any <input type=range>
+ *   //    or <input type=number> to wire up modulation.
+ *
+ *   // 3. Programmatic connection (optional):
+ *   widget.connect(document.querySelector('#my-slider'), { depth: 0.7 });
+ *
+ *   // 4. Chain LFOs — drag LFO 2's handle onto LFO 1's Rate slider,
+ *   //    or call:
+ *   engine.addRoute(lfo2Id, 'lfo', lfo1Id, 'rate', { depth: 0.4 });
+ *
+ * Re-exports the engine singleton and UI classes for advanced use.
+ */
+
+import { engine, SHAPES, seededRand, smoothRand } from './lfo-engine.js';
+import { LFOWidget, ModIndicator, injectStyles, LFO_COLORS } from './lfo-ui.js';
+
+export { engine, SHAPES, seededRand, smoothRand };
+export { LFOWidget, ModIndicator, injectStyles, LFO_COLORS };
+
+// Registry so disconnect() can clean up the ModIndicator badge.
+// Maps routeId → LFOWidget that owns it.
+const _widgetByRoute = new Map();
+
+let _count = 0;
+let _colorCount = 0; // separate counter so color cycling advances on every createLFO call
+
+/**
+ * Create a fully wired LFO widget.
+ *
+ * @param {HTMLElement|object} containerOrOpts
+ *   If an HTMLElement, the widget is appended to it and opts is the second arg.
+ *   If an object, treated as opts — caller is responsible for appending widget.element.
+ * @param {object} [opts]
+ * @param {string}   [opts.shape='sine']   Initial waveform shape.
+ * @param {number}   [opts.rate=1]         Initial rate in Hz.
+ * @param {number}   [opts.depth=1]        Initial depth 0–1.
+ * @param {number}   [opts.phase=0]        Initial phase offset 0–1.
+ * @param {number}   [opts.offset=0]       DC offset -1–1.
+ * @param {string}   [opts.color]          Accent color. Auto-assigned if omitted.
+ * @param {string}   [opts.label]          Widget label. Auto-assigned if omitted.
+ * @param {function} [opts.onConnect]      Called when a connection is made.
+ * @param {function} [opts.onDisconnect]   Called when a connection is removed.
+ *
+ * @returns {{ lfoId: string, widget: LFOWidget }}
+ */
+export function createLFO(containerOrOpts = {}, opts = {}) {
+  let container, engineOpts, uiOpts;
+
+  if (containerOrOpts instanceof Element) {
+    container  = containerOrOpts;
+    engineOpts = opts;
+    uiOpts     = opts;
+  } else {
+    container  = null;
+    engineOpts = containerOrOpts;
+    uiOpts     = containerOrOpts;
+  }
+
+  const colorIdx = _colorCount++;
+  if (!uiOpts.label) {
+    uiOpts = { ...uiOpts, label: `LFO ${++_count}` };
+  }
+  if (!uiOpts.color) {
+    uiOpts = { ...uiOpts, color: LFO_COLORS[colorIdx % LFO_COLORS.length] };
+  }
+
+  // Wrap caller callbacks to maintain _widgetByRoute registry.
+  const callerOnConnect    = uiOpts.onConnect;
+  const callerOnDisconnect = uiOpts.onDisconnect;
+  // Forward-declare so the onConnect closure can reference it without a lint warning.
+  let widget;
+
+  uiOpts = {
+    ...uiOpts,
+    onConnect: (lfoId, el, routeId) => {
+      _widgetByRoute.set(routeId, widget);
+      callerOnConnect?.(lfoId, el, routeId);
+    },
+    onDisconnect: (routeId) => {
+      _widgetByRoute.delete(routeId);
+      callerOnDisconnect?.(routeId);
+    },
+  };
+
+  const lfoId = engine.createLFO(engineOpts);
+  const div   = container ?? document.createElement('div');
+  widget = new LFOWidget(div, lfoId, uiOpts);
+
+  return { lfoId, widget };
+}
+
+/**
+ * Programmatically connect an LFO to an HTML element.
+ * Equivalent to calling widget.connect(element, opts).
+ *
+ * @param {LFOWidget}   widget
+ * @param {HTMLElement} element
+ * @param {object}      [opts]
+ * @param {number}      [opts.depth=0.5]
+ * @returns {string|null} routeId, or null if connection was rejected.
+ */
+export function connect(widget, element, opts = {}) {
+  return widget.connect(element, opts);
+}
+
+/**
+ * Remove a modulation route and its UI indicator.
+ * Prefer calling widget.disconnectRoute(routeId) directly when you have the widget.
+ * This function handles programmatic routes created via connect() or drag-to-assign.
+ *
+ * @param {string} routeId
+ */
+export function disconnect(routeId) {
+  const widget = _widgetByRoute.get(routeId);
+  if (widget) {
+    // Goes through the widget so the ModIndicator badge is also removed.
+    widget.disconnectRoute(routeId);
+  } else {
+    // Fallback for engine-only routes (e.g. direct engine.addRoute calls).
+    engine.removeRoute(routeId);
+  }
+}
+
+/**
+ * Get all currently active modulation routes.
+ * @returns {object[]}
+ */
+export function getRoutes() {
+  return engine.getAllRoutes();
+}