@khalido/home 0.1.3 → 0.2.0

package/dist/connectors/hue/schemas.d.ts

@@ -19,6 +19,33 @@ export declare const Resource: z.ZodObject<{
     dimming: z.ZodOptional<z.ZodObject<{
         brightness: z.ZodNumber;
     }, z.core.$loose>>;
+    color: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        xy: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$loose>>>;
+        gamut: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+            red: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$loose>;
+            green: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$loose>;
+            blue: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$loose>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>>;
+    color_temperature: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        mirek: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        mirek_schema: z.ZodOptional<z.ZodObject<{
+            mirek_minimum: z.ZodOptional<z.ZodNumber>;
+            mirek_maximum: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>>;
     children: z.ZodOptional<z.ZodArray<z.ZodObject<{
         rid: z.ZodString;
         rtype: z.ZodString;

package/dist/connectors/hue/schemas.js

@@ -4,6 +4,7 @@ import { z } from "zod";
 // field is unconfirmed from the primary source. Only the fields the snapshot reads are parsed;
 // 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 = [
     "light",
@@ -22,6 +23,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/dist/connectors/hue/state.d.ts

@@ -1,3 +1,4 @@
+import { type Gamut, type XY } 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. */
 export type HueSnapshot = {
@@ -17,8 +18,16 @@ 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 declare function lights(s: HueSnapshot): LightView[];
 /** A room or zone as a row shows it, with its grouped light's state. */
 export type GroupView = {

package/dist/connectors/hue/state.js

@@ -1,3 +1,4 @@
+import { mirekToKelvin, xyToHex } from "./color.js";
 /** A snapshot from one full `get()`. */
 export function snapshotFrom(resources, asOf) {
     return {
@@ -32,7 +33,7 @@ const ofType = (s, type) => Object.values(s.resources).filter((r) => r.type ===
 const groupedLightOf = (s, r) => r.services
     ?.map((x) => s.resources[x.rid])
     .find((x) => x?.type === "grouped_light");
-/** 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) {
     const zigbee = ofType(s, "zigbee_connectivity");
     return ofType(s, "light").map((l) => {
@@ -43,9 +44,27 @@ export function lights(s) {
             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) {
+    const out = {};
+    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;
+}
 /** Rooms and zones. A room's children are devices; a zone's are lights. */
 export function groups(s) {
     const all = ofType(s, "light");

package/dist/connectors/spotify/changes.d.ts

@@ -2,8 +2,16 @@ import type { Part } from "../../home.ts";
 import type { SpotifyState, Stall, Track } from "./client.ts";
 /** A stall in a few words: `playback stalled at 1:39 (Soloist issue #5); tried a seek`. */
 export declare function stallText(s: Stall | undefined): string | undefined;
-/** 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. */
-export type SpeakerState = "offline" | "connecting" | "waiting" | "idle" | "playing" | "paused" | "buffering" | (string & {});
+/**
+ * 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 declare const playingElsewhere: (s: SpotifyState | undefined) => boolean;
+/**
+ * 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" | "buffering" | (string & {});
 export declare function speakerState(part: Part<SpotifyState> | undefined): SpeakerState;
 /**
  * A change worth telling someone about, from two reports of the speaker. `own`, on playback events only: it happened while
@@ -24,9 +32,15 @@ export type SpotifyEvent = {
 /**
  * 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 declare function spotifyChanges(before: Part<SpotifyState> | undefined, after: Part<SpotifyState> | undefined): SpotifyEvent[];
-/** The speaker in a few words: `Kitchen speaker: playing "Song" by Band · 35%`, or `…: waiting for someone to pick it`. */
-export declare 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 declare function spotifyText(s: SpotifyState, on?: string[]): string;

package/dist/connectors/spotify/changes.js

@@ -9,6 +9,12 @@ export function stallText(s) {
         : `playback stalled at ${at} (Soloist issue #5)`;
     return s.tried ? `${what}; tried ${s.tried}` : what;
 }
+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) => s?.active === false && PLAYING.has(s.status ?? "");
 export function speakerState(part) {
     if (!part || part.status === "disconnected" || part.status === "unavailable")
         return "offline";
@@ -16,13 +22,16 @@ export function speakerState(part) {
         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
 }
-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(before, after) {
@@ -45,8 +54,11 @@ export function spotifyChanges(before, after) {
         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) => (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)
@@ -57,7 +69,11 @@ export function spotifyChanges(before, after) {
         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) => !!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 });
@@ -68,8 +84,12 @@ export function spotifyChanges(before, after) {
         events.push({ type: "recovered" });
     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) {
+/**
+ * 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, on = []) {
     const who = s.deviceName ?? "Soloist";
     if (s.loggedIn === false)
         return `${who}: waiting for someone to pick it`;
@@ -77,6 +97,8 @@ export function spotifyText(s) {
     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/dist/connectors/spotify/index.d.ts

@@ -5,7 +5,7 @@ import type { Manifest } from "../../manifest.ts";
 import { type SpeakerState } from "./changes.ts";
 import { type SocketFactory, type SpotifyState } from "./client.ts";
 export { positionMs, type PositionAnchor, type SocketFactory, type SocketLike, type SpotifyState, type Stall, toSpotifyUri, type Track, } from "./client.ts";
-export { type SpeakerState, speakerState, type SpotifyEvent, spotifyChanges, spotifyText, } from "./changes.ts";
+export { type SpeakerState, playingElsewhere, speakerState, type SpotifyEvent, spotifyChanges, spotifyText, } from "./changes.ts";
 /** Soloist has no default port (`--ws ADDR:PORT` opens it); this library assumes this one, the port in chota-bot's unit. */
 export declare const DEFAULT_URL = "ws://127.0.0.1:9091";
 /** A Soloist speaker in a home config. No key: Soloist's API key is the daemon's, never the library's. */

package/dist/connectors/spotify/index.js

@@ -6,7 +6,7 @@ import { writeLane } from "../../lane.js";
 import { speakerState, spotifyText, stallText, } from "./changes.js";
 import { commandFrame, fold, Frame, FRAME_TYPES, OPEN, oddities, positionMs, toSpotifyUri, } from "./client.js";
 export { positionMs, toSpotifyUri, } from "./client.js";
-export { speakerState, spotifyChanges, spotifyText, } from "./changes.js";
+export { playingElsewhere, speakerState, spotifyChanges, spotifyText, } from "./changes.js";
 /** Soloist has no default port (`--ws ADDR:PORT` opens it); this library assumes this one, the port in chota-bot's unit. */
 export const DEFAULT_URL = "ws://127.0.0.1:9091";
 /** A Soloist speaker in a home config. No key: Soloist's API key is the daemon's, never the library's. */
@@ -651,6 +651,7 @@ export function spotify(config = {}) {
         if (!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;
         const { stalled: _, ...rest } = state;
@@ -678,7 +679,11 @@ export function spotify(config = {}) {
         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 () => {
         if (!playing())
@@ -720,6 +725,7 @@ export function spotify(config = {}) {
         // Still ours to fix: playing this track, stalled, and no duck, interrupt or person in between.
         const ours = () => isOpen() &&
             state.status === "playing" &&
+            state.active !== false &&
             state.track?.uri === track &&
             state.stalled?.track === track &&
             (!state.aside || state.aside === "repair");

package/dist/devices.d.ts

@@ -25,3 +25,27 @@ export declare const SERVICES: readonly string[];
  * no name of its own (the Daikin, the Enphase gateway) the entry's `name`. A device's own name is never replaced.
  */
 export declare function homeDevices(snapshot: Record<string, Part | undefined>, config?: Pick<HomeConfig, "devices" | "rooms">): HomeDevice[];
+/**
+ * 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 declare function spotifyElsewhere(snapshot: Record<string, Part | undefined>): string[];
+/** 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 declare function byRoom(snapshot: Record<string, Part | undefined>, config: Pick<HomeConfig, "devices" | "rooms">): {
+    rooms: RoomDevices[];
+    unplaced: HomeDevice[];
+};

package/dist/devices.js

@@ -3,7 +3,7 @@ import { daikinHomeDevices, } from "./connectors/daikin/index.js";
 import { enphaseHomeDevices, } from "./connectors/enphase/index.js";
 import { hueHomeDevices } from "./connectors/hue/index.js";
 import { printersHomeDevices, } from "./connectors/printers/index.js";
-import { spotifyHomeDevices, } from "./connectors/spotify/index.js";
+import { playingElsewhere, spotifyHomeDevices, spotifyText, } from "./connectors/spotify/index.js";
 import { IDENTITY, sameId } from "./discover.js";
 import { manifestOf } from "./manifests.js";
 /** Each connector's devices from its part, in the order `home status` lists the connectors. */
@@ -23,7 +23,13 @@ export const SERVICES = ["amber", "up", "weather"];
  * no name of its own (the Daikin, the Enphase gateway) the entry's `name`. A device's own name is never replaced.
  */
 export function homeDevices(snapshot, config) {
-    const all = Object.entries(DEVICES).flatMap(([name, devices]) => devices(snapshot[name]));
+    // 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]) => devices(snapshot[name]))
+        .map((d) => d.connector === "spotify" && on.length
+        ? { ...d, text: spotifyText(d.detail, on) }
+        : d);
     if (!config)
         return all;
     const entries = config.devices ?? [];
@@ -59,3 +65,51 @@ export function homeDevices(snapshot, config) {
         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) {
+    const s = snapshot.spotify?.state;
+    const cast = snapshot.cast?.state;
+    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);
+}
+/**
+ * `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, config) {
+    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/dist/discover.js

@@ -82,7 +82,7 @@ function newEntry(f) {
         [IDENTITY[f.connector]]: f.id,
     };
     if (f.connector === "hue")
-        return { ...base, key: "HUE_APPLICATION_KEY", ca: "hue-root-ca.pem" };
+        return { ...base, key: "HUE_APPLICATION_KEY" };
     if (f.connector === "enphase")
         return { ...base, token: "~/.config/home/enphase-token.json" };
     return base;

package/dist/finders-entry.d.ts

@@ -1 +1 @@
-export { FINDERS, fileCache } from "./finders.ts";
+export { FINDERS, fileCache, MissingTool } from "./finders.ts";

package/dist/finders-entry.js

@@ -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.js";
+export { FINDERS, fileCache, MissingTool } from "./finders.js";

package/dist/finders.d.ts

@@ -1,5 +1,6 @@
 import { type AddressCache, type Connector, type Finder, type Found } from "./discover.ts";
 /** 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 declare class MissingTool extends Error {
 }
 /**
@@ -27,7 +28,7 @@ export declare function mdnsResolve(type: string): Promise<{
 }[]>;
 /** Daikin's `key=value,key=value` answers, percent-decoded. */
 export declare const daikinFields: (text: string) => any;
-/** 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 declare function findDaikins(ms?: number): Promise<{
     ip: string;
     fields: Record<string, string>;

package/dist/finders.js

@@ -13,6 +13,7 @@ import { parseAvahi, parseAvahiBrowse, parseBrowse, parseResolve, } from "./disc
 // does not slow a scan. Without the tool the mDNS finders throw, naming it, rather than "nothing answered".
 // `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 {
 }
 /**
@@ -94,17 +95,27 @@ function decoded(v) {
         return v;
     }
 }
-/** 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) {
     return new Promise((resolve) => {
         const found = [];
         const sock = createSocket({ type: "udp4", reuseAddr: true });
-        sock.on("message", (msg, from) => found.push({ ip: from.address, fields: daikinFields(msg.toString()) }));
-        sock.on("error", () => (sock.close(), resolve(found)));
+        sock.on("message", (msg, from) => {
+            if (!found.some((f) => f.ip === from.address))
+                found.push({ ip: from.address, fields: daikinFields(msg.toString()) });
+        });
+        const asks = [];
+        const done = () => (asks.forEach(clearTimeout),
+            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/dist/home.d.ts

@@ -87,7 +87,7 @@ export type Change<I extends Integration<any, string> = Integration<unknown, str
 }[I["name"]];
 /**
  * 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 declare function createHome<I extends Integration<any, string>>(integrations: readonly I[], onChange?: (home: HomeSnapshot<I>, change: Change<I>) => void, options?: {
     clock?: Clock;
@@ -105,7 +105,16 @@ export declare function createHome<I extends Integration<any, string>>(integrati
      * promise resolves once each target has reported (its next update, good or bad), or at once for one that isn't running.
      */
     refresh(name?: I["name"]): Promise<void>;
-    /** 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>;
+    /** 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: I["name"]) => Promise<boolean>;
+    /** Run every integration, and any added meanwhile, until `signal` aborts. One failing marks itself unavailable; the rest carry on. */
     start(signal: AbortSignal): Promise<void>;
 };
 /**