@khalido/home 0.1.3 → 0.2.0

package/src/cli/hue.ts

@@ -1,16 +1,20 @@
-// `home lights off`, `home room`, `home scene`, `home pair` (also as `home hue <verb>`): one write to the bridge each.
+// `home lights off`, `home light`, `home room`, `home scene`, `home pair` (also as `home hue <verb>`): one write to the bridge each,
+// then what the bridge reports. The name lookups and the checks are the library's (`client.light`, `room`, `scene`).
 import { readFileSync } from "node:fs";
 import { hostname } from "node:os";
 import {
   bunPinnedFetch,
-  groups,
-  homeGroupedLightId,
+  type GroupView,
+  type HueApplied,
+  type HueRequest,
+  HueError,
   hue,
   hueClient,
-  pair,
-  scenes,
+  hueText,
+  type LightChange,
+  type LightView,
+  pairWhenPressed,
 } from "../connectors/hue/index.ts";
-import { snapshotFrom } from "../connectors/hue/state.ts";
 import { FINDERS } from "../finders.ts";
 import { env, fail, usage, type Verbs } from "./context.ts";
 
@@ -24,12 +28,9 @@ export async function bridge(): Promise<{ host: string; id: string }> {
   return { host: env.HUE_BRIDGE_HOST ?? b.host, id: env.HUE_BRIDGE_ID ?? b.id };
 }
 
+/** HUE_CA_FILE when set; else undefined, and the package's own copy of Signify's roots is used. */
 export const ca = () =>
-  env.HUE_CA_FILE
-    ? readFileSync(env.HUE_CA_FILE, "utf8")
-    : fail(
-        "set HUE_CA_FILE to Signify's root CA (see src/connectors/hue/README.md)",
-      );
+  env.HUE_CA_FILE ? readFileSync(env.HUE_CA_FILE, "utf8") : undefined;
 
 const key = () =>
   env.HUE_APPLICATION_KEY ??
@@ -50,72 +51,159 @@ async function client() {
   });
 }
 
-/** Find one room, zone or scene by name, case-insensitively; a miss lists what exists. */
-function byName<T extends { name?: string }>(
-  items: T[],
-  name: string,
-  what: string,
-): T {
-  return (
-    items.find((i) => i.name?.toLowerCase() === name.toLowerCase()) ??
-    fail(`no ${what} "${name}"; have: ${items.map((i) => i.name).join(", ")}`)
+/** What a write left, in a line: the light or room as the bridge then reported it, or that it has not reported the change yet. */
+const said = ({
+  state,
+  confirmed,
+  wouldSend,
+}: HueApplied<LightView | GroupView>) =>
+  console.log(
+    wouldSend
+      ? dryLine(wouldSend, hueText(state))
+      : confirmed
+        ? hueText(state)
+        : `sent; the bridge has not reported it yet (${hueText(state)})`,
   );
+const dryLine = (r: HueRequest, now: string) =>
+  `dry run, nothing sent: would PUT ${r.path} ${JSON.stringify(r.body)} (now ${now})`;
+
+export const CHANGE_USAGE = "[on|off] [<1-100>] [<kelvin>k] [<hex colour>]";
+/** The words after a name as a change: `on`, `off`, `40` (brightness), `2700k` (white), `ff8800` (colour), in any order. */
+export function changeFrom(words: string[], usageLine: string): LightChange {
+  const change: LightChange = {};
+  for (const w of words) {
+    if (w === "on" || w === "off") {
+      if (change.on !== undefined && change.on !== (w === "on"))
+        usage(`on or off, not both; ${usageLine}`);
+      change.on = w === "on";
+    } else if (/^\d{1,3}%?$/.test(w))
+      change.brightness = Number.parseInt(w, 10);
+    else if (/^\d{4,5}k$/i.test(w)) change.kelvin = Number.parseInt(w, 10);
+    else if (/^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.test(w)) change.color = w;
+    else
+      usage(
+        `"${w}" is not on, off, a brightness, a temperature like 2700k or a colour like ff8800; ${usageLine}`,
+      );
+  }
+  if (!words.length) usage(usageLine);
+  return change;
 }
 
+/** A change the bridge can't make (an unknown name, a value off the light's range) is a usage error; anything else passes through. */
+const orUsage = (e: unknown): never => {
+  if (e instanceof HueError && e.code === "invalid") usage(e.message);
+  throw e;
+};
+
+/** How long `home pair` waits for the button: time to walk to the bridge. */
+const PAIR_WAIT_MS = 60_000;
+
 export const hueVerbs: Verbs = {
-  async lights([state]) {
-    if (state !== "off") usage("usage: home lights off");
-    const c = await client();
-    const id =
-      homeGroupedLightId(snapshotFrom(await c.get(), "")) ??
-      fail("the bridge has no home group");
-    await c.put("grouped_light", id, { on: { on: false } });
+  async lights([word], o) {
+    if (word !== "off") usage("usage: home lights off");
+    const { state, confirmed, wouldSend } = await (
+      await client()
+    )
+      .allOff({ dryRun: !!o.dryRun })
+      .catch(orUsage);
+    const on = state.filter((l) => l.on && l.reachable !== false).length;
+    console.log(
+      wouldSend
+        ? dryLine(wouldSend, `${on} of ${state.length} on`)
+        : confirmed
+          ? `${state.length} lights off`
+          : `sent; the bridge still reports ${on} of ${state.length} on`,
+    );
   },
 
-  async room([name, value]) {
-    if (!name || !value) usage("usage: home room <name> on|off|<1-100>");
-    const c = await client();
-    const room = byName(
-      groups(snapshotFrom(await c.get(), "")),
-      name!,
-      "room or zone",
+  async light([name, ...words], o) {
+    const line = `usage: home light <name> ${CHANGE_USAGE}`;
+    if (!name) usage(line);
+    const change = changeFrom(words, line);
+    said(
+      await (
+        await client()
+      )
+        .light(name!, change, { dryRun: !!o.dryRun })
+        .catch(orUsage),
     );
-    if (!room.groupedLightId) fail(`${room.name} has no grouped light`);
-    const level = Number(value);
-    if (value !== "on" && value !== "off" && !(level >= 1 && level <= 100))
-      usage(`brightness must be 1-100, got ${value}`);
-    const body =
-      value === "on" || value === "off"
-        ? { on: { on: value === "on" } }
-        : { on: { on: true }, dimming: { brightness: level } };
-    await c.put("grouped_light", room.groupedLightId!, body);
   },
 
-  async scene(words) {
-    const name = words.join(" ") || usage("usage: home scene <name>");
+  async room([name, ...words], o) {
+    const line = `usage: home room <name> ${CHANGE_USAGE}`;
+    if (!name) usage(line);
+    const change = changeFrom(words, line);
+    said(
+      await (
+        await client()
+      )
+        .room(name!, change, { dryRun: !!o.dryRun })
+        .catch(orUsage),
+    );
+  },
+
+  async scene(words, o) {
+    const line = "usage: home scene <name> [in <room>]";
+    if (!words.length) usage(line);
     const c = await client();
-    await c.recallScene(
-      byName(scenes(snapshotFrom(await c.get(), "")), name, "scene").id,
+    // "Relax in Bedroom" is the scene Relax in that room, unless a scene is named all of it.
+    const at = words.lastIndexOf("in");
+    const dry = { dryRun: !!o.dryRun };
+    const whole = () => c.scene(words.join(" "), undefined, dry);
+    said(
+      await (
+        at > 0 && at < words.length - 1
+          ? whole().catch(() =>
+              c.scene(
+                words.slice(0, at).join(" "),
+                words.slice(at + 1).join(" "),
+                dry,
+              ),
+            )
+          : whole()
+      ).catch(orUsage),
     );
   },
 
-  async pair() {
+  async pair(_, o) {
+    if (o.dryRun) usage("home pair has no dry run");
     const b = await bridge();
-    const { key } = await pair({
+    console.error(`Hue bridge ${b.id.slice(-6).toUpperCase()} at ${b.host}.`);
+    // The countdown redraws one line on a terminal; piped, it is one line said once.
+    const live = process.stderr.isTTY;
+    const until = Date.now() + PAIR_WAIT_MS;
+    const prompt = () =>
+      `Press the link button on the bridge: ${Math.max(0, Math.ceil((until - Date.now()) / 1000))} s left`;
+    let tick: ReturnType<typeof setInterval> | undefined;
+    const { key } = await pairWhenPressed({
       host: b.host,
       fetch: bunPinnedFetch(b.id, ca()),
       deviceType: `home#${hostname().slice(0, 19)}`,
-    }).catch((e) =>
-      e.code === "link_button"
-        ? fail(
-            "press the link button on the bridge, then pair again within 30 s",
-            "auth",
-            "home pair",
-          )
-        : Promise.reject(e),
-    );
+      timeoutMs: PAIR_WAIT_MS,
+      onWaiting() {
+        if (!live) return console.error(prompt());
+        process.stderr.write(prompt());
+        tick = setInterval(
+          () => process.stderr.write(`\r\x1b[K${prompt()}`),
+          1000,
+        );
+      },
+    })
+      .finally(() => {
+        clearInterval(tick);
+        if (tick) process.stderr.write("\r\x1b[K");
+      })
+      .catch((e) =>
+        e.code === "link_button"
+          ? fail(
+              `no button press detected in ${PAIR_WAIT_MS / 1000} s; nothing was changed`,
+              "auth",
+              "home pair",
+            )
+          : Promise.reject(e),
+      );
     console.error(
-      "Paired. Put this in your shell environment (never in a repo):",
+      "Paired. Put these in your shell environment or .env (never in a repo):",
     );
     console.log(
       `HUE_APPLICATION_KEY=${key}\nHUE_BRIDGE_HOST=${b.host}\nHUE_BRIDGE_ID=${b.id}`,

package/src/cli/main.ts

@@ -14,23 +14,31 @@ import {
   usage,
   type Verbs,
 } from "./context.ts";
+import { DAIKIN_USAGE, daikinVerbs } from "./daikin.ts";
 import { discover } from "./discover.ts";
 import { enphaseVerbs } from "./enphase.ts";
-import { hueVerbs } from "./hue.ts";
+import { CHANGE_USAGE, hueVerbs } from "./hue.ts";
 import { locate } from "./locate.ts";
 import { probe } from "./probe.ts";
 import { SPOTIFY_USAGE, spotifyVerbs } from "./spotify.ts";
-import { status } from "./status.ts";
+import { devices, status } from "./status.ts";
 import { UP_OPTIONS, UP_USAGE, upVerbs } from "./up.ts";
 
 const HUE_HELP: Record<string, string> = {
   lights: "lights off: one write to the whole-home group",
-  room: "room <name> on|off|<1-100>",
-  scene: "scene <name>",
-  pair: "pair: press the bridge's button first; prints the env lines to set",
+  light: `light <name> ${CHANGE_USAGE}`,
+  room: `room <name> ${CHANGE_USAGE}: every light in a room or zone, one write`,
+  scene: "scene <name> [in <room>]",
+  pair: "pair: waits 60 s for the bridge's button, counting down; prints the env lines to set",
 };
 
 /** Each connector's verbs beyond its status, the usage a wrong one prints, and any options of its own. */
+/** Only where a write reads it: on any other command cac refuses it, so `--dry-run` never lets a real write through. */
+const DRY_RUN: [string, string] = [
+  "--dry-run",
+  "check the write and print what would be sent; send nothing",
+];
+
 const VERBS: Record<
   string,
   {
@@ -41,10 +49,12 @@ const VERBS: Record<
 > = {
   hue: {
     verbs: hueVerbs,
+    options: [DRY_RUN],
     usage: `usage: home hue ${Object.values(HUE_HELP)
       .map((h) => h.split(":")[0])
       .join(" | ")}`,
   },
+  daikin: { verbs: daikinVerbs, usage: DAIKIN_USAGE, options: [DRY_RUN] },
   enphase: { verbs: enphaseVerbs, usage: "usage: home enphase login" },
   cast: { verbs: castVerbs, usage: CAST_USAGE, options: CAST_OPTIONS },
   up: { verbs: upVerbs, usage: UP_USAGE, options: UP_OPTIONS },
@@ -66,6 +76,12 @@ const statusCommand = cli
   .alias("doctor")
   .alias("!") // cac's marker for the default command: `home` alone runs status
   .action((o: Options) => status(o));
+cli
+  .command(
+    "devices",
+    "every device the connectors read, one line each: its state, its room, and why when it isn't available",
+  )
+  .action((o: Options) => devices(o));
 cli
   .command(
     "discover",
@@ -123,10 +139,11 @@ for (const m of MANIFESTS) {
   );
 }
 // Hue's verbs also stand alone, as typed before the CLI had `home hue`: `home lights off`, `home room …`, `home scene …`, `home pair`.
-for (const [verb, run] of Object.entries(hueVerbs))
-  cli
-    .command(`${verb} [...args]`, `Hue: ${HUE_HELP[verb]}`)
-    .action((args: string[], o: Options) => run(args, o));
+for (const [verb, run] of Object.entries(hueVerbs)) {
+  const c = cli.command(`${verb} [...args]`, `Hue: ${HUE_HELP[verb]}`);
+  if (verb !== "pair") c.option(...DRY_RUN);
+  c.action((args: string[], o: Options) => run(args, o));
+}
 
 cli.help();
 
@@ -150,7 +167,15 @@ function describe(e: unknown): {
     e instanceof Error &&
     (e.name === "TimeoutError" || e.name === "AbortError" || socket)
   )
-    return { error, code: "network" };
+    return {
+      // macOS answers "no route to host" for a LAN address when the terminal app lacks the Local Network permission.
+      error:
+        (e as { code?: string }).code === "EHOSTUNREACH" &&
+        process.platform === "darwin"
+          ? `${error} If the device is up, allow this terminal under System Settings > Privacy & Security > Local Network.`
+          : error,
+      code: "network",
+    };
   return { error, code: "error" };
 }
 

package/src/cli/probe.ts

@@ -6,6 +6,7 @@ import {
   printerList,
 } from "../connectors/printers/index.ts";
 import { gatewayHost } from "../connectors/enphase/client.ts";
+import { fetchTimeout } from "../connector.ts";
 import { bunPinnedFetch } from "../connectors/hue/index.ts";
 import { type WeatherSource } from "../connectors/weather/index.ts";
 import {
@@ -39,7 +40,7 @@ function envFromConfig(path: string): Record<string, string> {
       Object.assign(out, {
         HUE_BRIDGE_HOST: d.host,
         HUE_BRIDGE_ID: d.bridgeId,
-        HUE_CA_FILE: fromConfig(path, d.ca),
+        HUE_CA_FILE: d.ca && fromConfig(path, d.ca),
         HUE_APPLICATION_KEY: env[d.key],
       });
     if (d.connector === "daikin") out.DAIKIN_HOST = d.host;
@@ -111,25 +112,28 @@ const jsonOr = (body: string) => {
 
 export async function probe(o: Options): Promise<void> {
   const configPath = configPathOf(o);
-  if (configPath) Object.assign(env, envFromConfig(configPath)); // the config's addresses, for this one command
+  if (configPath) {
+    delete env.HUE_CA_FILE; // the config's `ca` or the package's roots, never the shell's file
+    Object.assign(env, envFromConfig(configPath)); // the config's addresses, for this one command
+  }
   const out: Record<string, unknown> = {};
   try {
     const b = await bridge();
-    const fetchPinned = env.HUE_CA_FILE
-      ? bunPinnedFetch(b.id, ca())
-      : undefined;
-    const r = fetchPinned
-      ? await fetchPinned(`https://${b.host}/api/0/config`).then((x) =>
-          x.json(),
-        )
-      : "needs HUE_CA_FILE";
-    out.hue =
-      typeof r === "string"
-        ? { status: r }
-        : {
-            status: "answers",
-            ...pick(r, ["name", "modelid", "apiversion", "swversion"]),
-          };
+    const r = await fetchTimeout(
+      bunPinnedFetch(b.id, ca()),
+      `https://${b.host}/api/0/config`,
+      {},
+      { timeoutMs: 5000 },
+    ).then((x) => x.json());
+    out.hue = {
+      status: "answers",
+      ...pick(r as Record<string, unknown>, [
+        "name",
+        "modelid",
+        "apiversion",
+        "swversion",
+      ]),
+    };
   } catch (error) {
     out.hue = { status: "unavailable", detail: (error as Error).message };
   }

package/src/cli/status.ts

@@ -12,13 +12,15 @@ import {
   type WeatherSource,
 } from "../connectors/weather/index.ts";
 import { ftpFetch } from "../connectors/weather/ftp.ts";
-import { loadHome } from "../config.ts";
+import { HomeConfig, loadHome } from "../config.ts";
+import { DEVICES, type HomeDevice, homeDevices } from "../devices.ts";
 import { energyNow, gridText } from "../energy.ts";
 import { FINDERS } from "../finders.ts";
 import { type Integration, type Part, type Status, settle } from "../home.ts";
 import { kw, type Manifest } from "../manifest.ts";
 import { MANIFESTS, manifestOf } from "../manifests.ts";
 import { castNow } from "./cast.ts";
+import { daikinHost } from "./daikin.ts";
 import { printersNow } from "./printers.ts";
 import { spotifyFromEnv } from "./spotify.ts";
 import {
@@ -62,17 +64,25 @@ export const weatherSources = (): WeatherSource[] => [
 
 /**
  * Each connector from the shell's env names, once the manifest's non-optional names are set. `needs` adds a step that
- * is not an env name (Enphase's token file). Addresses come from the env only; `home probe` and `home discover` search.
+ * is not an env name (Enphase's token file). Addresses come from the env, except the Daikin's and the Hue bridge's, which
+ * are searched for when unset; `home probe` and `home discover` search for the rest.
  */
 const FROM_ENV: Record<
   string,
   {
-    needs?: () => string[];
+    needs?: () => string[] | Promise<string[]>;
     build: () => Integration<any> | Promise<Integration<any>>;
   }
 > = {
   hue: { build: hueFromEnv },
-  daikin: { build: () => daikin({ host: env.DAIKIN_HOST!, fetch }) },
+  daikin: {
+    // No address set: ask the network. A home with no unit reads "not set up", not as a failure.
+    needs: async () =>
+      (await daikinHost())
+        ? []
+        : ["DAIKIN_HOST (no unit answered the UDP broadcast)"],
+    build: async () => daikin({ host: (await daikinHost())!, fetch }),
+  },
   enphase: {
     needs: () => (existsSync(TOKEN_FILE) ? [] : ["`home enphase login`"]),
     build: enphaseFromEnv,
@@ -106,7 +116,7 @@ async function statusFromEnv(
       const from = FROM_ENV[m.name]!;
       const needs = [
         ...m.env.filter((e) => !e.optional && !env[e.name]).map((e) => e.name),
-        ...(from.needs?.() ?? []),
+        ...((await from.needs?.()) ?? []),
       ];
       rows[m.name] = {
         status: needs.length ? "not set up" : "connecting",
@@ -216,13 +226,54 @@ function rowLines(name: string, r: Row): string[] {
   ];
 }
 
+/** Every connector's row (or the one named), from the config at `path`, else from the shell's env names. */
+const rowsOf = (path: string | undefined, only?: string) =>
+  path
+    ? statusFromConfig(path, only)
+    : statusFromEnv(only === undefined ? MANIFESTS : [manifestOf(only)!]);
+
+/**
+ * `home devices`: every device the connectors read, one line each from `homeDevices`, with its room and name from the
+ * config when there is one. A connector that isn't connected is named on stderr.
+ */
+export async function devices(o: Options): Promise<void> {
+  const path = configPathOf(o);
+  const rows = await rowsOf(path);
+  const parts: Record<string, Part> = {};
+  for (const [name, r] of Object.entries(rows))
+    if (r.status !== "not set up") parts[name] = r as Part;
+  // loadHome has already accepted the config, so a parse that fails here is not expected: list without rooms.
+  const config = path ? HomeConfig.safeParse(readConfig(path)).data : undefined;
+  const list = homeDevices(parts, config);
+  // A connector that isn't connected may have no device to list: say so, off stdout.
+  for (const [name, r] of Object.entries(rows))
+    if (name in DEVICES && r.status !== "connected")
+      console.error(
+        [
+          `${name}: ${r.status}`,
+          r.needs.length ? `needs ${r.needs.join(", ")}` : "",
+          r.detail ?? "",
+        ]
+          .filter(Boolean)
+          .join(" · "),
+      );
+  if (o.json) return printJson(list);
+  for (const d of list) console.log(deviceLine(d));
+}
+
+/** A device's line: "connector  text · in room · not available: reason". */
+export const deviceLine = (d: HomeDevice): string =>
+  [
+    `${d.connector.padEnd(9)}${d.text}`,
+    d.room ? `in ${d.room}` : "",
+    d.available === false ? `not available: ${d.reason}` : "",
+  ]
+    .filter(Boolean)
+    .join(" · ");
+
 /** `home status`: every connector, with the energy now on top. With `only` (`home <connector>`), that connector alone. */
 export async function status(o: Options, only?: string): Promise<void> {
-  const path = configPathOf(o);
-  const manifests = only === undefined ? MANIFESTS : [manifestOf(only)!];
-  const rows = path
-    ? await statusFromConfig(path, only)
-    : await statusFromEnv(manifests);
+  const rows = await rowsOf(configPathOf(o), only);
   if (only !== undefined) {
     const row = rows[only]!;
     if (row.status !== "connected") process.exitCode = 1; // `home <connector>` is a check a script can test; `home` alone lists every one and exits 0

package/src/config.ts

@@ -70,6 +70,12 @@ export const Room = z.looseObject({
     .describe(
       "the Hue room, zone or grouped_light id whose lights this room's marker shows",
     ),
+  photos: z
+    .array(filePath)
+    .optional()
+    .describe(
+      "photos of the room, as paths relative to the config or from ~/; the library never reads them, a drawing agent or an app does",
+    ),
 });
 
 /** JSONC (comments and trailing commas) through jsonc-parser, which runs on Node too; a syntax error throws rather than parsing to part of the file. */
@@ -323,7 +329,7 @@ export type LoadOptions = {
   fetch?: typeof fetch;
   /** Hue's pinned fetch and Enphase's unverified one: Bun's by default, `NODE_TLS` from `@khalido/home/node` under Node. */
   tls?: {
-    hue(bridgeId: string, ca: string): typeof fetch;
+    hue(bridgeId: string, ca?: string): typeof fetch;
     enphase(): typeof fetch;
   };
   /** BOM's transport: `ftpFetch()` from `@khalido/home/weather/ftp`. Without it a listed `bom` source stops and says why. */
@@ -445,7 +451,7 @@ export function loadHome(
   ): HomeIntegration {
     switch (d.connector) {
       case "hue": {
-        const ca = file(d.ca);
+        const ca = d.ca === undefined ? undefined : file(d.ca);
         return hue({
           ...start("hue", d.bridgeId, d.host),
           bridgeId: d.bridgeId,

package/src/connectors/cast/README.md

@@ -10,9 +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.
+- `castStatus(state)`: 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(state, targets)`: the targets an announcement would not disturb, as names for `announceAll`, and `skipped` with why (`busy`, `offline`, `standby`, `unknown`, `form`). With `{ forms: ["speaker", "display"] }` a TV, or a model whose form isn't known, is skipped as `form`, and a group holding one becomes its other free members. 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.
+- `castFreeSpeakers(state)`: the one call for "where can I announce now": `castFree` over every device and group, with `forms: ["speaker", "display"]`. Read live 2026-11-11 (Bun 1.4.4, reads only): 8 devices and groups gave one free group of four, with two TVs and a device whose model was not known skipped as `form`.
 - `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`.
@@ -31,7 +32,9 @@ CastV2 is TLS to port 8009 (a group: its own port), carrying length-prefixed pro
 - 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.
 - **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.
+- **A group's own level was not restored** (same run; fixed in 0.1.3, confirmed below): 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; fixed in 0.1.3: the group's own level goes back first, then each member's.
+- **From a Mac, 2026-11-11 (Bun 1.4.4).** `home cast announce --to <a Nest Hub> --say … --volume 40`: played, idle and volume restored, 6 s in all; KO heard it.
+- **On 0.1.3, 2026-11-11, from the Pi (Bun 1.4.4; chota-bot's session).** A group announce at volume 30: played, and the group and all four members read their earlier levels straight after and 10 s later. With Spotify cast to the group of four: every member read the group's track "via" the group at its own level, `castStatus` gave each member and the group `busy`, and `castFree` over every target left only the idle TV free. So what `castFree` assumes members report is what they report. `castFree` over every target at idle: the group and an idle TV free, a TV with Spotify paused skipped as busy, a device not in discovery skipped as unknown.
 - 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

@@ -37,7 +37,13 @@ import {
 } from "./writes.ts";
 
 export type { CastConnect } from "./codec.ts";
-export { castDevices, castForm, castFree, castStatus } from "./state.ts";
+export {
+  castDevices,
+  castForm,
+  castFree,
+  castFreeSpeakers,
+  castStatus,
+} from "./state.ts";
 export type {
   CastDevice,
   CastForm,