@khalido/home 0.1.1 → 0.1.2

package/dist/connectors/spotify/index.js

@@ -33,10 +33,12 @@ const COMMAND_TIMEOUT_MS = 3000;
 const QUERY_TIMEOUT_MS = 1000;
 /** A socket that has said nothing this long after opening is closed: Soloist sends `auth_state` at once on connect. */
 const HELLO_MS = 10_000;
-/** After an idle → playing change, a volume above the cap is lowered for this long: the volume can come before or after the status (issue #23). */
+/** After a start signal, a volume above the cap is lowered for this long: the volume can come before or after the status (issue #23). */
 const CAP_WINDOW_MS = 10_000;
 /** How long a write waits for Soloist to report the change it asked for. Loopback events arrive in milliseconds; a stated guess. */
 const CONFIRM_MS = 2000;
+/** Between the two halves of `setRepeat`: back to back left repeat on `track`, 600 ms apart worked (live, 2026-11-09). */
+const REPEAT_GAP_MS = 600;
 /** Between two commands. Soloist publishes no limit; it is on loopback; a stated guess. */
 const WRITE_GAP_MS = 100;
 /** While playing, a stall check this often: one `get_state`. Soloist issue #5 reports stalls 71–150 s into a track; a stated guess. */
@@ -45,6 +47,8 @@ const STALL_CHECK_MS = 20_000;
 const OVERRUN_MS = 15_000;
 /** After a repair's seek, how long before looking whether the position moves again. */
 const REPAIR_WAIT_MS = 5000;
+/** A reported volume is rounded (phone steps are sixteenths: 43.75 shows as 44), so "it took" allows this much. */
+const VOLUME_SLACK = 1;
 const MIN_BACKOFF_MS = 1000;
 const MAX_BACKOFF_MS = 60_000;
 /** Signed out is Soloist's normal state until someone picks the speaker (seen live 2026-11-08); a bad key looks the same (issue #18). */
@@ -78,15 +82,16 @@ export function spotify(config = {}) {
     const checkMs = config.stallCheckMs ?? STALL_CHECK_MS;
     let state = { asOf: asOf(clock) };
     let socket;
-    let open = false;
-    let heard = false; // an auth_state on this socket: until then the part stays connecting
-    let whole = false; // signed in, the first playback_state has come too (or HELLO_MS passed): a one-shot read sees the track
+    // This socket's progress. "heard": signed in, the first playback_state still to come. "whole": a one-shot read sees the track (or HELLO_MS passed).
+    let link = "down";
+    const isOpen = () => link !== "down";
     let down; // why the last socket ended, while there is none open
     let statusKnown = false; // Soloist has told this socket its status: only then is idle → playing an edge
     let queueAsked = false; // get_queue sent on this socket
     let signedIn = false; // signed out → in on this socket: the first status after it counts as a start if it is playing
     let capUntil = -Infinity;
-    let capped = false; // the cap has been sent in this window
+    let capped = false; // the cap took in this window
+    let capping = false; // a lowering is on its way
     let startBuffering = false; // a start from idle is still buffering
     let capNote; // the last first-play lowering, in `anomaly` until the speaker goes idle
     let frameNote; // a frame the schema rejected, or an error nothing was waiting for
@@ -99,10 +104,10 @@ export function spotify(config = {}) {
     const publish = () => {
         let status;
         let detail;
-        if (!open)
+        if (link === "down")
             ((status = reported || down ? "disconnected" : "connecting"),
                 (detail = down));
-        else if (!heard || (state.loggedIn === true && !whole))
+        else if (link !== "whole")
             status = "connecting";
         else
             ((status = "connected"),
@@ -128,7 +133,7 @@ export function spotify(config = {}) {
      */
     const command = (name, fields = {}, answers) => new Promise((resolve, reject) => {
         const s = socket;
-        if (!s || !open || s.readyState !== OPEN)
+        if (!s || !isOpen() || s.readyState !== OPEN)
             return reject(offline());
         if (state.loggedIn === false && !answers)
             return reject(new ConnectorError(WAITING, { code: "waiting" }));
@@ -157,11 +162,17 @@ export function spotify(config = {}) {
             p.finish(new ConnectorError(`Soloist did not answer ${name} in ${ms / 1000} s`, { code: "timeout" })));
     });
     const send = async (body) => {
+        if (body.activeFirst && inactive()) {
+            await command("activate").catch(() => { }); // best effort: the write itself says how it went
+            await waitFor(() => state.active === true || !isOpen(), CONFIRM_MS);
+        }
         const before = state;
         const at = clock.now();
         await command(body.command, body.fields, body.answers);
-        if (body.then)
+        if (body.then) {
+            await clock.sleep(REPEAT_GAP_MS);
             await command(body.then.command, body.then.fields); // repeat's second half, still this write's turn
+        }
         return { before, at };
     };
     let once = 0; // skips and queued tracks never merge: two nexts are two skips
@@ -174,7 +185,7 @@ export function spotify(config = {}) {
     const change = async (slot, body) => {
         const sent = await write(slot, body);
         const took = () => body.took?.(state, sent.before, sent.at) ?? true;
-        await waitFor(() => took() || !open, CONFIRM_MS);
+        await waitFor(() => took() || !isOpen(), CONFIRM_MS);
         return { state, confirmed: took() };
     };
     /** The track restarted: a new anchor near 0 when it had been 5 s or more in (a prev past the first seconds, a next on repeat-track). */
@@ -183,11 +194,14 @@ export function spotify(config = {}) {
         (positionMs(b, at) ?? 0) >= 5000;
     const newTrack = (s, b) => !!s.track && s.track.uri !== b.track?.uri;
     const invalid = (message) => new ConnectorError(message, { code: "invalid" });
+    const near = (volume, v) => volume !== undefined && Math.abs(volume - v) <= VOLUME_SLACK;
     const volumeTo = (v) => change("volume", {
         command: "set_volume",
         fields: { volume: v },
-        took: (s) => s.volume === v,
+        took: (s) => near(s.volume, v),
     });
+    /** Soloist accepts a `set_volume` while it isn't the active device and drops it (three times live, 2026-11-09). */
+    const inactive = () => isOpen() && state.loggedIn !== false && state.active === false;
     /** Ask Soloist for something, through the lane; the same query twice merges. A refusal is an anomaly, a drop is the status's to say. */
     const ANSWERS = {
         get_state: "playback_state",
@@ -207,22 +221,48 @@ export function spotify(config = {}) {
         frameNote = `${name} failed: ${errorText(error)}`;
         publish();
     });
-    /** Within the window after a start from idle, a volume above the cap is lowered to it, once (issue #23). */
+    /**
+     * Within the window after a start signal, a volume above the cap is lowered to it (issue #23). Only while active, since
+     * Soloist drops it otherwise, and retried until Soloist reports it. A volume raised after that is someone's choice;
+     * one raised before it is reported can't be told from the start's own jump, so it is lowered too.
+     */
     const applyCap = () => {
         if (cap === undefined ||
             capped ||
+            capping ||
             state.volume === undefined ||
-            clock.now() > capUntil ||
-            state.volume <= cap)
+            state.volume <= cap + VOLUME_SLACK ||
+            state.active === false ||
+            clock.now() > capUntil)
             return;
-        capped = true;
-        capNote = `started at volume ${state.volume}, above maxVolume ${cap}; lowered it (Soloist issue #23)`;
-        change("volume", {
-            command: "set_volume",
-            fields: { volume: cap },
-            took: (s) => s.volume === cap,
-        }).catch((error) => ((note = `lowering the volume to ${cap} failed: ${errorText(error)}`),
-            publish()));
+        capping = true;
+        const from = state.volume;
+        const window = capUntil;
+        volumeTo(cap).then(({ confirmed }) => {
+            capping = false;
+            if (capUntil !== window)
+                return applyCap(); // a new start while it went: this lowering doesn't speak for that one
+            if (confirmed) {
+                capped = true;
+                if (state.status === "idle")
+                    return;
+                capNote = `started at volume ${from}, above maxVolume ${cap}; lowered it (Soloist issue #23)`;
+                note = undefined;
+                return publish();
+            }
+            if (clock.now() > capUntil) {
+                note = `could not lower the volume to ${cap}: Soloist has not reported it`;
+                return publish();
+            }
+            applyCap();
+        }, (error) => {
+            capping = false;
+            if (error instanceof ConnectorError && error.code === "offline")
+                return; // the status says it
+            capped = true; // refused or unanswered: not again this window
+            note = `lowering the volume to ${cap} failed: ${errorText(error)}`;
+            publish();
+        });
     };
     const handle = (data) => {
         let raw;
@@ -254,12 +294,17 @@ export function spotify(config = {}) {
         }
         const before = state.status;
         const wasSignedIn = state.loggedIn;
+        const wasActive = link === "open" ? undefined : state.active; // the first frames on a socket are not a change
         state = fold(state, f, asOf(clock));
+        if (state.track?.uri !== repairedFor)
+            repairedFor = undefined; // one repair per play of a track
+        // Going active makes a new stream, at WirePlumber's saved level (live, 2026-11-09): the likeliest moment for a loud start.
+        if (wasActive === false && state.active === true)
+            ((capUntil = clock.now() + CAP_WINDOW_MS), (capped = false));
         if (f.type === "auth_state") {
             // Signed out there is no playback_state to wait for, and a later sign-in must not send the part back to connecting.
-            if (!heard && f.logged_in !== true)
-                whole = true;
-            heard = true;
+            if (link === "open" || (link === "heard" && f.logged_in === false))
+                link = f.logged_in === true ? "heard" : "whole";
             if (f.logged_in === false)
                 statusKnown = false;
             // A first sign-in (someone picked the speaker) sends only auth_state; the docs don't promise a playback_state after it.
@@ -269,14 +314,14 @@ export function spotify(config = {}) {
         if (f.type === "playback_state") {
             if (!queueAsked)
                 ((queueAsked = true), query("get_queue", { limit: 10 })); // queue_changed pushes changes only, so ask once per socket
-            whole = true;
+            link = "whole";
         }
         if (pending?.answers === f.type)
             pending.finish();
         if ((f.type === "playback_state" || f.type === "playback_changed") &&
             f.status !== undefined) {
-            // A start is idle → playing or buffering, or a sign-in whose first status is either: a phone picked the speaker and played (issue #23).
-            // Soloist's jump to 100 comes about 100 ms after `playing` (issue #23), so a start through buffering opens the window again then.
+            // A start is idle → playing or buffering, or a sign-in whose first status is either: a phone picked the speaker and played.
+            // The volume can land just after `playing` (issue #23), so a start through buffering opens the window again then.
             const started = ((f.status === "playing" || f.status === "buffering") &&
                 (statusKnown ? before === "idle" : signedIn)) ||
                 (f.status === "playing" && startBuffering);
@@ -319,10 +364,8 @@ export function spotify(config = {}) {
             signal.removeEventListener("abort", stop);
             if (socket === s)
                 socket = undefined;
-            const was = open;
-            open = false;
-            heard = false;
-            whole = false;
+            const was = isOpen();
+            link = "down";
             queueAsked = false;
             statusKnown = false;
             signedIn = false;
@@ -339,17 +382,17 @@ export function spotify(config = {}) {
         s.onopen = () => {
             if (ended)
                 return;
-            open = true;
+            link = "open";
             down = undefined;
             note = undefined; // a new socket: what failed on the last one is history
             void clock.sleep(HELLO_MS, quiet.signal).then(() => {
                 if (quiet.signal.aborted)
                     return;
-                if (!heard)
+                if (link === "open")
                     return (end(`Soloist said nothing in ${HELLO_MS / 1000} s`),
                         s.close());
-                if (!whole)
-                    ((whole = true), publish()); // signed in, no playback_state: connected with what there is
+                if (link === "heard")
+                    ((link = "whole"), publish()); // signed in, no playback_state: connected with what there is
             });
         };
         s.onmessage = (ev) => void (ended || handle(ev.data));
@@ -367,7 +410,7 @@ export function spotify(config = {}) {
         waiters.delete(check);
     };
     /** Not connected or not playing: the reason `duck` and `interrupt` just run `fn`. */
-    const notPlaying = () => !open
+    const notPlaying = () => !isOpen()
         ? "Soloist is not connected"
         : state.status === "playing" || state.status === "buffering"
             ? undefined
@@ -388,7 +431,7 @@ export function spotify(config = {}) {
      */
     const aside = (kind, fn, enter, leave) => {
         const run = async () => {
-            if (open)
+            if (isOpen())
                 marked(kind);
             try {
                 return await within();
@@ -423,10 +466,20 @@ export function spotify(config = {}) {
             why: failed(`sent the ${what}; Soloist has not reported it`),
         };
     const actions = {
+        async activate() {
+            if (isOpen() && state.loggedIn !== false && state.active === true)
+                return { state, confirmed: true }; // a second activate might make a new stream
+            return change("activate", {
+                command: "activate",
+                took: (s) => s.active === true,
+            });
+        },
+        // A `play` while inactive didn't take live; going active first is untested for this. `resume` worked inactive, so it doesn't.
         async play(linkOrUri) {
             if (linkOrUri === undefined)
                 return change("transport", {
                     command: "play",
+                    activeFirst: true,
                     took: (s) => s.status === "playing",
                 });
             const uri = toSpotifyUri(linkOrUri);
@@ -435,6 +488,7 @@ export function spotify(config = {}) {
             return change("transport", {
                 command: "play",
                 fields: { uri },
+                activeFirst: true,
                 took: (s) => s.status === "playing" &&
                     (s.track?.uri === uri || s.context?.uri === uri),
             });
@@ -471,6 +525,8 @@ export function spotify(config = {}) {
         async setVolume(volume) {
             if (!Number.isFinite(volume) || volume < 0 || volume > 100)
                 throw invalid(`volume is 0–100, not ${volume}`);
+            if (inactive())
+                throw new ConnectorError("the speaker is not the active Spotify device, so Soloist would drop this; activate it first (`home spotify activate`; its volume may jump to the level last saved)", { code: "inactive" });
             return volumeTo(Math.round(cap === undefined ? volume : Math.min(volume, cap)));
         },
         async queue(track) {
@@ -544,6 +600,8 @@ export function spotify(config = {}) {
                 const no = notPlaying();
                 if (no)
                     return no;
+                if (inactive())
+                    return "it is not the active device, so its volume can't be changed";
                 if (state.volume === undefined)
                     return "its volume is not known";
                 if (state.volume <= to)
@@ -556,7 +614,7 @@ export function spotify(config = {}) {
                     return failed(`lowering the volume for duck failed: ${errorText(error)}`);
                 }
             }, async () => {
-                if (state.volume !== Math.round(to))
+                if (!near(state.volume, Math.round(to)))
                     return {
                         music: "kept",
                         why: shown
@@ -593,7 +651,7 @@ export function spotify(config = {}) {
         state = rest;
     }
     let seen; // the last check's reported position
-    let repairedFor; // at most one repair per track
+    let repairedFor; // at most one repair per play of a track
     /** Ask Soloist where it is, waiting for the answer (or the query's timeout). */
     const fresh = () => write("query-get_state", {
         command: "get_state",
@@ -614,7 +672,7 @@ export function spotify(config = {}) {
         a.track === b.track &&
         b.atMs - a.atMs >= gap &&
         Math.abs(b.ms - a.ms) < 1000;
-    const playing = () => open && state.status === "playing" && !state.aside;
+    const playing = () => isOpen() && state.status === "playing" && !state.aside;
     /** One look while playing: a fresh position, then frozen, overrun, recovered or fine (Soloist issue #5). */
     const checkStall = async () => {
         if (!playing())
@@ -654,7 +712,7 @@ export function spotify(config = {}) {
         repairedFor = track;
         const tried = (what) => state.stalled && stallAs({ ...state.stalled, tried: what });
         // Still ours to fix: playing this track, stalled, and no duck, interrupt or person in between.
-        const ours = () => open &&
+        const ours = () => isOpen() &&
             state.status === "playing" &&
             state.track?.uri === track &&
             state.stalled?.track === track &&
@@ -698,8 +756,10 @@ export function spotify(config = {}) {
         /** Ask Soloist for its state again (`get_state`, or `get_auth_state` without a session); while it is unreachable, reconnect now. */
         refresh() {
             const s = socket;
-            if (s && open && s.readyState === OPEN)
-                return query(state.loggedIn === false || !heard ? "get_auth_state" : "get_state");
+            if (s && isOpen() && s.readyState === OPEN)
+                return query(state.loggedIn === false || link === "open"
+                    ? "get_auth_state"
+                    : "get_state");
             wake?.abort();
         },
         async run(signal, update) {

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

@@ -82,8 +82,10 @@ export declare function toSnapshot(txs: Transaction[], categories: Category[], a
     truncated: boolean;
     household?: Household;
 }): UpSnapshot;
-/** Up as a home integration: two months of transactions now, then every 15 minutes. Reads only; it never writes. */
-export declare function up(config: UpConfig): Integration<UpSnapshot, "up">;
+/** Up as a home integration: two months of transactions now, then every 15 minutes. The integration only reads; `client` is there for a consumer's writes. */
+export declare function up(config: UpConfig): Integration<UpSnapshot, "up"> & {
+    client: UpClient;
+};
 /** "Oct so far $2,140 · Sep $1,980 · 3 to categorise": this month's spend against last month's. */
 export declare function upText(s: UpSnapshot): string;
 /** One line per parent category this month, largest five: "home $1,030: groceries $620, utilities $410". */

package/dist/connectors/up/index.js

@@ -97,13 +97,14 @@ export function toSnapshot(txs, categories, at) {
         truncated: at.truncated,
     };
 }
-/** Up as a home integration: two months of transactions now, then every 15 minutes. Reads only; it never writes. */
+/** Up as a home integration: two months of transactions now, then every 15 minutes. The integration only reads; `client` is there for a consumer's writes. */
 export function up(config) {
     const client = upClient(config);
     const clock = config.clock ?? realClock;
     const poll = poller(clock);
     return {
         name: "up",
+        client,
         refresh: poll.nudge,
         async run(signal, update) {
             let last;

package/dist/discover.d.ts

@@ -85,6 +85,7 @@ export type CachedAddress = {
     host: string;
     port?: number;
     name?: string;
+    model?: string;
     seenAt: string;
 };
 /**
@@ -111,6 +112,7 @@ export declare function addressBook(cache: AddressCache | undefined, options?: {
         host: string;
         port?: number;
         name?: string;
+        model?: string;
     }): void;
     entries: () => {
         [x: string]: CachedAddress;

package/dist/discover.js

@@ -241,13 +241,16 @@ export function addressBook(cache, options = {}) {
                 c.host === address.host &&
                 c.port === address.port &&
                 isFresh(c) &&
-                (!address.name || address.name === c.name))
+                (!address.name || address.name === c.name) &&
+                (!address.model || address.model === c.model))
                 return;
             const name = address.name || c?.name;
+            const model = address.model || c?.model;
             entries[key] = {
                 host: address.host,
                 ...(address.port === undefined ? {} : { port: address.port }),
                 ...(name ? { name } : {}),
+                ...(model ? { model } : {}),
                 seenAt: new Date(now()).toISOString(),
             };
             cache.write({ ...entries });

package/dist/lane.js

@@ -24,28 +24,32 @@ export function writeLane(options) {
     }
     async function run() {
         running = true;
-        while (queue.length) {
-            const now = clock.now();
-            const next = queue.find((p) => readyAt(p.slot) <= now);
-            if (!next) {
-                wake = new AbortController();
-                await clock.sleep(Math.min(...queue.map((p) => readyAt(p.slot))) - now, wake.signal);
-                continue;
-            }
-            queue.splice(queue.indexOf(next), 1);
-            lastAt = now;
-            sent.set(next.slot, [...recent(next.slot), now]);
-            try {
-                const result = await next.write(next.body);
-                for (const w of next.waiters)
-                    w.resolve(result);
-            }
-            catch (error) {
-                for (const w of next.waiters)
-                    w.reject(error);
+        try {
+            while (queue.length) {
+                const now = clock.now();
+                const next = queue.find((p) => readyAt(p.slot) <= now);
+                if (!next) {
+                    wake = new AbortController();
+                    await clock.sleep(Math.min(...queue.map((p) => readyAt(p.slot))) - now, wake.signal);
+                    continue;
+                }
+                queue.splice(queue.indexOf(next), 1);
+                lastAt = now;
+                sent.set(next.slot, [...recent(next.slot), now]);
+                try {
+                    const result = await next.write(next.body);
+                    for (const w of next.waiters)
+                        w.resolve(result);
+                }
+                catch (error) {
+                    for (const w of next.waiters)
+                        w.reject(error);
+                }
             }
         }
-        running = false;
+        finally {
+            running = false; // a throw here must not leave the lane stuck
+        }
     }
     return {
         send(slot, body, write, merge = (_, newer) => newer) {

package/docs/cast.md

@@ -109,7 +109,7 @@ No host: a group's host changes with its leader. All entries fold into one `cast
 - `announce(target, clip, { volume?, timeoutMs? })`, target a device or group, `clip` a URL or bytes with their type (KO's own dictation as recorded, or TTS output; the library never synthesises) served by `serveClip`. The result names each member it could not restore. Read status, set volume, launch Default Media Receiver (`CC1AD845`), `LOAD` the clip, wait for `IDLE`/`FINISHED` (with a timeout), then restore: a prior Default Media Receiver `contentId` is re-loaded at its `currentTime`, an idle device gets `STOP`, then the volume. Spotify, YouTube and other apps cannot be resumed generically (our launch ends their session); the result says so.
 - `castUrl(name, url)` launches DashCast (`84912283`, pychromecast's list) with the URL. HA casts its dashboard with its own registered receiver (`A078F6B0`), a hint at DashCast's limits. KO's own receiver costs a one-off Cast SDK fee and must be published (unpublished ones run only on serial-registered devices). Try DashCast first.
 
-**TTS.** The library plays a URL, never synthesises. The speaker fetches it, so it must be HTTP on the LAN, not loopback, and in a format Default Media Receiver plays (MP3, AAC, WAV; not AIFF): `say -o msg.m4a --file-format=m4af --data-format=aac "…"` (m4af alone holds uncompressed PCM). Smallest server: a ~25-line `serveClip(bytes, type)` over `node:http` beside `tls.ts`, bound to the Mac's LAN address, random port, unguessable path, closed when the clip has played or after a minute (not after the first fetch, so a probe before it does no harm). The consumer runs `say`; `serveClip` picks the address on the target's network; the sidecar will raise macOS's local-network prompt once. A cloud voice later is MP3 bytes served the same way.
+**TTS.** The library plays a URL, never synthesises. The speaker fetches it, so it must be HTTP on the LAN, not loopback, and in a format Default Media Receiver plays (MP3 or AAC; not AIFF; a 24 kHz mono WAV failed on audio-only Nest speakers, live 2026-11-09): `say -o msg.m4a --file-format=m4af --data-format=aac "…"` (m4af alone holds uncompressed PCM). Smallest server: a ~25-line `serveClip(bytes, type)` over `node:http` beside `tls.ts`, bound to the Mac's LAN address, random port, unguessable path, closed when the clip has played or after a minute (not after the first fetch, so a probe before it does no harm). The consumer runs `say`; `serveClip` picks the address on the target's network; the sidecar will raise macOS's local-network prompt once. A cloud voice later is MP3 bytes served the same way.
 
 **CLI.** `home status`: `cast  7 · Display A idle 47% · TV B standby · Whole house (3, led by Display A) idle`. `home probe`: this probe.
 

package/docs/cli.md

@@ -15,11 +15,11 @@ home config check [path]      # validate a home config: what it would set up, se
 home discover --write [path]  # with a config (the path, else --config or HOME_CONFIG): match what answers by identity, add new devices, update moved hosts and renamed Cast names in place
 home probe                    # read-only, no keys: Hue's public config, Daikin by UDP broadcast, the IQ Gateway's /info, each weather source, each Cast device's and printer's status
 home locate "<street address>" [--write [path]]  # latitude and longitude from OpenStreetMap's Nominatim; --write sets them in the config's location (and timezone, when absent, to this machine's)
-home cast announce --to <name> (--say "<text>" | --file <path>) [--volume 0-100]  # play a clip, then put back what was playing and the volume
+home cast announce --to <name> [--to <name>…] (--say "<text>" | --file <path>) [--volume 0-100]  # exit 1 if any didn't play; play a clip, then put back what was playing and the volume
 home cast volume <name> <0-100>
 home cast mute <name> on|off
 home cast stop <name>         # end the running app; the device returns to its idle screen
-home spotify pause | play [link] | next | volume <0-100>  # the Soloist speaker at SOLOIST_WS; volume held to SOLOIST_MAX_VOLUME; prints what Soloist then reported
+home spotify activate | pause | play [link] | next | volume <0-100>  # the Soloist speaker at SOLOIST_WS; volume held to SOLOIST_MAX_VOLUME; prints what Soloist then reported
 ```
 
 ## Output

package/docs/decisions.md

@@ -148,3 +148,4 @@ KO's decisions on this package, newest block last. They override every other doc
 - **Signed out reads as waiting**, everywhere: `speakerState` says `waiting`, the detail says "waiting for someone to pick it", the write error's code is `waiting`.
 - **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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khalido/home",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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/src/cli/cast.ts

@@ -34,6 +34,7 @@ export function castNow() {
           {
             castId: key.slice(5),
             name: c.name ?? key.slice(5),
+            model: c.model,
             host: c.host,
             port: c.port,
           },
@@ -71,7 +72,7 @@ async function withCast<T>(
 }
 
 export const CAST_USAGE =
-  'usage: home cast announce --to <name> (--say "<text>" | --file <path>) [--volume 0-100] | volume <name> <0-100> | mute <name> on|off | stop <name>';
+  'usage: home cast announce --to <name> [--to <name>…] (--say "<text>" | --file <path>) [--volume 0-100] | volume <name> <0-100> | mute <name> on|off | stop <name>';
 
 /** A 0–100 argument as the 0–1 a Cast device takes. */
 function percentLevel(value: string | undefined): number {
@@ -96,7 +97,7 @@ const AUDIO_TYPES: Record<string, string> = {
 export const CAST_OPTIONS: [string, string, { type: unknown[] }?][] = [
   [
     "--to <name>",
-    "announce: the device or group, by name or castId",
+    "announce: the device or group, by name or castId; repeat for several",
     { type: [String] },
   ],
   ["--say <text>", "announce: words spoken by macOS `say`", { type: [String] }],
@@ -119,7 +120,8 @@ export const castVerbs: Verbs = {
     await withCast((c) => c.stop(name!));
   },
   async announce(_, o) {
-    const [to, say, file] = [text(o.to), text(o.say), text(o.file)];
+    const [say, file] = [text(o.say), text(o.file)];
+    const to = [o.to].flat().filter(Boolean).map(String); // --to can repeat
     // cac gives "true" for a flag with no value: `--say` alone must not speak the word "true", so each flag needs a value after it.
     const bare = ["--to", "--say", "--file"].some((f) =>
       process.argv.some(
@@ -130,7 +132,7 @@ export const castVerbs: Verbs = {
       ),
     );
     if (bare) usage(CAST_USAGE);
-    if (!to || !say === !file) usage(CAST_USAGE);
+    if (!to.length || !say === !file) usage(CAST_USAGE);
     const volume =
       o.volume === undefined ? undefined : percentLevel(text(o.volume));
     let type: string;
@@ -160,13 +162,19 @@ export const castVerbs: Verbs = {
       }
       type = "audio/mp4";
     }
-    const r = await withCast((c) =>
-      c.announce(to!, { bytes, type }, { volume }),
+    const results = await withCast((c) =>
+      c.announceAll(to, { bytes, type }, { volume }),
     );
-    if (o.json) return printJson(r);
-    console.log(r.played ? "played" : `not played: ${r.why}`);
-    if (r.restored.length) console.log(`restored: ${r.restored.join(", ")}`);
-    for (const n of r.notRestored)
-      console.log(`not restored: ${n.name}: ${n.why}`);
+    if (results.some((r) => !r.played)) process.exitCode = 1; // docs/cli.md: 1 is a failure, so a script can tell
+    if (o.json) return printJson(to.length === 1 ? results[0] : results);
+    const named = results.length > 1;
+    for (const r of results) {
+      const who = named ? `${r.target}: ` : "";
+      console.log(`${who}${r.played ? "played" : `not played: ${r.why}`}`);
+      if (r.restored.length)
+        console.log(`${who}restored: ${r.restored.join(", ")}`);
+      for (const n of r.notRestored)
+        console.log(`${who}not restored: ${n.name}: ${n.why}`);
+    }
   },
 };

package/src/cli/spotify.ts

@@ -31,7 +31,7 @@ export const spotifyFromEnv = () =>
   });
 
 export const SPOTIFY_USAGE =
-  "usage: home spotify pause | play [link] | next | volume <0-100>";
+  "usage: home spotify activate | pause | play [link] | next | volume <0-100>";
 
 async function withSpotify<T>(
   act: (s: ReturnType<typeof spotify>) => Promise<T>,
@@ -64,6 +64,7 @@ const said = ({ state, confirmed }: Applied) =>
   );
 
 export const spotifyVerbs: Verbs = {
+  activate: () => withSpotify((s) => s.activate()).then(said),
   pause: () => withSpotify((s) => s.pause()).then(said),
   next: () => withSpotify((s) => s.next()).then(said),
   play: ([link]) => withSpotify((s) => s.play(link)).then(said),

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 }),
         },
       ];
     });