feat: even more matrix stream examples

2025-10-02 22:08:40 +02:00
parent d1fb5fc96e
commit 1383f6d32f
8 changed files with 694 additions and 2 deletions
--- a/examples/pixelstream/main.cpp
+++ b/examples/pixelstream/main.cpp
@@ -12,7 +12,7 @@
 #endif

 #ifndef PIXEL_BRIGHTNESS
-#define PIXEL_BRIGHTNESS 50
+#define PIXEL_BRIGHTNESS 80
 #endif

 #ifndef PIXEL_MATRIX_WIDTH
--- a/test/package.json
+++ b/test/package.json
@@ -9,6 +9,11 @@
    "pixelstream:lava-lamp": "node pixelstream/lava-lamp.js",
    "pixelstream:meteor-rain": "node pixelstream/meteor-rain.js",
    "pixelstream:spiral-bloom": "node pixelstream/spiral-bloom.js",
-    "pixelstream:ocean-glimmer": "node pixelstream/ocean-glimmer.js"
+    "pixelstream:ocean-glimmer": "node pixelstream/ocean-glimmer.js",
+    "pixelstream:nebula-drift": "node pixelstream/nebula-drift.js",
+    "pixelstream:voxel-fireflies": "node pixelstream/voxel-fireflies.js",
+    "pixelstream:wormhole-tunnel": "node pixelstream/wormhole-tunnel.js",
+    "pixelstream:circuit-pulse": "node pixelstream/circuit-pulse.js",
+    "pixelstream:aurora-curtains": "node pixelstream/aurora-curtains.js"
  }
 }
--- a/test/pixelstream/aurora-curtains.js
+++ b/test/pixelstream/aurora-curtains.js
@@ -0,0 +1,115 @@
+const dgram = require('dgram');
+
+const {
+  clamp,
+  createFrame,
+  frameToPayload,
+  hexToRgb,
+  samplePalette,
+  toIndex,
+} = require('./shared-frame-utils');
+
+const DEFAULT_PORT = 4210;
+const DEFAULT_WIDTH = 16;
+const DEFAULT_HEIGHT = 16;
+const DEFAULT_INTERVAL_MS = 65;
+const BAND_COUNT = 5;
+const WAVE_SPEED = 0.35;
+const HORIZONTAL_SWAY = 0.45;
+
+const paletteStops = [
+  { stop: 0.0, color: hexToRgb('01010a') },
+  { stop: 0.2, color: hexToRgb('041332') },
+  { stop: 0.4, color: hexToRgb('0c3857') },
+  { stop: 0.65, color: hexToRgb('1aa07a') },
+  { stop: 0.85, color: hexToRgb('68d284') },
+  { stop: 1.0, color: hexToRgb('f4f5c6') },
+];
+
+const host = process.argv[2];
+const port = parseInt(process.argv[3] || String(DEFAULT_PORT), 10);
+const width = parseInt(process.argv[4] || String(DEFAULT_WIDTH), 10);
+const height = parseInt(process.argv[5] || String(DEFAULT_HEIGHT), 10);
+const intervalMs = parseInt(process.argv[6] || String(DEFAULT_INTERVAL_MS), 10);
+
+if (!host) {
+  console.error('Usage: node aurora-curtains.js <device-ip> [port] [width] [height] [interval-ms]');
+  process.exit(1);
+}
+
+if (Number.isNaN(port) || Number.isNaN(width) || Number.isNaN(height) || Number.isNaN(intervalMs)) {
+  console.error('Invalid numeric argument. Expected integers for port, width, height, and interval-ms.');
+  process.exit(1);
+}
+
+if (width <= 0 || height <= 0) {
+  console.error('Matrix dimensions must be positive integers.');
+  process.exit(1);
+}
+
+const socket = dgram.createSocket('udp4');
+const isBroadcast = host === '255.255.255.255' || host.endsWith('.255');
+const frame = createFrame(width, height);
+const bands = createBands(BAND_COUNT, width);
+let timeSeconds = 0;
+const frameTimeSeconds = intervalMs / 1000;
+
+if (isBroadcast) {
+  socket.bind(() => {
+    socket.setBroadcast(true);
+  });
+}
+
+socket.on('error', (error) => {
+  console.error('Socket error:', error.message);
+});
+
+function createBands(count, matrixWidth) {
+  const generatedBands = [];
+  for (let index = 0; index < count; ++index) {
+    generatedBands.push({
+      center: Math.random() * (matrixWidth - 1),
+      phase: Math.random() * Math.PI * 2,
+      width: 1.2 + Math.random() * 1.8,
+    });
+  }
+  return generatedBands;
+}
+
+function generateFrame() {
+  timeSeconds += frameTimeSeconds;
+
+  for (let row = 0; row < height; ++row) {
+    const verticalRatio = row / Math.max(1, height - 1);
+    for (let col = 0; col < width; ++col) {
+      let intensity = 0;
+
+      bands.forEach((band, index) => {
+        const sway = Math.sin(timeSeconds * WAVE_SPEED + band.phase + verticalRatio * Math.PI * 2) * HORIZONTAL_SWAY;
+        const center = band.center + sway * (index % 2 === 0 ? 1 : -1);
+        const distance = Math.abs(col - center);
+        const blurred = Math.exp(-(distance * distance) / (2 * band.width * band.width));
+        intensity += blurred * (0.8 + Math.sin(timeSeconds * 0.4 + index) * 0.2);
+      });
+
+      const normalized = clamp(intensity / bands.length, 0, 1);
+      const gradientBlend = clamp((normalized * 0.7 + verticalRatio * 0.3), 0, 1);
+      frame[toIndex(col, row, width)] = samplePalette(paletteStops, gradientBlend);
+    }
+  }
+
+  return frameToPayload(frame);
+}
+
+function sendFrame() {
+  const payload = generateFrame();
+  const message = Buffer.from(payload, 'utf8');
+  socket.send(message, port, host);
+}
+
+setInterval(sendFrame, intervalMs);
+
+console.log(
+  `Streaming aurora curtains to ${host}:${port} (${width}x${height}, interval=${intervalMs}ms)`
+);
+
--- a/test/pixelstream/circuit-pulse.js
+++ b/test/pixelstream/circuit-pulse.js
@@ -0,0 +1,166 @@
+const dgram = require('dgram');
+
+const {
+  addHexColor,
+  createFrame,
+  fadeFrame,
+  frameToPayload,
+  hexToRgb,
+  samplePalette,
+  toIndex,
+} = require('./shared-frame-utils');
+
+const DEFAULT_PORT = 4210;
+const DEFAULT_WIDTH = 16;
+const DEFAULT_HEIGHT = 16;
+const DEFAULT_INTERVAL_MS = 50;
+const PATH_FADE = 0.85;
+const PULSE_LENGTH = 6;
+
+const paletteStops = [
+  { stop: 0.0, color: hexToRgb('020209') },
+  { stop: 0.3, color: hexToRgb('023047') },
+  { stop: 0.6, color: hexToRgb('115173') },
+  { stop: 0.8, color: hexToRgb('1ca78f') },
+  { stop: 1.0, color: hexToRgb('94fdf3') },
+];
+
+const accentColors = ['14f5ff', 'a7ff4d', 'ffcc3f'];
+
+const host = process.argv[2];
+const port = parseInt(process.argv[3] || String(DEFAULT_PORT), 10);
+const width = parseInt(process.argv[4] || String(DEFAULT_WIDTH), 10);
+const height = parseInt(process.argv[5] || String(DEFAULT_HEIGHT), 10);
+const intervalMs = parseInt(process.argv[6] || String(DEFAULT_INTERVAL_MS), 10);
+
+if (!host) {
+  console.error('Usage: node circuit-pulse.js <device-ip> [port] [width] [height] [interval-ms]');
+  process.exit(1);
+}
+
+if (Number.isNaN(port) || Number.isNaN(width) || Number.isNaN(height) || Number.isNaN(intervalMs)) {
+  console.error('Invalid numeric argument. Expected integers for port, width, height, and interval-ms.');
+  process.exit(1);
+}
+
+if (width <= 0 || height <= 0) {
+  console.error('Matrix dimensions must be positive integers.');
+  process.exit(1);
+}
+
+const socket = dgram.createSocket('udp4');
+const isBroadcast = host === '255.255.255.255' || host.endsWith('.255');
+const frame = createFrame(width, height);
+const paths = createPaths(width, height);
+const pulses = createPulses(paths.length);
+const frameTimeSeconds = intervalMs / 1000;
+
+if (isBroadcast) {
+  socket.bind(() => {
+    socket.setBroadcast(true);
+  });
+}
+
+socket.on('error', (error) => {
+  console.error('Socket error:', error.message);
+});
+
+function createPaths(matrixWidth, matrixHeight) {
+  const horizontalStep = Math.max(2, Math.floor(matrixHeight / 4));
+  const verticalStep = Math.max(2, Math.floor(matrixWidth / 4));
+  const generatedPaths = [];
+
+  for (let y = 1; y < matrixHeight; y += horizontalStep) {
+    const path = [];
+    for (let x = 0; x < matrixWidth; ++x) {
+      path.push({ x, y });
+    }
+    generatedPaths.push(path);
+  }
+
+  for (let x = 2; x < matrixWidth; x += verticalStep) {
+    const path = [];
+    for (let y = 0; y < matrixHeight; ++y) {
+      path.push({ x, y });
+    }
+    generatedPaths.push(path);
+  }
+
+  return generatedPaths;
+}
+
+function createPulses(count) {
+  const pulseList = [];
+  for (let index = 0; index < count; ++index) {
+    pulseList.push(spawnPulse(index));
+  }
+  return pulseList;
+}
+
+function spawnPulse(pathIndex) {
+  const color = accentColors[pathIndex % accentColors.length];
+  return {
+    pathIndex,
+    position: 0,
+    speed: 3 + Math.random() * 2,
+    color,
+  };
+}
+
+function updatePulse(pulse, deltaSeconds) {
+  pulse.position += pulse.speed * deltaSeconds;
+  const path = paths[pulse.pathIndex];
+
+  if (!path || path.length === 0) {
+    return;
+  }
+
+  if (pulse.position >= path.length + PULSE_LENGTH) {
+    Object.assign(pulse, spawnPulse(pulse.pathIndex));
+    pulse.position = 0;
+  }
+}
+
+function renderPulse(pulse) {
+  const path = paths[pulse.pathIndex];
+  if (!path) {
+    return;
+  }
+
+  for (let offset = 0; offset < PULSE_LENGTH; ++offset) {
+    const index = Math.floor(pulse.position) - offset;
+    if (index < 0 || index >= path.length) {
+      continue;
+    }
+
+    const { x, y } = path[index];
+    const intensity = Math.max(0, 1 - offset / PULSE_LENGTH);
+    const baseColor = samplePalette(paletteStops, intensity);
+    frame[toIndex(x, y, width)] = baseColor;
+    addHexColor(frame, toIndex(x, y, width), pulse.color, intensity * 1.4);
+  }
+}
+
+function generateFrame() {
+  fadeFrame(frame, PATH_FADE);
+
+  pulses.forEach((pulse) => {
+    updatePulse(pulse, frameTimeSeconds);
+    renderPulse(pulse);
+  });
+
+  return frameToPayload(frame);
+}
+
+function sendFrame() {
+  const payload = generateFrame();
+  const message = Buffer.from(payload, 'utf8');
+  socket.send(message, port, host);
+}
+
+setInterval(sendFrame, intervalMs);
+
+console.log(
+  `Streaming circuit pulse to ${host}:${port} (${width}x${height}, interval=${intervalMs}ms, paths=${paths.length})`
+);
+
--- a/test/pixelstream/nebula-drift.js
+++ b/test/pixelstream/nebula-drift.js
@@ -0,0 +1,104 @@
+const dgram = require('dgram');
+
+const {
+  clamp,
+  createFrame,
+  fadeFrame,
+  frameToPayload,
+  hexToRgb,
+  samplePalette,
+  toIndex,
+} = require('./shared-frame-utils');
+
+const DEFAULT_PORT = 4210;
+const DEFAULT_WIDTH = 16;
+const DEFAULT_HEIGHT = 16;
+const DEFAULT_INTERVAL_MS = 70;
+const PRIMARY_SPEED = 0.15;
+const SECONDARY_SPEED = 0.32;
+const WAVE_SCALE = 0.75;
+
+const paletteStops = [
+  { stop: 0.0, color: hexToRgb('100406') },
+  { stop: 0.25, color: hexToRgb('2e0f1f') },
+  { stop: 0.5, color: hexToRgb('6a1731') },
+  { stop: 0.7, color: hexToRgb('b63b32') },
+  { stop: 0.85, color: hexToRgb('f48b2a') },
+  { stop: 1.0, color: hexToRgb('ffe9b0') },
+];
+
+const host = process.argv[2];
+const port = parseInt(process.argv[3] || String(DEFAULT_PORT), 10);
+const width = parseInt(process.argv[4] || String(DEFAULT_WIDTH), 10);
+const height = parseInt(process.argv[5] || String(DEFAULT_HEIGHT), 10);
+const intervalMs = parseInt(process.argv[6] || String(DEFAULT_INTERVAL_MS), 10);
+
+if (!host) {
+  console.error('Usage: node nebula-drift.js <device-ip> [port] [width] [height] [interval-ms]');
+  process.exit(1);
+}
+
+if (Number.isNaN(port) || Number.isNaN(width) || Number.isNaN(height) || Number.isNaN(intervalMs)) {
+  console.error('Invalid numeric argument. Expected integers for port, width, height, and interval-ms.');
+  process.exit(1);
+}
+
+if (width <= 0 || height <= 0) {
+  console.error('Matrix dimensions must be positive integers.');
+  process.exit(1);
+}
+
+const socket = dgram.createSocket('udp4');
+const isBroadcast = host === '255.255.255.255' || host.endsWith('.255');
+const frame = createFrame(width, height);
+let timeSeconds = 0;
+const frameTimeSeconds = intervalMs / 1000;
+
+if (isBroadcast) {
+  socket.bind(() => {
+    socket.setBroadcast(true);
+  });
+}
+
+socket.on('error', (error) => {
+  console.error('Socket error:', error.message);
+});
+
+function layeredWave(u, v, speed, offset) {
+  return Math.sin((u * 3 + v * 2) * Math.PI * WAVE_SCALE + timeSeconds * speed + offset);
+}
+
+function generateFrame() {
+  timeSeconds += frameTimeSeconds;
+
+  for (let row = 0; row < height; ++row) {
+    const v = row / Math.max(1, height - 1);
+    for (let col = 0; col < width; ++col) {
+      const u = col / Math.max(1, width - 1);
+      const primary = layeredWave(u, v, PRIMARY_SPEED, 0);
+      const secondary = layeredWave(v, u, SECONDARY_SPEED, Math.PI / 4);
+      const tertiary = Math.sin((u + v) * Math.PI * 1.5 + timeSeconds * 0.18);
+
+      const combined = 0.45 * primary + 0.35 * secondary + 0.2 * tertiary;
+      const envelope = Math.sin((u * v) * Math.PI * 2 + timeSeconds * 0.1) * 0.25 + 0.75;
+      const value = clamp((combined * 0.5 + 0.5) * envelope, 0, 1);
+
+      frame[toIndex(col, row, width)] = samplePalette(paletteStops, value);
+    }
+  }
+
+  return frameToPayload(frame);
+}
+
+function sendFrame() {
+  const payload = generateFrame();
+  const message = Buffer.from(payload, 'utf8');
+  socket.send(message, port, host);
+}
+
+setInterval(sendFrame, intervalMs);
+
+console.log(
+  `Streaming nebula drift to ${host}:${port} (${width}x${height}, interval=${intervalMs}ms)`
+);
+
--- a/test/pixelstream/shared-frame-utils.js
+++ b/test/pixelstream/shared-frame-utils.js
@@ -74,6 +74,33 @@ function fadeFrame(frame, factor) {
  }
 }

+function addRgbToFrame(frame, index, rgb) {
+  if (index < 0 || index >= frame.length) {
+    return;
+  }
+
+  const current = hexToRgb(frame[index]);
+  const updated = {
+    r: clamp(current.r + rgb.r, 0, 255),
+    g: clamp(current.g + rgb.g, 0, 255),
+    b: clamp(current.b + rgb.b, 0, 255),
+  };
+  frame[index] = rgbToHex(updated);
+}
+
+function addHexColor(frame, index, hexColor, intensity = 1) {
+  if (intensity <= 0) {
+    return;
+  }
+
+  const base = hexToRgb(hexColor);
+  addRgbToFrame(frame, index, {
+    r: base.r * intensity,
+    g: base.g * intensity,
+    b: base.b * intensity,
+  });
+}
+
 module.exports = {
  SERPENTINE_WIRING,
  clamp,
@@ -85,5 +112,7 @@ module.exports = {
  createFrame,
  frameToPayload,
  fadeFrame,
+  addRgbToFrame,
+  addHexColor,
 };

--- a/test/pixelstream/voxel-fireflies.js
+++ b/test/pixelstream/voxel-fireflies.js
@@ -0,0 +1,165 @@
+const dgram = require('dgram');
+
+const {
+  addHexColor,
+  clamp,
+  createFrame,
+  fadeFrame,
+  frameToPayload,
+  hexToRgb,
+  samplePalette,
+  toIndex,
+} = require('./shared-frame-utils');
+
+const DEFAULT_PORT = 4210;
+const DEFAULT_WIDTH = 16;
+const DEFAULT_HEIGHT = 16;
+const DEFAULT_INTERVAL_MS = 55;
+const DEFAULT_FIREFLY_COUNT = 18;
+const HOVER_SPEED = 0.6;
+const GLOW_SPEED = 1.8;
+const TRAIL_DECAY = 0.8;
+
+const paletteStops = [
+  { stop: 0.0, color: hexToRgb('02030a') },
+  { stop: 0.2, color: hexToRgb('031c2d') },
+  { stop: 0.4, color: hexToRgb('053d4a') },
+  { stop: 0.6, color: hexToRgb('107b68') },
+  { stop: 0.8, color: hexToRgb('14c491') },
+  { stop: 1.0, color: hexToRgb('f2ffd2') },
+];
+
+const host = process.argv[2];
+const port = parseInt(process.argv[3] || String(DEFAULT_PORT), 10);
+const width = parseInt(process.argv[4] || String(DEFAULT_WIDTH), 10);
+const height = parseInt(process.argv[5] || String(DEFAULT_HEIGHT), 10);
+const intervalMs = parseInt(process.argv[6] || String(DEFAULT_INTERVAL_MS), 10);
+const fireflyCount = parseInt(process.argv[7] || String(DEFAULT_FIREFLY_COUNT), 10);
+
+if (!host) {
+  console.error('Usage: node voxel-fireflies.js <device-ip> [port] [width] [height] [interval-ms] [firefly-count]');
+  process.exit(1);
+}
+
+if (Number.isNaN(port) || Number.isNaN(width) || Number.isNaN(height) || Number.isNaN(intervalMs) || Number.isNaN(fireflyCount)) {
+  console.error('Invalid numeric argument. Expected integers for port, width, height, interval-ms, and firefly-count.');
+  process.exit(1);
+}
+
+if (width <= 0 || height <= 0) {
+  console.error('Matrix dimensions must be positive integers.');
+  process.exit(1);
+}
+
+if (fireflyCount <= 0) {
+  console.error('Firefly count must be a positive integer.');
+  process.exit(1);
+}
+
+const socket = dgram.createSocket('udp4');
+const isBroadcast = host === '255.255.255.255' || host.endsWith('.255');
+const frame = createFrame(width, height);
+const fireflies = createFireflies(fireflyCount, width, height);
+const frameTimeSeconds = intervalMs / 1000;
+
+if (isBroadcast) {
+  socket.bind(() => {
+    socket.setBroadcast(true);
+  });
+}
+
+socket.on('error', (error) => {
+  console.error('Socket error:', error.message);
+});
+
+function createFireflies(count, matrixWidth, matrixHeight) {
+  const list = [];
+  for (let index = 0; index < count; ++index) {
+    list.push(spawnFirefly(matrixWidth, matrixHeight));
+  }
+  return list;
+}
+
+function spawnFirefly(matrixWidth, matrixHeight) {
+  return {
+    x: Math.random() * (matrixWidth - 1),
+    y: Math.random() * (matrixHeight - 1),
+    targetX: Math.random() * (matrixWidth - 1),
+    targetY: Math.random() * (matrixHeight - 1),
+    glowPhase: Math.random() * Math.PI * 2,
+    dwell: 1 + Math.random() * 2,
+  };
+}
+
+function updateFirefly(firefly, deltaSeconds) {
+  const dx = firefly.targetX - firefly.x;
+  const dy = firefly.targetY - firefly.y;
+  const distance = Math.hypot(dx, dy);
+
+  if (distance < 0.2) {
+    firefly.dwell -= deltaSeconds;
+    if (firefly.dwell <= 0) {
+      firefly.targetX = Math.random() * (width - 1);
+      firefly.targetY = Math.random() * (height - 1);
+      firefly.dwell = 1 + Math.random() * 2;
+    }
+  } else {
+    const speed = HOVER_SPEED * (0.8 + Math.random() * 0.4);
+    firefly.x += (dx / distance) * speed * deltaSeconds;
+    firefly.y += (dy / distance) * speed * deltaSeconds;
+  }
+
+  firefly.glowPhase += deltaSeconds * GLOW_SPEED * (0.7 + Math.random() * 0.6);
+}
+
+function drawFirefly(firefly) {
+  const baseGlow = (Math.sin(firefly.glowPhase) + 1) * 0.5;
+  const col = Math.round(firefly.x);
+  const row = Math.round(firefly.y);
+
+  for (let dy = -1; dy <= 1; ++dy) {
+    for (let dx = -1; dx <= 1; ++dx) {
+      const sampleX = col + dx;
+      const sampleY = row + dy;
+      if (sampleX < 0 || sampleX >= width || sampleY < 0 || sampleY >= height) {
+        continue;
+      }
+
+      const distance = Math.hypot(dx, dy);
+      const falloff = clamp(1 - distance * 0.7, 0, 1);
+      const intensity = baseGlow * falloff;
+      if (intensity <= 0) {
+        continue;
+      }
+
+      frame[toIndex(sampleX, sampleY, width)] = samplePalette(paletteStops, intensity);
+      if (distance === 0) {
+        addHexColor(frame, toIndex(sampleX, sampleY, width), 'ffd966', intensity * 1.6);
+      }
+    }
+  }
+}
+
+function generateFrame() {
+  fadeFrame(frame, TRAIL_DECAY);
+
+  fireflies.forEach((firefly) => {
+    updateFirefly(firefly, frameTimeSeconds);
+    drawFirefly(firefly);
+  });
+
+  return frameToPayload(frame);
+}
+
+function sendFrame() {
+  const payload = generateFrame();
+  const message = Buffer.from(payload, 'utf8');
+  socket.send(message, port, host);
+}
+
+setInterval(sendFrame, intervalMs);
+
+console.log(
+  `Streaming voxel fireflies to ${host}:${port} (${width}x${height}, interval=${intervalMs}ms, fireflies=${fireflyCount})`
+);
+
--- a/test/pixelstream/wormhole-tunnel.js
+++ b/test/pixelstream/wormhole-tunnel.js
@@ -0,0 +1,108 @@
+const dgram = require('dgram');
+
+const {
+  clamp,
+  createFrame,
+  frameToPayload,
+  hexToRgb,
+  samplePalette,
+  toIndex,
+} = require('./shared-frame-utils');
+
+const DEFAULT_PORT = 4210;
+const DEFAULT_WIDTH = 16;
+const DEFAULT_HEIGHT = 16;
+const DEFAULT_INTERVAL_MS = 60;
+const RING_DENSITY = 8;
+const RING_SPEED = 1.4;
+const RING_SHARPNESS = 7.5;
+const TWIST_INTENSITY = 2.2;
+const TWIST_SPEED = 0.9;
+const CORE_EXPONENT = 1.6;
+
+const paletteStops = [
+  { stop: 0.0, color: hexToRgb('010005') },
+  { stop: 0.2, color: hexToRgb('07204f') },
+  { stop: 0.45, color: hexToRgb('124aa0') },
+  { stop: 0.7, color: hexToRgb('36a5ff') },
+  { stop: 0.87, color: hexToRgb('99e6ff') },
+  { stop: 1.0, color: hexToRgb('f1fbff') },
+];
+
+const host = process.argv[2];
+const port = parseInt(process.argv[3] || String(DEFAULT_PORT), 10);
+const width = parseInt(process.argv[4] || String(DEFAULT_WIDTH), 10);
+const height = parseInt(process.argv[5] || String(DEFAULT_HEIGHT), 10);
+const intervalMs = parseInt(process.argv[6] || String(DEFAULT_INTERVAL_MS), 10);
+
+if (!host) {
+  console.error('Usage: node wormhole-tunnel.js <device-ip> [port] [width] [height] [interval-ms]');
+  process.exit(1);
+}
+
+if (Number.isNaN(port) || Number.isNaN(width) || Number.isNaN(height) || Number.isNaN(intervalMs)) {
+  console.error('Invalid numeric argument. Expected integers for port, width, height, and interval-ms.');
+  process.exit(1);
+}
+
+if (width <= 0 || height <= 0) {
+  console.error('Matrix dimensions must be positive integers.');
+  process.exit(1);
+}
+
+const socket = dgram.createSocket('udp4');
+const isBroadcast = host === '255.255.255.255' || host.endsWith('.255');
+const frame = createFrame(width, height);
+let timeSeconds = 0;
+const frameTimeSeconds = intervalMs / 1000;
+
+if (isBroadcast) {
+  socket.bind(() => {
+    socket.setBroadcast(true);
+  });
+}
+
+socket.on('error', (error) => {
+  console.error('Socket error:', error.message);
+});
+
+function generateFrame() {
+  timeSeconds += frameTimeSeconds;
+
+  const cx = (width - 1) / 2;
+  const cy = (height - 1) / 2;
+  const radiusNorm = Math.hypot(cx, cy) || 1;
+
+  for (let row = 0; row < height; ++row) {
+    for (let col = 0; col < width; ++col) {
+      const dx = col - cx;
+      const dy = row - cy;
+      const radius = Math.hypot(dx, dy) / radiusNorm;
+      const angle = Math.atan2(dy, dx);
+
+      const radialPhase = radius * RING_DENSITY - timeSeconds * RING_SPEED;
+      const ring = Math.exp(-Math.pow(Math.sin(radialPhase * Math.PI), 2) * RING_SHARPNESS);
+
+      const twist = Math.sin(angle * TWIST_INTENSITY + timeSeconds * TWIST_SPEED) * 0.35 + 0.65;
+      const depth = Math.pow(clamp(1 - radius, 0, 1), CORE_EXPONENT);
+
+      const value = clamp(ring * 0.6 + depth * 0.3 + twist * 0.1, 0, 1);
+      frame[toIndex(col, row, width)] = samplePalette(paletteStops, value);
+    }
+  }
+
+  return frameToPayload(frame);
+}
+
+function sendFrame() {
+  const payload = generateFrame();
+  const message = Buffer.from(payload, 'utf8');
+  socket.send(message, port, host);
+}
+
+setInterval(sendFrame, intervalMs);
+
+console.log(
+  `Streaming wormhole tunnel to ${host}:${port} (${width}x${height}, interval=${intervalMs}ms)`
+);
+