wavegrid 0.2.0 → 0.3.0

package/LICENSE

@@ -1,7 +1,20 @@
-All Rights Reserved.
+The San Francisco License (SF License)
 
-Copyright (c) 2024 Interweb, Inc.
+Copyright (c) 2026 Interweb, Inc.
 
-This software and associated documentation files (the "Software") may not be
-reproduced, distributed, or used without express written permission from
-Interweb, Inc.
+Permission is granted, free of charge, to any person or organization
+obtaining a copy of this software and associated documentation files
+(the "Software"), to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit others
+to whom the Software is furnished to do the same.
+
+The only requirement is that this license notice and copyright notice
+shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -10,22 +10,23 @@
   </a>
 </p>
 
-The **brain** of the Illuminate installation. Sits between the control layer (Canvas/Simulator) and the physical hardware (BEYOND/OSC).
+The **brain** of the Wavegrid installation. Sits between the control layer (Canvas/Simulator) and the physical hardware (BEYOND/OSC via `@wavegrid/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)
+1. **Never jolt** — runs its own independent low-pass filter on all incoming state
+2. **Always alive** — on signal loss, gracefully falls back to ambient 3D sine wave animations
+3. **Pluggable** — input and output are adapters; swap them for any protocol or hardware
+4. **Lean** — no hardware dependencies in the core; OSC lives in `@wavegrid/osc`
 
 ## Architecture
 
 ```
-Canvas ──ws──▶ Simulator ──ws──▶ Receiver ──osc──▶ BEYOND
+Canvas ──ws──▶ Simulator ──ws──▶ Receiver ──adapter──▶ Hardware
                                     │
                               own LP filter
                               sine fallback
-                              health monitor
+                              shard support
 ```
 
 ## Usage
@@ -33,16 +34,29 @@ Canvas ──ws──▶ Simulator ──ws──▶ Receiver ──osc──▶
 ```sh
 pnpm dev:receiver
 # Connects to simulator at ws://localhost:3000
-# Outputs state to console (or OSC when configured)
+# Outputs state to console (or hardware when configured)
 ```
 
-## Fallback Behavior
+### With OSC hardware (requires `@wavegrid/osc`)
 
-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
+```sh
+ROUTING_CONFIG=./routing.json pnpm dev:receiver
+BEYOND_HOST=192.168.50.10 pnpm dev:receiver
+```
+
+### Programmatic
+
+```typescript
+import { Receiver, WebSocketInput, ConsoleOutput } from 'wavegrid';
+
+const receiver = new Receiver({
+  input: new WebSocketInput({ url: 'ws://localhost:3000' }),
+  output: new ConsoleOutput(),
+  numCannons: 49,
+  gridColumns: 7
+});
+receiver.start();
+```
 
 ## Configuration
 
@@ -51,5 +65,23 @@ When the upstream WebSocket connection drops:
 | `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) |
+| `WS_OUTPUT_PORT` | — | Optional WebSocket relay output port |
+| `SHARD_START` | — | First cannon index (inclusive) |
+| `SHARD_END` | — | Last cannon index (inclusive) |
+| `NUM_CANNONS` | `49` | Total cannons in the grid |
+| `GRID_COLUMNS` | `7` | Number of columns in the grid |
+| `ROUTING_CONFIG` | — | Path to JSON routing config (enables OSC) |
+| `BEYOND_HOST` | — | Quick single-target BEYOND OSC host |
+| `BEYOND_PORT` | `9000` | BEYOND OSC port |
+| `FB4_HOST` | — | Quick single-target FB4 OSC host |
+| `FB4_PORT` | `8000` | FB4 OSC port |
+
+## Built-in Adapters
+
+| Adapter | Direction | Purpose |
+|---------|-----------|---------|
+| `WebSocketInput` | Input | Connects to upstream simulator/server |
+| `ConsoleOutput` | Output | Logs frames to console (dev/debug) |
+| `CallbackOutput` | Output | Calls your function each tick |
+| `MultiOutput` | Output | Fans out to N adapters at once |
+| `WebSocketOutput` | Output | Broadcasts to downstream WS clients |

package/esm/fallback.js

@@ -8,7 +8,7 @@
  * The waves create organic, slowly evolving color movement — like the
  * installation is breathing on its own.
  */
-import { GRID_SIZE, NUM_CANNONS } from './filter';
+import { DEFAULT_GRID_COLUMNS } from './filter';
 export const DEFAULT_FALLBACK_CONFIG = {
     baseHue: 220,
     hueSpread: 60,
@@ -28,15 +28,18 @@ export const DEFAULT_FALLBACK_CONFIG = {
  *   2. Secondary wave moves perpendicular (brightness)
  *   3. Tertiary slow wave modulates saturation for depth
  */
-export function computeFallbackFrame(grid, tick, config = DEFAULT_FALLBACK_CONFIG) {
+export function computeFallbackFrame(grid, tick, config = DEFAULT_FALLBACK_CONFIG, gridColumns = DEFAULT_GRID_COLUMNS) {
     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;
+    const cols = Math.max(1, gridColumns);
+    for (let i = 0; i < grid.length; i++) {
+        const row = Math.floor(i / cols);
+        const col = i % cols;
+        const maxCol = Math.max(1, cols - 1);
+        const maxRow = Math.max(1, Math.ceil(grid.length / cols) - 1);
         // Normalize to -1..1
-        const nx = (col / (GRID_SIZE - 1)) * 2 - 1;
-        const ny = (row / (GRID_SIZE - 1)) * 2 - 1;
+        const nx = (col / maxCol) * 2 - 1;
+        const ny = (row / maxRow) * 2 - 1;
         // Primary diagonal wave → hue
         const wave1 = Math.sin((nx + ny) * spatialFreq * Math.PI + tick * timeFreq);
         // Secondary perpendicular wave → brightness

package/esm/filter.js

@@ -5,11 +5,15 @@
  * 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_NUM_CANNONS = 49;
+export const DEFAULT_GRID_COLUMNS = 7;
 export const DEFAULT_RECEIVER_ALPHA = 0.06;
-export function createFilteredGrid() {
-    return Array.from({ length: NUM_CANNONS }, () => ({
+/**
+ * Create a filtered grid of the given size.
+ * Defaults to 49 cannons for the 7×7 Civic Center installation.
+ */
+export function createFilteredGrid(numCannons = DEFAULT_NUM_CANNONS) {
+    return Array.from({ length: numCannons }, () => ({
         h: 220,
         s: 90,
         b: 80,

package/esm/index.js

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

package/esm/main.js

@@ -1,24 +1,86 @@
 /**
  * Receiver entry point.
  *
- * Demonstrates the adapter pattern — configure input and output
- * adapters via environment variables, then start the receiver.
+ * Configure input and output adapters via environment variables:
+ *
+ *   SIMULATOR_URL      WebSocket upstream (default ws://localhost:3000)
+ *   RECEIVER_ALPHA     LP filter alpha (default 0.06)
+ *   FALLBACK_DELAY     Ms before sine fallback (default 3000)
+ *   WS_OUTPUT_PORT     Optional WebSocket relay port
+ *   SHARD_START/END    Optional cannon index range
+ *   NUM_CANNONS        Total cannons in grid (default 49)
+ *   GRID_COLUMNS       Number of columns (default 7)
+ *   ROUTING_CONFIG     Path to a JSON routing config file (enables OSC output)
+ *   BEYOND_HOST/PORT   Quick single-target BEYOND OSC (alternative to routing file)
+ *   FB4_HOST/PORT      Quick single-target FB4 OSC (alternative to routing file)
  */
+import * as fs from 'fs';
 import { ConsoleOutput, MultiOutput, WebSocketInput, WebSocketOutput } from './adapters';
+import { DEFAULT_GRID_COLUMNS, DEFAULT_NUM_CANNONS } from './filter';
 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;
+const NUM_CANNONS = process.env.NUM_CANNONS ? parseInt(process.env.NUM_CANNONS, 10) : DEFAULT_NUM_CANNONS;
+const GRID_COLUMNS = process.env.GRID_COLUMNS ? parseInt(process.env.GRID_COLUMNS, 10) : DEFAULT_GRID_COLUMNS;
+let shard;
+if (process.env.SHARD_START !== undefined && process.env.SHARD_END !== undefined) {
+    shard = {
+        start: parseInt(process.env.SHARD_START, 10),
+        end: parseInt(process.env.SHARD_END, 10)
+    };
+}
 // ─── Input adapter ───
 const input = new WebSocketInput({ url: SIMULATOR_URL });
 // ─── Output adapter(s) ───
 const outputs = [new ConsoleOutput()];
+const outputLabels = ['Console'];
+// OSC adapters are in @wavegrid/osc — try to load them if env vars are set
+const hasOscConfig = process.env.ROUTING_CONFIG || process.env.BEYOND_HOST || process.env.FB4_HOST;
+if (hasOscConfig) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const osc = require('@wavegrid/osc');
+        if (process.env.ROUTING_CONFIG) {
+            const raw = fs.readFileSync(process.env.ROUTING_CONFIG, 'utf8');
+            const routingConfig = JSON.parse(raw);
+            const routed = osc.createRoutedOutput(routingConfig);
+            routed.connect();
+            outputs.push(routed);
+            outputLabels.push(`Routed OSC → [${routed.targetNames.join(', ')}]`);
+        }
+        if (process.env.BEYOND_HOST) {
+            const host = process.env.BEYOND_HOST;
+            const port = parseInt(process.env.BEYOND_PORT || '9000', 10);
+            const projectorMap = {};
+            for (let i = 0; i < NUM_CANNONS; i++)
+                projectorMap[i] = i;
+            const beyond = new osc.BeyondOscOutput({ host, port, projectorMap });
+            beyond.connect();
+            outputs.push(beyond);
+            outputLabels.push(`BEYOND OSC → ${host}:${port}`);
+        }
+        if (process.env.FB4_HOST) {
+            const host = process.env.FB4_HOST;
+            const port = parseInt(process.env.FB4_PORT || '8000', 10);
+            console.warn('  ⚠ FB4_HOST set but no serial map — use ROUTING_CONFIG for per-cannon FB4 mapping');
+            const fb4 = new osc.FB4OscOutput({ host, port, serialMap: {} });
+            fb4.connect();
+            outputs.push(fb4);
+            outputLabels.push(`FB4 OSC → ${host}:${port}`);
+        }
+    }
+    catch (e) {
+        console.warn('  ⚠ OSC env vars set but @wavegrid/osc is not installed. Run: pnpm add @wavegrid/osc');
+    }
+}
 let wsOutput = null;
 if (WS_OUTPUT_PORT) {
     wsOutput = new WebSocketOutput({ port: WS_OUTPUT_PORT });
     wsOutput.listen();
     outputs.push(wsOutput);
+    outputLabels.push(`WebSocket :${WS_OUTPUT_PORT}`);
 }
 const output = outputs.length === 1 ? outputs[0] : new MultiOutput(outputs);
 // ─── Receiver ───
@@ -26,17 +88,22 @@ const receiver = new Receiver({
     input,
     output,
     alpha: ALPHA,
-    fallbackDelay: FALLBACK_DELAY
+    fallbackDelay: FALLBACK_DELAY,
+    shard,
+    numCannons: NUM_CANNONS,
+    gridColumns: GRID_COLUMNS
 });
 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('  │   Wavegrid · Receiver                 │');
+console.log('  │   the brain                           │');
+console.log('  ╰──────────────────────────────────────╯');
 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(`  → Input:  WebSocket @ ${SIMULATOR_URL}`);
+console.log(`  → Output: ${outputLabels.join(' + ')}`);
+console.log(`  → Alpha: ${ALPHA}  Fallback delay: ${FALLBACK_DELAY}ms`);
+console.log(`  → Grid: ${NUM_CANNONS} cannons (${GRID_COLUMNS} columns)`);
+console.log(`  → Shard: ${shard ? `cannons ${shard.start}–${shard.end} (${shard.end - shard.start + 1} of ${NUM_CANNONS})` : `all cannons (no shard)`}`);
 console.log('');
 receiver.start();
 // Graceful shutdown

package/esm/receiver.js

@@ -12,14 +12,16 @@
  */
 import { ConsoleOutput, WebSocketInput } from './adapters';
 import { computeFallbackFrame, DEFAULT_FALLBACK_CONFIG } from './fallback';
-import { applyUpstreamState, createFilteredGrid, DEFAULT_RECEIVER_ALPHA, tickFilter } from './filter';
+import { applyUpstreamState, createFilteredGrid, DEFAULT_GRID_COLUMNS, DEFAULT_NUM_CANNONS, 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
+    tickMs: 1000 / 60,
+    numCannons: DEFAULT_NUM_CANNONS,
+    gridColumns: DEFAULT_GRID_COLUMNS
 };
 export class Receiver {
     config;
@@ -32,17 +34,21 @@ export class Receiver {
     _running = false;
     constructor(config = {}) {
         this.config = { ...DEFAULT_RECEIVER_CONFIG, ...config };
-        this.grid = createFilteredGrid();
+        this.grid = createFilteredGrid(this.config.numCannons);
     }
     get status() { return this._status; }
     get fallbackActive() { return this._fallbackActive; }
-    /** Get the current output state (after filtering). */
+    /** Get the current output state (after filtering and sharding). */
     getOutputState() {
-        return this.grid.map(c => ({
+        const full = this.grid.map(c => ({
             h: c.h,
             s: c.s,
             b: c.b
         }));
+        const shard = this.config.shard;
+        if (!shard)
+            return full;
+        return full.slice(shard.start, shard.end + 1);
     }
     /** Start the receiver — connects input and begins the tick loop. */
     start() {
@@ -98,7 +104,7 @@ export class Receiver {
             }
             // If fallback is active, compute sine wave targets
             if (this._fallbackActive) {
-                computeFallbackFrame(this.grid, this.tick, this.config.fallback);
+                computeFallbackFrame(this.grid, this.tick, this.config.fallback, this.config.gridColumns);
             }
             // Always tick the low-pass filter — this ensures smooth output
             // whether receiving data, transitioning to fallback, or in fallback

package/fallback.d.ts

@@ -36,4 +36,4 @@ export declare const DEFAULT_FALLBACK_CONFIG: FallbackConfig;
  *   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;
+export declare function computeFallbackFrame(grid: FilteredCannon[], tick: number, config?: FallbackConfig, gridColumns?: number): void;

package/fallback.js

@@ -32,15 +32,18 @@ exports.DEFAULT_FALLBACK_CONFIG = {
  *   2. Secondary wave moves perpendicular (brightness)
  *   3. Tertiary slow wave modulates saturation for depth
  */
-function computeFallbackFrame(grid, tick, config = exports.DEFAULT_FALLBACK_CONFIG) {
+function computeFallbackFrame(grid, tick, config = exports.DEFAULT_FALLBACK_CONFIG, gridColumns = filter_1.DEFAULT_GRID_COLUMNS) {
     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;
+    const cols = Math.max(1, gridColumns);
+    for (let i = 0; i < grid.length; i++) {
+        const row = Math.floor(i / cols);
+        const col = i % cols;
+        const maxCol = Math.max(1, cols - 1);
+        const maxRow = Math.max(1, Math.ceil(grid.length / cols) - 1);
         // Normalize to -1..1
-        const nx = (col / (filter_1.GRID_SIZE - 1)) * 2 - 1;
-        const ny = (row / (filter_1.GRID_SIZE - 1)) * 2 - 1;
+        const nx = (col / maxCol) * 2 - 1;
+        const ny = (row / maxRow) * 2 - 1;
         // Primary diagonal wave → hue
         const wave1 = Math.sin((nx + ny) * spatialFreq * Math.PI + tick * timeFreq);
         // Secondary perpendicular wave → brightness

package/filter.d.ts

@@ -15,10 +15,14 @@ export interface FilteredCannon extends CannonState {
     targetS: number;
     targetB: number;
 }
-export declare const NUM_CANNONS = 49;
-export declare const GRID_SIZE = 7;
+export declare const DEFAULT_NUM_CANNONS = 49;
+export declare const DEFAULT_GRID_COLUMNS = 7;
 export declare const DEFAULT_RECEIVER_ALPHA = 0.06;
-export declare function createFilteredGrid(): FilteredCannon[];
+/**
+ * Create a filtered grid of the given size.
+ * Defaults to 49 cannons for the 7×7 Civic Center installation.
+ */
+export declare function createFilteredGrid(numCannons?: number): FilteredCannon[];
 /**
  * Shortest angular distance on the hue circle.
  */

package/filter.js

@@ -7,16 +7,20 @@
  * 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.DEFAULT_RECEIVER_ALPHA = exports.DEFAULT_GRID_COLUMNS = exports.DEFAULT_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_NUM_CANNONS = 49;
+exports.DEFAULT_GRID_COLUMNS = 7;
 exports.DEFAULT_RECEIVER_ALPHA = 0.06;
-function createFilteredGrid() {
-    return Array.from({ length: exports.NUM_CANNONS }, () => ({
+/**
+ * Create a filtered grid of the given size.
+ * Defaults to 49 cannons for the 7×7 Civic Center installation.
+ */
+function createFilteredGrid(numCannons = exports.DEFAULT_NUM_CANNONS) {
+    return Array.from({ length: numCannons }, () => ({
         h: 220,
         s: 90,
         b: 80,

package/index.d.ts

@@ -1,8 +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 { angleDelta, applyUpstreamState, createFilteredGrid, DEFAULT_GRID_COLUMNS, DEFAULT_NUM_CANNONS, 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 type { ReceiverConfig, ReceiverState, ReceiverStatus, ShardConfig } from './receiver';
 export { Receiver } from './receiver';

package/index.js

@@ -1,6 +1,6 @@
 "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;
+exports.Receiver = exports.DEFAULT_FALLBACK_CONFIG = exports.computeFallbackFrame = exports.tickFilter = exports.DEFAULT_RECEIVER_ALPHA = exports.DEFAULT_NUM_CANNONS = exports.DEFAULT_GRID_COLUMNS = 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; } });
@@ -11,6 +11,8 @@ 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_GRID_COLUMNS", { enumerable: true, get: function () { return filter_1.DEFAULT_GRID_COLUMNS; } });
+Object.defineProperty(exports, "DEFAULT_NUM_CANNONS", { enumerable: true, get: function () { return filter_1.DEFAULT_NUM_CANNONS; } });
 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");

package/main.d.ts

@@ -1,7 +1,17 @@
 /**
  * Receiver entry point.
  *
- * Demonstrates the adapter pattern — configure input and output
- * adapters via environment variables, then start the receiver.
+ * Configure input and output adapters via environment variables:
+ *
+ *   SIMULATOR_URL      WebSocket upstream (default ws://localhost:3000)
+ *   RECEIVER_ALPHA     LP filter alpha (default 0.06)
+ *   FALLBACK_DELAY     Ms before sine fallback (default 3000)
+ *   WS_OUTPUT_PORT     Optional WebSocket relay port
+ *   SHARD_START/END    Optional cannon index range
+ *   NUM_CANNONS        Total cannons in grid (default 49)
+ *   GRID_COLUMNS       Number of columns (default 7)
+ *   ROUTING_CONFIG     Path to a JSON routing config file (enables OSC output)
+ *   BEYOND_HOST/PORT   Quick single-target BEYOND OSC (alternative to routing file)
+ *   FB4_HOST/PORT      Quick single-target FB4 OSC (alternative to routing file)
  */
 export {};

package/main.js

@@ -2,25 +2,120 @@
 /**
  * Receiver entry point.
  *
- * Demonstrates the adapter pattern — configure input and output
- * adapters via environment variables, then start the receiver.
+ * Configure input and output adapters via environment variables:
+ *
+ *   SIMULATOR_URL      WebSocket upstream (default ws://localhost:3000)
+ *   RECEIVER_ALPHA     LP filter alpha (default 0.06)
+ *   FALLBACK_DELAY     Ms before sine fallback (default 3000)
+ *   WS_OUTPUT_PORT     Optional WebSocket relay port
+ *   SHARD_START/END    Optional cannon index range
+ *   NUM_CANNONS        Total cannons in grid (default 49)
+ *   GRID_COLUMNS       Number of columns (default 7)
+ *   ROUTING_CONFIG     Path to a JSON routing config file (enables OSC output)
+ *   BEYOND_HOST/PORT   Quick single-target BEYOND OSC (alternative to routing file)
+ *   FB4_HOST/PORT      Quick single-target FB4 OSC (alternative to routing file)
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
 const adapters_1 = require("./adapters");
+const filter_1 = require("./filter");
 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;
+const NUM_CANNONS = process.env.NUM_CANNONS ? parseInt(process.env.NUM_CANNONS, 10) : filter_1.DEFAULT_NUM_CANNONS;
+const GRID_COLUMNS = process.env.GRID_COLUMNS ? parseInt(process.env.GRID_COLUMNS, 10) : filter_1.DEFAULT_GRID_COLUMNS;
+let shard;
+if (process.env.SHARD_START !== undefined && process.env.SHARD_END !== undefined) {
+    shard = {
+        start: parseInt(process.env.SHARD_START, 10),
+        end: parseInt(process.env.SHARD_END, 10)
+    };
+}
 // ─── Input adapter ───
 const input = new adapters_1.WebSocketInput({ url: SIMULATOR_URL });
 // ─── Output adapter(s) ───
 const outputs = [new adapters_1.ConsoleOutput()];
+const outputLabels = ['Console'];
+// OSC adapters are in @wavegrid/osc — try to load them if env vars are set
+const hasOscConfig = process.env.ROUTING_CONFIG || process.env.BEYOND_HOST || process.env.FB4_HOST;
+if (hasOscConfig) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const osc = require('@wavegrid/osc');
+        if (process.env.ROUTING_CONFIG) {
+            const raw = fs.readFileSync(process.env.ROUTING_CONFIG, 'utf8');
+            const routingConfig = JSON.parse(raw);
+            const routed = osc.createRoutedOutput(routingConfig);
+            routed.connect();
+            outputs.push(routed);
+            outputLabels.push(`Routed OSC → [${routed.targetNames.join(', ')}]`);
+        }
+        if (process.env.BEYOND_HOST) {
+            const host = process.env.BEYOND_HOST;
+            const port = parseInt(process.env.BEYOND_PORT || '9000', 10);
+            const projectorMap = {};
+            for (let i = 0; i < NUM_CANNONS; i++)
+                projectorMap[i] = i;
+            const beyond = new osc.BeyondOscOutput({ host, port, projectorMap });
+            beyond.connect();
+            outputs.push(beyond);
+            outputLabels.push(`BEYOND OSC → ${host}:${port}`);
+        }
+        if (process.env.FB4_HOST) {
+            const host = process.env.FB4_HOST;
+            const port = parseInt(process.env.FB4_PORT || '8000', 10);
+            console.warn('  ⚠ FB4_HOST set but no serial map — use ROUTING_CONFIG for per-cannon FB4 mapping');
+            const fb4 = new osc.FB4OscOutput({ host, port, serialMap: {} });
+            fb4.connect();
+            outputs.push(fb4);
+            outputLabels.push(`FB4 OSC → ${host}:${port}`);
+        }
+    }
+    catch (e) {
+        console.warn('  ⚠ OSC env vars set but @wavegrid/osc is not installed. Run: pnpm add @wavegrid/osc');
+    }
+}
 let wsOutput = null;
 if (WS_OUTPUT_PORT) {
     wsOutput = new adapters_1.WebSocketOutput({ port: WS_OUTPUT_PORT });
     wsOutput.listen();
     outputs.push(wsOutput);
+    outputLabels.push(`WebSocket :${WS_OUTPUT_PORT}`);
 }
 const output = outputs.length === 1 ? outputs[0] : new adapters_1.MultiOutput(outputs);
 // ─── Receiver ───
@@ -28,17 +123,22 @@ const receiver = new receiver_1.Receiver({
     input,
     output,
     alpha: ALPHA,
-    fallbackDelay: FALLBACK_DELAY
+    fallbackDelay: FALLBACK_DELAY,
+    shard,
+    numCannons: NUM_CANNONS,
+    gridColumns: GRID_COLUMNS
 });
 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('  │   Wavegrid · Receiver                 │');
+console.log('  │   the brain                           │');
+console.log('  ╰──────────────────────────────────────╯');
 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(`  → Input:  WebSocket @ ${SIMULATOR_URL}`);
+console.log(`  → Output: ${outputLabels.join(' + ')}`);
+console.log(`  → Alpha: ${ALPHA}  Fallback delay: ${FALLBACK_DELAY}ms`);
+console.log(`  → Grid: ${NUM_CANNONS} cannons (${GRID_COLUMNS} columns)`);
+console.log(`  → Shard: ${shard ? `cannons ${shard.start}–${shard.end} (${shard.end - shard.start + 1} of ${NUM_CANNONS})` : `all cannons (no shard)`}`);
 console.log('');
 receiver.start();
 // Graceful shutdown

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "wavegrid",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "author": "Dan Lynch <pyramation@gmail.com>",
-  "description": "Receiver brain — resilient state engine with independent low-pass filter, 3D sine wave fallback, and OSC bridge",
+  "description": "Receiver brain — resilient state engine with independent low-pass filter, 3D sine wave fallback, and pluggable adapter pattern",
   "main": "index.js",
   "module": "esm/index.js",
   "types": "index.d.ts",
@@ -31,10 +31,10 @@
   },
   "keywords": [
     "laser",
-    "osc",
     "receiver",
     "brain",
-    "7x7"
+    "adapter",
+    "wavegrid"
   ],
   "dependencies": {
     "ws": "^8.18.0"
@@ -43,5 +43,5 @@
     "@types/ws": "^8.5.13",
     "makage": "^0.3.0"
   },
-  "gitHead": "579bfca2fe84231a6722d3b4bfd44d1f42a0c9ef"
+  "gitHead": "1fc162ccd34d4b7e3594d26ee20043fb24a14ec6"
 }

package/receiver.d.ts

@@ -13,6 +13,12 @@
 import { InputAdapter, OutputAdapter } from './adapters';
 import { FallbackConfig } from './fallback';
 import { CannonState, FilteredCannon } from './filter';
+export interface ShardConfig {
+    /** First cannon index (inclusive). */
+    start: number;
+    /** Last cannon index (inclusive). */
+    end: number;
+}
 export interface ReceiverConfig {
     /** Input adapter — where state comes from. */
     input: InputAdapter;
@@ -26,6 +32,17 @@ export interface ReceiverConfig {
     fallback: FallbackConfig;
     /** Tick rate in ms (default 1000/60 ~ 16.67ms). */
     tickMs: number;
+    /**
+     * Optional shard — only output cannons in this index range.
+     * When omitted, the receiver outputs all cannons.
+     * The LP filter still processes the full grid; sharding only
+     * affects which cannons are sent to the output adapter.
+     */
+    shard?: ShardConfig;
+    /** Total number of cannons in the grid. Default 49. */
+    numCannons: number;
+    /** Number of columns in the grid (for fallback spatial mapping). Default 7. */
+    gridColumns: number;
 }
 export declare const DEFAULT_RECEIVER_CONFIG: ReceiverConfig;
 export type ReceiverStatus = 'connected' | 'reconnecting' | 'fallback';
@@ -48,7 +65,7 @@ export declare class Receiver {
     constructor(config?: Partial<ReceiverConfig>);
     get status(): ReceiverStatus;
     get fallbackActive(): boolean;
-    /** Get the current output state (after filtering). */
+    /** Get the current output state (after filtering and sharding). */
     getOutputState(): CannonState[];
     /** Start the receiver — connects input and begins the tick loop. */
     start(): void;

package/receiver.js

@@ -22,7 +22,9 @@ exports.DEFAULT_RECEIVER_CONFIG = {
     alpha: filter_1.DEFAULT_RECEIVER_ALPHA,
     fallbackDelay: 3000,
     fallback: fallback_1.DEFAULT_FALLBACK_CONFIG,
-    tickMs: 1000 / 60
+    tickMs: 1000 / 60,
+    numCannons: filter_1.DEFAULT_NUM_CANNONS,
+    gridColumns: filter_1.DEFAULT_GRID_COLUMNS
 };
 class Receiver {
     config;
@@ -35,17 +37,21 @@ class Receiver {
     _running = false;
     constructor(config = {}) {
         this.config = { ...exports.DEFAULT_RECEIVER_CONFIG, ...config };
-        this.grid = (0, filter_1.createFilteredGrid)();
+        this.grid = (0, filter_1.createFilteredGrid)(this.config.numCannons);
     }
     get status() { return this._status; }
     get fallbackActive() { return this._fallbackActive; }
-    /** Get the current output state (after filtering). */
+    /** Get the current output state (after filtering and sharding). */
     getOutputState() {
-        return this.grid.map(c => ({
+        const full = this.grid.map(c => ({
             h: c.h,
             s: c.s,
             b: c.b
         }));
+        const shard = this.config.shard;
+        if (!shard)
+            return full;
+        return full.slice(shard.start, shard.end + 1);
     }
     /** Start the receiver — connects input and begins the tick loop. */
     start() {
@@ -101,7 +107,7 @@ class Receiver {
             }
             // If fallback is active, compute sine wave targets
             if (this._fallbackActive) {
-                (0, fallback_1.computeFallbackFrame)(this.grid, this.tick, this.config.fallback);
+                (0, fallback_1.computeFallbackFrame)(this.grid, this.tick, this.config.fallback, this.config.gridColumns);
             }
             // Always tick the low-pass filter — this ensures smooth output
             // whether receiving data, transitioning to fallback, or in fallback