@khalido/home 0.1.2 → 0.2.0

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

@@ -1,9 +1,80 @@
 # Changelog
 
-All notable changes to home.ts (`@khalido/home` on npm), in [Keep a Changelog](https://keepachangelog.com/) form. Versions follow [SemVer](https://semver.org) at 0.x: a minor release can break what a consumer calls, a patch can't.
+All notable changes to home.ts (`@khalido/home` on npm), in [Keep a Changelog](https://keepachangelog.com/) form. Versions follow [SemVer](https://semver.org) at 0.x: a minor release can break what a consumer calls, a patch can't. A release that breaks something opens with a **Breaking** heading, so a consumer on `latest` sees it first.
 
 ## [Unreleased]
 
+## [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 Front room 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
+
+- **`Part.reason`:** why a part is `unavailable`, for code to switch on: `auth` (a key or token was rejected or unusable, so a person must re-key), `config` (a setting or file is wrong) or `crashed` (its `run` threw). `health()` and `home --json` carry it. It can be absent. Hue, Enphase, Amber and Up set `auth` on a rejected key, and so does an Enphase token that does not parse. In `home status`, a connector that fails to build from the environment says `auth` or `config`.
+- **`homeDevices(snapshot, config?)`:** every device in one list (Amber, Up and the weather read services and list nothing), each answering the same questions (`connector`, `id`, `name`, `kind`, `available`, `reason`, `asOf`, `state`, `text`, `room`, `members`), with the connector's own typed row in `detail` and `connector` narrowing its type. Each device connector also exports its own: `hueHomeDevices`, `daikinHomeDevices`, `enphaseHomeDevices`, `castHomeDevices`, `printersHomeDevices`, `spotifyHomeDevices`. `DeviceRecord` is the common shape and `deviceRecords(part, records)` what a connector returns them through: while its part isn't connected, none is `available`.
+- **`ConnectorCode`:** the type of `ConnectorError.code`, every code the library sets, so a consumer's table of messages fails to compile when one is added.
+- **cast:** `castStatus(snapshot)` says what each device and group is doing (`idle`, `restorable`, `busy` or `offline`, with the app, title and volume), and `castFree(snapshot, targets)` gives the targets an announcement would not disturb, with the ones it `skipped` and why. For announcing only where nothing is playing.
+- **weather:** `reason` on an `unavailable` weather part (`auth` if a stopped source's key was rejected, else `config`), and `state.sources.<name>.reason` beside `stopped`, so code can see a dead Google key while another source keeps the part `connected`. A custom `WeatherSource` can return `stopReason` with `stop`.
+
+### Changed
+
+- **`ConnectorError.code`** is typed `ConnectorCode`, no longer `string`. Reading it is unchanged. Only code that builds a `ConnectorError` with a code outside that set stops compiling; chota-bot and jaldi don't.
+- **hue:** a room or zone the bridge gives no on or off for prints its name alone in `home hue`, no longer "off".
+- **weather:** Google's key is sent in the `X-Goog-Api-Key` header, no longer in the URL.
+- **weather:** Google's stop text says which it was: `google: the key was rejected (HTTP 400 API_KEY_INVALID)` or `google: the request was refused (HTTP 400); check the latitude and longitude`. Before, both read `google: key rejected or request refused (HTTP 400)`.
+
+### Fixed
+
+- **cast:** `announce` to a group with a `volume` left the group's own level at the announcement's, though every member's was put back. The group's is now restored too, before its members', so theirs land last.
+- **spotify:** `interrupt` paused the music when the account was playing on another speaker (the box reports `playing` while not the active device). It now leaves it alone and returns `music: "untouched"`, as `duck` does.
+- **spotify:** `maxVolume` gave up when a lowering was refused or unanswered after a second start signal (buffering, then playing) had opened a new window, leaving the volume above the cap. The new window now lowers again.
+- **`createHome`:** an `onChange` that throws or rejects no longer marks the integration `unavailable`; the error goes to `console.error` and the integration keeps running.
+- **`createHome`:** `refresh()` before `start()` resolves at once instead of never.
+- **`createHome`:** an integration whose `run` fails after a good report keeps its last `state`.
+- **`createHome`:** a `run` that throws synchronously marks that integration `unavailable`; the others still start.
+- **`home <connector> --config`** needs only that connector's keys, and runs only that connector.
+- **`realClock.sleep`** resolves at once on an already-aborted signal.
+- **Docs:** the `readFile` in `docs/config.md` expands `~/`, which `home discover --write` puts in Enphase's `token`. The README says the package is ESM only.
+
 ## [0.1.2] - 2026-11-09
 
 From chota-bot's live writes on a Raspberry Pi. `setVolume` on an inactive speaker now rejects, and `track` events can come later than before.
@@ -68,7 +139,8 @@ 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.2...HEAD
+[Unreleased]: https://github.com/khalido/home.ts/compare/v0.1.3...HEAD
+[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
 [0.1.0]: https://github.com/khalido/home.ts/releases/tag/v0.1.0

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+. 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/clock.js

@@ -2,6 +2,8 @@
 export const realClock = {
     now: () => Date.now(),
     sleep: (ms, signal) => new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
         const done = () => (clearTimeout(timer),
             signal?.removeEventListener("abort", done),
             resolve());

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

@@ -6,13 +6,20 @@ export declare const TIMEOUT_MS = 10000;
  * Node's fetch puts the reason there: "fetch failed: connect ECONNREFUSED 192.0.2.10:443".
  */
 export declare function errorText(error: unknown): string;
+/**
+ * Every `code` a `ConnectorError` from this library carries, so a consumer's table of messages fails to compile when one is added.
+ * The spotify connector's writes: `offline` (not connected), `waiting` (nobody signed in), `inactive` (not the active device), `refused`
+ * (the device said no), `timeout` (no answer), `invalid` (bad input, nothing sent). `link_button`: Hue wants its button
+ * pressed. `ipp`: a printer answered with an IPP error, its code in `status`.
+ */
+export type ConnectorCode = "offline" | "waiting" | "inactive" | "refused" | "timeout" | "invalid" | "link_button" | "ipp";
 /** A failed device or service call. `status` is the HTTP status (or a device's own code); `code` a connector's own reason. */
 export declare class ConnectorError extends Error {
     readonly status?: number;
-    readonly code?: string;
+    readonly code?: ConnectorCode;
     constructor(message: string, options?: {
         status?: number;
-        code?: string;
+        code?: ConnectorCode;
         cause?: unknown;
     });
 }

package/dist/connectors/amber/index.js

@@ -44,6 +44,7 @@ export function amber(config) {
                     if (error instanceof AmberError && error.status === 401)
                         return update({
                             status: "unavailable",
+                            reason: "auth",
                             detail: "Amber rejected the key",
                             state: last,
                         });

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

@@ -1,14 +1,14 @@
 import { z } from "zod";
 import { type Clock } from "../../clock.ts";
 import { type Found } from "../../discover.ts";
-import type { Integration } from "../../home.ts";
+import { type DeviceRecord, type Integration, type Part } from "../../home.ts";
 import type { Manifest } from "../../manifest.ts";
 import { type CastConnect } from "./codec.ts";
-import { type CastDevice, type CastSnapshot, type Resolved } from "./state.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 { castForm } from "./state.ts";
-export type { CastDevice, CastForm, CastSnapshot, Resolved } 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. */
 export declare const configSchema: z.ZodObject<{
@@ -58,6 +58,8 @@ export type CastConfig = {
 export declare function cast(config: CastConfig): Integration<CastSnapshot, "cast"> & CastActions;
 /** One Cast device or group in a few words: "Nest Hub: idle · 47%", "Group: idle · 43% · 3 members: A, B, C, led by A". */
 export declare function castText(d: CastDevice, s: CastSnapshot): string;
-/** Devices first, then groups, each by name. */
-export declare const castDevices: (s: CastSnapshot) => CastDevice[];
+/** A Cast device or group as a home device: `kind` is its form (`cast` for a model it doesn't know) or `group`; `detail` its `CastStatus`. */
+export type CastHomeDevice = DeviceRecord<"cast", CastForm | "cast" | "group", CastStatus["state"], CastStatus>;
+/** Every Cast device and group as a home device, devices first, each by name. */
+export declare function castHomeDevices(part: Part<CastSnapshot> | undefined): CastHomeDevice[];
 export declare const manifest: Manifest<CastSnapshot>;

package/dist/connectors/cast/index.js

@@ -3,11 +3,12 @@ import { asOf, realClock } from "../../clock.js";
 import { errorText } from "../../connector.js";
 import { HOUR, lostDetail, rescanDelay } from "../../discover.js";
 import { poller } from "../../poll.js";
+import { deviceRecords, } from "../../home.js";
 import { NS } from "./codec.js";
 import { CastPayload, KNOWN_TYPES } from "./schemas.js";
-import { castKey, connection, found, mediaApp, reduce, } from "./state.js";
+import { castKey, connection, found, mediaApp, reduce, castDevices, castStatus, } from "./state.js";
 import { castActions, } from "./writes.js";
-export { castForm } 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"),
@@ -411,8 +412,33 @@ export function castText(d, s) {
     ];
     return `${d.name}: ${parts.filter(Boolean).join(" · ")}`;
 }
-/** Devices first, then groups, each by name. */
-export const castDevices = (s) => Object.values(s.devices).sort((a, b) => a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name));
+/** Every Cast device and group as a home device, devices first, each by name. */
+export function castHomeDevices(part) {
+    const s = part?.state;
+    if (!s)
+        return [];
+    return deviceRecords(part, castStatus(s).map((detail) => {
+        const d = s.devices[detail.id];
+        // Connected and heard from: available. Connecting, or connected with no status yet: not known.
+        const available = d.status === "disconnected"
+            ? false
+            : d.status === "connected" && detail.state !== "offline"
+                ? true
+                : undefined;
+        return {
+            connector: "cast",
+            id: d.id,
+            name: d.name,
+            kind: d.kind === "group" ? "group" : (d.form ?? "cast"),
+            ...(available === undefined ? {} : { available }),
+            ...(d.asOf ? { asOf: d.asOf } : {}), // never answered: no time to give
+            state: detail.state,
+            text: castText(d, s),
+            ...(d.members ? { members: d.members } : {}),
+            detail,
+        };
+    }));
+}
 /** How many entries have an address, and one line per device and group. */
 const castView = (s) => ({
     found: Object.values(s.devices).filter((d) => d.host).length,

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

@@ -64,3 +64,69 @@ export declare const mediaApp: (app?: {
     }[];
     transportId?: string;
 }) => boolean;
+/** Google's own player for a URL of audio or video: what `announce` plays a clip with, and can put back. */
+export declare const DEFAULT_MEDIA_RECEIVER = "CC1AD845";
+/** Devices first, then groups, each by name. */
+export declare const castDevices: (s: CastSnapshot) => CastDevice[];
+/** A target is a castId, else a name in any case. `announce` and `castFree` find it the same way. */
+export declare const findCast: (devices: Record<string, CastDevice>, target: string) => CastDevice | undefined;
+/**
+ * What a device or group is doing, for a caller choosing where to play something. `state`:
+ * - `idle`: no app, or the idle screen.
+ * - `restorable`: the Default Media Receiver, whose clip `announce` puts back at its position.
+ * - `busy`: another app, playing or paused. An announce ends it and nothing here can resume it.
+ * - `offline`: not connected, or connected and not heard from yet.
+ * A member playing its group's media takes the group's state, with `via` naming the group and `app` the group's. A group
+ * is as free as its least free connected member. `standby` is a TV that is off or on another input: `idle` by its app,
+ * but a clip may wake it.
+ */
+export type CastStatus = {
+    id: string;
+    name: string;
+    kind: "device" | "group";
+    state: "idle" | "restorable" | "busy" | "offline";
+    app?: string;
+    playerState?: string;
+    title?: string;
+    artist?: string;
+    via?: string;
+    volume?: number;
+    muted?: boolean;
+    standby?: boolean;
+    members?: 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; `form` is one whose form wasn't asked for. */
+export type CastSkipped = {
+    name: string;
+    why: "busy" | "offline" | "standby" | "unknown" | "form";
+    app?: string;
+};
+/**
+ * Of these targets (names in any case, or ids), the ones an announcement would not disturb: `idle` or `restorable`, and
+ * not a TV in standby. `free` is names, for `announceAll`; `skipped` says which were left out and why.
+ * - A group stays a group while every connected member is free. An offline member doesn't split it: the group plays without it.
+ * - A group playing another app is skipped whole. Otherwise a group with a busy member, or one whose own socket is down,
+ *   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[], 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

@@ -143,3 +143,144 @@ function link(s) {
             delete d.playingVia;
     return { devices, asOf: s.asOf };
 }
+/** Google's own player for a URL of audio or video: what `announce` plays a clip with, and can put back. */
+export const DEFAULT_MEDIA_RECEIVER = "CC1AD845";
+/** Devices first, then groups, each by name. */
+export const castDevices = (s) => Object.values(s.devices).sort((a, b) => a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name));
+/** A target is a castId, else a name in any case. `announce` and `castFree` find it the same way. */
+export const findCast = (devices, target) => {
+    const all = Object.values(devices);
+    return (all.find((x) => x.id === castKey(target)) ??
+        all.find((x) => x.name.toLowerCase() === target.toLowerCase()));
+};
+const RANK = { idle: 0, restorable: 1, busy: 2, offline: 3 };
+/** By its own app alone: not its group's media, not its members. */
+const ownState = (d) => d.status !== "connected" || d.idle === undefined
+    ? "offline"
+    : d.idle
+        ? "idle"
+        : d.appId === DEFAULT_MEDIA_RECEIVER
+            ? "restorable"
+            : "busy";
+/** Every device and group in the snapshot as a `CastStatus`, devices first, each by name. */
+export function castStatus(s) {
+    const one = (d) => {
+        const group = d.playingVia ? s.devices[d.playingVia] : undefined;
+        const own = ownState(d);
+        // Its group's media is playing on it: the group's app decides, and an unknown one counts as busy.
+        const self = own === "offline" || !d.playingVia
+            ? own
+            : group && ownState(group) === "restorable"
+                ? "restorable"
+                : "busy";
+        const members = d.kind === "group"
+            ? (d.members ?? []).flatMap((id) => s.devices[id] ? [one(s.devices[id])] : [])
+            : undefined;
+        const state = self === "offline"
+            ? self
+            : (members ?? [])
+                .map((m) => m.state)
+                .filter((m) => m !== "offline")
+                .reduce((a, b) => (RANK[b] > RANK[a] ? b : a), self);
+        const status = {
+            id: d.id,
+            name: d.name,
+            kind: d.kind,
+            state,
+            app: d.idle === false
+                ? d.app
+                : group?.idle === false
+                    ? group.app
+                    : undefined,
+            playerState: d.playerState,
+            title: d.title,
+            artist: d.artist,
+            via: d.playingVia && (group?.name ?? d.playingVia),
+            volume: d.volume,
+            muted: d.muted,
+            standby: d.standby,
+            members,
+        };
+        for (const k of Object.keys(status))
+            if (status[k] === undefined)
+                delete status[k];
+        return status;
+    };
+    return castDevices(s).map(one);
+}
+/**
+ * Of these targets (names in any case, or ids), the ones an announcement would not disturb: `idle` or `restorable`, and
+ * not a TV in standby. `free` is names, for `announceAll`; `skipped` says which were left out and why.
+ * - A group stays a group while every connected member is free. An offline member doesn't split it: the group plays without it.
+ * - A group playing another app is skipped whole. Otherwise a group with a busy member, or one whose own socket is down,
+ *   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, 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`
+    const skipped = new Map();
+    const ok = (c) => (c.state === "idle" || c.state === "restorable") && !c.standby;
+    const skip = (c) => skipped.set(c.id, {
+        name: c.name,
+        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) && 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);
+        if (!d || !c)
+            skipped.set(target, { name: target, why: "unknown" });
+        else if (c.kind === "device")
+            device(c);
+        else {
+            const members = c.members ?? [];
+            const own = ownState(d);
+            const up = members.filter((m) => m.state !== "offline");
+            if (own === "busy" || (own === "offline" && !members.length))
+                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)
+                    covered.add(m.id);
+            }
+            else
+                for (const m of members)
+                    device(m);
+        }
+    }
+    return {
+        free: [...free.values()]
+            .filter((c) => c.kind === "group" || !covered.has(c.id))
+            .map((c) => c.name),
+        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/cast/writes.d.ts

@@ -1,7 +1,5 @@
 import type { Clock } from "../../clock.ts";
 import { type CastDevice } from "./state.ts";
-/** Google's own player for a URL of audio or video. */
-export declare const DEFAULT_MEDIA_RECEIVER = "CC1AD845";
 /** Each request (a status, a volume, LAUNCH, LOAD, STOP) gets this long to answer. */
 export declare const ANSWER_MS = 10000;
 /** How long an announcement waits for its clip to finish, beyond the clip's own length when the device reports it. */

package/dist/connectors/cast/writes.js

@@ -2,11 +2,9 @@ import { errorText } from "../../connector.js";
 import { writeLane } from "../../lane.js";
 import { NS } from "./codec.js";
 import { MediaStatus, MultizoneStatus, ReceiverStatus, } from "./schemas.js";
-import { castKey } from "./state.js";
+import { castKey, DEFAULT_MEDIA_RECEIVER, findCast, } from "./state.js";
 // Writes over the sockets `cast()` already holds: volume, mute, stop, and an announcement that plays a clip and puts
-// the device back as it was. Never called by the integration itself; tried on a scripted fake socket, not yet live.
-/** Google's own player for a URL of audio or video. */
-export const DEFAULT_MEDIA_RECEIVER = "CC1AD845";
+// the device back as it was. Never called by the integration itself; announce, volume and mute have run on real devices (the README has the dates).
 /** Each request (a status, a volume, LAUNCH, LOAD, STOP) gets this long to answer. */
 export const ANSWER_MS = 10_000;
 /** How long an announcement waits for its clip to finish, beyond the clip's own length when the device reports it. */
@@ -83,8 +81,7 @@ export function castActions(ctx) {
     const { clock } = ctx;
     const find = (target) => {
         const all = Object.values(ctx.devices());
-        const d = all.find((x) => x.id === castKey(target)) ??
-            all.find((x) => x.name.toLowerCase() === target.toLowerCase());
+        const d = findCast(ctx.devices(), target);
         if (!d)
             throw new Error(`no Cast device or group "${target}"; have: ${all
                 .map((x) => x.name)
@@ -244,7 +241,7 @@ export function castActions(ctx) {
         /**
          * Read the target's state, set the volume if asked and unmute a muted target, launch the Default Media Receiver, play the clip to its end, then
          * put back what it can, always: what the Default Media Receiver was playing is loaded again where it was, an idle
-         * device gets STOP, then the volume (a group's, member by member through each member's own socket). Another app
+         * device gets STOP, then the volume (a group's own first, then member by member through each member's own socket). Another app
          * (Spotify, YouTube) is interrupted and cannot be resumed from here; the result says so. Throws only before anything changed.
          */
         async announce(target, clip, options = {}) {
@@ -360,6 +357,27 @@ export function castActions(ctx) {
                             muted: before.volume?.muted,
                         },
                     ];
+                // A group keeps a level of its own, which its members' levels don't bring back (live, 2026-11-10: it stayed at the
+                // announcement's 30 with every member restored). First, so whatever it does to the members, their own levels land last.
+                if (d.kind === "group" && options.volume !== undefined) {
+                    const level = before.volume?.level;
+                    if (level === undefined)
+                        result.notRestored.push({
+                            name: d.name,
+                            why: "its volume before was not reported",
+                        });
+                    else
+                        try {
+                            await receiver(s, { type: "SET_VOLUME", volume: { level } });
+                            result.restored.push(`${d.name}: volume`);
+                        }
+                        catch (error) {
+                            result.notRestored.push({
+                                name: d.name,
+                                why: `volume not restored: ${errorText(error)}`,
+                            });
+                        }
+                }
                 for (const m of each) {
                     const ms = m.id === d.id ? s : ctx.session(m.id);
                     if (m.level === undefined)