Add protocol module, video-node binary, query/web CLI tools

- Protocol module: framed binary encoding for control requests/responses
  (ENUM_DEVICES, ENUM_CONTROLS, GET/SET_CONTROL, STREAM_OPEN/CLOSE)
- video-node: scans /dev/media* and /dev/video*, serves V4L2 device
  topology and controls over TCP; uses UDP discovery for peer announce
- query_cli: auto-discovers a node, queries devices and controls
- protocol_cli: low-level protocol frame decoder for debugging
- dev/web: Express 5 ESM web inspector — live SSE discovery picker,
  REST bridge to video-node, controls UI with sliders/selects/checkboxes
- Makefile: sequential module builds before cli/node to fix make -j races
- common.mk: add DEPFLAGS (-MMD -MP) for automatic header dependencies
- All module Makefiles: split compile/link, generate .d dependency files
- discovery: replace 100ms poll loop with pthread_cond_timedwait;
  respond to all announcements (not just new peers) for instant re-discovery
- ENUM_DEVICES response: carry device_caps (V4L2_CAP_*) per video node
  so clients can distinguish capture nodes from metadata nodes

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

dev/web/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+package-lock.json

dev/web/Makefile

@@ -0,0 +1,9 @@
+.PHONY: all clean
+
+all: node_modules
+
+node_modules: package.json
+	npm install
+
+clean:
+	rm -rf node_modules

dev/web/discovery.mjs

@@ -0,0 +1,86 @@
+/*
+ * UDP multicast discovery — streaming callback API.
+ *
+ * Announcement wire format (matches discovery.c):
+ *   [u16 msg_type=0x0010][u32 payload_len]   <- 6-byte frame header
+ *   [u8  protocol_version]
+ *   [u16 site_id]
+ *   [u16 tcp_port]
+ *   [u16 function_flags]
+ *   [u8  name_len]
+ *   [bytes name...]
+ */
+
+import dgram from 'node:dgram';
+
+const MULTICAST_GROUP = '224.0.0.251';
+const DISCOVERY_PORT  = 5353;
+const ANNOUNCE_TYPE   = 0x0010;
+const HEADER_SIZE     = 6;
+const ANN_FIXED_SIZE  = 8;
+
+/*
+ * Open a discovery socket, send an immediate announce to prompt replies,
+ * and call on_peer for each newly-seen peer (deduplicated by addr+name).
+ *
+ * Returns a stop() function.  Call it when done (e.g. user closed the picker
+ * or selected a node).  Safe to call multiple times.
+ */
+export function start_discovery(on_peer) {
+	const sock = dgram.createSocket({ type: 'udp4', reuseAddr: true });
+	const seen = new Set();
+	let closed = false;
+
+	sock.on('error', () => stop());
+
+	sock.on('message', (msg, rinfo) => {
+		if (msg.length < HEADER_SIZE) { return; }
+		const msg_type    = msg.readUInt16BE(0);
+		const payload_len = msg.readUInt32BE(2);
+		if (msg_type !== ANNOUNCE_TYPE) { return; }
+		if (msg.length < HEADER_SIZE + payload_len) { return; }
+		if (payload_len < ANN_FIXED_SIZE) { return; }
+
+		const p          = msg.slice(HEADER_SIZE);
+		const site_id    = p.readUInt16BE(1);
+		const tcp_port   = p.readUInt16BE(3);
+		const func_flags = p.readUInt16BE(5);
+		const name_len   = p.readUInt8(7);
+		if (payload_len < ANN_FIXED_SIZE + name_len) { return; }
+		const name       = p.toString('utf8', 8, 8 + name_len);
+
+		const key = `${rinfo.address}:${name}`;
+		if (seen.has(key)) { return; }
+		seen.add(key);
+
+		on_peer({ addr: rinfo.address, tcp_port, site_id, function_flags: func_flags, name });
+	});
+
+	sock.bind(DISCOVERY_PORT, () => {
+		sock.addMembership(MULTICAST_GROUP);
+		send_announce(sock);
+	});
+
+	function stop() {
+		if (closed) { return; }
+		closed = true;
+		try { sock.close(); } catch {}
+	}
+
+	return stop;
+}
+
+function send_announce(sock) {
+	const name        = Buffer.from('web-inspector', 'utf8');
+	const payload_len = 8 + name.length;
+	const buf         = Buffer.allocUnsafe(6 + payload_len);
+	buf.writeUInt16BE(ANNOUNCE_TYPE, 0);
+	buf.writeUInt32BE(payload_len, 2);
+	buf.writeUInt8(1, 6);           /* protocol_version */
+	buf.writeUInt16BE(0, 7);        /* site_id */
+	buf.writeUInt16BE(0, 9);        /* tcp_port (0 = no server) */
+	buf.writeUInt16BE(0, 11);       /* function_flags */
+	buf.writeUInt8(name.length, 13);
+	name.copy(buf, 14);
+	sock.send(buf, 0, buf.length, DISCOVERY_PORT, MULTICAST_GROUP);
+}

dev/web/node_client.mjs

@@ -0,0 +1,135 @@
+/*
+ * TCP client for video-node.
+ * Handles frame reassembly, request/response correlation by request_id,
+ * and reconnection state.
+ */
+
+import net from 'node:net';
+import { EventEmitter } from 'node:events';
+import {
+	FRAME_HEADER_SIZE, MSG_CONTROL_RESPONSE,
+	encode_enum_devices, encode_enum_controls,
+	encode_get_control, encode_set_control,
+	decode_enum_devices_response, decode_enum_controls_response,
+	decode_get_control_response, decode_set_control_response,
+} from './protocol.mjs';
+
+export class Node_Client extends EventEmitter {
+	constructor() {
+		super();
+		this._socket   = null;
+		this._buf      = Buffer.alloc(0);
+		this._pending  = new Map();   /* request_id -> { resolve, reject, decode } */
+		this._next_id  = 1;
+		this.connected = false;
+		this.host      = null;
+		this.port      = null;
+	}
+
+	connect(host, port) {
+		if (this._socket) { this._socket.destroy(); }
+
+		this.host = host;
+		this.port = port;
+
+		return new Promise((resolve, reject) => {
+			const sock = net.createConnection({ host, port });
+
+			sock.once('connect', () => {
+				this._socket   = sock;
+				this.connected = true;
+				this._buf      = Buffer.alloc(0);
+				this.emit('connect');
+				resolve();
+			});
+
+			sock.once('error', err => {
+				if (!this.connected) { reject(err); }
+				else { this.emit('error', err); }
+			});
+
+			sock.on('data', chunk => this._on_data(chunk));
+
+			sock.on('close', () => {
+				this.connected = false;
+				this._socket   = null;
+				/* reject all pending requests */
+				for (const { reject: rej } of this._pending.values()) {
+					rej(new Error('disconnected'));
+				}
+				this._pending.clear();
+				this.emit('disconnect');
+			});
+		});
+	}
+
+	disconnect() {
+		if (this._socket) { this._socket.destroy(); }
+	}
+
+	/* ---------------------------------------------------------------------- */
+
+	_on_data(chunk) {
+		this._buf = Buffer.concat([this._buf, chunk]);
+		while (true) {
+			if (this._buf.length < FRAME_HEADER_SIZE) { break; }
+			const msg_type    = this._buf.readUInt16BE(0);
+			const payload_len = this._buf.readUInt32BE(2);
+			if (this._buf.length < FRAME_HEADER_SIZE + payload_len) { break; }
+			const payload = this._buf.slice(FRAME_HEADER_SIZE, FRAME_HEADER_SIZE + payload_len);
+			this._buf = this._buf.slice(FRAME_HEADER_SIZE + payload_len);
+			this._on_frame(msg_type, payload);
+		}
+	}
+
+	_on_frame(msg_type, payload) {
+		if (msg_type !== MSG_CONTROL_RESPONSE) { return; }
+		if (payload.length < 4) { return; }
+		const request_id = payload.readUInt16BE(0);
+		const entry = this._pending.get(request_id);
+		if (!entry) { return; }
+		this._pending.delete(request_id);
+		try {
+			entry.resolve(entry.decode(payload));
+		} catch (err) {
+			entry.reject(err);
+		}
+	}
+
+	_request(frame, decode_fn) {
+		if (!this.connected) { return Promise.reject(new Error('not connected')); }
+		const id = this._alloc_id();
+		/* patch request_id into the frame payload (bytes 6-7) */
+		frame.writeUInt16BE(id, FRAME_HEADER_SIZE);
+		return new Promise((resolve, reject) => {
+			this._pending.set(id, { resolve, reject, decode: decode_fn });
+			this._socket.write(frame, err => {
+				if (err) { this._pending.delete(id); reject(err); }
+			});
+		});
+	}
+
+	_alloc_id() {
+		const id = this._next_id;
+		this._next_id = (this._next_id % 0xFFFF) + 1;
+		return id;
+	}
+
+	/* ---------------------------------------------------------------------- */
+
+	enum_devices() {
+		return this._request(encode_enum_devices(0), decode_enum_devices_response);
+	}
+
+	enum_controls(device_index) {
+		return this._request(encode_enum_controls(0, device_index), decode_enum_controls_response);
+	}
+
+	get_control(device_index, control_id) {
+		return this._request(encode_get_control(0, device_index, control_id), decode_get_control_response);
+	}
+
+	set_control(device_index, control_id, value) {
+		return this._request(encode_set_control(0, device_index, control_id, value), decode_set_control_response);
+	}
+}

dev/web/package.json

@@ -0,0 +1,8 @@
+{
+	"name": "video-web",
+	"version": "1.0.0",
+	"type": "module",
+	"dependencies": {
+		"express": "^5.2.1"
+	}
+}

dev/web/protocol.mjs

@@ -0,0 +1,196 @@
+/*
+ * Binary protocol encoder/decoder for video-node.
+ *
+ * Frame layout (TCP):
+ *   [u16 message_type][u32 payload_length][payload...]
+ *
+ * CONTROL_REQUEST payload:
+ *   [u16 request_id][u16 command][command-specific...]
+ *
+ * CONTROL_RESPONSE payload:
+ *   [u16 request_id][u16 status][command-specific...]
+ *
+ * str8 encoding: [u8 length][bytes...] — not NUL-terminated on wire.
+ */
+
+export const FRAME_HEADER_SIZE     = 6;
+export const MSG_CONTROL_REQUEST   = 0x0002;
+export const MSG_CONTROL_RESPONSE  = 0x0003;
+
+export const CMD_ENUM_DEVICES      = 0x0003;
+export const CMD_ENUM_CONTROLS     = 0x0004;
+export const CMD_GET_CONTROL       = 0x0005;
+export const CMD_SET_CONTROL       = 0x0006;
+
+export const STATUS_OK             = 0x0000;
+
+/* -------------------------------------------------------------------------
+ * Low-level buffer helpers
+ * ------------------------------------------------------------------------- */
+
+function read_str8(buf, offset) {
+	const len = buf.readUInt8(offset);
+	const value = buf.toString('utf8', offset + 1, offset + 1 + len);
+	return { value, size: 1 + len };
+}
+
+function read_i64(buf, offset) {
+	/* Returns a JS number — safe for the int32 values V4L2 uses in practice. */
+	const hi = buf.readInt32BE(offset);
+	const lo = buf.readUInt32BE(offset + 4);
+	return hi * 0x100000000 + lo;
+}
+
+/* -------------------------------------------------------------------------
+ * Frame builder
+ * ------------------------------------------------------------------------- */
+
+export function build_frame(msg_type, payload) {
+	const frame = Buffer.allocUnsafe(FRAME_HEADER_SIZE + payload.length);
+	frame.writeUInt16BE(msg_type, 0);
+	frame.writeUInt32BE(payload.length, 2);
+	payload.copy(frame, FRAME_HEADER_SIZE);
+	return frame;
+}
+
+/* -------------------------------------------------------------------------
+ * Request encoders — return a complete TCP frame Buffer.
+ * request_id must be provided by the caller (u16).
+ * ------------------------------------------------------------------------- */
+
+export function encode_enum_devices(request_id) {
+	const p = Buffer.allocUnsafe(4);
+	p.writeUInt16BE(request_id, 0);
+	p.writeUInt16BE(CMD_ENUM_DEVICES, 2);
+	return build_frame(MSG_CONTROL_REQUEST, p);
+}
+
+export function encode_enum_controls(request_id, device_index) {
+	const p = Buffer.allocUnsafe(6);
+	p.writeUInt16BE(request_id, 0);
+	p.writeUInt16BE(CMD_ENUM_CONTROLS, 2);
+	p.writeUInt16BE(device_index, 4);
+	return build_frame(MSG_CONTROL_REQUEST, p);
+}
+
+export function encode_get_control(request_id, device_index, control_id) {
+	const p = Buffer.allocUnsafe(10);
+	p.writeUInt16BE(request_id, 0);
+	p.writeUInt16BE(CMD_GET_CONTROL, 2);
+	p.writeUInt16BE(device_index, 4);
+	p.writeUInt32BE(control_id, 6);
+	return build_frame(MSG_CONTROL_REQUEST, p);
+}
+
+export function encode_set_control(request_id, device_index, control_id, value) {
+	const p = Buffer.allocUnsafe(14);
+	p.writeUInt16BE(request_id, 0);
+	p.writeUInt16BE(CMD_SET_CONTROL, 2);
+	p.writeUInt16BE(device_index, 4);
+	p.writeUInt16BE(0, 6);
+	p.writeUInt32BE(control_id, 6);
+	p.writeInt32BE(value, 10);
+	return build_frame(MSG_CONTROL_REQUEST, p);
+}
+
+/* -------------------------------------------------------------------------
+ * Response decoders — take a payload Buffer (without frame header).
+ * All throw on malformed data.
+ * ------------------------------------------------------------------------- */
+
+export function decode_response_header(payload) {
+	return {
+		request_id: payload.readUInt16BE(0),
+		status:     payload.readUInt16BE(2),
+	};
+}
+
+export function decode_enum_devices_response(payload) {
+	const hdr = decode_response_header(payload);
+	if (hdr.status !== STATUS_OK) { return { ...hdr, media: [], standalone: [] }; }
+
+	let pos = 4;
+	const media_count = payload.readUInt16BE(pos); pos += 2;
+	const media = [];
+
+	for (let i = 0; i < media_count; i++) {
+		let s;
+		s = read_str8(payload, pos); pos += s.size; const path     = s.value;
+		s = read_str8(payload, pos); pos += s.size; const driver   = s.value;
+		s = read_str8(payload, pos); pos += s.size; const model    = s.value;
+		s = read_str8(payload, pos); pos += s.size; const bus_info = s.value;
+		const vcount = payload.readUInt8(pos); pos++;
+
+		const video_nodes = [];
+		for (let j = 0; j < vcount; j++) {
+			s = read_str8(payload, pos); pos += s.size; const vpath       = s.value;
+			s = read_str8(payload, pos); pos += s.size; const entity_name = s.value;
+			const entity_type  = payload.readUInt32BE(pos); pos += 4;
+			const entity_flags = payload.readUInt32BE(pos); pos += 4;
+			const device_caps  = payload.readUInt32BE(pos); pos += 4;
+			const pad_flags    = payload.readUInt8(pos);    pos++;
+			const is_capture   = payload.readUInt8(pos);    pos++;
+			video_nodes.push({ path: vpath, entity_name, entity_type,
+				entity_flags, device_caps, pad_flags, is_capture: !!is_capture });
+		}
+
+		media.push({ path, driver, model, bus_info, video_nodes });
+	}
+
+	const standalone_count = payload.readUInt16BE(pos); pos += 2;
+	const standalone = [];
+	for (let i = 0; i < standalone_count; i++) {
+		let s;
+		s = read_str8(payload, pos); pos += s.size; const path = s.value;
+		s = read_str8(payload, pos); pos += s.size; const name = s.value;
+		standalone.push({ path, name });
+	}
+
+	return { ...hdr, media, standalone };
+}
+
+export function decode_enum_controls_response(payload) {
+	const hdr = decode_response_header(payload);
+	if (hdr.status !== STATUS_OK) { return { ...hdr, controls: [] }; }
+
+	let pos = 4;
+	const count = payload.readUInt16BE(pos); pos += 2;
+	const controls = [];
+
+	for (let i = 0; i < count; i++) {
+		const id    = payload.readUInt32BE(pos); pos += 4;
+		const type  = payload.readUInt8(pos);    pos++;
+		const flags = payload.readUInt32BE(pos); pos += 4;
+		const s = read_str8(payload, pos);       pos += s.size;
+		const name  = s.value;
+		const min   = payload.readInt32BE(pos);  pos += 4;
+		const max   = payload.readInt32BE(pos);  pos += 4;
+		const step  = payload.readInt32BE(pos);  pos += 4;
+		const def   = payload.readInt32BE(pos);  pos += 4;
+		const cur   = payload.readInt32BE(pos);  pos += 4;
+		const menu_count = payload.readUInt8(pos); pos++;
+
+		const menu_items = [];
+		for (let j = 0; j < menu_count; j++) {
+			const midx   = payload.readUInt32BE(pos); pos += 4;
+			const ms = read_str8(payload, pos);        pos += ms.size;
+			const mval   = read_i64(payload, pos);     pos += 8;
+			menu_items.push({ index: midx, name: ms.value, int_value: mval });
+		}
+
+		controls.push({ id, type, flags, name, min, max, step,
+			default_val: def, current_val: cur, menu_items });
+	}
+
+	return { ...hdr, controls };
+}
+
+export function decode_get_control_response(payload) {
+	const hdr = decode_response_header(payload);
+	const value = (hdr.status === STATUS_OK) ? payload.readInt32BE(4) : 0;
+	return { ...hdr, value };
+}
+
+export function decode_set_control_response(payload) {
+	return decode_response_header(payload);
+}

dev/web/public/app.mjs

@@ -0,0 +1,503 @@
+/* V4L2 control type codes (must match CTRL_TYPE_* in v4l2_ctrl.h) */
+const CTRL_INTEGER      = 1;
+const CTRL_BOOLEAN      = 2;
+const CTRL_MENU         = 3;
+const CTRL_BUTTON       = 4;
+const CTRL_INTEGER_MENU = 9;
+
+/* V4L2 control flags */
+const FLAG_DISABLED  = 0x0001;
+const FLAG_GRABBED   = 0x0002;
+const FLAG_READ_ONLY = 0x0004;
+const FLAG_INACTIVE  = 0x0010;
+
+/* V4L2_CAP bits (from linux/videodev2.h) */
+const CAP_VIDEO_CAPTURE = 0x00000001;
+const CAP_META_CAPTURE  = 0x00800000;
+
+/* -------------------------------------------------------------------------
+ * State
+ * ------------------------------------------------------------------------- */
+
+let selected_device_idx = null;
+let device_data = null;   /* last ENUM_DEVICES result */
+
+/* -------------------------------------------------------------------------
+ * Utilities
+ * ------------------------------------------------------------------------- */
+
+const $ = id => document.getElementById(id);
+
+function toast(msg, type = '') {
+	const el = document.createElement('div');
+	el.className = 'toast' + (type ? ` ${type}` : '');
+	el.textContent = msg;
+	$('toast-container').appendChild(el);
+	setTimeout(() => {
+		el.classList.add('fading');
+		setTimeout(() => el.remove(), 450);
+	}, 2500);
+}
+
+async function api(method, path, body) {
+	const opts = { method, headers: { 'Content-Type': 'application/json' } };
+	if (body !== undefined) { opts.body = JSON.stringify(body); }
+	const res = await fetch(path, opts);
+	const data = await res.json();
+	if (!res.ok) { throw new Error(data.error || `HTTP ${res.status}`); }
+	return data;
+}
+
+function caps_tags(device_caps) {
+	const tags = [];
+	if (device_caps & CAP_VIDEO_CAPTURE) { tags.push('video'); }
+	if (device_caps & CAP_META_CAPTURE)  { tags.push('meta'); }
+	return tags.join(' ');
+}
+
+/* -------------------------------------------------------------------------
+ * Connection UI
+ * ------------------------------------------------------------------------- */
+
+async function refresh_status() {
+	try {
+		const s = await api('GET', '/api/status');
+		const dot  = $('status-dot');
+		const text = $('status-text');
+		if (s.connected) {
+			dot.className = 'ok';
+			text.textContent = `${s.host}:${s.port}`;
+			$('btn-disconnect').style.display = '';
+			$('btn-connect').style.display    = 'none';
+			await refresh_devices();
+		} else {
+			dot.className = '';
+			text.textContent = 'disconnected';
+			$('btn-disconnect').style.display = 'none';
+			$('btn-connect').style.display    = '';
+			show_empty_devices();
+		}
+	} catch (err) {
+		console.error(err);
+	}
+}
+
+$('btn-connect').addEventListener('click', async () => {
+	const host = $('inp-host').value.trim();
+	const port = $('inp-port').value.trim();
+	if (!host || !port) { toast('enter host and port', 'err'); return; }
+	try {
+		await api('POST', '/api/connect', { host, port: parseInt(port) });
+		toast('connected', 'ok');
+		await refresh_status();
+	} catch (err) {
+		toast(err.message, 'err');
+	}
+});
+
+let discovery_es = null;
+
+$('btn-discover').addEventListener('click', () => {
+	if (discovery_es) { return; }  /* already open */
+	show_peer_picker();
+});
+
+async function connect_to_peer(peer) {
+	await api('POST', '/api/connect', { host: peer.addr, port: peer.tcp_port });
+	$('inp-host').value = peer.addr;
+	$('inp-port').value = peer.tcp_port;
+	toast(`connected to ${peer.name}`, 'ok');
+}
+
+function show_peer_picker() {
+	/* -- overlay ----------------------------------------------------------- */
+	const overlay = document.createElement('div');
+	overlay.style.cssText = `
+		position:fixed; inset:0; background:rgba(0,0,0,0.6);
+		display:flex; align-items:center; justify-content:center; z-index:200;
+	`;
+
+	const box = document.createElement('div');
+	box.style.cssText = `
+		background:var(--surface); border:1px solid var(--border);
+		border-radius:8px; padding:20px; min-width:320px; max-width:480px;
+	`;
+
+	const header = document.createElement('div');
+	header.style.cssText = 'display:flex; align-items:center; gap:10px; margin-bottom:14px;';
+
+	const title = document.createElement('div');
+	title.style.cssText = 'font-weight:600; flex:1;';
+	title.textContent = 'Discovering nodes…';
+
+	const spinner = document.createElement('span');
+	spinner.textContent = '⟳';
+	spinner.style.cssText = 'animation:spin 1s linear infinite; display:inline-block; font-size:16px;';
+
+	const cancel_btn = document.createElement('button');
+	cancel_btn.textContent = 'Close';
+
+	header.appendChild(title);
+	header.appendChild(spinner);
+	header.appendChild(cancel_btn);
+	box.appendChild(header);
+
+	const peer_list = document.createElement('div');
+	peer_list.style.cssText = 'display:flex; flex-direction:column; gap:6px; min-height:40px;';
+
+	const hint = document.createElement('div');
+	hint.style.cssText = 'color:var(--text-dim); font-size:12px; padding:8px 0;';
+	hint.textContent = 'Waiting for announcements…';
+	peer_list.appendChild(hint);
+
+	box.appendChild(peer_list);
+	overlay.appendChild(box);
+	document.body.appendChild(overlay);
+
+	/* add spin keyframe once */
+	if (!document.getElementById('spin-style')) {
+		const s = document.createElement('style');
+		s.id = 'spin-style';
+		s.textContent = '@keyframes spin { to { transform:rotate(360deg); } }';
+		document.head.appendChild(s);
+	}
+
+	/* -- SSE --------------------------------------------------------------- */
+	const es = new EventSource('/api/discover');
+	discovery_es = es;
+
+	es.onmessage = e => {
+		const peer = JSON.parse(e.data);
+		hint.remove();
+		title.textContent = 'Select a node:';
+
+		const btn = document.createElement('button');
+		btn.style.cssText = 'display:flex; width:100%; text-align:left; padding:8px 12px; gap:12px; align-items:baseline;';
+		btn.innerHTML = `
+			<strong>${peer.name}</strong>
+			<span style="color:var(--text-dim);font-family:var(--font-mono);font-size:12px;margin-left:auto">
+				${peer.addr}:${peer.tcp_port}
+			</span>`;
+		btn.addEventListener('click', async () => {
+			close_picker();
+			try {
+				await connect_to_peer(peer);
+				await refresh_status();
+			} catch (err) {
+				toast(err.message, 'err');
+			}
+		});
+		peer_list.appendChild(btn);
+	};
+
+	es.onerror = () => {
+		title.textContent = 'Discovery error';
+		spinner.style.display = 'none';
+	};
+
+	/* -- close ------------------------------------------------------------- */
+	function close_picker() {
+		es.close();
+		discovery_es = null;
+		overlay.remove();
+	}
+
+	cancel_btn.addEventListener('click', close_picker);
+	overlay.addEventListener('click', e => { if (e.target === overlay) { close_picker(); } });
+}
+
+$('btn-disconnect').addEventListener('click', async () => {
+	await api('POST', '/api/disconnect');
+	selected_device_idx = null;
+	device_data = null;
+	show_empty_devices();
+	show_empty_controls();
+	await refresh_status();
+});
+
+$('btn-refresh-devices').addEventListener('click', refresh_devices);
+
+/* -------------------------------------------------------------------------
+ * Device list
+ * ------------------------------------------------------------------------- */
+
+function show_empty_devices() {
+	$('device-list').innerHTML = '<div class="empty">Not connected</div>';
+}
+
+function show_empty_controls(msg = 'Select a device') {
+	$('controls-title').textContent = 'Controls';
+	$('controls-scroll').innerHTML = `<div class="empty">${msg}</div>`;
+}
+
+async function refresh_devices() {
+	try {
+		device_data = await api('GET', '/api/devices');
+		render_device_list();
+	} catch (err) {
+		toast(err.message, 'err');
+	}
+}
+
+function render_device_list() {
+	const list = $('device-list');
+	list.innerHTML = '';
+
+	if (!device_data) { return; }
+
+	let flat_idx = 0;
+
+	const { media, standalone } = device_data;
+
+	if (media.length > 0) {
+		for (const md of media) {
+			const group = document.createElement('div');
+			group.className = 'device-group';
+
+			const gh = document.createElement('div');
+			gh.className = 'device-group-header';
+			gh.textContent = `${md.model}  (${md.driver})`;
+			group.appendChild(gh);
+
+			for (const vn of md.video_nodes) {
+				const idx = flat_idx++;
+				group.appendChild(make_device_item(idx, vn.path,
+					vn.entity_name, vn.device_caps, vn.is_capture));
+			}
+			list.appendChild(group);
+		}
+	}
+
+	if (standalone.length > 0) {
+		const group = document.createElement('div');
+		group.className = 'device-group';
+		const gh = document.createElement('div');
+		gh.className = 'device-group-header';
+		gh.textContent = 'Standalone';
+		group.appendChild(gh);
+		for (const sd of standalone) {
+			const idx = flat_idx++;
+			group.appendChild(make_device_item(idx, sd.path, sd.name, 0, false));
+		}
+		list.appendChild(group);
+	}
+
+	if (flat_idx === 0) {
+		list.innerHTML = '<div class="empty">No devices found</div>';
+	}
+
+	/* re-select previously selected device */
+	if (selected_device_idx !== null) {
+		const item = list.querySelector(`[data-idx="${selected_device_idx}"]`);
+		if (item) { item.classList.add('selected'); }
+	}
+}
+
+function make_device_item(idx, path, label, device_caps, is_capture) {
+	const el = document.createElement('div');
+	el.className = 'device-item';
+	el.dataset.idx = idx;
+
+	const caps_text = caps_tags(device_caps);
+	const badge = is_capture ? '<span class="capture-badge">capture</span>' : '';
+
+	el.innerHTML = `
+		<div class="d-path">${path}${badge}</div>
+		<div class="d-meta">${label}</div>
+		${caps_text ? `<div class="d-caps">${caps_text}</div>` : ''}
+	`;
+
+	el.addEventListener('click', () => select_device(idx, path));
+	return el;
+}
+
+async function select_device(idx, path) {
+	selected_device_idx = idx;
+	document.querySelectorAll('.device-item').forEach(el => {
+		el.classList.toggle('selected', parseInt(el.dataset.idx) === idx);
+	});
+	await load_controls(idx, path);
+}
+
+/* -------------------------------------------------------------------------
+ * Controls
+ * ------------------------------------------------------------------------- */
+
+async function load_controls(device_idx, device_path) {
+	$('controls-title').textContent = `Controls — ${device_path}`;
+	$('controls-scroll').innerHTML = '<div class="empty">Loading…</div>';
+	try {
+		const result = await api('GET', `/api/devices/${device_idx}/controls`);
+		render_controls(device_idx, result.controls ?? []);
+	} catch (err) {
+		toast(err.message, 'err');
+		show_empty_controls('Failed to load controls');
+	}
+}
+
+/*
+ * V4L2 control IDs with their class prefix (from linux/v4l2-controls.h).
+ * Used for grouping controls into sections.
+ */
+const CTRL_CLASSES = [
+	{ base: 0x00980000, name: 'User'         },
+	{ base: 0x009a0000, name: 'Camera'       },
+	{ base: 0x009b0000, name: 'Flash'        },
+	{ base: 0x009c0000, name: 'JPEG'         },
+	{ base: 0x009e0000, name: 'Image Source' },
+	{ base: 0x009f0000, name: 'Image Proc'   },
+	{ base: 0x00a20000, name: 'Codec'        },
+];
+
+function ctrl_class_name(id) {
+	for (const c of CTRL_CLASSES) {
+		if ((id & 0xFFFF0000) === c.base) { return c.name; }
+	}
+	return 'Other';
+}
+
+function render_controls(device_idx, controls) {
+	const scroll = $('controls-scroll');
+	scroll.innerHTML = '';
+
+	if (controls.length === 0) {
+		scroll.innerHTML = '<div class="empty">No controls</div>';
+		return;
+	}
+
+	const groups = new Map();
+	for (const ctrl of controls) {
+		const cls = ctrl_class_name(ctrl.id);
+		if (!groups.has(cls)) { groups.set(cls, []); }
+		groups.get(cls).push(ctrl);
+	}
+
+	for (const [cls_name, ctrls] of groups) {
+		const group_el = document.createElement('div');
+		group_el.className = 'ctrl-group';
+
+		const title = document.createElement('div');
+		title.className = 'ctrl-group-title';
+		title.textContent = cls_name;
+		group_el.appendChild(title);
+
+		for (const ctrl of ctrls) {
+			const row = make_ctrl_row(device_idx, ctrl);
+			if (row) { group_el.appendChild(row); }
+		}
+		scroll.appendChild(group_el);
+	}
+}
+
+function make_ctrl_row(device_idx, ctrl) {
+	const disabled  = !!(ctrl.flags & FLAG_DISABLED);
+	const read_only = !!(ctrl.flags & (FLAG_READ_ONLY | FLAG_GRABBED));
+
+	const row = document.createElement('div');
+	row.className = 'ctrl-row'
+		+ (disabled  ? ' disabled'  : '')
+		+ (read_only ? ' readonly'  : '');
+
+	const label_el = document.createElement('div');
+	label_el.className = 'ctrl-label';
+	label_el.textContent = ctrl.name;
+	row.appendChild(label_el);
+
+	const input_wrap = document.createElement('div');
+	input_wrap.className = 'ctrl-input';
+
+	const value_el = document.createElement('div');
+	value_el.className = 'ctrl-value-display';
+
+	let input_el = null;
+	let get_value = null;
+
+	switch (ctrl.type) {
+	case CTRL_BOOLEAN: {
+		input_el = document.createElement('input');
+		input_el.type = 'checkbox';
+		input_el.checked = !!ctrl.current_val;
+		get_value = () => input_el.checked ? 1 : 0;
+		value_el.textContent = '';
+		break;
+	}
+	case CTRL_MENU:
+	case CTRL_INTEGER_MENU: {
+		input_el = document.createElement('select');
+		for (const item of ctrl.menu_items) {
+			const opt = document.createElement('option');
+			opt.value = item.index;
+			opt.textContent = ctrl.type === CTRL_INTEGER_MENU
+				? item.int_value.toString()
+				: item.name;
+			if (item.index === ctrl.current_val) { opt.selected = true; }
+			input_el.appendChild(opt);
+		}
+		get_value = () => parseInt(input_el.value);
+		value_el.textContent = '';
+		break;
+	}
+	case CTRL_BUTTON: {
+		input_el = document.createElement('button');
+		input_el.textContent = ctrl.name;
+		input_el.style.width = '100%';
+		get_value = () => 1;
+		value_el.textContent = '';
+		break;
+	}
+	case CTRL_INTEGER:
+	default: {
+		const range = document.createElement('input');
+		range.type  = 'range';
+		range.min   = ctrl.min;
+		range.max   = ctrl.max;
+		range.step  = ctrl.step || 1;
+		range.value = ctrl.current_val;
+		value_el.textContent = ctrl.current_val;
+		range.addEventListener('input', () => {
+			value_el.textContent = range.value;
+		});
+		input_el = range;
+		get_value = () => parseInt(range.value);
+		break;
+	}
+	}
+
+	if (!input_el) { return null; }
+
+	input_wrap.appendChild(input_el);
+	row.appendChild(input_wrap);
+	row.appendChild(value_el);
+
+	/* send SET_CONTROL on change/click */
+	if (!read_only && !disabled) {
+		const send = async () => {
+			try {
+				const id_hex = ctrl.id.toString(16).padStart(8, '0');
+				await api('POST', `/api/devices/${device_idx}/controls/${id_hex}`,
+					{ value: get_value() });
+			} catch (err) {
+				toast(`${ctrl.name}: ${err.message}`, 'err');
+			}
+		};
+
+		if (ctrl.type === CTRL_BUTTON) {
+			input_el.addEventListener('click', send);
+		} else if (ctrl.type === CTRL_BOOLEAN || ctrl.type === CTRL_MENU
+				|| ctrl.type === CTRL_INTEGER_MENU) {
+			input_el.addEventListener('change', send);
+		} else {
+			/* slider: send on pointerup so we don't flood the node */
+			input_el.addEventListener('pointerup', send);
+			input_el.addEventListener('keyup', send);
+		}
+	}
+
+	return row;
+}
+
+/* -------------------------------------------------------------------------
+ * Init
+ * ------------------------------------------------------------------------- */
+
+refresh_status();

dev/web/public/index.html

@@ -0,0 +1,328 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="UTF-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1.0">
+	<title>Video Node Inspector</title>
+	<style>
+		*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+		:root {
+			--bg:        #1a1a1e;
+			--surface:   #25252b;
+			--surface2:  #2e2e36;
+			--border:    #3a3a44;
+			--text:      #e0e0e8;
+			--text-dim:  #888898;
+			--accent:    #5b8af0;
+			--accent2:   #3a5cc0;
+			--ok:        #4caf80;
+			--warn:      #e0a030;
+			--err:       #e05050;
+			--radius:    6px;
+			--font-mono: 'Cascadia Code', 'Fira Mono', monospace;
+		}
+
+		body {
+			background: var(--bg);
+			color: var(--text);
+			font-family: system-ui, sans-serif;
+			font-size: 14px;
+			display: flex;
+			flex-direction: column;
+			height: 100dvh;
+			overflow: hidden;
+		}
+
+		/* -- Top bar -------------------------------------------------------- */
+		#topbar {
+			display: flex;
+			align-items: center;
+			gap: 12px;
+			padding: 8px 16px;
+			background: var(--surface);
+			border-bottom: 1px solid var(--border);
+			flex-shrink: 0;
+		}
+
+		#topbar h1 { font-size: 15px; font-weight: 600; color: var(--text); }
+
+		#status-dot {
+			width: 8px; height: 8px; border-radius: 50%;
+			background: var(--err);
+			transition: background 0.3s;
+		}
+		#status-dot.ok { background: var(--ok); }
+
+		#status-text { font-size: 12px; color: var(--text-dim); margin-right: auto; }
+
+		button {
+			padding: 5px 12px;
+			border: 1px solid var(--border);
+			border-radius: var(--radius);
+			background: var(--surface2);
+			color: var(--text);
+			font-size: 13px;
+			cursor: pointer;
+		}
+		button:hover { background: var(--border); }
+		button.primary { background: var(--accent2); border-color: var(--accent); }
+		button.primary:hover { background: var(--accent); }
+
+		input[type=text], input[type=number] {
+			padding: 5px 8px;
+			border: 1px solid var(--border);
+			border-radius: var(--radius);
+			background: var(--surface2);
+			color: var(--text);
+			font-size: 13px;
+			width: 80px;
+		}
+
+		/* -- Connect bar ---------------------------------------------------- */
+		#connect-bar {
+			display: flex;
+			align-items: center;
+			gap: 8px;
+			padding: 6px 16px;
+			background: var(--surface);
+			border-bottom: 1px solid var(--border);
+			flex-shrink: 0;
+		}
+		#connect-bar label { font-size: 12px; color: var(--text-dim); }
+
+		/* -- Main layout ---------------------------------------------------- */
+		#main {
+			display: grid;
+			grid-template-columns: 260px 1fr;
+			flex: 1;
+			overflow: hidden;
+		}
+
+		/* -- Device panel --------------------------------------------------- */
+		#device-panel {
+			background: var(--surface);
+			border-right: 1px solid var(--border);
+			display: flex;
+			flex-direction: column;
+			overflow: hidden;
+		}
+
+		#device-panel h2 {
+			padding: 10px 14px;
+			font-size: 12px;
+			font-weight: 600;
+			text-transform: uppercase;
+			letter-spacing: 0.08em;
+			color: var(--text-dim);
+			border-bottom: 1px solid var(--border);
+			display: flex;
+			align-items: center;
+			justify-content: space-between;
+		}
+
+		#device-list {
+			overflow-y: auto;
+			flex: 1;
+		}
+
+		.device-group { padding: 8px 0 4px; }
+
+		.device-group-header {
+			padding: 4px 14px;
+			font-size: 11px;
+			font-weight: 600;
+			color: var(--text-dim);
+			text-transform: uppercase;
+			letter-spacing: 0.06em;
+		}
+
+		.device-item {
+			padding: 8px 14px;
+			cursor: pointer;
+			border-left: 3px solid transparent;
+			transition: background 0.1s;
+		}
+		.device-item:hover { background: var(--surface2); }
+		.device-item.selected {
+			background: var(--surface2);
+			border-left-color: var(--accent);
+		}
+
+		.device-item .d-path {
+			font-family: var(--font-mono);
+			font-size: 12px;
+			color: var(--accent);
+		}
+		.device-item .d-meta {
+			font-size: 11px;
+			color: var(--text-dim);
+			margin-top: 2px;
+		}
+		.device-item .d-caps {
+			font-size: 10px;
+			color: var(--text-dim);
+			margin-top: 2px;
+			font-family: var(--font-mono);
+		}
+		.capture-badge {
+			display: inline-block;
+			font-size: 9px;
+			padding: 1px 5px;
+			border-radius: 3px;
+			background: var(--accent2);
+			color: #fff;
+			margin-left: 6px;
+			vertical-align: middle;
+		}
+
+		/* -- Controls panel ------------------------------------------------- */
+		#controls-panel {
+			display: flex;
+			flex-direction: column;
+			overflow: hidden;
+		}
+
+		#controls-panel h2 {
+			padding: 10px 16px;
+			font-size: 12px;
+			font-weight: 600;
+			text-transform: uppercase;
+			letter-spacing: 0.08em;
+			color: var(--text-dim);
+			border-bottom: 1px solid var(--border);
+			display: flex;
+			align-items: center;
+			gap: 10px;
+		}
+
+		#controls-scroll { overflow-y: auto; flex: 1; padding: 12px 16px; }
+
+		.ctrl-group {
+			margin-bottom: 16px;
+		}
+
+		.ctrl-group-title {
+			font-size: 11px;
+			font-weight: 700;
+			text-transform: uppercase;
+			letter-spacing: 0.08em;
+			color: var(--text-dim);
+			padding: 4px 0 8px;
+			border-bottom: 1px solid var(--border);
+			margin-bottom: 8px;
+		}
+
+		.ctrl-row {
+			display: grid;
+			grid-template-columns: 200px 1fr auto;
+			align-items: center;
+			gap: 12px;
+			padding: 6px 0;
+			border-bottom: 1px solid var(--border);
+		}
+		.ctrl-row:last-child { border-bottom: none; }
+		.ctrl-row.disabled { opacity: 0.45; pointer-events: none; }
+		.ctrl-row.readonly { opacity: 0.65; }
+		.ctrl-row.readonly .ctrl-input { pointer-events: none; }
+
+		.ctrl-label { font-size: 13px; }
+		.ctrl-value-display {
+			font-family: var(--font-mono);
+			font-size: 12px;
+			color: var(--text-dim);
+			text-align: right;
+			min-width: 60px;
+		}
+
+		.ctrl-input { width: 100%; }
+
+		input[type=range] {
+			width: 100%;
+			accent-color: var(--accent);
+		}
+
+		select {
+			padding: 4px 8px;
+			border: 1px solid var(--border);
+			border-radius: var(--radius);
+			background: var(--surface2);
+			color: var(--text);
+			font-size: 13px;
+			width: 100%;
+		}
+
+		input[type=checkbox] {
+			width: 16px; height: 16px;
+			accent-color: var(--accent);
+		}
+
+		/* -- Toasts --------------------------------------------------------- */
+		#toast-container {
+			position: fixed; bottom: 16px; right: 16px;
+			display: flex; flex-direction: column; gap: 6px;
+			pointer-events: none; z-index: 100;
+		}
+		.toast {
+			padding: 8px 14px;
+			border-radius: var(--radius);
+			font-size: 13px;
+			background: var(--surface2);
+			border: 1px solid var(--border);
+			opacity: 1;
+			transition: opacity 0.4s;
+		}
+		.toast.err { border-color: var(--err); color: var(--err); }
+		.toast.ok  { border-color: var(--ok);  color: var(--ok);  }
+		.toast.fading { opacity: 0; }
+
+		/* -- Empty states --------------------------------------------------- */
+		.empty {
+			padding: 32px 16px;
+			text-align: center;
+			color: var(--text-dim);
+			font-size: 13px;
+		}
+	</style>
+</head>
+<body>
+
+<div id="topbar">
+	<div id="status-dot"></div>
+	<h1>Video Node Inspector</h1>
+	<span id="status-text">disconnected</span>
+	<button id="btn-discover">Discover</button>
+	<button id="btn-disconnect" style="display:none">Disconnect</button>
+</div>
+
+<div id="connect-bar">
+	<label>Host</label>
+	<input type="text" id="inp-host" placeholder="192.168.x.x" value="">
+	<label>Port</label>
+	<input type="number" id="inp-port" placeholder="7000" value="" style="width:70px">
+	<button id="btn-connect" class="primary">Connect</button>
+</div>
+
+<div id="main">
+	<div id="device-panel">
+		<h2>
+			Devices
+			<button id="btn-refresh-devices" style="font-size:11px;padding:2px 8px">↻</button>
+		</h2>
+		<div id="device-list">
+			<div class="empty">Not connected</div>
+		</div>
+	</div>
+	<div id="controls-panel">
+		<h2 id="controls-title">Controls</h2>
+		<div id="controls-scroll">
+			<div class="empty">Select a device</div>
+		</div>
+	</div>
+</div>
+
+<div id="toast-container"></div>
+
+<script type="module" src="app.mjs"></script>
+</body>
+</html>

dev/web/server.mjs

@@ -0,0 +1,174 @@
+/*
+ * Express 5 web server — REST bridge to video-node.
+ *
+ * Usage:
+ *   node server.mjs [--host IP] [--port PORT] [--discover] [--listen PORT]
+ *
+ * If --host and --port are given, connects on startup.
+ * If --discover is given, runs UDP discovery to find the node automatically.
+ * Otherwise, call POST /api/connect to connect at runtime.
+ */
+
+import express from 'express';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { Node_Client } from './node_client.mjs';
+import { start_discovery } from './discovery.mjs';
+
+/* -------------------------------------------------------------------------
+ * Argument parsing
+ * ------------------------------------------------------------------------- */
+
+const args = process.argv.slice(2);
+const arg = name => {
+	const i = args.indexOf(name);
+	return i >= 0 ? args[i + 1] : null;
+};
+
+const opt_host     = arg('--host');
+const opt_port     = arg('--port') ? parseInt(arg('--port')) : null;
+const opt_discover = args.includes('--discover');
+const listen_port  = arg('--listen') ? parseInt(arg('--listen')) : 3000;
+
+/* -------------------------------------------------------------------------
+ * Node client (singleton)
+ * ------------------------------------------------------------------------- */
+
+const client = new Node_Client();
+
+client.on('disconnect', () => {
+	console.log('video-node disconnected');
+});
+
+/* -------------------------------------------------------------------------
+ * Express app
+ * ------------------------------------------------------------------------- */
+
+const app = express();
+app.use(express.json());
+
+const __dir = path.dirname(fileURLToPath(import.meta.url));
+app.use(express.static(path.join(__dir, 'public')));
+
+/* -- Status ---------------------------------------------------------------- */
+
+app.get('/api/status', (_req, res) => {
+	res.json({
+		connected: client.connected,
+		host:      client.host,
+		port:      client.port,
+	});
+});
+
+/* -- Connect --------------------------------------------------------------- */
+
+app.post('/api/connect', async (req, res) => {
+	const { host, port } = req.body ?? {};
+	if (!host || !port) {
+		return res.status(400).json({ error: 'host and port required' });
+	}
+	try {
+		await client.connect(host, parseInt(port));
+		res.json({ ok: true, host: client.host, port: client.port });
+	} catch (err) {
+		res.status(502).json({ error: err.message });
+	}
+});
+
+/*
+ * SSE stream: each discovered peer arrives as a JSON event.
+ * The client closes the connection when done (user picked a node or dismissed).
+ */
+app.get('/api/discover', (req, res) => {
+	res.setHeader('Content-Type',  'text/event-stream');
+	res.setHeader('Cache-Control', 'no-cache');
+	res.setHeader('Connection',    'keep-alive');
+	res.flushHeaders();
+
+	const stop = start_discovery(peer => {
+		res.write(`data: ${JSON.stringify(peer)}\n\n`);
+	});
+
+	req.on('close', stop);
+});
+
+app.post('/api/disconnect', (_req, res) => {
+	client.disconnect();
+	res.json({ ok: true });
+});
+
+/* -- Devices --------------------------------------------------------------- */
+
+app.get('/api/devices', async (_req, res) => {
+	try {
+		const result = await client.enum_devices();
+		res.json(result);
+	} catch (err) {
+		res.status(502).json({ error: err.message });
+	}
+});
+
+/* -- Controls -------------------------------------------------------------- */
+
+app.get('/api/devices/:idx/controls', async (req, res) => {
+	const idx = parseInt(req.params.idx);
+	if (isNaN(idx)) { return res.status(400).json({ error: 'invalid device index' }); }
+	try {
+		const result = await client.enum_controls(idx);
+		res.json(result);
+	} catch (err) {
+		res.status(502).json({ error: err.message });
+	}
+});
+
+app.get('/api/devices/:idx/controls/:ctrl_id', async (req, res) => {
+	const idx     = parseInt(req.params.idx);
+	const ctrl_id = parseInt(req.params.ctrl_id, 16) || parseInt(req.params.ctrl_id);
+	if (isNaN(idx) || isNaN(ctrl_id)) {
+		return res.status(400).json({ error: 'invalid params' });
+	}
+	try {
+		const result = await client.get_control(idx, ctrl_id);
+		res.json(result);
+	} catch (err) {
+		res.status(502).json({ error: err.message });
+	}
+});
+
+app.post('/api/devices/:idx/controls/:ctrl_id', async (req, res) => {
+	const idx     = parseInt(req.params.idx);
+	const ctrl_id = parseInt(req.params.ctrl_id, 16) || parseInt(req.params.ctrl_id);
+	const value   = req.body?.value;
+	if (isNaN(idx) || isNaN(ctrl_id) || value === undefined) {
+		return res.status(400).json({ error: 'invalid params' });
+	}
+	try {
+		const result = await client.set_control(idx, ctrl_id, parseInt(value));
+		res.json(result);
+	} catch (err) {
+		res.status(502).json({ error: err.message });
+	}
+});
+
+/* -------------------------------------------------------------------------
+ * Startup
+ * ------------------------------------------------------------------------- */
+
+app.listen(listen_port, () => {
+	console.log(`listening on http://localhost:${listen_port}`);
+});
+
+if (opt_discover) {
+	console.log('discovering video-nodes...');
+	const stop = start_discovery(peer => {
+		console.log(`found ${peer.name} at ${peer.addr}:${peer.tcp_port} — connecting`);
+		stop();
+		client.connect(peer.addr, peer.tcp_port)
+			.then(() => console.log('connected'))
+			.catch(err => console.error('connect failed:', err.message));
+	});
+} else if (opt_host && opt_port) {
+	client.connect(opt_host, opt_port)
+		.then(() => console.log(`connected to ${opt_host}:${opt_port}`))
+		.catch(err => console.error('connect failed:', err.message));
+}