@khalido/home 0.2.0 → 0.2.2

package/dist/connectors/printers/index.js

@@ -8,6 +8,8 @@ import { getPrinterAttributes, printerUrl } from "./client.js";
 import { attributesOf } from "./codec.js";
 import { printerKey, printerText, toState, } from "./state.js";
 export { printerText, } from "./state.js";
+export { cancelJob, identifyPrinter, printJob, validateJob, } from "./client.js";
+export { mediaPixels, pwgRaster, } from "./raster.js";
 /** 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"),
@@ -92,6 +94,8 @@ export function printers(config = {}) {
             name: t.name,
             model: good.model ?? t.foundModel,
             host: t.host,
+            port: t.port,
+            rp: t.rp,
             room: t.room,
             ...(offline ? { state: "offline" } : {}),
             ipps: t.ipps,

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

@@ -0,0 +1,30 @@
+/** 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;
+};
+/** 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 declare function mediaPixels(media: RasterMedia): {
+    width: number;
+    height: number;
+};
+/**
+ * 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 declare function pwgRaster(pages: Iterable<GreyPage>, media: RasterMedia, total?: number): Uint8Array<ArrayBuffer>;
+/** A PWG Raster document back as pages and their headers' key fields; for tests and for checking a file before it prints. */
+export declare function readPwgRaster(file: Uint8Array): (GreyPage & {
+    dpi: number;
+    pageSizeName: string;
+    colorSpace: number;
+    bitsPerPixel: number;
+})[];

package/dist/connectors/printers/raster.js

@@ -0,0 +1,175 @@
+// 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).
+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) {
+    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) {
+    const i = mediaInches(media.name);
+    return {
+        width: Math.floor(i.width * media.dpi),
+        height: Math.floor(i.height * media.dpi),
+    };
+}
+function header(page, media, total) {
+    const h = new Uint8Array(HEADER);
+    const v = new DataView(h.buffer);
+    const u32 = (offset, n) => v.setUint32(offset, n);
+    const str = (offset, s) => 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, out) {
+    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, media, total = Array.isArray(pages) ? pages.length : 0) {
+    const chunks = [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, b) {
+    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) {
+    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/dist/connectors/printers/state.d.ts

@@ -18,6 +18,8 @@ export type Printer = {
     name: string;
     model?: string;
     host?: string;
+    port?: number;
+    rp?: string;
     room?: string;
     state?: PrinterStatus;
     stateCode?: number;

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

@@ -41,6 +41,6 @@ export declare function spotifyChanges(before: Part<SpotifyState> | undefined, a
 /**
  * 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 Front room speaker`.
+ * `on` names where, when the caller knows (`spotifyElsewhere`): `… is playing on Den speaker`.
  */
 export declare function spotifyText(s: SpotifyState, on?: string[]): string;

package/dist/connectors/spotify/changes.js

@@ -87,7 +87,7 @@ export function spotifyChanges(before, after) {
 /**
  * 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 Front room speaker`.
+ * `on` names where, when the caller knows (`spotifyElsewhere`): `… is playing on Den speaker`.
  */
 export function spotifyText(s, on = []) {
     const who = s.deviceName ?? "Soloist";

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

@@ -30,10 +30,23 @@ export type SpotifyConfig = {
 };
 /** Soloist's repeat modes. */
 export type Repeat = "off" | "context" | "track";
-/** What a write left: the state once Soloist reported the change (`confirmed`), or the state as it stood when `CONFIRM_MS` ran out without it. */
+/** One WebSocket command, as a dry run reports it: Soloist's command name and its fields. */
+export type SpotifyRequest = {
+    command: string;
+    fields?: Record<string, unknown>;
+};
+/** `dryRun`: run every check a real write runs (connected, signed in, the input), send nothing, and say what would go. */
+export type SpotifyWriteOptions = {
+    dryRun?: boolean;
+};
+/**
+ * What a write left: the state once Soloist reported the change (`confirmed`), or the state as it stood when `CONFIRM_MS`
+ * ran out without it. A dry run resolves `confirmed: false` with `wouldSend`, the commands in order; an `activate` already done resolves `confirmed: true` with `wouldSend: []`.
+ */
 export type Applied = {
     state: SpotifyState;
     confirmed: boolean;
+    wouldSend?: SpotifyRequest[];
 };
 /**
  * What happened to the music around `duck` or `interrupt`'s `fn`: `untouched` (it was not playing, not connected, already
@@ -54,36 +67,37 @@ export type Aside<T> = {
  */
 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>;
+    activate(options?: SpotifyWriteOptions): 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>;
-    resume(): Promise<Applied>;
-    next(): Promise<Applied>;
-    prev(): Promise<Applied>;
+    play(linkOrUri?: string, options?: SpotifyWriteOptions): Promise<Applied>;
+    pause(options?: SpotifyWriteOptions): Promise<Applied>;
+    resume(options?: SpotifyWriteOptions): Promise<Applied>;
+    next(options?: SpotifyWriteOptions): Promise<Applied>;
+    prev(options?: SpotifyWriteOptions): Promise<Applied>;
     /** Jump to a position in the current track, in ms. */
-    seek(ms: number): Promise<Applied>;
+    seek(ms: number, options?: SpotifyWriteOptions): Promise<Applied>;
     /** Set the volume 0–100, held to `maxVolume` and rounded to a whole percent: `state.volume` is what Soloist then reports. */
-    setVolume(volume: number): Promise<Applied>;
+    setVolume(volume: number, options?: SpotifyWriteOptions): Promise<Applied>;
     /** Add a track to the queue (Soloist queues tracks only); confirmed when it shows in `upNext`. */
-    queue(track: string): Promise<Applied>;
-    setShuffle(on: boolean): Promise<Applied>;
+    queue(track: string, options?: SpotifyWriteOptions): Promise<Applied>;
+    setShuffle(on: boolean, options?: SpotifyWriteOptions): Promise<Applied>;
     /** Repeat off, the context (playlist, album) or the track: two commands, in the order Soloist's docs give, as one write. */
-    setRepeat(mode: Repeat): Promise<Applied>;
+    setRepeat(mode: Repeat, options?: SpotifyWriteOptions): Promise<Applied>;
     /**
      * Pause if playing, run `fn`, then resume, unless someone changed it meanwhile (resumed, stopped or skipped it from a
      * phone): then it is theirs and stays. The resume runs even if `fn` throws. Not playing or not connected: just `fn`.
      * One `interrupt` or `duck` at a time; a second waits for the first, so never call either from inside `fn` (it would wait
      * forever). Two announcements back to back belong in one `fn`, or the music comes back between them.
      */
-    interrupt<T>(fn: () => Promise<T> | T): Promise<Aside<T>>;
+    interrupt<T>(fn: () => Promise<T> | T, options?: SpotifyWriteOptions): Promise<Aside<T>>;
     /**
      * Lower the volume to `to` while `fn` runs, then put the earlier volume back, unless someone set the volume meanwhile.
      * For a short announcement over the music. Not playing, not connected or already at `to` or below: just `fn`.
+     * With `dryRun`, `interrupt` and `duck` run `fn`, touch nothing, and say in `why` what they would have done.
      */
     duck<T>(fn: () => Promise<T> | T, options: {
         to: number;
-    }): Promise<Aside<T>>;
+    } & SpotifyWriteOptions): Promise<Aside<T>>;
 };
 /**
  * A Spotify Soloist speaker as one integration: one WebSocket to Soloist, its `auth_state` and `playback_state` on connect,

package/dist/connectors/spotify/index.js

@@ -183,12 +183,31 @@ export function spotify(config = {}) {
      * Soloist accepted the command that carried it (a merged write's may be another's: a pause merged into a later play never
      * confirms). A drop ends the wait early, unconfirmed.
      */
-    const change = async (slot, body) => {
+    const change = async (slot, body, options = {}) => {
+        if (options.dryRun)
+            return dry(body);
         const sent = await write(slot, body);
         const took = () => body.took?.(state, sent.before, sent.at) ?? true;
         await waitFor(() => took() || !isOpen(), CONFIRM_MS);
         return { state, confirmed: took() };
     };
+    /** A dry run: `command`'s own checks (connected, signed in), then the commands `send` would send, in order. */
+    const dry = (body) => {
+        if (!socket || !isOpen() || socket.readyState !== OPEN)
+            throw offline();
+        if (state.loggedIn === false)
+            throw new ConnectorError(WAITING, { code: "waiting" });
+        const one = (command, fields) => fields ? { command, fields } : { command };
+        return {
+            state,
+            confirmed: false,
+            wouldSend: [
+                ...(body.activeFirst && inactive() ? [one("activate")] : []),
+                one(body.command, body.fields),
+                ...(body.then ? [one(body.then.command, body.then.fields)] : []),
+            ],
+        };
+    };
     /** The track restarted: a new anchor near 0 when it had been 5 s or more in (a prev past the first seconds, a next on repeat-track). */
     const restarted = (s, b, at) => s.position !== b.position &&
         (s.position?.ms ?? Infinity) < 5000 &&
@@ -196,11 +215,11 @@ export function spotify(config = {}) {
     const newTrack = (s, b) => !!s.track && s.track.uri !== b.track?.uri;
     const invalid = (message) => new ConnectorError(message, { code: "invalid" });
     const near = (volume, v) => volume !== undefined && Math.abs(volume - v) <= VOLUME_SLACK;
-    const volumeTo = (v) => change("volume", {
+    const volumeTo = (v, options) => change("volume", {
         command: "set_volume",
         fields: { volume: v },
         took: (s) => near(s.volume, v),
-    });
+    }, options);
     /** Soloist accepts a `set_volume` while it isn't the active device and drops it (three times live, 2026-11-09). */
     const inactive = () => isOpen() && state.loggedIn !== false && state.active === false;
     /** Ask Soloist for something, through the lane; the same query twice merges. A refusal is an anomaly, a drop is the status's to say. */
@@ -228,6 +247,17 @@ export function spotify(config = {}) {
      * 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 ||
             capping ||
@@ -247,7 +277,7 @@ export function spotify(config = {}) {
                 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();
             }
@@ -462,6 +492,27 @@ export function spotify(config = {}) {
         asides = p.catch(() => { });
         return p;
     };
+    /** Why `interrupt` would leave the music alone, if it would. */
+    const interruptSkip = () => notPlaying() ??
+        // "playing" while inactive is the account playing on another speaker (live, 2026-11-10): a pause would stop that one.
+        (inactive()
+            ? "it is not the active device, so the music playing is on another speaker"
+            : undefined);
+    /** Why `duck` would leave the volume alone, if it would. */
+    const duckSkip = (to) => notPlaying() ??
+        (inactive()
+            ? "it is not the active device, so its volume can't be changed"
+            : state.volume === undefined
+                ? "its volume is not known"
+                : state.volume <= to
+                    ? `it was already at ${state.volume}`
+                    : undefined);
+    /** A dry `interrupt` or `duck`: `fn` runs, the music is not touched, and `why` says what would have happened to it. */
+    const dryAside = async (fn, skip, would) => ({
+        value: await fn(),
+        music: "untouched",
+        why: `dry run: ${skip ? `${skip}, so the music would be left alone` : `would ${would}`}`,
+    });
     const putBack = (r, what) => r.confirmed
         ? { music: "restored" }
         : {
@@ -469,22 +520,23 @@ export function spotify(config = {}) {
             why: failed(`sent the ${what}; Soloist has not reported it`),
         };
     const actions = {
-        async activate() {
+        async activate(options) {
             if (isOpen() && state.loggedIn !== false && state.active === true)
-                return { state, confirmed: true }; // a second activate might make a new stream
-            return change("activate", {
-                command: "activate",
-                took: (s) => s.active === true,
-            });
+                return {
+                    state,
+                    confirmed: true,
+                    ...(options?.dryRun ? { wouldSend: [] } : {}),
+                }; // a second activate might make a new stream
+            return change("activate", { command: "activate", took: (s) => s.active === true }, options);
         },
         // A `play` while inactive didn't take live; going active first is untested for this. `resume` worked inactive, so it doesn't.
-        async play(linkOrUri) {
+        async play(linkOrUri, options) {
             if (linkOrUri === undefined)
                 return change("transport", {
                     command: "play",
                     activeFirst: true,
                     took: (s) => s.status === "playing",
-                });
+                }, options);
             const uri = toSpotifyUri(linkOrUri);
             if (!uri)
                 throw invalid(`not a Spotify link or URI: ${linkOrUri}`);
@@ -494,28 +546,22 @@ export function spotify(config = {}) {
                 activeFirst: true,
                 took: (s) => s.status === "playing" &&
                     (s.track?.uri === uri || s.context?.uri === uri),
-            });
+            }, options);
         },
-        pause: () => change("transport", {
-            command: "pause",
-            took: (s) => s.status === "paused",
-        }),
-        resume: () => change("transport", {
-            command: "play",
-            took: (s) => s.status === "playing",
-        }),
+        pause: (options) => change("transport", { command: "pause", took: (s) => s.status === "paused" }, options),
+        resume: (options) => change("transport", { command: "play", took: (s) => s.status === "playing" }, options),
         // The end of the queue goes idle; repeat-track restarts it.
-        next: () => change(`once-${++once}`, {
+        next: (options) => change(`once-${++once}`, {
             command: "skip_next",
             took: (s, b, at) => newTrack(s, b) ||
                 (s.status === "idle" && b.status !== "idle") ||
                 restarted(s, b, at),
-        }),
-        prev: () => change(`once-${++once}`, {
+        }, options),
+        prev: (options) => change(`once-${++once}`, {
             command: "skip_prev",
             took: (s, b, at) => newTrack(s, b) || restarted(s, b, at),
-        }),
-        async seek(ms) {
+        }, options),
+        async seek(ms, options) {
             if (!Number.isFinite(ms) || ms < 0)
                 throw invalid(`a position in ms, 0 or more, not ${ms}`);
             return change("seek", {
@@ -523,16 +569,16 @@ export function spotify(config = {}) {
                 fields: { position_ms: ms },
                 took: (s, b) => s.position !== b.position &&
                     Math.abs((s.position?.ms ?? -Infinity) - ms) < 2000,
-            });
+            }, options);
         },
-        async setVolume(volume) {
+        async setVolume(volume, options) {
             if (!Number.isFinite(volume) || volume < 0 || volume > 100)
                 throw invalid(`volume is 0–100, not ${volume}`);
             if (inactive())
                 throw new ConnectorError("the speaker is not the active Spotify device, so Soloist would drop this; activate it first (`home spotify activate`; its volume may jump to the level last saved)", { code: "inactive" });
-            return volumeTo(Math.round(cap === undefined ? volume : Math.min(volume, cap)));
+            return volumeTo(Math.round(cap === undefined ? volume : Math.min(volume, cap)), options);
         },
-        async queue(track) {
+        async queue(track, options) {
             const uri = toSpotifyUri(track);
             if (!uri?.startsWith("spotify:track:"))
                 throw invalid(`only a Spotify track can be queued, not ${track}`);
@@ -540,14 +586,14 @@ export function spotify(config = {}) {
                 command: "add_to_queue",
                 fields: { uri },
                 took: (s) => !!s.upNext?.some((t) => t.uri === uri),
-            });
+            }, options);
         },
-        setShuffle: (on) => change("shuffle", {
+        setShuffle: (on, options) => change("shuffle", {
             command: "set_shuffle",
             fields: { enabled: on },
             took: (s) => s.shuffle === on,
-        }),
-        async setRepeat(mode) {
+        }, options),
+        async setRepeat(mode, options) {
             // developer.spotify.com/documentation/soloist/reference/websocket-api: clear the other mode first, then set this one.
             if (!Object.hasOwn(REPEAT_ORDER, mode))
                 throw invalid(`repeat is off, context or track, not ${mode}`);
@@ -557,18 +603,17 @@ export function spotify(config = {}) {
                 fields: { enabled: first[1] },
                 then: { command: second[0], fields: { enabled: second[1] } },
                 took: (s) => s.repeat === mode,
-            });
+            }, options);
         },
-        interrupt(fn) {
+        interrupt(fn, options) {
+            if (options?.dryRun)
+                return dryAside(fn, interruptSkip(), "pause the music, then resume it");
             let track;
             let shown = false; // the pause showed
             return aside("interrupt", fn, async () => {
-                const no = notPlaying();
+                const no = interruptSkip();
                 if (no)
                     return no;
-                // "playing" while inactive is the account playing on another speaker (live, 2026-11-10): a pause would stop that one.
-                if (inactive())
-                    return "it is not the active device, so the music playing is on another speaker";
                 track = state.track?.uri;
                 try {
                     shown = (await actions.pause()).confirmed; // a pause that never shows still runs fn: what interrupts matters more
@@ -597,21 +642,17 @@ export function spotify(config = {}) {
                 }
             });
         },
-        duck(fn, { to }) {
+        duck(fn, { to, dryRun }) {
             if (!Number.isFinite(to) || to < 0 || to > 100)
                 return Promise.reject(invalid(`duck's volume is 0–100, not ${to}`));
+            if (dryRun)
+                return dryAside(fn, duckSkip(to), `lower the volume from ${state.volume} to ${Math.round(to)}, then put it back`);
             let earlier = 0;
             let shown = false; // the lowered volume showed
             return aside("duck", fn, async () => {
-                const no = notPlaying();
+                const no = duckSkip(to);
                 if (no)
                     return no;
-                if (inactive())
-                    return "it is not the active device, so its volume can't be changed";
-                if (state.volume === undefined)
-                    return "its volume is not known";
-                if (state.volume <= to)
-                    return `it was already at ${state.volume}`;
                 earlier = state.volume;
                 try {
                     shown = (await volumeTo(Math.round(to))).confirmed;

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

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { ConnectorError } from "../../connector.ts";
-/** 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 declare class UpError extends ConnectorError {
 }
 declare const TransactionResource: z.ZodObject<{

package/dist/connectors/up/client.js

@@ -3,7 +3,7 @@ import { ConnectorError, fetchTimeout, getJson } from "../../connector.js";
 // Up Bank's API v1 (https://developer.up.com.au/, spec github.com/up-banking/api, v1/openapi.json). Field names checked
 // against one live read, 2026-10-16. Every field optional so a change degrades a reading rather than throwing.
 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/dist/connectors/up/index.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { asOf, realClock } from "../../clock.js";
-import { errorText } from "../../connector.js";
+import { errorText, isRejectedKey } from "../../connector.js";
 import { envName } from "../../home.js";
 import { poller } from "../../poll.js";
 import { upClient, UpError, } from "./client.js";
@@ -139,7 +139,7 @@ export function up(config) {
                 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/dist/connectors/weather/google.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ConnectorError, fetchTimeout } from "../../connector.js";
+import { ConnectorError, fetchTimeout, isRejectedKey, } from "../../connector.js";
 import { RAIN_INTENSITIES } from "./rain.js";
 import { sunDisagrees } from "./sun.js";
 import { HOURLY_MINUTES, iso, nextPoll, num, RAIN_HORIZON_MINUTES, USER_AGENT, } from "./source.js";
@@ -360,7 +360,7 @@ export function google(options) {
                     ? error
                     : {};
                 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",