@khalido/home 0.1.3 → 0.2.0

package/dist/home.js

@@ -36,24 +36,75 @@ function stamped(part, before, now) {
 }
 /**
  * Load a home: run each integration, keep one snapshot, call `onChange` with it and what changed after every report.
- * `clock` stamps each part's `lastGoodAt` and `downSince`.
+ * `clock` stamps each part's `lastGoodAt` and `downSince`. `add` and `remove` change the set while it runs.
  */
 export function createHome(integrations, onChange, options = {}) {
     const clock = options.clock ?? realClock;
-    let snapshot = Object.fromEntries(integrations.map((i) => [i.name, { status: "connecting" }]));
+    const list = [...integrations]; // the integrations now: `add` and `remove` change it
+    const parts = () => snapshot;
+    let snapshot = Object.fromEntries(list.map((i) => [i.name, { status: "connecting" }]));
     const waiting = new Map(); // refresh() callers, resolved by the integration's next report
-    const finished = new Set(integrations.map((i) => i.name)); // not running, before start or after its run ended: a refresh of one resolves at once, nothing will report
-    const set = (name, reported) => {
-        const before = snapshot[name];
+    const runs = new Map(); // the ones running: before start or after its run ended, a refresh resolves at once, nothing will report
+    const latest = new WeakMap(); // each integration's newest run: a report from an older run of the same object is dropped
+    let started; // start()'s signal, while it runs
+    let changing = Promise.resolve(); // add and remove, one at a time: two on one name must not overlap
+    let changes = 0; // those under way or queued: start outlasts a replace of its only integration
+    const change = (fn) => {
+        changes++;
+        const done = changing.then(fn).finally(() => changes--);
+        changing = done.catch(() => { });
+        return done;
+    };
+    const heard = (name) => {
+        for (const resolve of waiting.get(name) ?? [])
+            resolve();
+        waiting.delete(name);
+    };
+    // A report counts only from the integration now listed under its name: one replaced or removed may still be finishing.
+    const set = (i, run, reported) => {
+        const name = i.name;
+        const before = parts()[name];
+        if (latest.get(i) !== run || !list.includes(i) || !before)
+            return;
         const part = stamped(reported, before, asOf(clock));
         snapshot = { ...snapshot, [name]: part };
         Promise.try(() => onChange?.(snapshot, { name, before, after: part })).catch((error) => console.error(`onChange threw on ${name}: ${errorText(error)}`)); // the caller's bug, thrown or async, not the device's: the integration keeps running
-        const w = waiting.get(name);
-        if (w) {
-            waiting.delete(name);
-            for (const resolve of w)
-                resolve();
-        }
+        heard(name);
+    };
+    /** Run one integration until the home's signal or its own `stop` aborts. One failing marks itself unavailable. */
+    const launch = (i, signal) => {
+        const stop = new AbortController();
+        const run = { stop, done: Promise.resolve() };
+        runs.set(i, run);
+        latest.set(i, run);
+        run.done = Promise.try(() => i.run(AbortSignal.any([signal, stop.signal]), (part) => set(i, run, part)))
+            .catch((error) => set(i, run, {
+            status: "unavailable",
+            reason: "crashed",
+            detail: errorText(error),
+            state: parts()[i.name]?.state, // the last good state stays, as it does through a failed read
+        }))
+            .finally(() => {
+            if (runs.get(i) !== run)
+                return;
+            runs.delete(i);
+            if (list.includes(i))
+                heard(i.name); // nothing more will report
+        });
+    };
+    /** Take one out of the list and the snapshot, and wait for its run to end. */
+    const drop = async (name) => {
+        const at = list.findIndex((i) => i.name === name);
+        if (at < 0)
+            return false;
+        const [old] = list.splice(at, 1);
+        const { [name]: _, ...rest } = parts();
+        snapshot = rest;
+        heard(name);
+        const run = runs.get(old);
+        run?.stop.abort();
+        await run?.done;
+        return true;
     };
     return {
         /** The latest snapshot. Never touches a device. */
@@ -61,19 +112,17 @@ export function createHome(integrations, onChange, options = {}) {
         /** One integration's part, typed by its name: `home.part("weather")?.state?.blocks`. */
         part: (name) => snapshot[name],
         /** One integration by name, for its writes: `home.integration("daikin")?.client.write(setPower(true))`. */
-        integration: (name) => integrations.find((i) => i.name === name),
+        integration: (name) => list.find((i) => i.name === name),
         /**
          * Read now: one integration by name, or every one. Results arrive through the snapshot and `onChange` as usual; the
          * promise resolves once each target has reported (its next update, good or bad), or at once for one that isn't running.
          */
         refresh(name) {
-            const targets = name === undefined
-                ? integrations
-                : integrations.filter((i) => i.name === name);
-            if (!targets.length)
-                throw new Error(`no integration "${name}"; have ${integrations.map((i) => i.name).join(", ")}`);
+            const targets = name === undefined ? [...list] : list.filter((i) => i.name === name);
+            if (!targets.length && name !== undefined)
+                throw new Error(`no integration "${name}"; have ${list.map((i) => i.name).join(", ")}`);
             const reported = targets.map((i) => new Promise((resolve) => {
-                if (finished.has(i.name))
+                if (!runs.has(i))
                     return resolve();
                 waiting.set(i.name, [...(waiting.get(i.name) ?? []), resolve]);
             }));
@@ -81,29 +130,44 @@ export function createHome(integrations, onChange, options = {}) {
                 i.refresh();
             return Promise.all(reported).then(() => undefined);
         },
-        /** Run every integration until `signal` aborts. One failing marks itself unavailable; the rest carry on. */
+        /**
+         * Add an integration while the home runs, or before it starts: a bridge paired just now, a key that arrived late. One
+         * already there under that name is stopped first and its part dropped, so the new one starts from `connecting` and
+         * the two never run together. Resolves once the new one is running; its reports arrive as any other's. Calls on
+         * one home run one at a time. Once `start`'s signal has aborted, an added one waits for the next `start`.
+         */
+        add: (integration) => change(async () => {
+            await drop(integration.name);
+            list.push(integration);
+            const live = started && !started.aborted ? started : undefined;
+            snapshot = {
+                ...snapshot,
+                [integration.name]: {
+                    status: "connecting",
+                    ...(live ? { downSince: asOf(clock) } : {}),
+                },
+            };
+            if (live)
+                launch(integration, live);
+        }),
+        /** Stop one integration and drop its part from the snapshot. Resolves once its run has ended; false if there was none by that name. */
+        remove: (name) => change(() => drop(name)),
+        /** Run every integration, and any added meanwhile, until `signal` aborts. One failing marks itself unavailable; the rest carry on. */
         async start(signal) {
-            finished.clear(); // a second start, after the first has stopped, runs them all again
+            started = signal;
             const now = asOf(clock); // the wait for a first report counts from here, not from createHome
-            snapshot = Object.fromEntries(Object.entries(snapshot).map(([name, p]) => [
+            snapshot = Object.fromEntries(Object.entries(parts()).map(([name, p]) => [
                 name,
                 p.status === "connecting"
                     ? { ...p, downSince: p.downSince ?? now }
                     : p,
             ]));
-            await Promise.all(integrations.map((i) => Promise.try(() => i.run(signal, (part) => set(i.name, part)))
-                .catch((error) => set(i.name, {
-                status: "unavailable",
-                reason: "crashed",
-                detail: errorText(error),
-                state: snapshot[i.name].state, // the last good state stays, as it does through a failed read
-            }))
-                .finally(() => {
-                finished.add(i.name);
-                for (const resolve of waiting.get(i.name) ?? [])
-                    resolve(); // nothing more will report
-                waiting.delete(i.name);
-            })));
+            for (const i of list)
+                launch(i, signal); // a second start, after the first has stopped, runs them all again
+            // Until every run has ended, those added meanwhile too.
+            while (runs.size || changes)
+                await Promise.all([...[...runs.values()].map((r) => r.done), changing]);
+            // `started` stays: one added after every run has ended still runs, until the signal aborts.
         },
     };
 }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { type Change, createHome, type DeviceRecord, deviceRecords, envName, filePath, settle, type HomeSnapshot, type Integration, type Part, type Reason, type StateOf, type Status, } from "./home.ts";
 export { DOWN_POLLS, type Health, health, PUSH_DOWN_MS, STALE_POLLS, } from "./health.ts";
-export { type HomeDevice, homeDevices } from "./devices.ts";
+export { byRoom, type HomeDevice, homeDevices, type RoomDevices, spotifyElsewhere, } from "./devices.ts";
 export { asOf, type Clock, realClock } from "./clock.ts";
 export { type ConnectorCode, ConnectorError } from "./connector.ts";
 export { bestWindow, type EnergyNow, energyNow, gridText, type PriceWindow, solarLevel, } from "./energy.ts";

package/dist/index.js

@@ -2,7 +2,7 @@
 // Each connector has its own entry point (`@khalido/home/hue` and so on). Every export is named; test/exports.test.ts lists them.
 export { createHome, deviceRecords, envName, filePath, settle, } from "./home.js";
 export { DOWN_POLLS, health, PUSH_DOWN_MS, STALE_POLLS, } from "./health.js";
-export { homeDevices } from "./devices.js";
+export { byRoom, homeDevices, spotifyElsewhere, } from "./devices.js";
 export { asOf, realClock } from "./clock.js";
 export { ConnectorError } from "./connector.js";
 export { bestWindow, energyNow, gridText, solarLevel, } from "./energy.js";

package/dist/node-fetch.d.ts

@@ -1,5 +1,5 @@
-/** A `fetch` that trusts only `ca` and accepts only a certificate whose CN is `bridgeId`: Node's `bunPinnedFetch`. */
-export declare function nodePinnedFetch(bridgeId: string, ca: string): typeof fetch;
+/** A `fetch` that trusts only `ca` (Signify's roots when left out) and accepts only a certificate whose CN is `bridgeId`: Node's `bunPinnedFetch`. */
+export declare function nodePinnedFetch(bridgeId: string, ca?: string): typeof fetch;
 /** A `fetch` for the Enphase gateway that skips certificate verification, for its requests only: Node's `bunGatewayFetch`. */
 export declare function nodeGatewayFetch(): typeof fetch;
 /** What `loadHome` takes as `tls` under Node. */

package/dist/node-fetch.js

@@ -1,11 +1,12 @@
 import { Agent, fetch as undiciFetch } from "undici";
+import { HUE_BRIDGE_ROOT_CA } from "./connectors/hue/ca.js";
 // `@khalido/home/node`: the fetches Hue and Enphase need under Node, where Bun's `tls` fetch option does not exist. Node's
 // global `fetch` takes no CA, so these use undici's own `fetch` and `Agent` (one undici on both sides). Outside the
 // runtime-neutral build, like cast/tls.ts; a Node consumer passes `NODE_TLS` to `loadHome`, or one fetch to `hue()` or `enphase()`.
 /** undici's `fetch` through `dispatcher`. Takes a URL, not a `Request`, and returns undici's own `Response`. */
 const through = (dispatcher) => ((input, init) => undiciFetch(input, { ...init, dispatcher }));
-/** A `fetch` that trusts only `ca` and accepts only a certificate whose CN is `bridgeId`: Node's `bunPinnedFetch`. */
-export function nodePinnedFetch(bridgeId, ca) {
+/** A `fetch` that trusts only `ca` (Signify's roots when left out) and accepts only a certificate whose CN is `bridgeId`: Node's `bunPinnedFetch`. */
+export function nodePinnedFetch(bridgeId, ca = HUE_BRIDGE_ROOT_CA) {
     const checkServerIdentity = (_host, cert) => {
         const cn = [cert.subject?.CN].flat()[0];
         return cn?.toLowerCase() === bridgeId.toLowerCase()

package/docs/cli.md

@@ -3,11 +3,16 @@
 ```sh
 home <connector> [--json]     # one connector's lines: amber, cast, daikin, enphase, hue, printers, spotify, up, weather
 home [status|doctor] [--json] # each integration: connected or not, which env names it still needs, rooms
+home devices [--json]         # every device the connectors read, one line each: its state, its room (with a config), and why when it isn't available
 home up transactions | categories | uncategorised | spend | categorise | tag | webhooks  # Up Bank's lists and reports; categorise and tag write
-home lights off               # one write to the whole-home group
-home room <name> on|off|<1-100>
-home scene <name>
-home pair                     # press the bridge's button first; prints the env lines to set
+home lights off               # one write to the whole-home group; prints how many lights are off, or how many the bridge still reports on
+home light <name> [on|off] [<1-100>] [<kelvin>k] [<hex colour>]  # one light: `home light "Desk lamp" 40 2700k`, `home light Shelf ff8800`
+home room <name> [on|off] [<1-100>] [<kelvin>k] [<hex colour>]   # every light in a room or zone, one write
+home scene <name> [in <room>]  # a scene; name the room when several have one by that name
+home pair                     # waits 60 s for the bridge's button, counting down; prints the env lines to set
+home daikin on | off           # power only: the AC comes back as it was last left
+home daikin cool | heat | auto [°C] | dry | fan  # mode, on, and the setpoint: the one given, else cool 25 and heat 27; prints what the unit then reports. Live on KO's unit: on, and dry to cool at 25 (2026-11-11); the rest untried
+                              # --dry-run on a hue or daikin write (lights, light, room, scene, daikin …): check it and print what would be sent; nothing is sent. Refused on every other command
 home enphase login            # once a year: mints the Enphase owner token into ~/.config/home/ (0600)
 home discover [--json] [--passes n]  # which smart-home devices answer here (mDNS + Daikin UDP), which this package supports, then with a config how they match it; two passes 5 s apart
 home cache [clear]            # the addresses kept between runs, or delete them so the next run discovers afresh
@@ -19,6 +24,7 @@ home cast announce --to <name> [--to <name>…] (--say "<text>" | --file <path>)
 home cast volume <name> <0-100>
 home cast mute <name> on|off
 home cast stop <name>         # end the running app; the device returns to its idle screen
+                              # volume, mute and stop print the device's line once it reports the change (within 2 s), else "sent; the device has not reported it yet"
 home spotify activate | pause | play [link] | next | volume <0-100>  # the Soloist speaker at SOLOIST_WS; volume held to SOLOIST_MAX_VOLUME; prints what Soloist then reported
 ```
 
@@ -26,16 +32,16 @@ home spotify activate | pause | play [link] | next | volume <0-100>  # the Soloi
 
 - **stdout is data, stderr everything else.** Notes such as "nothing to categorise" or "no webhooks" go to stderr, so `home … | jq` never sees them.
 - **Bun on PATH.** The command starts with `#!/usr/bin/env bun`. A non-login SSH shell may not have `~/.bun/bin` on its PATH: run `PATH="$HOME/.bun/bin:$PATH" home`.
-- **`--json` shapes.** `home --json` is one object keyed by connector, with `now` (`energyNow`) first. `home <connector> --json` is that connector's object: `status`, `needs`, `access`, `detail`, `reason` (why it is `unavailable`, when known: `auth`, `config` or `crashed`), `anomaly`, then its state (the weather adds `line`, its text). Lists (`home up transactions`, `uncategorised`, `spend --by merchant`) are arrays, `[]` when empty.
+- **`--json` shapes.** `home --json` is one object keyed by connector, with `now` (`energyNow`) first. `home devices --json` is the array `homeDevices` returns; a connector that isn't connected is named on stderr, and the command exits 0. `home <connector> --json` is that connector's object: `status`, `needs`, `access`, `detail`, `reason` (why it is `unavailable`, when known: `auth`, `config` or `crashed`), `anomaly`, then its state (the weather adds `line`, its text). Lists (`home up transactions`, `uncategorised`, `spend --by merchant`) are arrays, `[]` when empty.
 - **Errors under `--json`** are one object on stderr: `{"error": "…", "code": "usage" | "auth" | "network" | "error", "fix": "home enphase login"}`; `fix` is there only when one command resolves it. In text: `home: <error> (run \`<fix>\`)`.
 - **Exit codes.** 0 success, empty results included. 1 a failure, and `home <connector>` when that connector is not `connected`, so a script can test one. 2 a wrong command, verb or argument. `home` alone lists every connector and exits 0 whatever their state.
 
 With `--config <home.jsonc>` or `HOME_CONFIG`, `status` runs the integrations the config describes until each has answered (at most 15 s) and `probe` takes its addresses from it; keys still come from the shell, by the names in the file. Without one, it reads `HUE_*` and the other names in `.env.example` from the shell, and parses arguments with [cac](https://github.com/cacjs/cac), which also generates `home --help`. Every connector has a verb of its own: `home amber`, `home cast`, `home hue` print only that connector's lines (`--json` for its record), and the verbs that need more sit under it (`home hue pair`, `home enphase login`, `home cast announce …`). The commands come from each connector's manifest (`src/manifest.ts`), as does `.env.example` (`bun run gen`). With no `HUE_BRIDGE_HOST` it finds the bridge by mDNS (`dns-sd`, macOS) every time and caches nothing. `home` with no arguments is `status`:
 
 ```
-hue      not set up · needs HUE_APPLICATION_KEY, HUE_CA_FILE  (local HTTPS, key from `home pair`)
+hue      not set up · needs HUE_APPLICATION_KEY  (local HTTPS, key from `home pair`)
 daikin   connected · off · cool 25 °C · room 24 °C · outdoor unit 19.5 °C  (local HTTP JSON (dsiot), no key)
 weather  connected · Sydney - Observatory Hill (1.1 km) 20:20: 16.6 °C, feels 16.7, 93%, 23.6 mm since 9am to 20:23 · today showers rain 80%, tomorrow 14–19 °C cloudy rain 30% (bom) · cloud 100%, UV 0, 0 W/m² (open-meteo) · sun -17°, setting, rises 06:15  (BOM anonymous FTP, Open-Meteo, Google with GOOGLE_WEATHER_KEY; sun computed)
 ```
 
-Startup is about 10 ms and 38 MB RSS for `home status` without a key; with Enphase, Amber and the Daikin live it takes 0.4–0.8 s, the devices read in parallel (Bun 1.4.2, Apple M5, measured 2026-10-13). The weather line adds 1.8–2.0 s, nearly all of it BOM's FTP (two files, one connection each). Cast takes about 0.3 s: `dns-sd` answers from the system's mDNS cache in 4–13 ms, the browse waits 200 ms of quiet for stragglers, each resolve ends on its TXT line, and seven sockets connect and answer in 50–80 ms (`home status` from a Cast-only config: 0.33–0.44 s, was 3.2 s with fixed 1.5 s windows; Bun 1.4.2, measured 2026-10-13). A configured entry discovery misses costs the second pass, 5 s more. `status` reads addresses from the environment only, except Cast, which has none to read; `discover` and `probe` do the other network searches. A full-screen TUI was considered (OpenTUI 0.6.2, 52 MB of native binaries) and skipped for now.
+Startup is about 10 ms and 38 MB RSS for `home status` without a key; with Enphase, Amber and the Daikin live it takes 0.4–0.8 s, the devices read in parallel (Bun 1.4.2, Apple M5, measured 2026-10-13). The weather line adds 1.8–2.0 s, nearly all of it BOM's FTP (two files, one connection each). Cast takes about 0.3 s: `dns-sd` answers from the system's mDNS cache in 4–13 ms, the browse waits 200 ms of quiet for stragglers, each resolve ends on its TXT line, and seven sockets connect and answer in 50–80 ms (`home status` from a Cast-only config: 0.33–0.44 s, was 3.2 s with fixed 1.5 s windows; Bun 1.4.2, measured 2026-10-13). A configured entry discovery misses costs the second pass, 5 s more. `status` reads addresses from the environment, except Cast, which has none to read, and the Daikin, found by UDP broadcast when `DAIKIN_HOST` is unset (1.5 s); `discover` and `probe` do the other network searches. A full-screen TUI was considered (OpenTUI 0.6.2, 52 MB of native binaries) and skipped for now.

package/docs/config.md

@@ -7,9 +7,13 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { createHome, loadHome, parseJsonc } from "@khalido/home";
+import { serveClip } from "@khalido/home/cast/serve";
+import { tlsConnect } from "@khalido/home/cast/tls";
+import { FINDERS, fileCache } from "@khalido/home/finders";
 import { ftpFetch } from "@khalido/home/weather/ftp";
 
 const path = "/path/to/home.jsonc";
+const cachePath = "/path/to/addresses.json";
 const readFile = (p: string) =>
   readFileSync(
     resolve(dirname(path), p.replace(/^~(?=\/)/, homedir())),
@@ -19,15 +23,19 @@ const home = createHome(
   loadHome(parseJsonc(readFileSync(path, "utf8")), {
     env: process.env,
     readFile,
-    ftpFetch: ftpFetch(),
+    ftpFetch: ftpFetch(), // BOM's weather
+    finders: FINDERS, // finds Cast devices, and any device that moves
+    castConnect: tlsConnect, // Cast's socket; a config with Cast is refused without it
+    castServe: serveClip, // only to announce a clip from bytes, not a URL
+    cache: fileCache(cachePath), // addresses kept between runs
   }),
 );
 ```
 
-`loadHome` runs on Bun and Node. Hue and Enphase need a fetch that handles their certificates: Bun's `tls` fetch option by default, and under Node `tls: NODE_TLS` from `@khalido/home/node`. Under Node, a config with Hue or Enphase and no `tls` is a problem `loadHome` names, not a silent failure at the first read.
+Only `env` is always needed: `readFile` for a config that names a file, `ftpFetch` for BOM, `finders` and `castConnect` for Cast. `loadHome` runs on Bun and Node. Hue and Enphase need a fetch that handles their certificates: Bun's `tls` fetch option by default, and under Node `tls: NODE_TLS` from `@khalido/home/node`. Under Node, a config with Hue or Enphase and no `tls` is a problem `loadHome` names, not a silent failure at the first read.
 
 - **A device entry is only how to reach it and where it is**: its identity (the Hue `bridgeId`, a Daikin's `mac`, the Enphase `serial`, a Cast `castId`), its last known `host`, a key's env name, a file's path, its `room`. What a device reports about itself (model, firmware) comes live; a note about it is a comment.
-- **Secrets are env variable names** (`"key": "AMBER_KEY"`), resolved against the `env` the caller passes; a pasted key fails the schema. Files (`ca`, `token`) are paths the caller reads, relative to the config or from `~/`, which the caller expands (`home discover --write` writes Enphase's token as `~/.config/home/enphase-token.json`); the library reads nothing.
+- **Secrets are env variable names** (`"key": "AMBER_KEY"`), resolved against the `env` the caller passes; a pasted key fails the schema. `env` is any record, not only `process.env`: a key the app keeps in its own store (a Hue key paired from a chat) goes in as `env: { ...process.env, HUE_APPLICATION_KEY: stored }`. Files (Enphase's `token`; a Hue `ca` only to replace Signify's roots, which the package carries) are paths the caller reads, relative to the config or from `~/`, which the caller expands (`home discover --write` writes Enphase's token as `~/.config/home/enphase-token.json`); the library reads nothing.
 - **Problems name the field**: an unknown connector, a missing env name or a device in a missing room is an error, never a skip. `checkHome` returns them all; `loadHome` throws them all. Unknown keys pass through for a consumer's own settings.
 - **One device per connector** for now (each integration is named by its connector), except printers (one entry each, by `uuid`) and Cast: one entry per device and speaker group (`name`, the Google Home name, and `castId`, the mDNS id), all read by one `cast` integration that finds every address by discovery, since a group's moves with its leader. A `spotify` entry is only its Soloist `url` (and `maxVolume`): a socket on the same machine, with nothing to discover.
 - **Identity, not address.** A device is recognised by the id its own discovery reports; `host` is a cache. `home discover` lists what answers (mDNS, Daikin's UDP broadcast), in two passes 5 s apart since both drop answers now and then: the first pass prints at once, the second only what it adds (`--passes 1` for a quick look; `--json` waits for both); with a config (`--config` or `HOME_CONFIG`) it then matches those against it by identity and prints new devices, moved addresses and conflicts (a different device at an entry's host). `home discover --write <file>` adds the new ones (each with an id no entry has), updates moved hosts and refreshes the `name` of a Cast entry renamed in the Google Home app through `jsonc-parser`'s edits, every comment and other line left as it was, and writes only a result that passes `checkPlan`. Nothing else writes the file; the library never does. Two devices with one id are a config problem.

package/docs/decisions.md

@@ -153,3 +153,15 @@ KO's decisions on this package, newest block last. They override every other doc
 - **`Part.reason`, only on `unavailable`** (KO, 2026-11-09). An admin page had to match `detail` text like "pair again" to know a person must re-key. `reason` is `auth` (a key or token rejected or unusable), `config` (a setting or file is wrong) or `crashed` (a `run` threw), for code to switch on; `detail` stays the text for people. `disconnected` gets none: it already says unreachable. Additive, so a patch. `config` came a day later (KO, 2026-11-10), so "re-key", "fix a setting" and "report a bug" are three answers; `crashed` stays though nothing reads it yet. Weather has one too: each source says why it stopped (`stopReason`), the part is `auth` if any stopped source is, else `config`, and `state.sources.<name>.reason` shows a dead key while another source keeps the part `connected`.
 - **Google's key goes in the `X-Goog-Api-Key` header, not the URL** (KO, 2026-11-10), so nothing that prints a URL can print it. Its rejection is read from the error body: a bad key and a bad latitude are both HTTP 400, and only the key's carries `API_KEY_INVALID` (live, 2026-11-10).
 - **Every device answers the same few questions** (KO, 2026-11-10: "nice and consistent so we can easily and consistently add devices"). `DeviceRecord` is identity, availability, one word of state and one line of text, the same for a light, a speaker and a printer; `homeDevices(snapshot, config?)` lists them all. Everything particular to a kind stays in the connector's own typed row, carried as `detail`, so the common record never grows a field only one kind has. Three levels, each inside the last: the house list, the connector's typed row, the raw snapshot. Each connector exports its own typed function, listed by hand in `src/devices.ts`, and not a manifest field: `MANIFESTS` is untyped, and `detail` must narrow by `connector`. The list is read-only: a write means something different for a light, a speaker and an air conditioner, so there is no generic `turnOn`. Not done, for a 0.2.0: Hue's `reachable` becoming `available`, and its groups joining its lights in one call.
+
+# 2026-11-11
+
+- **Signify's two root certificates ship in the package** (KO, 2026-11-11). Signify's own page tells apps to bundle both and validate against them, and openHAB, Homebridge's tools, openhue-go and Raycast do. `ca` stays as an override. No trust-on-first-use and no way to turn validation off: self-signed bridges were updated in May 2025, and Home Assistant's `ssl=False` is what this avoids. `docs/hue.md` has the detail.
+- **`pairWhenPressed` polls for 30 s; `pair` stays one request.** A consumer pairing from a chat wants "press the button" and then a key, not its own retry loop. 2 s between asks is this library's choice (openHAB uses 0.5 s, openhue-cli 1 s, Homebridge 15 s).
+- **Hue discovery stays mDNS only.** Signify's cloud endpoint (`discovery.meethue.com`) would also find a bridge, but nothing here calls a cloud to reach a local device.
+- **The Daikin's default setpoints live in the library: cool 25, heat 27** (KO, 2026-11-11: "I like having opinionated defaults"). `mode("cool")` always sets one, since the unit keeps a setpoint per mode and would otherwise give whatever the remote last left; `power(true)` is the way to get it "as it was". A caller that wants another number passes it.
+- **Daikin's `power` and `mode` resolve with `{ state, confirmed }`**, as spotify's writes do: the unit is read until it shows what was asked, so a bot can tell "done" from "sent".
+- **Hue's writes are by name, on the client, and read before they write** (KO, 2026-11-11, after chota asked for what the CLI had). `light`, `room` and `scene` resolve a name against a fresh read, check the change against that light's own gamut and kelvin range, send only what was asked, and resolve `{ state, confirmed }` as the Daikin's do. A read costs about 0.3 s (289 ms for 177 resources, Bun 1.4.4, 2026-11-11); it buys a miss that lists what exists and no table of bulb models. A colour off the gamut moves to the nearest the light can show, as Signify's page says to; a kelvin off the range throws, since there is no "nearest" a person would expect.
+- **Spotify playing on another device reads as `elsewhere`, not `playing`** (KO, 2026-11-11; chota raised it three times). Soloist reports the account's playback, not the box's, so `playing` while inactive is a silent speaker. `speakerState`, `spotifyText` and `spotifyChanges` all go through one test, `playingElsewhere`. Paused while inactive is left as Soloist says: nothing live shows whose pause it is. Soloist never names the other device, so where is a join with Cast by track name (`spotifyElsewhere`), passed to `spotifyText(state, on)` by `homeDevices`, which sees both parts; the speaker's own part can't know it, so `home status` says "another Spotify device".
+- **`home.add` replaces by name and starts the part over** (KO, 2026-11-11; chota pairs Hue from a chat). The old run ends before the new one starts, so a device never has two streams; the new part is a bare `connecting`, since the old state belonged to another key or address. No type widening: a `loadHome` home is already typed for every connector, so `add` takes the home's own integration type. `remove` fires no `onChange`: a change needs an `after`.
+- **Dry run is an option on each write, not a separate client** (KO, 2026-11-12; chota asked, since KO's rule is no device write without his OK at the time). It runs the read and every check a real write runs, so a wrong name or an unreachable light fails the same way, and returns the request instead of sending it, in the same `{ state, confirmed }` shape with `wouldSend` added. Hue and Daikin first, chota's lights and aircon tools; Cast and Spotify when a tool needs them.

package/docs/hue.md

@@ -0,0 +1,161 @@
+# Hue: certificates, discovery, write rates, rooms, colour and pairing
+
+What Signify asks of an app on the bridge's local API, what other projects do, and what this library does. Signify's developer pages need a free Hue developer login; KO read them on 2026-11-11 and the points below are from those, in our words. The connector's own file is [src/connectors/hue/README.md](../src/connectors/hue/README.md).
+
+## Links
+
+| Page                                                                                                                                          | For                                                              | Login |
+| --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ----- |
+| [Bridge release notes](https://www.philips-hue.com/en-au/support/release-notes/bridge)                                                        | what each bridge software version changed; check after an update | no    |
+| [Using HTTPS](https://developers.meethue.com/develop/application-design-guidance/using-https/)                                                | the two root certificates, CN check, self-signed bridges         | yes   |
+| [Hue Bridge Discovery](https://developers.meethue.com/develop/application-design-guidance/hue-bridge-discovery/)                              | mDNS, the cloud endpoint, validating a bridge                    | yes   |
+| [Hue System Performance](https://developers.meethue.com/develop/application-design-guidance/hue-system-performance/)                          | latency, how many commands a second                              | yes   |
+| [Color Conversion Formulas](https://developers.meethue.com/develop/application-design-guidance/color-conversion-formulas-rgb-to-xy-and-back/) | RGB to `xy` and back, the gamuts                                 | yes   |
+| [API v2: getting started](https://developers.meethue.com/develop/hue-api-v2/getting-started/)                                                 | pairing, the key header, resource URLs                           | yes   |
+| [API v2: core concepts](https://developers.meethue.com/develop/hue-api-v2/core-concepts/)                                                     | the resource model, the event stream                             | yes   |
+| [openhue-api](https://github.com/openhue/openhue-api)                                                                                         | an OpenAPI spec of CLIP v2 (Apache-2.0), no login                | no    |
+| [IANA: `hue` service](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?&search=hue)               | the registered mDNS service and its TXT keys                     | no    |
+
+## Certificates
+
+Signify's rules ([Using HTTPS](https://developers.meethue.com/develop/application-design-guidance/using-https/)):
+
+- The local API is HTTPS only, port 443. No fallback to HTTP: a fake bridge could ask for one and collect the key.
+- Signify has two private root certificates for bridges: one in use, and a second it may switch to. An app bundles both and validates the bridge's certificate against them.
+- The certificate's Common Name is the bridge id. Check it, since the certificate carries no address.
+- Today the root signs a bridge's certificate directly. Under the second root there will likely be an intermediate, which the bridge sends in the handshake, so the two roots are still all an app carries.
+- Self-signed certificates are gone: the few early bridges that had them were updated (the release notes put this at software 1971060010, 22 May 2025). A bridge that fails validation needs its firmware updated. Trust-on-first-use code can be removed.
+- Turning validation off is for development only.
+- Keep the connection alive between requests.
+
+| Root                               | Valid to   | SHA-256 of the DER                                                                                |
+| ---------------------------------- | ---------- | ------------------------------------------------------------------------------------------------- |
+| `CN=root-bridge, O=Philips Hue`    | 2038-01-19 | `F0:BD:8E:65:09:E8:2F:77:4D:63:BC:00:9D:53:88:C9:69:FE:3D:CF:7D:6D:54:1D:63:51:B7:2B:89:8D:8A:CF` |
+| `CN=Hue Root CA 01, O=Signify Hue` | 2050-12-31 | `D8:B8:94:48:B2:AF:8E:16:76:18:5A:C0:72:19:EE:9D:CB:C8:F0:1C:12:2A:02:6A:2A:4B:7B:5C:FE:03:28:B8` |
+
+**What this library does.** Both roots are in the package as `HUE_BRIDGE_ROOT_CA` (`src/connectors/hue/ca.ts`), byte for byte the bundle on Signify's page (compared 2026-11-11), and a test holds the two fingerprints. `bunPinnedFetch(bridgeId)` and `nodePinnedFetch(bridgeId)` trust those two and nothing else, and accept only a certificate whose CN is the bridge id. A caller can still pass its own `ca`. There is no trust-on-first-use and no way to turn validation off.
+
+**Live, 2026-11-11, KO's BSB002 on software 1978545030 (Bun 1.4.4), reads of `/api/0/config` only:**
+
+- Its certificate is `CN=<bridge id>`, issued 9 April 2025 by `root-bridge`, with no intermediate.
+- The bundle: accepted. The two roots in the other order: accepted, so Bun reads both from one PEM string. The second root alone: refused ("unable to verify the first certificate"). Another bridge id: refused by the CN check.
+
+**Untried:** a Bridge Pro (BSB003). Others report it chains to the second root through an intermediate (hb-hue-tools, openHAB #20400); nothing here has met one. Node's fetch against a real bridge.
+
+**What others do** (their sources read 2026-11-11):
+
+| Project                   | Approach                                                                                        |
+| ------------------------- | ----------------------------------------------------------------------------------------------- |
+| Home Assistant (aiohue)   | validation off (`ssl=False`)                                                                    |
+| node-hue-api, openhue-cli | validation off; node-hue-api compares the CN to the bridge id it read over that same connection |
+| openHAB hue binding       | both roots bundled; an option trusts the bridge's own certificate instead                       |
+| hb-hue-tools (Homebridge) | both roots bundled, CN and serial checked against the bridge id                                 |
+| openhue-go                | both roots bundled, chain checked, no CN check                                                  |
+| Raycast's Hue extension   | both roots bundled, CN checked; self-signed support dropped June 2025                           |
+| Hue-Sync                  | the first root as a file; the user points `NODE_EXTRA_CA_CERTS` at it                           |
+
+Everyone who bundles carries the same bytes and cites Signify's page. Signify's page tells apps to bundle them; no licence text for the certificates was found.
+
+## Discovery
+
+Signify's rules ([Hue Bridge Discovery](https://developers.meethue.com/develop/application-design-guidance/hue-bridge-discovery/)):
+
+- Discover only at first install, or when the stored address stops answering. Store the address; check it at each start.
+- **mDNS** first: service `_hue._tcp`, with `bridgeid` and `modelid` in the TXT record. SSDP is gone.
+- **The cloud endpoint**, `https://discovery.meethue.com`: the bridges seen from this network's public address, each with its id and LAN address. At most one request per 15 minutes per client. Empty if the bridge has never been online.
+- **A typed address** as the fallback.
+- Validate what was found with `GET https://<address>/api/0/config`, which needs no key: name, `bridgeid`, `modelid`, software version.
+- Several bridges: list them by id for the person to pick, or start pairing on all and let the button press pick.
+
+**What this library does.** mDNS only (`FINDERS.hue`), matched by bridge id. The address lives in the config or the caller's address cache; `hue()` searches again only after three failed reconnects, and follows the bridge to a new address. `home probe` is the `/api/0/config` check. A typed address is `host` in the config or `HUE_BRIDGE_HOST`.
+
+**Not done:**
+
+- The cloud endpoint. It would find a bridge where mDNS is blocked, at the cost of one request to Signify; nothing here calls a cloud to reach a local device. Worth adding to `home discover` only if mDNS fails someone.
+- More than one bridge: the CLI takes the first mDNS answer. A config can list several by `bridgeId`.
+
+## Write rates
+
+Signify's rules ([Hue System Performance](https://developers.meethue.com/develop/application-design-guidance/hue-system-performance/)):
+
+- **About 10 commands a second to lights, 100 ms apart; at most 1 a second to groups.** Send fewer where you can: the Zigbee network is shared with switches and the bridge's own housekeeping.
+- The bridge turns each command into one Zigbee message per thing changed, and the network carries about 25 a second. Brightness alone is one message, brightness and colour two, those plus on/off three. So send only what changes: no `on` to a light already on.
+- Latency to one light, wired, one hop: about 55 ms for one message, 95 ms for two, 125 ms for three.
+- A group command is a Zigbee broadcast, limited to about one a second, and broadcasts slow single-light commands too.
+- Past the limit the bridge buffers without saying so and latency grows to seconds; when the buffer fills it drops the command and answers an error (type 901, "Internal error, 503").
+- Other apps share the same budget. A light several hops away is slower.
+- Fast updates to many lights for more than a few seconds belong on the Entertainment streaming API, not this one.
+
+**What this library does.** Two write lanes per client (`WRITE_GAP_MS` in `client.ts`): `light` writes 100 ms apart, `grouped_light` and `scene` writes 1 s apart, both Signify's figures. A write to a resource whose last write is still waiting merges into it, so a burst cannot build a backlog. Prefer one `grouped_light` or scene write over many light writes.
+
+**Not done:** a 503 (error 901) is reported as a failed write, not retried or slowed for. Whether a merged write carries a field the light already has (an `on` to a light that is on) is the caller's to avoid. No Entertainment API.
+
+**Transition time.** A change fades over 400 ms unless the write says otherwise, and the setting does not stick: each write that wants another time must carry it (v2: `dynamics.duration`, in ms). Right for everyday use; an app that wants a light to respond at once sends 0. Latency above is measured with 0. `transitionMs` on a light or room change sets it; without one a write takes the bridge's 400 ms.
+
+## Rooms, zones and scenes
+
+People group their lights into rooms in the Hue app, so a home app should use those rooms and not make its own. Signify's [groups and scenes guide](https://developers.meethue.com/develop/application-design-guidance/hue-groups-rooms-and-scene-control/) is written for API v1; the points that carry over to v2:
+
+- **A write to a group changes its lights together**, with no popcorn effect, and costs one broadcast (the one-a-second limit above).
+- **A light is in at most one room.** Zones (v2) are the free groupings; a light can be in several. The whole-home group is made by the bridge.
+- **Each light does what it can:** a dimmable light ignores a colour sent to its group.
+- **A light that is off takes no brightness or colour change.** Turn it on in the same write.
+- **Colour has one mode at a time.** If a write carries more than one, `xy` wins over colour temperature.
+- **A scene belongs to a room or zone and stores each light's state.** Recalling it changes only the lights that are in both.
+
+In v2 a room or zone is a `room` or `zone` resource whose `grouped_light` service takes the writes, and the whole home is `bridge_home`.
+
+**What this library does.** Reads rooms, zones (`groups(state)`, each with its lights and its grouped light's on/off and brightness), the whole-home group (`homeGroupedLightId`) and scenes (`scenes(state)`). The config's `hueRoom` ties a Hue room to a room on the plan, and `homeDevices` gives each light its room. Writes: `home lights off`, `home room <name> [on|off] [<1-100>] [<kelvin>k] [<hex colour>]`, `home scene <name>`, each one group write; from code, the typed writes below, or `client.put("grouped_light", id, body)` and `client.recallScene(id)` for anything else.
+
+Typed writes by name: `client.light(name, change)`, `client.room(name, change)`, `client.scene(name, room?)`, each resolving `{ state, confirmed }` (the connector README has the rules).
+
+**Not done:** creating or editing rooms and scenes, which stays in the Hue app. The typed writes ran on KO's bridge on 2026-11-11: every one confirmed in about a second, a fade included (the connector README has the run).
+
+## Colour
+
+Signify's rules ([Color Conversion Formulas](https://developers.meethue.com/develop/application-design-guidance/color-conversion-formulas-rgb-to-xy-and-back/)):
+
+- A light's colour is an `xy` point in the CIE colour space, so one `xy` is the same colour on every light that can show it. Brightness is separate.
+- Each light can show the colours inside a triangle, its gamut. Three are named: C for newer lights (red 0.6915, 0.3038; green 0.17, 0.7; blue 0.1532, 0.0475), B for the older bulb, A for the legacy LivingColors lamps and strips. **API v2 gives each light's gamut on its `light` resource**, so nothing needs a table of models.
+- RGB to `xy`: scale to 0–1, undo the sRGB gamma, convert to XYZ with the D65 matrix, then `x = X / (X + Y + Z)` and `y = Y / (X + Y + Z)`; `Y` is the brightness. If the point is outside the light's gamut, move it to the nearest point on the triangle.
+- `xy` to RGB, for showing a light's colour on a screen, is the same in reverse, with the brightness as `Y`.
+- A colour given as hue, saturation and value goes to RGB first.
+- White is a colour temperature in mirek (`color_temperature.mirek`, 153 cool to 500 warm on most lights), not an `xy`.
+
+**What this library does.** `light(name, { color })` and `room(name, { color })` take a hex string or `{ r, g, b }` and send its `xy`, moved inside the light's own gamut; `kelvin` is a white temperature checked against the light's own range, never rounded into it. The state has each light's `kelvin`, `kelvinRange`, `xy`, `gamut` and a `hex` for a screen. Brightness stays separate: a dark red and a bright red are one colour. KO's bridge does report it (2026-11-11): each light's `color.xy`, its `gamut` and `gamut_type`, and `color_temperature.mirek` with the light's own `mirek_minimum` and `mirek_maximum`. The conversions are public maths; Signify's page also carries an iOS SDK extract "as is", which is read for the method and not copied.
+
+## Pairing
+
+`POST https://<address>/api` with `{ devicetype, generateclientkey: true }`. Until the link button is pressed the bridge answers error 101; for about 30 s after, it answers with the application key. The key keeps working until it is deleted on the bridge. `devicetype` is `app#instance`, at most 40 characters.
+
+**What this library does.**
+
+- `pair({ host, fetch, deviceType })`: one request. Throws `HueError` with `code: "link_button"` until the button is pressed.
+- `pairWhenPressed({ …, timeoutMs?, everyMs?, onWaiting?, signal? })`: asks every 2 s for 30 s and returns `{ key }`. `onWaiting()` takes nothing and is called once, when the bridge first says the button isn't pressed; if it was already pressed, it is never called. After the time it throws the `link_button` error: nothing was changed on the bridge, so tell the person and ask again.
+- `home pair` uses it with 60 s, names the bridge it found, counts down on a terminal, and prints the env lines. With no press it says so and exits 1.
+- The library never stores the key.
+
+A consumer pairing from a chat:
+
+```ts
+import { FINDERS } from "@khalido/home/finders";
+import { bunPinnedFetch, pairWhenPressed } from "@khalido/home/hue";
+
+const [bridge] = await FINDERS.hue(); // mDNS: needs avahi-utils on Linux, else throws MissingTool
+if (!bridge) throw new Error("no Hue bridge answered");
+const { key } = await pairWhenPressed({
+  host: bridge.host,
+  fetch: bunPinnedFetch(bridge.id),
+  deviceType: "chota#pi",
+  onWaiting: () => say("Press the button on the Hue bridge."),
+});
+// store `key` as a secret; then hue({ host: bridge.host, bridgeId: bridge.id, key })
+```
+
+`FINDERS.hue()` returns every bridge that answers; this takes the first. A home with two should list them by id and let the person choose. To use the key from a home config, pass it in `env` under the name the config gives (`env: { ...process.env, HUE_APPLICATION_KEY: key }`), and `home.add` the Hue integration that builds ([using.md](using.md) has the three lines).
+
+That is Bun. Under Node, `nodePinnedFetch(bridge.id)` from `@khalido/home/node` takes the place of `bunPinnedFetch`.
+
+**What others do:** Home Assistant asks the person to press, then makes one request per click of Submit. openHAB asks every 0.5 s for 5 minutes, Homebridge every 15 s with no limit, openhue-cli every second with no limit. Home Assistant and openHAB leave out `generateclientkey`.
+
+**Live, 2026-11-11, KO's BSB002 (Bun 1.4.4):** `home pair` gave the `link_button` error after its wait with no press, and a key on the next run once the button was pressed. The key then read the bridge: 177 resources in 286 ms, all parsed (the connector README has the rest).