@khalido/home 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,9 +1,65 @@
 # 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.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.
+
+### Added
+
+- **spotify:** `activate()`, and `home spotify activate`.
+- **cast:** `announceAll(targets, clip, options)`, one result per device, and repeated `--to` on `home cast announce` (`--json` is an array with several).
+- **cast:** `form` on a device whose model it knows (`speaker`, `display`, `tv`, from `castForm(model)`), so "all speakers" can skip TVs. The address cache keeps the model; a cached device without one goes through discovery once.
+- **up:** the integration has `client`, for a consumer's writes.
+
+### Changed
+
+- **spotify:** `setVolume` while the speaker isn't the active device rejects with code `inactive`, instead of `confirmed: false`: Soloist accepts it and drops it. `duck` then runs `fn` with `music: "untouched"`.
+- **spotify:** `play` while inactive goes active first.
+- **spotify:** the `track` event waits for the track's name.
+- **cast:** a clip that doesn't start playing fails after 15 s (or `timeoutMs`), naming its type. An error the receiver reports sooner gives its reason, and its code if it has one.
+
+### Fixed
+
+- **spotify:** `maxVolume` waits until the speaker is active, retries until Soloist reports the lower volume, and says "lowered it" only then; if it never shows, `detail` says so. It said "lowered it" at 56 with a cap of 40. The window also opens when the speaker goes active.
+- **spotify:** `setRepeat("off")` from `track` stayed on `track`: the two commands now go 600 ms apart.
+- **spotify:** a volume within 1 of the request confirms, since Soloist rounds it.
+- **spotify:** a stall repair can run again when a track comes back after another.
+- **`home cast announce`** exits 1 when a clip didn't play.
+
 ## [0.1.1] - 2026-11-09
 
 Fixes from chota-bot's first live reads, on a Raspberry Pi and a Mac. No breaking changes.
@@ -42,6 +98,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.1...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,7 @@ 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.
 
 ## Try it
 
@@ -50,17 +50,17 @@ The library never reads your environment or a file: you pass addresses, keys and
 
 ## Connectors
 
-| Connector                                     | Reads                                                                                                 | Writes                                                                                                                                                                                                                    |
-| --------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [hue](src/connectors/hue/README.md)           | lights, rooms, scenes, over the bridge's event stream                                                 | lights, rooms, scenes                                                                                                                                                                                                     |
-| [daikin](src/connectors/daikin/README.md)     | the AC, over its local API                                                                            | power, mode, setpoint, fan                                                                                                                                                                                                |
-| [enphase](src/connectors/enphase/README.md)   | solar production and consumption from the IQ Gateway                                                  | none                                                                                                                                                                                                                      |
-| [cast](src/connectors/cast/README.md)         | every Cast device and speaker group                                                                   | volume, mute, stop, announcements                                                                                                                                                                                         |
-| [printers](src/connectors/printers/README.md) | AirPrint printers over IPP: state, toner, paper                                                       | none                                                                                                                                                                                                                      |
-| [spotify](src/connectors/spotify/README.md)   | a Spotify Soloist speaker: what is playing, volume, shuffle, over its local WebSocket                 | play a link, pause, resume, skip, seek, volume (capped), queue, shuffle, repeat, each confirmed by what the speaker reports; turn down or pause around an announcement; a stalled stream noticed and, if asked, restarted |
-| [amber](src/connectors/amber/README.md)       | live import and feed-in prices                                                                        | none                                                                                                                                                                                                                      |
-| [up](src/connectors/up/README.md)             | household spending by category, what still needs one                                                  | a category or tag on a transaction                                                                                                                                                                                        |
-| [weather](src/connectors/weather/README.md)   | now, forecast by the hour and by part of the day, rain soon, the sun, from BOM, Open-Meteo and Google | none                                                                                                                                                                                                                      |
+| Connector                                     | Reads                                                                                                 | Writes                                                                                                                                                                                                                              |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [hue](src/connectors/hue/README.md)           | lights, rooms, scenes, over the bridge's event stream                                                 | lights, rooms, scenes                                                                                                                                                                                                               |
+| [daikin](src/connectors/daikin/README.md)     | the AC, over its local API                                                                            | power, mode, setpoint, fan                                                                                                                                                                                                          |
+| [enphase](src/connectors/enphase/README.md)   | solar production and consumption from the IQ Gateway                                                  | none                                                                                                                                                                                                                                |
+| [cast](src/connectors/cast/README.md)         | every Cast device and speaker group                                                                   | volume, mute, stop, announcements                                                                                                                                                                                                   |
+| [printers](src/connectors/printers/README.md) | AirPrint printers over IPP: state, toner, paper                                                       | none                                                                                                                                                                                                                                |
+| [spotify](src/connectors/spotify/README.md)   | a Spotify Soloist speaker: what is playing, volume, shuffle, over its local WebSocket                 | activate, play a link, pause, resume, skip, seek, volume (capped), queue, shuffle, repeat, each confirmed by what the speaker reports; turn down or pause around an announcement; a stalled stream noticed and, if asked, restarted |
+| [amber](src/connectors/amber/README.md)       | live import and feed-in prices                                                                        | none                                                                                                                                                                                                                                |
+| [up](src/connectors/up/README.md)             | household spending by category, what still needs one                                                  | a category or tag on a transaction                                                                                                                                                                                                  |
+| [weather](src/connectors/weather/README.md)   | now, forecast by the hour and by part of the day, rain soon, the sun, from BOM, Open-Meteo and Google | none                                                                                                                                                                                                                                |
 
 Each connector's README says what has run against a real device and what has not. This covers only the devices I own; [Home Assistant](https://www.home-assistant.io/) is the inspiration and the reference for every protocol.
 

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.js

@@ -331,7 +331,9 @@ export function loadHome(input, options) {
                 {
                     castId: x.castId,
                     name: x.name,
-                    ...(c?.port === undefined ? {} : { host: c.host, port: c.port }),
+                    ...(c?.port === undefined
+                        ? {}
+                        : { host: c.host, port: c.port, model: c.model }),
                 },
             ];
         });

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,13 +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 type { CastDevice, CastSnapshot, Resolved } from "./state.ts";
+export { castDevices, castForm, castFree, 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<{
@@ -30,6 +31,7 @@ export type CastConfig = {
     expect?: {
         castId: string;
         name: string;
+        model?: string;
         host?: string;
         port?: number;
     }[];
@@ -38,6 +40,7 @@ export type CastConfig = {
         host: string;
         port: number;
         name?: string;
+        model?: string;
     }) => void;
     clock?: Clock;
     /** Heartbeat interval; a socket silent for three of them is dropped. */
@@ -55,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,10 +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 { castDevices, castForm, castFree, 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"),
@@ -205,6 +207,7 @@ export function cast(config) {
                 host: d.host,
                 port: d.port,
                 name: named.has(id) ? d.name : undefined,
+                model: d.model,
             }); // a config's name never reaches the cache
             publish();
             void (async () => {
@@ -359,10 +362,14 @@ export function cast(config) {
             report = update;
             running = signal;
             const expect = config.expect ?? [];
-            const cached = expect.filter((e) => e.host !== undefined && e.port !== undefined);
+            // A device with no model (a cache from before 0.1.2) goes through discovery once, or it would never get a `form`.
+            const cached = expect.filter((e) => e.host !== undefined &&
+                e.port !== undefined &&
+                (e.port !== 8009 || e.model !== undefined));
             snapshot = found(snapshot, cached.map((e) => ({
                 id: e.castId,
                 name: e.name,
+                model: e.model,
                 host: e.host,
                 port: e.port,
                 group: e.port !== 8009,
@@ -405,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/schemas.d.ts

@@ -41,6 +41,7 @@ export declare const MediaStatus: z.ZodObject<{
         mediaSessionId: z.ZodOptional<z.ZodNumber>;
         playerState: z.ZodOptional<z.ZodString>;
         idleReason: z.ZodOptional<z.ZodString>;
+        detailedErrorCode: z.ZodOptional<z.ZodNumber>;
         currentTime: z.ZodOptional<z.ZodNumber>;
         media: z.ZodOptional<z.ZodObject<{
             contentId: z.ZodOptional<z.ZodString>;
@@ -118,6 +119,7 @@ export declare const CastPayload: z.ZodDiscriminatedUnion<[z.ZodObject<{
         mediaSessionId: z.ZodOptional<z.ZodNumber>;
         playerState: z.ZodOptional<z.ZodString>;
         idleReason: z.ZodOptional<z.ZodString>;
+        detailedErrorCode: z.ZodOptional<z.ZodNumber>;
         currentTime: z.ZodOptional<z.ZodNumber>;
         media: z.ZodOptional<z.ZodObject<{
             contentId: z.ZodOptional<z.ZodString>;

package/dist/connectors/cast/schemas.js

@@ -36,6 +36,7 @@ export const MediaStatus = z.looseObject({
         mediaSessionId: z.number().optional(),
         playerState: z.string().optional(), // "PLAYING" | "PAUSED" | "BUFFERING" | "IDLE"
         idleReason: z.string().optional(), // "FINISHED" | "CANCELLED" | "INTERRUPTED" | "ERROR"
+        detailedErrorCode: z.number().optional(),
         currentTime: z.number().optional(), // seconds into the media
         media: z
             .looseObject({

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

@@ -1,4 +1,7 @@
 import type { CastPayload } from "./schemas.ts";
+/** What a device is for, read from its model name; a model it doesn't know has none. A group is `kind: "group"`. */
+export type CastForm = "speaker" | "display" | "tv";
+export declare function castForm(model?: string): CastForm | undefined;
 /** A Cast device or group as found by discovery: what `resolve` returns for each. */
 export type Resolved = {
     id: string;
@@ -16,6 +19,7 @@ export type CastDevice = {
     id: string;
     name: string;
     model?: string;
+    form?: CastForm;
     kind: "device" | "group";
     host?: string;
     port?: number;
@@ -60,3 +64,55 @@ 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. */
+export type CastSkipped = {
+    name: string;
+    why: "busy" | "offline" | "standby" | "unknown";
+    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.
+ */
+export declare function castFree(s: CastSnapshot, targets: string[]): {
+    free: string[];
+    skipped: CastSkipped[];
+};

package/dist/connectors/cast/state.js

@@ -1,3 +1,14 @@
+export function castForm(model) {
+    if (!model)
+        return undefined;
+    if (/hub|tablet|display/i.test(model))
+        return "display";
+    if (/audio|speaker|mini|google home/i.test(model))
+        return "speaker";
+    if (/chromecast|streamer|\btv\b/i.test(model))
+        return "tv";
+    return undefined;
+}
 /** An id as the snapshot keys it: the mDNS id (32 hex) and the certificate's and multizone's dashed UUID are one key. */
 export const castKey = (id) => id.toLowerCase().replace(/-/g, "");
 /** Add or update what discovery found; devices it did not find this time are kept as they were. */
@@ -11,6 +22,7 @@ export function found(s, entries, asOf) {
             id,
             name: e.name,
             model: e.model,
+            form: kind === "device" ? castForm(e.model) : undefined,
             kind,
             host: e.host,
             port: e.port,
@@ -131,3 +143,125 @@ 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.
+ */
+export function castFree(s, targets) {
+    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: 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));
+    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) &&
+                !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()],
+    };
+}

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

@@ -1,11 +1,11 @@
 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. */
 export declare const PLAY_MS = 60000;
+/** How long a clip gets to start playing. A clip a speaker can't play took 35–44 s to say so (live, 2026-11-09); good ones start within a few seconds. A stated guess. */
+export declare const START_MS = 15000;
 /** Level writes, and mute writes, per device or group in any minute; more wait their turn, the newest winning. A guess: Cast publishes no limit. */
 export declare const VOLUME_PER_MINUTE = 30;
 /** What to play: a URL the device can fetch (type defaults to audio/mpeg), or bytes for `serve` to put on the LAN. */
@@ -44,6 +44,13 @@ export type CastActions = {
         volume?: number;
         timeoutMs?: number;
     }): Promise<AnnounceResult>;
+    /** `announce` to several targets at once, one result per device, in the order given. A target that can't be reached is its own `played: false`. A group and one of its own members are not told apart. */
+    announceAll(targets: string[], clip: CastClip, options?: {
+        volume?: number;
+        timeoutMs?: number;
+    }): Promise<(AnnounceResult & {
+        target: string;
+    })[]>;
 };
 /** A payload as it came, before any schema. */
 export type RawPayload = {