wavegrid 0.1.1

package/LICENSE

@@ -0,0 +1,7 @@
+All Rights Reserved.
+
+Copyright (c) 2024 Interweb, Inc.
+
+This software and associated documentation files (the "Software") may not be
+reproduced, distributed, or used without express written permission from
+Interweb, Inc.

package/README.md

@@ -0,0 +1,55 @@
+# @wavegrid/receiver
+
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/Illuminate/actions/workflows/ci.yml">
+    <img height="20" src="https://github.com/constructive-io/Illuminate/actions/workflows/ci.yml/badge.svg" />
+  </a>
+</p>
+
+The **brain** of the Illuminate installation. Sits between the control layer (Canvas/Simulator) and the physical hardware (BEYOND/OSC).
+
+## Design Principles
+
+1. **Never jolt** — runs its own independent low-pass filter on all incoming state, so even if a client disconnects mid-transition, the output always flows smoothly
+2. **Always alive** — on signal loss, gracefully falls back to ambient 3D sine wave animations instead of freezing or going dark
+3. **Hardware bridge** — translates HSB grid state into OSC messages for BEYOND (future phase)
+
+## Architecture
+
+```
+Canvas ──ws──▶ Simulator ──ws──▶ Receiver ──osc──▶ BEYOND
+                                    │
+                              own LP filter
+                              sine fallback
+                              health monitor
+```
+
+## Usage
+
+```sh
+pnpm dev:receiver
+# Connects to simulator at ws://localhost:3000
+# Outputs state to console (or OSC when configured)
+```
+
+## Fallback Behavior
+
+When the upstream WebSocket connection drops:
+- The receiver continues running its own tick loop at 60fps
+- Current state smoothly transitions into a 3D sine wave pattern
+- Sine waves sweep through hue/brightness across the 7×7 grid
+- When connection restores, sine wave smoothly blends back to received state
+
+## Configuration
+
+| Env | Default | Description |
+|-----|---------|-------------|
+| `SIMULATOR_URL` | `ws://localhost:3000` | Upstream WebSocket |
+| `RECEIVER_ALPHA` | `0.06` | Low-pass filter smoothing (lower = smoother) |
+| `FALLBACK_DELAY` | `3000` | ms before switching to sine fallback |
+| `OSC_HOST` | — | BEYOND OSC target host (future) |
+| `OSC_PORT` | — | BEYOND OSC target port (future) |

package/adapters.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Adapter interfaces for the Illuminate Receiver.
+ *
+ * The Receiver is a pure state engine — it doesn't know or care where
+ * input comes from or where output goes. These adapters make both sides
+ * pluggable so the module can be published today and connected to any
+ * hardware/protocol later by instantiating the right adapter class.
+ */
+import { EventEmitter } from 'events';
+import { CannonState } from './filter';
+/**
+ * Translates a logical grid index (0–48) to a hardware address string.
+ * Examples:
+ *   (index) => `/beyond/laser/${index + 1}`
+ *   (index) => `dmx/fixture/${index * 3}`
+ */
+export type AddressMapping = (index: number) => string;
+/**
+ * Generic output adapter interface.
+ * Implement this to send filtered grid state to any target:
+ * OSC/BEYOND, DMX, Art-Net, MQTT, HTTP, file, etc.
+ */
+export interface OutputAdapter {
+    /** Called every tick (~60fps) with the full filtered grid state. */
+    send(grid: CannonState[]): void;
+    /** Clean up resources (close sockets, etc). */
+    close(): void;
+}
+/**
+ * Configuration shared by all output adapters that use address mapping.
+ */
+export interface MappedOutputConfig {
+    /** Translate grid index → hardware address. */
+    mapping?: AddressMapping;
+}
+/**
+ * Generic input adapter interface.
+ * Implement this to receive grid state from any source:
+ * WebSocket, MQTT, HTTP polling, serial, etc.
+ *
+ * Emits:
+ *   'state' (grid: CannonState[]) — new state snapshot received
+ *   'connected' — upstream connection established
+ *   'disconnected' — upstream connection lost
+ */
+export interface InputAdapter {
+    /** Start receiving state. */
+    connect(): void;
+    /** Stop receiving and clean up. */
+    disconnect(): void;
+    /** Register event listener. */
+    on(event: 'state', listener: (grid: CannonState[]) => void): this;
+    on(event: 'connected', listener: () => void): this;
+    on(event: 'disconnected', listener: () => void): this;
+    /** Remove event listener. */
+    off(event: string, listener: (...args: unknown[]) => void): this;
+}
+/**
+ * Console output adapter — logs state periodically for dev/debug.
+ * Use this when no hardware is connected.
+ */
+export declare class ConsoleOutput implements OutputAdapter {
+    private frameCount;
+    private logInterval;
+    constructor(opts?: {
+        logEveryNFrames?: number;
+    });
+    send(grid: CannonState[]): void;
+    close(): void;
+}
+/**
+ * Callback output adapter — calls a user-provided function each tick.
+ * Useful for custom integrations, testing, or piping to another system.
+ */
+export declare class CallbackOutput implements OutputAdapter {
+    private fn;
+    constructor(fn: (grid: CannonState[]) => void);
+    send(grid: CannonState[]): void;
+    close(): void;
+}
+/**
+ * Multi-output adapter — fans out to multiple output adapters.
+ * Use this to send to both console and hardware simultaneously.
+ *
+ * Example:
+ *   new MultiOutput([new ConsoleOutput(), new BeyondOscOutput(config)])
+ */
+export declare class MultiOutput implements OutputAdapter {
+    private outputs;
+    constructor(outputs: OutputAdapter[]);
+    send(grid: CannonState[]): void;
+    close(): void;
+}
+/**
+ * WebSocket input adapter — connects to an upstream server and
+ * receives state snapshots as JSON messages.
+ *
+ * Expected message format: { type: "state", grid: CannonState[] }
+ * This is what the Illuminate simulator broadcasts.
+ */
+export declare class WebSocketInput extends EventEmitter implements InputAdapter {
+    private url;
+    private ws;
+    private reconnectTimer;
+    private reconnectInterval;
+    private _connected;
+    private _running;
+    constructor(opts: {
+        url: string;
+        reconnectInterval?: number;
+    });
+    get connected(): boolean;
+    connect(): void;
+    disconnect(): void;
+    private doConnect;
+    private scheduleReconnect;
+}
+/**
+ * WebSocket server output adapter — broadcasts filtered state to
+ * all connected downstream clients.
+ *
+ * Use this to relay the receiver's output to other systems, UIs,
+ * or a chain of downstream receivers.
+ */
+export declare class WebSocketOutput implements OutputAdapter {
+    private wss;
+    private port;
+    private mapping;
+    private broadcastInterval;
+    private frameCount;
+    constructor(opts: {
+        port: number;
+        mapping?: AddressMapping;
+        broadcastEveryNFrames?: number;
+    });
+    /** Start the WebSocket server. Call this before the receiver starts ticking. */
+    listen(): void;
+    send(grid: CannonState[]): void;
+    close(): void;
+}

package/adapters.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * Adapter interfaces for the Illuminate Receiver.
+ *
+ * The Receiver is a pure state engine — it doesn't know or care where
+ * input comes from or where output goes. These adapters make both sides
+ * pluggable so the module can be published today and connected to any
+ * hardware/protocol later by instantiating the right adapter class.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketOutput = exports.WebSocketInput = exports.MultiOutput = exports.CallbackOutput = exports.ConsoleOutput = void 0;
+const events_1 = require("events");
+// ═══════════════════════════════════════════════════
+// Built-in Output Adapters
+// ═══════════════════════════════════════════════════
+/**
+ * Console output adapter — logs state periodically for dev/debug.
+ * Use this when no hardware is connected.
+ */
+class ConsoleOutput {
+    frameCount = 0;
+    logInterval;
+    constructor(opts = {}) {
+        this.logInterval = opts.logEveryNFrames ?? 60;
+    }
+    send(grid) {
+        this.frameCount++;
+        if (this.frameCount % this.logInterval === 0) {
+            const sample = grid[0];
+            process.stdout.write(`\r  ◈ frame ${this.frameCount}  sample[0]: h=${sample.h.toFixed(1)} s=${sample.s.toFixed(1)} b=${sample.b.toFixed(1)}  `);
+        }
+    }
+    close() {
+        console.log('\n  ◈ Console output closed');
+    }
+}
+exports.ConsoleOutput = ConsoleOutput;
+/**
+ * Callback output adapter — calls a user-provided function each tick.
+ * Useful for custom integrations, testing, or piping to another system.
+ */
+class CallbackOutput {
+    fn;
+    constructor(fn) {
+        this.fn = fn;
+    }
+    send(grid) {
+        this.fn(grid);
+    }
+    close() {
+        // nothing to clean up
+    }
+}
+exports.CallbackOutput = CallbackOutput;
+/**
+ * Multi-output adapter — fans out to multiple output adapters.
+ * Use this to send to both console and hardware simultaneously.
+ *
+ * Example:
+ *   new MultiOutput([new ConsoleOutput(), new BeyondOscOutput(config)])
+ */
+class MultiOutput {
+    outputs;
+    constructor(outputs) {
+        this.outputs = outputs;
+    }
+    send(grid) {
+        for (const out of this.outputs) {
+            out.send(grid);
+        }
+    }
+    close() {
+        for (const out of this.outputs) {
+            out.close();
+        }
+    }
+}
+exports.MultiOutput = MultiOutput;
+// ═══════════════════════════════════════════════════
+// Built-in Input Adapters
+// ═══════════════════════════════════════════════════
+/**
+ * WebSocket input adapter — connects to an upstream server and
+ * receives state snapshots as JSON messages.
+ *
+ * Expected message format: { type: "state", grid: CannonState[] }
+ * This is what the Illuminate simulator broadcasts.
+ */
+class WebSocketInput extends events_1.EventEmitter {
+    url;
+    ws = null;
+    reconnectTimer = null;
+    reconnectInterval;
+    _connected = false;
+    _running = false;
+    constructor(opts) {
+        super();
+        this.url = opts.url;
+        this.reconnectInterval = opts.reconnectInterval ?? 2000;
+    }
+    get connected() { return this._connected; }
+    connect() {
+        if (this._running)
+            return;
+        this._running = true;
+        this.doConnect();
+    }
+    disconnect() {
+        this._running = false;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+        this._connected = false;
+    }
+    doConnect() {
+        // Dynamic import to avoid issues in environments without ws
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { WebSocket } = require('ws');
+        try {
+            this.ws = new WebSocket(this.url);
+            this.ws.on('open', () => {
+                this._connected = true;
+                this.emit('connected');
+            });
+            this.ws.on('message', (raw) => {
+                try {
+                    const msg = JSON.parse(raw.toString());
+                    if (msg.type === 'state' && Array.isArray(msg.grid)) {
+                        this.emit('state', msg.grid);
+                    }
+                }
+                catch (_e) {
+                    // ignore malformed messages
+                }
+            });
+            this.ws.on('close', () => {
+                this._connected = false;
+                this.emit('disconnected');
+                this.scheduleReconnect();
+            });
+            this.ws.on('error', () => {
+                this.scheduleReconnect();
+            });
+        }
+        catch (_e) {
+            this.scheduleReconnect();
+        }
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer || !this._running)
+            return;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            if (this._running)
+                this.doConnect();
+        }, this.reconnectInterval);
+    }
+}
+exports.WebSocketInput = WebSocketInput;
+// ═══════════════════════════════════════════════════
+// WebSocket Output Adapter
+// ═══════════════════════════════════════════════════
+/**
+ * WebSocket server output adapter — broadcasts filtered state to
+ * all connected downstream clients.
+ *
+ * Use this to relay the receiver's output to other systems, UIs,
+ * or a chain of downstream receivers.
+ */
+class WebSocketOutput {
+    wss = null;
+    port;
+    mapping;
+    broadcastInterval;
+    frameCount = 0;
+    constructor(opts) {
+        this.port = opts.port;
+        this.mapping = opts.mapping ?? null;
+        this.broadcastInterval = opts.broadcastEveryNFrames ?? 1;
+    }
+    /** Start the WebSocket server. Call this before the receiver starts ticking. */
+    listen() {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { WebSocketServer } = require('ws');
+        this.wss = new WebSocketServer({ port: this.port });
+        console.log(`  \u25C8 WebSocket output listening on :${this.port}`);
+    }
+    send(grid) {
+        if (!this.wss)
+            return;
+        this.frameCount++;
+        if (this.frameCount % this.broadcastInterval !== 0)
+            return;
+        const payload = this.mapping
+            ? JSON.stringify({ type: 'state', grid, mapping: grid.map((_, i) => this.mapping(i)) })
+            : JSON.stringify({ type: 'state', grid });
+        for (const client of this.wss.clients) {
+            if (client.readyState === 1) {
+                client.send(payload);
+            }
+        }
+    }
+    close() {
+        if (this.wss) {
+            this.wss.close();
+            this.wss = null;
+            console.log(`  \u25C8 WebSocket output closed`);
+        }
+    }
+}
+exports.WebSocketOutput = WebSocketOutput;

package/esm/adapters.js

@@ -0,0 +1,208 @@
+/**
+ * Adapter interfaces for the Illuminate Receiver.
+ *
+ * The Receiver is a pure state engine — it doesn't know or care where
+ * input comes from or where output goes. These adapters make both sides
+ * pluggable so the module can be published today and connected to any
+ * hardware/protocol later by instantiating the right adapter class.
+ */
+import { EventEmitter } from 'events';
+// ═══════════════════════════════════════════════════
+// Built-in Output Adapters
+// ═══════════════════════════════════════════════════
+/**
+ * Console output adapter — logs state periodically for dev/debug.
+ * Use this when no hardware is connected.
+ */
+export class ConsoleOutput {
+    frameCount = 0;
+    logInterval;
+    constructor(opts = {}) {
+        this.logInterval = opts.logEveryNFrames ?? 60;
+    }
+    send(grid) {
+        this.frameCount++;
+        if (this.frameCount % this.logInterval === 0) {
+            const sample = grid[0];
+            process.stdout.write(`\r  ◈ frame ${this.frameCount}  sample[0]: h=${sample.h.toFixed(1)} s=${sample.s.toFixed(1)} b=${sample.b.toFixed(1)}  `);
+        }
+    }
+    close() {
+        console.log('\n  ◈ Console output closed');
+    }
+}
+/**
+ * Callback output adapter — calls a user-provided function each tick.
+ * Useful for custom integrations, testing, or piping to another system.
+ */
+export class CallbackOutput {
+    fn;
+    constructor(fn) {
+        this.fn = fn;
+    }
+    send(grid) {
+        this.fn(grid);
+    }
+    close() {
+        // nothing to clean up
+    }
+}
+/**
+ * Multi-output adapter — fans out to multiple output adapters.
+ * Use this to send to both console and hardware simultaneously.
+ *
+ * Example:
+ *   new MultiOutput([new ConsoleOutput(), new BeyondOscOutput(config)])
+ */
+export class MultiOutput {
+    outputs;
+    constructor(outputs) {
+        this.outputs = outputs;
+    }
+    send(grid) {
+        for (const out of this.outputs) {
+            out.send(grid);
+        }
+    }
+    close() {
+        for (const out of this.outputs) {
+            out.close();
+        }
+    }
+}
+// ═══════════════════════════════════════════════════
+// Built-in Input Adapters
+// ═══════════════════════════════════════════════════
+/**
+ * WebSocket input adapter — connects to an upstream server and
+ * receives state snapshots as JSON messages.
+ *
+ * Expected message format: { type: "state", grid: CannonState[] }
+ * This is what the Illuminate simulator broadcasts.
+ */
+export class WebSocketInput extends EventEmitter {
+    url;
+    ws = null;
+    reconnectTimer = null;
+    reconnectInterval;
+    _connected = false;
+    _running = false;
+    constructor(opts) {
+        super();
+        this.url = opts.url;
+        this.reconnectInterval = opts.reconnectInterval ?? 2000;
+    }
+    get connected() { return this._connected; }
+    connect() {
+        if (this._running)
+            return;
+        this._running = true;
+        this.doConnect();
+    }
+    disconnect() {
+        this._running = false;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+        this._connected = false;
+    }
+    doConnect() {
+        // Dynamic import to avoid issues in environments without ws
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { WebSocket } = require('ws');
+        try {
+            this.ws = new WebSocket(this.url);
+            this.ws.on('open', () => {
+                this._connected = true;
+                this.emit('connected');
+            });
+            this.ws.on('message', (raw) => {
+                try {
+                    const msg = JSON.parse(raw.toString());
+                    if (msg.type === 'state' && Array.isArray(msg.grid)) {
+                        this.emit('state', msg.grid);
+                    }
+                }
+                catch (_e) {
+                    // ignore malformed messages
+                }
+            });
+            this.ws.on('close', () => {
+                this._connected = false;
+                this.emit('disconnected');
+                this.scheduleReconnect();
+            });
+            this.ws.on('error', () => {
+                this.scheduleReconnect();
+            });
+        }
+        catch (_e) {
+            this.scheduleReconnect();
+        }
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer || !this._running)
+            return;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            if (this._running)
+                this.doConnect();
+        }, this.reconnectInterval);
+    }
+}
+// ═══════════════════════════════════════════════════
+// WebSocket Output Adapter
+// ═══════════════════════════════════════════════════
+/**
+ * WebSocket server output adapter — broadcasts filtered state to
+ * all connected downstream clients.
+ *
+ * Use this to relay the receiver's output to other systems, UIs,
+ * or a chain of downstream receivers.
+ */
+export class WebSocketOutput {
+    wss = null;
+    port;
+    mapping;
+    broadcastInterval;
+    frameCount = 0;
+    constructor(opts) {
+        this.port = opts.port;
+        this.mapping = opts.mapping ?? null;
+        this.broadcastInterval = opts.broadcastEveryNFrames ?? 1;
+    }
+    /** Start the WebSocket server. Call this before the receiver starts ticking. */
+    listen() {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { WebSocketServer } = require('ws');
+        this.wss = new WebSocketServer({ port: this.port });
+        console.log(`  \u25C8 WebSocket output listening on :${this.port}`);
+    }
+    send(grid) {
+        if (!this.wss)
+            return;
+        this.frameCount++;
+        if (this.frameCount % this.broadcastInterval !== 0)
+            return;
+        const payload = this.mapping
+            ? JSON.stringify({ type: 'state', grid, mapping: grid.map((_, i) => this.mapping(i)) })
+            : JSON.stringify({ type: 'state', grid });
+        for (const client of this.wss.clients) {
+            if (client.readyState === 1) {
+                client.send(payload);
+            }
+        }
+    }
+    close() {
+        if (this.wss) {
+            this.wss.close();
+            this.wss = null;
+            console.log(`  \u25C8 WebSocket output closed`);
+        }
+    }
+}

package/esm/fallback.js

@@ -0,0 +1,55 @@
+/**
+ * 3D sine wave fallback animations.
+ *
+ * When the upstream signal is lost, the receiver doesn't freeze or go dark.
+ * Instead it smoothly transitions into ambient sine wave patterns that sweep
+ * across the 7×7 grid in three dimensions (hue, brightness, and time).
+ *
+ * The waves create organic, slowly evolving color movement — like the
+ * installation is breathing on its own.
+ */
+import { GRID_SIZE, NUM_CANNONS } from './filter';
+export const DEFAULT_FALLBACK_CONFIG = {
+    baseHue: 220,
+    hueSpread: 60,
+    brightnessMin: 30,
+    brightnessMax: 85,
+    spatialFreq: 0.8,
+    timeFreq: 0.015,
+    timeFreq2: 0.009
+};
+/**
+ * Compute one frame of the 3D sine wave fallback and write targets
+ * into the filtered grid. The receiver's low-pass filter then smoothly
+ * converges the output to these targets.
+ *
+ * Three overlapping sine waves create organic movement:
+ *   1. Primary wave sweeps diagonally across the grid (hue)
+ *   2. Secondary wave moves perpendicular (brightness)
+ *   3. Tertiary slow wave modulates saturation for depth
+ */
+export function computeFallbackFrame(grid, tick, config = DEFAULT_FALLBACK_CONFIG) {
+    const { baseHue, hueSpread, brightnessMin, brightnessMax, spatialFreq, timeFreq, timeFreq2 } = config;
+    const brightRange = brightnessMax - brightnessMin;
+    for (let i = 0; i < NUM_CANNONS; i++) {
+        const row = Math.floor(i / GRID_SIZE);
+        const col = i % GRID_SIZE;
+        // Normalize to -1..1
+        const nx = (col / (GRID_SIZE - 1)) * 2 - 1;
+        const ny = (row / (GRID_SIZE - 1)) * 2 - 1;
+        // Primary diagonal wave → hue
+        const wave1 = Math.sin((nx + ny) * spatialFreq * Math.PI + tick * timeFreq);
+        // Secondary perpendicular wave → brightness
+        const wave2 = Math.sin((nx - ny) * spatialFreq * Math.PI * 0.7 + tick * timeFreq2);
+        // Tertiary slow radial wave → saturation depth
+        const dist = Math.sqrt(nx * nx + ny * ny);
+        const wave3 = Math.sin(dist * Math.PI + tick * timeFreq * 0.4);
+        // Map to HSB
+        const h = (baseHue + wave1 * hueSpread + 360) % 360;
+        const s = 70 + wave3 * 20; // 50–90 range
+        const b = brightnessMin + ((wave2 + 1) / 2) * brightRange;
+        grid[i].targetH = h;
+        grid[i].targetS = Math.max(0, Math.min(100, s));
+        grid[i].targetB = Math.max(0, Math.min(100, b));
+    }
+}