@khalido/home 0.1.2 → 0.1.3

package/docs/cli.md

@@ -26,7 +26,7 @@ home spotify activate | pause | play [link] | next | volume <0-100>  # the Soloi
 
 - **stdout is data, stderr everything else.** Notes such as "nothing to categorise" or "no webhooks" go to stderr, so `home … | jq` never sees them.
 - **Bun on PATH.** The command starts with `#!/usr/bin/env bun`. A non-login SSH shell may not have `~/.bun/bin` on its PATH: run `PATH="$HOME/.bun/bin:$PATH" home`.
-- **`--json` shapes.** `home --json` is one object keyed by connector, with `now` (`energyNow`) first. `home <connector> --json` is that connector's object: `status`, `needs`, `access`, `detail`, `anomaly`, then its state (the weather adds `line`, its text). Lists (`home up transactions`, `uncategorised`, `spend --by merchant`) are arrays, `[]` when empty.
+- **`--json` shapes.** `home --json` is one object keyed by connector, with `now` (`energyNow`) first. `home <connector> --json` is that connector's object: `status`, `needs`, `access`, `detail`, `reason` (why it is `unavailable`, when known: `auth`, `config` or `crashed`), `anomaly`, then its state (the weather adds `line`, its text). Lists (`home up transactions`, `uncategorised`, `spend --by merchant`) are arrays, `[]` when empty.
 - **Errors under `--json`** are one object on stderr: `{"error": "…", "code": "usage" | "auth" | "network" | "error", "fix": "home enphase login"}`; `fix` is there only when one command resolves it. In text: `home: <error> (run \`<fix>\`)`.
 - **Exit codes.** 0 success, empty results included. 1 a failure, and `home <connector>` when that connector is not `connected`, so a script can test one. 2 a wrong command, verb or argument. `home` alone lists every connector and exits 0 whatever their state.
 

package/docs/config.md

@@ -4,12 +4,17 @@ One JSONC file lays out the home, so the `home` command, jaldi and chota-bot rea
 
 ```ts
 import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { createHome, loadHome, parseJsonc } from "@khalido/home";
 import { ftpFetch } from "@khalido/home/weather/ftp";
 
 const path = "/path/to/home.jsonc";
-const readFile = (p: string) => readFileSync(resolve(dirname(path), p), "utf8"); // paths in the config are relative to it
+const readFile = (p: string) =>
+  readFileSync(
+    resolve(dirname(path), p.replace(/^~(?=\/)/, homedir())),
+    "utf8",
+  ); // relative to the config, or from ~/
 const home = createHome(
   loadHome(parseJsonc(readFileSync(path, "utf8")), {
     env: process.env,
@@ -22,12 +27,12 @@ const home = createHome(
 `loadHome` runs on Bun and Node. Hue and Enphase need a fetch that handles their certificates: Bun's `tls` fetch option by default, and under Node `tls: NODE_TLS` from `@khalido/home/node`. Under Node, a config with Hue or Enphase and no `tls` is a problem `loadHome` names, not a silent failure at the first read.
 
 - **A device entry is only how to reach it and where it is**: its identity (the Hue `bridgeId`, a Daikin's `mac`, the Enphase `serial`, a Cast `castId`), its last known `host`, a key's env name, a file's path, its `room`. What a device reports about itself (model, firmware) comes live; a note about it is a comment.
-- **Secrets are env variable names** (`"key": "AMBER_KEY"`), resolved against the `env` the caller passes; a pasted key fails the schema. Files (`ca`, `token`) are paths the caller reads, relative to the config; the library reads nothing.
+- **Secrets are env variable names** (`"key": "AMBER_KEY"`), resolved against the `env` the caller passes; a pasted key fails the schema. Files (`ca`, `token`) are paths the caller reads, relative to the config or from `~/`, which the caller expands (`home discover --write` writes Enphase's token as `~/.config/home/enphase-token.json`); the library reads nothing.
 - **Problems name the field**: an unknown connector, a missing env name or a device in a missing room is an error, never a skip. `checkHome` returns them all; `loadHome` throws them all. Unknown keys pass through for a consumer's own settings.
 - **One device per connector** for now (each integration is named by its connector), except printers (one entry each, by `uuid`) and Cast: one entry per device and speaker group (`name`, the Google Home name, and `castId`, the mDNS id), all read by one `cast` integration that finds every address by discovery, since a group's moves with its leader. A `spotify` entry is only its Soloist `url` (and `maxVolume`): a socket on the same machine, with nothing to discover.
 - **Identity, not address.** A device is recognised by the id its own discovery reports; `host` is a cache. `home discover` lists what answers (mDNS, Daikin's UDP broadcast), in two passes 5 s apart since both drop answers now and then: the first pass prints at once, the second only what it adds (`--passes 1` for a quick look; `--json` waits for both); with a config (`--config` or `HOME_CONFIG`) it then matches those against it by identity and prints new devices, moved addresses and conflicts (a different device at an entry's host). `home discover --write <file>` adds the new ones (each with an id no entry has), updates moved hosts and refreshes the `name` of a Cast entry renamed in the Google Home app through `jsonc-parser`'s edits, every comment and other line left as it was, and writes only a result that passes `checkPlan`. Nothing else writes the file; the library never does. Two devices with one id are a config problem.
 - **A device that moves is found again, without periodic scans**, when the caller passes `finders` to `loadHome` (`FINDERS` from `@khalido/home/finders`, Node-side like `weather/ftp`; the CLI does, and jaldi and chota-bot can). After three failed reads in a row (Hue: three failed reconnects of its event stream), Hue, Daikin and Enphase run their discovery (two passes, the second skipped when the first finds the device), switch to the address their identity now answers at and say "moved from a to b" in `detail` (persist it with `home discover --write`); otherwise they look again at 1, 5 and 15 minutes, then hourly for as long as reads fail, so a device back from the wall socket reads again without a restart. The detail says what discovery found ("not found by discovery", or "discovery finds it at its address but reads fail", or "discovery failed: …" when it could not run), and "no answer for a day" once a day has passed; the part stays `disconnected`, since `unavailable` is for a rejected key. `refresh()` resets the wait. Amber and the weather have no discovery and do not take part. Cast always needs `finders.cast`: discovery is how it finds every address.
-- **Discovery is rare: addresses are cached between runs.** `loadHome(config, { cache, configAt })` takes an `AddressCache` (`read()` and `write(entries)`, keyed by connector and identity, each entry `{ host, port?, name?, seenAt }`). A cached address newer than the config (`configAt`, the file's modified time) is tried first, a failure there scans at once rather than after three, and each address that answers is written back when it changed or predates the config, so a config edit is re-trusted at the first good read. Nothing evicts an entry but `home cache clear`: a device gone for good keeps its entry, and `home status` without a config, which reads every Cast entry from the cache, shows it as not found until then. The consumer persists it: the CLI keeps `$XDG_CACHE_HOME/home/addresses.json` (default `~/.cache/home/addresses.json`, 0600) through `fileCache` from `@khalido/home/finders`, written at the end of `status`, `probe` and `discover`; jaldi's sidecar and chota-bot pass `FINDERS` and their own cache the same way. The config's `host` stays the human-set fallback and `home discover --write` the way to change the config. `home status` from a Cast config: 0.33–0.44 s cold, 0.13 s with a warm cache, 1.4 s once when a cached address has gone stale (Bun 1.4.2, measured 2026-10-13).
+- **Discovery is rare: addresses are cached between runs.** `loadHome(config, { cache, configAt })` takes an `AddressCache` (`read()` and `write(entries)`, keyed by connector and identity, each entry `{ host, port?, name?, seenAt }`). A cached address newer than the config (`configAt`, the file's modified time) is tried first, a failure there scans at once rather than after three, and each address that answers is written back when it changed or predates the config, so a config edit is re-trusted at the first good read. Nothing evicts an entry but `home cache clear`: a device gone for good keeps its entry, and `home status` without a config, which reads every Cast entry from the cache, shows it as not found until then. The consumer persists it: the CLI keeps `$XDG_CACHE_HOME/home/addresses.json` (default `~/.cache/home/addresses.json`, 0600) through `fileCache` from `@khalido/home/finders`, written at the end of `status`, `probe` and `discover`; another consumer passes `FINDERS` and its own cache the same way. The config's `host` stays the human-set fallback and `home discover --write` the way to change the config. `home status` from a Cast config: 0.33–0.44 s cold, 0.13 s with a warm cache, 1.4 s once when a cached address has gone stale (Bun 1.4.2, measured 2026-10-13).
 - **Parsing** is through `jsonc-parser` (comments and trailing commas), on Bun and Node alike; a syntax error throws. `bun run schema` rewrites `home.schema.json` from the zod schema, and a test fails if they drift.
 - `createHome` stays for code-first use.
 

package/docs/decisions.md

@@ -149,3 +149,7 @@ KO's decisions on this package, newest block last. They override every other doc
 - **Stalls (Soloist issue #5) are noticed by default and repaired only when asked** (`repairStalls: true`): the repair is the library's first write nobody asked for, so a consumer opts in. Two signals, since the issue doesn't say whether the reported position freezes: a frozen position across fresh reports, and still playing well past the track's end, the symptom actually reported. One repair per track, never a loop. The nudges (seek, then pause and play; a skip past the end) are guesses until a stall is seen live.
 - **The project is home.ts; the npm package stays `@khalido/home`** (KO, 2026-11-08), so imports stay short (`@khalido/home/spotify`). It is home automation for TypeScript, starting with the devices in KO's house, and is meant to grow into more of the basics.
 - **Spotify: inactive is refused, and activating is the caller's choice** (KO, 2026-11-09). Soloist accepts and drops `set_volume` while it isn't the active device. `setVolume` refuses with code `inactive`, and `activate()` is separate, because activating makes a new stream and can jump the volume to the level last saved. `duck` runs `fn` anyway, with `music: "untouched"`, because the announcement matters more. `play` goes active itself, since someone asking for music wants it to start; `resume` doesn't, since it worked inactive. The `maxVolume` cap says "lowered" only once Soloist reports it.
+
+- **`Part.reason`, only on `unavailable`** (KO, 2026-11-09). An admin page had to match `detail` text like "pair again" to know a person must re-key. `reason` is `auth` (a key or token rejected or unusable), `config` (a setting or file is wrong) or `crashed` (a `run` threw), for code to switch on; `detail` stays the text for people. `disconnected` gets none: it already says unreachable. Additive, so a patch. `config` came a day later (KO, 2026-11-10), so "re-key", "fix a setting" and "report a bug" are three answers; `crashed` stays though nothing reads it yet. Weather has one too: each source says why it stopped (`stopReason`), the part is `auth` if any stopped source is, else `config`, and `state.sources.<name>.reason` shows a dead key while another source keeps the part `connected`.
+- **Google's key goes in the `X-Goog-Api-Key` header, not the URL** (KO, 2026-11-10), so nothing that prints a URL can print it. Its rejection is read from the error body: a bad key and a bad latitude are both HTTP 400, and only the key's carries `API_KEY_INVALID` (live, 2026-11-10).
+- **Every device answers the same few questions** (KO, 2026-11-10: "nice and consistent so we can easily and consistently add devices"). `DeviceRecord` is identity, availability, one word of state and one line of text, the same for a light, a speaker and a printer; `homeDevices(snapshot, config?)` lists them all. Everything particular to a kind stays in the connector's own typed row, carried as `detail`, so the common record never grows a field only one kind has. Three levels, each inside the last: the house list, the connector's typed row, the raw snapshot. Each connector exports its own typed function, listed by hand in `src/devices.ts`, and not a manifest field: `MANIFESTS` is untyped, and `detail` must narrow by `connector`. The list is read-only: a write means something different for a light, a speaker and an air conditioner, so there is no generic `turnOn`. Not done, for a 0.2.0: Hue's `reachable` becoming `available`, and its groups joining its lights in one call.

package/docs/using.md

@@ -37,6 +37,23 @@ health(home.snapshot(), Date.now()); // per integration: ok, stale or down, with
 
 `createHome` stamps each part with `lastGoodAt` (its last good read) and `downSince` (when it stopped being connected). `health` judges from those: a polling connector is stale after 2½ polls with no good read and down after 3 polls not connected; Hue and Cast are down after 2 minutes not connected. Health takes each connector's interval from its manifest; a home that changes one (the weather's `pollMinutes`) passes it: `health(snapshot, now, { pollSeconds: { weather: 60 * 60 } })`. For a one-shot read (a script, a printed brief), `settle(integrations, { ms })` runs them until each has answered and returns the snapshot.
 
+## Every device, the same way
+
+`homeDevices(home.snapshot(), config)` lists every device the home has: each Hue light, room and zone, the Daikin, the Enphase gateway, each Cast device and group, each printer and the Soloist speaker. Each answers the same questions in the same words: `connector`, `id`, `name`, `kind` (light, group, speaker, display, tv, ac, printer, solar; `cast` for a Cast model the library doesn't know), `available` (and when it is false, `reason`: `offline`, `auth`, `config` or `crashed`), `asOf` (when the device last reported or was last read; a quiet light can be hours old and current), `state` (one word: on, off, idle, busy, cool, printing), `text` (one line for people), `room` and, for a group, `members`. A field the device hasn't reported is absent. The config is optional: with it a device takes its entry's `room`, and a device with no name of its own (the Daikin, the gateway) its entry's `name`; a device's own name is never replaced. While a connector isn't connected none of its devices is `available`, and each keeps its last values.
+
+To drill down, `detail` is the connector's own typed row, and `connector` (with `kind` for Hue) tells TypeScript which:
+
+```ts
+for (const d of homeDevices(home.snapshot(), config)) {
+  console.log(d.text); // "Kitchen: on · 60%"
+  if (d.connector === "cast") d.detail.volume; // CastStatus
+  if (d.connector === "hue" && d.kind === "light") d.detail.brightness; // LightView
+  if (d.connector === "printers") d.detail.markers; // Printer
+}
+```
+
+Below that is the connector's snapshot, exactly as the device sent it (`home.part("hue")?.state`). One connector alone: `castHomeDevices(home.part("cast"))`, and likewise `hueHomeDevices`, `daikinHomeDevices`, `enphaseHomeDevices`, `printersHomeDevices`, `spotifyHomeDevices`. The list is for reading; a write goes to the device's connector, with `d.id` where it takes one.
+
 ## Writes
 
 Writes hang off the integration: `home.integration("daikin")?.client.write(setMode("cool"))`, `home.integration("hue")?.client.recallScene(id)`, `home.integration("cast")?.setVolume(…)`, `home.integration("spotify")?.play(link)`. Each goes through the device's write lane: spaced, and a burst to one light or the AC merges so the last value lands. Spotify's writes resolve with `{ state, confirmed }`, the state once Soloist reported the change, and `duck(fn, { to })` and `interrupt(fn)` turn the music down or pause it around an announcement, returning what happened to it (`music`: `untouched`, `restored`, `kept` or `failed`). `speakerState(part)` says the speaker in one word (offline, waiting, idle, playing, paused) and `spotifyChanges(change.before, change.after)` turns an `onChange` into events (started, resumed, paused, stopped, track, stalled, recovered, offline, waiting, picked), those from the library's own `duck` or `interrupt` marked `own`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khalido/home",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "home.ts: small, typed home automation for TypeScript: Hue, Daikin, Enphase, Google Cast, AirPrint printers and a Spotify Soloist speaker on the local network; Amber prices, Up Bank spending and the weather from the cloud.",
   "license": "MIT",
   "author": "Khalid Omar",

package/skills/use-home/SKILL.md

@@ -29,13 +29,13 @@ The contract (in `docs/cli.md`): stdout is data, stderr everything else. `--json
 
 What a status means:
 
-| Status         | Meaning                                                                            | What to do                                        |
-| -------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------- |
-| `connected`    | read and current                                                                   | use it                                            |
-| `connecting`   | still starting (a 15 s cap in the CLI)                                             | wait, or run again                                |
-| `disconnected` | the device or service did not answer; the last good state is kept, with its `asOf` | say so; check the device is on and at its address |
-| `unavailable`  | stopped for good: a key rejected, a setting wrong                                  | the `detail` names it; fix the key or setting     |
-| `not set up`   | env names or a file missing (`needs` lists them)                                   | set them, or say what is needed                   |
+| Status         | Meaning                                                                                                                                                         | What to do                                        |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `connected`    | read and current                                                                                                                                                | use it                                            |
+| `connecting`   | still starting (a 15 s cap in the CLI)                                                                                                                          | wait, or run again                                |
+| `disconnected` | the device or service did not answer; the last good state is kept, with its `asOf`                                                                              | say so; check the device is on and at its address |
+| `unavailable`  | stopped for good: a key rejected, a setting wrong; `reason`, when present, is `auth` (a person must re-key), `config` (a setting or file is wrong) or `crashed` | the `detail` names it; fix the key or setting     |
+| `not set up`   | env names or a file missing (`needs` lists them)                                                                                                                | set them, or say what is needed                   |
 
 Weather: `blocks` holds morning, afternoon and evening for today and tomorrow in the home's time zone; `rainSoon` says when rain starts in the next two hours (needs the Google key). Energy: `now` in `home --json` is the one owner of solar, use, grid flow and cost per hour; never recompute it.
 

package/src/cli/enphase.ts

@@ -23,7 +23,11 @@ export function enphaseToken(): { token: string; expiresAt: Date } | undefined {
     const { token } = JSON.parse(text) as { token: string };
     return { token, expiresAt: tokenExpiry(token) };
   } catch (error) {
-    return fail(`${TOKEN_FILE}: ${(error as Error).message}`);
+    return fail(
+      `${TOKEN_FILE}: ${(error as Error).message}`,
+      "auth",
+      "home enphase login",
+    );
   }
 }
 

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/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
 
@@ -10,8 +10,10 @@ Nest speakers, Nest Hubs, Chromecasts, Google TV and speaker groups, read over C
 - 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): `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). 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.
+- `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> [--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.
@@ -28,7 +30,9 @@ CastV2 is TLS to port 8009 (a group: its own port), carrying length-prefixed pro
 - 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.
 - **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.
-- Not seen yet: a group playing, a leader change, member changes, and Node's `tls` (no Node caller yet).
+- **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,8 +37,15 @@ import {
 } 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, castStatus } from "./state.ts";
+export type {
+  CastDevice,
+  CastForm,
+  CastSkipped,
+  CastSnapshot,
+  CastStatus,
+  Resolved,
+} from "./state.ts";
 export type {
   AnnounceResult,
   CastActions,
@@ -536,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/state.ts

@@ -213,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()],
+  };
+}