@khalido/home 0.1.1 → 0.1.3

package/dist/connectors/cast/writes.js

@@ -2,15 +2,15 @@ import { errorText } from "../../connector.js";
 import { writeLane } from "../../lane.js";
 import { NS } from "./codec.js";
 import { MediaStatus, MultizoneStatus, ReceiverStatus, } from "./schemas.js";
-import { castKey } from "./state.js";
+import { castKey, DEFAULT_MEDIA_RECEIVER, findCast, } from "./state.js";
 // Writes over the sockets `cast()` already holds: volume, mute, stop, and an announcement that plays a clip and puts
-// the device back as it was. Never called by the integration itself; tried on a scripted fake socket, not yet live.
-/** Google's own player for a URL of audio or video. */
-export const DEFAULT_MEDIA_RECEIVER = "CC1AD845";
+// the device back as it was. Never called by the integration itself; announce, volume and mute have run on real devices (the README has the dates).
 /** Each request (a status, a volume, LAUNCH, LOAD, STOP) gets this long to answer. */
 export const ANSWER_MS = 10_000;
 /** How long an announcement waits for its clip to finish, beyond the clip's own length when the device reports it. */
 export const PLAY_MS = 60_000;
+/** How long a clip gets to start playing. A clip a speaker can't play took 35–44 s to say so (live, 2026-11-09); good ones start within a few seconds. A stated guess. */
+export const START_MS = 15_000;
 const RECEIVER = "receiver-0";
 /** Level writes, and mute writes, per device or group in any minute; more wait their turn, the newest winning. A guess: Cast publishes no limit. */
 export const VOLUME_PER_MINUTE = 30;
@@ -33,6 +33,7 @@ function checkLevel(level) {
  * aborts, or after `ms` (a function is read again each time it would expire, so a deadline can grow).
  */
 function waitFor(clock, s, ms, what, pick, signal) {
+    const name = () => (typeof what === "string" ? what : what());
     return new Promise((resolve, reject) => {
         const done = new AbortController();
         const finish = (settle) => done.signal.aborted ||
@@ -40,10 +41,10 @@ function waitFor(clock, s, ms, what, pick, signal) {
                 signal?.removeEventListener("abort", cancel),
                 done.abort(),
                 settle());
-        const cancel = () => finish(() => reject(new Error(`stopped waiting for ${what}`)));
+        const cancel = () => finish(() => reject(new Error(`stopped waiting for ${name()}`)));
         const off = s.listen((raw) => {
             if (raw === undefined)
-                return finish(() => reject(new Error(`the socket closed waiting for ${what}`)));
+                return finish(() => reject(new Error(`the socket closed waiting for ${name()}`)));
             try {
                 const value = pick(raw);
                 if (value !== undefined)
@@ -59,7 +60,7 @@ function waitFor(clock, s, ms, what, pick, signal) {
         void (async () => {
             for (let left = limit(); left > 0 && !done.signal.aborted; left = start + limit() - clock.now())
                 await clock.sleep(left, done.signal);
-            finish(() => reject(new Error(`no ${what} in ${Math.round(limit() / 1000)} s`)));
+            finish(() => reject(new Error(`no ${name()} in ${Math.round(limit() / 1000)} s`)));
         })();
     });
 }
@@ -80,8 +81,7 @@ export function castActions(ctx) {
     const { clock } = ctx;
     const find = (target) => {
         const all = Object.values(ctx.devices());
-        const d = all.find((x) => x.id === castKey(target)) ??
-            all.find((x) => x.name.toLowerCase() === target.toLowerCase());
+        const d = findCast(ctx.devices(), target);
         if (!d)
             throw new Error(`no Cast device or group "${target}"; have: ${all
                 .map((x) => x.name)
@@ -171,8 +171,11 @@ export function castActions(ctx) {
         const loadId = s.nextId();
         let session;
         let durationS = 0;
+        let started = false; // it has reached PLAYING: BUFFERING is where a clip it can't play sits
         const cancel = new AbortController();
-        const finished = waitFor(clock, s, () => timeoutMs ?? PLAY_MS + durationS * 1000, "end of the clip", (raw) => {
+        const finished = waitFor(clock, s, () => timeoutMs ?? (started ? PLAY_MS + durationS * 1000 : START_MS), () => started
+            ? "end of the clip"
+            : `start of the clip (${media.contentType}, which this device may not play)`, (raw) => {
             const r = MediaStatus.safeParse(raw);
             if (!r.success)
                 return undefined;
@@ -187,11 +190,13 @@ export function castActions(ctx) {
                     continue;
                 if (typeof m.media?.duration === "number")
                     durationS = m.media.duration;
+                if (m.playerState === "PLAYING")
+                    started = true;
                 if (m.playerState !== "IDLE" || !m.idleReason)
                     continue;
                 if (m.idleReason === "FINISHED")
                     return true;
-                throw new Error(`the clip stopped: ${m.idleReason}`);
+                throw new Error(`the clip stopped: ${m.idleReason}${m.detailedErrorCode === undefined ? "" : ` (detailed error ${m.detailedErrorCode})`}${m.idleReason === "ERROR" ? `; this device may not play ${media.contentType}` : ""}`);
             }
             return undefined;
         }, cancel.signal);
@@ -216,7 +221,7 @@ export function castActions(ctx) {
             .get(id)
             .send("level" in volume ? "level" : "muted", volume, (v) => receiver(live(find(target)), { type: "SET_VOLUME", volume: v }));
     };
-    return {
+    const actions = {
         async setVolume(target, level) {
             checkLevel(level);
             await setVolume(target, { level });
@@ -236,7 +241,7 @@ export function castActions(ctx) {
         /**
          * Read the target's state, set the volume if asked and unmute a muted target, launch the Default Media Receiver, play the clip to its end, then
          * put back what it can, always: what the Default Media Receiver was playing is loaded again where it was, an idle
-         * device gets STOP, then the volume (a group's, member by member through each member's own socket). Another app
+         * device gets STOP, then the volume (a group's own first, then member by member through each member's own socket). Another app
          * (Spotify, YouTube) is interrupted and cannot be resumed from here; the result says so. Throws only before anything changed.
          */
         async announce(target, clip, options = {}) {
@@ -352,6 +357,27 @@ export function castActions(ctx) {
                             muted: before.volume?.muted,
                         },
                     ];
+                // A group keeps a level of its own, which its members' levels don't bring back (live, 2026-11-10: it stayed at the
+                // announcement's 30 with every member restored). First, so whatever it does to the members, their own levels land last.
+                if (d.kind === "group" && options.volume !== undefined) {
+                    const level = before.volume?.level;
+                    if (level === undefined)
+                        result.notRestored.push({
+                            name: d.name,
+                            why: "its volume before was not reported",
+                        });
+                    else
+                        try {
+                            await receiver(s, { type: "SET_VOLUME", volume: { level } });
+                            result.restored.push(`${d.name}: volume`);
+                        }
+                        catch (error) {
+                            result.notRestored.push({
+                                name: d.name,
+                                why: `volume not restored: ${errorText(error)}`,
+                            });
+                        }
+                }
                 for (const m of each) {
                     const ms = m.id === d.id ? s : ctx.session(m.id);
                     if (m.level === undefined)
@@ -386,5 +412,33 @@ export function castActions(ctx) {
                 }
             }
         },
+        async announceAll(targets, clip, options = {}) {
+            // A caller's mistake is one error, not a failure per speaker.
+            if (options.volume !== undefined)
+                checkLevel(options.volume);
+            if (!("url" in clip) && !ctx.serve)
+                throw new Error("a clip of bytes needs serve: serveClip from @khalido/home/cast/serve");
+            const id = (t) => {
+                try {
+                    return find(t).id;
+                }
+                catch {
+                    return t; // unknown: announce says so, as this target's own failure
+                }
+            };
+            const once = targets.filter((t, i) => targets.findIndex((o) => id(o) === id(t)) === i); // one device twice would save the first's volume as the one to restore
+            return Promise.all(once.map(async (target) => ({
+                target,
+                ...(await actions
+                    .announce(target, clip, options)
+                    .catch((error) => ({
+                    played: false,
+                    why: errorText(error),
+                    restored: [],
+                    notRestored: [],
+                }))),
+            })));
+        },
     };
+    return actions;
 }

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

@@ -1,9 +1,9 @@
 import { type Clock } from "../../clock.ts";
 import { z } from "zod";
-import type { Integration } from "../../home.ts";
+import { type DeviceRecord, type Integration, type Part } from "../../home.ts";
 import { type Finder } from "../../discover.ts";
 import type { Manifest } from "../../manifest.ts";
-import { daikinClient, type DaikinState } from "./client.ts";
+import { daikinClient, type DaikinState, type Mode } from "./client.ts";
 export { DaikinError, type DaikinState, daikinClient, type Fan, type Mode, setFan, setMode, setPower, setTarget, type WriteRequest, } from "./client.ts";
 /** Poll every 120 s, as Home Assistant's daikin integration does (its coordinator's update_interval). */
 export declare const POLL_MS = 120000;
@@ -39,3 +39,7 @@ export declare function daikin(config: DaikinConfig): Integration<DaikinSnapshot
 /** The AC in a few words: "off · cool 25 °C · room 24 °C · outdoor unit 19.5 °C". */
 export declare function acText(s: DaikinState): string;
 export declare const manifest: Manifest<DaikinSnapshot>;
+/** The AC as a home device: `state` is `off`, its mode while on, or `on` when it hasn't said which; `detail` its snapshot. */
+export type DaikinHomeDevice = DeviceRecord<"daikin", "ac", "off" | "on" | Mode, DaikinSnapshot>;
+/** The one unit, once it has been read. It reports no name or id of its own: a home config's entry names and places it. */
+export declare function daikinHomeDevices(part: Part<DaikinSnapshot> | undefined): DaikinHomeDevice[];

package/dist/connectors/daikin/index.js

@@ -1,8 +1,9 @@
 import { asOf, realClock } from "../../clock.js";
 import { z } from "zod";
+import { deviceRecords, } from "../../home.js";
 import { lostDetail, relocator } from "../../discover.js";
 import { poller } from "../../poll.js";
-import { daikinClient, DaikinError } from "./client.js";
+import { daikinClient, DaikinError, } from "./client.js";
 export { DaikinError, daikinClient, setFan, setMode, setPower, setTarget, } from "./client.js";
 /** Poll every 120 s, as Home Assistant's daikin integration does (its coordinator's update_interval). */
 export const POLL_MS = 120_000;
@@ -106,3 +107,22 @@ export const manifest = {
     ],
     lines: ({ state }) => (state ? [acText(state)] : []),
 };
+/** The one unit, once it has been read. It reports no name or id of its own: a home config's entry names and places it. */
+export function daikinHomeDevices(part) {
+    const s = part?.state;
+    if (!s)
+        return [];
+    return deviceRecords(part, [
+        {
+            connector: "daikin",
+            id: "daikin",
+            name: manifest.title,
+            kind: "ac",
+            available: true,
+            ...(s.on === undefined ? {} : { state: s.on ? (s.mode ?? "on") : "off" }),
+            asOf: s.asOf,
+            text: `${manifest.title}: ${acText(s)}`,
+            detail: s,
+        },
+    ]);
+}

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

@@ -1,6 +1,6 @@
 import { type Clock } from "../../clock.ts";
 import { z } from "zod";
-import { type Integration } from "../../home.ts";
+import { type DeviceRecord, type Integration, type Part } from "../../home.ts";
 import { type Finder } from "../../discover.ts";
 import { type Manifest } from "../../manifest.ts";
 import { type EnphaseState } from "./client.ts";
@@ -41,3 +41,7 @@ export declare function enphase(config: EnphaseConfig): Integration<EnphaseSnaps
 /** "solar 2.1 kW, using 0.6 kW · token 300 days left". The login ask near the end is the integration's, in `detail`. */
 export declare function enphaseText(s: EnphaseSnapshot): string;
 export declare const manifest: Manifest<EnphaseSnapshot>;
+/** The gateway as a home device: `state` is `producing` while the solar makes power, else `idle`; `detail` its snapshot. */
+export type EnphaseHomeDevice = DeviceRecord<"enphase", "solar", "producing" | "idle", EnphaseSnapshot>;
+/** The one gateway, once it has been read. */
+export declare function enphaseHomeDevices(part: Part<EnphaseSnapshot> | undefined): EnphaseHomeDevice[];

package/dist/connectors/enphase/index.js

@@ -1,6 +1,6 @@
 import { localDay, realClock } from "../../clock.js";
 import { z } from "zod";
-import { filePath } from "../../home.js";
+import { deviceRecords, filePath, } from "../../home.js";
 import { lostDetail, relocator } from "../../discover.js";
 import { kw } from "../../manifest.js";
 import { poller } from "../../poll.js";
@@ -51,7 +51,17 @@ export function enphase(config) {
         name: "enphase",
         refresh: () => (where.reset(), poll.nudge()),
         async run(signal, update) {
-            const expiresAt = tokenExpiry(config.token); // a bad token fails this integration only
+            let expiresAt;
+            try {
+                expiresAt = tokenExpiry(config.token); // a bad token fails this integration only
+            }
+            catch {
+                return update({
+                    status: "unavailable",
+                    reason: "auth",
+                    detail: "the token is unreadable; run `home enphase login`",
+                });
+            }
             let last;
             let day;
             let moved; // kept in `detail` so a consumer can persist the new address
@@ -106,6 +116,7 @@ export function enphase(config) {
                     if (error instanceof EnphaseError && error.status === 401)
                         return update({
                             status: "unavailable",
+                            reason: "auth",
                             detail: "the gateway rejected the token; run `home enphase login`",
                             state: last,
                         });
@@ -172,3 +183,24 @@ export const manifest = {
     files: ["token"],
     lines: ({ state }) => (state ? [enphaseText(state)] : []),
 };
+/** The one gateway, once it has been read. */
+export function enphaseHomeDevices(part) {
+    const s = part?.state;
+    if (!s)
+        return [];
+    return deviceRecords(part, [
+        {
+            connector: "enphase",
+            id: "enphase",
+            name: manifest.title,
+            kind: "solar",
+            available: true,
+            ...(s.productionW === undefined
+                ? {}
+                : { state: s.productionW > 0 ? "producing" : "idle" }),
+            asOf: s.asOf,
+            text: `${manifest.title}: ${enphaseText(s)}`,
+            detail: s,
+        },
+    ]);
+}

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

@@ -1,10 +1,10 @@
 import { type Clock } from "../../clock.ts";
 import { z } from "zod";
 import { type Finder } from "../../discover.ts";
-import { type Integration } from "../../home.ts";
+import { type DeviceRecord, type Integration, type Part } from "../../home.ts";
 import type { Manifest } from "../../manifest.ts";
 import { type HueClient } from "./client.ts";
-import { type HueSnapshot } from "./state.ts";
+import { type GroupView, type HueSnapshot, type LightView } from "./state.ts";
 export { bunPinnedFetch, type HueClient, HueError, type HueOptions, hueClient, pair, } from "./client.ts";
 export type { HueEvent, Resource } from "./schemas.ts";
 export { type GroupView, groups, type HueSnapshot, homeGroupedLightId, type LightView, lights, scenes, } from "./state.ts";
@@ -39,4 +39,8 @@ export type HueConfig = {
 export declare function hue(config: HueConfig): Integration<HueSnapshot, "hue"> & {
     readonly client: HueClient;
 };
+/** A Hue light, or a room or zone, as a home device: `detail` is its `LightView` or `GroupView`. */
+export type HueHomeDevice = DeviceRecord<"hue", "light", "on" | "off", LightView> | DeviceRecord<"hue", "group", "on" | "off", GroupView>;
+/** Every light, then every room and zone. A light's `available` is its Zigbee link; a group's `members` are its lights. */
+export declare function hueHomeDevices(part: Part<HueSnapshot> | undefined): HueHomeDevice[];
 export declare const manifest: Manifest<HueSnapshot>;

package/dist/connectors/hue/index.js

@@ -2,7 +2,7 @@ import { asOf, realClock } from "../../clock.js";
 import { errorText } from "../../connector.js";
 import { z } from "zod";
 import { lostDetail, relocator } from "../../discover.js";
-import { envName, filePath, } from "../../home.js";
+import { envName, filePath, deviceRecords, } from "../../home.js";
 import { bunPinnedFetch, hueClient } from "./client.js";
 import { hueEvents, isRejectedKey } from "./events.js";
 import { groups, lights, reduce, snapshotFrom, } from "./state.js";
@@ -137,6 +137,7 @@ export function hue(config) {
                     if (isRejectedKey(error))
                         return update({
                             status: "unavailable",
+                            reason: "auth",
                             detail: "the bridge rejected the key; pair again",
                             state: snapshot,
                         });
@@ -161,6 +162,41 @@ const view = (s) => ({
         brightness,
     })),
 });
+/** "Kitchen: on · 40%", "Kitchen: off", or the name alone when the bridge hasn't said. */
+const onText = (v) => `${v.name ?? v.id}${v.on === undefined ? "" : `: ${v.on ? `on${v.brightness === undefined ? "" : ` · ${Math.round(v.brightness)}%`}` : "off"}`}`;
+/** Every light, then every room and zone. A light's `available` is its Zigbee link; a group's `members` are its lights. */
+export function hueHomeDevices(part) {
+    const s = part?.state;
+    if (!s)
+        return [];
+    const on = (v) => v.on === undefined
+        ? {}
+        : { state: v.on ? "on" : "off" };
+    return deviceRecords(part, [
+        ...lights(s).map((l) => ({
+            connector: "hue",
+            id: l.id,
+            name: l.name ?? l.id,
+            kind: "light",
+            ...(l.reachable === undefined ? {} : { available: l.reachable }),
+            ...on(l),
+            asOf: s.asOf,
+            text: onText(l),
+            detail: l,
+        })),
+        ...groups(s).map((g) => ({
+            connector: "hue",
+            id: g.id,
+            name: g.name ?? g.id,
+            kind: "group",
+            ...on(g),
+            asOf: s.asOf,
+            text: onText(g),
+            members: g.lightIds,
+            detail: g,
+        })),
+    ]);
+}
 export const manifest = {
     name: "hue",
     title: "Philips Hue",
@@ -195,11 +231,8 @@ export const manifest = {
     lines({ state }) {
         if (!state)
             return [];
-        const { lightsOn, rooms } = view(state);
-        return [
-            `${lightsOn} lights on`,
-            ...rooms.map((r) => `${r.name}: ${r.on ? `on${r.brightness === undefined ? "" : ` · ${Math.round(r.brightness)}%`}` : "off"}`),
-        ];
+        const { lightsOn } = view(state);
+        return [`${lightsOn} lights on`, ...groups(state).map(onText)];
     },
     record: ({ state }) => (state ? view(state) : {}),
 };

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

@@ -1,9 +1,9 @@
 import { z } from "zod";
 import { type Clock } from "../../clock.ts";
 import { type Finder } from "../../discover.ts";
-import type { Integration } from "../../home.ts";
+import { type DeviceRecord, type Integration, type Part } from "../../home.ts";
 import type { Manifest } from "../../manifest.ts";
-import { type Printer, type PrintersState } from "./state.ts";
+import { type Printer, type PrinterStatus, type PrintersState } from "./state.ts";
 export { type Marker, type Printer, type PrintersState, type PrinterStatus, printerText, } from "./state.ts";
 /** One printer in a home config. Everything the printer reports about itself (model, markers, state) comes live; `host` and `port` are only where it last answered. */
 export declare const configSchema: z.ZodObject<{
@@ -50,3 +50,7 @@ export declare function printers(config?: PrintersConfig): Integration<PrintersS
 /** Printers sorted by name. */
 export declare const printerList: (s: PrintersState) => Printer[];
 export declare const manifest: Manifest<PrintersState>;
+/** A printer as a home device: `state` is the printer's own (`idle`, `printing`, `stopped`, `offline`); `detail` its `Printer`. */
+export type PrinterHomeDevice = DeviceRecord<"printers", "printer", PrinterStatus, Printer>;
+/** Every printer, by name. One that has stopped answering is not `available`, and keeps its last values. */
+export declare function printersHomeDevices(part: Part<PrintersState> | undefined): PrinterHomeDevice[];

package/dist/connectors/printers/index.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { asOf, realClock } from "../../clock.js";
 import { errorText } from "../../connector.js";
 import { DAY_MS, discover, HOUR, lostDetail, rescanDelay, } from "../../discover.js";
+import { deviceRecords, } from "../../home.js";
 import { poller } from "../../poll.js";
 import { getPrinterAttributes, printerUrl } from "./client.js";
 import { attributesOf } from "./codec.js";
@@ -280,3 +281,25 @@ export const manifest = {
         ];
     },
 };
+/** Every printer, by name. One that has stopped answering is not `available`, and keeps its last values. */
+export function printersHomeDevices(part) {
+    if (!part?.state)
+        return [];
+    return deviceRecords(part, printerList(part.state).map((p) => ({
+        connector: "printers",
+        id: p.uuid,
+        name: p.name,
+        kind: "printer",
+        ...(p.state === undefined ? {} : { available: p.state !== "offline" }),
+        ...(p.state === undefined ? {} : { state: p.state }),
+        // An offline printer's values are from when it last answered, not from this check.
+        ...(p.state === "offline"
+            ? p.lastSeen === undefined
+                ? {}
+                : { asOf: p.lastSeen }
+            : { asOf: p.asOf }),
+        text: printerText(p),
+        ...(p.room ? { room: p.room } : {}),
+        detail: p,
+    })));
+}

package/dist/connectors/spotify/changes.d.ts

@@ -24,7 +24,7 @@ export type SpotifyEvent = {
 /**
  * The events between two reports, for `onChange`'s `before` and `after`: `offline` and `online`; `waiting` (signed out) and
  * `picked` (someone picked the speaker); `started` (from idle), `resumed` (from paused), `paused`, `stopped` (to idle), then
- * `track` for a new track, so "started" and the track come as a pair, then `stalled` and `recovered` (Soloist issue #5). Buffering counts as playing. No `before`, or one
+ * `track` for a new track, once it has a name, then `stalled` and `recovered` (Soloist issue #5). Buffering counts as playing. No `before`, or one
  * with no state (createHome's placeholder before the first report, as at a restart): nothing, since nothing was seen to change. No volume or queue events: read the state.
  */
 export declare function spotifyChanges(before: Part<SpotifyState> | undefined, after: Part<SpotifyState> | undefined): SpotifyEvent[];

package/dist/connectors/spotify/changes.js

@@ -22,7 +22,7 @@ const PLAYING = new Set(["playing", "buffering"]);
 /**
  * The events between two reports, for `onChange`'s `before` and `after`: `offline` and `online`; `waiting` (signed out) and
  * `picked` (someone picked the speaker); `started` (from idle), `resumed` (from paused), `paused`, `stopped` (to idle), then
- * `track` for a new track, so "started" and the track come as a pair, then `stalled` and `recovered` (Soloist issue #5). Buffering counts as playing. No `before`, or one
+ * `track` for a new track, once it has a name, then `stalled` and `recovered` (Soloist issue #5). Buffering counts as playing. No `before`, or one
  * with no state (createHome's placeholder before the first report, as at a restart): nothing, since nothing was seen to change. No volume or queue events: read the state.
  */
 export function spotifyChanges(before, after) {
@@ -55,7 +55,9 @@ export function spotifyChanges(before, after) {
         add({ type: "paused" });
     if (to === "idle" && from !== undefined && from !== "idle")
         add({ type: "stopped" });
-    if (a?.track && a.track.uri !== b?.track?.uri)
+    // Soloist's first report of a new track can have no name yet (seen live): the event waits for it.
+    const named = (p) => !!p?.track?.name;
+    if (a?.track && named(a) && (a.track.uri !== b?.track?.uri || !named(b)))
         add({ type: "track", track: a.track });
     if (a?.stalled && !b?.stalled)
         events.push({ type: "stalled", stall: a.stalled });

package/dist/connectors/spotify/client.d.ts

@@ -158,7 +158,7 @@ export type SpotifyState = {
         name?: string;
     };
     position?: PositionAnchor;
-    /** 0–100, as Soloist reports it. */
+    /** 0–100, as Soloist reports it, rounded. Until `active` it isn't the level that will play (it reads `--initial-volume`, seen live). */
     volume?: number;
     shuffle?: boolean;
     /** off, context or track. */

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

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { type Clock } from "../../clock.ts";
-import type { Integration } from "../../home.ts";
+import { type DeviceRecord, type Integration, type Part } from "../../home.ts";
 import type { Manifest } from "../../manifest.ts";
+import { type SpeakerState } from "./changes.ts";
 import { type SocketFactory, type SpotifyState } from "./client.ts";
 export { positionMs, type PositionAnchor, type SocketFactory, type SocketLike, type SpotifyState, type Stall, toSpotifyUri, type Track, } from "./client.ts";
 export { type SpeakerState, speakerState, type SpotifyEvent, spotifyChanges, spotifyText, } from "./changes.ts";
@@ -49,9 +50,11 @@ export type Aside<T> = {
 /**
  * The writes, on the object `spotify()` returns. Each resolves once Soloist reports the change it asked for, with the state
  * then (`confirmed: true`), or after `CONFIRM_MS` with the state as it stands (`confirmed: false`). Each rejects with a
- * `ConnectorError` whose `code` is `offline`, `waiting` (nobody has picked the speaker), `refused`, `timeout` or `invalid`.
+ * `ConnectorError` whose `code` is `offline`, `waiting` (nobody has picked the speaker), `inactive` (`setVolume` on a speaker that isn't the active device: `activate()` first), `refused`, `timeout` or `invalid`.
  */
 export type SpotifyActions = {
+    /** Make this the account's active Spotify device. Soloist drops volume changes until it is. It makes a new audio stream, so the volume can jump to the level last saved. */
+    activate(): Promise<Applied>;
     /** Play a Spotify link or URI (track, album, playlist, artist, episode, show), or resume what is loaded when none is given. */
     play(linkOrUri?: string): Promise<Applied>;
     pause(): Promise<Applied>;
@@ -90,3 +93,7 @@ export type SpotifyActions = {
  */
 export declare function spotify(config?: SpotifyConfig): Integration<SpotifyState, "spotify"> & SpotifyActions;
 export declare const manifest: Manifest<SpotifyState>;
+/** The Soloist speaker as a home device: `state` is `speakerState`'s word; `detail` its `SpotifyState`. */
+export type SpotifyHomeDevice = DeviceRecord<"spotify", "speaker", SpeakerState, SpotifyState>;
+/** The one speaker, once Soloist has said something. Its name is Soloist's `--device-name`, the one phones show. */
+export declare function spotifyHomeDevices(part: Part<SpotifyState> | undefined): SpotifyHomeDevice[];