@agenticros/eyes 1.0.0

package/README.md

@@ -0,0 +1,25 @@
+# @agenticros/eyes
+
+Fullscreen robot eyes for an Ubuntu tablet or robot display, driven by ROS 2 `cmd_vel` (`geometry_msgs/Twist`).
+
+Part of the [AgenticROS](https://github.com/agenticros/agenticros) monorepo. Prefer launching via the CLI:
+
+```bash
+agenticros eyes
+agenticros eyes --no-browser
+agenticros eyes --no-teleop          # gaze only (no WASD publish)
+agenticros up real --eyes            # start eyes after the real-robot stack
+```
+
+See [docs/eyes.md](../../docs/eyes.md) for setup, config, and keyboard teleop.
+
+## Direct run (development)
+
+```bash
+source /opt/ros/jazzy/setup.bash
+cd packages/robot-eyes
+pnpm install   # from monorepo root is preferred
+pnpm start
+```
+
+Requires Node 18+, ROS 2, and a graphical display (`DISPLAY`) for kiosk mode.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@agenticros/eyes",
+  "version": "1.0.0",
+  "description": "Fullscreen robot eyes for tablet/display devices, driven by ROS 2 cmd_vel Twist",
+  "type": "module",
+  "main": "./src/index.js",
+  "bin": {
+    "agenticros-eyes": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "public",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node -e \"process.exit(0)\"",
+    "typecheck": "node -e \"process.exit(0)\"",
+    "start": "node src/index.js",
+    "start:no-browser": "node src/index.js --no-browser",
+    "test": "node -e \"process.exit(0)\""
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "optionalDependencies": {
+    "rclnodejs": "^1.9.0"
+  },
+  "keywords": [
+    "agenticros",
+    "ros2",
+    "robot",
+    "eyes",
+    "cmd_vel",
+    "teleop"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agenticros/agenticros.git",
+    "directory": "packages/robot-eyes"
+  },
+  "author": "PlaiPin",
+  "license": "MIT"
+}

package/public/eyes.js

@@ -0,0 +1,246 @@
+const canvas = document.getElementById('eyes');
+const ctx = canvas.getContext('2d');
+
+const state = {
+  // Target from ROS (+/-1); idle offsets applied on top when not driving
+  rosGazeX: 0,
+  driving: false,
+  // Smoothed pupil position in [-1, 1]
+  gazeX: 0,
+  gazeY: 0,
+  // Idle wander target
+  idleX: 0,
+  idleY: 0,
+  nextIdleAt: 0,
+  idleHoldUntil: 0,
+  // Blink: 0 open → 1 closed
+  blink: 0,
+  blinkPhase: 'open', // open | closing | closed | opening
+  nextBlinkAt: 0,
+  blinkHoldUntil: 0,
+};
+
+const BLINK_CLOSE_MS = 90;
+const BLINK_OPEN_MS = 110;
+const BLINK_HOLD_MS = 40;
+const GAZE_LERP = 0.12;
+const IDLE_LERP = 0.04;
+
+function rand(min, max) {
+  return min + Math.random() * (max - min);
+}
+
+function scheduleBlink(now) {
+  state.nextBlinkAt = now + rand(2200, 5200);
+}
+
+function scheduleIdle(now) {
+  state.nextIdleAt = now + rand(2500, 6000);
+}
+
+scheduleBlink(performance.now());
+scheduleIdle(performance.now());
+
+function connectWs() {
+  const proto = location.protocol === 'https:' ? 'wss' : 'ws';
+  const ws = new WebSocket(`${proto}://${location.host}`);
+
+  ws.addEventListener('message', (ev) => {
+    try {
+      const msg = JSON.parse(ev.data);
+      if (msg.type !== 'gaze') return;
+      state.rosGazeX = Number(msg.gazeX) || 0;
+      state.driving = Boolean(msg.driving);
+      if (state.driving) {
+        state.idleX = 0;
+        state.idleY = 0;
+      }
+    } catch {
+      // ignore malformed
+    }
+  });
+
+  ws.addEventListener('close', () => {
+    setTimeout(connectWs, 1000);
+  });
+
+  ws.addEventListener('error', () => {
+    ws.close();
+  });
+}
+
+async function enterFullscreen() {
+  const el = document.documentElement;
+  if (document.fullscreenElement) return;
+  try {
+    if (el.requestFullscreen) await el.requestFullscreen();
+  } catch {
+    // Kiosk browsers often already cover the screen
+  }
+}
+
+document.addEventListener('click', () => {
+  enterFullscreen();
+});
+
+document.addEventListener('keydown', (e) => {
+  if (e.key === 'Escape') {
+    // Allow escape while developing; kiosk may ignore it
+    window.close();
+  }
+  if (e.key === 'f' || e.key === 'F') {
+    enterFullscreen();
+  }
+});
+
+function resize() {
+  const dpr = Math.min(window.devicePixelRatio || 1, 2);
+  canvas.width = Math.floor(window.innerWidth * dpr);
+  canvas.height = Math.floor(window.innerHeight * dpr);
+  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+}
+
+window.addEventListener('resize', resize);
+resize();
+
+function updateBlink(now, dt) {
+  if (state.blinkPhase === 'open') {
+    if (now >= state.nextBlinkAt) {
+      state.blinkPhase = 'closing';
+    }
+    return;
+  }
+
+  if (state.blinkPhase === 'closing') {
+    state.blink = Math.min(1, state.blink + dt / BLINK_CLOSE_MS);
+    if (state.blink >= 1) {
+      state.blink = 1;
+      state.blinkPhase = 'closed';
+      state.blinkHoldUntil = now + BLINK_HOLD_MS;
+    }
+    return;
+  }
+
+  if (state.blinkPhase === 'closed') {
+    if (now >= state.blinkHoldUntil) {
+      state.blinkPhase = 'opening';
+    }
+    return;
+  }
+
+  if (state.blinkPhase === 'opening') {
+    state.blink = Math.max(0, state.blink - dt / BLINK_OPEN_MS);
+    if (state.blink <= 0) {
+      state.blink = 0;
+      state.blinkPhase = 'open';
+      scheduleBlink(now);
+    }
+  }
+}
+
+function updateIdle(now) {
+  if (state.driving) {
+    state.idleX = 0;
+    state.idleY = 0;
+    return;
+  }
+
+  if (now >= state.nextIdleAt && now >= state.idleHoldUntil) {
+    // Sometimes glance around, sometimes return to center
+    if (Math.random() < 0.35) {
+      state.idleX = 0;
+      state.idleY = 0;
+    } else {
+      state.idleX = rand(-0.45, 0.45);
+      state.idleY = rand(-0.25, 0.25);
+    }
+    state.idleHoldUntil = now + rand(600, 1800);
+    scheduleIdle(now);
+  }
+}
+
+function updateGaze() {
+  const targetX = state.driving ? state.rosGazeX : state.idleX;
+  const targetY = state.driving ? 0 : state.idleY;
+  const lerp = state.driving ? GAZE_LERP : IDLE_LERP;
+  state.gazeX += (targetX - state.gazeX) * lerp;
+  state.gazeY += (targetY - state.gazeY) * lerp;
+}
+
+function drawEye(cx, cy, eyeW, eyeH, gazeX, gazeY, blink) {
+  const rx = eyeW / 2;
+  const ry = eyeH / 2;
+
+  // sclera
+  ctx.beginPath();
+  ctx.ellipse(cx, cy, rx, ry, 0, 0, Math.PI * 2);
+  ctx.fillStyle = '#f5f5f5';
+  ctx.fill();
+
+  // iris + pupil
+  const maxOffsetX = rx * 0.32;
+  const maxOffsetY = ry * 0.28;
+  const px = cx + gazeX * maxOffsetX;
+  const py = cy + gazeY * maxOffsetY;
+  const irisR = Math.min(rx, ry) * 0.42;
+  const pupilR = irisR * 0.55;
+
+  ctx.beginPath();
+  ctx.arc(px, py, irisR, 0, Math.PI * 2);
+  ctx.fillStyle = '#1a1a1a';
+  ctx.fill();
+
+  ctx.beginPath();
+  ctx.arc(px, py, pupilR, 0, Math.PI * 2);
+  ctx.fillStyle = '#000';
+  ctx.fill();
+
+  // highlight
+  ctx.beginPath();
+  ctx.arc(px - irisR * 0.35, py - irisR * 0.35, pupilR * 0.35, 0, Math.PI * 2);
+  ctx.fillStyle = 'rgba(255,255,255,0.85)';
+  ctx.fill();
+
+  // eyelids (cover from top and bottom)
+  if (blink > 0) {
+    const cover = ry * blink + 2;
+    ctx.fillStyle = '#000';
+    // clip to eye bounds roughly with rects over the ellipse region
+    ctx.fillRect(cx - rx - 2, cy - ry - 2, eyeW + 4, cover + 2);
+    ctx.fillRect(cx - rx - 2, cy + ry - cover, eyeW + 4, cover + 2);
+  }
+}
+
+function draw() {
+  const w = window.innerWidth;
+  const h = window.innerHeight;
+
+  ctx.fillStyle = '#000';
+  ctx.fillRect(0, 0, w, h);
+
+  const eyeW = Math.min(w * 0.28, h * 0.55);
+  const eyeH = eyeW * 0.62;
+  const gap = w * 0.14;
+  const cy = h * 0.5;
+  const leftCx = w * 0.5 - gap / 2 - eyeW / 2;
+  const rightCx = w * 0.5 + gap / 2 + eyeW / 2;
+
+  drawEye(leftCx, cy, eyeW, eyeH, state.gazeX, state.gazeY, state.blink);
+  drawEye(rightCx, cy, eyeW, eyeH, state.gazeX, state.gazeY, state.blink);
+}
+
+let last = performance.now();
+
+function frame(now) {
+  const dt = Math.min(50, now - last);
+  last = now;
+  updateBlink(now, dt);
+  updateIdle(now);
+  updateGaze();
+  draw();
+  requestAnimationFrame(frame);
+}
+
+connectWs();
+enterFullscreen();
+requestAnimationFrame(frame);

package/public/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no" />
+    <title>Robot Eyes</title>
+    <link rel="stylesheet" href="/style.css" />
+  </head>
+  <body>
+    <canvas id="eyes"></canvas>
+    <script type="module" src="/eyes.js"></script>
+    <script type="module" src="/teleop.js"></script>
+  </body>
+</html>

package/public/style.css

@@ -0,0 +1,22 @@
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+html,
+body {
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  background: #000;
+  cursor: none;
+  touch-action: none;
+}
+
+canvas#eyes {
+  display: block;
+  width: 100vw;
+  height: 100vh;
+  background: #000;
+}

package/public/teleop.js

@@ -0,0 +1,102 @@
+/**
+ * Invisible keyboard teleop — no on-screen UI.
+ * WASD drive, Q faster, Z slower. Messages go to the server over WebSocket.
+ */
+
+const MOVE_KEYS = new Set(['w', 'a', 's', 'd']);
+
+/** @type {WebSocket | null} */
+let socket = null;
+let reconnectTimer = 0;
+
+const pressed = {
+  w: false,
+  a: false,
+  s: false,
+  d: false,
+};
+
+function send(payload) {
+  if (socket && socket.readyState === WebSocket.OPEN) {
+    socket.send(JSON.stringify(payload));
+  }
+}
+
+function sendKeys() {
+  send({
+    type: 'keys',
+    keys: { ...pressed },
+  });
+}
+
+function connect() {
+  const proto = location.protocol === 'https:' ? 'wss' : 'ws';
+  const ws = new WebSocket(`${proto}://${location.host}`);
+  socket = ws;
+
+  ws.addEventListener('open', () => {
+    sendKeys();
+  });
+
+  ws.addEventListener('close', () => {
+    socket = null;
+    clearTimeout(reconnectTimer);
+    reconnectTimer = setTimeout(connect, 1000);
+  });
+
+  ws.addEventListener('error', () => {
+    ws.close();
+  });
+}
+
+function normalizeKey(e) {
+  return e.key.length === 1 ? e.key.toLowerCase() : e.key.toLowerCase();
+}
+
+window.addEventListener('keydown', (e) => {
+  const key = normalizeKey(e);
+
+  if (MOVE_KEYS.has(key)) {
+    e.preventDefault();
+    if (!pressed[key]) {
+      pressed[key] = true;
+      sendKeys();
+    }
+    return;
+  }
+
+  if (key === 'q' && !e.repeat) {
+    e.preventDefault();
+    send({ type: 'speed', delta: 1 });
+    return;
+  }
+
+  if (key === 'z' && !e.repeat) {
+    e.preventDefault();
+    send({ type: 'speed', delta: -1 });
+  }
+});
+
+window.addEventListener('keyup', (e) => {
+  const key = normalizeKey(e);
+  if (!MOVE_KEYS.has(key)) return;
+  e.preventDefault();
+  if (pressed[key]) {
+    pressed[key] = false;
+    sendKeys();
+  }
+});
+
+// Release all keys if the window loses focus (safety)
+window.addEventListener('blur', () => {
+  let changed = false;
+  for (const k of MOVE_KEYS) {
+    if (pressed[k]) {
+      pressed[k] = false;
+      changed = true;
+    }
+  }
+  if (changed) sendKeys();
+});
+
+connect();

package/src/index.js

@@ -0,0 +1,410 @@
+#!/usr/bin/env node
+/**
+ * @agenticros/eyes — fullscreen robot face driven by ROS 2 cmd_vel Twist.
+ *
+ * Subscribes to CMD_VEL_TOPIC for gaze (left/right turns). Optionally publishes
+ * the same topic from invisible WASD keyboard teleop (disabled with --no-teleop).
+ *
+ * Env (set by `agenticros eyes` from ~/.agenticros/config.json):
+ *   CMD_VEL_TOPIC, MAX_LINEAR_VELOCITY, MAX_ANGULAR_VELOCITY, PORT, …
+ */
+import { createRequire } from "module";
+import http from "http";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { spawn, execFileSync } from "child_process";
+import { WebSocketServer } from "ws";
+
+const require = createRequire(import.meta.url);
+let rclnodejs;
+try {
+  rclnodejs = require("rclnodejs");
+} catch (e) {
+  console.error(
+    "Failed to load rclnodejs. Source ROS 2 and reinstall deps on the robot:\n" +
+      "  source /opt/ros/<distro>/setup.bash && pnpm install --filter @agenticros/eyes\n" +
+      String(e instanceof Error ? e.message : e),
+  );
+  process.exit(1);
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PUBLIC_DIR = path.join(__dirname, "..", "public");
+
+const PORT = Number(process.env.PORT || 8765);
+const TOPIC = process.env.CMD_VEL_TOPIC || "/cmd_vel";
+const ANGULAR_DEADZONE = Number(process.env.ANGULAR_DEADZONE || 0.05);
+const CMD_TIMEOUT_MS = Number(process.env.CMD_TIMEOUT_MS || 300);
+const NO_BROWSER = process.argv.includes("--no-browser");
+const NO_TELEOP =
+  process.argv.includes("--no-teleop") ||
+  process.env.AGENTICROS_EYES_NO_TELEOP === "1";
+
+const MAX_LINEAR = Number(process.env.MAX_LINEAR_VELOCITY || 1.0);
+const MAX_ANGULAR = Number(process.env.MAX_ANGULAR_VELOCITY || 1.5);
+
+const TELOP_LINEAR = Math.min(
+  Number(process.env.TELOP_LINEAR || 0.25),
+  MAX_LINEAR,
+);
+const TELOP_ANGULAR = Math.min(
+  Number(process.env.TELOP_ANGULAR || 0.9),
+  MAX_ANGULAR,
+);
+const TELOP_SCALE_STEP = Number(process.env.TELOP_SCALE_STEP || 0.15);
+const TELOP_SCALE_MIN = Number(process.env.TELOP_SCALE_MIN || 0.2);
+const TELOP_SCALE_MAX = Number(process.env.TELOP_SCALE_MAX || 3);
+const TELOP_RATE_HZ = Number(process.env.TELOP_RATE_HZ || 20);
+
+/** @type {{ gazeX: number, driving: boolean, lastCmdAt: number }} */
+const state = {
+  gazeX: 0,
+  driving: false,
+  lastCmdAt: 0,
+};
+
+const teleop = {
+  /** @type {Map<object, { w: boolean, a: boolean, s: boolean, d: boolean }>} */
+  clients: new Map(),
+  scale: 1,
+  publishing: false,
+};
+
+function mimeType(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  switch (ext) {
+    case ".html":
+      return "text/html; charset=utf-8";
+    case ".js":
+      return "application/javascript; charset=utf-8";
+    case ".css":
+      return "text/css; charset=utf-8";
+    case ".svg":
+      return "image/svg+xml";
+    case ".png":
+      return "image/png";
+    default:
+      return "application/octet-stream";
+  }
+}
+
+function createHttpServer() {
+  return http.createServer((req, res) => {
+    const urlPath = decodeURIComponent((req.url || "/").split("?")[0]);
+    const rel = urlPath === "/" ? "/index.html" : urlPath;
+    const filePath = path.normalize(path.join(PUBLIC_DIR, rel));
+
+    if (!filePath.startsWith(PUBLIC_DIR)) {
+      res.writeHead(403).end("Forbidden");
+      return;
+    }
+
+    // Gaze-only mode: serve HTML without the teleop script.
+    if (NO_TELEOP && rel === "/index.html") {
+      fs.readFile(filePath, "utf8", (err, html) => {
+        if (err) {
+          res.writeHead(404).end("Not found");
+          return;
+        }
+        const stripped = html.replace(
+          /\s*<script type="module" src="\/teleop\.js"><\/script>\s*/i,
+          "\n",
+        );
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(stripped);
+      });
+      return;
+    }
+
+    fs.readFile(filePath, (err, data) => {
+      if (err) {
+        res.writeHead(404).end("Not found");
+        return;
+      }
+      res.writeHead(200, { "Content-Type": mimeType(filePath) });
+      res.end(data);
+    });
+  });
+}
+
+function broadcast(wss, payload) {
+  const raw = JSON.stringify(payload);
+  for (const client of wss.clients) {
+    if (client.readyState === 1) {
+      client.send(raw);
+    }
+  }
+}
+
+function gazeFromTwist(msg) {
+  const z = msg?.angular?.z ?? 0;
+  if (Math.abs(z) < ANGULAR_DEADZONE) {
+    return { gazeX: 0, driving: false };
+  }
+  // +angular.z = left turn → eyes look right (screen +X)
+  return { gazeX: z > 0 ? 1 : -1, driving: true };
+}
+
+function mergedKeys() {
+  const keys = { w: false, a: false, s: false, d: false };
+  for (const k of teleop.clients.values()) {
+    keys.w ||= k.w;
+    keys.a ||= k.a;
+    keys.s ||= k.s;
+    keys.d ||= k.d;
+  }
+  return keys;
+}
+
+function clampTwist(twist) {
+  const { linear, angular } = twist;
+  const lx = linear?.x ?? 0;
+  const ly = linear?.y ?? 0;
+  const lz = linear?.z ?? 0;
+  const ax = angular?.x ?? 0;
+  const ay = angular?.y ?? 0;
+  const az = angular?.z ?? 0;
+
+  const linMag = Math.sqrt(lx * lx + ly * ly + lz * lz);
+  const scaleLin = linMag > MAX_LINEAR && linMag > 0 ? MAX_LINEAR / linMag : 1;
+  const angMag = Math.abs(az);
+  const scaleAng = angMag > MAX_ANGULAR && angMag > 0 ? MAX_ANGULAR / angMag : 1;
+
+  return {
+    linear: { x: lx * scaleLin, y: ly * scaleLin, z: lz * scaleLin },
+    angular: {
+      x: ax * scaleAng,
+      y: ay * scaleAng,
+      z: Math.max(-MAX_ANGULAR, Math.min(MAX_ANGULAR, az)),
+    },
+  };
+}
+
+function twistFromKeys(keys) {
+  const linear = TELOP_LINEAR * teleop.scale;
+  const angular = TELOP_ANGULAR * teleop.scale;
+  let x = 0;
+  let z = 0;
+  if (keys.w) x += linear;
+  if (keys.s) x -= linear;
+  if (keys.a) z += angular;
+  if (keys.d) z -= angular;
+  return clampTwist({
+    linear: { x, y: 0, z: 0 },
+    angular: { x: 0, y: 0, z },
+  });
+}
+
+function anyKeyDown(keys) {
+  return keys.w || keys.a || keys.s || keys.d;
+}
+
+function findBrowser() {
+  const candidates = [
+    process.env.BROWSER,
+    "firefox",
+    "chromium-browser",
+    "chromium",
+    "google-chrome",
+    "google-chrome-stable",
+  ].filter(Boolean);
+
+  for (const bin of candidates) {
+    try {
+      execFileSync("which", [bin], { stdio: "ignore" });
+      return bin;
+    } catch {
+      // try next
+    }
+  }
+  return null;
+}
+
+function launchKiosk(url) {
+  const bin = findBrowser();
+  if (!bin) {
+    console.warn("No browser found. Open this URL fullscreen manually:", url);
+    return null;
+  }
+
+  const args = bin.includes("firefox")
+    ? ["--kiosk", url]
+    : ["--kiosk", "--noerrdialogs", "--disable-infobars", `--app=${url}`, url];
+
+  console.log(`Launching ${bin} in kiosk mode → ${url}`);
+  const child = spawn(bin, args, {
+    stdio: "ignore",
+    detached: true,
+    env: { ...process.env, DISPLAY: process.env.DISPLAY || ":0" },
+  });
+  child.unref();
+  child.on("error", (err) => {
+    console.warn(`Failed to launch ${bin}:`, err.message);
+    console.warn("Open this URL fullscreen manually:", url);
+  });
+  return child;
+}
+
+async function main() {
+  await rclnodejs.init();
+  const node = rclnodejs.createNode("robot_eyes");
+  const publisher = NO_TELEOP
+    ? null
+    : node.createPublisher("geometry_msgs/msg/Twist", TOPIC);
+
+  const server = createHttpServer();
+  const wss = new WebSocketServer({ server });
+
+  const publishStop = () => {
+    if (!publisher) return;
+    publisher.publish({
+      linear: { x: 0, y: 0, z: 0 },
+      angular: { x: 0, y: 0, z: 0 },
+    });
+    teleop.publishing = false;
+  };
+
+  const tickTeleop = () => {
+    if (NO_TELEOP || !publisher) return;
+    const keys = mergedKeys();
+    if (!anyKeyDown(keys)) {
+      if (teleop.publishing) {
+        publishStop();
+      }
+      return;
+    }
+    publisher.publish(twistFromKeys(keys));
+    teleop.publishing = true;
+  };
+
+  if (!NO_TELEOP) {
+    setInterval(tickTeleop, Math.max(10, Math.round(1000 / TELOP_RATE_HZ)));
+  }
+
+  wss.on("connection", (ws) => {
+    if (!NO_TELEOP) {
+      teleop.clients.set(ws, { w: false, a: false, s: false, d: false });
+    }
+
+    ws.send(
+      JSON.stringify({
+        type: "gaze",
+        gazeX: state.gazeX,
+        driving: state.driving,
+      }),
+    );
+
+    ws.on("message", (raw) => {
+      if (NO_TELEOP) return;
+      let msg;
+      try {
+        msg = JSON.parse(String(raw));
+      } catch {
+        return;
+      }
+
+      if (msg.type === "keys" && msg.keys && typeof msg.keys === "object") {
+        teleop.clients.set(ws, {
+          w: Boolean(msg.keys.w),
+          a: Boolean(msg.keys.a),
+          s: Boolean(msg.keys.s),
+          d: Boolean(msg.keys.d),
+        });
+        tickTeleop();
+        return;
+      }
+
+      if (msg.type === "speed" && (msg.delta === 1 || msg.delta === -1)) {
+        const next = teleop.scale + msg.delta * TELOP_SCALE_STEP;
+        teleop.scale = Math.min(
+          TELOP_SCALE_MAX,
+          Math.max(TELOP_SCALE_MIN, next),
+        );
+        console.log(
+          `teleop speed scale: ${teleop.scale.toFixed(2)} ` +
+            `(linear≈${(TELOP_LINEAR * teleop.scale).toFixed(2)} m/s, ` +
+            `angular≈${(TELOP_ANGULAR * teleop.scale).toFixed(2)} rad/s)`,
+        );
+      }
+    });
+
+    ws.on("close", () => {
+      if (!NO_TELEOP) {
+        teleop.clients.delete(ws);
+        tickTeleop();
+      }
+    });
+  });
+
+  node.createSubscription("geometry_msgs/msg/Twist", TOPIC, (msg) => {
+    const next = gazeFromTwist(msg);
+    state.gazeX = next.gazeX;
+    state.driving = next.driving;
+    state.lastCmdAt = Date.now();
+    broadcast(wss, {
+      type: "gaze",
+      gazeX: state.gazeX,
+      driving: state.driving,
+    });
+  });
+
+  setInterval(() => {
+    if (!state.driving) return;
+    if (Date.now() - state.lastCmdAt < CMD_TIMEOUT_MS) return;
+    state.gazeX = 0;
+    state.driving = false;
+    broadcast(wss, {
+      type: "gaze",
+      gazeX: 0,
+      driving: false,
+    });
+  }, 50);
+
+  server.listen(PORT, "127.0.0.1", () => {
+    const url = `http://127.0.0.1:${PORT}/`;
+    console.log(`robot-eyes listening on ${url}`);
+    console.log(
+      `${NO_TELEOP ? "Subscribed" : "Subscribed + publishing"} ${TOPIC} ` +
+        `(deadzone=${ANGULAR_DEADZONE}, maxLin=${MAX_LINEAR}, maxAng=${MAX_ANGULAR})`,
+    );
+    if (NO_TELEOP) {
+      console.log("Keyboard teleop disabled (--no-teleop / gaze-only)");
+    } else {
+      console.log(
+        `Keyboard teleop: WASD drive, Q faster, Z slower ` +
+          `(base linear=${TELOP_LINEAR}, angular=${TELOP_ANGULAR})`,
+      );
+    }
+    if (!NO_BROWSER) {
+      launchKiosk(url);
+    } else {
+      console.log("--no-browser: open the URL yourself for fullscreen");
+    }
+  });
+
+  rclnodejs.spin(node);
+
+  const shutdown = async () => {
+    console.log("\nShutting down…");
+    try {
+      publishStop();
+      wss.close();
+      server.close();
+      node.destroy();
+      await rclnodejs.shutdown();
+    } catch {
+      // ignore
+    }
+    process.exit(0);
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});