@khalido/home 0.0.0-stage → 0.1.1

package/src/connectors/printers/index.ts

@@ -0,0 +1,385 @@
+import { z } from "zod";
+import { asOf, type Clock, realClock } from "../../clock.ts";
+import { errorText } from "../../connector.ts";
+import {
+  DAY_MS,
+  discover,
+  type Finder,
+  HOUR,
+  type Found,
+  type Lost,
+  lostDetail,
+  rescanDelay,
+} from "../../discover.ts";
+import type { Integration, Part, Status } from "../../home.ts";
+import type { Manifest } from "../../manifest.ts";
+import { poller } from "../../poll.ts";
+import { getPrinterAttributes, printerUrl } from "./client.ts";
+import { attributesOf } from "./codec.ts";
+import {
+  type Printer,
+  printerKey,
+  printerText,
+  type PrintersState,
+  type Reading,
+  toState,
+} 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 const configSchema = z.looseObject({
+  connector: z.literal("printers"),
+  name: z
+    .string()
+    .describe(
+      "the printer's name for display (mDNS `ty`, or its instance name); `home discover --write` fills it",
+    ),
+  uuid: z
+    .string()
+    .describe(
+      "the printer's UUID from its mDNS TXT record, the stable identity; `home discover --write` fills it",
+    ),
+  host: z
+    .string()
+    .optional()
+    .describe("the address it last answered at; discovery refreshes it"),
+  port: z
+    .number()
+    .int()
+    .min(1)
+    .max(65535)
+    .optional()
+    .describe("its IPP port (631 plain, 443 TLS); discovery fills it"),
+  offlineDays: z
+    .number()
+    .positive()
+    .optional()
+    .describe(
+      "days an unreachable printer shows as offline with its last-seen time before its entry flags it as long gone; default 14",
+    ),
+});
+
+export type PrinterEntry = {
+  uuid: string;
+  name?: string;
+  host?: string;
+  port?: number;
+  room?: string;
+  offlineDays?: number;
+};
+
+export type PrintersConfig = {
+  /** The config's printers (a `name` is the config's and stays; without one the printer's own, from discovery, is used). Discovery adds any others it finds. */
+  printers?: PrinterEntry[];
+  /** Plain HTTP and HTTPS; the global `fetch` when left out. A printer's self-signed certificate on IPPS fails here, as it should. */
+  fetch?: typeof fetch;
+  /** mDNS discovery (`FINDERS.printers`): at start, then after a failed read on the relocator's cadence (1, 5, 15 minutes, hourly), and hourly for new printers. Without it only the configured addresses are read. */
+  find?: Finder;
+  /** Each address that answered, for an address cache. */
+  seen?: (
+    uuid: string,
+    address: { host: string; port: number; name?: string },
+  ) => void;
+  clock?: Clock;
+  /** Poll interval; default 120 s. */
+  pollMs?: number;
+};
+
+export const POLL_MS = 120_000;
+/** A printer unreachable this many days gets a note in `anomaly`, unless its config says otherwise. */
+const OFFLINE_DAYS = 14;
+
+/** What the integration knows about one printer between polls. */
+type Target = {
+  key: string;
+  name: string;
+  fixedName: boolean; // the config named it
+  room?: string;
+  offlineDays: number;
+  host?: string;
+  port?: number;
+  rp?: string; // from discovery's TXT
+  secure?: boolean; // from discovery: found on _ipps._tcp alone
+  foundModel?: string;
+  good?: Reading; // the last read that worked
+  lastSeen?: number;
+  since: number; // when we first looked, the start of "no answer" for a printer never seen
+  failure?: string; // why the latest read failed; absent after a good read
+  lost: Lost; // what the latest scan learned about a failed one
+  ipps: boolean;
+};
+
+/**
+ * Every printer as one integration, state only: a Get-Printer-Attributes over IPP to each, every 120 s. An unreachable
+ * printer stays in the snapshot as `offline` with its last good values and `lastSeen`, and the part is never
+ * `unavailable` for that. Discovery is one shared scan, as Cast's is, not a relocator per printer: it finds printers
+ * the config does not list, and after a failed read it looks for the printer's new address (at 1, 5 and 15 minutes, then hourly).
+ */
+export function printers(
+  config: PrintersConfig = {},
+): Integration<PrintersState, "printers"> {
+  const clock = config.clock ?? realClock;
+  const fetcher = config.fetch ?? fetch;
+  const pollMs = config.pollMs ?? POLL_MS;
+  const poll = poller(clock);
+  const targets = new Map<string, Target>();
+  const add = (
+    t: Partial<Target> & { key: string; name: string; fixedName: boolean },
+  ): Target => {
+    const target: Target = {
+      offlineDays: OFFLINE_DAYS,
+      since: clock.now(),
+      lost: {},
+      ipps: false,
+      ...t,
+    };
+    targets.set(t.key, target);
+    return target;
+  };
+  for (const p of config.printers ?? [])
+    add({
+      key: printerKey(p.uuid),
+      name: p.name ?? p.uuid,
+      fixedName: p.name !== undefined,
+      room: p.room,
+      host: p.host,
+      port: p.port,
+      offlineDays: p.offlineDays ?? OFFLINE_DAYS,
+    });
+  let report: ((part: Part<PrintersState>) => void) | undefined;
+  let polled = false;
+  let requestId = 0;
+  let lastScan = Number.NEGATIVE_INFINITY;
+  let nextScan = 0;
+  let attempt = 0;
+  let scanError: string | undefined;
+
+  /** The entry for the snapshot: the last good values, `offline` while the latest read has failed. */
+  function view(t: Target, now: string): Printer {
+    const { uuid: _, anomaly: oddReading, ...good } = t.good ?? {};
+    const offline = t.failure !== undefined;
+    const base = t.lastSeen ?? t.since;
+    const idle = clock.now() - base;
+    const long =
+      offline && idle > t.offlineDays * DAY_MS
+        ? `no answer for ${Math.floor(idle / DAY_MS)} days`
+        : undefined;
+    return {
+      ...good,
+      uuid: t.key,
+      name: t.name,
+      model: good.model ?? t.foundModel,
+      host: t.host,
+      room: t.room,
+      ...(offline ? { state: "offline" as const } : {}),
+      ipps: t.ipps,
+      lastSeen:
+        t.lastSeen === undefined
+          ? undefined
+          : new Date(t.lastSeen).toISOString(),
+      asOf: now,
+      detail: offline
+        ? lostDetail(
+            { ...t.lost, ...(idle >= DAY_MS ? { overADay: true } : {}) },
+            t.failure,
+          )
+        : undefined,
+      anomaly: [oddReading, long].filter(Boolean).join("; ") || undefined,
+    };
+  }
+
+  function publish() {
+    const now = asOf(clock);
+    const list = [...targets.values()].map((t) => view(t, now));
+    const down = list.filter((p) => p.state === "offline");
+    const status: Status = !polled
+      ? "connecting"
+      : list.length && down.length < list.length
+        ? "connected"
+        : "disconnected";
+    const detail =
+      [
+        scanError && `discovery failed: ${scanError}`,
+        list.length
+          ? down.length
+            ? `${down.map((p) => p.name).join(", ")} offline`
+            : ""
+          : config.find
+            ? "no printers found"
+            : "no printers configured",
+      ]
+        .filter(Boolean)
+        .join("; ") || undefined;
+    const anomaly =
+      list
+        .filter((p) => p.anomaly)
+        .map((p) => `${p.name}: ${p.anomaly}`)
+        .join("; ") || undefined;
+    report?.({
+      status,
+      detail,
+      anomaly,
+      state: {
+        printers: Object.fromEntries(list.map((p) => [p.uuid, p])),
+        asOf: now,
+      },
+    });
+  }
+
+  /** One read. A failure is data (`failure`), never thrown; an address that answers as another printer is a failure. */
+  async function read(t: Target, signal: AbortSignal): Promise<void> {
+    if (!t.host) {
+      t.failure = "no address yet";
+      return;
+    }
+    const address = { host: t.host, port: t.port, rp: t.rp, secure: t.secure };
+    t.ipps = printerUrl(address).secure;
+    try {
+      const reading = toState(
+        attributesOf(
+          await getPrinterAttributes(fetcher, address, {
+            signal,
+            requestId: ++requestId,
+          }),
+        ),
+      );
+      if (
+        reading.uuid &&
+        /^[0-9a-f]{32}$/.test(t.key) &&
+        printerKey(reading.uuid) !== t.key
+      )
+        throw new Error("the address answers as another printer");
+      t.good = reading;
+      t.lastSeen = clock.now();
+      t.failure = undefined;
+      t.lost = {};
+      config.seen?.(t.key, {
+        host: t.host,
+        port: t.port ?? (t.ipps ? 443 : 631),
+        name: t.fixedName ? undefined : t.name,
+      });
+    } catch (error) {
+      if (!signal.aborted) t.failure = errorText(error);
+    }
+  }
+
+  /** One discovery. Printers it finds get their address and TXT; ones the config lacks join the snapshot. Returns those that need reading again. */
+  async function scan(
+    signal: AbortSignal,
+    failed: Target[],
+  ): Promise<Target[]> {
+    lastScan = clock.now();
+    let all: Found[];
+    try {
+      const wanted = failed.map((t) => t.key);
+      all = await discover(config.find!, {
+        clock,
+        signal,
+        passes: failed.length ? undefined : 1,
+        done: wanted.length
+          ? (found) =>
+              wanted.every((k) => found.some((f) => printerKey(f.id) === k))
+          : undefined,
+      });
+      scanError = undefined;
+    } catch (error) {
+      scanError = errorText(error);
+      for (const t of failed) t.lost = { discoveryFailed: scanError };
+      return [];
+    }
+    const changed: Target[] = [];
+    const mine = all.filter((f) => f.connector === "printers");
+    for (const f of mine) {
+      const key = printerKey(f.id);
+      const known = targets.get(key);
+      const t = known ?? add({ key, name: f.name ?? f.id, fixedName: false });
+      const moved =
+        t.host !== f.host || (f.port !== undefined && t.port !== f.port);
+      // A printer known by host alone was read at the default path over http; the TXT may say otherwise.
+      const reroute =
+        (f.txt?.rp !== undefined && f.txt.rp !== t.rp) ||
+        (f.secure !== undefined && f.secure !== t.secure);
+      if (!t.fixedName && f.name) t.name = f.name;
+      Object.assign(t, {
+        host: f.host,
+        port: f.port ?? t.port,
+        rp: f.txt?.rp ?? t.rp,
+        secure: f.secure ?? t.secure,
+        foundModel: f.model ?? t.foundModel,
+      });
+      if (!known || moved || reroute) changed.push(t);
+      else if (failed.includes(t)) t.lost = { seenHere: true };
+    }
+    for (const t of failed)
+      if (!mine.some((f) => printerKey(f.id) === t.key))
+        t.lost = { seenHere: false };
+    return changed;
+  }
+
+  async function pollOnce(signal: AbortSignal): Promise<void> {
+    const first = !polled;
+    await Promise.all([...targets.values()].map((t) => read(t, signal)));
+    if (signal.aborted || !config.find) return;
+    const now = clock.now();
+    const failed = () =>
+      [...targets.values()].filter((t) => t.failure !== undefined);
+    if (!(
+      first ||
+      (failed().length && now >= nextScan) ||
+      now >= lastScan + HOUR
+    ))
+      return;
+    const changed = await scan(signal, failed());
+    await Promise.all(changed.map((t) => read(t, signal)));
+    if (failed().length) nextScan = now + rescanDelay(attempt++);
+    else ((attempt = 0), (nextScan = 0));
+  }
+
+  return {
+    name: "printers",
+    /** Read now; a printer that is down is looked for again at once. */
+    refresh() {
+      attempt = 0;
+      nextScan = 0;
+      poll.nudge();
+    },
+    async run(signal, update) {
+      report = update;
+      while (!signal.aborted) {
+        await pollOnce(signal);
+        if (signal.aborted) return;
+        polled = true;
+        publish();
+        await poll.wait(pollMs, signal);
+      }
+    },
+  };
+}
+
+/** Printers sorted by name. */
+export const printerList = (s: PrintersState) =>
+  Object.values(s.printers).sort((a, b) => a.name.localeCompare(b.name));
+
+export const manifest: Manifest<PrintersState> = {
+  name: "printers",
+  title: "Printers",
+  iotClass: "local_polling",
+  pollSeconds: POLL_MS / 1000,
+  access: "local IPP over HTTP, no key; found by mDNS (AirPrint)",
+  env: [],
+  lines({ state }) {
+    if (!state) return [];
+    const list = printerList(state);
+    return [
+      `${list.length} printer${list.length === 1 ? "" : "s"}`,
+      ...list.map(printerText),
+    ];
+  },
+};

package/src/connectors/printers/state.ts

@@ -0,0 +1,182 @@
+import { idKey } from "../../discover.ts";
+import type { IppValue } from "./codec.ts";
+
+/** One consumable as the printer lists it: ink or toner, a drum, a fuser, waste. The level is the printer's own number, unrounded. */
+export type Marker = {
+  name?: string;
+  level?: number;
+  type?: string;
+  color?: string;
+};
+
+export type PrinterStatus = "idle" | "printing" | "stopped" | "offline";
+
+/**
+ * One printer. Every field the printer reports is optional; an odd reading passes through and is named in `anomaly`.
+ * `uuid` is the key: the mDNS `UUID` (or `printer-uuid`) lowercase without dashes. An unreachable printer keeps its last good
+ * values, with `state: "offline"` and `lastSeen`; `asOf` is when this entry was last checked, `lastSeen` when it last answered.
+ */
+export type Printer = {
+  uuid: string;
+  name: string;
+  model?: string;
+  host?: string;
+  room?: string;
+  state?: PrinterStatus; // absent when the printer sent a code outside 3 to 5; `stateCode` has it
+  stateCode?: number;
+  reasons?: string[];
+  message?: string;
+  markers?: Marker[];
+  media?: string[]; // media-ready keywords, as sent: "iso_a4_210x297mm"
+  queuedJobs?: number;
+  acceptingJobs?: boolean;
+  formats?: string[]; // document-format-supported: MIME types
+  ippVersions?: string[];
+  alerts?: string[];
+  ipps: boolean; // read over TLS
+  lastSeen?: string;
+  asOf: string;
+  detail?: string;
+  anomaly?: string;
+};
+
+export type PrintersState = { printers: Record<string, Printer>; asOf: string };
+
+/** An id as the snapshot keys it: a UUID in any form (`urn:uuid:…`, dashed, upper case) is its 32 hex digits; an instance name keeps its letters and digits. */
+export const printerKey = idKey;
+
+/** The fields of `Printer` that come from Get-Printer-Attributes. */
+export type Reading = Partial<
+  Pick<
+    Printer,
+    | "model"
+    | "state"
+    | "stateCode"
+    | "reasons"
+    | "message"
+    | "markers"
+    | "media"
+    | "queuedJobs"
+    | "acceptingJobs"
+    | "formats"
+    | "ippVersions"
+    | "alerts"
+    | "anomaly"
+  >
+> & { uuid?: string };
+
+const strings = (v?: IppValue[]): string[] | undefined =>
+  v?.flatMap((x) =>
+    typeof x === "string"
+      ? [x]
+      : x instanceof Uint8Array
+        ? [new TextDecoder().decode(x)]
+        : [],
+  );
+const numbers = (v?: IppValue[]): number[] | undefined =>
+  v?.flatMap((x) => (typeof x === "number" ? [x] : []));
+
+const STATES: Record<number, PrinterStatus> = {
+  3: "idle",
+  4: "printing",
+  5: "stopped",
+};
+
+/**
+ * The printer's attributes (name → values, from `attributesOf`) as a `Reading`. Nothing is clamped or corrected: a state
+ * outside 3 to 5 leaves `state` out and keeps the code; a marker level outside 0 to 100 (PWG 5100.13 gives the negative ones
+ * special meanings) stays as sent; both, and lists that disagree in length, are named in `anomaly`.
+ */
+export function toState(attrs: Record<string, IppValue[]>): Reading {
+  const odd: string[] = [];
+  const [stateCode] = numbers(attrs["printer-state"]) ?? [];
+  const state = stateCode === undefined ? undefined : STATES[stateCode];
+  if (stateCode !== undefined && !state)
+    odd.push(
+      `printer-state ${stateCode}, not 3 (idle), 4 (processing) or 5 (stopped)`,
+    );
+  const names = strings(attrs["marker-names"]);
+  const levels = numbers(attrs["marker-levels"]);
+  const types = strings(attrs["marker-types"]);
+  const colors = strings(attrs["marker-colors"]);
+  const count = Math.max(
+    names?.length ?? 0,
+    levels?.length ?? 0,
+    types?.length ?? 0,
+    colors?.length ?? 0,
+  );
+  const lengths = [names, levels, types, colors].flatMap((x) =>
+    x ? [x.length] : [],
+  );
+  if (new Set(lengths).size > 1)
+    odd.push(`marker lists of different lengths (${lengths.join(", ")})`);
+  const markers: Marker[] = Array.from({ length: count }, (_, i) => ({
+    name: names?.[i],
+    level: levels?.[i],
+    type: types?.[i],
+    color: colors?.[i],
+  }));
+  for (const m of markers)
+    if (m.level !== undefined && (m.level < 0 || m.level > 100))
+      odd.push(`marker ${m.name ?? "?"} level ${m.level}, outside 0 to 100`);
+  const accepting = attrs["printer-is-accepting-jobs"]?.[0];
+  const uuid = strings(attrs["printer-uuid"])?.[0];
+  return {
+    uuid,
+    model: strings(attrs["printer-make-and-model"])?.[0],
+    state,
+    stateCode,
+    reasons: strings(attrs["printer-state-reasons"]),
+    message: strings(attrs["printer-state-message"])?.[0],
+    markers: count ? markers : undefined,
+    media: strings(attrs["media-ready"]),
+    queuedJobs: numbers(attrs["queued-job-count"])?.[0],
+    acceptingJobs: typeof accepting === "boolean" ? accepting : undefined,
+    formats: strings(attrs["document-format-supported"]),
+    ippVersions: strings(attrs["ipp-versions-supported"]),
+    alerts: strings(attrs["printer-alert"]),
+    anomaly: odd.length ? odd.join("; ") : undefined,
+  };
+}
+
+/** A PWG media keyword for reading: `iso_a4_210x297mm` is "A4", `na_letter_8.5x11in` "Letter". A keyword in another shape stays as it is. */
+export function mediaName(keyword: string): string {
+  const parts = keyword.split("_");
+  if (parts.length < 3) return keyword;
+  const name = parts[1]!;
+  return /^[a-z]\d+$/.test(name)
+    ? name.toUpperCase()
+    : name.charAt(0).toUpperCase() + name.slice(1);
+}
+
+/** "5 min ago", "2 h ago", "3 days ago" from two instants; whole units, down. */
+export function ago(fromMs: number, toMs: number): string {
+  const min = Math.max(0, Math.floor((toMs - fromMs) / 60_000));
+  if (min < 60) return `${min} min ago`;
+  const h = Math.floor(min / 60);
+  return h < 48 ? `${h} h ago` : `${Math.floor(h / 24)} days ago`;
+}
+
+/** One printer in a few words: "Office: idle · Black Toner 40% · A4 ready", "Office: offline, last seen 2 h ago". */
+export function printerText(p: Printer): string {
+  if (p.state === "offline") {
+    const seen =
+      p.lastSeen === undefined
+        ? "never seen"
+        : `last seen ${ago(Date.parse(p.lastSeen), Date.parse(p.asOf))}`;
+    return `${p.name}: offline, ${seen}`;
+  }
+  const attention = (p.reasons ?? []).filter((r) =>
+    /-(error|warning)$/.test(r),
+  );
+  const media = [...new Set((p.media ?? []).map(mediaName))];
+  const parts = [
+    p.state ?? (p.stateCode === undefined ? "" : `state ${p.stateCode}`),
+    ...(p.markers ?? []).map((m) => `${m.name ?? "?"} ${m.level ?? "?"}%`),
+    media.length ? `${media.join(", ")} ready` : "",
+    p.queuedJobs ? `${p.queuedJobs} queued` : "",
+    p.acceptingJobs === false ? "not accepting jobs" : "",
+    ...attention,
+  ];
+  return `${p.name}: ${parts.filter(Boolean).join(" · ")}`;
+}

package/src/connectors/spotify/README.md

@@ -0,0 +1,83 @@
+# Spotify (Soloist)
+
+What a [Spotify Soloist](https://developer.spotify.com/documentation/soloist) speaker is playing (start with its [basic integration](https://developer.spotify.com/documentation/soloist/howtos/basic-integration)), and control over it, over Soloist's local WebSocket. `iot_class`: **local_push**. Reads seen live on a real Soloist (2026-11-09); writes tested against a fake socket only.
+
+Soloist is Spotify's own headless Spotify Connect client (Linux arm64, armv7, x86_64, Apple Silicon, Windows x86_64). The machine running it is a speaker in every Spotify app on the network; this connector is how a program on the same machine sees and steers it. It doesn't search Spotify or read a library: Soloist plays URIs and reports its own session. Search belongs to the consumer (KO, 2026-11-08; `docs/ideas.md`).
+
+## Built
+
+**Connecting.** `spotify({ url?, maxVolume?, repairStalls?, stallCheckMs?, connect?, clock? })` holds one WebSocket to `url`, `ws://127.0.0.1:9091` by default (chota-bot's port; Soloist has none, its docs' example is 9090, so start it with `--ws 127.0.0.1:9091` or pass `url`). `connect` defaults to the runtime's `WebSocket` (Bun, Node 22+).
+
+- No report until `auth_state` and, signed in, the first `playback_state` (at most 10 s): the part stays createHome's `connecting`, and a one-shot read sees the track. Then `connected`. Nothing answering, or a drop, is `disconnected` with the reason in `detail` and the last state kept; a reconnect stays `disconnected` until Soloist answers. A socket silent for 10 s is closed. Backoff 1 s doubling to 60 s, back to 1 s after a socket that opened. Without `SOLOIST_WS`, `home` lists the speaker as not set up.
+- **Signed out is normal** until someone picks the speaker in a Spotify app (seen live): `connected`, `loggedIn: false`, detail "waiting for someone to pick it in the Spotify app", which also names a bad key ([#18](https://github.com/spotify/soloist/issues/18)). Writes are refused unsent with code `waiting`.
+- `refresh()` asks again (`get_state`, or `get_auth_state` signed out; a refused query is an `anomaly`), or reconnects now while down.
+
+**State.** Each frame passes a zod schema, every field optional, and folds into `SpotifyState`: `loggedIn`, `deviceName`, `active`, `status`, `track` (`uri`, `type`, `name`, `artists`, `album`, cover, `durationMs`), `context`, `position` (Soloist's anchor `ms`, `atMs`, `speed`; `positionMs(state, now)` moves it on, not clamped), `volume`, `shuffle`, `repeat`, `upNext` (from `queue_changed`, plus one `get_queue` with `limit: 10` per socket; an unanswered one is quiet, as an empty queue may send nothing). An empty item `uri` is nothing loaded: no `track`. Unknown frame types are skipped. The library adds `aside` while its own `duck`, `interrupt` or stall repair runs, and `stalled`. Odd readings pass through into `anomaly`: an unknown status or repeat, a volume outside 0–100, a negative speed, a position past the track's end, a frame the schema rejects (which leaves the state as it was).
+
+**Writes**, on the integration: `play(linkOrUri?)`, `pause`, `resume`, `next`, `prev`, `seek(ms)`, `setVolume(0–100)`, `queue(track)`, `setShuffle(on)`, `setRepeat("off" | "context" | "track")`. A link is an `open.spotify.com` URL or a `spotify:` URI; `spotify.link` short links are refused.
+
+- Each resolves `{ state, confirmed }`: after Soloist accepts (`command_result`), it waits up to 2 s for the event that shows _this caller's_ change (the volume sent, `paused` or `playing`, a new track URI, the context or track played, a position near the seek, the shuffle or repeat set, the track in `upNext`), then gives the state. No such event: `confirmed: false`, the state as it stands. A write merged into a later one confirms only if its own change shows; a write of what is already so confirms at once; a drop ends the wait. `next` also confirms on idle (end of queue) or a restart, `prev` on a restart from 5 s or more in.
+- Errors are `ConnectorError` with `code`: `offline`, `waiting`, `refused` (Soloist's `error`), `timeout` (3 s), `invalid` (bad input, nothing sent).
+- One write lane, 100 ms apart (a guess). `volume`, `seek`, `shuffle`, `repeat` merge to the last; `play`, `pause`, `resume` share a slot, so the last wins; each `next`, `prev`, `queue` is its own. Queries go through the lane too, at most 1 s each, since Soloist's `error` names no command.
+- `setRepeat` is two commands in the docs' order (clear the other mode, then set this one); if the second is refused, repeat may be left off.
+- A failed write the library made itself stays in `detail` until a write works or the socket reconnects.
+
+**`maxVolume`** holds requests (rounded to a whole percent). Within 10 s of a start from idle (to playing or buffering, or the first such status after a sign-in; a start through buffering opens the window again at `playing`), a reported volume above it is lowered once and `anomaly` says so until the speaker goes idle: [#23](https://github.com/spotify/soloist/issues/23), the first play on PipeWire starts at 100%. `--initial-volume` is ignored there. Not on resuming from pause, not on connecting to a song already playing, and a person turning it up again keeps it.
+
+**`duck(fn, { to })` and `interrupt(fn)`** turn the music down, or pause it, around `fn`, then put it back. Both resolve `{ value, music, why? }`, `music` one of:
+
+- `untouched`: not playing or buffering, not connected, (duck) the volume unknown or already at `to` or below, or the lowering or pause failed, so `fn` ran over it.
+- `restored`: put back as it was.
+- `kept`: someone changed it meanwhile (resumed, skipped, set the volume), or the pause or lower volume never showed. Theirs stays.
+- `failed`: the restore failed or was never reported; it may be left quiet or paused.
+
+The restore runs even if `fn` throws: the error is `fn`'s, and a failed restore goes to `detail`. `duck` restores the earlier volume even above `maxVolume`. One aside at a time: never call one inside another's `fn` (it waits forever), and put two announcements in one `fn`. With Cast: `speaker.duck(() => cast.announce("Kitchen", clip), { to: 20 })`. Cast's own `announce` restores what a Cast device was playing; these are for Soloist's output.
+
+**Reading it.** `speakerState` takes the Part; `spotifyText` and `positionMs` take its `state`. `speakerState(part)`: `offline`, `connecting`, `waiting`, then Soloist's status (`idle`, `playing`, `paused`, `buffering`, or its own string); signed in with no status yet is `idle`. `spotifyChanges(before, after)`, for `onChange`, gives events in this order: `offline`, `online`, `waiting`, `picked`, `started` (from idle), `resumed` (from paused), `paused`, `stopped`, `track`, `stalled`, `recovered`. Buffering counts as playing. Nothing on the first report, so a restart announces nothing; no volume or queue events. Playback events during an aside carry `own: true`; connection, sign-in and stall events never do.
+
+**Stalls** ([#5](https://github.com/spotify/soloist/issues/5): playback stops mid-track, often the first after idle, while Soloist still says `playing`). While playing, one `get_state` every 20 s (`stallCheckMs`, code only; 0 turns it off).
+
+- `frozen`: two fresh reports at least 10 s apart by Soloist's clock, under 1 s of movement. `overrun`: the same track more than 15 s past its length (the reported symptom), not with repeat-track. A pause or drop between checks starts over. Paused, buffering, idle and the library's own asides are not looked at.
+- Sets `state.stalled` (`track`, `ms`, `how`, `tried`), "playback stalled at 1:39 (Soloist issue #5)" in `anomaly`, and a `stalled` event; `recovered` when a later check sees it move. A new track or a stop just ends it.
+- `repairStalls: true` (off by default: an unasked write) tries once per track: a skip for an overrun; otherwise a seek to where it stuck, then a pause and play if it hasn't moved 5 s later. It queues with `duck` and `interrupt`, runs as an aside, and stops if the music stops, changes or another aside starts. #5 reports no workaround: the nudges are guesses.
+
+**CLI and config.** `home spotify` and the writes `home spotify pause | play [link] | next | volume <0-100>` (held to `SOLOIST_MAX_VOLUME`) need `SOLOIST_WS`, and print what Soloist then reported. Config: `{ "connector": "spotify", "url"?, "maxVolume"?, "repairStalls"?, "name"? }`, one per home.
+
+## Protocol
+
+JSON text frames on a plain WebSocket: no path, subprotocol, auth, TLS or origin check, so bind it to loopback (any web page on the same machine can reach it). Client frames are `{ "type": "command", "command": "…", …fields }`.
+
+- **Server** (every frame has a `type`): `auth_state` (`logged_in`, `is_active`, `device_name`), `playback_state` (`status`, `item`, `context`, `position`, `volume`, `is_active`, `options`, `available_actions`), `track_changed`, `playback_changed`, `volume_changed`, `device_changed`, `context_changed`, `options_changed` (`shuffle`, `repeat`: off, context, track), `position_sync` (`position_ms`, `timestamp_ms` epoch ms, `speed`), `queue_changed` (`previous`, `upcoming`; broadcasts capped at 10), `command_result` (`command`), `error` (`message`).
+- **Commands:** queries `get_auth_state`, `get_state`, `get_queue` (answered by their frame, no `command_result`); controls `play` (`uri`?), `pause`, `skip_next`, `skip_prev`, `seek` (`position_ms`), `set_volume` (`volume`, 0–100), `set_shuffle`, `set_repeat_context` and `set_repeat_track` (`enabled`), `add_to_queue` (`uri`, tracks only), `activate`, `deactivate`. Controls need a session; without one Soloist answers `error` "command requires authentication".
+- On connect: `auth_state`, then `playback_state` only if signed in. A later sign-in is promised only `auth_state`, so the connector asks `get_state`.
+- If `--ws` can't bind, Soloist runs without it and only logs a warning: `disconnected` while the daemon looks healthy. `--ws ADDR:0` writes the port to the data dir; this connector takes a fixed `url`.
+
+Not built: `activate`/`deactivate`, `available_actions`. An ad (`entity_type: "ad"`) shows as a `track`.
+
+## Unverified
+
+Writes through this connector, and what a live read hasn't shown. In particular:
+
+- **Stalls:** whether the reported position freezes in one (if not, only an overrun is caught), whether `get_state` re-anchors the position, and whether a seek or a pause and play restarts it.
+- **Writes:** that each confirming event arrives within 2 s; which events a `play` of an album or playlist sends; `play` of a new URI with no phone around; seek on playback a phone started.
+- **The cap:** the order of statuses at a start. Soloist's docs list `buffering` but not when it comes; #23 reports the 100% about 100 ms after `playing`, on the first play after the process starts.
+- **The rest:** `get_queue` answered by `queue_changed`; `play` with nothing loaded; whole-number volumes; the order of `auth_state` and `playback_state`; the 100% first play and its lowering; Family-plan members picking the speaker; whether the session survives a Soloist restart; a USB speaker's standby dropping it mid-play.
+
+## Live findings
+
+**2026-11-09, Raspberry Pi 5, Bun 1.4.4, through this connector** (chota-bot's session, reads only). `home spotify` took 140 ms. In code: connected at 11 ms, second report at 55 ms, 51 MB RSS, a clean exit after abort. Track, volume and `paused` read correctly, with no anomaly. `spotifyChanges` gave nothing on the first report.
+
+**2026-11-08, Raspberry Pi 5, Pi OS Lite Trixie arm64, via `soloist ctl`** (chota-bot's session). `soloist 1.3.10.51 build 1793988108 (20261106)` as a systemd user unit with `-w 127.0.0.1:9091`. It logs the days left on the build (88), the WebSocket listening, then "waiting for login". Builds expire 90 days after they're made (exit code 10); chota-bot's units refresh weekly.
+
+- Not logged in until a phone picked the speaker: the normal waiting state. After: logged in, active device.
+- Playback a phone started was controllable from the Pi: volume, pause, and `play` with no `uri` resumed in place.
+- Soloist and avahi-daemon both bound UDP 5353 (`ss -ulpn`) and the phone found the speaker ([#1](https://github.com/spotify/soloist/issues/1) didn't bite).
+- Under PipeWire 1.4 the stream is a node "Spotify". The USB speaker has no hardware volume, so the sink stays at 100% and Soloist's volume is the music's: `maxVolume` caps that only.
+- Logs: `journalctl _SYSTEMD_USER_UNIT=soloist.service`.
+- chota-bot found a client-credentials search URI that Soloist then played (outside this library).
+
+## Sources
+
+- [Soloist documentation](https://developer.spotify.com/documentation/soloist), [WebSocket API](https://developer.spotify.com/documentation/soloist/reference/websocket-api), [`soloist ctl`](https://developer.spotify.com/documentation/soloist/reference/soloist-ctl), [command line](https://developer.spotify.com/documentation/soloist/reference/command-line) (read 2026-11-08). Soloist is Spotify's binary, never redistributed here.
+- [Soloist's issues](https://github.com/spotify/soloist/issues): #1, #5, #15, #18, #23, #24.
+- chota-bot's first client (KO's, 2026-11-08), ported here. Home Assistant has no Soloist integration; its `spotify` is the cloud Web API.