@khalido/home 0.1.3 → 0.2.1

package/src/connectors/enphase/index.ts

@@ -1,4 +1,5 @@
 import { type Clock, localDay, realClock } from "../../clock.ts";
+import { isRejectedKey } from "../../connector.ts";
 import { z } from "zod";
 import {
   type DeviceRecord,
@@ -180,7 +181,7 @@ export function enphase(
           });
         } catch (error) {
           if (signal.aborted) return; // stopped mid-read: not a failure
-          if (error instanceof EnphaseError && error.status === 401)
+          if (isRejectedKey(error))
             return update({
               status: "unavailable",
               reason: "auth",

package/src/connectors/hue/README.md

@@ -4,26 +4,45 @@ Philips Hue over the bridge's local CLIP v2 API: HTTPS on the LAN, one key, one
 
 ## Official docs
 
-Both pages need a free Hue developer login.
+The developer pages need a free Hue developer login.
 
 - [Getting started](https://developers.meethue.com/develop/hue-api-v2/getting-started/): pairing (`POST /api` with `devicetype` and `generateclientkey`), the `hue-application-key` header, the resource URLs.
 - [Core concepts](https://developers.meethue.com/develop/hue-api-v2/core-concepts/): the resource model (devices own services; rooms and zones group them; `grouped_light`, `bridge_home`), the event stream, and the rate guidance.
-- [Using HTTPS](https://developers.meethue.com/develop/application-design-guidance/using-https/): the bridge certificate and Signify's root CA.
+- [Using HTTPS](https://developers.meethue.com/develop/application-design-guidance/using-https/): the bridge certificate and Signify's two root CAs.
+- [Bridge release notes](https://www.philips-hue.com/en-au/support/release-notes/bridge) (no login): what each bridge software version changed.
+
+[docs/hue.md](../../../docs/hue.md) has every link and what each page asks of an app.
 
 The schemas here were checked against [openhue-api](https://github.com/openhue/openhue-api) (Apache-2.0), an OpenAPI spec of CLIP v2, not against Signify's gated pages. Treat every field as unconfirmed from the primary source; all are optional, so a change degrades rather than throws.
 
 ## Pinning
 
-The bridge serves only its leaf certificate, `CN=<bridge id>`, signed by Signify's `root-bridge` CA (valid to 2038-01-19). Trust that CA and nothing else, and check the CN equals your bridge id. Never turn verification off: the key goes out on every request.
+The bridge serves its certificate, `CN=<bridge id>`, signed by one of Signify's two private roots. Trust those two and nothing else, and check the CN equals your bridge id. Never turn verification off: the key goes out on every request. The package carries both roots as `HUE_BRIDGE_ROOT_CA`, the bundle from Signify's page byte for byte; [docs/hue.md](../../../docs/hue.md) has Signify's rules, the fingerprints and what other projects do.
 
-- **Bun**: `bunPinnedFetch(bridgeId, ca)`, which `hue()` uses by default. Measured on Bun 1.4.2: 124 ms cold, 16 ms kept alive; a wrong bridge id is rejected.
-- **Node**: `nodePinnedFetch(bridgeId, ca)` from `@khalido/home/node`, undici's `fetch` with an `Agent` holding `ca` and the same CN check. Checked on Node 24.20 and 26.11 against a local TLS server (2026-10-28), not yet a real bridge.
+- **Bun**: `bunPinnedFetch(bridgeId, ca?)`, which `hue()` uses by default. Measured on Bun 1.4.2: 124 ms cold, 16 ms kept alive.
+- **Node**: `nodePinnedFetch(bridgeId, ca?)` from `@khalido/home/node`, undici's `fetch` with an `Agent` holding the roots and the same CN check. Checked on Node 24.20 and 26.11 against a local TLS server (2026-10-28), not yet a real bridge.
 
-The CA's SHA-256 is `F0:BD:8E:65:09:E8:2F:77:4D:63:BC:00:9D:53:88:C9:69:FE:3D:CF:7D:6D:54:1D:63:51:B7:2B:89:8D:8A:CF`. It comes from a public mirror and passes `openssl verify` against a live BSB002; confirming it against the copy on the developer portal is still to do. It is not in the package yet: pass `ca` yourself (the CLI reads `HUE_CA_FILE`). The plan is a `HUE_BRIDGE_ROOT_CA` export here so pinning is one import.
+`ca` replaces the bundle when given (the config's `ca`, the CLI's `HUE_CA_FILE`); nobody needs it for a real bridge. Live against KO's BSB002 (software 1978545030, Bun 1.4.4, 2026-11-11): the bundle is accepted, the second root alone and a wrong bridge id are refused. A bridge still on a self-signed certificate (software before 1971060010, May 2025) is refused: update it. A Bridge Pro is untried.
 
 ## Pairing
 
-`pair({ host, fetch, deviceType })` makes one `POST /api`. Until someone presses the bridge's link button it throws `HueError` with `code: "link_button"` (bridge error 101). It never retries in a loop; the caller decides how to prompt. Pairing happens once: the key it returns keeps working, and the library never stores it.
+`pair({ host, fetch, deviceType })` makes one `POST /api`. Until someone presses the bridge's link button it throws `HueError` with `code: "link_button"` (bridge error 101). `pairWhenPressed` takes the same and asks every 2 s (`everyMs`) for 30 s (`timeoutMs`), calling `onWaiting` once when the bridge first says the button isn't pressed, so the caller can prompt; then it throws that error. `home pair` uses it with 60 s and a countdown. Pairing happens once: the key it returns keeps working, and the library never stores it. Live, 2026-11-11, KO's BSB002 (Bun 1.4.4): `home pair` timed out with no press, then returned a key once the button was pressed.
+
+## Lights, rooms and scenes
+
+`hueClient` (and `hue().client`) has three writes by name or id, each resolving `{ state, confirmed }`: the light or group as the bridge then reported it, read every half second for at most 3 s (`CONFIRM_MS`). Unconfirmed is a result, not an error.
+
+- `light(name, change)` changes one light; `room(name, change)` every light in a room or zone with one group write.
+- `change` is `{ on?, brightness?, color?, kelvin?, transitionMs? }`, and only what is given is sent. `brightness` is 1–100. `color` is a hex string or `{ r, g, b }`, sent as `xy` moved inside the light's own gamut (a room: its first colour light's). `kelvin` is a white temperature, checked against the light's own range (a room: the widest of its lights'). `color` and `kelvin` are one or the other. `transitionMs` is the fade; the bridge's own is 400 ms.
+- Without `on`, a change to a light that is off turns it on, since an off light takes nothing else; a light already on gets no `on`. A room always gets `on: true`, since some of its lights may be off.
+- `allOff()` turns every light in the home off with one write to the home group; `confirmed` once no light the bridge reaches is on. Fake bridge only, untried live.
+- `scene(name, room?)` recalls a scene. Scene names repeat across rooms, so a name several rooms use needs `room`. `confirmed` is the bridge reporting the scene active.
+- A name is matched whole, in any case. A miss, a name two things share, a value off the range, a colour for a white light: each throws `HueError` with `code: "invalid"` before anything is sent, and a light the bridge has lost throws with `code: "offline"`; a miss lists what exists, and a name two things share lists them with their ids.
+- Confirmation compares on/off, brightness within a point, and on a light the white temperature (within 2 mirek) or the colour (within 0.02 in `xy`). A room reports no colour, so only its on/off and brightness are compared; its brightness is the bridge's figure for the group.
+
+The state has each light's `kelvin` and `kelvinRange`, and on a colour light its `xy`, a `hex` for a screen (the hue at full brightness) and its `gamut`. `colorToXy`, `xyToHex`, `kelvinToMirek` and `mirekToKelvin` are exported. `hueText(view)` is the line.
+
+CLI: `home light <name> [on|off] [<1-100>] [<kelvin>k] [<hex colour>]`, the same for `home room`, and `home scene <name> [in <room>]`, each printing what the bridge then reported. Quote a name with a space. They ran on KO's bridge on 2026-11-11 (below).
 
 ## Events
 
@@ -33,18 +52,44 @@ Unconfirmed: whether the bridge resumes from `Last-Event-ID`; how many streams o
 
 ## Rates
 
-Two write lanes per client (`src/lane.ts`). `grouped_light` and `scene` writes go out 1 s apart, `light` writes 100 ms apart, each lane in order. A write to a resource whose last write is still waiting merges into it (`mergeBody`, the newer field winning), so a burst cannot build a backlog; the merged write keeps the first one's place in the lane. Unverified: which the bridge applies when a merge carries both `color_temperature` and `color`. That is Signify's guidance as secondary sources quote it (about 10 commands a second to lights, 1 a second to groups), unconfirmed from the gated page. Prefer one `grouped_light` or scene write over many light writes: the bridge sends it to every light at once.
+Two write lanes per client (`src/lane.ts`). `grouped_light` and `scene` writes go out 1 s apart, `light` writes 100 ms apart, each lane in order. A write to a resource whose last write is still waiting merges into it (`mergeBody`, the newer field winning), so a burst cannot build a backlog; the merged write keeps the first one's place in the lane. Unverified: which the bridge applies when a merge carries both `color_temperature` and `color`. That is Signify's guidance (about 10 commands a second to lights, 1 a second to groups; its Hue System Performance page, read 2026-11-11; [docs/hue.md](../../../docs/hue.md) has the rest). Prefer one `grouped_light` or scene write over many light writes: the bridge sends it to every light at once.
+
+## First live read (2026-11-11)
+
+KO's BSB002, software 1978545030, Bun 1.4.4, reads only, with the key from `home pair` and the bundled roots.
+
+- `home hue`: connected in 0.47 s. A full read is 177 resources in 286 ms, and every one parsed.
+- 16 lights, 6 rooms, 30 scenes, 2 lights unreachable (shown as not available, reason `offline`). A room with no lights has no on/off and prints its name alone.
+- Every light has `dimming` and `color_temperature`, each with its own mirek range (153–500 on a colour light, 153–454 on a white one). 6 have `color`, with `xy` and their gamut (type C) on the resource, as Signify's page says. `grouped_light` carries `on`, `dimming`, `color_temperature` and `color` too.
+- The event stream: connected at 0.4 s, then nothing from the bridge for 90 s, so the watchdog reconnected and read again at 90.8 s, as designed. With no light changing, that is one full read every 90 s.
+- Untried: any write through the paired key, an event arriving (nothing changed while watching), a move to a new address.
+
+## First live writes (2026-11-11)
+
+KO's BSB002 at his request, Bun 1.4.4, every light put back as it was.
+
+- **A room of four white lights:** brightness, a white temperature, off and on each confirmed in 0.8–1.4 s (a read, the write, a read). Each light restored one by one read exactly as before.
+- **A room of three colour lights, one unreachable, through the CLI:** on at 50% and 2700 K, a colour on each reachable light (`ff8800` and `0044ff` read back as exactly those), a colour for the room, a scene by name and room, then off. All confirmed, each command about 1 s. The unreachable light did not stop the room confirming.
+- **A fade does not delay confirmation:** with `transitionMs: 1500` the bridge reported the target at once. Ten room writes 2 s apart over 20 s all confirmed.
+- **A light the bridge has lost:** it accepted the write and answered "has communication issues, command may not have effect", naming the light by id. `light` now refuses first, by name, with `code: "offline"`.
+- **A scene name three rooms use** listed the three with their rooms and exited 2.
+- **A group's brightness is the bridge's own average:** after a room write to 40%, one light read 46% and the group 42%. Passed through as reported.
+- Untried: zones, a white temperature on a room that mixes ranges, an event arriving on the stream after a write, effects and gradients (not built).
+
+## Dry run (2026-11-12)
+
+`light`, `room`, `scene` and `allOff` take `{ dryRun: true }` last: the read, every check before sending, and `wouldSend` (`{ method, path, body }`); nothing sent. On KO's bridge (Bun 1.4.4): `home room "Living room" 40 2700k --dry-run`, `home lights off --dry-run` and `home scene Relax --dry-run` (which listed the three rooms with a Relax) printed their requests and changed no light.
 
 ## Sources
 
 What this folder learned from, and on what terms. No code was copied.
 
-| Source                                                                                                           | Licence                      | Used for                             |
-| ---------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------ |
-| [Signify's Hue API docs](https://developers.meethue.com/develop/hue-api-v2/)                                     | Developer terms, login-gated | the API itself                       |
-| [openhue/openhue-api](https://github.com/openhue/openhue-api)                                                    | Apache-2.0                   | resource and event-stream shapes     |
-| [Home Assistant `hue` integration](https://github.com/home-assistant/core/tree/dev/homeassistant/components/hue) | Apache-2.0                   | how HA wires aiohue into entities    |
-| [home-assistant-libs/aiohue](https://github.com/home-assistant-libs/aiohue)                                      | Apache-2.0                   | reconnect behaviour                  |
-| [jash90/lumen-desktop](https://github.com/jash90/lumen-desktop)                                                  | MIT                          | the public copy of Signify's root CA |
-| [jdmg94/Hue-Sync](https://github.com/jdmg94/Hue-Sync)                                                            | Apache-2.0                   | resource types, cross-checked        |
-| [vchlum/smart-home](https://github.com/vchlum/smart-home)                                                        | MIT                          | a compact CLIP v2 event loop         |
+| Source                                                                                                           | Licence                      | Used for                                |
+| ---------------------------------------------------------------------------------------------------------------- | ---------------------------- | --------------------------------------- |
+| [Signify's Hue API docs](https://developers.meethue.com/develop/hue-api-v2/)                                     | Developer terms, login-gated | the API itself                          |
+| [openhue/openhue-api](https://github.com/openhue/openhue-api)                                                    | Apache-2.0                   | resource and event-stream shapes        |
+| [Home Assistant `hue` integration](https://github.com/home-assistant/core/tree/dev/homeassistant/components/hue) | Apache-2.0                   | how HA wires aiohue into entities       |
+| [home-assistant-libs/aiohue](https://github.com/home-assistant-libs/aiohue)                                      | Apache-2.0                   | reconnect behaviour                     |
+| [Signify's Using HTTPS page](https://developers.meethue.com/develop/application-design-guidance/using-https/)    | Developer terms, login-gated | the two root certificates, as published |
+| [jdmg94/Hue-Sync](https://github.com/jdmg94/Hue-Sync)                                                            | Apache-2.0                   | resource types, cross-checked           |
+| [vchlum/smart-home](https://github.com/vchlum/smart-home)                                                        | MIT                          | a compact CLIP v2 event loop            |

package/src/connectors/hue/ca.ts

@@ -0,0 +1,39 @@
+// Signify's two root certificates for Hue bridges, so pinning needs no file: `bunPinnedFetch(bridgeId)` and
+// `nodePinnedFetch(bridgeId)` trust these and nothing else. Public certificates, as Signify's "Using HTTPS" page gives
+// them (login-gated); these bytes are the ones openHAB, hb-hue-tools, openhue-go and Raycast's Hue extension ship.
+//
+//   CN=root-bridge, O=Philips Hue       to 2038-01-19   the one in use: KO's square bridge (BSB002) chains to it
+//     SHA-256 F0:BD:8E:65:09:E8:2F:77:4D:63:BC:00:9D:53:88:C9:69:FE:3D:CF:7D:6D:54:1D:63:51:B7:2B:89:8D:8A:CF
+//   CN=Hue Root CA 01, O=Signify Hue    to 2050-12-31   Signify's spare, likely behind an intermediate: untried here
+//     SHA-256 D8:B8:94:48:B2:AF:8E:16:76:18:5A:C0:72:19:EE:9D:CB:C8:F0:1C:12:2A:02:6A:2A:4B:7B:5C:FE:03:28:B8
+//
+// test/hue.test.ts checks both fingerprints, so an edit here fails.
+
+/** Signify's root certificates for Hue bridges (PEM, two certificates): the default `ca` everywhere one is taken. */
+export const HUE_BRIDGE_ROOT_CA = `-----BEGIN CERTIFICATE-----
+MIICMjCCAdigAwIBAgIUO7FSLbaxikuXAljzVaurLXWmFw4wCgYIKoZIzj0EAwIw
+OTELMAkGA1UEBhMCTkwxFDASBgNVBAoMC1BoaWxpcHMgSHVlMRQwEgYDVQQDDAty
+b290LWJyaWRnZTAiGA8yMDE3MDEwMTAwMDAwMFoYDzIwMzgwMTE5MDMxNDA3WjA5
+MQswCQYDVQQGEwJOTDEUMBIGA1UECgwLUGhpbGlwcyBIdWUxFDASBgNVBAMMC3Jv
+b3QtYnJpZGdlMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEjNw2tx2AplOf9x86
+aTdvEcL1FU65QDxziKvBpW9XXSIcibAeQiKxegpq8Exbr9v6LBnYbna2VcaK0G22
+jOKkTqOBuTCBtjAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNV
+HQ4EFgQUZ2ONTFrDT6o8ItRnKfqWKnHFGmQwdAYDVR0jBG0wa4AUZ2ONTFrDT6o8
+ItRnKfqWKnHFGmShPaQ7MDkxCzAJBgNVBAYTAk5MMRQwEgYDVQQKDAtQaGlsaXBz
+IEh1ZTEUMBIGA1UEAwwLcm9vdC1icmlkZ2WCFDuxUi22sYpLlwJY81Wrqy11phcO
+MAoGCCqGSM49BAMCA0gAMEUCIEBYYEOsa07TH7E5MJnGw557lVkORgit2Rm1h3B2
+sFgDAiEA1Fj/C3AN5psFMjo0//mrQebo0eKd3aWRx+pQY08mk48=
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+MIIBzDCCAXOgAwIBAgICEAAwCgYIKoZIzj0EAwIwPDELMAkGA1UEBhMCTkwxFDAS
+BgNVBAoMC1NpZ25pZnkgSHVlMRcwFQYDVQQDDA5IdWUgUm9vdCBDQSAwMTAgFw0y
+NTAyMjUwMDAwMDBaGA8yMDUwMTIzMTIzNTk1OVowPDELMAkGA1UEBhMCTkwxFDAS
+BgNVBAoMC1NpZ25pZnkgSHVlMRcwFQYDVQQDDA5IdWUgUm9vdCBDQSAwMTBZMBMG
+ByqGSM49AgEGCCqGSM49AwEHA0IABFfOO0jfSAUXGQ9kjEDzyBrcMQ3ItyA5krE+
+cyvb1Y3xFti7KlAad8UOnAx0FBLn7HZrlmIwm1QnX0fK3LPM13mjYzBhMB0GA1Ud
+DgQWBBTF1pSpsCASX/z0VHLigxU2CAaqoTAfBgNVHSMEGDAWgBTF1pSpsCASX/z0
+VHLigxU2CAaqoTAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBBjAKBggq
+hkjOPQQDAgNHADBEAiAk7duT+IHbOGO4UUuGLAEpyYejGZK9Z7V9oSfnvuQ5BQIg
+IYSgwwxHXm73/JgcU9lAM6c8Bmu3UE3kBIUwBs1qXFw=
+-----END CERTIFICATE-----
+`;

package/src/connectors/hue/client.ts

@@ -1,6 +1,17 @@
 import { z } from "zod";
+import { colorToXy, kelvinToMirek, type Rgb, type XY } from "./color.ts";
 import { Envelope, type Kind, PairResponse, Resource } from "./schemas.ts";
-import type { Clock } from "../../clock.ts";
+import {
+  type GroupView,
+  groups,
+  type LightView,
+  lights,
+  scenes,
+  snapshotFrom,
+  homeGroupedLightId,
+} from "./state.ts";
+import { HUE_BRIDGE_ROOT_CA } from "./ca.ts";
+import { type Clock, realClock } from "../../clock.ts";
 import { ConnectorError, fetchTimeout } from "../../connector.ts";
 import { writeLane } from "../../lane.ts";
 
@@ -12,12 +23,43 @@ export type HueOptions = {
   clock?: Clock;
 };
 
-/** A failed bridge call. `code` is "link_button" when pairing waits on the bridge's button. */
+/** A failed bridge call. `code` is "link_button" when pairing waits on the bridge's button, "invalid" for a change that can't be made (an unknown name, a value off the light's range) and "offline" for a light the bridge has lost, both caught before anything is sent. */
 export class HueError extends ConnectorError {
-  declare readonly code?: "link_button";
+  declare readonly code?: "link_button" | "invalid" | "offline";
 }
 
-/** Minimum gap between writes, per lane. Signify's guidance (login-gated, unconfirmed): ~10/s to lights, 1/s to groups. */
+/**
+ * What to change on a light, or on a room or zone: only what is given is sent. `brightness` is 1–100, `color` a hex
+ * string or `{ r, g, b }`, `kelvin` a white temperature; `color` and `kelvin` are one or the other. Without `on`, a
+ * change turns the light on, since a light that is off takes no brightness or colour. `transitionMs` is the fade (the
+ * bridge's own is 400 ms; 0 is at once).
+ */
+export type LightChange = {
+  on?: boolean;
+  brightness?: number;
+  color?: string | Rgb;
+  kelvin?: number;
+  transitionMs?: number;
+};
+
+/**
+ * What a write left: the light or group once the bridge reported the change (`confirmed`), or as it stood when
+ * `CONFIRM_MS` ran out. With `{ dryRun: true }` nothing is sent: `wouldSend` is the request the write would make, `state`
+ * is how things stand now, and `confirmed` is false. Check `wouldSend` first.
+ */
+export type HueApplied<V> = {
+  state: V;
+  confirmed: boolean;
+  wouldSend?: HueRequest;
+};
+/** One CLIP v2 write: `PUT /clip/v2/resource/<path>` with this body. */
+export type HueRequest = { method: "PUT"; path: string; body: object };
+/** `dryRun`: every check a write makes before sending (the name, the range, a lost light) and nothing sent. For testing a bot with people home. */
+export type HueWriteOptions = { dryRun?: boolean };
+/** How long `light`, `room` and `scene` wait for the bridge to report what was asked, reading every half second. */
+export const CONFIRM_MS = 3000;
+
+/** Minimum gap between writes, per lane: Signify's guidance (Hue System Performance, read 2026-11-11), about 10 a second to lights and 1 a second to groups. */
 export const WRITE_GAP_MS = { group: 1000, light: 100 } as const;
 type Lane = keyof typeof WRITE_GAP_MS;
 
@@ -83,7 +125,8 @@ export function hueClient(options: HueOptions) {
       mergeBody,
     );
 
-  return {
+  const clock = options.clock ?? realClock;
+  const base = {
     put,
     /** Every resource of one kind, or every resource on the bridge when `kind` is left out (one call). */
     async get(kind?: Kind, signal?: AbortSignal): Promise<Resource[]> {
@@ -103,6 +146,266 @@ export function hueClient(options: HueOptions) {
       return put("scene", id, { recall: { action: "active" } });
     },
   };
+
+  /** Whether two of these labels are the same, so only an id tells them apart. */
+  const same = (labels: string[]) => new Set(labels).size < labels.length;
+  const invalid = (message: string) =>
+    new HueError(message, { code: "invalid" });
+  /** One of `items` by id or by name (any case). A miss, or a name two of them share, throws listing what exists. */
+  function pick<T extends { id: string; name?: string }>(
+    items: T[],
+    target: string,
+    what: string,
+    label: (item: T) => string = (i) => i.name ?? i.id,
+  ): T {
+    const wanted = target.trim().toLowerCase();
+    const found = items.filter(
+      (i) => i.id === target || i.name?.toLowerCase() === wanted,
+    );
+    if (found.length === 1) return found[0]!;
+    throw invalid(
+      found.length
+        ? `"${target}" names ${found.length}: ${same(found.map(label)) ? found.map((i) => `${label(i)} (${i.id})`).join(", ") : found.map(label).join(", ")}`
+        : `no ${what} "${target}"; have: ${items.map(label).join(", ") || "none"}`,
+    );
+  }
+  const read = async () => snapshotFrom(await base.get(), "");
+
+  /** The CLIP body for `change`, checked against what the light (or a group's lights) can take. Throws before anything is sent. */
+  function bodyFor(
+    change: LightChange,
+    name: string,
+    members: LightView[],
+    isOn: boolean | undefined,
+  ): Record<string, unknown> {
+    const { on, brightness, color, kelvin, transitionMs } = change;
+    const look =
+      brightness !== undefined || color !== undefined || kelvin !== undefined;
+    if (on === undefined && !look) throw invalid("nothing to change");
+    if (on === false && look)
+      throw invalid("off takes no brightness or colour");
+    if (color !== undefined && kelvin !== undefined)
+      throw invalid("a colour or a white temperature, not both");
+    const body: Record<string, unknown> = {};
+    if (on !== undefined) body.on = { on };
+    else if (isOn !== true) body.on = { on: true }; // off, or a group where some may be
+    if (brightness !== undefined) {
+      if (!(brightness >= 1 && brightness <= 100))
+        throw invalid(`brightness is 1–100, not ${brightness}`);
+      body.dimming = { brightness };
+    }
+    if (color !== undefined) {
+      const gamut = members.find((l) => l.gamut)?.gamut;
+      if (!gamut) throw invalid(`${name} has no colour light`);
+      try {
+        body.color = { xy: colorToXy(color, gamut) };
+      } catch (error) {
+        throw invalid((error as Error).message); // a bad colour, as every other change that can't be made
+      }
+    }
+    if (kelvin !== undefined) {
+      const ranges = members.flatMap((l) =>
+        l.kelvinRange ? [l.kelvinRange] : [],
+      );
+      if (!ranges.length) throw invalid(`${name} takes no white temperature`);
+      const low = Math.min(...ranges.map((r) => r[0]));
+      const high = Math.max(...ranges.map((r) => r[1]));
+      if (!(kelvin >= low && kelvin <= high))
+        throw invalid(
+          `${kelvin} K is outside ${name}'s range, ${low}–${high} K`,
+        );
+      body.color_temperature = { mirek: kelvinToMirek(kelvin) };
+    }
+    if (transitionMs !== undefined) {
+      if (!(Number.isInteger(transitionMs) && transitionMs >= 0))
+        throw invalid(
+          `transitionMs is a whole number of ms, not ${transitionMs}`,
+        );
+      body.dynamics = { duration: transitionMs };
+    }
+    return body;
+  }
+
+  /** Read every half second until `view()` gives a state that is as `asked`, or `CONFIRM_MS` passes. A failed read is not a failed write. */
+  async function confirm<V>(
+    view: () => Promise<V | undefined>,
+    asked: (v: V) => boolean,
+  ): Promise<HueApplied<V>> {
+    const until = clock.now() + CONFIRM_MS;
+    let state: V | undefined;
+    let failed: unknown;
+    for (;;) {
+      try {
+        state = (await view()) ?? state;
+        if (state !== undefined && asked(state)) break;
+      } catch (error) {
+        failed = error;
+      }
+      if (clock.now() >= until) break;
+      await clock.sleep(500);
+    }
+    if (state === undefined)
+      throw failed ?? new HueError("sent, but it is no longer on the bridge");
+    return { state, confirmed: asked(state) };
+  }
+  /**
+   * Whether a view shows what the body asked: on, brightness within a point, and on a light the white temperature within
+   * 2 mirek or the colour within 0.02 in `xy`. A room reports neither, so its colour is not compared (its `on` is).
+   */
+  const shows =
+    (body: Record<string, unknown>, light: boolean) =>
+    (v: Partial<LightView>): boolean => {
+      const on = (body.on as { on: boolean } | undefined)?.on;
+      const brightness = (body.dimming as { brightness: number } | undefined)
+        ?.brightness;
+      const mirek = (body.color_temperature as { mirek: number } | undefined)
+        ?.mirek;
+      const xy = (body.color as { xy: XY } | undefined)?.xy;
+      return (
+        (on === undefined || v.on === on) &&
+        (brightness === undefined ||
+          (v.brightness !== undefined &&
+            Math.abs(v.brightness - brightness) <= 1)) &&
+        (!light ||
+          mirek === undefined ||
+          (v.kelvin !== undefined &&
+            Math.abs(kelvinToMirek(v.kelvin) - mirek) <= 2)) &&
+        (!light ||
+          xy === undefined ||
+          (v.xy !== undefined &&
+            Math.abs(v.xy.x - xy.x) <= 0.02 &&
+            Math.abs(v.xy.y - xy.y) <= 0.02))
+      );
+    };
+
+  /** Send, or with `dryRun` say what would be sent and how `now` stands. */
+  async function send<V>(
+    options: HueWriteOptions | undefined,
+    kind: Kind,
+    id: string,
+    body: object,
+    now: V | undefined,
+    after: () => Promise<HueApplied<V>>,
+  ): Promise<HueApplied<V>> {
+    if (options?.dryRun) {
+      if (now === undefined)
+        throw new HueError("its room or zone is not on the bridge");
+      return {
+        state: now,
+        confirmed: false,
+        wouldSend: { method: "PUT", path: `${kind}/${id}`, body },
+      };
+    }
+    await put(kind, id, body);
+    return after();
+  }
+  return {
+    ...base,
+    /** Change one light, by name or id. Only when a person asks. Resolves with the light as the bridge then reported it. */
+    async light(
+      target: string,
+      change: LightChange,
+      options?: HueWriteOptions,
+    ): Promise<HueApplied<LightView>> {
+      const l = pick(lights(await read()), target, "light");
+      // The bridge takes a write to a light it has lost and answers "may not have effect": say so before sending.
+      if (l.reachable === false)
+        throw new HueError(
+          `${l.name ?? l.id} is unreachable: the bridge has lost it (is it switched off at the wall?)`,
+          { code: "offline" },
+        );
+      const body = bodyFor(change, l.name ?? l.id, [l], l.on);
+      return send(options, "light", l.id, body, l, () =>
+        confirm(
+          async () => lights(await read()).find((x) => x.id === l.id),
+          shows(body, true),
+        ),
+      );
+    },
+    /**
+     * Every light in the home off, with one write to the bridge's home group. Only when a person asks. Resolves with
+     * every light as the bridge then reported it, `confirmed` once none it can reach is on.
+     */
+    async allOff(options?: HueWriteOptions): Promise<HueApplied<LightView[]>> {
+      const s = await read();
+      const id = homeGroupedLightId(s);
+      if (!id) throw invalid("the bridge has no home group");
+      return send(
+        options,
+        "grouped_light",
+        id,
+        { on: { on: false } },
+        lights(s),
+        () =>
+          confirm(
+            async () => lights(await read()),
+            (all) => all.every((l) => !l.on || l.reachable === false),
+          ),
+      );
+    },
+    /**
+     * Change every light in a room or zone with one write, by name or id. Only when a person asks. Resolves with the
+     * group as the bridge then reported it; its brightness is the bridge's figure for the group, so a group holding a
+     * light that is off or unreachable may stay unconfirmed.
+     */
+    async room(
+      target: string,
+      change: LightChange,
+      options?: HueWriteOptions,
+    ): Promise<HueApplied<GroupView>> {
+      const s = await read();
+      const g = pick(groups(s), target, "room or zone");
+      const name = g.name ?? g.id;
+      if (!g.groupedLightId) throw invalid(`${name} has no lights`);
+      const members = lights(s).filter((l) => g.lightIds.includes(l.id));
+      const body = bodyFor(change, name, members, undefined);
+      return send(options, "grouped_light", g.groupedLightId, body, g, () =>
+        confirm(
+          async () => groups(await read()).find((x) => x.id === g.id),
+          shows(body, false),
+        ),
+      );
+    },
+    /**
+     * Recall a scene by name or id. A name several rooms use ("Relax") needs `room`. Only when a person asks. Resolves
+     * with the scene's room or zone, `confirmed` once the bridge reports the scene active.
+     */
+    async scene(
+      target: string,
+      room?: string,
+      options?: HueWriteOptions,
+    ): Promise<HueApplied<GroupView>> {
+      const s = await read();
+      const all = groups(s);
+      const within =
+        room === undefined ? undefined : pick(all, room, "room or zone");
+      const roomName = (id?: string) =>
+        all.find((g) => g.id === id)?.name ?? "no room";
+      const sc = pick(
+        scenes(s).filter((x) => !within || x.groupId === within.id),
+        target,
+        "scene",
+        (x) => `${x.name ?? x.id} in ${roomName(x.groupId)}`,
+      );
+      let active = false;
+      return send(
+        options,
+        "scene",
+        sc.id,
+        { recall: { action: "active" } },
+        all.find((g) => g.id === sc.groupId),
+        () =>
+          confirm(
+            async () => {
+              const now = await read();
+              active = scenes(now).find((x) => x.id === sc.id)?.active === true;
+              return groups(now).find((x) => x.id === sc.groupId);
+            },
+            () => active,
+          ),
+      );
+    },
+  };
 }
 export type HueClient = ReturnType<typeof hueClient>;
 
@@ -111,15 +414,21 @@ export async function pair(options: {
   host: string;
   fetch: typeof fetch;
   deviceType: string;
+  signal?: AbortSignal;
 }): Promise<{ key: string; clientKey?: string }> {
-  const res = await fetchTimeout(options.fetch, `https://${options.host}/api`, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({
-      devicetype: options.deviceType,
-      generateclientkey: true,
-    }),
-  });
+  const res = await fetchTimeout(
+    options.fetch,
+    `https://${options.host}/api`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        devicetype: options.deviceType,
+        generateclientkey: true,
+      }),
+    },
+    { signal: options.signal },
+  );
   const parsed = PairResponse.safeParse(
     await res.json().catch(() => undefined),
   );
@@ -138,10 +447,48 @@ export async function pair(options: {
 }
 
 /**
- * A `fetch` that trusts only `ca` and accepts only a certificate whose CN is `bridgeId`.
+ * `pair`, asked again every `everyMs` (2 s) until someone presses the bridge's button, for `timeoutMs` (30 s, as long as
+ * the button stays pressed). `onWaiting` is called once, when the bridge first says the button isn't pressed: the moment
+ * to tell the person. Throws the last `link_button` error when time runs out, any other error at once, and the signal's
+ * reason when aborted.
+ */
+export async function pairWhenPressed(options: {
+  host: string;
+  fetch: typeof fetch;
+  deviceType: string;
+  timeoutMs?: number;
+  everyMs?: number;
+  onWaiting?: () => void;
+  clock?: Clock;
+  signal?: AbortSignal;
+}): Promise<{ key: string; clientKey?: string }> {
+  const clock = options.clock ?? realClock;
+  const until = clock.now() + (options.timeoutMs ?? 30_000);
+  let waiting = false;
+  while (true) {
+    try {
+      return await pair(options);
+    } catch (error) {
+      const pressed = !(
+        error instanceof HueError && error.code === "link_button"
+      );
+      if (pressed || clock.now() >= until) throw error;
+      if (!waiting) options.onWaiting?.();
+      waiting = true;
+    }
+    await clock.sleep(options.everyMs ?? 2000, options.signal);
+    options.signal?.throwIfAborted();
+  }
+}
+
+/**
+ * A `fetch` that trusts only `ca` (Signify's roots, `HUE_BRIDGE_ROOT_CA`, when left out) and accepts only a certificate whose CN is `bridgeId`.
  * Uses Bun's `tls` fetch option; Node ignores it and then rejects the bridge, so it fails closed there; Node uses `nodePinnedFetch` from `@khalido/home/node`.
  */
-export function bunPinnedFetch(bridgeId: string, ca: string): typeof fetch {
+export function bunPinnedFetch(
+  bridgeId: string,
+  ca: string = HUE_BRIDGE_ROOT_CA,
+): typeof fetch {
   const checkServerIdentity = (
     _host: string,
     cert: { subject?: { CN?: string } },