amaran-light-cli 1.11.0 → 1.12.0

package/scripts/ble-live-extended-check.ts

@@ -0,0 +1,205 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { z } from 'zod';
+import { SavedStateSchema } from '../src/ble/library.js';
+import { FAN_MODES, type FixtureState, parseFanMode } from '../src/ble/telink.js';
+import { captureWebcam, imagePixels, RegionSchema, regionsFile } from './webcam.js';
+
+const base = process.env.AMARAN_BLE_URL ?? 'http://127.0.0.1:2708';
+const run = Date.now();
+const results: unknown[] = [];
+const errors: string[] = [];
+const initial: Record<string, FixtureState> = {};
+const fans: Record<string, number> = {};
+const calibration = z.object({ regions: z.array(RegionSchema) }).parse(JSON.parse(readFileSync(regionsFile, 'utf8')));
+const keys = ['desk', 'front', 'back'];
+let changed = false;
+
+async function request(route: string, body?: object, method = body ? 'POST' : 'GET'): Promise<unknown> {
+  const response = await fetch(`${base}${route}`, {
+    method,
+    ...(body ? { body: JSON.stringify(body), headers: { 'content-type': 'application/json' } } : {}),
+    signal: AbortSignal.timeout(60_000),
+  });
+  const data = z
+    .object({ ok: z.boolean(), result: z.unknown().optional(), error: z.string().optional() })
+    .parse(await response.json());
+  if (!response.ok || !data.ok) throw new Error(`${route}: ${data.error ?? response.status}`);
+  results.push({ route, body, result: data.result });
+  return data.result;
+}
+async function light(key: string, action: string, body?: object) {
+  return SavedStateSchema.parse(await request(`/lights/${key}/${action}`, body));
+}
+function image(label: string) {
+  const filename = captureWebcam(`extended-${run}-${label}`);
+  return z
+    .object({
+      regions: z.array(
+        z.object({ name: z.string(), rgb: z.array(z.number()), haloRgb: z.array(z.number()).optional() })
+      ),
+    })
+    .parse(JSON.parse(readFileSync(filename.replace(/\.png$/, '.json'), 'utf8'))).regions;
+}
+function mean(rgb: number[]) {
+  return rgb.reduce((sum, value) => sum + value, 0) / rgb.length;
+}
+function pulsingVideo(key: string) {
+  const region = calibration.regions.find((entry) => entry.name === key);
+  if (!region) throw new Error(`No calibrated region for ${key}`);
+  const prefix = `extended-${run}-pulsing`;
+  const capture = spawnSync(
+    'ffmpeg',
+    [
+      '-hide_banner',
+      '-loglevel',
+      'error',
+      '-f',
+      'avfoundation',
+      '-pixel_format',
+      'nv12',
+      '-framerate',
+      '30',
+      '-video_size',
+      '1280x720',
+      '-i',
+      `${process.env.AMARAN_CAMERA_INDEX ?? '0'}:none`,
+      '-t',
+      '12',
+      '-vf',
+      'fps=2',
+      '-y',
+      `artifacts/webcam/${prefix}-%03d.png`,
+    ],
+    { encoding: 'utf8', timeout: 30_000 }
+  );
+  if (capture.status !== 0) throw new Error(capture.stderr || 'Pulsing video capture failed');
+  const levels = readdirSync('artifacts/webcam')
+    .filter((name) => name.startsWith(`${prefix}-`) && name.endsWith('.png'))
+    .sort()
+    .map((name) => {
+      const pixels = imagePixels(`artifacts/webcam/${name}`);
+      let sum = 0;
+      for (let y = region.y; y < region.y + region.height; y++)
+        for (let x = region.x; x < region.x + region.width; x++) {
+          const offset = (y * 1280 + x) * 3;
+          sum += mean([...pixels.subarray(offset, offset + 3)]);
+        }
+      return sum / (region.width * region.height);
+    });
+  assert.ok(levels.length >= 20, 'Need enough camera samples to observe pulsing');
+  const settled = levels.slice(6);
+  assert.ok(Math.max(...settled) - Math.min(...settled) > 40, `Camera did not confirm pulse modulation: ${levels}`);
+  const changes = settled.slice(1).map((value, index) => value - settled[index]);
+  assert.ok(
+    changes.some((value) => value > 20) && changes.some((value) => value < -20),
+    'Need both rising and falling output after camera exposure settles'
+  );
+  results.push({ opticalPulsing: { key, levels, span: Math.max(...settled) - Math.min(...settled) } });
+}
+
+try {
+  for (const key of keys) {
+    initial[key] = await light(key, 'state');
+    const fan = z.object({ mode: z.number() }).parse(await request(`/lights/${key}/fan`));
+    parseFanMode(fan.mode);
+    assert.notEqual(fan.mode, FAN_MODES.manual, 'Cannot infer an original manual RPM setpoint for restoration');
+    fans[key] = fan.mode;
+  }
+  writeFileSync(`artifacts/extended-${run}-initial.json`, JSON.stringify({ states: initial, fans }, null, 2), {
+    mode: 0o600,
+  });
+  assert.ok(
+    Object.values(initial).every((state) => state.mode === 'cct'),
+    'Begin hardware checks with all three fixtures in steady CCT mode'
+  );
+  changed = true;
+  await request('/batch', { targets: 'all', action: 'off', args: {} });
+  const dark = image('all-off');
+  await request('/batch', { targets: 'all', action: 'cct', args: { kelvin: 3200, brightness: 1 } });
+  const bright = image('all-1pct');
+  for (const key of keys) {
+    const before = dark.find((region) => region.name === key);
+    const after = bright.find((region) => region.name === key);
+    assert.ok(before && after);
+    assert.ok(mean(after.rgb) - mean(before.rgb) > 40, `Camera did not confirm ${key} illumination`);
+    const fan = z
+      .object({ mode: z.number(), speed: z.number(), highTemperature: z.boolean() })
+      .parse(await request(`/lights/${key}/fan`, { mode: 'medium' }));
+    assert.equal(fan.mode, 5);
+    assert.equal(fan.highTemperature, false);
+    await request(`/lights/${key}/fan`, { mode: fans[key] });
+  }
+  for (const gm of [-30, 30, 0]) {
+    assert.equal((await light('back', 'gm', { value: gm })).gm, gm);
+    image(`gm-${gm}`);
+  }
+  await request('/batch', { targets: 'all', action: 'brightness', args: { value: 2 }, broadcast: true });
+  for (const key of keys) assert.equal((await light(key, 'state')).intensity, 20);
+  image('broadcast-2pct');
+  await request('/fade', { targets: 'all', brightness: 1, seconds: 2 });
+  for (const key of keys) assert.equal((await light(key, 'state')).intensity, 10);
+  image('faded-1pct');
+  const scene = z.object({ id: z.string() }).parse(await request('/library/scenes', { name: `Hardware check ${run}` }));
+  try {
+    await light('back', 'color', { color: '#00ff00', brightness: 1 });
+    const colored = image('hsi-green').find((region) => region.name === 'back');
+    assert.ok(
+      colored?.haloRgb && colored.haloRgb[1] - Math.max(colored.haloRgb[0], colored.haloRgb[2]) > 20,
+      'Camera did not confirm green HSI'
+    );
+    await request(`/library/scenes/${scene.id}/recall`, {});
+    for (const key of keys) assert.equal((await light(key, 'state')).cct, 3200);
+  } finally {
+    await request(`/library/scenes/${scene.id}`, undefined, 'DELETE');
+  }
+  await light('front', 'off', {});
+  await light('back', 'off', {});
+  const pulse = await light('desk', 'effect', { name: 'pulsing', brightness: 1, frequency: 1, kelvin: 3200 });
+  assert.equal(pulse.effect, 'pulsing');
+  pulsingVideo('desk');
+  await light('desk', 'effect-stop', {});
+  await light('desk', 'off', {});
+  for (const settings of [
+    { name: 'pulsing', brightness: 1, frequency: 1, hue: 120, saturation: 100 },
+    { name: 'party-lights', brightness: 1, frequency: 1, saturation: 80 },
+  ]) {
+    const state = await light('back', 'effect', settings);
+    assert.equal(state.effect, settings.name);
+    image(settings.name);
+    await light('back', 'effect-intensity', { value: 2 });
+    await light('back', 'effect-stop', {});
+  }
+} catch (error) {
+  errors.push(String(error));
+} finally {
+  for (const [key, state] of changed ? Object.entries(initial) : []) {
+    try {
+      assert.equal(state.mode, 'cct', 'This check restores an initial steady CCT setup');
+      await light(key, 'cct', {
+        kelvin: state.cct,
+        brightness: state.intensity / 10,
+        ...(key === 'back' ? { gm: state.gm } : {}),
+      });
+      await light(key, state.sleep ? 'off' : 'on', {});
+      const restored = await light(key, 'state');
+      for (const field of ['cct', 'intensity', 'sleep'] as const) assert.equal(restored[field], state[field]);
+      if (key === 'back') assert.equal(restored.gm, state.gm);
+    } catch (error) {
+      errors.push(`Restore ${key}: ${error}`);
+    }
+    if (fans[key] !== undefined) {
+      try {
+        await request(`/lights/${key}/fan`, { mode: fans[key] });
+      } catch (error) {
+        errors.push(`Restore ${key} fan: ${error}`);
+      }
+    }
+  }
+  writeFileSync(`artifacts/extended-${run}-results.json`, JSON.stringify({ results, errors }, null, 2), {
+    mode: 0o600,
+  });
+}
+if (errors.length) throw new Error(errors.join('\n'));
+console.log(`Extended live checks passed; results saved to artifacts/extended-${run}-results.json`);

package/scripts/ble-non-ota-check.ts

@@ -0,0 +1,193 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { realpathSync, writeFileSync } from 'node:fs';
+import { z } from 'zod';
+import { SavedStateSchema } from '../src/ble/library.js';
+
+const base = process.env.AMARAN_BLE_URL ?? 'http://127.0.0.1:2708';
+const database = process.argv[2];
+if (!database) throw new Error('Supply the matching Desktop database path');
+const run = Date.now();
+const records: unknown[] = [],
+  failures: string[] = [];
+const cleanup: string[] = [],
+  jobs: string[] = [];
+let baseline: { id: string; states: Record<string, z.infer<typeof SavedStateSchema>> } | undefined;
+let overrides: Record<string, number> = {};
+async function request(route: string, body?: object, method = body ? 'POST' : 'GET') {
+  const response = await fetch(`${base}${route}`, {
+    method,
+    headers: { connection: 'close', ...(body ? { 'content-type': 'application/json' } : {}) },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+    signal: AbortSignal.timeout(60_000),
+  });
+  const data = z
+    .object({ ok: z.boolean(), result: z.unknown().optional(), error: z.string().optional() })
+    .parse(await response.json());
+  if (!response.ok || !data.ok) throw new Error(`${route}: ${data.error ?? response.status}`);
+  records.push({ route, body, result: data.result });
+  return data.result;
+}
+const Status = z.object({ id: z.string(), state: z.string(), frames: z.number(), error: z.string().optional() });
+async function start(body: object) {
+  const status = Status.parse(await request('/programs', body));
+  jobs.push(status.id);
+  return status;
+}
+async function wait(id: string, condition: (state: z.infer<typeof Status>) => boolean) {
+  const end = Date.now() + 30_000;
+  while (Date.now() < end) {
+    const status = Status.parse(await request(`/programs/${id}`));
+    if (status.state === 'failed') throw new Error(status.error);
+    if (condition(status)) return status;
+    await new Promise((resolve) => setTimeout(resolve, 150));
+  }
+  throw new Error('Timed out waiting for program');
+}
+async function state(key: string) {
+  return SavedStateSchema.parse(await request(`/lights/${key}/state`));
+}
+try {
+  overrides = Object.fromEntries(
+    Object.entries(z.record(z.number()).parse(await request('/overrides', { targets: 'all' }))).map(([key, ms]) => [
+      key,
+      ms ? Date.now() + ms : 0,
+    ])
+  );
+  for (const key of ['desk', 'front', 'back']) {
+    const light = await state(key);
+    assert.ok(!light.sleep && light.mode === 'cct' && light.intensity <= 50, 'Begin awake in CCT at 5% or less');
+  }
+  baseline = z
+    .object({ id: z.string(), states: z.record(SavedStateSchema) })
+    .parse(await request('/library/scenes', { name: `Non-OTA baseline ${run}` }));
+  const group = z.object({ id: z.string() }).parse(await request('/groups', { name: `Native verification ${run}` }));
+  cleanup.push(`/groups/${encodeURIComponent(group.id)}`);
+  for (const member of ['desk', 'back']) await request(`/groups/${encodeURIComponent(group.id)}/members`, { member });
+  await request(`/groups/${encodeURIComponent(group.id)}/native`, { action: 'enable' });
+  const changed = z
+    .object({ delivery: z.literal('native-group') })
+    .parse(await request(`/lights/${encodeURIComponent(group.id)}/brightness`, { value: 1 }));
+  assert.equal(changed.delivery, 'native-group');
+  assert.equal((await state('desk')).intensity, 10);
+  assert.equal((await state('back')).intensity, 10);
+  assert.equal((await state('front')).intensity, baseline.states.front.intensity);
+  await request(`/groups/${encodeURIComponent(group.id)}/members`, { member: 'front' });
+  await request(`/groups/${encodeURIComponent(group.id)}/members`, { member: 'front', remove: true });
+  await request(`/groups/${encodeURIComponent(group.id)}/native`, { action: 'disable' });
+  await request(`/library/scenes/${baseline.id}/recall`, {});
+  const preview = z
+    .object({
+      valid: z.boolean(),
+      plan: z.object({
+        groups: z.array(z.object({ id: z.string() })),
+        entries: z.array(z.object({ collection: z.string(), entry: z.object({ id: z.string() }) })),
+      }),
+    })
+    .parse(await request('/desktop/import', { database: realpathSync(database), prefix: `Import check ${run}` }));
+  assert.equal(preview.valid, true);
+  for (const item of preview.plan.groups) cleanup.push(`/groups/${encodeURIComponent(item.id)}`);
+  for (const item of preview.plan.entries)
+    cleanup.push(`/library/${item.collection}/${encodeURIComponent(item.entry.id)}`);
+  await request('/desktop/import', { database: realpathSync(database), prefix: `Import check ${run}`, apply: true });
+  const again = z
+    .object({ changes: z.object({ created: z.number(), unchanged: z.number() }) })
+    .parse(
+      await request('/desktop/import', { database: realpathSync(database), prefix: `Import check ${run}`, apply: true })
+    );
+  assert.equal(again.changes.created, 0);
+  assert.ok(again.changes.unchanged > 0);
+  const timeline = await start({
+    kind: 'timeline',
+    targets: 'all',
+    duration: 2,
+    steps: [
+      { at: 0, action: 'brightness', args: { value: 1 } },
+      { at: 1, action: 'brightness', args: { value: 2 } },
+    ],
+  });
+  await wait(timeline.id, (status) => status.state === 'completed');
+  const takeover = await start({
+    kind: 'timeline',
+    targets: ['back'],
+    duration: 5,
+    steps: [
+      { at: 0, action: 'brightness', args: { value: 1 } },
+      { at: 4, action: 'brightness', args: { value: 2 } },
+    ],
+  });
+  await wait(takeover.id, (status) => status.frames > 0);
+  await request('/lights/back/brightness', { value: 3 });
+  assert.equal(Status.parse(await request(`/programs/${takeover.id}`)).state, 'cancelled');
+  assert.equal((await state('back')).intensity, 30);
+  await request(`/library/scenes/${baseline.id}/recall`, {});
+  const picker = await start({
+    kind: 'picker',
+    targets: ['back'],
+    duration: 4,
+    maxBrightness: 1,
+    source: { kind: 'image-file', file: realpathSync('artifacts/program-test-green.png') },
+  });
+  await wait(picker.id, (status) => status.frames > 0);
+  assert.equal((await state('back')).mode, 'hsi');
+  assert.equal((await state('back')).hue, 120);
+  await wait(picker.id, (status) => status.state === 'completed');
+  const audio = await start({
+    kind: 'audio',
+    targets: 'all',
+    duration: 3,
+    maxBrightness: 2,
+    source: { kind: 'audio-file', file: realpathSync('artifacts/program-test-tone.wav') },
+  });
+  const audioDone = await wait(audio.id, (status) => status.state === 'completed');
+  assert.ok(audioDone.frames > 0);
+  const file = `artifacts/timeline-check-${run}.json`;
+  writeFileSync(file, JSON.stringify({ duration: 1, steps: [{ at: 0, action: 'brightness', args: { value: 1 } }] }), {
+    mode: 0o600,
+  });
+  execFileSync(process.execPath, ['dist/cli.js', 'ble', 'program', file, '--targets', 'back'], {
+    stdio: 'pipe',
+    timeout: 20_000,
+  });
+} catch (error) {
+  failures.push(String(error));
+} finally {
+  for (const id of jobs) {
+    try {
+      await request(`/programs/${id}`, undefined, 'DELETE');
+    } catch (error) {
+      failures.push(`Stop program ${id}: ${error}`);
+    }
+  }
+  if (baseline) {
+    try {
+      await request(`/library/scenes/${baseline.id}/recall`, {});
+      for (const [key, expected] of Object.entries(baseline.states)) {
+        const actual = await state(key);
+        for (const field of ['mode', 'intensity', 'sleep', 'cct'] as const)
+          assert.equal(actual[field], expected[field]);
+      }
+    } catch (error) {
+      failures.push(`Restore: ${error}`);
+    }
+    cleanup.push(`/library/scenes/${baseline.id}`);
+  }
+  for (const route of cleanup.reverse()) {
+    try {
+      await request(route, undefined, 'DELETE');
+    } catch (error) {
+      failures.push(`Cleanup ${route}: ${error}`);
+    }
+  }
+  if (!failures.length)
+    for (const [key, until] of Object.entries(overrides)) {
+      try {
+        await request('/overrides', { targets: [key], minutes: Math.max(0, (until - Date.now()) / 60_000) });
+      } catch (error) {
+        failures.push(`Restore override ${key}: ${error}`);
+      }
+    }
+  writeFileSync(`artifacts/non-ota-check-${run}.json`, JSON.stringify({ records, failures }, null, 2), { mode: 0o600 });
+}
+if (failures.length) throw new Error(failures.join('\n'));
+console.log(`Non-OTA checks passed; original state restored: artifacts/non-ota-check-${run}.json`);

package/scripts/ble-probe.ts

@@ -0,0 +1,45 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { MeshCrypto } from '../src/ble/crypto.js';
+import { importMesh } from '../src/ble/setup.js';
+import { loadMeshConfig, meshDirectory, SequenceStore } from '../src/ble/storage.js';
+import { cctPacket, powerPacket } from '../src/ble/telink.js';
+import { MeshTransport } from '../src/ble/transport.js';
+import { captureWebcam } from './webcam.js';
+
+if (process.argv[2] === 'import') {
+  importMesh(process.argv[3]);
+} else {
+  const config = loadMeshConfig();
+  const crypto = new MeshCrypto(config.netKey, config.appKey);
+  const sequence = new SequenceStore(meshDirectory(), crypto.networkId.toString('hex'), config.source);
+  const transport = new MeshTransport(config, sequence, true);
+  try {
+    await transport.connect();
+    if (process.argv[2] === 'test-desk') {
+      const light = config.lights.find((entry) => entry.key === 'desk');
+      if (!light) throw new Error('Desk fixture not configured');
+      try {
+        await transport.send(light.address, cctPacket(3200, 10));
+        await delay(300);
+        await transport.send(light.address, powerPacket(true));
+        await delay(300);
+        console.log('ON state', await transport.readState(light.address));
+        console.log(captureWebcam(`ble-desk-on-${Date.now()}`));
+      } finally {
+        await transport.send(light.address, powerPacket(false));
+        await delay(300);
+        console.log('OFF state', await transport.readState(light.address));
+      }
+      console.log(captureWebcam(`ble-desk-off-${Date.now()}`));
+    } else {
+      for (const light of config.lights) {
+        console.log(light.name, await transport.readState(light.address));
+        console.log('Fan', await transport.readFan(light.address));
+      }
+    }
+  } finally {
+    await transport.disconnect();
+    sequence.close();
+  }
+  process.exit(0);
+}

package/scripts/calibrate-webcam.ts

@@ -0,0 +1,152 @@
+import { readdirSync, writeFileSync } from 'node:fs';
+import { setTimeout as delay } from 'node:timers/promises';
+import { MeshCrypto } from '../src/ble/crypto.js';
+import { loadMeshConfig, meshDirectory, SequenceStore } from '../src/ble/storage.js';
+import { cctPacket, type FixtureState, powerPacket } from '../src/ble/telink.js';
+import { MeshTransport } from '../src/ble/transport.js';
+import { type CameraRegion, captureWebcam, imagePixels, regionsFile } from './webcam.js';
+
+function locateLight(dark: Buffer, lit: Buffer, name: string): CameraRegion {
+  const width = 320;
+  const height = 180;
+  const mask = new Uint8Array(width * height);
+  for (let y = 1; y < height - 1; y++)
+    for (let x = 1; x < width - 1; x++) {
+      let bright = true;
+      for (let dy = -1; dy <= 1; dy++)
+        for (let dx = -1; dx <= 1; dx++) {
+          const offset = ((y + dy) * 4 * 1280 + (x + dx) * 4) * 3;
+          const light = (lit[offset] + lit[offset + 1] + lit[offset + 2]) / 3;
+          const before = (dark[offset] + dark[offset + 1] + dark[offset + 2]) / 3;
+          if (light < 248 || light - before < 65) bright = false;
+        }
+      if (bright) mask[y * width + x] = 1;
+    }
+  const candidates: { count: number; x: number; y: number; width: number; height: number }[] = [];
+  for (let start = 0; start < mask.length; start++) {
+    if (!mask[start]) continue;
+    const queue = [start];
+    mask[start] = 0;
+    let minX = width,
+      maxX = 0,
+      minY = height,
+      maxY = 0;
+    for (let i = 0; i < queue.length; i++) {
+      const index = queue[i],
+        x = index % width,
+        y = Math.floor(index / width);
+      minX = Math.min(minX, x);
+      maxX = Math.max(maxX, x);
+      minY = Math.min(minY, y);
+      maxY = Math.max(maxY, y);
+      for (const next of [
+        index - width,
+        index + width,
+        ...(x > 0 ? [index - 1] : []),
+        ...(x < width - 1 ? [index + 1] : []),
+      ]) {
+        if (next >= 0 && next < mask.length && mask[next]) {
+          mask[next] = 0;
+          queue.push(next);
+        }
+      }
+    }
+    const w = maxX - minX + 1,
+      h = maxY - minY + 1;
+    if (queue.length >= 8 && w / h > 0.35 && w / h < 2.8 && w < 70 && h < 70) {
+      candidates.push({ count: queue.length, x: (minX + maxX) * 2, y: (minY + maxY) * 2, width: w * 4, height: h * 4 });
+    }
+  }
+  candidates.sort((a, b) => b.count - a.count);
+  const best = candidates[0];
+  if (!best || (candidates[1] && candidates[1].count > best.count * 0.7))
+    throw new Error(`Cannot identify a unique emitting fixture for ${name}: ${JSON.stringify(candidates)}`);
+  const size = Math.max(8, Math.min(24, Math.floor(Math.min(best.width, best.height) / 2)));
+  return { name, x: Math.round(best.x - size / 2), y: Math.round(best.y - size / 2), width: size, height: size };
+}
+
+const config = loadMeshConfig();
+if (process.argv.includes('--reuse')) {
+  const capture = readdirSync('artifacts/webcam')
+    .filter((name) => /^calibration-\d+-off\.png$/.test(name))
+    .sort()
+    .at(-1);
+  if (!capture) throw new Error('No saved calibration captures');
+  const prefix = `artifacts/webcam/${capture.replace(/-off\.png$/, '')}`;
+  const dark = imagePixels(`${prefix}-off.png`);
+  const regions = config.lights.map((light) => locateLight(dark, imagePixels(`${prefix}-${light.key}.png`), light.key));
+  writeFileSync(
+    regionsFile,
+    JSON.stringify(
+      { cameraIndex: process.env.AMARAN_CAMERA_INDEX ?? '0', capturedAt: new Date().toISOString(), regions },
+      null,
+      2
+    ),
+    { mode: 0o600 }
+  );
+  console.log(prefix, regions);
+  process.exit(0);
+}
+const crypto = new MeshCrypto(config.netKey, config.appKey);
+const sequence = new SequenceStore(meshDirectory(), crypto.networkId.toString('hex'), config.source);
+const transport = new MeshTransport(config, sequence);
+const original = new Map<number, FixtureState>();
+const regions: CameraRegion[] = [];
+const errors: unknown[] = [];
+try {
+  await transport.connect();
+  for (const light of config.lights) {
+    const state = await transport.readState(light.address);
+    if (state.mode !== 'cct')
+      throw new Error('Camera calibration currently requires CCT mode so all settings can be restored');
+    original.set(light.address, state);
+  }
+  for (const light of config.lights) await transport.send(light.address, powerPacket(false));
+  await delay(300);
+  const stamp = Date.now();
+  const dark = imagePixels(captureWebcam(`calibration-${stamp}-off`));
+  for (const light of config.lights) {
+    await transport.send(light.address, cctPacket(3200, 10, 0));
+    await delay(300);
+    const frame = captureWebcam(`calibration-${stamp}-${light.key}`);
+    regions.push(locateLight(dark, imagePixels(frame), light.key));
+    await transport.send(light.address, powerPacket(false));
+    await delay(300);
+  }
+  writeFileSync(
+    regionsFile,
+    JSON.stringify(
+      { cameraIndex: process.env.AMARAN_CAMERA_INDEX ?? '0', capturedAt: new Date().toISOString(), regions },
+      null,
+      2
+    ),
+    { mode: 0o600 }
+  );
+  console.log('Identified fixture regions:', regions);
+} catch (error) {
+  errors.push(error);
+} finally {
+  for (const light of config.lights) {
+    const state = original.get(light.address);
+    if (!state) continue;
+    try {
+      await transport.send(light.address, cctPacket(state.cct ?? 3200, state.intensity, state.gm ?? 0));
+      await delay(200);
+      await transport.send(light.address, powerPacket(!state.sleep));
+      const actual = await transport.readState(light.address);
+      if (
+        actual.cct !== state.cct ||
+        actual.intensity !== state.intensity ||
+        actual.sleep !== state.sleep ||
+        (light.model === '150c' && actual.gm !== state.gm)
+      )
+        errors.push(new Error(`Failed to restore ${light.key}`));
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  await transport.disconnect();
+  sequence.close();
+}
+if (errors.length) throw new AggregateError(errors, 'Camera calibration failed');
+process.exit(0);

package/scripts/desktop-reference.ts

@@ -0,0 +1,85 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { setTimeout as delay } from 'node:timers/promises';
+import WebSocket from 'ws';
+import { captureWebcam } from './webcam.js';
+
+const ws = new WebSocket(process.env.AMARAN_REFERENCE_WS ?? 'ws://127.0.0.1:12345');
+const pending = new Map<string, { resolve: (value: unknown) => void; reject: (error: Error) => void }>();
+ws.on('message', (raw) => {
+  const message = JSON.parse(raw.toString());
+  const key = `${message.request?.type}:${message.request?.node_id ?? ''}`;
+  const request = pending.get(key);
+  if (!request) return;
+  if (message.code !== 0) request.reject(new Error(message.message));
+  else request.resolve(message.data?.data ?? message.data);
+});
+
+async function command(type: string, nodeId?: string, args?: Record<string, unknown>): Promise<unknown> {
+  const key = `${type}:${nodeId ?? ''}`;
+  if (pending.has(key)) throw new Error(`Concurrent duplicate command: ${key}`);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await new Promise((resolve, reject) => {
+      pending.set(key, { resolve, reject });
+      timer = setTimeout(() => reject(new Error(`Desktop response timeout: ${key}`)), 8000);
+      ws.send(JSON.stringify({ version: 1, client_id: 'hardware-reference', type, node_id: nodeId, args }));
+    });
+  } finally {
+    clearTimeout(timer);
+    pending.delete(key);
+  }
+}
+
+const fixtures = [
+  { key: 'desk', nodeId: '400Q5-11B2F8' },
+  { key: 'front', nodeId: '400Q5-119B16' },
+  { key: 'back', nodeId: '400J5-F2C008' },
+];
+
+try {
+  await new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error('Desktop connection timeout')), 8000);
+    ws.once('open', () => {
+      clearTimeout(timeout);
+      resolve();
+    });
+    ws.once('error', (error) => {
+      clearTimeout(timeout);
+      reject(error);
+    });
+  });
+  mkdirSync('artifacts', { recursive: true });
+  const snapshot = [];
+  for (const fixture of fixtures) {
+    snapshot.push({
+      ...fixture,
+      sleep: await command('get_sleep', fixture.nodeId),
+      intensity: await command('get_intensity', fixture.nodeId),
+      cct: await command('get_cct', fixture.nodeId),
+    });
+  }
+  writeFileSync(`artifacts/desktop-state-${Date.now()}.json`, JSON.stringify(snapshot, null, 2), { mode: 0o600 });
+  console.log(JSON.stringify(snapshot, null, 2));
+  if (process.argv[2] === 'reference') {
+    const stamp = Date.now();
+    for (const fixture of fixtures) {
+      await command('set_intensity', fixture.nodeId, { intensity: 10 });
+      await command('set_sleep', fixture.nodeId, { sleep: true });
+    }
+    await delay(1000);
+    console.log(captureWebcam(`desktop-${stamp}-all-off`));
+    for (const fixture of fixtures) {
+      await command('set_cct', fixture.nodeId, { cct: 3200, intensity: 10 });
+      await command('set_sleep', fixture.nodeId, { sleep: false });
+      await delay(1000);
+      console.log(captureWebcam(`desktop-${stamp}-${fixture.key}-3200-1pct`));
+      await command('set_cct', fixture.nodeId, { cct: 6500, intensity: 10 });
+      await delay(1000);
+      console.log(captureWebcam(`desktop-${stamp}-${fixture.key}-6500-1pct`));
+      await command('set_sleep', fixture.nodeId, { sleep: true });
+    }
+    console.log('Reference complete. All fixtures left asleep at 1%; original state saved in artifacts.');
+  }
+} finally {
+  ws.close();
+}