@khalido/home 0.1.3 → 0.2.1

package/src/connectors/printers/codec.ts

@@ -29,8 +29,14 @@ export const TAG = {
   mimeMediaType: 0x49,
 } as const;
 
-/** The operation ids this package sends. Identify-Printer (0x003C) and Print-Job (0x0002) are the writes that come later. */
-export const OPERATION = { getPrinterAttributes: 0x000b } as const;
+/** The operation ids this package sends (RFC 8011; Identify-Printer from PWG 5100.13). */
+export const OPERATION = {
+  printJob: 0x0002,
+  validateJob: 0x0004,
+  cancelJob: 0x0008,
+  getPrinterAttributes: 0x000b,
+  identifyPrinter: 0x003c,
+} as const;
 
 const STRING_TAGS: ReadonlySet<number> = new Set([
   TAG.textWithoutLanguage,
@@ -138,19 +144,30 @@ export function encodeMessage(m: IppMessage): Uint8Array<ArrayBuffer> {
       });
   }
   out.push(TAG.end);
-  return Uint8Array.from([...out, ...(m.data ?? [])]);
+  const bytes = new Uint8Array(out.length + (m.data?.length ?? 0));
+  bytes.set(out);
+  if (m.data) bytes.set(m.data, out.length);
+  return bytes;
 }
 
-/** The Get-Printer-Attributes request: IPP 2.0, utf-8, English, the printer's `ipp://` URI, and the attributes wanted. */
-export function getPrinterAttributesRequest(
+/**
+ * A request to one printer: IPP 2.0, utf-8, English, the printer's `ipp://` URI, then `attributes` in the operation
+ * group, `job` (when given) in a job group, and `data` (a document) after the end tag.
+ */
+export function operationRequest(
+  code: number,
   printerUri: string,
-  requested: string[],
-  requestId = 1,
+  options: {
+    attributes?: IppAttribute[];
+    job?: IppAttribute[];
+    data?: Uint8Array;
+    requestId?: number;
+  } = {},
 ): Uint8Array<ArrayBuffer> {
   return encodeMessage({
     version: [2, 0],
-    code: OPERATION.getPrinterAttributes,
-    requestId,
+    code,
+    requestId: options.requestId ?? 1,
     groups: [
       {
         tag: TAG.operation,
@@ -162,13 +179,30 @@ export function getPrinterAttributesRequest(
             values: ["en"],
           },
           { name: "printer-uri", tag: TAG.uri, values: [printerUri] },
-          { name: "requested-attributes", tag: TAG.keyword, values: requested },
+          ...(options.attributes ?? []),
         ],
       },
+      ...(options.job?.length
+        ? [{ tag: TAG.job, attributes: options.job }]
+        : []),
     ],
+    data: options.data,
   });
 }
 
+/** The Get-Printer-Attributes request: the attributes wanted. */
+export const getPrinterAttributesRequest = (
+  printerUri: string,
+  requested: string[],
+  requestId = 1,
+) =>
+  operationRequest(OPERATION.getPrinterAttributes, printerUri, {
+    requestId,
+    attributes: [
+      { name: "requested-attributes", tag: TAG.keyword, values: requested },
+    ],
+  });
+
 const fail = (why: string): never => {
   throw new Error(`ipp: ${why}`);
 };

package/src/connectors/printers/index.ts

@@ -39,6 +39,21 @@ export {
   type PrinterStatus,
   printerText,
 } from "./state.ts";
+export {
+  cancelJob,
+  identifyPrinter,
+  type PrintedJob,
+  type PrinterAddress,
+  type PrintJob,
+  printJob,
+  validateJob,
+} from "./client.ts";
+export {
+  type GreyPage,
+  mediaPixels,
+  pwgRaster,
+  type RasterMedia,
+} from "./raster.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({
@@ -184,6 +199,8 @@ export function printers(
       name: t.name,
       model: good.model ?? t.foundModel,
       host: t.host,
+      port: t.port,
+      rp: t.rp,
       room: t.room,
       ...(offline ? { state: "offline" as const } : {}),
       ipps: t.ipps,

package/src/connectors/printers/raster.ts

@@ -0,0 +1,215 @@
+// PWG Raster (PWG 5102.4), 8-bit grey only: what an AirPrint printer that lists `image/pwg-raster` takes when it lists no
+// PDF. A file is "RaS2", then per page a 1796-byte big-endian header and the page's pixels, compressed line by line:
+// a line-repeat byte (the line appears n + 1 times), then runs: 0 to 127 is one pixel repeated n + 1 times, 129 to 255 is
+// 257 − n pixels as they are. Checked against a page macOS's own filters made for a Brother (test/fixtures/printers).
+
+/** One page: `pixels` is `width × height` bytes, row by row from the top, 0 black to 255 white. */
+export type GreyPage = {
+  width: number;
+  height: number;
+  pixels: Uint8Array;
+};
+
+/** What every page is printed as: the printer's resolution and the PWG media name and size it lists. */
+export type RasterMedia = {
+  /** PWG self-describing name, as the printer lists it in `media-supported`: `iso_a4_210x297mm`. */
+  name: string;
+  /** dots per inch, one of the printer's `pwg-raster-document-resolution-supported`. */
+  dpi: number;
+};
+
+const HEADER = 1796;
+const SGRAY = 18; // cupsColorSpace for sgray (PWG 5102.4 table 9)
+const WHITE = 0xffffff; // AlternatePrimary: the white point, as PWG 5102.4 recommends
+
+/** A PWG media name's size in inches: `iso_a4_210x297mm` is 8.27 × 11.69. */
+function mediaInches(name: string): { width: number; height: number } {
+  const m = /_(\d+(?:\.\d+)?)x(\d+(?:\.\d+)?)(mm|in)$/.exec(name);
+  if (!m) throw new RangeError(`not a PWG media size: ${name}`);
+  const per = m[3] === "mm" ? 1 / 25.4 : 1;
+  return { width: Number(m[1]) * per, height: Number(m[2]) * per };
+}
+
+/** The pixels a page of this media is at its resolution, rounded down as macOS's filters do: A4 at 600 dpi is 4960 × 7015. */
+export function mediaPixels(media: RasterMedia): {
+  width: number;
+  height: number;
+} {
+  const i = mediaInches(media.name);
+  return {
+    width: Math.floor(i.width * media.dpi),
+    height: Math.floor(i.height * media.dpi),
+  };
+}
+
+function header(page: GreyPage, media: RasterMedia, total: number) {
+  const h = new Uint8Array(HEADER);
+  const v = new DataView(h.buffer);
+  const u32 = (offset: number, n: number) => v.setUint32(offset, n);
+  const str = (offset: number, s: string) =>
+    h.set(new TextEncoder().encode(s).subarray(0, 63), offset);
+  const pt = mediaPixels({ name: media.name, dpi: 72 }); // PageSize is in points
+  str(0, "PwgRaster"); // MediaClass
+  u32(276, media.dpi); // HWResolution
+  u32(280, media.dpi);
+  u32(340, 1); // NumCopies: copies are the job's, not the page's
+  u32(352, pt.width); // PageSize, points
+  u32(356, pt.height);
+  u32(372, page.width); // Width, Height in pixels
+  u32(376, page.height);
+  u32(384, 8); // BitsPerColor
+  u32(388, 8); // BitsPerPixel
+  u32(392, page.width); // BytesPerLine
+  u32(400, SGRAY); // ColorSpace; ColorOrder (396) 0 is chunky
+  u32(420, 1); // NumColors
+  u32(452, total); // TotalPageCount
+  u32(456, 1); // CrossFeedTransform
+  u32(460, 1); // FeedTransform
+  u32(480, WHITE); // AlternatePrimary
+  str(1732, media.name); // PageSizeName
+  return h;
+}
+
+/** One line's runs, appended to `out`. */
+function packLine(line: Uint8Array, out: number[]) {
+  let i = 0;
+  while (i < line.length) {
+    let run = 1;
+    while (run < 128 && i + run < line.length && line[i + run] === line[i])
+      run++;
+    if (run > 1 || i + 1 === line.length) {
+      out.push(run - 1, line[i]!);
+      i += run;
+      continue;
+    }
+    // Literal: up to 128 pixels, stopping before two equal pixels that would pack better as a repeat.
+    let n = 1;
+    while (
+      n < 128 &&
+      i + n < line.length &&
+      !(i + n + 1 < line.length && line[i + n] === line[i + n + 1])
+    )
+      n++;
+    if (n === 1) {
+      out.push(0, line[i]!); // a lone pixel is a repeat of one: 257 − 256 can't be written
+      i += 1;
+      continue;
+    }
+    out.push(257 - n);
+    for (let k = 0; k < n; k++) out.push(line[i + k]!);
+    i += n;
+  }
+}
+
+/**
+ * Pages as one PWG Raster document, `image/pwg-raster`. Every page must be `width × height` bytes. Pages may come one at
+ * a time (a generator), so only the packed document and the current page are held; then `total` is the page count.
+ */
+export function pwgRaster(
+  pages: Iterable<GreyPage>,
+  media: RasterMedia,
+  total = Array.isArray(pages) ? pages.length : 0,
+): Uint8Array<ArrayBuffer> {
+  const chunks: Uint8Array[] = [new TextEncoder().encode("RaS2")];
+  for (const page of pages) {
+    if (page.pixels.length !== page.width * page.height)
+      throw new RangeError(
+        `a ${page.width} × ${page.height} page needs ${page.width * page.height} bytes, got ${page.pixels.length}`,
+      );
+    chunks.push(header(page, media, total));
+    let y = 0;
+    while (y < page.height) {
+      const line = page.pixels.subarray(y * page.width, (y + 1) * page.width);
+      let repeat = 0;
+      while (
+        repeat < 255 &&
+        y + repeat + 1 < page.height &&
+        equal(
+          line,
+          page.pixels.subarray(
+            (y + repeat + 1) * page.width,
+            (y + repeat + 2) * page.width,
+          ),
+        )
+      )
+        repeat++;
+      const out = [repeat]; // one line at a time: a page as a number[] would be hundreds of MB
+      packLine(line, out);
+      chunks.push(Uint8Array.from(out));
+      y += repeat + 1;
+    }
+  }
+  const size = chunks.reduce((n, c) => n + c.length, 0);
+  const file = new Uint8Array(size);
+  let at = 0;
+  for (const c of chunks) (file.set(c, at), (at += c.length));
+  return file;
+}
+
+function equal(a: Uint8Array, b: Uint8Array) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/** A PWG Raster document back as pages and their headers' key fields; for tests and for checking a file before it prints. */
+export function readPwgRaster(file: Uint8Array): (GreyPage & {
+  dpi: number;
+  pageSizeName: string;
+  colorSpace: number;
+  bitsPerPixel: number;
+})[] {
+  const text = new TextDecoder();
+  if (text.decode(file.subarray(0, 4)) !== "RaS2")
+    throw new Error("pwg raster: no RaS2 sync word");
+  const pages = [];
+  let at = 4;
+  while (at < file.length) {
+    const v = new DataView(file.buffer, file.byteOffset + at, HEADER);
+    const width = v.getUint32(372);
+    const height = v.getUint32(376);
+    const bitsPerPixel = v.getUint32(388);
+    const bytes = bitsPerPixel / 8;
+    const name = file.subarray(at + 1732, at + 1796);
+    const pageSizeName = text.decode(name.subarray(0, name.indexOf(0)));
+    const page = {
+      width,
+      height,
+      dpi: v.getUint32(276),
+      pageSizeName,
+      colorSpace: v.getUint32(400),
+      bitsPerPixel,
+      pixels: new Uint8Array(width * height * bytes),
+    };
+    at += HEADER;
+    const lineBytes = width * bytes;
+    let y = 0;
+    while (y < height) {
+      const repeat = file[at++]! + 1;
+      const line = new Uint8Array(lineBytes);
+      let x = 0;
+      while (x < lineBytes) {
+        const c = file[at++]!;
+        if (c === 128) {
+          line.fill(255, x); // the rest of the line is white
+          break;
+        }
+        if (c < 128) {
+          const px = file.subarray(at, at + bytes);
+          for (let k = 0; k <= c; k++) line.set(px, x + k * bytes);
+          at += bytes;
+          x += (c + 1) * bytes;
+        } else {
+          const n = (257 - c) * bytes;
+          line.set(file.subarray(at, at + n), x);
+          at += n;
+          x += n;
+        }
+      }
+      for (let k = 0; k < repeat && y < height; k++, y++)
+        page.pixels.set(line, y * lineBytes);
+    }
+    pages.push(page);
+  }
+  return pages;
+}

package/src/connectors/printers/state.ts

@@ -21,6 +21,8 @@ export type Printer = {
   name: string;
   model?: string;
   host?: string;
+  port?: number; // where it last answered, with `rp`: what a write needs to reach it
+  rp?: string; // the IPP path from discovery's TXT; absent is `ipp/print`
   room?: string;
   state?: PrinterStatus; // absent when the printer sent a code outside 3 to 5; `stateCode` has it
   stateCode?: number;

package/src/connectors/spotify/README.md

@@ -35,7 +35,7 @@ Soloist is Spotify's own headless Spotify Connect client (Linux arm64, armv7, x8
 
 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. `track` waits for the track's name, which Soloist can send a few seconds after the track (seen live); one that never gets a name never fires. One press on a phone can fire track, resumed, stopped, started and track over 3 s, sometimes with a 0.8 s `waiting`, and the order varies: anything announcing these should wait a few seconds. `state.volume` isn't the level that will play until `active` (it reads `--initial-volume`).
+**Reading it.** `speakerState` takes the Part; `spotifyText` and `positionMs` take its `state`. `speakerState(part)`: `offline`, `connecting`, `waiting`, `elsewhere` (Soloist says playing but isn't the active device: the music is on another Spotify device and this one is silent; `playingElsewhere(state)` is the test), 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. Music elsewhere is silence here: leaving is `stopped`, arriving is `started` then `track`, and its tracks, pauses and stops meanwhile fire nothing (a resume there after a pause there fires one `stopped`: paused while inactive reads as Soloist says, so the resume looks like music leaving). Soloist doesn't say where it is; `spotifyElsewhere(snapshot)` from `@khalido/home` names the Cast devices playing that track in Spotify, and `homeDevices` puts them in the speaker's line (matched by name, built snapshots only, untried live), and is empty for a phone. 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. `track` waits for the track's name, which Soloist can send a few seconds after the track (seen live); one that never gets a name never fires. One press on a phone can fire track, resumed, stopped, started and track over 3 s, sometimes with a 0.8 s `waiting`, and the order varies: anything announcing these should wait a few seconds. `state.volume` isn't the level that will play until `active` (it reads `--initial-volume`).
 
 **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).
 
@@ -58,6 +58,8 @@ Not built: `deactivate`, `available_actions`. An ad (`entity_type: "ad"`) shows
 
 ## Unverified
 
+What Soloist does that this connector works around, and the upstream issues to watch: [khalido/home.ts#1](https://github.com/khalido/home.ts/issues/1).
+
 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.
@@ -68,12 +70,18 @@ Writes through this connector, and what a live read hasn't shown. In particular:
 
 ## Live findings
 
+**2026-11-11, Raspberry Pi 5, Bun 1.4.4, on 0.1.3** (chota-bot's session; `maxVolume: 40` watching, writes from the CLI in another process). Two gaps in the cap, not fixed:
+
+- From inactive and paused at 60, `play`: lowered to 40 within 2 ms of going active, `playing` at 40, then 60 again 90 ms after `playing`, and it played at 60. The cap takes its first confirmed lowering as done, so nothing lowered it again, and `anomaly` still said "lowered it". After 0.2.0 the note adds "it is back at 60"; the level is left alone, since it is the one the speaker was playing at. Soloist puts its own level back after `playing`.
+- The connector started while the speaker was already active and paused at 60: `play` resumed at 60, nothing lowered it, no anomaly. This is the documented "not on resuming from pause while active".
+- A volume set by hand (35) held through pause and play, so the put-back belongs to activation, not to pause.
+
 **2026-11-10, Raspberry Pi 5, Bun 1.4.4, on 0.1.2, through this connector** (chota-bot's session, KO listening).
 
 - Confirmed with `maxVolume: 60`, the speaker active and playing: `activate`, `setVolume(50)`, `setVolume(90)` (came back 60), `seek`, `setShuffle`, `setRepeat("context")` and `("off")` (about 2.1 s each), `queue` (first in `upNext`), `play` of a playlist URI. `duck(fn, { to: 20 })` around a Cast announce: 20 inside, `music: "restored"`, 60 after, 5.2 s in all.
 - **The level can jump above the cap on a pause, not only on a start.** One-shot CLI, cap 60: `volume 45` read 45, `play` 45, then `pause` read 62 and the next `play` 62 (62 was the level before the test). Nothing lowered it: a pause is not a start signal, and each CLI command is a new process.
 - **That jump did not repeat, and it is not WirePlumber.** A second pass the same day, the speaker already active: 60, `volume 45`, `pause`, `play`, `volume 60`. Soloist's number and the stream's live level (`wpctl get-volume`) matched at every step (0.60, 0.45, 0.45, 0.45, 0.60), WirePlumber 0.5.8 never wrote a saved entry for the stream in `stream-properties`, and the stream kept its id across pause and play. The run that jumped had just been made active with `activate`, minutes after the account was casting from a phone, which points at the account side. One case each way.
-- **`active: false` with `status: "playing"`:** the account playing on another speaker. `speakerState` says `playing`, `spotifyText` prints it as this speaker's, and `spotifyChanges` fired `resumed`, with the box silent.
+- **`active: false` with `status: "playing"`:** the account playing on another speaker. `speakerState` said `playing`, `spotifyText` printed it as this speaker's, and `spotifyChanges` fired `resumed`, with the box silent. Since 2026-11-11 all three read it as `elsewhere`, and the stall watch skips it; not yet seen live.
 - Through chota-bot's wrapper, later the same day: `play` of a playlist confirmed in 241 ms, `next` in 134 ms, `pause` in 17 ms; `duck` to 15 and `interrupt`, 2.5 s each, both `restored`. `play()` with the music paused on a Cast speaker: confirmed in 1.3 s, playing on the box at the same position.
 - **`interrupt` paused music that was on another speaker** (found in chota's switch): it checked `playing` and not `active`. Fixed after 0.1.2.
 - `positionMs` around a duck and an interrupt read 2 s, 2 s, 3 s, 5 s, then 4 s after a pause: it can step back a second.

package/src/connectors/spotify/changes.ts

@@ -14,11 +14,24 @@ export function stallText(s: Stall | undefined): string | undefined {
   return s.tried ? `${what}; tried ${s.tried}` : what;
 }
 
-/** The speaker in one word, to switch on. `offline`: not reached (or no part); `waiting`: running, nobody has picked it. A status Soloist sends beyond its four passes through. */
+const PLAYING = new Set(["playing", "buffering"]);
+
+/**
+ * Soloist says playing while it is not the account's active device: the music is on another Spotify device (a phone,
+ * another speaker) and this one is silent (live, 2026-11-10). Soloist doesn't say which. Unknown `active` is not elsewhere.
+ */
+export const playingElsewhere = (s: SpotifyState | undefined): boolean =>
+  s?.active === false && PLAYING.has(s.status ?? "");
+
+/**
+ * The speaker in one word, to switch on. `offline`: not reached (or no part); `waiting`: running, nobody has picked it;
+ * `elsewhere`: the account's music is playing on another Spotify device, not this one. A status Soloist sends beyond its four passes through.
+ */
 export type SpeakerState =
   | "offline"
   | "connecting"
   | "waiting"
+  | "elsewhere"
   | "idle"
   | "playing"
   | "paused"
@@ -32,6 +45,7 @@ export function speakerState(
     return "offline";
   if (part.status === "connecting") return "connecting";
   if (part.state?.loggedIn === false) return "waiting";
+  if (playingElsewhere(part.state)) return "elsewhere";
   return part.state?.status ?? "idle"; // signed in, nothing reported yet: nothing is playing
 }
 
@@ -57,12 +71,12 @@ export type SpotifyEvent = { own?: true } & (
   | { type: "track"; track: Track }
 );
 
-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, once it has a name, 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.
+ * Music on another Spotify device (`playingElsewhere`) is not playing here: it moving away is `stopped`, it arriving is `started`
+ * then `track`, and nothing fires for its tracks meanwhile. 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(
@@ -87,8 +101,11 @@ export function spotifyChanges(
     events.push({ type: "waiting" });
   if (b?.loggedIn === false && a?.loggedIn === true)
     events.push({ type: "picked" });
-  const from = b?.status;
-  const to = a?.status;
+  // What this speaker itself is doing: music on another device is silence here.
+  const here = (s?: SpotifyState) => (playingElsewhere(s) ? "idle" : s?.status);
+  const from = here(b);
+  // Still inactive after playing elsewhere: a pause or stop there is the other device's, not this one's.
+  const to = playingElsewhere(b) && a?.active === false ? "idle" : here(a);
   const playingNow = to !== undefined && PLAYING.has(to);
   const playingThen = from !== undefined && PLAYING.has(from);
   if (playingNow && !playingThen)
@@ -98,7 +115,13 @@ export function spotifyChanges(
     add({ type: "stopped" });
   // Soloist's first report of a new track can have no name yet (seen live): the event waits for it.
   const named = (p?: SpotifyState) => !!p?.track?.name;
-  if (a?.track && named(a) && (a.track.uri !== b?.track?.uri || !named(b)))
+  const heard = playingElsewhere(b) && playingNow ? undefined : b; // a track that was on another device is new here once it plays here
+  if (
+    a?.track &&
+    named(a) &&
+    !playingElsewhere(a) &&
+    (a.track.uri !== heard?.track?.uri || !named(heard))
+  )
     add({ type: "track", track: a.track });
   if (a?.stalled && !b?.stalled)
     events.push({ type: "stalled", stall: a.stalled });
@@ -112,14 +135,20 @@ export function spotifyChanges(
   return events;
 }
 
-/** The speaker in a few words: `Kitchen speaker: playing "Song" by Band · 35%`, or `…: waiting for someone to pick it`. */
-export function spotifyText(s: SpotifyState): string {
+/**
+ * The speaker in a few words: `Kitchen speaker: playing "Song" by Band · 35%`, `…: waiting for someone to pick it`, or,
+ * for music on another Spotify device, `…: silent · "Song" by Band is playing on another Spotify device` (no volume: it isn't this speaker's playing level).
+ * `on` names where, when the caller knows (`spotifyElsewhere`): `… is playing on Den speaker`.
+ */
+export function spotifyText(s: SpotifyState, on: string[] = []): string {
   const who = s.deviceName ?? "Soloist";
   if (s.loggedIn === false) return `${who}: waiting for someone to pick it`;
   const t = s.track;
   const what = t
     ? `${t.name ? ` "${t.name}"` : ` ${t.uri}`}${t.artists.length ? ` by ${t.artists.join(", ")}` : ""}`
     : "";
+  if (playingElsewhere(s))
+    return `${who}: silent ·${what || " music"} is playing on ${on.length ? on.join(", ") : "another Spotify device"}`;
   const parts = [
     `${s.status ?? "status unknown"}${what}`,
     s.volume === undefined ? "" : `${s.volume}%`,

package/src/connectors/spotify/index.ts

@@ -43,6 +43,7 @@ export {
 } from "./client.ts";
 export {
   type SpeakerState,
+  playingElsewhere,
   speakerState,
   type SpotifyEvent,
   spotifyChanges,
@@ -389,6 +390,17 @@ export function spotify(
    * one raised before it is reported can't be told from the start's own jump, so it is lowered too.
    */
   const applyCap = () => {
+    // Lowered, then above the cap again in the same window: Soloist putting its own level back (seen live) or a person.
+    // The note says where it is now, not only that it was lowered.
+    if (capped && capNote && cap !== undefined && state.volume !== undefined) {
+      const base = capNote.replace(/; it is back at \d+$/, "");
+      const note =
+        state.volume > cap + VOLUME_SLACK
+          ? `${base}; it is back at ${state.volume}`
+          : base;
+      if (note !== capNote) ((capNote = note), publish());
+      return;
+    }
     if (
       cap === undefined ||
       capped ||
@@ -409,7 +421,7 @@ export function spotify(
         if (confirmed) {
           capped = true;
           if (state.status === "idle") return;
-          capNote = `started at volume ${from}, above maxVolume ${cap}; lowered it (Soloist issue #23)`;
+          capNote = `started at volume ${from}, above maxVolume ${cap}; lowered it to ${cap} (Soloist issue #23)`;
           note = undefined;
           return publish();
         }
@@ -836,6 +848,7 @@ export function spotify(
       !st ||
       state.aside === "repair" ||
       (state.track?.uri === st.track &&
+        state.active !== false && // moved to another device: no longer this speaker's stall
         (state.status === "playing" || state.status === "buffering"))
     )
       return;
@@ -870,7 +883,12 @@ export function spotify(
     a.track === b.track &&
     b.atMs - a.atMs >= gap &&
     Math.abs(b.ms - a.ms) < 1000;
-  const playing = () => isOpen() && state.status === "playing" && !state.aside;
+  // Not while inactive: "playing" then is another device's music, and a repair's seek or pause would land on it.
+  const playing = () =>
+    isOpen() &&
+    state.status === "playing" &&
+    state.active !== false &&
+    !state.aside;
 
   /** One look while playing: a fresh position, then frozen, overrun, recovered or fine (Soloist issue #5). */
   const checkStall = async () => {
@@ -916,6 +934,7 @@ export function spotify(
     const ours = () =>
       isOpen() &&
       state.status === "playing" &&
+      state.active !== false &&
       state.track?.uri === track &&
       state.stalled?.track === track &&
       (!state.aside || state.aside === "repair");

package/src/connectors/up/README.md

@@ -7,7 +7,7 @@ Reads the household's spending from Up Bank's API: two months of transactions, s
 - **`client.ts`**: `upClient({ token, fetch })`. Reads: `ping`, `accounts(filter)`, `transactions(query)` following cursors to `limit` (default 1000) and `pageCap` (20) and returning `{ transactions, truncated }` so a cut-off list never looks complete, `transaction(id)`, `categories`, `tags`, `webhooks`, `webhook(id)`, `webhookLogs(id)`. Writes: `setCategory(id, categoryId | null)`, `addTags(id, labels)`, `removeTags(id, labels)`, each re-reading and returning the transaction as Up now holds it; `createWebhook`, `deleteWebhook`, `pingWebhook`. A transaction is flattened to cents (Up's `valueInBaseUnits`) and ids.
 - **`spend.ts`**, pure, one owner per number. `notSpend(t)` is the rule and says why: held, money in, `transferAccount` set (a movement between your own accounts), or a description Up gives its own movements ("Cover from", "Forward to", "Round Up", "Quick save transfer"). "Transfer to …" is not on the list: paying someone else is spend. `isSpend`, `spendByCategory` (parents and children, excluded movements counted and summed so a total can be checked), `spendByMerchant`, `uncategorised` (spend with no category; money in is categorisable too but left out), `recurring` (a heuristic: three or more months within 20% of the median), `unusual` (over twice the median of three or more earlier purchases at that merchant), `dollars` for display.
 - **`webhook.ts`**: `verifyWebhook(rawBody, signature, secret)`, the SHA-256 HMAC of the raw body in hex, Web Crypto, compared in constant time; `parseWebhookEvent(body)` gives the event type and the transaction id. A consumer's handler verifies, then calls `home.refresh("up")`.
-- **The integration** (`up({ token, account?, timeZone?, fetch })`, with `client` on it for a consumer's writes): every 15 minutes it reads the categories, the accounts the filter names, and 63 days of transactions, then cuts this month and last in the home's time zone. The snapshot holds each month's spend by category and top five merchants, the ids still to categorise, and the latest 20 purchases trimmed to id, time, description, amount, category, status and tags (movements between your own accounts are left out: their descriptions name the accounts). Never kept: raw text, message, note, who spent (`performingCustomer`), account ids, balances. A 401 is `unavailable`; a read that hit its page cap is an `anomaly`, as is an amount missing or not in AUD. It never writes.
+- **The integration** (`up({ token, account?, timeZone?, fetch })`, with `client` on it for a consumer's writes): every 15 minutes it reads the categories, the accounts the filter names, and 63 days of transactions, then cuts this month and last in the home's time zone. The snapshot holds each month's spend by category and top five merchants, the ids still to categorise, and the latest 20 purchases trimmed to id, time, description, amount, category, status and tags (movements between your own accounts are left out: their descriptions name the accounts). Never kept: raw text, message, note, who spent (`performingCustomer`), account ids, balances. A 401 or 403 is `unavailable`; a read that hit its page cap is an `anomaly`, as is an amount missing or not in AUD. It never writes.
 - **Config**: `{ connector: "up", key: "UP_TOKEN", account: { ownershipType: "JOINT", accountType: "TRANSACTIONAL" } }`. Accounts are chosen by type and ownership, never by id. Without `account`, every account is read; transfers between them are excluded by `transferAccount`.
 - **CLI**: `home up` (this month, last month, to categorise, top five categories), `home up transactions [--since] [--until] [--category] [--tag] [--status] [--limit] [--json|--csv]`, `categories`, `uncategorised`, `spend [--by category|merchant|recurring]`, and the writes `categorise <id> <category|none>`, `tag <id> <label> [--remove]`, `webhooks [get|logs|ping|create|delete]`. `UP_ACCOUNT` ("JOINT TRANSACTIONAL") is the filter's env form.
 - **Household filter** (`household: { categories, tags }` in the config, `UP_HOUSEHOLD="home tag:home"` in env): the totals, top merchants and recent rows count only purchases in a listed category or its parent, or with a listed tag, so a family dashboard shows groceries and utilities, not personal spending. Tag anything else `home` in the Up app to bring it in. "To categorise" still looks at every purchase, since a category is how one joins. A listed category Up does not have is an `anomaly`, not a silent zero. `inHousehold` is the one owner of the rule; `home up spend` applies it too. `webhooks create` writes the secret Up returns once to `~/.config/home/up-webhook-<id>.secret` (0600); it is never printed.

package/src/connectors/up/client.ts

@@ -6,7 +6,7 @@ import { ConnectorError, fetchTimeout, getJson } from "../../connector.ts";
 
 const BASE = "https://api.up.com.au/api/v1";
 
-/** A failed Up call. `status` 401 means the token is wrong or revoked; 429 the rate limit (unpublished: read `X-RateLimit-Remaining`). */
+/** A failed Up call. `status` 401 or 403 (`isRejectedKey`) means the token is wrong or revoked; 429 the rate limit (unpublished: read `X-RateLimit-Remaining`). */
 export class UpError extends ConnectorError {}
 
 const Money = z.looseObject({

package/src/connectors/up/index.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { asOf, type Clock, realClock } from "../../clock.ts";
-import { errorText } from "../../connector.ts";
+import { errorText, isRejectedKey } from "../../connector.ts";
 import { envName, type Integration } from "../../home.ts";
 import type { Manifest } from "../../manifest.ts";
 import { poller } from "../../poll.ts";
@@ -288,7 +288,7 @@ export function up(config: UpConfig): Integration<UpSnapshot, "up"> & {
           });
         } catch (error) {
           if (signal.aborted) return; // stopped mid-read: not a failure
-          if (error instanceof UpError && error.status === 401)
+          if (isRejectedKey(error))
             return update({
               status: "unavailable",
               reason: "auth",

package/src/connectors/weather/google.ts

@@ -1,5 +1,9 @@
 import { z } from "zod";
-import { ConnectorError, fetchTimeout } from "../../connector.ts";
+import {
+  ConnectorError,
+  fetchTimeout,
+  isRejectedKey,
+} from "../../connector.ts";
 import { RAIN_INTENSITIES } from "./rain.ts";
 import { sunDisagrees } from "./sun.ts";
 import {
@@ -434,7 +438,7 @@ export function google(options: GoogleOptions): WeatherSource {
             ? error
             : ({} as { status?: number; why?: string });
         const said = `HTTP ${status}${why ? ` ${why}` : ""}`;
-        if (status === 401 || status === 403 || why?.startsWith("API_KEY_"))
+        if (isRejectedKey(error) || why?.startsWith("API_KEY_"))
           return {
             stop: `google: the key was rejected (${said})`,
             stopReason: "auth",