wavegrid 0.1.1

package/esm/filter.js

@@ -0,0 +1,62 @@
+/**
+ * Independent low-pass filter for the receiver.
+ *
+ * This is separate from the simulator's filter — the receiver runs its own
+ * smoothing so that even if the upstream connection drops mid-transition,
+ * the output to hardware never jolts.
+ */
+export const NUM_CANNONS = 49;
+export const GRID_SIZE = 7;
+export const DEFAULT_RECEIVER_ALPHA = 0.06;
+export function createFilteredGrid() {
+    return Array.from({ length: NUM_CANNONS }, () => ({
+        h: 220,
+        s: 90,
+        b: 80,
+        targetH: 220,
+        targetS: 90,
+        targetB: 80
+    }));
+}
+/**
+ * Shortest angular distance on the hue circle.
+ */
+export function angleDelta(from, to) {
+    return ((to - from + 540) % 360) - 180;
+}
+/**
+ * Single tick of exponential low-pass interpolation.
+ * Returns true if any cannon changed (i.e., output is still settling).
+ */
+export function tickFilter(grid, alpha = DEFAULT_RECEIVER_ALPHA) {
+    let changed = false;
+    for (let i = 0; i < grid.length; i++) {
+        const c = grid[i];
+        const dh = angleDelta(c.h, c.targetH);
+        const ds = c.targetS - c.s;
+        const db = c.targetB - c.b;
+        if (Math.abs(dh) > 0.3 || Math.abs(ds) > 0.3 || Math.abs(db) > 0.3) {
+            c.h = (c.h + dh * alpha + 360) % 360;
+            c.s = c.s + ds * alpha;
+            c.b = c.b + db * alpha;
+            changed = true;
+        }
+        else {
+            c.h = c.targetH;
+            c.s = c.targetS;
+            c.b = c.targetB;
+        }
+    }
+    return changed;
+}
+/**
+ * Set the target state for all cannons from an upstream state snapshot.
+ * The filter will smoothly converge to these values.
+ */
+export function applyUpstreamState(grid, upstream) {
+    for (let i = 0; i < Math.min(grid.length, upstream.length); i++) {
+        grid[i].targetH = upstream[i].h;
+        grid[i].targetS = upstream[i].s;
+        grid[i].targetB = upstream[i].b;
+    }
+}

package/esm/index.js

@@ -0,0 +1,4 @@
+export { CallbackOutput, ConsoleOutput, MultiOutput, WebSocketInput, WebSocketOutput } from './adapters';
+export { angleDelta, applyUpstreamState, createFilteredGrid, DEFAULT_RECEIVER_ALPHA, tickFilter } from './filter';
+export { computeFallbackFrame, DEFAULT_FALLBACK_CONFIG } from './fallback';
+export { Receiver } from './receiver';

package/esm/main.js

@@ -0,0 +1,51 @@
+/**
+ * Receiver entry point.
+ *
+ * Demonstrates the adapter pattern — configure input and output
+ * adapters via environment variables, then start the receiver.
+ */
+import { ConsoleOutput, MultiOutput, WebSocketInput, WebSocketOutput } from './adapters';
+import { Receiver } from './receiver';
+const SIMULATOR_URL = process.env.SIMULATOR_URL || 'ws://localhost:3000';
+const ALPHA = parseFloat(process.env.RECEIVER_ALPHA || '0.06');
+const FALLBACK_DELAY = parseInt(process.env.FALLBACK_DELAY || '3000', 10);
+const WS_OUTPUT_PORT = process.env.WS_OUTPUT_PORT ? parseInt(process.env.WS_OUTPUT_PORT, 10) : undefined;
+// ─── Input adapter ───
+const input = new WebSocketInput({ url: SIMULATOR_URL });
+// ─── Output adapter(s) ───
+const outputs = [new ConsoleOutput()];
+let wsOutput = null;
+if (WS_OUTPUT_PORT) {
+    wsOutput = new WebSocketOutput({ port: WS_OUTPUT_PORT });
+    wsOutput.listen();
+    outputs.push(wsOutput);
+}
+const output = outputs.length === 1 ? outputs[0] : new MultiOutput(outputs);
+// ─── Receiver ───
+const receiver = new Receiver({
+    input,
+    output,
+    alpha: ALPHA,
+    fallbackDelay: FALLBACK_DELAY
+});
+console.log('');
+console.log('  \u256D\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E');
+console.log('  \u2502   Illuminate \u00B7 Receiver               \u2502');
+console.log('  \u2502   the brain                           \u2502');
+console.log('  \u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F');
+console.log('');
+console.log(`  \u2192 Input:  WebSocket @ ${SIMULATOR_URL}`);
+console.log(`  \u2192 Output: Console${wsOutput ? ` + WebSocket :${WS_OUTPUT_PORT}` : ''}`);
+console.log(`  \u2192 Alpha: ${ALPHA}  Fallback delay: ${FALLBACK_DELAY}ms`);
+console.log('');
+receiver.start();
+// Graceful shutdown
+process.on('SIGINT', () => {
+    console.log('\n\n  Shutting down...');
+    receiver.stop();
+    process.exit(0);
+});
+process.on('SIGTERM', () => {
+    receiver.stop();
+    process.exit(0);
+});

package/esm/receiver.js

@@ -0,0 +1,110 @@
+/**
+ * The Receiver — the brain of the Illuminate installation.
+ *
+ * A pure state engine that:
+ *   1. Receives grid state from an InputAdapter (upstream source)
+ *   2. Runs an independent low-pass filter (smooth, never jolts)
+ *   3. Falls back to 3D sine waves on signal loss
+ *   4. Sends filtered output to an OutputAdapter (hardware target)
+ *
+ * Both input and output are pluggable adapters — swap them to connect
+ * to any protocol or hardware without modifying the receiver core.
+ */
+import { ConsoleOutput, WebSocketInput } from './adapters';
+import { computeFallbackFrame, DEFAULT_FALLBACK_CONFIG } from './fallback';
+import { applyUpstreamState, createFilteredGrid, DEFAULT_RECEIVER_ALPHA, tickFilter } from './filter';
+export const DEFAULT_RECEIVER_CONFIG = {
+    input: new WebSocketInput({ url: 'ws://localhost:3000' }),
+    output: new ConsoleOutput(),
+    alpha: DEFAULT_RECEIVER_ALPHA,
+    fallbackDelay: 3000,
+    fallback: DEFAULT_FALLBACK_CONFIG,
+    tickMs: 1000 / 60
+};
+export class Receiver {
+    config;
+    grid;
+    tickTimer = null;
+    tick = 0;
+    lastDataAt = Date.now();
+    _status = 'reconnecting';
+    _fallbackActive = false;
+    _running = false;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_RECEIVER_CONFIG, ...config };
+        this.grid = createFilteredGrid();
+    }
+    get status() { return this._status; }
+    get fallbackActive() { return this._fallbackActive; }
+    /** Get the current output state (after filtering). */
+    getOutputState() {
+        return this.grid.map(c => ({
+            h: c.h,
+            s: c.s,
+            b: c.b
+        }));
+    }
+    /** Start the receiver — connects input and begins the tick loop. */
+    start() {
+        if (this._running)
+            return;
+        this._running = true;
+        this.bindInput();
+        this.startTickLoop();
+        console.log('  \u25C8 Receiver started');
+    }
+    /** Stop the receiver — disconnects and stops the tick loop. */
+    stop() {
+        this._running = false;
+        if (this.tickTimer) {
+            clearInterval(this.tickTimer);
+            this.tickTimer = null;
+        }
+        this.config.input.disconnect();
+        this.config.output.close();
+        console.log('  \u25C8 Receiver stopped');
+    }
+    bindInput() {
+        const input = this.config.input;
+        input.on('connected', () => {
+            this._status = 'connected';
+            this.lastDataAt = Date.now();
+            console.log('  \u25C8 Input connected');
+        });
+        input.on('state', (upstream) => {
+            this.lastDataAt = Date.now();
+            applyUpstreamState(this.grid, upstream);
+            if (this._fallbackActive) {
+                console.log('\n  \u25C8 Signal restored \u2014 blending back from fallback');
+                this._fallbackActive = false;
+            }
+        });
+        input.on('disconnected', () => {
+            this._status = 'reconnecting';
+            console.log('\n  \u25C8 Input disconnected');
+        });
+        input.connect();
+    }
+    startTickLoop() {
+        this.tickTimer = setInterval(() => {
+            this.tick++;
+            const now = Date.now();
+            const timeSinceData = now - this.lastDataAt;
+            // Check if we should switch to fallback
+            if (timeSinceData > this.config.fallbackDelay && !this._fallbackActive) {
+                this._fallbackActive = true;
+                this._status = 'fallback';
+                console.log('\n  \u25C8 Signal lost \u2014 entering sine wave fallback');
+            }
+            // If fallback is active, compute sine wave targets
+            if (this._fallbackActive) {
+                computeFallbackFrame(this.grid, this.tick, this.config.fallback);
+            }
+            // Always tick the low-pass filter — this ensures smooth output
+            // whether receiving data, transitioning to fallback, or in fallback
+            tickFilter(this.grid, this.config.alpha);
+            // Send filtered output to the output adapter
+            this.config.output.send(this.getOutputState());
+        }, this.config.tickMs);
+    }
+}

package/fallback.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 { FilteredCannon } from './filter';
+export interface FallbackConfig {
+    /** Base hue center for the wave (0–360). Default 220 (civic blue). */
+    baseHue: number;
+    /** Hue spread of the wave. Default 60. */
+    hueSpread: number;
+    /** Brightness min. Default 30. */
+    brightnessMin: number;
+    /** Brightness max. Default 85. */
+    brightnessMax: number;
+    /** Spatial frequency for the wave across the grid. Default 0.8. */
+    spatialFreq: number;
+    /** Time frequency — how fast the wave moves (radians per tick). Default 0.015. */
+    timeFreq: number;
+    /** Secondary wave time frequency for depth. Default 0.009. */
+    timeFreq2: number;
+}
+export declare const DEFAULT_FALLBACK_CONFIG: FallbackConfig;
+/**
+ * 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 declare function computeFallbackFrame(grid: FilteredCannon[], tick: number, config?: FallbackConfig): void;

package/fallback.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_FALLBACK_CONFIG = void 0;
+exports.computeFallbackFrame = computeFallbackFrame;
+const filter_1 = require("./filter");
+exports.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
+ */
+function computeFallbackFrame(grid, tick, config = exports.DEFAULT_FALLBACK_CONFIG) {
+    const { baseHue, hueSpread, brightnessMin, brightnessMax, spatialFreq, timeFreq, timeFreq2 } = config;
+    const brightRange = brightnessMax - brightnessMin;
+    for (let i = 0; i < filter_1.NUM_CANNONS; i++) {
+        const row = Math.floor(i / filter_1.GRID_SIZE);
+        const col = i % filter_1.GRID_SIZE;
+        // Normalize to -1..1
+        const nx = (col / (filter_1.GRID_SIZE - 1)) * 2 - 1;
+        const ny = (row / (filter_1.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));
+    }
+}

package/filter.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Independent low-pass filter for the receiver.
+ *
+ * This is separate from the simulator's filter — the receiver runs its own
+ * smoothing so that even if the upstream connection drops mid-transition,
+ * the output to hardware never jolts.
+ */
+export interface CannonState {
+    h: number;
+    s: number;
+    b: number;
+}
+export interface FilteredCannon extends CannonState {
+    targetH: number;
+    targetS: number;
+    targetB: number;
+}
+export declare const NUM_CANNONS = 49;
+export declare const GRID_SIZE = 7;
+export declare const DEFAULT_RECEIVER_ALPHA = 0.06;
+export declare function createFilteredGrid(): FilteredCannon[];
+/**
+ * Shortest angular distance on the hue circle.
+ */
+export declare function angleDelta(from: number, to: number): number;
+/**
+ * Single tick of exponential low-pass interpolation.
+ * Returns true if any cannon changed (i.e., output is still settling).
+ */
+export declare function tickFilter(grid: FilteredCannon[], alpha?: number): boolean;
+/**
+ * Set the target state for all cannons from an upstream state snapshot.
+ * The filter will smoothly converge to these values.
+ */
+export declare function applyUpstreamState(grid: FilteredCannon[], upstream: CannonState[]): void;

package/filter.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Independent low-pass filter for the receiver.
+ *
+ * This is separate from the simulator's filter — the receiver runs its own
+ * smoothing so that even if the upstream connection drops mid-transition,
+ * the output to hardware never jolts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RECEIVER_ALPHA = exports.GRID_SIZE = exports.NUM_CANNONS = void 0;
+exports.createFilteredGrid = createFilteredGrid;
+exports.angleDelta = angleDelta;
+exports.tickFilter = tickFilter;
+exports.applyUpstreamState = applyUpstreamState;
+exports.NUM_CANNONS = 49;
+exports.GRID_SIZE = 7;
+exports.DEFAULT_RECEIVER_ALPHA = 0.06;
+function createFilteredGrid() {
+    return Array.from({ length: exports.NUM_CANNONS }, () => ({
+        h: 220,
+        s: 90,
+        b: 80,
+        targetH: 220,
+        targetS: 90,
+        targetB: 80
+    }));
+}
+/**
+ * Shortest angular distance on the hue circle.
+ */
+function angleDelta(from, to) {
+    return ((to - from + 540) % 360) - 180;
+}
+/**
+ * Single tick of exponential low-pass interpolation.
+ * Returns true if any cannon changed (i.e., output is still settling).
+ */
+function tickFilter(grid, alpha = exports.DEFAULT_RECEIVER_ALPHA) {
+    let changed = false;
+    for (let i = 0; i < grid.length; i++) {
+        const c = grid[i];
+        const dh = angleDelta(c.h, c.targetH);
+        const ds = c.targetS - c.s;
+        const db = c.targetB - c.b;
+        if (Math.abs(dh) > 0.3 || Math.abs(ds) > 0.3 || Math.abs(db) > 0.3) {
+            c.h = (c.h + dh * alpha + 360) % 360;
+            c.s = c.s + ds * alpha;
+            c.b = c.b + db * alpha;
+            changed = true;
+        }
+        else {
+            c.h = c.targetH;
+            c.s = c.targetS;
+            c.b = c.targetB;
+        }
+    }
+    return changed;
+}
+/**
+ * Set the target state for all cannons from an upstream state snapshot.
+ * The filter will smoothly converge to these values.
+ */
+function applyUpstreamState(grid, upstream) {
+    for (let i = 0; i < Math.min(grid.length, upstream.length); i++) {
+        grid[i].targetH = upstream[i].h;
+        grid[i].targetS = upstream[i].s;
+        grid[i].targetB = upstream[i].b;
+    }
+}

package/index.d.ts

@@ -0,0 +1,8 @@
+export type { AddressMapping, InputAdapter, MappedOutputConfig, OutputAdapter } from './adapters';
+export { CallbackOutput, ConsoleOutput, MultiOutput, WebSocketInput, WebSocketOutput } from './adapters';
+export type { CannonState, FilteredCannon } from './filter';
+export { angleDelta, applyUpstreamState, createFilteredGrid, DEFAULT_RECEIVER_ALPHA, tickFilter } from './filter';
+export type { FallbackConfig } from './fallback';
+export { computeFallbackFrame, DEFAULT_FALLBACK_CONFIG } from './fallback';
+export type { ReceiverConfig, ReceiverState, ReceiverStatus } from './receiver';
+export { Receiver } from './receiver';

package/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Receiver = exports.DEFAULT_FALLBACK_CONFIG = exports.computeFallbackFrame = exports.tickFilter = exports.DEFAULT_RECEIVER_ALPHA = exports.createFilteredGrid = exports.applyUpstreamState = exports.angleDelta = exports.WebSocketOutput = exports.WebSocketInput = exports.MultiOutput = exports.ConsoleOutput = exports.CallbackOutput = void 0;
+var adapters_1 = require("./adapters");
+Object.defineProperty(exports, "CallbackOutput", { enumerable: true, get: function () { return adapters_1.CallbackOutput; } });
+Object.defineProperty(exports, "ConsoleOutput", { enumerable: true, get: function () { return adapters_1.ConsoleOutput; } });
+Object.defineProperty(exports, "MultiOutput", { enumerable: true, get: function () { return adapters_1.MultiOutput; } });
+Object.defineProperty(exports, "WebSocketInput", { enumerable: true, get: function () { return adapters_1.WebSocketInput; } });
+Object.defineProperty(exports, "WebSocketOutput", { enumerable: true, get: function () { return adapters_1.WebSocketOutput; } });
+var filter_1 = require("./filter");
+Object.defineProperty(exports, "angleDelta", { enumerable: true, get: function () { return filter_1.angleDelta; } });
+Object.defineProperty(exports, "applyUpstreamState", { enumerable: true, get: function () { return filter_1.applyUpstreamState; } });
+Object.defineProperty(exports, "createFilteredGrid", { enumerable: true, get: function () { return filter_1.createFilteredGrid; } });
+Object.defineProperty(exports, "DEFAULT_RECEIVER_ALPHA", { enumerable: true, get: function () { return filter_1.DEFAULT_RECEIVER_ALPHA; } });
+Object.defineProperty(exports, "tickFilter", { enumerable: true, get: function () { return filter_1.tickFilter; } });
+var fallback_1 = require("./fallback");
+Object.defineProperty(exports, "computeFallbackFrame", { enumerable: true, get: function () { return fallback_1.computeFallbackFrame; } });
+Object.defineProperty(exports, "DEFAULT_FALLBACK_CONFIG", { enumerable: true, get: function () { return fallback_1.DEFAULT_FALLBACK_CONFIG; } });
+var receiver_1 = require("./receiver");
+Object.defineProperty(exports, "Receiver", { enumerable: true, get: function () { return receiver_1.Receiver; } });

package/main.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Receiver entry point.
+ *
+ * Demonstrates the adapter pattern — configure input and output
+ * adapters via environment variables, then start the receiver.
+ */
+export {};

package/main.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Receiver entry point.
+ *
+ * Demonstrates the adapter pattern — configure input and output
+ * adapters via environment variables, then start the receiver.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const adapters_1 = require("./adapters");
+const receiver_1 = require("./receiver");
+const SIMULATOR_URL = process.env.SIMULATOR_URL || 'ws://localhost:3000';
+const ALPHA = parseFloat(process.env.RECEIVER_ALPHA || '0.06');
+const FALLBACK_DELAY = parseInt(process.env.FALLBACK_DELAY || '3000', 10);
+const WS_OUTPUT_PORT = process.env.WS_OUTPUT_PORT ? parseInt(process.env.WS_OUTPUT_PORT, 10) : undefined;
+// ─── Input adapter ───
+const input = new adapters_1.WebSocketInput({ url: SIMULATOR_URL });
+// ─── Output adapter(s) ───
+const outputs = [new adapters_1.ConsoleOutput()];
+let wsOutput = null;
+if (WS_OUTPUT_PORT) {
+    wsOutput = new adapters_1.WebSocketOutput({ port: WS_OUTPUT_PORT });
+    wsOutput.listen();
+    outputs.push(wsOutput);
+}
+const output = outputs.length === 1 ? outputs[0] : new adapters_1.MultiOutput(outputs);
+// ─── Receiver ───
+const receiver = new receiver_1.Receiver({
+    input,
+    output,
+    alpha: ALPHA,
+    fallbackDelay: FALLBACK_DELAY
+});
+console.log('');
+console.log('  \u256D\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E');
+console.log('  \u2502   Illuminate \u00B7 Receiver               \u2502');
+console.log('  \u2502   the brain                           \u2502');
+console.log('  \u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F');
+console.log('');
+console.log(`  \u2192 Input:  WebSocket @ ${SIMULATOR_URL}`);
+console.log(`  \u2192 Output: Console${wsOutput ? ` + WebSocket :${WS_OUTPUT_PORT}` : ''}`);
+console.log(`  \u2192 Alpha: ${ALPHA}  Fallback delay: ${FALLBACK_DELAY}ms`);
+console.log('');
+receiver.start();
+// Graceful shutdown
+process.on('SIGINT', () => {
+    console.log('\n\n  Shutting down...');
+    receiver.stop();
+    process.exit(0);
+});
+process.on('SIGTERM', () => {
+    receiver.stop();
+    process.exit(0);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "wavegrid",
+  "version": "0.1.1",
+  "author": "Dan Lynch <pyramation@gmail.com>",
+  "description": "Receiver brain — resilient state engine with independent low-pass filter, 3D sine wave fallback, and OSC bridge",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/Illuminate",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/Illuminate"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/Illuminate/issues"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "ESLINT_USE_FLAT_CONFIG=false eslint src --fix",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch",
+    "dev": "ts-node src/main.ts"
+  },
+  "keywords": [
+    "laser",
+    "osc",
+    "receiver",
+    "brain",
+    "7x7"
+  ],
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.13",
+    "makage": "^0.3.0"
+  },
+  "gitHead": "6f651b8d0dfbb6538c667dd3905ce6989ae18e46"
+}

package/receiver.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The Receiver — the brain of the Illuminate installation.
+ *
+ * A pure state engine that:
+ *   1. Receives grid state from an InputAdapter (upstream source)
+ *   2. Runs an independent low-pass filter (smooth, never jolts)
+ *   3. Falls back to 3D sine waves on signal loss
+ *   4. Sends filtered output to an OutputAdapter (hardware target)
+ *
+ * Both input and output are pluggable adapters — swap them to connect
+ * to any protocol or hardware without modifying the receiver core.
+ */
+import { InputAdapter, OutputAdapter } from './adapters';
+import { FallbackConfig } from './fallback';
+import { CannonState, FilteredCannon } from './filter';
+export interface ReceiverConfig {
+    /** Input adapter — where state comes from. */
+    input: InputAdapter;
+    /** Output adapter — where filtered state goes. */
+    output: OutputAdapter;
+    /** Low-pass filter alpha (lower = smoother). Default 0.06. */
+    alpha: number;
+    /** Ms of no data before switching to fallback. Default 3000. */
+    fallbackDelay: number;
+    /** Fallback animation config. */
+    fallback: FallbackConfig;
+    /** Tick rate in ms (default 1000/60 ~ 16.67ms). */
+    tickMs: number;
+}
+export declare const DEFAULT_RECEIVER_CONFIG: ReceiverConfig;
+export type ReceiverStatus = 'connected' | 'reconnecting' | 'fallback';
+export interface ReceiverState {
+    status: ReceiverStatus;
+    grid: FilteredCannon[];
+    tick: number;
+    lastDataAt: number;
+    fallbackActive: boolean;
+}
+export declare class Receiver {
+    private config;
+    private grid;
+    private tickTimer;
+    private tick;
+    private lastDataAt;
+    private _status;
+    private _fallbackActive;
+    private _running;
+    constructor(config?: Partial<ReceiverConfig>);
+    get status(): ReceiverStatus;
+    get fallbackActive(): boolean;
+    /** Get the current output state (after filtering). */
+    getOutputState(): CannonState[];
+    /** Start the receiver — connects input and begins the tick loop. */
+    start(): void;
+    /** Stop the receiver — disconnects and stops the tick loop. */
+    stop(): void;
+    private bindInput;
+    private startTickLoop;
+}