@khalido/home 0.1.1 → 0.1.3

package/src/cli/status.ts

@@ -116,6 +116,7 @@ async function statusFromEnv(
       try {
         return [await from.build()];
       } catch (error) {
+        const code = error instanceof CliError ? error.code : undefined;
         const fix =
           error instanceof CliError && error.fix
             ? ` (run \`${error.fix}\`)`
@@ -123,6 +124,13 @@ async function statusFromEnv(
         rows[m.name] = {
           status: "unavailable",
           needs,
+          // A build reads settings and files, so a failure is config unless it was a key (auth) or the network (nothing to fix here).
+          reason:
+            code === "auth"
+              ? "auth"
+              : code === "network"
+                ? undefined
+                : "config",
           detail: `${(error as Error).message}${fix}`,
         };
         return [];
@@ -136,6 +144,18 @@ async function statusFromEnv(
   return rows;
 }
 
+/** The config with only this connector's devices, and the weather only for `home weather`, so `home amber` doesn't need Up's key. A malformed one passes through for `loadHome` to report. */
+function narrowed(input: unknown, only: string): unknown {
+  const config = input as { devices?: unknown } | null;
+  if (!Array.isArray(config?.devices)) return input;
+  const { location, weather, ...rest } = config as Record<string, unknown>;
+  return {
+    ...rest,
+    ...(only === "weather" ? { location, weather } : {}),
+    devices: config.devices.filter((d) => d?.connector === only),
+  };
+}
+
 /** The rows from a config: its integrations (or the one named) run until each has answered (weather: every source), at most 15 s. */
 async function statusFromConfig(
   path: string,
@@ -150,9 +170,11 @@ async function statusFromConfig(
     cache: addresses.cache,
     configAt: statSync(path).mtimeMs,
   };
-  const all = loadHome(readConfig(path), options);
-  const integrations =
-    only === undefined ? all : all.filter((i) => i.name === only);
+  const input = readConfig(path);
+  const integrations = loadHome(
+    only === undefined ? input : narrowed(input, only),
+    options,
+  );
   if (!integrations.length) fail(`no ${only} in ${path}`);
   return Object.fromEntries(
     Object.entries(await settle(integrations)).map(([name, p]) => [
@@ -170,6 +192,7 @@ function rowRecord(name: string, r: Row): Record<string, unknown> {
     needs: r.needs,
     access: m?.access ?? "",
     detail: r.detail,
+    reason: r.reason,
     anomaly: r.anomaly,
     ...(m?.record && r.state ? m.record(r as Part) : (r.state as object)),
   };

package/src/clock.ts

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

package/src/config.ts

@@ -509,7 +509,9 @@ export function loadHome(
         {
           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/src/connector.ts

@@ -17,13 +17,29 @@ export function errorText(error: unknown): string {
     : error.message;
 }
 
+/**
+ * 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 class ConnectorError extends Error {
   readonly status?: number;
-  readonly code?: string;
+  readonly code?: ConnectorCode;
   constructor(
     message: string,
-    options: { status?: number; code?: string; cause?: unknown } = {},
+    options: { status?: number; code?: ConnectorCode; cause?: unknown } = {},
   ) {
     super(
       message,

package/src/connectors/amber/index.ts

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

package/src/connectors/cast/README.md

@@ -1,6 +1,6 @@
 # Google Cast
 
-Nest speakers, Nest Hubs, Chromecasts, Google TV and speaker groups, read over CastV2 on the local network. `iot_class`: **local_push** (one socket per device or group, status pushed, a PING every 5 s). The integration only reads; the writes (volume, mute, stop, announcements) are calls on the same object, never made by the integration itself, and so far tried only on a scripted fake socket. The design and what comes next (casting a page) are in [docs/cast.md](../../../docs/cast.md).
+Nest speakers, Nest Hubs, Chromecasts, Google TV and speaker groups, read over CastV2 on the local network. `iot_class`: **local_push** (one socket per device or group, status pushed, a PING every 5 s). The integration only reads; the writes (volume, mute, stop, announcements) are calls on the same object, never made by the integration itself, and announcements, volume and mute have run on real devices (2026-11-09 and 2026-11-10, below); `stop` and `announceAll` only on a scripted fake socket. The design and what comes next (casting a page) are in [docs/cast.md](../../../docs/cast.md).
 
 ## Built
 
@@ -8,12 +8,14 @@ Nest speakers, Nest Hubs, Chromecasts, Google TV and speaker groups, read over C
 - Per socket: `CONNECT` to `receiver-0`, receiver `GET_STATUS`, multizone `GET_STATUS` (a group's members; on a device's own port, the device alone, by its current name), then whatever the device pushes. A running app with the media namespace gets a `CONNECT` and media `GET_STATUS` on its `transportId`, as Home Assistant does. A device's `PING` is answered with `PONG`; a socket silent for three heartbeats (15 s), or without a receiver status 10 s after connecting, is closed and the detail says which.
 - A dropped socket reconnects with backoff (1 s doubling to 60 s) at whatever address discovery last gave. The drop starts one shared `resolve()` at once (a group's address changes with its leader); while anything stays down or missing, that one discovery repeats at 1, 5 and 15 minutes, then hourly, as the relocator does, never once per socket. `refresh()` re-asks every open socket and nudges the discovery, which also finds devices when nothing was found at start.
 - The part is `connecting` until every device has answered or failed, then `connected` while any is up; `detail` names the ones down. A payload of a known type the schema rejects is an `anomaly`, never thrown.
-- State (`CastSnapshot`, by mDNS id): app, `idle` (no app, or Backdrop's `isIdleScreen`), `standby`, volume (unrounded), muted, `volumeControl`, player state, title, artist; groups carry `members` and `leader`; devices carry `groups`, and `playingVia` when they show a playing group's media because their own is empty (Home Assistant's model, not yet seen live).
+- State (`CastSnapshot`, by mDNS id): `form` (`speaker`, `display` or `tv`, from `castForm(model)`; none for a model it doesn't know; the address cache keeps the model), app, `idle` (no app, or Backdrop's `isIdleScreen`), `standby`, volume (unrounded), muted, `volumeControl`, player state, title, artist; groups carry `members` and `leader`; devices carry `groups`, and `playingVia` when they show a playing group's media because their own is empty (Home Assistant's model, not yet seen live).
 - Names: a device's `name` in the snapshot is its own, from discovery's `fn` or its own multizone status (the same text on all six live devices, 2026-10-13), so a rename in the Google Home app shows once the device answers, even when every address came from the cache and discovery never ran; the config's name is only the placeholder until then. A group's multizone status lists its members, not itself, so a group's new name shows at the next discovery.
+- `castStatus(snapshot)`: what each device and group is doing, for a caller choosing where to play something. `state` is `idle`, `restorable` (the Default Media Receiver, which `announce` puts back), `busy` (another app, playing or paused: an announce ends it) or `offline` (not connected, or not heard from yet); with the app, title, artist, volume, `via` (the group whose media a member is playing), `standby`, and a group's `members`. A group is as free as its least free connected member.
+- `castFree(snapshot, targets)`: the targets an announcement would not disturb, as names for `announceAll`, and `skipped` with why (`busy`, `offline`, `standby`, `unknown`). A TV in standby is skipped, since a clip may wake it. A group stays a group while every connected member is free; one playing another app is skipped whole; otherwise a group with a busy member becomes its free members one by one (they then play out of step). A device is never named beside a free group that holds it. Both functions are pure, over the snapshot, and tested on built snapshots only: what a group's members report while it plays Spotify hasn't been checked live.
 - Writes, on the object `cast()` returns (`CastActions`), over the sockets it already holds, never a second connection. A target is a name (any case) or a castId; volume is 0 to 1, as the snapshot's. `setVolume`, `setMuted` (receiver `SET_VOLUME`; a group's goes to the group's socket; per device, levels and mutes each at most 30 a minute, the newest waiting one winning; one device's lane never waits on another's) and `stop` (receiver `STOP` of the running app; nothing when idle). Each request waits 10 s for its reply and a refusal (`LAUNCH_ERROR`, `LOAD_FAILED`, …) rejects, naming it.
-- `announce(target, clip, { volume?, timeoutMs? })`: `clip` is `{ url, type? }` or `{ bytes, type }`, bytes served through `serve` (`serveClip` from `@khalido/home/cast/serve`, passed to `cast()`). It reads the receiver status (and a Default Media Receiver's media status), for a group re-runs discovery first and reconnects if the leader moved, sets the volume if given and unmutes a muted target (as two requests: a `SET_VOLUME` takes a level or a mute, not both), launches the Default Media Receiver (`CC1AD845`), `LOAD`s the clip and waits for its media session to go `IDLE` with `FINISHED` (60 s plus the clip's length when the device reports it, or `timeoutMs`). Then, always: what the Default Media Receiver was playing is loaded again at its `currentTime`, an idle device gets `STOP`, then the volume and mute (a group's member by member, through each member's own socket, from the group's multizone status). Another app (Spotify, YouTube) is interrupted, as Google's own announcements do, and the result names it in `notRestored`. It returns `{ played, why?, restored, notRestored }` and throws only before anything changed (an unknown target, a socket down).
+- `announce(target, clip, { volume?, timeoutMs? })`: `clip` is `{ url, type? }` or `{ bytes, type }`, bytes served through `serve` (`serveClip` from `@khalido/home/cast/serve`, passed to `cast()`). It reads the receiver status (and a Default Media Receiver's media status), for a group re-runs discovery first and reconnects if the leader moved, sets the volume if given and unmutes a muted target (as two requests: a `SET_VOLUME` takes a level or a mute, not both), launches the Default Media Receiver (`CC1AD845`), `LOAD`s the clip and waits for its media session to go `IDLE` with `FINISHED` (60 s plus the clip's length when the device reports it, or `timeoutMs`). Then, always: what the Default Media Receiver was playing is loaded again at its `currentTime`, an idle device gets `STOP`, then the volume and mute (a group's its own level first, then member by member, through each member's own socket, from the group's multizone status). Another app (Spotify, YouTube) is interrupted, as Google's own announcements do, and the result names it in `notRestored`. It returns `{ played, why?, restored, notRestored }` and throws only before anything changed (an unknown target, a socket down). A clip gets 15 s to reach `PLAYING`, then the name of its type goes in the failure, since a device that can't play it took 35-44 s to say so; a receiver error sooner carries its reason and code. `timeoutMs` replaces both waits. `announceAll(targets, clip, options)` does several at once, one result per device, an unreachable target its own `played: false`; a group and one of its members would clash, untried.
 - `serveClip(bytes, type, { host?, signal? })` (`node:http`, Node-only like `tls.ts`): an address of this machine on the target's network (else the first non-internal IPv4), a random port and an unguessable path, `Content-Type` and `Content-Length`; the whole body to every GET and HEAD (a `Range` probe gets a full 200, which HTTP allows), so a player that probes before it fetches still gets the clip. It closes on `close()`, which `announce` calls once the clip has played, when `signal` aborts, or after 60 s. Not yet seen live: how the Default Media Receiver fetches, and the macOS local-network prompt the first serve may raise.
-- CLI: `home cast announce --to <name> (--say "<text>" | --file <path>) [--volume 0-100]`, `home cast volume <name> <0-100>`, `home cast mute <name> on|off`, `home cast stop <name>`. `--say` runs `say -o <tmp>.m4a --file-format=m4af --data-format=aac` (without the data format, m4af holds uncompressed PCM), serves it as `audio/mp4` and deletes the file. The library never runs `say`.
+- CLI: `home cast announce --to <name> [--to <name>…] (--say "<text>" | --file <path>) [--volume 0-100]`, `home cast volume <name> <0-100>`, `home cast mute <name> on|off`, `home cast stop <name>`. `--say` runs `say -o <tmp>.m4a --file-format=m4af --data-format=aac` (without the data format, m4af holds uncompressed PCM), serves it as `audio/mp4` and deletes the file. The library never runs `say`.
 - Config: one entry per device or group, `{ "connector": "cast", "name": "…", "castId": "…" }`, all folded into one `cast` integration; `home discover --write` fills them and refreshes a renamed entry's `name` (the same `castId` with a new `fn`), printed as `renamed`. No host: discovery gives every address.
 
 ## Protocol
@@ -27,7 +29,10 @@ CastV2 is TLS to port 8009 (a group: its own port), carrying length-prefixed pro
 - **Receiver status**: hubs and the Chromecast Ultra run Backdrop (`E8C28D3C`) with `isIdleScreen: true`; the speakers report no application; the TV Streamer reports `isStandBy: true`, `isActiveInput: false` and a `fixed` volume; the Ultra's volume is `attenuation`.
 - No device sent a `PING` in 12 s of listening, so our 5 s ping is what keeps the socket's silence check honest.
 - Media status first seen live 2026-11-09 (Bun 1.4.4): a paused title and artist on a TV.
-- Not seen yet: a group playing, a leader change, member changes, and Node's `tls` (no Node caller yet).
+- **First announcements, 2026-11-09, from a Pi on 0.1.1.** MP3 played on two audio-only speakers and two displays, 7-8 s each, the clip fetched from the Pi's LAN address, idle and volume restored. A 24 kHz mono WAV played on the displays and failed on both audio-only speakers, "the clip stopped: ERROR" after 35-44 s. One WAV format tried: use MP3 or AAC.
+- **On 0.1.2, 2026-11-10, from the Pi (Bun 1.4.4; chota-bot's session, KO listening).** MP3 at volume 30 on one audio-only speaker: played and restored in 2 s. To a group of four: played in 9.5 s, each member back at its own level. `setVolume` and `setMuted` on one speaker read back as set. Over Spotify playing on the speaker: played, the volume restored, Spotify listed in `notRestored`, and KO had to pick the speaker again in the Spotify app.
+- **A group's own level was not restored** (same run; fixed after 0.1.2, untried live): after the group announce at 30 the group read 30 (it had been 53) though every member was back; setting the group to 53 afterwards did not move the members. `restoreVolume` restored members only; since fixed: the group's own level goes back first, then each member's. Untried live.
+- Not seen yet: `stop`, an announce over a Default Media Receiver stream, `announceAll`, a leader change, member changes, and Node's `tls` (no Node caller yet).
 
 ## TLS: verification off, the name checked
 

package/src/connectors/cast/index.ts

@@ -3,7 +3,13 @@ import { asOf, type Clock, realClock } from "../../clock.ts";
 import { errorText } from "../../connector.ts";
 import { type Found, HOUR, lostDetail, rescanDelay } from "../../discover.ts";
 import { poller } from "../../poll.ts";
-import type { Integration, Part, Status } from "../../home.ts";
+import {
+  type DeviceRecord,
+  deviceRecords,
+  type Integration,
+  type Part,
+  type Status,
+} from "../../home.ts";
 import type { Manifest } from "../../manifest.ts";
 import { type CastChannel, type CastConnect, NS } from "./codec.ts";
 import { CastPayload, KNOWN_TYPES } from "./schemas.ts";
@@ -16,6 +22,10 @@ import {
   mediaApp,
   reduce,
   type Resolved,
+  castDevices,
+  type CastForm,
+  type CastStatus,
+  castStatus,
 } from "./state.ts";
 import {
   type CastActions,
@@ -27,7 +37,15 @@ import {
 } 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,
@@ -77,11 +95,17 @@ export type CastConfig = {
    * `host` and `port` (an address cache) an entry connects at once; discovery runs only when an entry has none, or a
    * cached address fails. A cached port other than 8009 is a group's (devices always listen on 8009).
    */
-  expect?: { castId: string; name: string; host?: string; port?: number }[];
+  expect?: {
+    castId: string;
+    name: string;
+    model?: string;
+    host?: string;
+    port?: number;
+  }[];
   /** Each address that connected and passed the certificate check, for an address cache; again with the device's new name when it reports a rename. `name` is the device's own, never a config's. */
   seen?: (
     id: string,
-    address: { host: string; port: number; name?: string },
+    address: { host: string; port: number; name?: string; model?: string },
   ) => void;
   clock?: Clock;
   /** Heartbeat interval; a socket silent for three of them is dropped. */
@@ -304,6 +328,7 @@ export function cast(
         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 () => {
@@ -468,14 +493,19 @@ export function cast(
       report = update;
       running = signal;
       const expect = config.expect ?? [];
+      // 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) =>
+          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,
@@ -523,11 +553,46 @@ export function castText(d: CastDevice, s: CastSnapshot): string {
   return `${d.name}: ${parts.filter(Boolean).join(" · ")}`;
 }
 
-/** Devices first, then groups, each by name. */
-export const castDevices = (s: CastSnapshot) =>
-  Object.values(s.devices).sort(
-    (a, b) => a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name),
+/** 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 function castHomeDevices(
+  part: Part<CastSnapshot> | undefined,
+): CastHomeDevice[] {
+  const s = part?.state;
+  if (!s) return [];
+  return deviceRecords(
+    part,
+    castStatus(s).map((detail): CastHomeDevice => {
+      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: CastSnapshot) => ({

package/src/connectors/cast/schemas.ts

@@ -43,6 +43,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/src/connectors/cast/state.ts

@@ -1,5 +1,15 @@
 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 function castForm(model?: string): CastForm | undefined {
+  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;
+}
+
 /** A Cast device or group as found by discovery: what `resolve` returns for each. */
 export type Resolved = {
   id: string;
@@ -18,6 +28,7 @@ export type CastDevice = {
   id: string;
   name: string;
   model?: string;
+  form?: CastForm; // devices: speaker, display or tv, when the model is one it knows
   kind: "device" | "group";
   host?: string;
   port?: number;
@@ -63,6 +74,7 @@ export function found(
       id,
       name: e.name,
       model: e.model,
+      form: kind === "device" ? castForm(e.model) : undefined,
       kind,
       host: e.host,
       port: e.port,
@@ -201,3 +213,180 @@ function link(s: CastSnapshot): CastSnapshot {
     if (d.playingVia === undefined) 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: CastSnapshot) =>
+  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: Record<string, CastDevice>,
+  target: string,
+): CastDevice | undefined => {
+  const all = Object.values(devices);
+  return (
+    all.find((x) => x.id === castKey(target)) ??
+    all.find((x) => x.name.toLowerCase() === target.toLowerCase())
+  );
+};
+
+/**
+ * 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[]; // groups: each member the snapshot has
+};
+
+const RANK = { idle: 0, restorable: 1, busy: 2, offline: 3 } as const;
+
+/** By its own app alone: not its group's media, not its members. */
+const ownState = (d: CastDevice): CastStatus["state"] =>
+  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: CastSnapshot): CastStatus[] {
+  const one = (d: CastDevice): CastStatus => {
+    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: CastStatus = {
+      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) as (keyof CastStatus)[])
+      if (status[k] === undefined) delete status[k];
+    return status;
+  };
+  return castDevices(s).map(one);
+}
+
+/** 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 function castFree(
+  s: CastSnapshot,
+  targets: string[],
+): { free: string[]; skipped: CastSkipped[] } {
+  const status = new Map(castStatus(s).map((c) => [c.id, c]));
+  const free = new Map<string, CastStatus>();
+  const covered = new Set<string>(); // members of the groups in `free`
+  const skipped = new Map<string, CastSkipped>();
+  const ok = (c: CastStatus) =>
+    (c.state === "idle" || c.state === "restorable") && !c.standby;
+  const skip = (c: CastStatus) =>
+    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: CastStatus) => (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()],
+  };
+}