@khalido/home 0.1.3 → 0.2.1

package/.env.example

@@ -4,8 +4,8 @@
 HUE_BRIDGE_HOST=hue-bridge.local      # optional: found by mDNS (dns-sd) when unset
 HUE_BRIDGE_ID=0017880000000000        # optional: the certificate's CN must match it; mDNS finds it when unset
 HUE_APPLICATION_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx # from `home pair`
-HUE_CA_FILE=/path/to/hue-root-ca.pem  # until HUE_BRIDGE_ROOT_CA ships in src/connectors/hue/
-DAIKIN_HOST=192.0.2.20                # the unit's address; `home probe` finds it by UDP broadcast
+HUE_CA_FILE=/path/to/hue-root-ca.pem  # optional: a root CA to trust instead of Signify's two, which the package carries
+DAIKIN_HOST=192.0.2.20                # optional: the unit's address; found by UDP broadcast when unset (1.5 s a run)
 IQ_GATEWAY_HOST=envoy.local           # the IQ Gateway on the LAN (a scheme is tolerated)
 IQ_GATEWAY_SERIAL_NUMBER=000000000000 # optional: for `home enphase login`; from the Enphase app: System > Devices > Gateway
 ENPHASE_USERNAME=you@example.com      # optional: for `home enphase login`, once a year: the Enphase account

package/CHANGELOG.md

@@ -4,6 +4,59 @@ All notable changes to home.ts (`@khalido/home` on npm), in [Keep a Changelog](h
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-11-12
+
+### Added
+
+- **printers:** printing. `identifyPrinter`, `validateJob`, `printJob` and `cancelJob` over IPP, and `pwgRaster` for a printer that takes no PDF (8-bit grey PWG Raster). The snapshot's `Printer` gains `port` and `rp`, so a write can reach it. `home printers print <file.pdf> [printer]`, `identify` and `cancel`; `print --dry-run` has the printer validate the job and sends no job; a printer with no PDF needs poppler's `pdftoppm`. Live on a Brother HL-L2350DW.
+
+### Fixed
+
+- **cli, enphase:** a stale `IQ_GATEWAY_HOST` no longer leaves `home enphase` refused for good: with the gateway's serial from the address cache, a failed read is followed by mDNS discovery, and the line says where the gateway moved. Without `IQ_GATEWAY_HOST` the address comes from the cache, then from mDNS.
+- **amber, enphase, up:** a 403 is a rejected key (`unavailable`, `reason: "auth"`), as a 401 already was and as Hue and Google weather already read both. It was `disconnected` and retried forever. One check, `isRejectedKey` in `src/connector.ts`, now serves every connector and the CLI.
+- **spotify:** after the first-play lowering ([spotify/soloist#23](https://github.com/spotify/soloist/issues/23)), `anomaly` no longer says only "lowered it" when the volume is back above `maxVolume`: it adds `it is back at <n>`. Soloist puts its own level back about 90 ms after `playing` when it goes active (live, 2026-11-11), and the cap leaves that level alone.
+
+## [0.2.0] - 2026-11-12
+
+### Breaking
+
+- **spotify: music on another Spotify device no longer reads as this speaker playing.** When Soloist says `playing` (or `buffering`) while it isn't the account's active device, `speakerState` now gives `elsewhere` (it gave `playing`), `spotifyText` says `silent · "Song" by Band is playing on another Spotify device`, and `spotifyChanges` treats it as silence: music moving off this speaker is `stopped`, music moving onto it is `started` then `track`, and nothing fires for its tracks or pauses meanwhile (it fired `resumed` with the box silent). `home devices --json` carries the new `state`. What to do: add `elsewhere` wherever you switch on `speakerState`; `state.status` is still what Soloist said.
+- **cli: `home scene <name>` no longer takes the first match** when several rooms have a scene by that name: it lists them and exits 2, and `home scene <name> in <room>` picks one. A wrong or shared room or scene name is a usage error (exit 2), where it was exit 1. What to do: a script that recalls a shared scene name adds `in <room>`.
+
+### Fixed
+
+- **spotify:** the stall watch no longer looks at, or repairs, music playing on another device.
+
+### Changed
+
+- **cli:** `home room <name> <n>` and `home scene` print the room's line after the write, where they printed nothing.
+- **hue:** a light's line shows its white temperature or colour when on (`Desk: on · 40% · 2700 K`), in `home hue`, `home devices` and `homeDevices`.
+- **docs, for a consumer:** `docs/using.md` has each write and what it resolves with in one table, an announce-where-free example, and what a part's `status` and `reason` and an error's `code` mean. `docs/config.md`'s `loadHome` call now passes what Cast needs (`finders`, `castConnect`). `llms.txt` says what to call.
+- **docs:** `castStatus` and `castFree` take the Cast part's state (`home.part("cast")?.state`), which the docs called "the snapshot".
+- **cli:** `home` and `home daikin` find the Daikin by UDP broadcast when `DAIKIN_HOST` is unset, as the write commands do, so `DAIKIN_HOST` is optional. With no unit on the network it reads "not set up".
+- **cli:** `home cast volume | mute | stop` print the device's line once it reports the change, where they printed nothing; after 2 s without it, "sent; the device has not reported it yet".
+- **cli:** "no route to host" on macOS now adds that the terminal may need the Local Network permission.
+
+### Added
+
+- **Dry run on Hue's and the Daikin's writes**: `{ dryRun: true }` as the last argument of `light`, `room`, `scene`, `allOff`, `power` and `mode`. The read and every check made before sending run, and no write is sent; the result's `wouldSend` is the request it would make (`HueRequest`, `DaikinRequest` with `sets`), `state` how things stand, `confirmed: false`. `--dry-run` on the same commands (`home light | room | scene | lights off`, `home hue …`, `home daikin …`); every other command refuses the flag.
+- **hue: `client.allOff()`**: every light in the home off with one write, resolving `{ state, confirmed }` with every light as the bridge then reported it. `home lights off` uses it and now prints the result.
+- **`byRoom(snapshot, config)`** from `@khalido/home`, for a map of the home: each room of the config with its devices, `noData` for a connector the config places there that has nothing to list, and `unplaced` for the rest.
+- **config: `photos` on a room**, a list of paths. The library carries them and reads nothing.
+- **cast: `castFreeSpeakers(state)`**: every free speaker and display in one call, a whole group where all of it is free, never a TV; `free` goes straight to `announceAll`.
+- **cast: `castFree(state, targets, { forms })`**: with `forms: ["speaker", "display"]` a TV is left out (`why: "form"`, only when `forms` is given), and a group holding one becomes its other free members.
+- **`home.add(integration)` and `home.remove(name)`** on the home `createHome` returns: add one while the rest keep running (a bridge paired just now), replace one by name (the old run has ended before the new one starts; how an `unavailable` part comes back after a re-key), or stop one and drop its part. `start` now also waits for those added.
+- **spotify: `playingElsewhere(state)`**, and **`spotifyElsewhere(snapshot)`** from `@khalido/home`: the names of the Cast devices and groups playing that track in Spotify, matched by the track's name since Soloist doesn't say where the music is. Empty for a phone or a laptop. `homeDevices` and `home devices` put it in the speaker's line (`silent · "Song" is playing on Den speaker`), and `spotifyText(state, on)` takes it. Tested on built snapshots only.
+- **hue: lights, rooms and scenes by name.** `client.light(name, change)`, `client.room(name, change)` and `client.scene(name, room?)`, each resolving `{ state, confirmed }` (`HueApplied`). `change` (`LightChange`) is `{ on?, brightness?, color?, kelvin?, transitionMs? }`: a colour as hex or `{ r, g, b }`, sent as `xy` inside the light's own gamut; a white temperature in kelvin, checked against the light's range. An unknown name or a value the light can't take throws `HueError` with `code: "invalid"` before anything is sent, and a light the bridge has lost throws with `code: "offline"`.
+- **hue: colour in the state.** Each light's `kelvin` and `kelvinRange`, and on a colour light its `xy`, `hex` and `gamut`. `colorToXy`, `xyToHex`, `kelvinToMirek`, `mirekToKelvin` and `hueText` are exported.
+- **`home light <name> …`**, and `home room` and `home scene` now take a brightness, a temperature (`2700k`) and a colour (`ff8800`) together, name a scene's room (`in <room>`), and print what the bridge then reported.
+- **hue: Signify's root certificates are in the package**, as `HUE_BRIDGE_ROOT_CA` from `@khalido/home/hue`: both roots, the bundle from Signify's "Using HTTPS" page. `ca` is now optional everywhere it was required: `hue({ host, bridgeId, key })`, `bunPinnedFetch(bridgeId)`, `nodePinnedFetch(bridgeId)`, the config's `ca` and the CLI's `HUE_CA_FILE`. One given still replaces the bundle. `home probe` reads the bridge without setup, and `home discover --write` no longer writes a `ca` line.
+- **hue: `pairWhenPressed`**: `pair`, asked every 2 s for 30 s until the bridge's button is pressed, with `onWaiting` for the moment to prompt. `pair` takes a `signal`. `home pair` now waits 60 s for the button, counting down, and says when no press was detected.
+- **daikin: `client.power(on)` and `client.mode(mode, targetC?)`**, resolving with `{ state, confirmed }` (`DaikinApplied`) once the unit reports what was asked, or after 5 s (`CONFIRM_MS`) without it. `mode` sends the mode, power on and the setpoint as one request: the one given, else the library's defaults, `DEFAULT_TARGET_C` (cool 25, heat 27).
+- **`home daikin on | off`** (power only, as it was last left) and **`home daikin cool | heat | auto [°C] | dry | fan`**, each printing what the unit then reports.
+- **`MissingTool`** from `@khalido/home/finders`: thrown when the discovery tool (`dns-sd` on macOS, `avahi-browse` on Linux) isn't installed.
+- **`home devices`:** every device the connectors read, one line each from `homeDevices`: its state, its room and name from the config when there is one, and why when it isn't available. `--json` prints the records. A connector that isn't connected is named on stderr.
+
 ## [0.1.3] - 2026-11-10
 
 ### Added
@@ -98,7 +151,9 @@ First release. Nine connectors: Hue, Daikin, Enphase, Google Cast, AirPrint prin
 - **Agent skills** in `skills/`: `use-home` (reading safely, connecting, the rules for writes) and `draw-home` (an SVG plan of a home and its rooms). `llms.txt` points agents at the docs.
 - **Node.** Hue and Enphase take the fetches in `@khalido/home/node`. The library runs on Bun 1.4+ and Node 24+; the `home` command needs Bun.
 
-[Unreleased]: https://github.com/khalido/home.ts/compare/v0.1.3...HEAD
+[Unreleased]: https://github.com/khalido/home.ts/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/khalido/home.ts/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/khalido/home.ts/compare/v0.1.3...v0.2.0
 [0.1.3]: https://github.com/khalido/home.ts/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/khalido/home.ts/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/khalido/home.ts/compare/v0.1.0...v0.1.1

package/README.md

@@ -13,7 +13,9 @@ Small, typed home automation for TypeScript, starting with the devices in my hou
 bun add @khalido/home     # or: npm install @khalido/home
 ```
 
-The library runs on Bun 1.4+ and Node 24+, and is ESM only. The `home` command needs Bun.
+The library runs on Bun 1.4+ and Node 24+, and is ESM only. The `home` command needs Bun on your `PATH`; in a project that added the package, run it as `bunx home`.
+
+Pointing a coding agent at it? Give it [llms.txt](llms.txt): what to call and where each doc is. [Using it from an app](docs/using.md) is the same for people.
 
 ## Try it
 
@@ -26,6 +28,7 @@ bun link        # puts `home` on your PATH
 home discover   # what answers on this network, and which of it this package supports
 home probe      # read-only checks, no keys
 home            # each connector: connected, or what it still needs
+home devices    # every device, one line each
 ```
 
 Copy [.env.example](.env.example) to `.env` and fill in the connectors you have, or describe the home in a [config file](docs/config.md) ([example](examples/home.jsonc)).
@@ -66,9 +69,11 @@ Each connector's README says what has run against a real device and what has not
 
 ## More
 
+- [Using it from an app](docs/using.md): the wiring, each write and what it returns
 - [The `home` command](docs/cli.md) and [the home config](docs/config.md)
+- [Hue](docs/hue.md): Signify's guidance on certificates, pairing and write rates
 - [Why it is shaped this way](docs/philosophy.md) and [decisions](docs/decisions.md)
-- To add a connector, follow [AGENTS.md](AGENTS.md)
+- To add a connector, follow [AGENTS.md](https://github.com/khalido/home.ts/blob/main/AGENTS.md)
 - For agents: [llms.txt](llms.txt)
 
 I use it from jaldi, a Mac launcher, and chota-bot, a family bot on a Raspberry Pi, both on Bun; the docs name both.

package/dist/config.d.ts

@@ -16,6 +16,7 @@ export declare const Room: z.ZodObject<{
     name: z.ZodString;
     floor: z.ZodOptional<z.ZodString>;
     hueRoom: z.ZodOptional<z.ZodString>;
+    photos: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$loose>;
 /** JSONC (comments and trailing commas) through jsonc-parser, which runs on Node too; a syntax error throws rather than parsing to part of the file. */
 export declare function parseJsonc(text: string): unknown;
@@ -25,7 +26,7 @@ export declare const Device: z.ZodDiscriminatedUnion<[z.ZodObject<{
     host: z.ZodString;
     bridgeId: z.ZodString;
     key: z.ZodString;
-    ca: z.ZodString;
+    ca: z.ZodOptional<z.ZodString>;
     id: z.ZodString;
     room: z.ZodOptional<z.ZodString>;
     name: z.ZodOptional<z.ZodString>;
@@ -123,13 +124,14 @@ export declare const HomeConfig: z.ZodObject<{
         name: z.ZodString;
         floor: z.ZodOptional<z.ZodString>;
         hueRoom: z.ZodOptional<z.ZodString>;
+        photos: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$loose>>>;
     devices: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         connector: z.ZodLiteral<"hue">;
         host: z.ZodString;
         bridgeId: z.ZodString;
         key: z.ZodString;
-        ca: z.ZodString;
+        ca: z.ZodOptional<z.ZodString>;
         id: z.ZodString;
         room: z.ZodOptional<z.ZodString>;
         name: z.ZodOptional<z.ZodString>;
@@ -246,7 +248,7 @@ export type LoadOptions = {
     fetch?: typeof fetch;
     /** Hue's pinned fetch and Enphase's unverified one: Bun's by default, `NODE_TLS` from `@khalido/home/node` under Node. */
     tls?: {
-        hue(bridgeId: string, ca: string): typeof fetch;
+        hue(bridgeId: string, ca?: string): typeof fetch;
         enphase(): typeof fetch;
     };
     /** BOM's transport: `ftpFetch()` from `@khalido/home/weather/ftp`. Without it a listed `bom` source stops and says why. */

package/dist/config.js

@@ -25,6 +25,10 @@ export const Room = z.looseObject({
         .string()
         .optional()
         .describe("the Hue room, zone or grouped_light id whose lights this room's marker shows"),
+    photos: z
+        .array(filePath)
+        .optional()
+        .describe("photos of the room, as paths relative to the config or from ~/; the library never reads them, a drawing agent or an app does"),
 });
 /** JSONC (comments and trailing commas) through jsonc-parser, which runs on Node too; a syntax error throws rather than parsing to part of the file. */
 export function parseJsonc(text) {
@@ -266,7 +270,7 @@ export function loadHome(input, options) {
     function one(d, at) {
         switch (d.connector) {
             case "hue": {
-                const ca = file(d.ca);
+                const ca = d.ca === undefined ? undefined : file(d.ca);
                 return hue({
                     ...start("hue", d.bridgeId, d.host),
                     bridgeId: d.bridgeId,

package/dist/connector.d.ts

@@ -23,6 +23,8 @@ export declare class ConnectorError extends Error {
         cause?: unknown;
     });
 }
+/** A 401 or 403 from a device or service: the key or token is wrong or revoked. Every connector reads it as `reason: "auth"`. */
+export declare const isRejectedKey: (error: unknown) => boolean;
 /** `fetch` that gives up after `timeoutMs`, or as soon as `signal` (a run's) aborts. Returns the response whatever its status. */
 export declare function fetchTimeout(fetcher: typeof fetch, url: string | URL, init?: Omit<RequestInit, "signal">, options?: {
     timeoutMs?: number;

package/dist/connector.js

@@ -24,6 +24,9 @@ export class ConnectorError extends Error {
         this.code = options.code;
     }
 }
+/** A 401 or 403 from a device or service: the key or token is wrong or revoked. Every connector reads it as `reason: "auth"`. */
+export const isRejectedKey = (error) => error instanceof ConnectorError &&
+    (error.status === 401 || error.status === 403);
 /** `fetch` that gives up after `timeoutMs`, or as soon as `signal` (a run's) aborts. Returns the response whatever its status. */
 export function fetchTimeout(fetcher, url, init = {}, options = {}) {
     const timeout = AbortSignal.timeout(options.timeoutMs ?? TIMEOUT_MS);

package/dist/connectors/amber/client.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { ConnectorError } from "../../connector.ts";
-/** A failed Amber call. `status` 401 means the key is wrong or revoked; 429 means the rate limit (50 per 5 min). */
+/** A failed Amber call. `status` 401 or 403 (`isRejectedKey`) means the key is wrong or revoked; 429 means the rate limit (50 per 5 min). */
 export declare class AmberError extends ConnectorError {
 }
 /** One 5-minute price interval on one channel. Prices are c/kWh including GST, as a cost: negative feed-in means you are paid. */

package/dist/connectors/amber/client.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { ConnectorError, getJson } from "../../connector.js";
 // Amber Electric's public API v1 (https://app.amber.com.au/developers; the published spec is 1.0, there is no v2). Shapes checked against live replies,
 // 2026-10-13; every field optional so a change degrades a reading rather than throwing.
-/** A failed Amber call. `status` 401 means the key is wrong or revoked; 429 means the rate limit (50 per 5 min). */
+/** A failed Amber call. `status` 401 or 403 (`isRejectedKey`) means the key is wrong or revoked; 429 means the rate limit (50 per 5 min). */
 export class AmberError extends ConnectorError {
 }
 /** One 5-minute price interval on one channel. Prices are c/kWh including GST, as a cost: negative feed-in means you are paid. */

package/dist/connectors/amber/index.js

@@ -1,5 +1,5 @@
 import { asOf, realClock } from "../../clock.js";
-import { errorText } from "../../connector.js";
+import { errorText, isRejectedKey } from "../../connector.js";
 import { z } from "zod";
 import { envName } from "../../home.js";
 import { energyNow } from "../../energy.js";
@@ -41,7 +41,7 @@ export function amber(config) {
                 catch (error) {
                     if (signal.aborted)
                         return; // stopped mid-read: not a failure
-                    if (error instanceof AmberError && error.status === 401)
+                    if (isRejectedKey(error))
                         return update({
                             status: "unavailable",
                             reason: "auth",

package/dist/connectors/cast/index.d.ts

@@ -7,7 +7,7 @@ import { type CastConnect } from "./codec.ts";
 import { type CastDevice, type CastSnapshot, type Resolved, type CastForm, type CastStatus } from "./state.ts";
 import { type CastActions, type ServeClip } from "./writes.ts";
 export type { CastConnect } from "./codec.ts";
-export { castDevices, castForm, castFree, castStatus } from "./state.ts";
+export { castDevices, castForm, castFree, castFreeSpeakers, castStatus, } from "./state.ts";
 export type { CastDevice, CastForm, CastSkipped, CastSnapshot, CastStatus, Resolved, } from "./state.ts";
 export type { AnnounceResult, CastActions, CastClip, ServeClip, } from "./writes.ts";
 /** A Cast device or speaker group in a home config. No host: a group's moves with its leader, so every address comes from discovery. */

package/dist/connectors/cast/index.js

@@ -8,7 +8,7 @@ import { NS } from "./codec.js";
 import { CastPayload, KNOWN_TYPES } from "./schemas.js";
 import { castKey, connection, found, mediaApp, reduce, castDevices, castStatus, } from "./state.js";
 import { castActions, } from "./writes.js";
-export { castDevices, castForm, castFree, castStatus } from "./state.js";
+export { castDevices, castForm, castFree, castFreeSpeakers, castStatus, } from "./state.js";
 /** A Cast device or speaker group in a home config. No host: a group's moves with its leader, so every address comes from discovery. */
 export const configSchema = z.looseObject({
     connector: z.literal("cast"),

package/dist/connectors/cast/state.d.ts

@@ -97,10 +97,10 @@ export type CastStatus = {
 };
 /** Every device and group in the snapshot as a `CastStatus`, devices first, each by name. */
 export declare function castStatus(s: CastSnapshot): CastStatus[];
-/** A target `castFree` left out: `standby` is a TV that is off, which a clip may wake. */
+/** A target `castFree` left out: `standby` is a TV that is off, which a clip may wake; `form` is one whose form wasn't asked for. */
 export type CastSkipped = {
     name: string;
-    why: "busy" | "offline" | "standby" | "unknown";
+    why: "busy" | "offline" | "standby" | "unknown" | "form";
     app?: string;
 };
 /**
@@ -111,8 +111,22 @@ export type CastSkipped = {
  *   becomes its free members, named one by one (they then play out of step with each other).
  * - A device is never named beside a free group that holds it, nor two groups that share a member: the second becomes its
  *   members not yet covered.
+ * - With `forms` (`["speaker", "display"]` keeps an announcement off TVs), a device of another form, or of a model this
+ *   library doesn't know, is skipped with `why: "form"`, and a group holding one (or a member the snapshot doesn't have)
+ *   becomes its other free members. An empty list leaves every device out.
  */
-export declare function castFree(s: CastSnapshot, targets: string[]): {
+export declare function castFree(s: CastSnapshot, targets: string[], options?: {
+    forms?: readonly CastForm[];
+}): {
+    free: string[];
+    skipped: CastSkipped[];
+};
+/**
+ * Where an announcement can play right now, in one call: every speaker and display that is free, a whole group where all
+ * of it is, and never a TV. `castFree` over everything Cast has found, with `forms: ["speaker", "display"]`; `free` goes
+ * straight to `announceAll`.
+ */
+export declare const castFreeSpeakers: (s: CastSnapshot) => {
     free: string[];
     skipped: CastSkipped[];
 };

package/dist/connectors/cast/state.js

@@ -216,8 +216,18 @@ export function castStatus(s) {
  *   becomes its free members, named one by one (they then play out of step with each other).
  * - A device is never named beside a free group that holds it, nor two groups that share a member: the second becomes its
  *   members not yet covered.
+ * - With `forms` (`["speaker", "display"]` keeps an announcement off TVs), a device of another form, or of a model this
+ *   library doesn't know, is skipped with `why: "form"`, and a group holding one (or a member the snapshot doesn't have)
+ *   becomes its other free members. An empty list leaves every device out.
  */
-export function castFree(s, targets) {
+export function castFree(s, targets, options = {}) {
+    /** A device of a form asked for. A group has no form of its own: its members decide. */
+    const wanted = (id) => {
+        const d = s.devices[id];
+        if (!options.forms || d?.kind === "group")
+            return true;
+        return d?.form !== undefined && options.forms.includes(d.form);
+    };
     const status = new Map(castStatus(s).map((c) => [c.id, c]));
     const free = new Map();
     const covered = new Set(); // members of the groups in `free`
@@ -225,14 +235,16 @@ export function castFree(s, targets) {
     const ok = (c) => (c.state === "idle" || c.state === "restorable") && !c.standby;
     const skip = (c) => skipped.set(c.id, {
         name: c.name,
-        why: c.state === "offline"
-            ? "offline"
-            : c.standby && c.state !== "busy"
-                ? "standby"
-                : "busy",
+        why: !wanted(c.id)
+            ? "form"
+            : c.state === "offline"
+                ? "offline"
+                : c.standby && c.state !== "busy"
+                    ? "standby"
+                    : "busy",
         ...(c.app ? { app: c.app } : {}),
     });
-    const device = (c) => (ok(c) ? free.set(c.id, c) : skip(c));
+    const device = (c) => ok(c) && wanted(c.id) ? free.set(c.id, c) : skip(c);
     for (const target of targets) {
         const d = findCast(s.devices, target);
         const c = d && status.get(d.id);
@@ -248,6 +260,7 @@ export function castFree(s, targets) {
                 skip(c);
             else if (own !== "offline" &&
                 up.every(ok) &&
+                (d.members ?? []).every(wanted) &&
                 !members.some((m) => covered.has(m.id))) {
                 free.set(c.id, c);
                 for (const m of members)
@@ -265,3 +278,9 @@ export function castFree(s, targets) {
         skipped: [...skipped.values()],
     };
 }
+/**
+ * Where an announcement can play right now, in one call: every speaker and display that is free, a whole group where all
+ * of it is, and never a TV. `castFree` over everything Cast has found, with `forms: ["speaker", "display"]`; `free` goes
+ * straight to `announceAll`.
+ */
+export const castFreeSpeakers = (s) => castFree(s, castDevices(s).map((d) => d.id), { forms: ["speaker", "display"] });

package/dist/connectors/daikin/client.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { Clock } from "../../clock.ts";
+import { type Clock } from "../../clock.ts";
 import { ConnectorError } from "../../connector.ts";
 /** A failed Daikin call. `status` is the HTTP status, or the dsiot `rsc` when HTTP succeeded. */
 export declare class DaikinError extends ConnectorError {
@@ -23,6 +23,41 @@ type Node = {
     pch?: Node[];
 };
 declare const Node: z.ZodType<Node>;
+/**
+ * The setpoint a mode gets when the caller names none: this library's opinion (KO's: not too cold, properly warm).
+ * Without one, "cool" would mean whatever the remote last left. Auto keeps the unit's own.
+ */
+export declare const DEFAULT_TARGET_C: {
+    readonly cool: 25;
+    readonly heat: 27;
+};
+/**
+ * What a write left: the state once the unit reported the change (`confirmed`), or as it stood when `CONFIRM_MS` ran out
+ * without it. With `{ dryRun: true }` nothing is sent: `wouldSend` is the request and what it sets, `state` the unit as it
+ * reads now, and `confirmed` is false. Check `wouldSend` first.
+ */
+export type DaikinApplied = {
+    state: DaikinState;
+    confirmed: boolean;
+    wouldSend?: DaikinRequest;
+};
+/** One write: `POST /dsiot/multireq` with `body`; `sets` is what it changes, in this library's words. */
+export type DaikinRequest = {
+    method: "POST";
+    path: "/dsiot/multireq";
+    body: WriteRequest;
+    sets: {
+        on?: boolean;
+        mode?: Mode;
+        targetC?: number;
+    };
+};
+/** `dryRun`: every check a write makes (the mode, the setpoint's range), one read for the state, and nothing sent. */
+export type DaikinWriteOptions = {
+    dryRun?: boolean;
+};
+/** How long `power` and `mode` wait for the unit to report what was asked, reading once a second. */
+export declare const CONFIRM_MS = 5000;
 /** Little-endian hex to an integer, two's complement when `signed`: "2700" → 39, "EEFF" → -18. */
 export declare function hexLE(hex: string, signed?: boolean): number | undefined;
 /** Map the indoor and outdoor `dgc_status` trees to a state. Unknown codes go to `anomaly`, never to a guess. */
@@ -48,7 +83,7 @@ export declare const setMode: (mode: Mode) => WriteRequest;
 export declare function setTarget(c: number, mode: Mode): WriteRequest;
 /** Set the fan speed of `mode` (usually the current one). */
 export declare function setFan(fan: Fan, mode: Mode): WriteRequest;
-/** A client for one unit. Reads are op 2; `write` sends a body built by setPower, setMode, setTarget or setFan. */
+/** A client for one unit. Reads are op 2. `power` and `mode` are the writes most callers want; `write` sends any body built by setPower, setMode, setTarget or setFan. */
 export declare function daikinClient(options: {
     host: string;
     fetch: typeof fetch;
@@ -61,5 +96,13 @@ export declare function daikinClient(options: {
      * unconfirmed; re-read to be sure). Writes waiting their turn merge (`mergeWrites`) and resolve with the send that carried them.
      */
     write(request: WriteRequest): Promise<void>;
+    /** Turn the unit on or off, as it was last left. Only when a person asks. Resolves with what the unit then reported. */
+    power: (on: boolean, options?: DaikinWriteOptions) => Promise<DaikinApplied>;
+    /**
+     * Select a mode, turn the unit on and set its setpoint, in one request: `targetC`, else `DEFAULT_TARGET_C` (cool 25,
+     * heat 27), else (auto) the unit's own. Dry and fan take none, and a `targetC` for them throws before anything is
+     * sent, as one off the unit's range does. Only when a person asks. Resolves with what the unit then reported.
+     */
+    mode(mode: Mode, targetC?: number, options?: DaikinWriteOptions): Promise<DaikinApplied>;
 };
 export {};

package/dist/connectors/daikin/client.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { realClock } from "../../clock.js";
 import { ConnectorError, getJson } from "../../connector.js";
 import { writeLane } from "../../lane.js";
 // Daikin's JSON dsiot API (the BRP084 family): POST /dsiot/multireq, plain HTTP, no key. Field paths and value
@@ -56,6 +57,16 @@ const TARGET_RANGE = {
     heat: [10, 30],
     auto: [18, 30],
 };
+/**
+ * The setpoint a mode gets when the caller names none: this library's opinion (KO's: not too cold, properly warm).
+ * Without one, "cool" would mean whatever the remote last left. Auto keeps the unit's own.
+ */
+export const DEFAULT_TARGET_C = {
+    cool: 25,
+    heat: 27,
+};
+/** How long `power` and `mode` wait for the unit to report what was asked, reading once a second. */
+export const CONFIRM_MS = 5000;
 /** Little-endian hex to an integer, two's complement when `signed`: "2700" → 39, "EEFF" → -18. */
 export function hexLE(hex, signed = false) {
     if (!/^(?:[0-9a-f]{2})+$/i.test(hex))
@@ -173,7 +184,7 @@ export function setFan(fan, mode) {
         throw new DaikinError(`${mode} mode has no fan speed`);
     return write([["e_3001", FAN[mode], key(FANS, fan)]]);
 }
-/** A client for one unit. Reads are op 2; `write` sends a body built by setPower, setMode, setTarget or setFan. */
+/** A client for one unit. Reads are op 2. `power` and `mode` are the writes most callers want; `write` sends any body built by setPower, setMode, setTarget or setFan. */
 export function daikinClient(options) {
     const lane = writeLane({
         gapMs: WRITE_GAP_MS,
@@ -190,7 +201,8 @@ export function daikinClient(options) {
         schema: Multi,
         error: DaikinError,
     });
-    return {
+    const clock = options.clock ?? realClock;
+    const client = {
         /** The indoor and outdoor status in one request. A failed outdoor read leaves `outsideC` empty. */
         async read(signal) {
             const m = await multireq({
@@ -218,4 +230,57 @@ export function daikinClient(options) {
             }, mergeWrites);
         },
     };
+    /** Send `request`, then read once a second until the unit reports `asked` or `CONFIRM_MS` passes. Rejects if the write is refused, or if no read after it succeeds. */
+    async function apply(request, sets, asked, options) {
+        if (options?.dryRun)
+            return {
+                state: await client.read(),
+                confirmed: false,
+                wouldSend: {
+                    method: "POST",
+                    path: "/dsiot/multireq",
+                    body: request,
+                    sets,
+                },
+            };
+        await client.write(request);
+        const until = clock.now() + CONFIRM_MS;
+        let state;
+        let failed;
+        // The write was accepted, so one dropped read must not turn it into a failure: keep reading until the time is up.
+        for (;;) {
+            try {
+                state = await client.read();
+                if (asked(state))
+                    break;
+            }
+            catch (error) {
+                failed = error;
+            }
+            if (clock.now() >= until)
+                break;
+            await clock.sleep(1000);
+        }
+        if (!state)
+            throw failed; // sent, but the unit answered no read since: nothing to report
+        return { state, confirmed: asked(state) };
+    }
+    return {
+        ...client,
+        /** Turn the unit on or off, as it was last left. Only when a person asks. Resolves with what the unit then reported. */
+        power: (on, options) => apply(setPower(on), { on }, (s) => s.on === on, options),
+        /**
+         * Select a mode, turn the unit on and set its setpoint, in one request: `targetC`, else `DEFAULT_TARGET_C` (cool 25,
+         * heat 27), else (auto) the unit's own. Dry and fan take none, and a `targetC` for them throws before anything is
+         * sent, as one off the unit's range does. Only when a person asks. Resolves with what the unit then reported.
+         */
+        async mode(mode, targetC, options) {
+            const c = targetC ?? DEFAULT_TARGET_C[mode];
+            return apply(c === undefined
+                ? setMode(mode)
+                : mergeWrites(setMode(mode), setTarget(c, mode)), { on: true, mode, ...(c === undefined ? {} : { targetC: c }) }, (s) => s.on === true &&
+                s.mode === mode &&
+                (c === undefined || s.targetC === c), options);
+        },
+    };
 }

package/dist/connectors/daikin/index.d.ts

@@ -4,7 +4,7 @@ import { type DeviceRecord, type Integration, type Part } from "../../home.ts";
 import { type Finder } from "../../discover.ts";
 import type { Manifest } from "../../manifest.ts";
 import { daikinClient, type DaikinState, type Mode } from "./client.ts";
-export { DaikinError, type DaikinState, daikinClient, type Fan, type Mode, setFan, setMode, setPower, setTarget, type WriteRequest, } from "./client.ts";
+export { CONFIRM_MS, type DaikinApplied, type DaikinRequest, type DaikinWriteOptions, DaikinError, type DaikinState, DEFAULT_TARGET_C, daikinClient, type Fan, type Mode, setFan, setMode, setPower, setTarget, type WriteRequest, } from "./client.ts";
 /** Poll every 120 s, as Home Assistant's daikin integration does (its coordinator's update_interval). */
 export declare const POLL_MS = 120000;
 /** A Daikin AC in a home config: its last known address, and the MAC its UDP discovery reports, which is how it is recognised. */
@@ -30,7 +30,7 @@ export type DaikinSnapshot = DaikinState & {
 /** What `daikin().client` is: the reads and writes of the unit, at wherever it is now. */
 export type DaikinClient = ReturnType<typeof daikinClient>;
 /**
- * One Daikin AC as a home integration: one read now, then every 120 s. Its writes are `client.write(setPower(true))`: one
+ * One Daikin AC as a home integration: one read now, then every 120 s. Its writes are `client.power(on)` and `client.mode(mode, targetC?)`: one
  * client for the integration's life, so the writes share its lane and follow the unit when it moves.
  */
 export declare function daikin(config: DaikinConfig): Integration<DaikinSnapshot, "daikin"> & {

package/dist/connectors/daikin/index.js

@@ -4,7 +4,7 @@ import { deviceRecords, } from "../../home.js";
 import { lostDetail, relocator } from "../../discover.js";
 import { poller } from "../../poll.js";
 import { daikinClient, DaikinError, } from "./client.js";
-export { DaikinError, daikinClient, setFan, setMode, setPower, setTarget, } from "./client.js";
+export { CONFIRM_MS, DaikinError, DEFAULT_TARGET_C, daikinClient, setFan, setMode, setPower, setTarget, } from "./client.js";
 /** Poll every 120 s, as Home Assistant's daikin integration does (its coordinator's update_interval). */
 export const POLL_MS = 120_000;
 /** A Daikin AC in a home config: its last known address, and the MAC its UDP discovery reports, which is how it is recognised. */
@@ -17,7 +17,7 @@ export const configSchema = z.looseObject({
         .describe("the unit's MAC as its UDP discovery reports it: its identity"),
 });
 /**
- * One Daikin AC as a home integration: one read now, then every 120 s. Its writes are `client.write(setPower(true))`: one
+ * One Daikin AC as a home integration: one read now, then every 120 s. Its writes are `client.power(on)` and `client.mode(mode, targetC?)`: one
  * client for the integration's life, so the writes share its lane and follow the unit when it moves.
  */
 export function daikin(config) {
@@ -102,7 +102,8 @@ export const manifest = {
         {
             name: "DAIKIN_HOST",
             example: "192.0.2.20",
-            what: "the unit's address; `home probe` finds it by UDP broadcast",
+            optional: true,
+            what: "the unit's address; found by UDP broadcast when unset (1.5 s a run)",
         },
     ],
     lines: ({ state }) => (state ? [acText(state)] : []),

package/dist/connectors/enphase/client.d.ts

@@ -1,5 +1,5 @@
 import { ConnectorError } from "../../connector.ts";
-/** A failed Enphase call. `status` 401 means the token is wrong or expired. */
+/** A failed Enphase call. `status` 401 or 403 (`isRejectedKey`) means the token is wrong or expired. */
 export declare class EnphaseError extends ConnectorError {
 }
 /** Solar right now and today. Watts and watt-hours as the gateway reports them, negatives included. */

package/dist/connectors/enphase/client.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { ConnectorError, fetchTimeout, getJson } from "../../connector.js";
 import { Login, Meters, Production, Readings, } from "./schemas.js";
-/** A failed Enphase call. `status` 401 means the token is wrong or expired. */
+/** A failed Enphase call. `status` 401 or 403 (`isRejectedKey`) means the token is wrong or expired. */
 export class EnphaseError extends ConnectorError {
 }
 /** A daily counter equal to the lifetime one is the software 8 bug seen on KO's gateway (D8.3.5528): not today's energy. */

package/dist/connectors/enphase/index.js

@@ -1,4 +1,5 @@
 import { localDay, realClock } from "../../clock.js";
+import { isRejectedKey } from "../../connector.js";
 import { z } from "zod";
 import { deviceRecords, filePath, } from "../../home.js";
 import { lostDetail, relocator } from "../../discover.js";
@@ -113,7 +114,7 @@ export function enphase(config) {
                 catch (error) {
                     if (signal.aborted)
                         return; // stopped mid-read: not a failure
-                    if (error instanceof EnphaseError && error.status === 401)
+                    if (isRejectedKey(error))
                         return update({
                             status: "unavailable",
                             reason: "auth",

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

@@ -0,0 +1,2 @@
+/** Signify's root certificates for Hue bridges (PEM, two certificates): the default `ca` everywhere one is taken. */
+export declare const HUE_BRIDGE_ROOT_CA = "-----BEGIN CERTIFICATE-----\nMIICMjCCAdigAwIBAgIUO7FSLbaxikuXAljzVaurLXWmFw4wCgYIKoZIzj0EAwIw\nOTELMAkGA1UEBhMCTkwxFDASBgNVBAoMC1BoaWxpcHMgSHVlMRQwEgYDVQQDDAty\nb290LWJyaWRnZTAiGA8yMDE3MDEwMTAwMDAwMFoYDzIwMzgwMTE5MDMxNDA3WjA5\nMQswCQYDVQQGEwJOTDEUMBIGA1UECgwLUGhpbGlwcyBIdWUxFDASBgNVBAMMC3Jv\nb3QtYnJpZGdlMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEjNw2tx2AplOf9x86\naTdvEcL1FU65QDxziKvBpW9XXSIcibAeQiKxegpq8Exbr9v6LBnYbna2VcaK0G22\njOKkTqOBuTCBtjAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNV\nHQ4EFgQUZ2ONTFrDT6o8ItRnKfqWKnHFGmQwdAYDVR0jBG0wa4AUZ2ONTFrDT6o8\nItRnKfqWKnHFGmShPaQ7MDkxCzAJBgNVBAYTAk5MMRQwEgYDVQQKDAtQaGlsaXBz\nIEh1ZTEUMBIGA1UEAwwLcm9vdC1icmlkZ2WCFDuxUi22sYpLlwJY81Wrqy11phcO\nMAoGCCqGSM49BAMCA0gAMEUCIEBYYEOsa07TH7E5MJnGw557lVkORgit2Rm1h3B2\nsFgDAiEA1Fj/C3AN5psFMjo0//mrQebo0eKd3aWRx+pQY08mk48=\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIBzDCCAXOgAwIBAgICEAAwCgYIKoZIzj0EAwIwPDELMAkGA1UEBhMCTkwxFDAS\nBgNVBAoMC1NpZ25pZnkgSHVlMRcwFQYDVQQDDA5IdWUgUm9vdCBDQSAwMTAgFw0y\nNTAyMjUwMDAwMDBaGA8yMDUwMTIzMTIzNTk1OVowPDELMAkGA1UEBhMCTkwxFDAS\nBgNVBAoMC1NpZ25pZnkgSHVlMRcwFQYDVQQDDA5IdWUgUm9vdCBDQSAwMTBZMBMG\nByqGSM49AgEGCCqGSM49AwEHA0IABFfOO0jfSAUXGQ9kjEDzyBrcMQ3ItyA5krE+\ncyvb1Y3xFti7KlAad8UOnAx0FBLn7HZrlmIwm1QnX0fK3LPM13mjYzBhMB0GA1Ud\nDgQWBBTF1pSpsCASX/z0VHLigxU2CAaqoTAfBgNVHSMEGDAWgBTF1pSpsCASX/z0\nVHLigxU2CAaqoTAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBBjAKBggq\nhkjOPQQDAgNHADBEAiAk7duT+IHbOGO4UUuGLAEpyYejGZK9Z7V9oSfnvuQ5BQIg\nIYSgwwxHXm73/JgcU9lAM6c8Bmu3UE3kBIUwBs1qXFw=\n-----END CERTIFICATE-----\n";