@khalido/home 0.1.0 → 0.1.2

package/src/connectors/spotify/index.ts

@@ -99,9 +99,11 @@ export type Aside<T> = { value: T; music: Music; why?: string };
 /**
  * The writes, on the object `spotify()` returns. Each resolves once Soloist reports the change it asked for, with the state
  * then (`confirmed: true`), or after `CONFIRM_MS` with the state as it stands (`confirmed: false`). Each rejects with a
- * `ConnectorError` whose `code` is `offline`, `waiting` (nobody has picked the speaker), `refused`, `timeout` or `invalid`.
+ * `ConnectorError` whose `code` is `offline`, `waiting` (nobody has picked the speaker), `inactive` (`setVolume` on a speaker that isn't the active device: `activate()` first), `refused`, `timeout` or `invalid`.
  */
 export type SpotifyActions = {
+  /** Make this the account's active Spotify device. Soloist drops volume changes until it is. It makes a new audio stream, so the volume can jump to the level last saved. */
+  activate(): Promise<Applied>;
   /** Play a Spotify link or URI (track, album, playlist, artist, episode, show), or resume what is loaded when none is given. */
   play(linkOrUri?: string): Promise<Applied>;
   pause(): Promise<Applied>;
@@ -137,10 +139,12 @@ const COMMAND_TIMEOUT_MS = 3000;
 const QUERY_TIMEOUT_MS = 1000;
 /** A socket that has said nothing this long after opening is closed: Soloist sends `auth_state` at once on connect. */
 const HELLO_MS = 10_000;
-/** After an idle → playing change, a volume above the cap is lowered for this long: the volume can come before or after the status (issue #23). */
+/** After a start signal, a volume above the cap is lowered for this long: the volume can come before or after the status (issue #23). */
 const CAP_WINDOW_MS = 10_000;
 /** How long a write waits for Soloist to report the change it asked for. Loopback events arrive in milliseconds; a stated guess. */
 const CONFIRM_MS = 2000;
+/** Between the two halves of `setRepeat`: back to back left repeat on `track`, 600 ms apart worked (live, 2026-11-09). */
+const REPEAT_GAP_MS = 600;
 /** Between two commands. Soloist publishes no limit; it is on loopback; a stated guess. */
 const WRITE_GAP_MS = 100;
 /** While playing, a stall check this often: one `get_state`. Soloist issue #5 reports stalls 71–150 s into a track; a stated guess. */
@@ -149,6 +153,8 @@ const STALL_CHECK_MS = 20_000;
 const OVERRUN_MS = 15_000;
 /** After a repair's seek, how long before looking whether the position moves again. */
 const REPAIR_WAIT_MS = 5000;
+/** A reported volume is rounded (phone steps are sixteenths: 43.75 shows as 44), so "it took" allows this much. */
+const VOLUME_SLACK = 1;
 const MIN_BACKOFF_MS = 1000;
 const MAX_BACKOFF_MS = 60_000;
 
@@ -190,15 +196,17 @@ export function spotify(
 
   let state: SpotifyState = { asOf: asOf(clock) };
   let socket: SocketLike | undefined;
-  let open = false;
-  let heard = false; // an auth_state on this socket: until then the part stays connecting
-  let whole = false; // signed in, the first playback_state has come too (or HELLO_MS passed): a one-shot read sees the track
+  // This socket's progress. "heard": signed in, the first playback_state still to come. "whole": a one-shot read sees the track (or HELLO_MS passed).
+  let link: "down" | "open" | "heard" | "whole" = "down";
+  const isOpen = () => link !== "down";
   let down: string | undefined; // why the last socket ended, while there is none open
   let statusKnown = false; // Soloist has told this socket its status: only then is idle → playing an edge
   let queueAsked = false; // get_queue sent on this socket
   let signedIn = false; // signed out → in on this socket: the first status after it counts as a start if it is playing
   let capUntil = -Infinity;
-  let capped = false; // the cap has been sent in this window
+  let capped = false; // the cap took in this window
+  let capping = false; // a lowering is on its way
+  let startBuffering = false; // a start from idle is still buffering
   let capNote: string | undefined; // the last first-play lowering, in `anomaly` until the speaker goes idle
   let frameNote: string | undefined; // a frame the schema rejected, or an error nothing was waiting for
   let note: string | undefined; // a write the integration made itself that failed (the cap, interrupt's resume), in `detail`
@@ -213,11 +221,10 @@ export function spotify(
   const publish = () => {
     let status: Status;
     let detail: string | undefined;
-    if (!open)
+    if (link === "down")
       ((status = reported || down ? "disconnected" : "connecting"),
         (detail = down));
-    else if (!heard || (state.loggedIn === true && !whole))
-      status = "connecting";
+    else if (link !== "whole") status = "connecting";
     else
       ((status = "connected"),
         (detail = state.loggedIn === false ? WAITING : note));
@@ -250,7 +257,7 @@ export function spotify(
   ) =>
     new Promise<void>((resolve, reject) => {
       const s = socket;
-      if (!s || !open || s.readyState !== OPEN) return reject(offline());
+      if (!s || !isOpen() || s.readyState !== OPEN) return reject(offline());
       if (state.loggedIn === false && !answers)
         return reject(new ConnectorError(WAITING, { code: "waiting" }));
       const stop = new AbortController();
@@ -290,12 +297,20 @@ export function spotify(
     answers?: string;
     then?: { command: string; fields: Record<string, unknown> };
     took?: (now: SpotifyState, before: SpotifyState, at: number) => boolean;
+    activeFirst?: boolean; // an inactive speaker goes active before this, in this write's own turn so the last transport write still wins
   };
   const send = async (body: Body) => {
+    if (body.activeFirst && inactive()) {
+      await command("activate").catch(() => {}); // best effort: the write itself says how it went
+      await waitFor(() => state.active === true || !isOpen(), CONFIRM_MS);
+    }
     const before = state;
     const at = clock.now();
     await command(body.command, body.fields, body.answers);
-    if (body.then) await command(body.then.command, body.then.fields); // repeat's second half, still this write's turn
+    if (body.then) {
+      await clock.sleep(REPEAT_GAP_MS);
+      await command(body.then.command, body.then.fields); // repeat's second half, still this write's turn
+    }
     return { before, at };
   };
   let once = 0; // skips and queued tracks never merge: two nexts are two skips
@@ -308,7 +323,7 @@ export function spotify(
   const change = async (slot: string, body: Body): Promise<Applied> => {
     const sent = await write(slot, body);
     const took = () => body.took?.(state, sent.before, sent.at) ?? true;
-    await waitFor(() => took() || !open, CONFIRM_MS);
+    await waitFor(() => took() || !isOpen(), CONFIRM_MS);
     return { state, confirmed: took() };
   };
   /** The track restarted: a new anchor near 0 when it had been 5 s or more in (a prev past the first seconds, a next on repeat-track). */
@@ -320,12 +335,17 @@ export function spotify(
     !!s.track && s.track.uri !== b.track?.uri;
   const invalid = (message: string) =>
     new ConnectorError(message, { code: "invalid" });
+  const near = (volume: number | undefined, v: number) =>
+    volume !== undefined && Math.abs(volume - v) <= VOLUME_SLACK;
   const volumeTo = (v: number) =>
     change("volume", {
       command: "set_volume",
       fields: { volume: v },
-      took: (s) => s.volume === v,
+      took: (s) => near(s.volume, v),
     });
+  /** Soloist accepts a `set_volume` while it isn't the active device and drops it (three times live, 2026-11-09). */
+  const inactive = () =>
+    isOpen() && state.loggedIn !== false && state.active === false;
   /** Ask Soloist for something, through the lane; the same query twice merges. A refusal is an anomaly, a drop is the status's to say. */
   const ANSWERS = {
     get_state: "playback_state",
@@ -352,27 +372,49 @@ export function spotify(
       publish();
     });
 
-  /** Within the window after idle → playing, a volume above the cap is lowered to it, once (issue #23). */
+  /**
+   * Within the window after a start signal, a volume above the cap is lowered to it (issue #23). Only while active, since
+   * Soloist drops it otherwise, and retried until Soloist reports it. A volume raised after that is someone's choice;
+   * one raised before it is reported can't be told from the start's own jump, so it is lowered too.
+   */
   const applyCap = () => {
     if (
       cap === undefined ||
       capped ||
+      capping ||
       state.volume === undefined ||
-      clock.now() > capUntil ||
-      state.volume <= cap
+      state.volume <= cap + VOLUME_SLACK ||
+      state.active === false ||
+      clock.now() > capUntil
     )
       return;
-    capped = true;
-    capNote = `started at volume ${state.volume}, above maxVolume ${cap}; lowered it (Soloist issue #23)`;
-    change("volume", {
-      command: "set_volume",
-      fields: { volume: cap },
-      took: (s) => s.volume === cap,
-    }).catch(
-      (error) => (
-        (note = `lowering the volume to ${cap} failed: ${errorText(error)}`),
-        publish()
-      ),
+    capping = true;
+    const from = state.volume;
+    const window = capUntil;
+    volumeTo(cap).then(
+      ({ confirmed }) => {
+        capping = false;
+        if (capUntil !== window) return applyCap(); // a new start while it went: this lowering doesn't speak for that one
+        if (confirmed) {
+          capped = true;
+          if (state.status === "idle") return;
+          capNote = `started at volume ${from}, above maxVolume ${cap}; lowered it (Soloist issue #23)`;
+          note = undefined;
+          return publish();
+        }
+        if (clock.now() > capUntil) {
+          note = `could not lower the volume to ${cap}: Soloist has not reported it`;
+          return publish();
+        }
+        applyCap();
+      },
+      (error) => {
+        capping = false;
+        if (error instanceof ConnectorError && error.code === "offline") return; // the status says it
+        capped = true; // refused or unanswered: not again this window
+        note = `lowering the volume to ${cap} failed: ${errorText(error)}`;
+        publish();
+      },
     );
   };
 
@@ -410,11 +452,16 @@ export function spotify(
     }
     const before = state.status;
     const wasSignedIn = state.loggedIn;
+    const wasActive = link === "open" ? undefined : state.active; // the first frames on a socket are not a change
     state = fold(state, f, asOf(clock));
+    if (state.track?.uri !== repairedFor) repairedFor = undefined; // one repair per play of a track
+    // Going active makes a new stream, at WirePlumber's saved level (live, 2026-11-09): the likeliest moment for a loud start.
+    if (wasActive === false && state.active === true)
+      ((capUntil = clock.now() + CAP_WINDOW_MS), (capped = false));
     if (f.type === "auth_state") {
       // Signed out there is no playback_state to wait for, and a later sign-in must not send the part back to connecting.
-      if (!heard && f.logged_in !== true) whole = true;
-      heard = true;
+      if (link === "open" || (link === "heard" && f.logged_in === false))
+        link = f.logged_in === true ? "heard" : "whole";
       if (f.logged_in === false) statusKnown = false;
       // A first sign-in (someone picked the speaker) sends only auth_state; the docs don't promise a playback_state after it.
       else if (f.logged_in === true && wasSignedIn === false)
@@ -422,17 +469,21 @@ export function spotify(
     }
     if (f.type === "playback_state") {
       if (!queueAsked) ((queueAsked = true), query("get_queue", { limit: 10 })); // queue_changed pushes changes only, so ask once per socket
-      whole = true;
+      link = "whole";
     }
     if (pending?.answers === f.type) pending.finish();
     if (
       (f.type === "playback_state" || f.type === "playback_changed") &&
       f.status !== undefined
     ) {
-      // A start is idle → playing, or a sign-in whose first status is playing: a phone picked the speaker and played (issue #23).
+      // A start is idle → playing or buffering, or a sign-in whose first status is either: a phone picked the speaker and played.
+      // The volume can land just after `playing` (issue #23), so a start through buffering opens the window again then.
       const started =
-        f.status === "playing" && (statusKnown ? before === "idle" : signedIn);
+        ((f.status === "playing" || f.status === "buffering") &&
+          (statusKnown ? before === "idle" : signedIn)) ||
+        (f.status === "playing" && startBuffering);
       if (started) ((capUntil = clock.now() + CAP_WINDOW_MS), (capped = false));
+      startBuffering = f.status === "buffering" && (started || startBuffering);
       signedIn = false;
       if (f.status === "idle") capNote = undefined;
       statusKnown = true;
@@ -465,13 +516,12 @@ export function spotify(
         quiet.abort();
         signal.removeEventListener("abort", stop);
         if (socket === s) socket = undefined;
-        const was = open;
-        open = false;
-        heard = false;
-        whole = false;
+        const was = isOpen();
+        link = "down";
         queueAsked = false;
         statusKnown = false;
         signedIn = false;
+        startBuffering = false;
         pending?.finish(offline());
         for (const w of [...waiters]) w(); // a write waiting to confirm stops waiting
         seen = undefined;
@@ -479,21 +529,23 @@ export function spotify(
       };
       const stop = () => (end("stopped"), s.close());
       signal.addEventListener("abort", stop, { once: true });
+      // An ended socket's late events belong to no session: they must not touch the next socket's state.
       s.onopen = () => {
-        open = true;
+        if (ended) return;
+        link = "open";
         down = undefined;
         note = undefined; // a new socket: what failed on the last one is history
         void clock.sleep(HELLO_MS, quiet.signal).then(() => {
           if (quiet.signal.aborted) return;
-          if (!heard)
+          if (link === "open")
             return (
               end(`Soloist said nothing in ${HELLO_MS / 1000} s`),
               s.close()
             );
-          if (!whole) ((whole = true), publish()); // signed in, no playback_state: connected with what there is
+          if (link === "heard") ((link = "whole"), publish()); // signed in, no playback_state: connected with what there is
         });
       };
-      s.onmessage = (ev) => handle(ev.data);
+      s.onmessage = (ev) => void (ended || handle(ev.data));
       s.onerror = () => {}; // onclose follows and says it
       s.onclose = () => end("Soloist closed the socket");
     });
@@ -510,7 +562,7 @@ export function spotify(
 
   /** Not connected or not playing: the reason `duck` and `interrupt` just run `fn`. */
   const notPlaying = () =>
-    !open
+    !isOpen()
       ? "Soloist is not connected"
       : state.status === "playing" || state.status === "buffering"
         ? undefined
@@ -536,7 +588,7 @@ export function spotify(
     leave: () => Promise<Left>,
   ) => {
     const run = async (): Promise<Aside<T>> => {
-      if (open) marked(kind);
+      if (isOpen()) marked(kind);
       try {
         return await within();
       } finally {
@@ -570,10 +622,20 @@ export function spotify(
         };
 
   const actions: SpotifyActions = {
+    async activate() {
+      if (isOpen() && state.loggedIn !== false && state.active === true)
+        return { state, confirmed: true }; // a second activate might make a new stream
+      return change("activate", {
+        command: "activate",
+        took: (s) => s.active === true,
+      });
+    },
+    // A `play` while inactive didn't take live; going active first is untested for this. `resume` worked inactive, so it doesn't.
     async play(linkOrUri) {
       if (linkOrUri === undefined)
         return change("transport", {
           command: "play",
+          activeFirst: true,
           took: (s) => s.status === "playing",
         });
       const uri = toSpotifyUri(linkOrUri);
@@ -581,6 +643,7 @@ export function spotify(
       return change("transport", {
         command: "play",
         fields: { uri },
+        activeFirst: true,
         took: (s) =>
           s.status === "playing" &&
           (s.track?.uri === uri || s.context?.uri === uri),
@@ -624,6 +687,11 @@ export function spotify(
     async setVolume(volume) {
       if (!Number.isFinite(volume) || volume < 0 || volume > 100)
         throw invalid(`volume is 0–100, not ${volume}`);
+      if (inactive())
+        throw new ConnectorError(
+          "the speaker is not the active Spotify device, so Soloist would drop this; activate it first (`home spotify activate`; its volume may jump to the level last saved)",
+          { code: "inactive" },
+        );
       return volumeTo(
         Math.round(cap === undefined ? volume : Math.min(volume, cap)),
       );
@@ -704,6 +772,8 @@ export function spotify(
         async () => {
           const no = notPlaying();
           if (no) return no;
+          if (inactive())
+            return "it is not the active device, so its volume can't be changed";
           if (state.volume === undefined) return "its volume is not known";
           if (state.volume <= to) return `it was already at ${state.volume}`;
           earlier = state.volume;
@@ -716,7 +786,7 @@ export function spotify(
           }
         },
         async () => {
-          if (state.volume !== Math.round(to))
+          if (!near(state.volume, Math.round(to)))
             return {
               music: "kept",
               why: shown
@@ -758,7 +828,7 @@ export function spotify(
     state = rest;
   }
   let seen: { track: string; ms: number; atMs: number } | undefined; // the last check's reported position
-  let repairedFor: string | undefined; // at most one repair per track
+  let repairedFor: string | undefined; // at most one repair per play of a track
   /** Ask Soloist where it is, waiting for the answer (or the query's timeout). */
   const fresh = () =>
     write("query-get_state", {
@@ -785,7 +855,7 @@ export function spotify(
     a.track === b.track &&
     b.atMs - a.atMs >= gap &&
     Math.abs(b.ms - a.ms) < 1000;
-  const playing = () => open && state.status === "playing" && !state.aside;
+  const playing = () => isOpen() && state.status === "playing" && !state.aside;
 
   /** One look while playing: a fresh position, then frozen, overrun, recovered or fine (Soloist issue #5). */
   const checkStall = async () => {
@@ -829,7 +899,7 @@ export function spotify(
       state.stalled && stallAs({ ...state.stalled, tried: what });
     // Still ours to fix: playing this track, stalled, and no duck, interrupt or person in between.
     const ours = () =>
-      open &&
+      isOpen() &&
       state.status === "playing" &&
       state.track?.uri === track &&
       state.stalled?.track === track &&
@@ -867,9 +937,11 @@ export function spotify(
     /** Ask Soloist for its state again (`get_state`, or `get_auth_state` without a session); while it is unreachable, reconnect now. */
     refresh() {
       const s = socket;
-      if (s && open && s.readyState === OPEN)
+      if (s && isOpen() && s.readyState === OPEN)
         return query(
-          state.loggedIn === false || !heard ? "get_auth_state" : "get_state",
+          state.loggedIn === false || link === "open"
+            ? "get_auth_state"
+            : "get_state",
         );
       wake?.abort();
     },

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 })`): 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 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/index.ts

@@ -241,13 +241,16 @@ export function toSnapshot(
   };
 }
 
-/** Up as a home integration: two months of transactions now, then every 15 minutes. Reads only; it never writes. */
-export function up(config: UpConfig): Integration<UpSnapshot, "up"> {
+/** Up as a home integration: two months of transactions now, then every 15 minutes. The integration only reads; `client` is there for a consumer's writes. */
+export function up(config: UpConfig): Integration<UpSnapshot, "up"> & {
+  client: UpClient;
+} {
   const client = upClient(config);
   const clock = config.clock ?? realClock;
   const poll = poller(clock);
   return {
     name: "up",
+    client,
     refresh: poll.nudge,
     async run(signal, update) {
       let last: UpSnapshot | undefined;

package/src/connectors/weather/README.md

@@ -68,7 +68,7 @@ Plain `fetch` cannot read `ftp://` (Bun 1.4.2: "protocol must be http:, https: o
 
 **Sun** (`sun.ts`). `sunNow` with [suncalc](https://github.com/mourner/suncalc) 2.1.1, which bundles its own types (degrees, azimuth clockwise from north; `@types/suncalc` describes v1 and is wrong for it). Times are for the local solar day containing `at`. On 2026-10-13 it matched BOM's own Sydney sunrise and sunset to the second. Dawn and dusk are civil (6° below the horizon), `nightEnd` and `night` astronomical (18°), `goldenHour` starts the evening's and `goldenHourEnd` ends the morning's (6° above). `rising` is before solar noon, which in suncalc's solar day means from solar midnight; `daylight` is altitude above 0°. **`sunNow(latitude, longitude, now)` is the owner**: the snapshot's `sun` is recomputed every 5 minutes, so a consumer showing `rising`, `daylight`, `next` or the position calls `sunNow` with its own clock, as `home status` does. `next` holds each of dawn, sunrise, sunset and dusk at its next occurrence after `at` (today's while still ahead, else tomorrow's), missing on a day that has none. The computed sun is the owner: Google's daily `sunEvents` are parsed only to check it, and a sunrise or sunset more than 2 minutes from the computed one (`sunDisagrees`, comparing within the solar day containing Google's time) goes into Google's `anomaly`, never into the sun.
 
-Every request has a 10 s timeout and the user agent `home (+https://github.com/khalido/home)`: BOM's app API gives Bun's default `Bun/1.4.2` no answer at all, so nothing here relies on the default.
+Every request has a 10 s timeout and the user agent `home (+https://github.com/khalido/home.ts)`: BOM's app API gives Bun's default `Bun/1.4.2` no answer at all, so nothing here relies on the default.
 
 ## Not built, on purpose
 

package/src/connectors/weather/index.ts

@@ -246,19 +246,35 @@ export function weather(
 /** "20:20" in the home's time zone (the runtime's when unset), or "?". */
 const hhmmIn = (iso: string | undefined, timeZone?: string) =>
   iso ? localTime(Date.parse(iso), timeZone) : "?";
-const day = (d?: ForecastDay) =>
+const day = (d?: ForecastDay, rainLeft?: number) =>
   d
     ? [
         d.minC === undefined && d.maxC === undefined
           ? ""
           : `${d.minC ?? "?"}–${d.maxC ?? "?"} °C`,
         d.text?.replace(/\.$/, "").toLowerCase() ?? "",
-        d.rainChance === undefined ? "" : `${d.rainChance}% chance of rain`,
+        d.rainChance === undefined
+          ? ""
+          : rainLeft !== undefined && rainLeft < d.rainChance
+            ? `${rainLeft}% chance of rain the rest of the day`
+            : `${d.rainChance}% chance of rain`,
       ]
         .filter(Boolean)
         .join(" ")
     : "?";
 
+/** The highest hourly chance left today, all 24 hours of it, when the hourly forecast is the same source and day as the forecast: sources are never mixed. */
+const rainLeftToday = (
+  w: Pick<Slices, "forecast" | "hourly"> & { timeZone?: string },
+  at: number,
+) => {
+  if (!w.hourly || w.hourly.source !== w.forecast?.source) return undefined;
+  const rest = dayBlocks(w.hourly, at, w.timeZone, [
+    { name: "rest", from: 0, to: 24 },
+  ])?.today[0];
+  return rest?.date === w.forecast.today?.date ? rest?.rainChance : undefined;
+};
+
 /** "rain in 30 min, ends in 55 min, 70%, 0.8 mm, moderate (google)", "raining, ends in 25 min", or "no rain for 2 h"; nothing when the forecast covers none of the window. */
 export function rainText(
   rain: Slices["rain"],
@@ -310,7 +326,7 @@ export function weatherText(
     : "";
   const f = w.forecast;
   const forecast = f
-    ? `today ${day(f.today)}, tomorrow ${day(f.tomorrow)} (${f.source}${f.modelled ? " modelled" : ""})`
+    ? `today ${day(f.today, rainLeftToday(w, Date.parse(sun.at)))}, tomorrow ${day(f.tomorrow)} (${f.source}${f.modelled ? " modelled" : ""})`
     : "";
   const k = w.sky;
   const skyParts = k

package/src/discover.ts

@@ -307,6 +307,7 @@ export type CachedAddress = {
   host: string;
   port?: number;
   name?: string;
+  model?: string; // Cast: what kind of device, without a discovery
   seenAt: string;
 };
 
@@ -345,7 +346,7 @@ export function addressBook(
     seen(
       connector: Connector,
       id: string | undefined,
-      address: { host: string; port?: number; name?: string },
+      address: { host: string; port?: number; name?: string; model?: string },
     ): void {
       if (!cache || id === undefined) return;
       const key = addressKey(connector, id);
@@ -355,14 +356,17 @@ export function addressBook(
         c.host === address.host &&
         c.port === address.port &&
         isFresh(c) &&
-        (!address.name || address.name === c.name)
+        (!address.name || address.name === c.name) &&
+        (!address.model || address.model === c.model)
       )
         return;
       const name = address.name || c?.name;
+      const model = address.model || c?.model;
       entries[key] = {
         host: address.host,
         ...(address.port === undefined ? {} : { port: address.port }),
         ...(name ? { name } : {}),
+        ...(model ? { model } : {}),
         seenAt: new Date(now()).toISOString(),
       };
       cache.write({ ...entries });
@@ -374,7 +378,8 @@ export function addressBook(
 /**
  * Run one discovery `passes` times, `gapMs` apart, and return the union (first answer wins). `onPass` sees each pass's
  * additions as they come; `done` ends it early once what was looked for has answered. A pass that throws adds nothing;
- * when every pass threw, discovery never ran, so it throws the last error rather than reporting nothing found.
+ * when every pass threw, discovery never ran, so it throws the last error rather than reporting nothing found. An error
+ * `stopOn` accepts is thrown at once: no later pass could do better.
  */
 export async function discover<T = Found>(
   pass: () => Promise<T[]>,
@@ -384,6 +389,7 @@ export async function discover<T = Found>(
     gapMs?: number;
     key?: (t: T) => string;
     done?: (all: T[]) => boolean;
+    stopOn?: (error: unknown) => boolean;
     onPass?: (n: number, added: T[]) => void;
     signal?: AbortSignal;
   },
@@ -401,9 +407,11 @@ export async function discover<T = Found>(
       );
     if (options.signal?.aborted) break;
     ran++;
-    const answers = await pass().catch(
-      (error) => (errors.push(error), [] as T[]),
-    );
+    const answers = await pass().catch((error) => {
+      if (options.stopOn?.(error)) throw error;
+      errors.push(error);
+      return [] as T[];
+    });
     const added = answers.filter((t) => !all.has(key(t)) && all.set(key(t), t));
     options.onPass?.(n, added);
     if (options.done?.([...all.values()])) break;

package/src/energy.ts

@@ -1,6 +1,7 @@
 import type { AmberState, PriceInterval } from "./connectors/amber/client.ts";
 import type { EnphaseState } from "./connectors/enphase/client.ts";
 import type { EnphaseSnapshot } from "./connectors/enphase/index.ts";
+import { kw } from "./manifest.ts";
 
 /** The home's energy right now: power from Enphase, prices from Amber, and what the grid flow costs per hour. */
 export type EnergyNow = {
@@ -112,7 +113,6 @@ export function solarLevel(
  * "balanced (-10 W)", or "" with no grid reading. Rounded for reading only; the numbers above stay as read.
  */
 export function gridText(now: EnergyNow): string {
-  const kw = (w: number) => `${(w / 1000).toFixed(1)} kW`;
   const rate = (c: number | undefined, positive: string, negative: string) =>
     c === undefined
       ? ""

package/src/finders.ts

@@ -31,6 +31,9 @@ import {
 // does not slow a scan. Without the tool the mDNS finders throw, naming it, rather than "nothing answered".
 // `fileCache` keeps the addresses discovery found in a file between runs, so the next run connects straight away.
 
+/** The system's mDNS tool is not installed: discovery can't run until it is. */
+export class MissingTool extends Error {}
+
 /**
  * Run a long-lived `dns-sd` query (or `avahi-browse`, by `command`) and return what it printed. It never exits by itself, so it is stopped once `done`
  * says the answer is in, or `quietMs` after the last output, or at `maxMs`. The system's mDNS cache usually answers in
@@ -68,11 +71,11 @@ export function dnsSd(
     proc.on("error", (error: NodeJS.ErrnoException) => {
       (clearTimeout(timer), clearTimeout(quiet));
       reject(
-        new Error(
-          error.code === "ENOENT"
-            ? `${command} not found; mDNS discovery needs it${install ? ` (${install})` : ""}`
-            : `${command}: ${error.message}`,
-        ),
+        error.code === "ENOENT"
+          ? new MissingTool(
+              `${command} not found; mDNS discovery needs it${install ? ` (${install})` : ""}`,
+            )
+          : new Error(`${command}: ${error.message}`),
       );
     });
     proc.on("close", finish);