@wavegrid/simulator 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,37 @@
+# @wavegrid/simulator
+
+<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>
+
+7×7 RGB grid simulator for the Illuminate project. Renders 49 virtual laser cannons with smooth interpolated transitions (low-pass filtered) — no abrupt color or brightness changes.
+
+## Usage
+
+```sh
+# Start the dev server
+pnpm dev
+
+# Run tests
+pnpm test
+
+# Build
+pnpm build
+```
+
+## Architecture
+
+- **`grid.ts`** — Core state engine with exponential interpolation (lerp). Each tick smoothly converges current values toward targets.
+- **`scenes.ts`** — Predefined color/brightness patterns (civic blue, pride, gold, sunset, etc.)
+- **`server.ts`** — HTTP + WebSocket server. Ticks at 60fps, broadcasts only when state changes.
+- **`ui.ts`** — Embedded HTML/CSS/JS client with touch-friendly grid controls.
+
+## Smooth Transitions
+
+All state changes go through a low-pass filter. When you change a scene or adjust a slider, the grid **flows** to the new state over ~1.5 seconds rather than jumping instantly. This ensures the physical laser array will never produce jarring transitions.

package/esm/grid.js

@@ -0,0 +1,64 @@
+export const NUM_CANNONS = 49;
+export const GRID_SIZE = 7;
+/**
+ * Smoothing factor per tick (0–1).
+ * Lower = smoother/slower transitions (more low-pass filtering).
+ * At 60fps with alpha=0.08, a full transition takes ~1.5s to settle.
+ */
+export const DEFAULT_ALPHA = 0.08;
+export function createGrid() {
+    return Array.from({ length: NUM_CANNONS }, () => ({
+        h: 220,
+        s: 90,
+        b: 80,
+        targetH: 220,
+        targetS: 90,
+        targetB: 80
+    }));
+}
+/**
+ * Exponential low-pass filter (lerp toward target).
+ * Called once per animation frame to smoothly converge current → target.
+ */
+export function tickGrid(grid, alpha = DEFAULT_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.5 || Math.abs(ds) > 0.5 || Math.abs(db) > 0.5) {
+            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;
+}
+/**
+ * Shortest angular distance on the hue circle (handles wrap-around).
+ */
+function angleDelta(from, to) {
+    let d = ((to - from + 540) % 360) - 180;
+    return d;
+}
+export function setCannonTarget(grid, index, h, s, b) {
+    const c = grid[index];
+    if (h !== undefined)
+        c.targetH = h;
+    if (s !== undefined)
+        c.targetS = s;
+    if (b !== undefined)
+        c.targetB = b;
+}
+export function setAllTargets(grid, h, s, b) {
+    for (let i = 0; i < grid.length; i++) {
+        setCannonTarget(grid, i, h, s, b);
+    }
+}

package/esm/index.js

@@ -0,0 +1,2 @@
+export { createGrid, tickGrid, setCannonTarget, setAllTargets, NUM_CANNONS, GRID_SIZE, DEFAULT_ALPHA } from './grid';
+export { applyScene, scenes } from './scenes';

package/esm/scenes.js

@@ -0,0 +1,31 @@
+import { NUM_CANNONS, setCannonTarget } from './grid';
+export const scenes = {
+    civic: () => ({ h: 220, s: 90, b: 80 }),
+    pride: (i, total) => ({ h: Math.round((i / total) * 360), s: 90, b: 80 }),
+    gold: () => ({ h: 45, s: 95, b: 80 }),
+    white: () => ({ h: 0, s: 0, b: 80 }),
+    solstice: (i) => {
+        const row = Math.floor(i / 7);
+        const col = i % 7;
+        return { h: 40 + row * 5 + col * 4, s: 85, b: 80 };
+    },
+    ocean: (i) => {
+        const row = Math.floor(i / 7);
+        const col = i % 7;
+        return { h: 180 + row * 8 + col * 3, s: 75, b: 70 };
+    },
+    sunset: (i) => {
+        const row = Math.floor(i / 7);
+        return { h: 10 + row * 5, s: 90, b: 85 - row * 5 };
+    },
+    off: () => ({ h: 0, s: 0, b: 0 })
+};
+export function applyScene(grid, sceneName) {
+    const generator = scenes[sceneName];
+    if (!generator)
+        return;
+    for (let i = 0; i < NUM_CANNONS; i++) {
+        const { h, s, b } = generator(i, NUM_CANNONS);
+        setCannonTarget(grid, i, h, s, b);
+    }
+}

package/esm/server.js

@@ -0,0 +1,82 @@
+import http from 'http';
+import { WebSocketServer, WebSocket } from 'ws';
+import { createGrid, tickGrid, setCannonTarget, setAllTargets } from './grid';
+import { applyScene, scenes } from './scenes';
+import { getHTML } from './ui';
+const PORT = parseInt(process.env.PORT || '3000', 10);
+const TICK_MS = 1000 / 60; // 60fps interpolation
+const grid = createGrid();
+const server = http.createServer((_req, res) => {
+    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(getHTML());
+});
+const wss = new WebSocketServer({ server });
+function broadcastState() {
+    const payload = JSON.stringify({
+        type: 'state',
+        grid: grid.map(c => ({ h: c.h, s: c.s, b: c.b }))
+    });
+    wss.clients.forEach(client => {
+        if (client.readyState === WebSocket.OPEN) {
+            client.send(payload);
+        }
+    });
+}
+wss.on('connection', (ws) => {
+    // Send initial state
+    ws.send(JSON.stringify({
+        type: 'state',
+        grid: grid.map(c => ({ h: c.h, s: c.s, b: c.b }))
+    }));
+    ws.on('message', (raw) => {
+        try {
+            const msg = JSON.parse(raw.toString());
+            handleMessage(msg);
+        }
+        catch (_e) {
+            // ignore malformed messages
+        }
+    });
+});
+function handleMessage(msg) {
+    switch (msg.type) {
+        case 'cannon':
+            setCannonTarget(grid, msg.index, msg.h ?? undefined, msg.s ?? undefined, msg.b ?? undefined);
+            break;
+        case 'master_brightness':
+            setAllTargets(grid, undefined, undefined, msg.value * 100);
+            break;
+        case 'scene':
+            if (msg.name && scenes[msg.name]) {
+                applyScene(grid, msg.name);
+            }
+            break;
+        case 'selection':
+            if (Array.isArray(msg.indices)) {
+                for (const idx of msg.indices) {
+                    if (idx >= 0 && idx < grid.length) {
+                        setCannonTarget(grid, idx, msg.h ?? undefined, msg.s ?? undefined, msg.b ?? undefined);
+                    }
+                }
+            }
+            break;
+    }
+}
+// Animation loop: tick interpolation and broadcast
+setInterval(() => {
+    const changed = tickGrid(grid);
+    if (changed) {
+        broadcastState();
+    }
+}, TICK_MS);
+server.listen(PORT, '0.0.0.0', () => {
+    console.log('');
+    console.log('╔══════════════════════════════════════════╗');
+    console.log('║   Illuminate · 7×7 Grid Simulator       ║');
+    console.log('║   49 virtual cannons ready               ║');
+    console.log('╚══════════════════════════════════════════╝');
+    console.log('');
+    console.log(`  → http://localhost:${PORT}`);
+    console.log('');
+});
+export { server, grid };

package/esm/ui.js

@@ -0,0 +1,354 @@
+import { scenes } from './scenes';
+export function getHTML() {
+    const sceneNames = Object.keys(scenes);
+    return `<!DOCTYPE html>
+<html>
+<head>
+  <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
+  <title>Illuminate · 7×7 Simulator</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      background: #0a0a0a; color: #eee; padding: 1rem;
+      min-height: 100vh;
+    }
+    h1 {
+      font-size: 1.1rem; font-weight: 600; margin-bottom: 1rem;
+      color: #ccc; letter-spacing: 0.03em;
+    }
+    .master {
+      background: #141414; border: 1px solid #2a2a2a; border-radius: 12px;
+      padding: 1rem; margin-bottom: 1.25rem;
+    }
+    .section-title {
+      font-size: 0.7rem; color: #666; text-transform: uppercase;
+      letter-spacing: 0.08em; margin-bottom: 0.75rem;
+    }
+    .scene-row { display: flex; gap: 6px; flex-wrap: wrap; margin-bottom: 0.75rem; }
+    .scene-btn {
+      padding: 6px 14px; border-radius: 20px; font-size: 0.75rem;
+      cursor: pointer; border: 1px solid #333; background: #1a1a1a;
+      color: #aaa; transition: all 0.2s;
+    }
+    .scene-btn:hover { border-color: #555; color: #ddd; }
+    .scene-btn.active { background: #1a3a6a; border-color: #3a6acc; color: #fff; }
+    .slider-row {
+      display: flex; align-items: center; gap: 10px; margin-bottom: 0.6rem;
+    }
+    .slider-row label {
+      font-size: 0.8rem; color: #777; min-width: 80px;
+    }
+    .slider-row input[type=range] {
+      flex: 1; height: 6px; -webkit-appearance: none; appearance: none;
+      background: #333; border-radius: 3px; outline: none;
+    }
+    .slider-row input[type=range]::-webkit-slider-thumb {
+      -webkit-appearance: none; width: 18px; height: 18px;
+      border-radius: 50%; background: #4a8cde; cursor: pointer;
+    }
+    .slider-row .val {
+      font-size: 0.8rem; font-weight: 500; min-width: 38px; text-align: right; color: #888;
+    }
+    .all-off {
+      width: 100%; padding: 10px; border-radius: 8px; margin-top: 0.5rem;
+      background: #1a0808; border: 1px solid #3a1515; color: #c44;
+      font-size: 0.85rem; font-weight: 500; cursor: pointer; text-align: center;
+      transition: background 0.2s;
+    }
+    .all-off:hover { background: #2a1010; }
+
+    .grid-section { margin-bottom: 1.25rem; }
+    .sel-actions { display: flex; gap: 6px; margin-bottom: 0.5rem; }
+    .sel-btn {
+      font-size: 0.7rem; padding: 5px 10px;
+      border: 1px solid #333; border-radius: 6px;
+      background: #1a1a1a; color: #aaa; cursor: pointer;
+      transition: all 0.15s;
+    }
+    .sel-btn:hover { border-color: #555; color: #ddd; }
+    .rc-btns { display: flex; gap: 4px; flex-wrap: wrap; margin-bottom: 0.6rem; }
+    .rc-btn {
+      font-size: 0.65rem; padding: 4px 8px;
+      border: 1px solid #1a2a4a; border-radius: 5px;
+      background: #0e1520; color: #5a8abb; cursor: pointer;
+      transition: all 0.15s;
+    }
+    .rc-btn:hover { background: #152030; border-color: #2a4a7a; }
+
+    .grid {
+      display: grid;
+      grid-template-columns: repeat(7, 1fr);
+      gap: 4px;
+      max-width: 420px;
+    }
+    .cell {
+      aspect-ratio: 1; border-radius: 8px;
+      border: 1.5px solid #222; background: #111;
+      display: flex; flex-direction: column;
+      align-items: center; justify-content: center;
+      cursor: pointer; transition: border-color 0.15s, transform 0.1s;
+      position: relative;
+    }
+    .cell:active { transform: scale(0.95); }
+    .cell.selected { border-color: #4a8cde; }
+    .cell-beam {
+      width: 60%; height: 60%; border-radius: 50%;
+      transition: none; /* driven by animation frame */
+    }
+    .cell-num {
+      font-size: 7px; color: #444; margin-top: 2px;
+      position: absolute; bottom: 3px;
+    }
+
+    .panel {
+      background: #141414; border: 1px solid #2a2a2a; border-radius: 12px;
+      padding: 1rem; display: none; margin-bottom: 1rem;
+    }
+    .panel.visible { display: block; }
+    .panel-header {
+      display: flex; align-items: center; justify-content: space-between;
+      margin-bottom: 0.75rem;
+    }
+    .panel-title { font-size: 0.9rem; font-weight: 500; }
+    .done-btn {
+      font-size: 0.7rem; padding: 4px 10px;
+      border: 1px solid #333; border-radius: 6px;
+      background: #1a1a1a; color: #aaa; cursor: pointer;
+    }
+
+    .status {
+      font-size: 0.65rem; color: #444; text-align: center; padding-top: 0.5rem;
+    }
+  </style>
+</head>
+<body>
+
+<h1>Illuminate · 7×7 Civic Center</h1>
+
+<div class="master">
+  <div class="section-title">Scenes</div>
+  <div class="scene-row" id="scene-row">
+    ${sceneNames.map((name, i) => `<button class="scene-btn${i === 0 ? ' active' : ''}" data-scene="${name}">${name}</button>`).join('\n    ')}
+  </div>
+  <div class="section-title" style="margin-top:0.75rem">Master</div>
+  <div class="slider-row">
+    <label>Brightness</label>
+    <input type="range" min="0" max="100" value="80" id="master-bright">
+    <span class="val" id="master-bright-val">80%</span>
+  </div>
+  <div class="all-off" id="all-off">All Off</div>
+</div>
+
+<div class="grid-section">
+  <div class="section-title">Cannon Grid — tap to select</div>
+  <div class="sel-actions">
+    <button class="sel-btn" id="sel-all">Select All</button>
+    <button class="sel-btn" id="sel-none">Clear</button>
+  </div>
+  <div class="rc-btns" id="rc-btns"></div>
+  <div class="grid" id="cannon-grid"></div>
+</div>
+
+<div class="panel" id="panel">
+  <div class="panel-header">
+    <span class="panel-title" id="panel-title">Cannon 1</span>
+    <button class="done-btn" id="done-btn">Done</button>
+  </div>
+  <div class="slider-row">
+    <label>Brightness</label>
+    <input type="range" min="0" max="100" value="80" id="panel-bright">
+    <span class="val" id="panel-bright-val">80%</span>
+  </div>
+  <div class="slider-row">
+    <label>Hue</label>
+    <input type="range" min="0" max="360" value="220" id="panel-hue">
+    <span class="val" id="panel-hue-val">220°</span>
+  </div>
+  <div class="slider-row">
+    <label>Saturation</label>
+    <input type="range" min="0" max="100" value="90" id="panel-sat">
+    <span class="val" id="panel-sat-val">90%</span>
+  </div>
+</div>
+
+<div class="status" id="status">Connecting...</div>
+
+<script>
+const NUM = 49;
+const ws = new WebSocket('ws://' + location.host);
+const status = document.getElementById('status');
+const selected = new Set();
+
+// Local display state (smoothly updated from server)
+const display = Array.from({length: NUM}, () => ({ h: 220, s: 90, b: 80 }));
+
+ws.onopen = () => { status.textContent = 'Connected · 49 cannons · smooth mode'; };
+ws.onclose = () => { status.textContent = 'Disconnected — reload page'; };
+
+ws.onmessage = (e) => {
+  const msg = JSON.parse(e.data);
+  if (msg.type === 'state') {
+    for (let i = 0; i < NUM; i++) {
+      display[i].h = msg.grid[i].h;
+      display[i].s = msg.grid[i].s;
+      display[i].b = msg.grid[i].b;
+    }
+  }
+};
+
+function send(data) {
+  if (ws.readyState === 1) ws.send(JSON.stringify(data));
+}
+
+function hslToHex(h, s, l) {
+  s /= 100; l /= 100;
+  const a = s * Math.min(l, 1 - l);
+  const f = n => { const k = (n + h / 30) % 12; return l - a * Math.max(Math.min(k - 3, 9 - k, 1), -1); };
+  const r = Math.round(255 * f(0));
+  const g = Math.round(255 * f(8));
+  const b = Math.round(255 * f(4));
+  return '#' + [r, g, b].map(v => v.toString(16).padStart(2, '0')).join('');
+}
+
+// Build grid
+const gridEl = document.getElementById('cannon-grid');
+for (let i = 0; i < NUM; i++) {
+  const cell = document.createElement('div');
+  cell.className = 'cell';
+  cell.id = 'cell-' + i;
+  cell.innerHTML = '<div class="cell-beam" id="beam-' + i + '"></div><span class="cell-num">' + (i + 1) + '</span>';
+  cell.addEventListener('click', () => toggleSelect(i));
+  gridEl.appendChild(cell);
+}
+
+// Build row/col buttons
+const rcEl = document.getElementById('rc-btns');
+for (let r = 0; r < 7; r++) {
+  const btn = document.createElement('button');
+  btn.className = 'rc-btn';
+  btn.textContent = 'R' + (r + 1);
+  btn.addEventListener('click', () => {
+    for (let c = 0; c < 7; c++) selectOn(r * 7 + c);
+    updatePanel();
+  });
+  rcEl.appendChild(btn);
+}
+for (let c = 0; c < 7; c++) {
+  const btn = document.createElement('button');
+  btn.className = 'rc-btn';
+  btn.textContent = 'C' + (c + 1);
+  btn.addEventListener('click', () => {
+    for (let r = 0; r < 7; r++) selectOn(r * 7 + c);
+    updatePanel();
+  });
+  rcEl.appendChild(btn);
+}
+
+function selectOn(idx) {
+  selected.add(idx);
+  document.getElementById('cell-' + idx).classList.add('selected');
+}
+
+function toggleSelect(idx) {
+  if (selected.has(idx)) {
+    selected.delete(idx);
+    document.getElementById('cell-' + idx).classList.remove('selected');
+  } else {
+    selected.add(idx);
+    document.getElementById('cell-' + idx).classList.add('selected');
+  }
+  updatePanel();
+}
+
+function updatePanel() {
+  const panel = document.getElementById('panel');
+  const title = document.getElementById('panel-title');
+  if (selected.size === 0) {
+    panel.classList.remove('visible');
+  } else {
+    panel.classList.add('visible');
+    title.textContent = selected.size === 1
+      ? 'Cannon ' + ([...selected][0] + 1)
+      : selected.size + ' cannons selected';
+  }
+}
+
+// Selection controls
+document.getElementById('sel-all').addEventListener('click', () => {
+  for (let i = 0; i < NUM; i++) selectOn(i);
+  updatePanel();
+});
+document.getElementById('sel-none').addEventListener('click', () => {
+  selected.forEach(idx => document.getElementById('cell-' + idx).classList.remove('selected'));
+  selected.clear();
+  updatePanel();
+});
+document.getElementById('done-btn').addEventListener('click', () => {
+  selected.forEach(idx => document.getElementById('cell-' + idx).classList.remove('selected'));
+  selected.clear();
+  updatePanel();
+});
+
+// Master brightness
+document.getElementById('master-bright').addEventListener('input', function() {
+  const v = parseInt(this.value);
+  document.getElementById('master-bright-val').textContent = v + '%';
+  send({ type: 'master_brightness', value: v / 100 });
+});
+
+// All off
+document.getElementById('all-off').addEventListener('click', () => {
+  document.getElementById('master-bright').value = 0;
+  document.getElementById('master-bright-val').textContent = '0%';
+  send({ type: 'master_brightness', value: 0 });
+});
+
+// Per-cannon controls
+document.getElementById('panel-bright').addEventListener('input', function() {
+  const v = parseInt(this.value);
+  document.getElementById('panel-bright-val').textContent = v + '%';
+  send({ type: 'selection', indices: [...selected], b: v });
+});
+document.getElementById('panel-hue').addEventListener('input', function() {
+  const v = parseInt(this.value);
+  document.getElementById('panel-hue-val').textContent = v + '°';
+  send({ type: 'selection', indices: [...selected], h: v });
+});
+document.getElementById('panel-sat').addEventListener('input', function() {
+  const v = parseInt(this.value);
+  document.getElementById('panel-sat-val').textContent = v + '%';
+  send({ type: 'selection', indices: [...selected], s: v });
+});
+
+// Scenes
+document.getElementById('scene-row').addEventListener('click', (e) => {
+  const btn = e.target.closest('.scene-btn');
+  if (!btn) return;
+  document.querySelectorAll('.scene-btn').forEach(b => b.classList.remove('active'));
+  btn.classList.add('active');
+  send({ type: 'scene', name: btn.dataset.scene });
+});
+
+// Render loop — updates beams from display state
+function render() {
+  for (let i = 0; i < NUM; i++) {
+    const c = display[i];
+    const beam = document.getElementById('beam-' + i);
+    if (beam) {
+      const lightness = Math.max(5, c.b * 0.5);
+      beam.style.background = c.b < 1
+        ? '#111'
+        : hslToHex(c.h, c.s, lightness);
+      beam.style.boxShadow = c.b > 20
+        ? '0 0 ' + (c.b * 0.15) + 'px ' + hslToHex(c.h, c.s, lightness)
+        : 'none';
+    }
+  }
+  requestAnimationFrame(render);
+}
+requestAnimationFrame(render);
+</script>
+</body>
+</html>`;
+}

package/grid.d.ts

@@ -0,0 +1,26 @@
+export interface CannonState {
+    h: number;
+    s: number;
+    b: number;
+}
+export interface CannonTarget extends CannonState {
+    targetH: number;
+    targetS: number;
+    targetB: number;
+}
+export declare const NUM_CANNONS = 49;
+export declare const GRID_SIZE = 7;
+/**
+ * Smoothing factor per tick (0–1).
+ * Lower = smoother/slower transitions (more low-pass filtering).
+ * At 60fps with alpha=0.08, a full transition takes ~1.5s to settle.
+ */
+export declare const DEFAULT_ALPHA = 0.08;
+export declare function createGrid(): CannonTarget[];
+/**
+ * Exponential low-pass filter (lerp toward target).
+ * Called once per animation frame to smoothly converge current → target.
+ */
+export declare function tickGrid(grid: CannonTarget[], alpha?: number): boolean;
+export declare function setCannonTarget(grid: CannonTarget[], index: number, h?: number, s?: number, b?: number): void;
+export declare function setAllTargets(grid: CannonTarget[], h?: number, s?: number, b?: number): void;

package/grid.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ALPHA = exports.GRID_SIZE = exports.NUM_CANNONS = void 0;
+exports.createGrid = createGrid;
+exports.tickGrid = tickGrid;
+exports.setCannonTarget = setCannonTarget;
+exports.setAllTargets = setAllTargets;
+exports.NUM_CANNONS = 49;
+exports.GRID_SIZE = 7;
+/**
+ * Smoothing factor per tick (0–1).
+ * Lower = smoother/slower transitions (more low-pass filtering).
+ * At 60fps with alpha=0.08, a full transition takes ~1.5s to settle.
+ */
+exports.DEFAULT_ALPHA = 0.08;
+function createGrid() {
+    return Array.from({ length: exports.NUM_CANNONS }, () => ({
+        h: 220,
+        s: 90,
+        b: 80,
+        targetH: 220,
+        targetS: 90,
+        targetB: 80
+    }));
+}
+/**
+ * Exponential low-pass filter (lerp toward target).
+ * Called once per animation frame to smoothly converge current → target.
+ */
+function tickGrid(grid, alpha = exports.DEFAULT_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.5 || Math.abs(ds) > 0.5 || Math.abs(db) > 0.5) {
+            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;
+}
+/**
+ * Shortest angular distance on the hue circle (handles wrap-around).
+ */
+function angleDelta(from, to) {
+    let d = ((to - from + 540) % 360) - 180;
+    return d;
+}
+function setCannonTarget(grid, index, h, s, b) {
+    const c = grid[index];
+    if (h !== undefined)
+        c.targetH = h;
+    if (s !== undefined)
+        c.targetS = s;
+    if (b !== undefined)
+        c.targetB = b;
+}
+function setAllTargets(grid, h, s, b) {
+    for (let i = 0; i < grid.length; i++) {
+        setCannonTarget(grid, i, h, s, b);
+    }
+}

package/index.d.ts

@@ -0,0 +1,4 @@
+export { createGrid, tickGrid, setCannonTarget, setAllTargets, NUM_CANNONS, GRID_SIZE, DEFAULT_ALPHA } from './grid';
+export { applyScene, scenes } from './scenes';
+export type { CannonState, CannonTarget } from './grid';
+export type { SceneColor, SceneGenerator } from './scenes';

package/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scenes = exports.applyScene = exports.DEFAULT_ALPHA = exports.GRID_SIZE = exports.NUM_CANNONS = exports.setAllTargets = exports.setCannonTarget = exports.tickGrid = exports.createGrid = void 0;
+var grid_1 = require("./grid");
+Object.defineProperty(exports, "createGrid", { enumerable: true, get: function () { return grid_1.createGrid; } });
+Object.defineProperty(exports, "tickGrid", { enumerable: true, get: function () { return grid_1.tickGrid; } });
+Object.defineProperty(exports, "setCannonTarget", { enumerable: true, get: function () { return grid_1.setCannonTarget; } });
+Object.defineProperty(exports, "setAllTargets", { enumerable: true, get: function () { return grid_1.setAllTargets; } });
+Object.defineProperty(exports, "NUM_CANNONS", { enumerable: true, get: function () { return grid_1.NUM_CANNONS; } });
+Object.defineProperty(exports, "GRID_SIZE", { enumerable: true, get: function () { return grid_1.GRID_SIZE; } });
+Object.defineProperty(exports, "DEFAULT_ALPHA", { enumerable: true, get: function () { return grid_1.DEFAULT_ALPHA; } });
+var scenes_1 = require("./scenes");
+Object.defineProperty(exports, "applyScene", { enumerable: true, get: function () { return scenes_1.applyScene; } });
+Object.defineProperty(exports, "scenes", { enumerable: true, get: function () { return scenes_1.scenes; } });

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@wavegrid/simulator",
+  "version": "0.1.1",
+  "author": "Dan Lynch <pyramation@gmail.com>",
+  "description": "7×7 RGB grid simulator with smooth transitions",
+  "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/server.ts"
+  },
+  "keywords": [
+    "laser",
+    "osc",
+    "lighting",
+    "simulator",
+    "7x7"
+  ],
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.13",
+    "makage": "^0.3.0"
+  },
+  "gitHead": "6f651b8d0dfbb6538c667dd3905ce6989ae18e46"
+}

package/scenes.d.ts

@@ -0,0 +1,9 @@
+import { CannonTarget } from './grid';
+export interface SceneColor {
+    h: number;
+    s: number;
+    b: number;
+}
+export type SceneGenerator = (index: number, total: number) => SceneColor;
+export declare const scenes: Record<string, SceneGenerator>;
+export declare function applyScene(grid: CannonTarget[], sceneName: string): void;

package/scenes.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scenes = void 0;
+exports.applyScene = applyScene;
+const grid_1 = require("./grid");
+exports.scenes = {
+    civic: () => ({ h: 220, s: 90, b: 80 }),
+    pride: (i, total) => ({ h: Math.round((i / total) * 360), s: 90, b: 80 }),
+    gold: () => ({ h: 45, s: 95, b: 80 }),
+    white: () => ({ h: 0, s: 0, b: 80 }),
+    solstice: (i) => {
+        const row = Math.floor(i / 7);
+        const col = i % 7;
+        return { h: 40 + row * 5 + col * 4, s: 85, b: 80 };
+    },
+    ocean: (i) => {
+        const row = Math.floor(i / 7);
+        const col = i % 7;
+        return { h: 180 + row * 8 + col * 3, s: 75, b: 70 };
+    },
+    sunset: (i) => {
+        const row = Math.floor(i / 7);
+        return { h: 10 + row * 5, s: 90, b: 85 - row * 5 };
+    },
+    off: () => ({ h: 0, s: 0, b: 0 })
+};
+function applyScene(grid, sceneName) {
+    const generator = exports.scenes[sceneName];
+    if (!generator)
+        return;
+    for (let i = 0; i < grid_1.NUM_CANNONS; i++) {
+        const { h, s, b } = generator(i, grid_1.NUM_CANNONS);
+        (0, grid_1.setCannonTarget)(grid, i, h, s, b);
+    }
+}

package/server.d.ts

@@ -0,0 +1,5 @@
+import http from 'http';
+import { CannonTarget } from './grid';
+declare const grid: CannonTarget[];
+declare const server: http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+export { server, grid };

package/server.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.grid = exports.server = void 0;
+const http_1 = __importDefault(require("http"));
+const ws_1 = require("ws");
+const grid_1 = require("./grid");
+const scenes_1 = require("./scenes");
+const ui_1 = require("./ui");
+const PORT = parseInt(process.env.PORT || '3000', 10);
+const TICK_MS = 1000 / 60; // 60fps interpolation
+const grid = (0, grid_1.createGrid)();
+exports.grid = grid;
+const server = http_1.default.createServer((_req, res) => {
+    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+    res.end((0, ui_1.getHTML)());
+});
+exports.server = server;
+const wss = new ws_1.WebSocketServer({ server });
+function broadcastState() {
+    const payload = JSON.stringify({
+        type: 'state',
+        grid: grid.map(c => ({ h: c.h, s: c.s, b: c.b }))
+    });
+    wss.clients.forEach(client => {
+        if (client.readyState === ws_1.WebSocket.OPEN) {
+            client.send(payload);
+        }
+    });
+}
+wss.on('connection', (ws) => {
+    // Send initial state
+    ws.send(JSON.stringify({
+        type: 'state',
+        grid: grid.map(c => ({ h: c.h, s: c.s, b: c.b }))
+    }));
+    ws.on('message', (raw) => {
+        try {
+            const msg = JSON.parse(raw.toString());
+            handleMessage(msg);
+        }
+        catch (_e) {
+            // ignore malformed messages
+        }
+    });
+});
+function handleMessage(msg) {
+    switch (msg.type) {
+        case 'cannon':
+            (0, grid_1.setCannonTarget)(grid, msg.index, msg.h ?? undefined, msg.s ?? undefined, msg.b ?? undefined);
+            break;
+        case 'master_brightness':
+            (0, grid_1.setAllTargets)(grid, undefined, undefined, msg.value * 100);
+            break;
+        case 'scene':
+            if (msg.name && scenes_1.scenes[msg.name]) {
+                (0, scenes_1.applyScene)(grid, msg.name);
+            }
+            break;
+        case 'selection':
+            if (Array.isArray(msg.indices)) {
+                for (const idx of msg.indices) {
+                    if (idx >= 0 && idx < grid.length) {
+                        (0, grid_1.setCannonTarget)(grid, idx, msg.h ?? undefined, msg.s ?? undefined, msg.b ?? undefined);
+                    }
+                }
+            }
+            break;
+    }
+}
+// Animation loop: tick interpolation and broadcast
+setInterval(() => {
+    const changed = (0, grid_1.tickGrid)(grid);
+    if (changed) {
+        broadcastState();
+    }
+}, TICK_MS);
+server.listen(PORT, '0.0.0.0', () => {
+    console.log('');
+    console.log('╔══════════════════════════════════════════╗');
+    console.log('║   Illuminate · 7×7 Grid Simulator       ║');
+    console.log('║   49 virtual cannons ready               ║');
+    console.log('╚══════════════════════════════════════════╝');
+    console.log('');
+    console.log(`  → http://localhost:${PORT}`);
+    console.log('');
+});

package/ui.d.ts

@@ -0,0 +1 @@
+export declare function getHTML(): string;

package/ui.js

@@ -0,0 +1,357 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getHTML = getHTML;
+const scenes_1 = require("./scenes");
+function getHTML() {
+    const sceneNames = Object.keys(scenes_1.scenes);
+    return `<!DOCTYPE html>
+<html>
+<head>
+  <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
+  <title>Illuminate · 7×7 Simulator</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      background: #0a0a0a; color: #eee; padding: 1rem;
+      min-height: 100vh;
+    }
+    h1 {
+      font-size: 1.1rem; font-weight: 600; margin-bottom: 1rem;
+      color: #ccc; letter-spacing: 0.03em;
+    }
+    .master {
+      background: #141414; border: 1px solid #2a2a2a; border-radius: 12px;
+      padding: 1rem; margin-bottom: 1.25rem;
+    }
+    .section-title {
+      font-size: 0.7rem; color: #666; text-transform: uppercase;
+      letter-spacing: 0.08em; margin-bottom: 0.75rem;
+    }
+    .scene-row { display: flex; gap: 6px; flex-wrap: wrap; margin-bottom: 0.75rem; }
+    .scene-btn {
+      padding: 6px 14px; border-radius: 20px; font-size: 0.75rem;
+      cursor: pointer; border: 1px solid #333; background: #1a1a1a;
+      color: #aaa; transition: all 0.2s;
+    }
+    .scene-btn:hover { border-color: #555; color: #ddd; }
+    .scene-btn.active { background: #1a3a6a; border-color: #3a6acc; color: #fff; }
+    .slider-row {
+      display: flex; align-items: center; gap: 10px; margin-bottom: 0.6rem;
+    }
+    .slider-row label {
+      font-size: 0.8rem; color: #777; min-width: 80px;
+    }
+    .slider-row input[type=range] {
+      flex: 1; height: 6px; -webkit-appearance: none; appearance: none;
+      background: #333; border-radius: 3px; outline: none;
+    }
+    .slider-row input[type=range]::-webkit-slider-thumb {
+      -webkit-appearance: none; width: 18px; height: 18px;
+      border-radius: 50%; background: #4a8cde; cursor: pointer;
+    }
+    .slider-row .val {
+      font-size: 0.8rem; font-weight: 500; min-width: 38px; text-align: right; color: #888;
+    }
+    .all-off {
+      width: 100%; padding: 10px; border-radius: 8px; margin-top: 0.5rem;
+      background: #1a0808; border: 1px solid #3a1515; color: #c44;
+      font-size: 0.85rem; font-weight: 500; cursor: pointer; text-align: center;
+      transition: background 0.2s;
+    }
+    .all-off:hover { background: #2a1010; }
+
+    .grid-section { margin-bottom: 1.25rem; }
+    .sel-actions { display: flex; gap: 6px; margin-bottom: 0.5rem; }
+    .sel-btn {
+      font-size: 0.7rem; padding: 5px 10px;
+      border: 1px solid #333; border-radius: 6px;
+      background: #1a1a1a; color: #aaa; cursor: pointer;
+      transition: all 0.15s;
+    }
+    .sel-btn:hover { border-color: #555; color: #ddd; }
+    .rc-btns { display: flex; gap: 4px; flex-wrap: wrap; margin-bottom: 0.6rem; }
+    .rc-btn {
+      font-size: 0.65rem; padding: 4px 8px;
+      border: 1px solid #1a2a4a; border-radius: 5px;
+      background: #0e1520; color: #5a8abb; cursor: pointer;
+      transition: all 0.15s;
+    }
+    .rc-btn:hover { background: #152030; border-color: #2a4a7a; }
+
+    .grid {
+      display: grid;
+      grid-template-columns: repeat(7, 1fr);
+      gap: 4px;
+      max-width: 420px;
+    }
+    .cell {
+      aspect-ratio: 1; border-radius: 8px;
+      border: 1.5px solid #222; background: #111;
+      display: flex; flex-direction: column;
+      align-items: center; justify-content: center;
+      cursor: pointer; transition: border-color 0.15s, transform 0.1s;
+      position: relative;
+    }
+    .cell:active { transform: scale(0.95); }
+    .cell.selected { border-color: #4a8cde; }
+    .cell-beam {
+      width: 60%; height: 60%; border-radius: 50%;
+      transition: none; /* driven by animation frame */
+    }
+    .cell-num {
+      font-size: 7px; color: #444; margin-top: 2px;
+      position: absolute; bottom: 3px;
+    }
+
+    .panel {
+      background: #141414; border: 1px solid #2a2a2a; border-radius: 12px;
+      padding: 1rem; display: none; margin-bottom: 1rem;
+    }
+    .panel.visible { display: block; }
+    .panel-header {
+      display: flex; align-items: center; justify-content: space-between;
+      margin-bottom: 0.75rem;
+    }
+    .panel-title { font-size: 0.9rem; font-weight: 500; }
+    .done-btn {
+      font-size: 0.7rem; padding: 4px 10px;
+      border: 1px solid #333; border-radius: 6px;
+      background: #1a1a1a; color: #aaa; cursor: pointer;
+    }
+
+    .status {
+      font-size: 0.65rem; color: #444; text-align: center; padding-top: 0.5rem;
+    }
+  </style>
+</head>
+<body>
+
+<h1>Illuminate · 7×7 Civic Center</h1>
+
+<div class="master">
+  <div class="section-title">Scenes</div>
+  <div class="scene-row" id="scene-row">
+    ${sceneNames.map((name, i) => `<button class="scene-btn${i === 0 ? ' active' : ''}" data-scene="${name}">${name}</button>`).join('\n    ')}
+  </div>
+  <div class="section-title" style="margin-top:0.75rem">Master</div>
+  <div class="slider-row">
+    <label>Brightness</label>
+    <input type="range" min="0" max="100" value="80" id="master-bright">
+    <span class="val" id="master-bright-val">80%</span>
+  </div>
+  <div class="all-off" id="all-off">All Off</div>
+</div>
+
+<div class="grid-section">
+  <div class="section-title">Cannon Grid — tap to select</div>
+  <div class="sel-actions">
+    <button class="sel-btn" id="sel-all">Select All</button>
+    <button class="sel-btn" id="sel-none">Clear</button>
+  </div>
+  <div class="rc-btns" id="rc-btns"></div>
+  <div class="grid" id="cannon-grid"></div>
+</div>
+
+<div class="panel" id="panel">
+  <div class="panel-header">
+    <span class="panel-title" id="panel-title">Cannon 1</span>
+    <button class="done-btn" id="done-btn">Done</button>
+  </div>
+  <div class="slider-row">
+    <label>Brightness</label>
+    <input type="range" min="0" max="100" value="80" id="panel-bright">
+    <span class="val" id="panel-bright-val">80%</span>
+  </div>
+  <div class="slider-row">
+    <label>Hue</label>
+    <input type="range" min="0" max="360" value="220" id="panel-hue">
+    <span class="val" id="panel-hue-val">220°</span>
+  </div>
+  <div class="slider-row">
+    <label>Saturation</label>
+    <input type="range" min="0" max="100" value="90" id="panel-sat">
+    <span class="val" id="panel-sat-val">90%</span>
+  </div>
+</div>
+
+<div class="status" id="status">Connecting...</div>
+
+<script>
+const NUM = 49;
+const ws = new WebSocket('ws://' + location.host);
+const status = document.getElementById('status');
+const selected = new Set();
+
+// Local display state (smoothly updated from server)
+const display = Array.from({length: NUM}, () => ({ h: 220, s: 90, b: 80 }));
+
+ws.onopen = () => { status.textContent = 'Connected · 49 cannons · smooth mode'; };
+ws.onclose = () => { status.textContent = 'Disconnected — reload page'; };
+
+ws.onmessage = (e) => {
+  const msg = JSON.parse(e.data);
+  if (msg.type === 'state') {
+    for (let i = 0; i < NUM; i++) {
+      display[i].h = msg.grid[i].h;
+      display[i].s = msg.grid[i].s;
+      display[i].b = msg.grid[i].b;
+    }
+  }
+};
+
+function send(data) {
+  if (ws.readyState === 1) ws.send(JSON.stringify(data));
+}
+
+function hslToHex(h, s, l) {
+  s /= 100; l /= 100;
+  const a = s * Math.min(l, 1 - l);
+  const f = n => { const k = (n + h / 30) % 12; return l - a * Math.max(Math.min(k - 3, 9 - k, 1), -1); };
+  const r = Math.round(255 * f(0));
+  const g = Math.round(255 * f(8));
+  const b = Math.round(255 * f(4));
+  return '#' + [r, g, b].map(v => v.toString(16).padStart(2, '0')).join('');
+}
+
+// Build grid
+const gridEl = document.getElementById('cannon-grid');
+for (let i = 0; i < NUM; i++) {
+  const cell = document.createElement('div');
+  cell.className = 'cell';
+  cell.id = 'cell-' + i;
+  cell.innerHTML = '<div class="cell-beam" id="beam-' + i + '"></div><span class="cell-num">' + (i + 1) + '</span>';
+  cell.addEventListener('click', () => toggleSelect(i));
+  gridEl.appendChild(cell);
+}
+
+// Build row/col buttons
+const rcEl = document.getElementById('rc-btns');
+for (let r = 0; r < 7; r++) {
+  const btn = document.createElement('button');
+  btn.className = 'rc-btn';
+  btn.textContent = 'R' + (r + 1);
+  btn.addEventListener('click', () => {
+    for (let c = 0; c < 7; c++) selectOn(r * 7 + c);
+    updatePanel();
+  });
+  rcEl.appendChild(btn);
+}
+for (let c = 0; c < 7; c++) {
+  const btn = document.createElement('button');
+  btn.className = 'rc-btn';
+  btn.textContent = 'C' + (c + 1);
+  btn.addEventListener('click', () => {
+    for (let r = 0; r < 7; r++) selectOn(r * 7 + c);
+    updatePanel();
+  });
+  rcEl.appendChild(btn);
+}
+
+function selectOn(idx) {
+  selected.add(idx);
+  document.getElementById('cell-' + idx).classList.add('selected');
+}
+
+function toggleSelect(idx) {
+  if (selected.has(idx)) {
+    selected.delete(idx);
+    document.getElementById('cell-' + idx).classList.remove('selected');
+  } else {
+    selected.add(idx);
+    document.getElementById('cell-' + idx).classList.add('selected');
+  }
+  updatePanel();
+}
+
+function updatePanel() {
+  const panel = document.getElementById('panel');
+  const title = document.getElementById('panel-title');
+  if (selected.size === 0) {
+    panel.classList.remove('visible');
+  } else {
+    panel.classList.add('visible');
+    title.textContent = selected.size === 1
+      ? 'Cannon ' + ([...selected][0] + 1)
+      : selected.size + ' cannons selected';
+  }
+}
+
+// Selection controls
+document.getElementById('sel-all').addEventListener('click', () => {
+  for (let i = 0; i < NUM; i++) selectOn(i);
+  updatePanel();
+});
+document.getElementById('sel-none').addEventListener('click', () => {
+  selected.forEach(idx => document.getElementById('cell-' + idx).classList.remove('selected'));
+  selected.clear();
+  updatePanel();
+});
+document.getElementById('done-btn').addEventListener('click', () => {
+  selected.forEach(idx => document.getElementById('cell-' + idx).classList.remove('selected'));
+  selected.clear();
+  updatePanel();
+});
+
+// Master brightness
+document.getElementById('master-bright').addEventListener('input', function() {
+  const v = parseInt(this.value);
+  document.getElementById('master-bright-val').textContent = v + '%';
+  send({ type: 'master_brightness', value: v / 100 });
+});
+
+// All off
+document.getElementById('all-off').addEventListener('click', () => {
+  document.getElementById('master-bright').value = 0;
+  document.getElementById('master-bright-val').textContent = '0%';
+  send({ type: 'master_brightness', value: 0 });
+});
+
+// Per-cannon controls
+document.getElementById('panel-bright').addEventListener('input', function() {
+  const v = parseInt(this.value);
+  document.getElementById('panel-bright-val').textContent = v + '%';
+  send({ type: 'selection', indices: [...selected], b: v });
+});
+document.getElementById('panel-hue').addEventListener('input', function() {
+  const v = parseInt(this.value);
+  document.getElementById('panel-hue-val').textContent = v + '°';
+  send({ type: 'selection', indices: [...selected], h: v });
+});
+document.getElementById('panel-sat').addEventListener('input', function() {
+  const v = parseInt(this.value);
+  document.getElementById('panel-sat-val').textContent = v + '%';
+  send({ type: 'selection', indices: [...selected], s: v });
+});
+
+// Scenes
+document.getElementById('scene-row').addEventListener('click', (e) => {
+  const btn = e.target.closest('.scene-btn');
+  if (!btn) return;
+  document.querySelectorAll('.scene-btn').forEach(b => b.classList.remove('active'));
+  btn.classList.add('active');
+  send({ type: 'scene', name: btn.dataset.scene });
+});
+
+// Render loop — updates beams from display state
+function render() {
+  for (let i = 0; i < NUM; i++) {
+    const c = display[i];
+    const beam = document.getElementById('beam-' + i);
+    if (beam) {
+      const lightness = Math.max(5, c.b * 0.5);
+      beam.style.background = c.b < 1
+        ? '#111'
+        : hslToHex(c.h, c.s, lightness);
+      beam.style.boxShadow = c.b > 20
+        ? '0 0 ' + (c.b * 0.15) + 'px ' + hslToHex(c.h, c.s, lightness)
+        : 'none';
+    }
+  }
+  requestAnimationFrame(render);
+}
+requestAnimationFrame(render);
+</script>
+</body>
+</html>`;
+}