lfocomp 0.1.0

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "lfocomp",
+  "version": "0.1.0",
+  "description": "Ableton-style LFO modulation component — wire LFOs to any HTML input by drag-and-drop",
+  "type": "module",
+  "main": "./lfo-comp.js",
+  "module": "./lfo-comp.js",
+  "types": "./types/lfo-comp.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./types/lfo-comp.d.ts",
+      "default": "./lfo-comp.js"
+    },
+    "./engine": {
+      "types": "./types/lfo-engine.d.ts",
+      "default": "./lfo-engine.js"
+    },
+    "./ui": {
+      "types": "./types/lfo-ui.d.ts",
+      "default": "./lfo-ui.js"
+    },
+    "./bundle": {
+      "types": "./types/lfo.d.ts",
+      "default": "./lfo.js"
+    }
+  },
+  "files": [
+    "lfo-comp.js",
+    "lfo-engine.js",
+    "lfo-ui.js",
+    "lfo.js",
+    "types/",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build:types": "tsc -p tsconfig.json && tsc -p tsconfig.bundle.json",
+    "build:bundle": "rollup lfo-comp.js --file lfo.js --format es",
+    "build": "npm run build:bundle && npm run build:types",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "serve": "python3 -m http.server 8080"
+  },
+  "keywords": [
+    "lfo",
+    "modulation",
+    "synthesizer",
+    "audio",
+    "ui",
+    "knob",
+    "ableton",
+    "bitwig",
+    "serum"
+  ],
+  "homepage": "https://kush42.github.io/lfo.html",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KUSH42/lfocomp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/KUSH42/lfocomp/issues"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
+    "jsdom": "^29.0.1",
+    "playwright": "^1.58.2",
+    "rollup": "^4.60.0",
+    "typescript": "^6.0.2",
+    "vitest": "^3.0.0"
+  }
+}

package/types/lfo-comp.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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?: HTMLElement | object, opts?: {
+    shape?: string;
+    rate?: number;
+    depth?: number;
+    phase?: number;
+    offset?: number;
+    color?: string;
+    label?: string;
+    onConnect?: Function;
+    onDisconnect?: Function;
+}): {
+    lfoId: string;
+    widget: LFOWidget;
+};
+/**
+ * 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: LFOWidget, element: HTMLElement, opts?: {
+    depth?: number;
+}): string | null;
+/**
+ * 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: string): void;
+/**
+ * Get all currently active modulation routes.
+ * @returns {object[]}
+ */
+export function getRoutes(): object[];
+import { LFOWidget } from './lfo-ui.js';
+import { engine } from './lfo-engine.js';
+import { SHAPES } from './lfo-engine.js';
+import { seededRand } from './lfo-engine.js';
+import { smoothRand } from './lfo-engine.js';
+import { ModIndicator } from './lfo-ui.js';
+import { injectStyles } from './lfo-ui.js';
+import { LFO_COLORS } from './lfo-ui.js';
+export { engine, SHAPES, seededRand, smoothRand, LFOWidget, ModIndicator, injectStyles, LFO_COLORS };

package/types/lfo-engine.d.ts

@@ -0,0 +1,150 @@
+/** Deterministic pseudo-random in [-1, 1] for a given integer seed. */
+export function seededRand(seed: any): number;
+/** Smoothly interpolated random (cubic Hermite) for non-integer phase. */
+export function smoothRand(seed: any, phase: any): number;
+/**
+ * Piecewise-linear phase skew — repositions the midpoint of a 0–1 fractional phase.
+ * skew = 0.5 → symmetric (no change).
+ * skew < 0.5 → ascending flank compressed (peak shifts left).
+ * skew > 0.5 → descending flank compressed (peak shifts right).
+ * @param {number} frac  Fractional phase in [0, 1).
+ * @param {number} skew  Skew amount in [0, 1].
+ * @returns {number} Skewed fractional phase in [0, 1).
+ */
+export function applySkew(frac: number, skew: number): number;
+/**
+ * lfo-engine.js — Core LFO math engine, no DOM dependencies.
+ *
+ * Manages LFO instances, a global RAF tick loop, and a modulation routing
+ * graph. Routes can target HTML elements (range/number inputs) or other
+ * LFO parameters (for chaining).
+ *
+ * Usage:
+ *   import { engine, SHAPES } from './lfo-engine.js';
+ *   const id = engine.createLFO({ shape: 'sine', rate: 2 });
+ *   const routeId = engine.addRoute(id, 'element', sliderEl, null, { depth: 0.5 });
+ */
+export const SHAPES: string[];
+export namespace SHAPE_FN {
+    function sine(p: any): number;
+    function triangle(p: any): number;
+    function saw(p: any): number;
+    function rsaw(p: any): number;
+    function square(p: any): 1 | -1;
+}
+export class LFOEngine {
+    /** @type {Map<string, LFOState>} */
+    _lfos: Map<string, LFOState>;
+    /** @type {Map<string, RouteState>} */
+    _routes: Map<string, RouteState>;
+    /** @type {Map<HTMLElement, ElementState>} */
+    _elementStates: Map<HTMLElement, ElementState>;
+    /** @type {Set<function>} */
+    _subscribers: Set<Function>;
+    _lastTs: any;
+    _rafId: number;
+    _running: boolean;
+    _tick(ts: any): void;
+    start(): void;
+    stop(): void;
+    /**
+     * Create a new LFO instance.
+     * @param {object} opts
+     * @param {string}  [opts.shape='sine']     Waveform shape. One of SHAPES.
+     * @param {number}  [opts.rate=1]           Frequency in Hz.
+     * @param {number}  [opts.depth=1]          Modulation depth multiplier 0–1.
+     * @param {number}  [opts.phase=0]          Initial phase offset 0–1.
+     * @param {number}  [opts.offset=0]         DC offset added to output, -1–1.
+     * @param {boolean} [opts.bipolar=true]     If false, output is remapped 0–1.
+     * @returns {string} LFO id.
+     */
+    createLFO(opts?: {
+        shape?: string;
+        rate?: number;
+        depth?: number;
+        phase?: number;
+        offset?: number;
+        bipolar?: boolean;
+    }): string;
+    /**
+     * Remove an LFO and all its routes.
+     * @param {string} id
+     */
+    destroyLFO(id: string): void;
+    /**
+     * Add a modulation route.
+     *
+     * For element routes: LFO modulates an HTML input element.
+     *   engine.addRoute(lfoId, 'element', inputEl, null, { depth: 0.5 });
+     *
+     * For LFO-chain routes: LFO modulates another LFO's rate or depth.
+     *   engine.addRoute(lfoId, 'lfo', targetLfoId, 'rate', { depth: 0.3 });
+     *
+     * @param {string}                sourceId
+     * @param {'element'|'lfo'}       targetType
+     * @param {HTMLElement|string}    target      Element or target LFO id.
+     * @param {string|null}           targetParam 'rate'|'depth' for lfo, null for element.
+     * @param {object}                opts
+     * @param {number}  [opts.depth=0.5]  Modulation depth 0–1.
+     * @param {number}  [opts.min]        Override element min.
+     * @param {number}  [opts.max]        Override element max.
+     * @param {number}  [opts.step]       Override element step.
+     * @returns {string|null} Route id, or null if the route was rejected (e.g. self-modulation).
+     */
+    addRoute(sourceId: string, targetType: "element" | "lfo", target: HTMLElement | string, targetParam: string | null, opts?: {
+        depth?: number;
+        min?: number;
+        max?: number;
+        step?: number;
+    }): string | null;
+    /**
+     * Remove a modulation route.
+     * @param {string} routeId
+     */
+    removeRoute(routeId: string): void;
+    /**
+     * Set the depth of an existing route.
+     * @param {string} routeId
+     * @param {number} depth  0–1
+     */
+    setRouteDepth(routeId: string, depth: number): void;
+    /**
+     * Enable or disable a route without removing it.
+     * @param {string}  routeId
+     * @param {boolean} enabled
+     */
+    setRouteEnabled(routeId: string, enabled: boolean): void;
+    /**
+     * Set a parameter on an LFO.
+     * @param {string} lfoId
+     * @param {string} param   'shape'|'rate'|'depth'|'phase'|'offset'|'bipolar'|'baseRate'|'baseDepth'|'jitter'|'skew'
+     * @param {*}      value
+     */
+    setParam(lfoId: string, param: string, value: any): void;
+    /**
+     * Get a parameter from an LFO.
+     * @param {string} lfoId
+     * @param {string} param
+     * @returns {*}
+     */
+    getParam(lfoId: string, param: string): any;
+    /** Get the current output value of an LFO. @param {string} lfoId @returns {number} */
+    getValue(lfoId: string): number;
+    /**
+     * Subscribe to tick notifications. Called each frame for every LFO.
+     * @param {function(lfoId: string, value: number): void} fn
+     * @returns {function} Unsubscribe callback.
+     */
+    subscribe(fn: any): Function;
+    getLFOs(): LFOState[];
+    getLFO(id: any): LFOState;
+    getAllRoutes(): RouteState[];
+    getRoute(id: any): RouteState;
+    getRoutesByElement(element: any): RouteState[];
+    getElementMeta(element: any): ElementState;
+    _initElementState(element: any, opts: any): void;
+    _cleanupElementState(element: any): void;
+    _computeValue(lfo: any, dt: any): any;
+}
+/** Global engine singleton — import and use directly. */
+export const engine: LFOEngine;

package/types/lfo-ui.d.ts

@@ -0,0 +1,147 @@
+export function injectStyles(): void;
+export const LFO_COLORS: string[];
+/**
+ * Floating badge anchored to a connected input element.
+ * Shows depth, allows drag-to-adjust, and a remove button.
+ */
+export class ModIndicator {
+    /**
+     * @param {HTMLElement} element   Connected input.
+     * @param {string}      routeId
+     * @param {string}      lfoId
+     * @param {string}      color
+     * @param {string}      lfoLabel
+     * @param {function}    onRemove  Called when the user removes this connection.
+     */
+    constructor(element: HTMLElement, routeId: string, lfoId: string, color: string, lfoLabel: string, onRemove: Function);
+    _element: HTMLElement;
+    _routeId: string;
+    _lfoId: string;
+    _color: string;
+    _onRemove: Function;
+    _badge: HTMLDivElement;
+    _arcCanvas: HTMLCanvasElement;
+    _rafId: number;
+    _buildBadge(label: any): void;
+    _depthLabel: HTMLSpanElement;
+    _buildArcCanvas(): void;
+    _arcCtx: CanvasRenderingContext2D;
+    _updateDepthLabel(): void;
+    _startPositioning(): void;
+    _reposition(): void;
+    _badgeSize: {
+        bw: number;
+        bh: number;
+    };
+    _updateArc(): void;
+    destroy(): void;
+    get routeId(): string;
+}
+/**
+ * Canvas-based LFO panel with waveform display, shape selector, parameter
+ * sliders, and a drag handle for wiring to any modulation target.
+ */
+export class LFOWidget {
+    /**
+     * @param {HTMLElement} container  Where the widget is appended.
+     * @param {string}      lfoId     Engine LFO id.
+     * @param {object}      [opts]
+     * @param {string}      [opts.color]    Accent color hex.
+     * @param {string}      [opts.label]    Display label.
+     * @param {function}    [opts.onConnect]    (lfoId, element, routeId) => void
+     * @param {function}    [opts.onDisconnect] (routeId) => void
+     */
+    constructor(container: HTMLElement, lfoId: string, opts?: {
+        color?: string;
+        label?: string;
+        onConnect?: Function;
+        onDisconnect?: Function;
+    });
+    _lfoId: string;
+    _color: string;
+    _label: string;
+    _onConnect: Function;
+    _onDisconnect: Function;
+    /** @type {Map<string, ModIndicator>} routeId → indicator */
+    _indicators: Map<string, ModIndicator>;
+    _latestValue: number;
+    _unsub: Function;
+    _rafHandle: number;
+    _destroyed: boolean;
+    _build(container: any): void;
+    _root: HTMLDivElement;
+    _led: HTMLDivElement;
+    _canvas: HTMLCanvasElement;
+    _ctx: CanvasRenderingContext2D;
+    _shapesEl: HTMLDivElement;
+    _bipolarBtn: HTMLButtonElement;
+    _rateInput: HTMLInputElement;
+    _depthInput: HTMLInputElement;
+    _phaseInput: HTMLInputElement;
+    _offsetInput: HTMLInputElement;
+    _jitterInput: HTMLInputElement;
+    _skewInput: HTMLInputElement;
+    _handle: HTMLDivElement;
+    _addParam(container: any, labelText: any, min: any, max: any, defaultVal: any, step: any, param: any, fmt: any, scale?: string): HTMLInputElement;
+    _refreshShapeButtons(): void;
+    _refreshBipolarBtn(): void;
+    /**
+     * Reflect effective (post-chain-modulation) rate and depth onto the param
+     * sliders so they visually track the modulated position.  Only touches the
+     * DOM when the effective value actually differs from the displayed value to
+     * avoid unnecessary repaints.
+     */
+    _syncChainedSliders(): void;
+    /**
+     * Remove any indicators whose routes have been deleted externally — e.g. when
+     * the target LFO is destroyed and engine.destroyLFO cleans up incoming routes.
+     * Called each tick so stale badges are cleared within one frame.
+     */
+    _pruneDeadRoutes(): void;
+    _recordSample(currentValue: any): void;
+    _wfBuf: HTMLCanvasElement;
+    _wfBufCtx: CanvasRenderingContext2D;
+    _wfHistory: Float32Array<ArrayBuffer>;
+    _wfSubpx: any;
+    _wfLastTime: number;
+    _wfPrevValue: any;
+    _wfNeedsFullRedraw: boolean;
+    /** Composite _wfBuf → visible canvas + cursor dot. Called from RAF. */
+    _rafDraw(): void;
+    /** Full repaint of _wfBuf from _wfHistory. */
+    _wfPaintFull(bCtx: any, W: any, H: any): void;
+    /**
+     * Scroll _wfBuf left by intShift, fill background+grid in new strip, then
+     * draw only the new right-edge stroke from _wfHistory.
+     */
+    _wfPaintIncremental(bCtx: any, W: any, H: any, intShift: any): void;
+    _wfDrawGrid(bCtx: any, W: any, H: any, x0: any, x1: any): void;
+    /** Stroke _wfHistory[xFrom..xTo] onto bCtx. */
+    _wfDrawHistoryStroke(bCtx: any, W: any, H: any, xFrom: any, xTo: any): void;
+    _updateLed(value: any): void;
+    _attachDragHandlers(handle: any): void;
+    _connectTo(element: any): void;
+    /**
+     * Programmatically connect this LFO to an element.
+     * @param {HTMLElement} element
+     * @param {object}      [opts]
+     * @param {number}      [opts.depth=0.5]
+     * @returns {string|null} routeId, or null if rejected (duplicate, self-mod).
+     */
+    connect(element: HTMLElement, opts?: {
+        depth?: number;
+    }): string | null;
+    /**
+     * Remove a specific modulation route.
+     * @param {string} routeId
+     */
+    disconnectRoute(routeId: string): void;
+    /** Disconnect all routes from this widget. */
+    disconnectAll(): void;
+    /** Tear down the widget and all its connections. */
+    destroy(): void;
+    get element(): HTMLDivElement;
+    get lfoId(): string;
+    get color(): string;
+    get label(): string;
+}