@khalido/home 0.1.3 → 0.2.0

package/src/connectors/cast/state.ts

@@ -325,10 +325,10 @@ export function castStatus(s: CastSnapshot): CastStatus[] {
   return castDevices(s).map(one);
 }
 
-/** A target `castFree` left out: `standby` is a TV that is off, which a clip may wake. */
+/** A target `castFree` left out: `standby` is a TV that is off, which a clip may wake; `form` is one whose form wasn't asked for. */
 export type CastSkipped = {
   name: string;
-  why: "busy" | "offline" | "standby" | "unknown";
+  why: "busy" | "offline" | "standby" | "unknown" | "form";
   app?: string;
 };
 
@@ -340,11 +340,21 @@ export type CastSkipped = {
  *   becomes its free members, named one by one (they then play out of step with each other).
  * - A device is never named beside a free group that holds it, nor two groups that share a member: the second becomes its
  *   members not yet covered.
+ * - With `forms` (`["speaker", "display"]` keeps an announcement off TVs), a device of another form, or of a model this
+ *   library doesn't know, is skipped with `why: "form"`, and a group holding one (or a member the snapshot doesn't have)
+ *   becomes its other free members. An empty list leaves every device out.
  */
 export function castFree(
   s: CastSnapshot,
   targets: string[],
+  options: { forms?: readonly CastForm[] } = {},
 ): { free: string[]; skipped: CastSkipped[] } {
+  /** A device of a form asked for. A group has no form of its own: its members decide. */
+  const wanted = (id: string) => {
+    const d = s.devices[id];
+    if (!options.forms || d?.kind === "group") return true;
+    return d?.form !== undefined && options.forms.includes(d.form);
+  };
   const status = new Map(castStatus(s).map((c) => [c.id, c]));
   const free = new Map<string, CastStatus>();
   const covered = new Set<string>(); // members of the groups in `free`
@@ -354,15 +364,17 @@ export function castFree(
   const skip = (c: CastStatus) =>
     skipped.set(c.id, {
       name: c.name,
-      why:
-        c.state === "offline"
+      why: !wanted(c.id)
+        ? "form"
+        : c.state === "offline"
           ? "offline"
           : c.standby && c.state !== "busy"
             ? "standby"
             : "busy",
       ...(c.app ? { app: c.app } : {}),
     });
-  const device = (c: CastStatus) => (ok(c) ? free.set(c.id, c) : skip(c));
+  const device = (c: CastStatus) =>
+    ok(c) && wanted(c.id) ? free.set(c.id, c) : skip(c);
   for (const target of targets) {
     const d = findCast(s.devices, target);
     const c = d && status.get(d.id);
@@ -376,6 +388,7 @@ export function castFree(
       else if (
         own !== "offline" &&
         up.every(ok) &&
+        (d.members ?? []).every(wanted) &&
         !members.some((m) => covered.has(m.id))
       ) {
         free.set(c.id, c);
@@ -390,3 +403,17 @@ export function castFree(
     skipped: [...skipped.values()],
   };
 }
+
+/**
+ * Where an announcement can play right now, in one call: every speaker and display that is free, a whole group where all
+ * of it is, and never a TV. `castFree` over everything Cast has found, with `forms: ["speaker", "display"]`; `free` goes
+ * straight to `announceAll`.
+ */
+export const castFreeSpeakers = (
+  s: CastSnapshot,
+): { free: string[]; skipped: CastSkipped[] } =>
+  castFree(
+    s,
+    castDevices(s).map((d) => d.id),
+    { forms: ["speaker", "display"] },
+  );

package/src/connectors/daikin/README.md

@@ -2,9 +2,9 @@
 
 Reads one Daikin AC over its local JSON `dsiot` API. `iot_class`: **local_polling**. KO's unit is a Daikin Australia **Alira X** with built-in Wi-Fi (likely; it reports a blank model string).
 
-- `client.ts`: `daikinClient({ host, fetch }).read()` returns `DaikinState` (power, mode, the selected mode's setpoint and fan speed, room °C, humidity, outside °C, `anomaly`). `setPower`, `setMode`, `setTarget`, `setFan` build write requests; `client.write(request)` sends one, through a write lane: 1 s apart and at most 20 a minute (guesses), a waiting write merging the next one field by field (`mergeWrites`). Every request times out at 10 s.
-- `index.ts`: `daikin({ host, fetch, clock })` reads now, then every **120 s** (Home Assistant's `update_interval`). A failed poll is `disconnected` and keeps the last reading with `asOf`; a 404 on `/dsiot/multireq` is a failed read too, saying "not a dsiot Daikin": the address may now be another device's, so discovery looks for the unit. There is no key, so nothing is terminal. Writes go through `daikin().client.write(…)`: one client for the integration's life, at the unit's current address.
-- `home status` reads `DAIKIN_HOST`, or a home config's address, with discovery by `mac` if the unit moves. There is no CLI command that writes.
+- `client.ts`: `daikinClient({ host, fetch }).read()` returns `DaikinState` (power, mode, the selected mode's setpoint and fan speed, room °C, humidity, outside °C, `anomaly`). **`power(on)` and `mode(mode, targetC?)` are the writes most callers want.** `mode` selects the mode, turns the unit on and sets the setpoint in one request: the one given, else the library's default (`DEFAULT_TARGET_C`: cool 25, heat 27), else (auto) the unit's own; dry and fan take none. Both resolve with `{ state, confirmed }`: the unit read once a second until it reports what was asked, at most 5 s (`CONFIRM_MS`); unconfirmed is a result, not an error. A setpoint off the unit's range or a half degree throws before anything is sent. `setPower`, `setMode`, `setTarget`, `setFan` build write requests; `client.write(request)` sends one, through a write lane: 1 s apart and at most 20 a minute (guesses), a waiting write merging the next one field by field (`mergeWrites`). Every request times out at 10 s.
+- `index.ts`: `daikin({ host, fetch, clock })` reads now, then every **120 s** (Home Assistant's `update_interval`). A failed poll is `disconnected` and keeps the last reading with `asOf`; a 404 on `/dsiot/multireq` is a failed read too, saying "not a dsiot Daikin": the address may now be another device's, so discovery looks for the unit. There is no key, so nothing is terminal. Writes go through `daikin().client` (`power`, `mode`, or `write` for a built request): one client for the integration's life, at the unit's current address.
+- `home status` and `home daikin` read `DAIKIN_HOST`, or a home config's address (with discovery by `mac` if the unit moves); with neither, they take the first unit to answer the UDP broadcast, which adds 1.5 s. The broadcast goes out three times in that window: a single one missed KO's unit in 2 runs of 3 while mDNS searches ran beside it (2026-11-11); three found it 6 of 6. `home daikin on | off` and `home daikin cool | heat | auto [°C] | dry | fan` are the CLI writes, at `DAIKIN_HOST` or the first unit to answer the UDP broadcast, printing what the unit then reports.
 
 ## The protocol
 
@@ -39,7 +39,7 @@ One read-only request, saved with the MAC, SSID, `edid` and the unit's ASCII ids
 ## Unconfirmed
 
 - **The write lane's rates** (1 s apart, 20 a minute) are guesses. One client lives as long as the integration and reads the unit's address at each send, so a move keeps the lane's count, and a write still waiting goes to the new address.
-- **Writes other than power.** Only `setPower(true)` has been sent to KO's unit (2026-10-16, Bun 1.4.3, see below); mode, setpoint and fan writes are untried. The encodings come from pydaikin, which reports verified live writes on other BRP084 units. The two sources disagree in three places, plus one choice of our own, settled here as follows:
+- **Writes other than power.** Only `setPower(true)` has been sent to KO's unit (2026-10-16 and 2026-11-11, see below); dry to cool at 25 °C worked (2026-11-11, below); heat, auto, fan mode and fan-speed writes are untried. The encodings come from pydaikin, which reports verified live writes on other BRP084 units. The two sources disagree in three places, plus one choice of our own, settled here as follows:
   - Setpoint width: pydaikin sends one byte, Alira two (`3200`). One byte, because the live field is one byte (`p_02` `mi 24`, `mx 40`).
   - Method: pydaikin POSTs, Alira PUTs. POST, the method reads already use.
   - Field: Alira always writes `p_03` and `p_0A`. Those are pydaikin's heat-mode setpoint and fan, and Alira reads by list position (its `[2]` and `[8]` are `p_03` and `p_0A`), so it appears written on a unit in heat. Per-mode fields here.
@@ -63,10 +63,22 @@ All setpoint and fan fields, read from `e_3001` with `md` (setpoint is one byte,
 
 Unmapped and unread: `p_27` (`0A00`, like auto), `p_34` (one signed byte, `00`, `mi FA`, `mx 00`), and the `p_05`–`p_08`, `p_20`–`p_25` fields (3- and 4-byte values, mostly `0F…`, likely schedules or limits). Meaning unknown.
 
+## Second write (2026-11-11)
+
+`setPower(true)` at KO's request, through `daikinClient().write` and the rewritten write lane (Bun 1.4.4, from a Mac): accepted in 280 ms, and reads at once, 2 s and 5 s later all showed `on` (before: off, dry, room 25 °C). The unit was found by the UDP broadcast. Then `setMode("dry")` at KO's request: accepted in 291 ms and the unit read `on`, dry. It was already in dry, so this shows the write is accepted, not that a mode changes. `home daikin on` on the running unit printed its line and exited 0. `home probe` shows 404 on the three old `/common` and `/aircon` paths and an answer on `dsiot`, as expected for this unit.
+
+## First mode change and setpoint (2026-11-11)
+
+`home daikin cool` at KO's request, the unit on in dry (Bun 1.4.4): one request with power, mode and the default setpoint; the command took 3.3 s in all, 1.5 s of it the UDP search, and printed `on · cool 25 °C`. A read some 15 s later showed the same, fan 3. So `mode` with a setpoint works on this unit, and the unit reports the change within the confirm wait. Still untried: heat, auto, fan mode, a fan-speed write, and `power(false)`.
+
 ## Read from a Pi (2026-11-10)
 
 `home daikin` on 0.1.2 (Bun 1.4.4; chota-bot's session): "connected · off · dry · room 26 °C · outdoor unit 28 °C". `home discover` found the unit by UDP. No write was sent.
 
+## Dry run (2026-11-12)
+
+`power` and `mode` take `{ dryRun: true }`: the checks, one read, and `wouldSend` with what it would set; nothing sent. `home daikin cool --dry-run` and `heat --dry-run` on KO's unit (Bun 1.4.4) read it and printed 25 and 27; the unit stayed off.
+
 ## Sources
 
 Both Daikin protocol sources are GPL-3.0, so they are read for facts only (endpoints, field paths, value maps) and no code is copied; that keeps this package MIT.

package/src/connectors/daikin/client.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { Clock } from "../../clock.ts";
+import { type Clock, realClock } from "../../clock.ts";
 import { ConnectorError, getJson } from "../../connector.ts";
 import { writeLane } from "../../lane.ts";
 
@@ -81,6 +81,37 @@ const TARGET_RANGE: Partial<Record<Mode, [number, number]>> = {
   auto: [18, 30],
 };
 
+/**
+ * The setpoint a mode gets when the caller names none: this library's opinion (KO's: not too cold, properly warm).
+ * Without one, "cool" would mean whatever the remote last left. Auto keeps the unit's own.
+ */
+export const DEFAULT_TARGET_C = {
+  cool: 25,
+  heat: 27,
+} as const satisfies Partial<Record<Mode, number>>;
+
+/**
+ * What a write left: the state once the unit reported the change (`confirmed`), or as it stood when `CONFIRM_MS` ran out
+ * without it. With `{ dryRun: true }` nothing is sent: `wouldSend` is the request and what it sets, `state` the unit as it
+ * reads now, and `confirmed` is false. Check `wouldSend` first.
+ */
+export type DaikinApplied = {
+  state: DaikinState;
+  confirmed: boolean;
+  wouldSend?: DaikinRequest;
+};
+/** One write: `POST /dsiot/multireq` with `body`; `sets` is what it changes, in this library's words. */
+export type DaikinRequest = {
+  method: "POST";
+  path: "/dsiot/multireq";
+  body: WriteRequest;
+  sets: { on?: boolean; mode?: Mode; targetC?: number };
+};
+/** `dryRun`: every check a write makes (the mode, the setpoint's range), one read for the state, and nothing sent. */
+export type DaikinWriteOptions = { dryRun?: boolean };
+/** How long `power` and `mode` wait for the unit to report what was asked, reading once a second. */
+export const CONFIRM_MS = 5000;
+
 /** Little-endian hex to an integer, two's complement when `signed`: "2700" → 39, "EEFF" → -18. */
 export function hexLE(hex: string, signed = false): number | undefined {
   if (!/^(?:[0-9a-f]{2})+$/i.test(hex)) return undefined;
@@ -229,7 +260,7 @@ export function setFan(fan: Fan, mode: Mode): WriteRequest {
   return write([["e_3001", FAN[mode]!, key(FANS, fan)]]);
 }
 
-/** A client for one unit. Reads are op 2; `write` sends a body built by setPower, setMode, setTarget or setFan. */
+/** A client for one unit. Reads are op 2. `power` and `mode` are the writes most callers want; `write` sends any body built by setPower, setMode, setTarget or setFan. */
 export function daikinClient(options: {
   host: string;
   fetch: typeof fetch;
@@ -251,7 +282,8 @@ export function daikinClient(options: {
       schema: Multi,
       error: DaikinError,
     });
-  return {
+  const clock = options.clock ?? realClock;
+  const client = {
     /** The indoor and outdoor status in one request. A failed outdoor read leaves `outsideC` empty. */
     async read(signal?: AbortSignal): Promise<DaikinState> {
       const m = await multireq(
@@ -292,4 +324,73 @@ export function daikinClient(options: {
       );
     },
   };
+  /** Send `request`, then read once a second until the unit reports `asked` or `CONFIRM_MS` passes. Rejects if the write is refused, or if no read after it succeeds. */
+  async function apply(
+    request: WriteRequest,
+    sets: DaikinRequest["sets"],
+    asked: (s: DaikinState) => boolean,
+    options: DaikinWriteOptions | undefined,
+  ): Promise<DaikinApplied> {
+    if (options?.dryRun)
+      return {
+        state: await client.read(),
+        confirmed: false,
+        wouldSend: {
+          method: "POST",
+          path: "/dsiot/multireq",
+          body: request,
+          sets,
+        },
+      };
+    await client.write(request);
+    const until = clock.now() + CONFIRM_MS;
+    let state: DaikinState | undefined;
+    let failed: unknown;
+    // The write was accepted, so one dropped read must not turn it into a failure: keep reading until the time is up.
+    for (;;) {
+      try {
+        state = await client.read();
+        if (asked(state)) break;
+      } catch (error) {
+        failed = error;
+      }
+      if (clock.now() >= until) break;
+      await clock.sleep(1000);
+    }
+    if (!state) throw failed; // sent, but the unit answered no read since: nothing to report
+    return { state, confirmed: asked(state) };
+  }
+  return {
+    ...client,
+    /** Turn the unit on or off, as it was last left. Only when a person asks. Resolves with what the unit then reported. */
+    power: (
+      on: boolean,
+      options?: DaikinWriteOptions,
+    ): Promise<DaikinApplied> =>
+      apply(setPower(on), { on }, (s) => s.on === on, options),
+    /**
+     * Select a mode, turn the unit on and set its setpoint, in one request: `targetC`, else `DEFAULT_TARGET_C` (cool 25,
+     * heat 27), else (auto) the unit's own. Dry and fan take none, and a `targetC` for them throws before anything is
+     * sent, as one off the unit's range does. Only when a person asks. Resolves with what the unit then reported.
+     */
+    async mode(
+      mode: Mode,
+      targetC?: number,
+      options?: DaikinWriteOptions,
+    ): Promise<DaikinApplied> {
+      const c =
+        targetC ?? (DEFAULT_TARGET_C as Partial<Record<Mode, number>>)[mode];
+      return apply(
+        c === undefined
+          ? setMode(mode)
+          : mergeWrites(setMode(mode), setTarget(c, mode)),
+        { on: true, mode, ...(c === undefined ? {} : { targetC: c }) },
+        (s) =>
+          s.on === true &&
+          s.mode === mode &&
+          (c === undefined || s.targetC === c),
+        options,
+      );
+    },
+  };
 }

package/src/connectors/daikin/index.ts

@@ -17,8 +17,13 @@ import {
 } from "./client.ts";
 
 export {
+  CONFIRM_MS,
+  type DaikinApplied,
+  type DaikinRequest,
+  type DaikinWriteOptions,
   DaikinError,
   type DaikinState,
+  DEFAULT_TARGET_C,
   daikinClient,
   type Fan,
   type Mode,
@@ -60,7 +65,7 @@ export type DaikinSnapshot = DaikinState & { asOf: string };
 export type DaikinClient = ReturnType<typeof daikinClient>;
 
 /**
- * One Daikin AC as a home integration: one read now, then every 120 s. Its writes are `client.write(setPower(true))`: one
+ * One Daikin AC as a home integration: one read now, then every 120 s. Its writes are `client.power(on)` and `client.mode(mode, targetC?)`: one
  * client for the integration's life, so the writes share its lane and follow the unit when it moves.
  */
 export function daikin(
@@ -148,7 +153,8 @@ export const manifest: Manifest<DaikinSnapshot> = {
     {
       name: "DAIKIN_HOST",
       example: "192.0.2.20",
-      what: "the unit's address; `home probe` finds it by UDP broadcast",
+      optional: true,
+      what: "the unit's address; found by UDP broadcast when unset (1.5 s a run)",
     },
   ],
   lines: ({ state }) => (state ? [acText(state)] : []),

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-----
+`;