@khalido/home 0.1.2 → 0.2.0

package/dist/connectors/hue/client.js

@@ -1,11 +1,17 @@
 import { z } from "zod";
+import { colorToXy, kelvinToMirek } from "./color.js";
 import { Envelope, PairResponse, Resource } from "./schemas.js";
+import { groups, lights, scenes, snapshotFrom, homeGroupedLightId, } from "./state.js";
+import { HUE_BRIDGE_ROOT_CA } from "./ca.js";
+import { realClock } from "../../clock.js";
 import { ConnectorError, fetchTimeout } from "../../connector.js";
 import { writeLane } from "../../lane.js";
-/** 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 {
 }
-/** Minimum gap between writes, per lane. Signify's guidance (login-gated, unconfirmed): ~10/s to lights, 1/s to groups. */
+/** 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 };
 /** Which lane a write goes in: `light` writes are fast, everything else (grouped_light, scene) is a group write. */
 export const laneFor = (kind) => kind === "light" ? "light" : "group";
@@ -44,7 +50,8 @@ export function hueClient(options) {
     }
     /** Change one resource, e.g. `put("grouped_light", id, { on: { on: false } })`. Spaced per lane; writes to one resource waiting their turn merge. */
     const put = (kind, id, body) => lanes[laneFor(kind)].send(`${kind}/${id}`, body, (b) => call("PUT", `/clip/v2/resource/${kind}/${id}`, b), 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, signal) {
@@ -57,6 +64,184 @@ export function hueClient(options) {
             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) => new Set(labels).size < labels.length;
+    const invalid = (message) => 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(items, target, what, label = (i) => i.name ?? i.id) {
+        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, name, members, isOn) {
+        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 = {};
+        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.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(view, asked) {
+        const until = clock.now() + CONFIRM_MS;
+        let state;
+        let failed;
+        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, light) => (v) => {
+        const on = body.on?.on;
+        const brightness = body.dimming
+            ?.brightness;
+        const mirek = body.color_temperature
+            ?.mirek;
+        const xy = body.color?.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(options, kind, id, body, now, after) {
+        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, change, options) {
+            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) {
+            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, change, options) {
+            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, room, options) {
+            const s = await read();
+            const all = groups(s);
+            const within = room === undefined ? undefined : pick(all, room, "room or zone");
+            const roomName = (id) => 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));
+        },
+    };
 }
 /** Ask the bridge for an application key. One call: throws `HueError` with code "link_button" until KO presses it. */
 export async function pair(options) {
@@ -67,7 +252,7 @@ export async function pair(options) {
             devicetype: options.deviceType,
             generateclientkey: true,
         }),
-    });
+    }, { signal: options.signal });
     const parsed = PairResponse.safeParse(await res.json().catch(() => undefined));
     if (!parsed.success)
         throw new HueError(`unexpected answer to POST /api (HTTP ${res.status})`, {
@@ -83,10 +268,36 @@ 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) {
+    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, ca) {
+export function bunPinnedFetch(bridgeId, ca = HUE_BRIDGE_ROOT_CA) {
     const checkServerIdentity = (_host, cert) => cert.subject?.CN?.toLowerCase() === bridgeId.toLowerCase()
         ? undefined
         : new Error(`Hue bridge certificate is for ${cert.subject?.CN ?? "nobody"}, expected ${bridgeId}`);

package/dist/connectors/hue/color.d.ts

@@ -0,0 +1,30 @@
+export type XY = {
+    x: number;
+    y: number;
+};
+export type Gamut = {
+    red: XY;
+    green: XY;
+    blue: XY;
+};
+export type Rgb = {
+    r: number;
+    g: number;
+    b: number;
+};
+/** A colour as a caller gives it: "#ff8800", "ff8800", "#f80", or `{ r, g, b }` each 0–255. Throws on anything else. */
+export declare function parseColor(color: string | Rgb): Rgb;
+/** Whether `p` is inside the gamut triangle. */
+export declare function inGamut(p: XY, g: Gamut): boolean;
+/** `p` if the light can show it, else the nearest point on its gamut's edge: the colour it can show that is closest. */
+export declare function nearestInGamut(p: XY, g: Gamut): XY;
+/**
+ * A colour's `xy`, moved inside `gamut` when one is given. Brightness is not part of it: black has no colour and throws
+ * (turn the light off instead), and a dark red and a bright red are the same point.
+ */
+export declare function colorToXy(color: string | Rgb, gamut?: Gamut): XY;
+/** An `xy` as a hex colour for a screen, at full brightness: what the light's colour looks like, not how bright it is. */
+export declare function xyToHex(xy: XY): string;
+/** Colour temperature: Hue counts in mirek, a million over the kelvin. 2700 K is 370 mirek. */
+export declare const kelvinToMirek: (kelvin: number) => number;
+export declare const mirekToKelvin: (mirek: number) => number;

package/dist/connectors/hue/color.js

@@ -0,0 +1,92 @@
+import { ConnectorError } from "../../connector.js";
+/** A colour as a caller gives it: "#ff8800", "ff8800", "#f80", or `{ r, g, b }` each 0–255. Throws on anything else. */
+export function parseColor(color) {
+    if (typeof color !== "string") {
+        const ok = [color.r, color.g, color.b].every((v) => Number.isFinite(v) && v >= 0 && v <= 255);
+        if (!ok)
+            throw new ConnectorError("a colour's r, g and b are each 0–255", {
+                code: "invalid",
+            });
+        return color;
+    }
+    const hex = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim())?.[1];
+    if (!hex)
+        throw new ConnectorError(`"${color}" is not a colour like #ff8800`, {
+            code: "invalid",
+        });
+    const full = hex.length === 3 ? [...hex].map((c) => c + c).join("") : hex;
+    const n = Number.parseInt(full, 16);
+    return { r: n >> 16, g: (n >> 8) & 255, b: n & 255 };
+}
+const linear = (v) => v > 0.04045 ? ((v + 0.055) / 1.055) ** 2.4 : v / 12.92;
+const gamma = (v) => v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055;
+const cross = (a, b) => a.x * b.y - a.y * b.x;
+const minus = (a, b) => ({ x: a.x - b.x, y: a.y - b.y });
+/** Whether `p` is inside the gamut triangle. */
+export function inGamut(p, g) {
+    const v1 = minus(g.green, g.red);
+    const v2 = minus(g.blue, g.red);
+    const q = minus(p, g.red);
+    const s = cross(q, v2) / cross(v1, v2);
+    const t = cross(v1, q) / cross(v1, v2);
+    return s >= 0 && t >= 0 && s + t <= 1;
+}
+/** The nearest point to `p` on the segment a–b. */
+function onSegment(a, b, p) {
+    const ab = minus(b, a);
+    const t = Math.min(1, Math.max(0, ((p.x - a.x) * ab.x + (p.y - a.y) * ab.y) / (ab.x ** 2 + ab.y ** 2)));
+    return { x: a.x + ab.x * t, y: a.y + ab.y * t };
+}
+/** `p` if the light can show it, else the nearest point on its gamut's edge: the colour it can show that is closest. */
+export function nearestInGamut(p, g) {
+    if (inGamut(p, g))
+        return p;
+    const edges = [
+        onSegment(g.red, g.green, p),
+        onSegment(g.green, g.blue, p),
+        onSegment(g.blue, g.red, p),
+    ];
+    const far = (q) => (q.x - p.x) ** 2 + (q.y - p.y) ** 2;
+    return edges.reduce((best, q) => (far(q) < far(best) ? q : best));
+}
+/**
+ * A colour's `xy`, moved inside `gamut` when one is given. Brightness is not part of it: black has no colour and throws
+ * (turn the light off instead), and a dark red and a bright red are the same point.
+ */
+export function colorToXy(color, gamut) {
+    const { r, g, b } = parseColor(color);
+    const [lr, lg, lb] = [r, g, b].map((v) => linear(v / 255));
+    const X = lr * 0.4124 + lg * 0.3576 + lb * 0.1805;
+    const Y = lr * 0.2126 + lg * 0.7152 + lb * 0.0722;
+    const Z = lr * 0.0193 + lg * 0.1192 + lb * 0.9505;
+    const sum = X + Y + Z;
+    if (sum === 0)
+        throw new ConnectorError("black is not a colour a light can show", {
+            code: "invalid",
+        });
+    const xy = { x: X / sum, y: Y / sum };
+    const at = gamut ? nearestInGamut(xy, gamut) : xy;
+    return { x: round4(at.x), y: round4(at.y) };
+}
+const round4 = (v) => Math.round(v * 1e4) / 1e4;
+/** An `xy` as a hex colour for a screen, at full brightness: what the light's colour looks like, not how bright it is. */
+export function xyToHex(xy) {
+    if (xy.y <= 0)
+        return "#000000";
+    const X = xy.x / xy.y;
+    const Z = (1 - xy.x - xy.y) / xy.y;
+    const rgb = [
+        X * 3.2406 - 1.5372 - Z * 0.4986,
+        -X * 0.9689 + 1.8758 + Z * 0.0415,
+        X * 0.0557 - 0.204 + Z * 1.057,
+    ].map((v) => Math.max(0, v));
+    const max = Math.max(...rgb);
+    return `#${rgb
+        .map((v) => Math.round(255 * Math.min(1, Math.max(0, gamma(max > 0 ? v / max : 0))))
+        .toString(16)
+        .padStart(2, "0"))
+        .join("")}`;
+}
+/** Colour temperature: Hue counts in mirek, a million over the kelvin. 2700 K is 370 mirek. */
+export const kelvinToMirek = (kelvin) => Math.round(1e6 / kelvin);
+export const mirekToKelvin = (mirek) => Math.round(1e6 / mirek);

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

@@ -1,11 +1,13 @@
 import { type Clock } from "../../clock.ts";
 import { z } from "zod";
 import { type Finder } from "../../discover.ts";
-import { type Integration } from "../../home.ts";
+import { type DeviceRecord, type Integration, type Part } from "../../home.ts";
 import type { Manifest } from "../../manifest.ts";
 import { type HueClient } from "./client.ts";
-import { type HueSnapshot } from "./state.ts";
-export { bunPinnedFetch, type HueClient, HueError, type HueOptions, hueClient, pair, } from "./client.ts";
+import { type GroupView, type HueSnapshot, type LightView } from "./state.ts";
+export { HUE_BRIDGE_ROOT_CA } from "./ca.ts";
+export { colorToXy, type Gamut, kelvinToMirek, mirekToKelvin, type Rgb, type XY, xyToHex, } from "./color.ts";
+export { bunPinnedFetch, CONFIRM_MS, type HueApplied, type HueRequest, type HueWriteOptions, type LightChange, type HueClient, HueError, type HueOptions, hueClient, pair, pairWhenPressed, } from "./client.ts";
 export type { HueEvent, Resource } from "./schemas.ts";
 export { type GroupView, groups, type HueSnapshot, homeGroupedLightId, type LightView, lights, scenes, } from "./state.ts";
 /** A Hue bridge in a home config: what it takes to reach it. Its model and software come live into the snapshot. */
@@ -14,17 +16,17 @@ export declare const configSchema: z.ZodObject<{
     host: z.ZodString;
     bridgeId: z.ZodString;
     key: z.ZodString;
-    ca: z.ZodString;
+    ca: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
 /**
- * Hue settings for a home. Leave out `fetch` in Bun and it pins to `ca` and `bridgeId`; in Node pass a pinned one.
+ * Hue settings for a home. Leave out `fetch` in Bun and it pins to `bridgeId` and `ca` (Signify's roots, `HUE_BRIDGE_ROOT_CA`, when left out); in Node pass a pinned one.
  * `find` (mDNS, matched by `bridgeId`) finds the bridge again after three failed reconnects; `idleMs` is the stream's watchdog.
  */
 export type HueConfig = {
     host: string;
     bridgeId: string;
     key: string;
-    ca: string;
+    ca?: string;
     fetch?: typeof fetch;
     clock?: Clock;
     find?: Finder;
@@ -39,4 +41,17 @@ export type HueConfig = {
 export declare function hue(config: HueConfig): Integration<HueSnapshot, "hue"> & {
     readonly client: HueClient;
 };
+/** A light, room or zone in a line: "Kitchen: on · 40%", "Desk: on · 40% · 2700 K", "Strip: on · 80% · #ff8800", "Kitchen: off", or the name alone when the bridge hasn't said. */
+export declare const hueText: (v: {
+    name?: string;
+    id: string;
+    on?: boolean;
+    brightness?: number;
+    kelvin?: number;
+    hex?: string;
+}) => string;
+/** A Hue light, or a room or zone, as a home device: `detail` is its `LightView` or `GroupView`. */
+export type HueHomeDevice = DeviceRecord<"hue", "light", "on" | "off", LightView> | DeviceRecord<"hue", "group", "on" | "off", GroupView>;
+/** Every light, then every room and zone. A light's `available` is its Zigbee link; a group's `members` are its lights. */
+export declare function hueHomeDevices(part: Part<HueSnapshot> | undefined): HueHomeDevice[];
 export declare const manifest: Manifest<HueSnapshot>;

package/dist/connectors/hue/index.js

@@ -2,11 +2,13 @@ import { asOf, realClock } from "../../clock.js";
 import { errorText } from "../../connector.js";
 import { z } from "zod";
 import { lostDetail, relocator } from "../../discover.js";
-import { envName, filePath, } from "../../home.js";
+import { envName, filePath, deviceRecords, } from "../../home.js";
 import { bunPinnedFetch, hueClient } from "./client.js";
 import { hueEvents, isRejectedKey } from "./events.js";
 import { groups, lights, reduce, snapshotFrom, } from "./state.js";
-export { bunPinnedFetch, HueError, hueClient, pair, } from "./client.js";
+export { HUE_BRIDGE_ROOT_CA } from "./ca.js";
+export { colorToXy, kelvinToMirek, mirekToKelvin, xyToHex, } from "./color.js";
+export { bunPinnedFetch, CONFIRM_MS, HueError, hueClient, pair, pairWhenPressed, } from "./client.js";
 export { groups, homeGroupedLightId, lights, scenes, } from "./state.js";
 /** A Hue bridge in a home config: what it takes to reach it. Its model and software come live into the snapshot. */
 export const configSchema = z.looseObject({
@@ -16,7 +18,9 @@ export const configSchema = z.looseObject({
         .string()
         .describe("the bridge id, the CN its certificate must carry: its identity"),
     key: envName.describe("env name holding the application key from `home pair`"),
-    ca: filePath.describe("Signify's root CA (PEM), relative to the config file"),
+    ca: filePath
+        .optional()
+        .describe("a root CA (PEM) to trust instead of Signify's two, which the package carries; relative to the config file"),
 });
 /**
  * Hue as a home integration: a full read on every (re)connect, then patched from the event stream; `refresh` re-reads it all.
@@ -137,6 +141,7 @@ export function hue(config) {
                     if (isRejectedKey(error))
                         return update({
                             status: "unavailable",
+                            reason: "auth",
                             detail: "the bridge rejected the key; pair again",
                             state: snapshot,
                         });
@@ -161,6 +166,53 @@ const view = (s) => ({
         brightness,
     })),
 });
+/** A light, room or zone in a line: "Kitchen: on · 40%", "Desk: on · 40% · 2700 K", "Strip: on · 80% · #ff8800", "Kitchen: off", or the name alone when the bridge hasn't said. */
+export const hueText = (v) => {
+    if (v.on === undefined)
+        return v.name ?? v.id;
+    const parts = v.on
+        ? [
+            "on",
+            v.brightness === undefined ? "" : `${Math.round(v.brightness)}%`,
+            // A colour light showing a white reports both; the white is what it is showing.
+            v.kelvin !== undefined ? `${v.kelvin} K` : (v.hex ?? ""),
+        ]
+        : ["off"];
+    return `${v.name ?? v.id}: ${parts.filter(Boolean).join(" · ")}`;
+};
+/** Every light, then every room and zone. A light's `available` is its Zigbee link; a group's `members` are its lights. */
+export function hueHomeDevices(part) {
+    const s = part?.state;
+    if (!s)
+        return [];
+    const on = (v) => v.on === undefined
+        ? {}
+        : { state: v.on ? "on" : "off" };
+    return deviceRecords(part, [
+        ...lights(s).map((l) => ({
+            connector: "hue",
+            id: l.id,
+            name: l.name ?? l.id,
+            kind: "light",
+            ...(l.reachable === undefined ? {} : { available: l.reachable }),
+            ...on(l),
+            asOf: s.asOf,
+            text: hueText(l),
+            detail: l,
+        })),
+        ...groups(s).map((g) => ({
+            connector: "hue",
+            id: g.id,
+            name: g.name ?? g.id,
+            kind: "group",
+            ...on(g),
+            asOf: s.asOf,
+            text: hueText(g),
+            members: g.lightIds,
+            detail: g,
+        })),
+    ]);
+}
 export const manifest = {
     name: "hue",
     title: "Philips Hue",
@@ -187,7 +239,8 @@ export const manifest = {
         {
             name: "HUE_CA_FILE",
             example: "/path/to/hue-root-ca.pem",
-            what: "until HUE_BRIDGE_ROOT_CA ships in src/connectors/hue/",
+            optional: true,
+            what: "a root CA to trust instead of Signify's two, which the package carries",
         },
     ],
     files: ["ca"],
@@ -195,11 +248,8 @@ export const manifest = {
     lines({ state }) {
         if (!state)
             return [];
-        const { lightsOn, rooms } = view(state);
-        return [
-            `${lightsOn} lights on`,
-            ...rooms.map((r) => `${r.name}: ${r.on ? `on${r.brightness === undefined ? "" : ` · ${Math.round(r.brightness)}%`}` : "off"}`),
-        ];
+        const { lightsOn } = view(state);
+        return [`${lightsOn} lights on`, ...groups(state).map(hueText)];
     },
     record: ({ state }) => (state ? view(state) : {}),
 };

package/dist/connectors/hue/schemas.d.ts

@@ -19,6 +19,33 @@ export declare const Resource: z.ZodObject<{
     dimming: z.ZodOptional<z.ZodObject<{
         brightness: z.ZodNumber;
     }, z.core.$loose>>;
+    color: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        xy: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$loose>>>;
+        gamut: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+            red: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$loose>;
+            green: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$loose>;
+            blue: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$loose>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>>;
+    color_temperature: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        mirek: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        mirek_schema: z.ZodOptional<z.ZodObject<{
+            mirek_minimum: z.ZodOptional<z.ZodNumber>;
+            mirek_maximum: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>>;
     children: z.ZodOptional<z.ZodArray<z.ZodObject<{
         rid: z.ZodString;
         rtype: z.ZodString;

package/dist/connectors/hue/schemas.js

@@ -4,6 +4,7 @@ import { z } from "zod";
 // field is unconfirmed from the primary source. Only the fields the snapshot reads are parsed;
 // all are optional and unknown fields pass through, so a schema change degrades, never throws.
 const ref = z.object({ rid: z.string(), rtype: z.string() });
+const xy = z.looseObject({ x: z.number(), y: z.number() });
 /** The resource kinds this library reads. */
 export const KINDS = [
     "light",
@@ -22,6 +23,31 @@ export const Resource = z.looseObject({
     metadata: z.looseObject({ name: z.string().optional() }).optional(),
     on: z.looseObject({ on: z.boolean() }).optional(),
     dimming: z.looseObject({ brightness: z.number() }).optional(),
+    // A light's colour and the triangle of colours it can show; absent on a white light. A shape this doesn't expect
+    // reads as absent, so one odd light never fails the whole read.
+    color: z
+        .looseObject({
+        xy: xy.optional().catch(undefined),
+        gamut: z
+            .looseObject({ red: xy, green: xy, blue: xy })
+            .optional()
+            .catch(undefined),
+    })
+        .optional()
+        .catch(undefined),
+    // mirek is null while the light shows a colour; the schema is this light's own range.
+    color_temperature: z
+        .looseObject({
+        mirek: z.number().nullable().optional(),
+        mirek_schema: z
+            .looseObject({
+            mirek_minimum: z.number().optional(),
+            mirek_maximum: z.number().optional(),
+        })
+            .optional(),
+    })
+        .optional()
+        .catch(undefined),
     children: z.array(ref).optional(),
     services: z.array(ref).optional(),
     group: ref.optional(), // scene: the room or zone it belongs to

package/dist/connectors/hue/state.d.ts

@@ -1,3 +1,4 @@
+import { type Gamut, type XY } from "./color.ts";
 import type { HueEvent, Resource } from "./schemas.ts";
 /** Every resource on the bridge by id, from the last full read plus every event since. `asOf` is local time it was last known fresh. */
 export type HueSnapshot = {
@@ -17,8 +18,16 @@ export type LightView = {
     on?: boolean;
     brightness?: number;
     reachable?: boolean;
+    /** White temperature in kelvin, while the light shows a white; its range is `kelvinRange` (warmest, coolest). */
+    kelvin?: number;
+    kelvinRange?: [number, number];
+    /** The colour it shows: the bridge's `xy`, and `hex` for a screen (the hue at full brightness). Colour lights only. */
+    xy?: XY;
+    hex?: string;
+    /** The colours it can show. Present on a colour light, so its presence says "takes a colour". */
+    gamut?: Gamut;
 };
-/** Every light, with on, brightness and reachability. */
+/** Every light, with on, brightness, reachability, and its white temperature and colour where it has them. */
 export declare function lights(s: HueSnapshot): LightView[];
 /** A room or zone as a row shows it, with its grouped light's state. */
 export type GroupView = {