@khalido/home 0.1.3 → 0.2.0

package/src/connectors/hue/schemas.ts

@@ -6,6 +6,7 @@ import { z } from "zod";
 // all are optional and unknown fields pass through, so a schema change degrades, never throws.
 
 const ref = z.object({ rid: z.string(), rtype: z.string() });
+const xy = z.looseObject({ x: z.number(), y: z.number() });
 
 /** The resource kinds this library reads. */
 export const KINDS = [
@@ -27,6 +28,31 @@ export const Resource = z.looseObject({
   metadata: z.looseObject({ name: z.string().optional() }).optional(),
   on: z.looseObject({ on: z.boolean() }).optional(),
   dimming: z.looseObject({ brightness: z.number() }).optional(),
+  // A light's colour and the triangle of colours it can show; absent on a white light. A shape this doesn't expect
+  // reads as absent, so one odd light never fails the whole read.
+  color: z
+    .looseObject({
+      xy: xy.optional().catch(undefined),
+      gamut: z
+        .looseObject({ red: xy, green: xy, blue: xy })
+        .optional()
+        .catch(undefined),
+    })
+    .optional()
+    .catch(undefined),
+  // mirek is null while the light shows a colour; the schema is this light's own range.
+  color_temperature: z
+    .looseObject({
+      mirek: z.number().nullable().optional(),
+      mirek_schema: z
+        .looseObject({
+          mirek_minimum: z.number().optional(),
+          mirek_maximum: z.number().optional(),
+        })
+        .optional(),
+    })
+    .optional()
+    .catch(undefined),
   children: z.array(ref).optional(),
   services: z.array(ref).optional(),
   group: ref.optional(), // scene: the room or zone it belongs to

package/src/connectors/hue/state.ts

@@ -1,3 +1,4 @@
+import { type Gamut, mirekToKelvin, type XY, xyToHex } from "./color.ts";
 import type { HueEvent, Resource } from "./schemas.ts";
 
 /** Every resource on the bridge by id, from the last full read plus every event since. `asOf` is local time it was last known fresh. */
@@ -56,9 +57,17 @@ export type LightView = {
   on?: boolean;
   brightness?: number;
   reachable?: boolean;
+  /** White temperature in kelvin, while the light shows a white; its range is `kelvinRange` (warmest, coolest). */
+  kelvin?: number;
+  kelvinRange?: [number, number];
+  /** The colour it shows: the bridge's `xy`, and `hex` for a screen (the hue at full brightness). Colour lights only. */
+  xy?: XY;
+  hex?: string;
+  /** The colours it can show. Present on a colour light, so its presence says "takes a colour". */
+  gamut?: Gamut;
 };
 
-/** Every light, with on, brightness and reachability. */
+/** Every light, with on, brightness, reachability, and its white temperature and colour where it has them. */
 export function lights(s: HueSnapshot): LightView[] {
   const zigbee = ofType(s, "zigbee_connectivity");
   return ofType(s, "light").map((l) => {
@@ -69,10 +78,27 @@ export function lights(s: HueSnapshot): LightView[] {
       on: l.on?.on,
       brightness: l.dimming?.brightness,
       reachable: link ? link.status === "connected" : undefined,
+      ...colorOf(l),
     };
   });
 }
 
+/** A light's temperature and colour fields, only those the bridge reported. */
+function colorOf(l: Resource): Partial<LightView> {
+  const out: Partial<LightView> = {};
+  const ct = l.color_temperature;
+  if (typeof ct?.mirek === "number") out.kelvin = mirekToKelvin(ct.mirek);
+  const { mirek_minimum: min, mirek_maximum: max } = ct?.mirek_schema ?? {};
+  if (min !== undefined && max !== undefined)
+    out.kelvinRange = [mirekToKelvin(max), mirekToKelvin(min)];
+  if (l.color?.xy) {
+    out.xy = l.color.xy;
+    out.hex = xyToHex(l.color.xy);
+  }
+  if (l.color?.gamut) out.gamut = l.color.gamut;
+  return out;
+}
+
 /** A room or zone as a row shows it, with its grouped light's state. */
 export type GroupView = {
   id: string;

package/src/connectors/spotify/README.md

@@ -35,7 +35,7 @@ Soloist is Spotify's own headless Spotify Connect client (Linux arm64, armv7, x8
 
 The restore runs even if `fn` throws: the error is `fn`'s, and a failed restore goes to `detail`. `duck` restores the earlier volume even above `maxVolume`. One aside at a time: never call one inside another's `fn` (it waits forever), and put two announcements in one `fn`. With Cast: `speaker.duck(() => cast.announce("Kitchen", clip), { to: 20 })`. Cast's own `announce` restores what a Cast device was playing; these are for Soloist's output.
 
-**Reading it.** `speakerState` takes the Part; `spotifyText` and `positionMs` take its `state`. `speakerState(part)`: `offline`, `connecting`, `waiting`, then Soloist's status (`idle`, `playing`, `paused`, `buffering`, or its own string); signed in with no status yet is `idle`. `spotifyChanges(before, after)`, for `onChange`, gives events in this order: `offline`, `online`, `waiting`, `picked`, `started` (from idle), `resumed` (from paused), `paused`, `stopped`, `track`, `stalled`, `recovered`. Buffering counts as playing. Nothing on the first report, so a restart announces nothing; no volume or queue events. Playback events during an aside carry `own: true`; connection, sign-in and stall events never do. `track` waits for the track's name, which Soloist can send a few seconds after the track (seen live); one that never gets a name never fires. One press on a phone can fire track, resumed, stopped, started and track over 3 s, sometimes with a 0.8 s `waiting`, and the order varies: anything announcing these should wait a few seconds. `state.volume` isn't the level that will play until `active` (it reads `--initial-volume`).
+**Reading it.** `speakerState` takes the Part; `spotifyText` and `positionMs` take its `state`. `speakerState(part)`: `offline`, `connecting`, `waiting`, `elsewhere` (Soloist says playing but isn't the active device: the music is on another Spotify device and this one is silent; `playingElsewhere(state)` is the test), then Soloist's status (`idle`, `playing`, `paused`, `buffering`, or its own string); signed in with no status yet is `idle`. `spotifyChanges(before, after)`, for `onChange`, gives events in this order: `offline`, `online`, `waiting`, `picked`, `started` (from idle), `resumed` (from paused), `paused`, `stopped`, `track`, `stalled`, `recovered`. Buffering counts as playing. Music elsewhere is silence here: leaving is `stopped`, arriving is `started` then `track`, and its tracks, pauses and stops meanwhile fire nothing (a resume there after a pause there fires one `stopped`: paused while inactive reads as Soloist says, so the resume looks like music leaving). Soloist doesn't say where it is; `spotifyElsewhere(snapshot)` from `@khalido/home` names the Cast devices playing that track in Spotify, and `homeDevices` puts them in the speaker's line (matched by name, built snapshots only, untried live), and is empty for a phone. Nothing on the first report, so a restart announces nothing; no volume or queue events. Playback events during an aside carry `own: true`; connection, sign-in and stall events never do. `track` waits for the track's name, which Soloist can send a few seconds after the track (seen live); one that never gets a name never fires. One press on a phone can fire track, resumed, stopped, started and track over 3 s, sometimes with a 0.8 s `waiting`, and the order varies: anything announcing these should wait a few seconds. `state.volume` isn't the level that will play until `active` (it reads `--initial-volume`).
 
 **Stalls** ([#5](https://github.com/spotify/soloist/issues/5): playback stops mid-track, often the first after idle, while Soloist still says `playing`). While playing, one `get_state` every 20 s (`stallCheckMs`, code only; 0 turns it off).
 
@@ -68,12 +68,18 @@ Writes through this connector, and what a live read hasn't shown. In particular:
 
 ## Live findings
 
+**2026-11-11, Raspberry Pi 5, Bun 1.4.4, on 0.1.3** (chota-bot's session; `maxVolume: 40` watching, writes from the CLI in another process). Two gaps in the cap, not fixed:
+
+- From inactive and paused at 60, `play`: lowered to 40 within 2 ms of going active, `playing` at 40, then 60 again 90 ms after `playing`, and it played at 60. The cap takes its first confirmed lowering as done, so nothing lowered it again, and `anomaly` still said "lowered it". Soloist puts its own level back after `playing`.
+- The connector started while the speaker was already active and paused at 60: `play` resumed at 60, nothing lowered it, no anomaly. This is the documented "not on resuming from pause while active".
+- A volume set by hand (35) held through pause and play, so the put-back belongs to activation, not to pause.
+
 **2026-11-10, Raspberry Pi 5, Bun 1.4.4, on 0.1.2, through this connector** (chota-bot's session, KO listening).
 
 - Confirmed with `maxVolume: 60`, the speaker active and playing: `activate`, `setVolume(50)`, `setVolume(90)` (came back 60), `seek`, `setShuffle`, `setRepeat("context")` and `("off")` (about 2.1 s each), `queue` (first in `upNext`), `play` of a playlist URI. `duck(fn, { to: 20 })` around a Cast announce: 20 inside, `music: "restored"`, 60 after, 5.2 s in all.
 - **The level can jump above the cap on a pause, not only on a start.** One-shot CLI, cap 60: `volume 45` read 45, `play` 45, then `pause` read 62 and the next `play` 62 (62 was the level before the test). Nothing lowered it: a pause is not a start signal, and each CLI command is a new process.
 - **That jump did not repeat, and it is not WirePlumber.** A second pass the same day, the speaker already active: 60, `volume 45`, `pause`, `play`, `volume 60`. Soloist's number and the stream's live level (`wpctl get-volume`) matched at every step (0.60, 0.45, 0.45, 0.45, 0.60), WirePlumber 0.5.8 never wrote a saved entry for the stream in `stream-properties`, and the stream kept its id across pause and play. The run that jumped had just been made active with `activate`, minutes after the account was casting from a phone, which points at the account side. One case each way.
-- **`active: false` with `status: "playing"`:** the account playing on another speaker. `speakerState` says `playing`, `spotifyText` prints it as this speaker's, and `spotifyChanges` fired `resumed`, with the box silent.
+- **`active: false` with `status: "playing"`:** the account playing on another speaker. `speakerState` said `playing`, `spotifyText` printed it as this speaker's, and `spotifyChanges` fired `resumed`, with the box silent. Since 2026-11-11 all three read it as `elsewhere`, and the stall watch skips it; not yet seen live.
 - Through chota-bot's wrapper, later the same day: `play` of a playlist confirmed in 241 ms, `next` in 134 ms, `pause` in 17 ms; `duck` to 15 and `interrupt`, 2.5 s each, both `restored`. `play()` with the music paused on a Cast speaker: confirmed in 1.3 s, playing on the box at the same position.
 - **`interrupt` paused music that was on another speaker** (found in chota's switch): it checked `playing` and not `active`. Fixed after 0.1.2.
 - `positionMs` around a duck and an interrupt read 2 s, 2 s, 3 s, 5 s, then 4 s after a pause: it can step back a second.

package/src/connectors/spotify/changes.ts

@@ -14,11 +14,24 @@ export function stallText(s: Stall | undefined): string | undefined {
   return s.tried ? `${what}; tried ${s.tried}` : what;
 }
 
-/** The speaker in one word, to switch on. `offline`: not reached (or no part); `waiting`: running, nobody has picked it. A status Soloist sends beyond its four passes through. */
+const PLAYING = new Set(["playing", "buffering"]);
+
+/**
+ * Soloist says playing while it is not the account's active device: the music is on another Spotify device (a phone,
+ * another speaker) and this one is silent (live, 2026-11-10). Soloist doesn't say which. Unknown `active` is not elsewhere.
+ */
+export const playingElsewhere = (s: SpotifyState | undefined): boolean =>
+  s?.active === false && PLAYING.has(s.status ?? "");
+
+/**
+ * The speaker in one word, to switch on. `offline`: not reached (or no part); `waiting`: running, nobody has picked it;
+ * `elsewhere`: the account's music is playing on another Spotify device, not this one. A status Soloist sends beyond its four passes through.
+ */
 export type SpeakerState =
   | "offline"
   | "connecting"
   | "waiting"
+  | "elsewhere"
   | "idle"
   | "playing"
   | "paused"
@@ -32,6 +45,7 @@ export function speakerState(
     return "offline";
   if (part.status === "connecting") return "connecting";
   if (part.state?.loggedIn === false) return "waiting";
+  if (playingElsewhere(part.state)) return "elsewhere";
   return part.state?.status ?? "idle"; // signed in, nothing reported yet: nothing is playing
 }
 
@@ -57,12 +71,12 @@ export type SpotifyEvent = { own?: true } & (
   | { type: "track"; track: Track }
 );
 
-const PLAYING = new Set(["playing", "buffering"]);
-
 /**
  * The events between two reports, for `onChange`'s `before` and `after`: `offline` and `online`; `waiting` (signed out) and
  * `picked` (someone picked the speaker); `started` (from idle), `resumed` (from paused), `paused`, `stopped` (to idle), then
- * `track` for a new track, once it has a name, then `stalled` and `recovered` (Soloist issue #5). Buffering counts as playing. No `before`, or one
+ * `track` for a new track, once it has a name, then `stalled` and `recovered` (Soloist issue #5). Buffering counts as playing.
+ * Music on another Spotify device (`playingElsewhere`) is not playing here: it moving away is `stopped`, it arriving is `started`
+ * then `track`, and nothing fires for its tracks meanwhile. No `before`, or one
  * with no state (createHome's placeholder before the first report, as at a restart): nothing, since nothing was seen to change. No volume or queue events: read the state.
  */
 export function spotifyChanges(
@@ -87,8 +101,11 @@ export function spotifyChanges(
     events.push({ type: "waiting" });
   if (b?.loggedIn === false && a?.loggedIn === true)
     events.push({ type: "picked" });
-  const from = b?.status;
-  const to = a?.status;
+  // What this speaker itself is doing: music on another device is silence here.
+  const here = (s?: SpotifyState) => (playingElsewhere(s) ? "idle" : s?.status);
+  const from = here(b);
+  // Still inactive after playing elsewhere: a pause or stop there is the other device's, not this one's.
+  const to = playingElsewhere(b) && a?.active === false ? "idle" : here(a);
   const playingNow = to !== undefined && PLAYING.has(to);
   const playingThen = from !== undefined && PLAYING.has(from);
   if (playingNow && !playingThen)
@@ -98,7 +115,13 @@ export function spotifyChanges(
     add({ type: "stopped" });
   // Soloist's first report of a new track can have no name yet (seen live): the event waits for it.
   const named = (p?: SpotifyState) => !!p?.track?.name;
-  if (a?.track && named(a) && (a.track.uri !== b?.track?.uri || !named(b)))
+  const heard = playingElsewhere(b) && playingNow ? undefined : b; // a track that was on another device is new here once it plays here
+  if (
+    a?.track &&
+    named(a) &&
+    !playingElsewhere(a) &&
+    (a.track.uri !== heard?.track?.uri || !named(heard))
+  )
     add({ type: "track", track: a.track });
   if (a?.stalled && !b?.stalled)
     events.push({ type: "stalled", stall: a.stalled });
@@ -112,14 +135,20 @@ export function spotifyChanges(
   return events;
 }
 
-/** The speaker in a few words: `Kitchen speaker: playing "Song" by Band · 35%`, or `…: waiting for someone to pick it`. */
-export function spotifyText(s: SpotifyState): string {
+/**
+ * The speaker in a few words: `Kitchen speaker: playing "Song" by Band · 35%`, `…: waiting for someone to pick it`, or,
+ * for music on another Spotify device, `…: silent · "Song" by Band is playing on another Spotify device` (no volume: it isn't this speaker's playing level).
+ * `on` names where, when the caller knows (`spotifyElsewhere`): `… is playing on Front room speaker`.
+ */
+export function spotifyText(s: SpotifyState, on: string[] = []): string {
   const who = s.deviceName ?? "Soloist";
   if (s.loggedIn === false) return `${who}: waiting for someone to pick it`;
   const t = s.track;
   const what = t
     ? `${t.name ? ` "${t.name}"` : ` ${t.uri}`}${t.artists.length ? ` by ${t.artists.join(", ")}` : ""}`
     : "";
+  if (playingElsewhere(s))
+    return `${who}: silent ·${what || " music"} is playing on ${on.length ? on.join(", ") : "another Spotify device"}`;
   const parts = [
     `${s.status ?? "status unknown"}${what}`,
     s.volume === undefined ? "" : `${s.volume}%`,

package/src/connectors/spotify/index.ts

@@ -43,6 +43,7 @@ export {
 } from "./client.ts";
 export {
   type SpeakerState,
+  playingElsewhere,
   speakerState,
   type SpotifyEvent,
   spotifyChanges,
@@ -836,6 +837,7 @@ export function spotify(
       !st ||
       state.aside === "repair" ||
       (state.track?.uri === st.track &&
+        state.active !== false && // moved to another device: no longer this speaker's stall
         (state.status === "playing" || state.status === "buffering"))
     )
       return;
@@ -870,7 +872,12 @@ export function spotify(
     a.track === b.track &&
     b.atMs - a.atMs >= gap &&
     Math.abs(b.ms - a.ms) < 1000;
-  const playing = () => isOpen() && state.status === "playing" && !state.aside;
+  // Not while inactive: "playing" then is another device's music, and a repair's seek or pause would land on it.
+  const playing = () =>
+    isOpen() &&
+    state.status === "playing" &&
+    state.active !== false &&
+    !state.aside;
 
   /** One look while playing: a fresh position, then frozen, overrun, recovered or fine (Soloist issue #5). */
   const checkStall = async () => {
@@ -916,6 +923,7 @@ export function spotify(
     const ours = () =>
       isOpen() &&
       state.status === "playing" &&
+      state.active !== false &&
       state.track?.uri === track &&
       state.stalled?.track === track &&
       (!state.aside || state.aside === "repair");

package/src/devices.ts

@@ -1,5 +1,6 @@
 import {
   type CastHomeDevice,
+  type CastSnapshot,
   castHomeDevices,
 } from "./connectors/cast/index.ts";
 import {
@@ -16,8 +17,11 @@ import {
   printersHomeDevices,
 } from "./connectors/printers/index.ts";
 import {
+  playingElsewhere,
   type SpotifyHomeDevice,
+  type SpotifyState,
   spotifyHomeDevices,
+  spotifyText,
 } from "./connectors/spotify/index.ts";
 import type { HomeConfig } from "./config.ts";
 import { IDENTITY, sameId } from "./discover.ts";
@@ -59,9 +63,17 @@ export function homeDevices(
   snapshot: Record<string, Part | undefined>,
   config?: Pick<HomeConfig, "devices" | "rooms">,
 ): HomeDevice[] {
-  const all = Object.entries(DEVICES).flatMap(([name, devices]): HomeDevice[] =>
-    devices(snapshot[name] as never),
-  );
+  // Soloist doesn't say where its music went; a Cast device playing that track does, so the speaker's line names it.
+  const on = spotifyElsewhere(snapshot);
+  const all = Object.entries(DEVICES)
+    .flatMap(([name, devices]): HomeDevice[] =>
+      devices(snapshot[name] as never),
+    )
+    .map((d) =>
+      d.connector === "spotify" && on.length
+        ? { ...d, text: spotifyText(d.detail, on) }
+        : d,
+    );
   if (!config) return all;
   const entries = config.devices ?? [];
   const hueRooms = new Map<string, string>(); // a Hue group's or light's id → the config room showing it
@@ -100,3 +112,71 @@ export function homeDevices(
     return { ...d, name, text, ...(room ? { room } : {}) };
   });
 }
+
+/**
+ * Where the account's Spotify is playing when the Soloist speaker says it is on another device: the names of the Cast
+ * devices and groups playing a track of that name in Spotify. A group is named, not its members. Empty when the music is
+ * on the speaker itself, nothing is playing, or it is on something Cast can't see (a phone, a laptop). Matched by the
+ * track's name, since neither side names the other.
+ */
+export function spotifyElsewhere(
+  snapshot: Record<string, Part | undefined>,
+): string[] {
+  const s = snapshot.spotify?.state as SpotifyState | undefined;
+  const cast = snapshot.cast?.state as CastSnapshot | undefined;
+  const name = s?.track?.name;
+  if (!playingElsewhere(s) || !name || !cast) return [];
+  return Object.values(cast.devices)
+    .filter(
+      (d) =>
+        d.status === "connected" &&
+        !d.playingVia && // its group's music: the group is named
+        d.app === "Spotify" &&
+        d.title === name &&
+        (d.playerState === "PLAYING" || d.playerState === "BUFFERING"),
+    )
+    .map((d) => d.name);
+}
+
+/** A room of the home config with the devices placed in it. `noData`: device connectors the config places here that listed nothing in it (never reached, not set up, or a `hueRoom` the bridge doesn't have), so the room isn't empty, it is unread. Per connector, not per device. */
+export type RoomDevices = {
+  id: string;
+  name: string;
+  floor?: string;
+  devices: HomeDevice[];
+  noData: string[];
+};
+
+/**
+ * `homeDevices` room by room, in the config's order, for a map of the home. A connector that is down but has read before
+ * still lists its devices, `available: false`; `noData` names one the config places in the room (a device's `room`, or
+ * `hueRoom`) that has nothing to list. `unplaced`: devices with no room, or one the config doesn't have.
+ */
+export function byRoom(
+  snapshot: Record<string, Part | undefined>,
+  config: Pick<HomeConfig, "devices" | "rooms">,
+): { rooms: RoomDevices[]; unplaced: HomeDevice[] } {
+  const all = homeDevices(snapshot, config);
+  const ids = new Set((config.rooms ?? []).map((r) => r.id));
+  return {
+    rooms: (config.rooms ?? []).map((r) => {
+      const devices = all.filter((d) => d.room === r.id);
+      const expected = new Set([
+        ...(config.devices ?? [])
+          .filter((d) => d.room === r.id)
+          .map((d) => d.connector),
+        ...(r.hueRoom === undefined ? [] : ["hue"]),
+      ]);
+      return {
+        id: r.id,
+        name: r.name,
+        ...(r.floor === undefined ? {} : { floor: r.floor }),
+        devices,
+        noData: [...expected].filter(
+          (c) => c in DEVICES && !devices.some((d) => d.connector === c),
+        ),
+      };
+    }),
+    unplaced: all.filter((d) => !d.room || !ids.has(d.room)),
+  };
+}

package/src/discover.ts

@@ -134,8 +134,7 @@ function newEntry(f: Found): Record<string, string | number> {
     host: f.host,
     [IDENTITY[f.connector]]: f.id,
   };
-  if (f.connector === "hue")
-    return { ...base, key: "HUE_APPLICATION_KEY", ca: "hue-root-ca.pem" };
+  if (f.connector === "hue") return { ...base, key: "HUE_APPLICATION_KEY" };
   if (f.connector === "enphase")
     return { ...base, token: "~/.config/home/enphase-token.json" };
   return base;

package/src/finders-entry.ts

@@ -1,2 +1,2 @@
 // `@khalido/home/finders`: what a Node consumer passes to `loadHome`. The rest of finders.ts is the CLI's.
-export { FINDERS, fileCache } from "./finders.ts";
+export { FINDERS, fileCache, MissingTool } from "./finders.ts";

package/src/finders.ts

@@ -32,6 +32,7 @@ import {
 // `fileCache` keeps the addresses discovery found in a file between runs, so the next run connects straight away.
 
 /** The system's mDNS tool is not installed: discovery can't run until it is. */
+/** The discovery tool isn't installed (`dns-sd` on macOS, `avahi-browse` from avahi-utils on Linux): the message names it. */
 export class MissingTool extends Error {}
 
 /**
@@ -153,21 +154,32 @@ function decoded(v: string): string {
   }
 }
 
-/** Broadcast pydaikin's discovery packet (UDP 30000 → 30050) and collect who answers within `ms`. */
+/** Broadcast pydaikin's discovery packet (UDP 30000 → 30050), three times across `ms`, and collect who answers, each unit once. */
 export function findDaikins(
   ms = 1500,
 ): Promise<{ ip: string; fields: Record<string, string> }[]> {
   return new Promise((resolve) => {
     const found: { ip: string; fields: Record<string, string> }[] = [];
     const sock = createSocket({ type: "udp4", reuseAddr: true });
-    sock.on("message", (msg, from) =>
-      found.push({ ip: from.address, fields: daikinFields(msg.toString()) }),
+    sock.on("message", (msg, from) => {
+      if (!found.some((f) => f.ip === from.address))
+        found.push({ ip: from.address, fields: daikinFields(msg.toString()) });
+    });
+    const asks: ReturnType<typeof setTimeout>[] = [];
+    const done = () => (
+      asks.forEach(clearTimeout),
+      sock.close(),
+      resolve(found)
     );
-    sock.on("error", () => (sock.close(), resolve(found)));
+    sock.on("error", done);
     sock.bind(30000, () => {
       sock.setBroadcast(true);
-      sock.send("DAIKIN_UDP/common/basic_info", 30050, "255.255.255.255");
-      setTimeout(() => (sock.close(), resolve(found)), ms);
+      // UDP drops packets, more so while mDNS is busy beside it: one ask missed KO's unit in 2 runs of 3 (2026-11-11). Ask three times.
+      const ask = () =>
+        sock.send("DAIKIN_UDP/common/basic_info", 30050, "255.255.255.255");
+      ask();
+      asks.push(setTimeout(ask, ms / 3), setTimeout(ask, (2 * ms) / 3));
+      setTimeout(done, ms);
     });
   });
 }

package/src/home.ts

@@ -140,7 +140,7 @@ function stamped(part: Part, before: Part | undefined, now: string): Part {
 
 /**
  * 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<I extends Integration<any, string>>(
   integrations: readonly I[],
@@ -148,14 +148,34 @@ export function createHome<I extends Integration<any, string>>(
   options: { clock?: Clock } = {},
 ) {
   type Name = I["name"];
+  type Run = { stop: AbortController; done: Promise<void> };
   const clock = options.clock ?? realClock;
+  const list: I[] = [...integrations]; // the integrations now: `add` and `remove` change it
+  const parts = () => snapshot as Record<string, Part>;
   let snapshot = Object.fromEntries(
-    integrations.map((i) => [i.name, { status: "connecting" }]),
+    list.map((i) => [i.name, { status: "connecting" }]),
   ) as HomeSnapshot<I>;
   const waiting = new Map<string, (() => void)[]>(); // refresh() callers, resolved by the integration's next report
-  const finished = new Set<string>(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: Name, reported: Part) => {
-    const before = (snapshot as Record<string, Part>)[name]!;
+  const runs = new Map<I, Run>(); // the ones running: before start or after its run ended, a refresh resolves at once, nothing will report
+  const latest = new WeakMap<I, Run>(); // each integration's newest run: a report from an older run of the same object is dropped
+  let started: AbortSignal | undefined; // start()'s signal, while it runs
+  let changing: Promise<unknown> = 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 = <T>(fn: () => Promise<T>): Promise<T> => {
+    changes++;
+    const done = changing.then(fn).finally(() => changes--);
+    changing = done.catch(() => {});
+    return done;
+  };
+  const heard = (name: string) => {
+    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: I, run: Run, reported: Part) => {
+    const name: 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(() =>
@@ -163,11 +183,45 @@ export function createHome<I extends Integration<any, string>>(
     ).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: I, signal: AbortSignal) => {
+    const stop = new AbortController();
+    const run: 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: string) => {
+    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 as HomeSnapshot<I>;
+    heard(name);
+    const run = runs.get(old!);
+    run?.stop.abort();
+    await run?.done;
+    return true;
   };
   return {
     /** The latest snapshot. Never touches a device. */
@@ -178,61 +232,67 @@ export function createHome<I extends Integration<any, string>>(
     integration: <N extends Name>(
       name: N,
     ): Extract<I, { name: N }> | undefined =>
-      integrations.find((i) => i.name === name) as
-        Extract<I, { name: N }> | undefined,
+      list.find((i) => i.name === name) as Extract<I, { name: N }> | undefined,
     /**
      * 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?: Name): Promise<void> {
       const targets =
-        name === undefined
-          ? integrations
-          : integrations.filter((i) => i.name === name);
-      if (!targets.length)
+        name === undefined ? [...list] : list.filter((i) => i.name === name);
+      if (!targets.length && name !== undefined)
         throw new Error(
-          `no integration "${name}"; have ${integrations.map((i) => i.name).join(", ")}`,
+          `no integration "${name}"; have ${list.map((i) => i.name).join(", ")}`,
         );
       const reported = targets.map(
         (i) =>
           new Promise<void>((resolve) => {
-            if (finished.has(i.name)) return resolve();
+            if (!runs.has(i)) return resolve();
             waiting.set(i.name, [...(waiting.get(i.name) ?? []), resolve]);
           }),
       );
       for (const i of targets) 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: I): Promise<void> =>
+      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: Name): Promise<boolean> => 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: AbortSignal): Promise<void> {
-      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 as Record<string, Part>).map(([name, p]) => [
+        Object.entries(parts()).map(([name, p]) => [
           name,
           p.status === "connecting"
             ? { ...p, downSince: p.downSince ?? now }
             : p,
         ]),
       ) as HomeSnapshot<I>;
-      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 as Record<string, Part>)[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/src/index.ts

@@ -22,7 +22,13 @@ export {
   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 {