@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/wiz/wiz.types.ts

@@ -1,223 +1,41 @@
-import type { IServiceCallRequest, TEntityPlatform } from '../../core/types.js';
+import type * as plugins from '../../plugins.js';
 
 export const wizDefaultPort = 38899;
 
-export type TWizBulbType = 'rgb' | 'tw' | 'dw' | 'socket' | 'fan' | 'unknown' | string;
-export type TWizDiscoveryProtocol = 'mdns' | 'udp' | 'manual';
-
 export interface IWizConfig {
-  host?: string;
+  homeId: string;
+  host: string;
+  macAddress: string;
   port?: number;
-  mac?: string;
   name?: string;
-  deviceInfo?: IWizDeviceInfo;
-  pilot?: IWizPilotState;
-  snapshot?: IWizSnapshot;
-  devices?: IWizSnapshotDevice[];
-  manualEntries?: IWizManualEntry[];
-  events?: IWizEvent[];
   timeoutMs?: number;
-  commandExecutor?: TWizCommandExecutor;
-  [key: string]: unknown;
+  /** Zero disables subscription polling; explicit reads still deliver observations. */
+  pollIntervalMs?: number;
+  maxPendingOperations?: number;
+  maxExchanges?: number;
 }
 
 export interface IHomeAssistantWizConfig extends IWizConfig {}
 
-export interface IWizDeviceFeatures {
-  light?: boolean;
-  switch?: boolean;
-  brightness?: boolean;
-  color?: boolean;
-  colorTemp?: boolean;
-  effect?: boolean;
-  fan?: boolean;
-  fanReverse?: boolean;
-  fanBreezeMode?: boolean;
-  power?: boolean;
-  occupancy?: boolean;
-  button?: boolean;
-  dualHead?: boolean;
-  [key: string]: unknown;
-}
-
-export interface IWizKelvinRange {
-  min?: number;
-  max?: number;
-}
-
-export interface IWizDeviceInfo {
-  id?: string;
-  mac?: string;
-  host?: string;
-  port?: number;
-  name?: string;
-  manufacturer?: string;
-  model?: string;
-  moduleName?: string;
-  fwVersion?: string;
-  typeId?: number | string;
-  bulbType?: TWizBulbType;
-  isSocket?: boolean;
-  whiteChannels?: number;
-  kelvinRange?: IWizKelvinRange;
-  fanSpeedRange?: number;
-  powerMonitoring?: boolean;
-  features?: IWizDeviceFeatures;
-  [key: string]: unknown;
-}
-
-export interface IWizPilotState {
-  mac?: string;
-  rssi?: number;
-  src?: string;
-  state?: boolean;
-  sceneId?: number;
-  schdPsetId?: number;
-  temp?: number;
-  dimming?: number;
-  r?: number;
-  g?: number;
-  b?: number;
-  c?: number;
-  w?: number;
-  speed?: number;
-  ratio?: number;
-  pc?: number;
-  fanState?: number;
-  fanMode?: number;
-  fanSpeed?: number;
-  fanRevrs?: number;
-  [key: string]: unknown;
-}
-
-export interface IWizPilotPatch {
-  state?: boolean;
-  sceneId?: number;
-  temp?: number;
-  dimming?: number;
-  r?: number;
-  g?: number;
-  b?: number;
-  c?: number;
-  w?: number;
-  speed?: number;
-  ratio?: number;
-  fanState?: number;
-  fanMode?: number;
-  fanSpeed?: number;
-  fanRevrs?: number;
-  [key: string]: unknown;
-}
-
-export interface IWizSensorRecord {
-  key: string;
-  name?: string;
-  platform?: 'sensor' | 'binary_sensor';
-  value?: unknown;
-  unit?: string;
-  deviceClass?: string;
-  writable?: boolean;
-  available?: boolean;
-  [key: string]: unknown;
-}
-
-export interface IWizButtonRecord {
-  key: string;
-  name?: string;
-  value?: unknown;
-  lastPressedAt?: string | number;
-  available?: boolean;
-  [key: string]: unknown;
-}
-
-export interface IWizEntityRecord {
-  platform: TEntityPlatform;
-  key?: string;
-  entityId?: string;
-  uniqueId?: string;
-  name?: string;
-  state?: unknown;
-  attributes?: Record<string, unknown>;
-  available?: boolean;
-  writable?: boolean;
-  [key: string]: unknown;
-}
-
-export interface IWizSnapshotDevice {
-  id?: string;
-  host?: string;
-  port?: number;
-  mac?: string;
-  name?: string;
-  available?: boolean;
-  deviceInfo?: IWizDeviceInfo;
-  pilot?: IWizPilotState;
-  sensors?: IWizSensorRecord[];
-  buttons?: IWizButtonRecord[];
-  entities?: IWizEntityRecord[];
-  metadata?: Record<string, unknown>;
-  [key: string]: unknown;
-}
+export type TWizControl =
+  | { readonly feature: 'power'; readonly value: boolean }
+  | { readonly feature: 'brightness'; readonly value: number }
+  | { readonly feature: 'rgb'; readonly value: Readonly<plugins.ecobridgeDeviceManager.IWizRgb> };
 
 export interface IWizSnapshot {
-  connected: boolean;
-  host?: string;
-  port?: number;
-  devices: IWizSnapshotDevice[];
-  events: IWizEvent[];
+  readonly homeId: string;
+  readonly host: string;
+  readonly port: number;
+  readonly name?: string;
+  readonly info: plugins.ecobridgeDeviceManager.IWizDeviceInfo;
+  readonly observedAt: string;
 }
 
-export interface IWizEvent {
-  type: 'pilot' | 'command_mapped' | 'command_failed' | 'udp_response' | 'error' | string;
-  timestamp?: number;
-  deviceId?: string;
-  entityId?: string;
-  command?: IWizClientCommand;
-  data?: unknown;
-  [key: string]: unknown;
-}
-
-export interface IWizClientCommand {
-  type: string;
-  service: string;
-  deviceId?: string;
-  entityId?: string;
-  payload: IWizPilotPatch;
-  target?: IServiceCallRequest['target'];
-  [key: string]: unknown;
-}
-
-export interface IWizCommandResult {
-  success: boolean;
-  error?: string;
-  data?: unknown;
-}
-
-export type TWizCommandExecutor = (
-  commandArg: IWizClientCommand
-) => Promise<IWizCommandResult | unknown> | IWizCommandResult | unknown;
-
-export interface IWizUdpCommand<TParams extends Record<string, unknown> = Record<string, unknown>> {
-  method: string;
-  params?: TParams;
-  id?: number | string;
-  env?: string;
-}
-
-export interface IWizUdpError {
-  code?: number;
-  message?: string;
-  data?: unknown;
-}
-
-export interface IWizUdpResponse<TResult = unknown> {
-  method?: string;
-  env?: string;
-  id?: number | string;
-  result?: TResult;
-  params?: TResult;
-  error?: IWizUdpError;
-  [key: string]: unknown;
+export interface IWizWriteResult {
+  readonly outcome: plugins.ecobridgeDeviceManager.TWizEffectOutcome;
+  readonly physicalStateConfirmed: false;
+  readonly observedState?: plugins.ecobridgeDeviceManager.IWizPilotState;
+  readonly errorCode?: plugins.ecobridgeDeviceManager.TWizErrorCode;
 }
 
 export interface IWizMdnsRecord {
@@ -229,37 +47,19 @@ export interface IWizMdnsRecord {
   port?: number;
   txt?: Record<string, string | undefined>;
   properties?: Record<string, string | undefined>;
-  [key: string]: unknown;
 }
 
 export interface IWizUdpDiscoveryRecord {
   host?: string;
-  address?: string;
-  ip?: string;
-  ip_address?: string;
   port?: number;
-  mac?: string;
-  mac_address?: string;
-  name?: string;
   method?: string;
   result?: Record<string, unknown>;
-  response?: IWizUdpResponse<Record<string, unknown>>;
-  metadata?: Record<string, unknown>;
-  [key: string]: unknown;
+  response?: { method?: string; result?: Record<string, unknown> };
 }
 
 export interface IWizManualEntry {
   host?: string;
   port?: number;
-  id?: string;
-  mac?: string;
   macAddress?: string;
   name?: string;
-  manufacturer?: string;
-  model?: string;
-  deviceInfo?: IWizDeviceInfo;
-  pilot?: IWizPilotState;
-  snapshot?: IWizSnapshot;
-  metadata?: Record<string, unknown>;
-  [key: string]: unknown;
 }

package/ts/integrations/wiz/wiz.validation.ts

@@ -0,0 +1,73 @@
+import * as plugins from '../../plugins.js';
+import type { IWizConfig, TWizControl } from './wiz.types.js';
+
+export function wizRecord(valueArg: unknown, allowedArg?: readonly string[]): Record<string, unknown> {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg) || Object.getPrototypeOf(valueArg) !== Object.prototype) {
+    throw new TypeError('WiZ inputs must be plain data objects.');
+  }
+  const result: Record<string, unknown> = {};
+  for (const key of Reflect.ownKeys(valueArg)) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (typeof key !== 'string' || allowedArg && !allowedArg.includes(key) || !descriptor || !('value' in descriptor) || !descriptor.enumerable) {
+      throw new TypeError('WiZ inputs may not contain accessors, symbols, hidden or unsupported fields.');
+    }
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true });
+  }
+  return result;
+}
+
+export function wizText(valueArg: unknown, nameArg: string, maximumArg = 256): string {
+  if (typeof valueArg !== 'string' || !valueArg.length || valueArg.length > maximumArg || valueArg !== valueArg.trim() || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError(`WiZ ${nameArg} must be bounded nonempty text without control characters.`);
+  }
+  return valueArg;
+}
+
+export function wizMac(valueArg: unknown): string {
+  if (typeof valueArg !== 'string' || !/^(?:[a-fA-F0-9]{12}|(?:[a-fA-F0-9]{2}:){5}[a-fA-F0-9]{2})$/.test(valueArg)) {
+    throw new TypeError('WiZ macAddress requires exactly six hexadecimal bytes.');
+  }
+  const mac = valueArg.replaceAll(':', '').toLowerCase();
+  if (mac === '000000000000' || (Number.parseInt(mac.slice(0, 2), 16) & 1) !== 0) throw new TypeError('WiZ requires a unicast device MAC.');
+  return mac;
+}
+
+export function wizAddress(valueArg: unknown): string {
+  if (typeof valueArg !== 'string' || plugins.net.isIP(valueArg) !== 4) throw new TypeError('WiZ requires an explicit local unicast IPv4 address.');
+  const parts = valueArg.split('.').map(Number);
+  const local = parts[0] === 10 || parts[0] === 127 || parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31 ||
+    parts[0] === 192 && parts[1] === 168 || parts[0] === 169 && parts[1] === 254;
+  if (!local || parts[3] === 0 || parts[3] === 255) throw new TypeError('WiZ requires a private, link-local or loopback unicast IPv4 address.');
+  return valueArg;
+}
+
+export function wizInteger(valueArg: unknown, fallbackArg: number, minimumArg: number, maximumArg: number): number {
+  const value = valueArg === undefined ? fallbackArg : valueArg;
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimumArg || value > maximumArg) {
+    throw new TypeError(`WiZ value must be an integer from ${minimumArg} through ${maximumArg}.`);
+  }
+  return value;
+}
+
+export function normalizeWizConfig(valueArg: unknown): Readonly<Required<Omit<IWizConfig, 'name'>> & Pick<IWizConfig, 'name'>> {
+  const value = wizRecord(valueArg, ['homeId', 'host', 'macAddress', 'port', 'name', 'timeoutMs', 'pollIntervalMs', 'maxPendingOperations', 'maxExchanges']);
+  const pollIntervalMs = wizInteger(value.pollIntervalMs, 30000, 0, 3600000);
+  if (pollIntervalMs > 0 && pollIntervalMs < 100) throw new TypeError('WiZ subscription polling must be disabled or at least 100 milliseconds.');
+  return Object.freeze({
+    homeId: wizText(value.homeId, 'homeId'), host: wizAddress(value.host), macAddress: wizMac(value.macAddress),
+    port: wizInteger(value.port, 38899, 1, 65535), ...(value.name === undefined ? {} : { name: wizText(value.name, 'name', 128) }),
+    timeoutMs: wizInteger(value.timeoutMs, 5000, 1, 60000), pollIntervalMs,
+    maxPendingOperations: wizInteger(value.maxPendingOperations, 16, 1, 128), maxExchanges: wizInteger(value.maxExchanges, 4096, 1, 16384),
+  });
+}
+
+export function wizControl(valueArg: unknown): TWizControl {
+  const value = wizRecord(valueArg, ['feature', 'value']);
+  if (value.feature === 'power' && typeof value.value === 'boolean') return Object.freeze({ feature: 'power', value: value.value });
+  if (value.feature === 'brightness') return Object.freeze({ feature: 'brightness', value: wizInteger(value.value, 0, 1, 100) });
+  if (value.feature === 'rgb') {
+    const rgb = wizRecord(value.value, ['red', 'green', 'blue']);
+    return Object.freeze({ feature: 'rgb', value: Object.freeze({ red: wizInteger(rgb.red, -1, 0, 255), green: wizInteger(rgb.green, -1, 0, 255), blue: wizInteger(rgb.blue, -1, 0, 255) }) });
+  }
+  throw new TypeError('WiZ supports one exact power, brightness or RGB control per operation.');
+}

package/ts/integrations/wled/index.ts

@@ -2,5 +2,6 @@ export * from './wled.classes.client.js';
 export * from './wled.classes.configflow.js';
 export * from './wled.classes.integration.js';
 export * from './wled.discovery.js';
+export * from './wled.errors.js';
 export * from './wled.mapper.js';
 export * from './wled.types.js';

package/ts/integrations/wled/readme.md

@@ -0,0 +1,83 @@
+# Native WLED integration
+
+The WLED integration connects directly to a controller’s JSON HTTP API and receives authoritative state changes through its `/ws` websocket endpoint. Controller MAC addresses define stable device and entity identities.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## Setup and control
+
+```typescript
+import { WledIntegration } from '@smarthome.exchange/integrations';
+
+const integration = new WledIntegration();
+const runtime = await integration.setup({
+  host: 'wled-desk.local',
+  expectedMac: 'aabbcc112233',
+  requestTimeoutMs: 5000,
+}, {});
+
+try {
+  const device = (await runtime.devices())[0];
+  const result = await runtime.callService!({
+    domain: 'light',
+    service: 'turn_on',
+    target: { deviceId: device.id },
+    data: { brightness: 128 },
+  });
+  if (!result.success) throw new Error(result.error);
+} finally {
+  await integration.destroy();
+}
+```
+
+`host` is a hostname or IP address, with optional `port` (default 80), `expectedMac`, and `requestTimeoutMs` (10–60000 ms). Config flow verifies the live JSON response and returns a configuration with its MAC pinned. Explicit unsupported settings are rejected, including credentials, alternate paths, TLS, snapshots, injected executors, and raw data. WLED itself provides neither API authentication nor native TLS; admission and home authorization remain the hub’s responsibility.
+
+Discovery admits manual entries explicitly marked `integrationDomain: 'wled'` and `_wled._tcp` mDNS records with valid `mac` TXT metadata. It copies endpoint fields only. It does not scan the network, trust an `esp32` name, fetch SSDP locations, or copy arbitrary candidate metadata into configuration.
+
+The device id is `wled.device.<mac>`. The controller entity is `light.wled_<mac>`, and an active segment’s entity is `light.wled_<mac>_segment_<id>`. Renaming a controller or segment preserves its identity. Exact entity targets select one segment; exact device targets select controller power and brightness. An entity and device target supplied together must refer to the same controller.
+
+| Service | Accepted data |
+| --- | --- |
+| `light.turn_on` | Optional `brightness`, `rgb_color`, `white`; colors require a segment target |
+| `light.turn_off` | No data |
+| `light.set_level` | Required integer `brightness` from 1 to 255 |
+| `light.set_color` | `rgb_color: [r, g, b]` and/or integer `white` from 0 to 255; requires a segment target |
+
+RGB controls appear only when `info.leds.seglc[id]` advertises RGB support. White controls additionally require an advertised white channel and a four-channel primary color. Each color channel is an integer from 0 to 255. RGB writes preserve the current white value; white writes preserve the current RGB values. Secondary and tertiary colors, other segments, effects and palettes are preserved. Firmware lacking capability metadata still exposes power and brightness, and rejects unverified color controls.
+
+`writeFeature()` accepts controller `power` and `brightness`, and segment `segment_<id>_power`, `segment_<id>_brightness`, `segment_<id>_rgb` (`#rrggbb`), and `segment_<id>_white` when advertised. It verifies the actual connected device and current capability rather than trusting caller-supplied feature flags.
+
+## State and lifecycle
+
+HTTP reads use `/json/si`. Writes use one POST to `/json/state`, followed by a fresh authoritative read. Each write sends the documented per-call `udpn.nn: true` flag to prevent UDP synchronization from changing other controllers. This does not change the controller’s persistent synchronization configuration. A firmware acknowledgement means API acceptance; it does not establish physical LED output. Writes are serialized, with at most 32 queued operations, and have a deadline covering queue wait, identity verification, acknowledgement and final state read. There are no automatic retries or optimistic state updates. A failure after attempting a POST returns `data.effectOutcome: 'indeterminate'`, and a `WledClient` caller receives `WledWriteError`; callers must reconcile the controller before deciding on a new action.
+
+`runtime.subscribe()` owns one receive-only websocket shared by subscribers. Full state and info pushes update entities, including segment addition and removal. The connection must provide a valid initial state before subscription succeeds. Malformed data, changed MAC identity, disconnects, and deadlines invalidate availability and close the socket. There is no automatic reconnect or polling fallback. Call `subscribe()` explicitly again to establish a new connection. Builds reporting `info.ws: -1` reject websocket subscriptions.
+
+Setup context cancellation closes all owned work. Per-operation signals cancel reads and feature writes. Removing the last subscriber terminates and drains its websocket, including an incomplete HTTP upgrade. `destroy()` aborts queued and active requests, drains the owned socket, and permanently closes the client or integration. Failed callbacks are unsubscribed without disrupting other subscribers. HTTP redirects are rejected, HTTP and websocket payloads are bounded to 1 MiB, and errors do not include raw device response bodies.
+
+Effects, palettes, presets, relative/toggle commands, nightlight, CCT, segment geometry, firmware/configuration writes, realtime frames and UDP synchronization are outside this native port. No real controller was used for verification; local HTTP and websocket fixtures cover the supported contract.
+
+Protocol references: [WLED JSON API](https://kno.wled.ge/interfaces/json-api/), [WLED websocket API](https://kno.wled.ge/interfaces/websocket/), and [official WLED mDNS advertisements](https://github.com/wled/WLED/blob/main/wled00/wled.cpp).
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [repository license file](../../../license.md).
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and are not included within the scope of the MIT license granted herein.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts/integrations/wled/wled.classes.client.ts

@@ -1,9 +1,211 @@
-import { SimpleLocalClient } from '../../core/index.js';
-import type { IWledConfig } from './wled.types.js';
-import { wledProfile } from './wled.types.js';
+import { DeviceCommunicationError } from '../../core/errors.js';
+import type { ILogger } from '../../core/types.js';
+import { WledSubscription } from './wled.classes.subscription.js';
+import { validateWledChange, wledPayload } from './wled.commands.js';
+import { WledWriteError } from './wled.errors.js';
+import { isWledRecord, parseWledSnapshot, wledConfig, wledEndpoint } from './wled.validation.js';
+import type { IWledConfig, IWledSnapshot, IWledStateChange, TWledClientEvent } from './wled.types.js';
 
-export class WledClient extends SimpleLocalClient<IWledConfig> {
-  constructor(configArg: IWledConfig) {
-    super(wledProfile, configArg);
+interface IWledSubscriber {
+  handler(eventArg: TWledClientEvent): void;
+  signal?: AbortSignal;
+  abort(): void;
+}
+
+export class WledClient {
+  private readonly config: IWledConfig;
+  private readonly endpoint: URL;
+  private readonly lifetime = new AbortController();
+  private readonly signal: AbortSignal;
+  private readonly subscribers = new Set<IWledSubscriber>();
+  private tail: Promise<void> = Promise.resolve();
+  private pending = 0;
+  private mac?: string;
+  private subscription?: WledSubscription;
+  private destroyed = false;
+  private healthy = false;
+
+  constructor(configArg: IWledConfig, signalArg?: AbortSignal, private readonly logger?: ILogger) {
+    this.config = wledConfig(configArg);
+    this.endpoint = wledEndpoint(this.config);
+    this.mac = this.config.expectedMac;
+    this.signal = AbortSignal.any([this.lifetime.signal, ...(signalArg ? [signalArg] : [])]);
+  }
+
+  public isHealthy(): boolean { return !this.destroyed && !this.signal.aborted && this.healthy && (!this.subscription || this.subscription.isHealthy); }
+
+  public getSnapshot(signalArg?: AbortSignal): Promise<IWledSnapshot> {
+    return this.enqueue((signal) => this.readSnapshot(signal), signalArg);
+  }
+
+  public setState(segmentIdArg: number | undefined, changeArg: IWledStateChange, signalArg?: AbortSignal): Promise<IWledSnapshot> {
+    if (segmentIdArg !== undefined && (!Number.isSafeInteger(segmentIdArg) || segmentIdArg < 0 || segmentIdArg > 254)) throw new Error('WLED segment id must be an integer between 0 and 254.');
+    const change = validateWledChange(changeArg);
+    let writeAttempted = false;
+    return this.enqueue(async (signal) => {
+      const before = await this.readSnapshot(signal);
+      const payload = wledPayload(before, segmentIdArg, change);
+      if (signal.aborted) throw new DOMException('WLED operation cancelled.', 'AbortError');
+      writeAttempted = true;
+      const response = await this.requestJson('/json/state', payload, signal);
+      if (!isWledRecord(response) || response.success !== true || response.error !== undefined) throw new DeviceCommunicationError('WLED did not acknowledge the state write.');
+      // Firmware acknowledgement is acceptance; the subsequent read is the authoritative state.
+      return this.readSnapshot(signal);
+    }, signalArg).catch((errorArg: unknown) => {
+      if (writeAttempted) throw new WledWriteError(errorArg instanceof Error ? errorArg : new DeviceCommunicationError('WLED write failed.'));
+      throw errorArg;
+    });
+  }
+
+  public async subscribe(handlerArg: (eventArg: TWledClientEvent) => void, signalArg?: AbortSignal): Promise<() => Promise<void>> {
+    this.assertActive(signalArg);
+    const initial = await this.getSnapshot(signalArg);
+    if (initial.info.ws === -1) throw new Error('This WLED build does not support websocket state updates.');
+    let rejectCancellation: ((errorArg: Error) => void) | undefined;
+    const cancellation = new Promise<never>((_, rejectArg) => { rejectCancellation = rejectArg; });
+    const subscriber: IWledSubscriber = {
+      handler: handlerArg,
+      signal: signalArg,
+      abort: () => {
+        rejectCancellation?.(new DOMException('WLED subscription cancelled.', 'AbortError'));
+        void unsubscribe();
+      },
+    };
+    const unsubscribe = async (): Promise<void> => {
+      signalArg?.removeEventListener('abort', subscriber.abort);
+      this.subscribers.delete(subscriber);
+      if (this.subscribers.size === 0 && this.subscription) {
+        const subscription = this.subscription;
+        await subscription.stop();
+        if (this.subscription === subscription) this.subscription = undefined;
+      }
+    };
+    this.subscribers.add(subscriber);
+    signalArg?.addEventListener('abort', subscriber.abort, { once: true });
+    if (signalArg?.aborted) subscriber.abort();
+    try {
+      await Promise.race([this.connectSubscription(), cancellation]);
+      this.assertActive(signalArg);
+      rejectCancellation = undefined;
+      return unsubscribe;
+    } catch (errorArg) { await unsubscribe(); throw errorArg; }
+  }
+
+  public async destroy(): Promise<void> {
+    this.destroyed = true;
+    this.healthy = false;
+    this.lifetime.abort();
+    for (const subscriber of this.subscribers) subscriber.signal?.removeEventListener('abort', subscriber.abort);
+    this.subscribers.clear();
+    await Promise.all([this.tail, this.subscription?.stop()]);
+    this.subscription = undefined;
+  }
+
+  private async connectSubscription(): Promise<void> {
+    if (this.subscription?.isStopping) {
+      const previous = this.subscription;
+      await previous.stop();
+      if (this.subscription === previous) this.subscription = undefined;
+    }
+    this.assertActive();
+    if (this.subscription?.isClosed) this.subscription = undefined;
+    if (!this.subscription) {
+      if (!this.mac) throw new Error('WLED subscription requires a verified device identity.');
+      const url = new URL('/ws', this.endpoint);
+      url.protocol = 'ws:';
+      this.subscription = new WledSubscription({
+        url, mac: this.mac, timeoutMs: this.config.requestTimeoutMs ?? 5000, signal: this.signal,
+        onSnapshot: (snapshotArg) => { this.healthy = true; this.emit({ type: 'snapshot', snapshot: snapshotArg }); },
+        onAvailability: (availableArg) => { this.healthy = availableArg; this.emit({ type: 'availability', available: availableArg }); },
+        onError: (errorArg) => { this.healthy = false; this.emit({ type: 'error', error: errorArg }); },
+      });
+    }
+    await this.subscription.start();
+  }
+
+  private emit(eventArg: TWledClientEvent): void {
+    if (this.destroyed || this.signal.aborted) return;
+    for (const subscriber of [...this.subscribers]) {
+      if (!this.subscribers.has(subscriber)) continue;
+      try { subscriber.handler(structuredClone(eventArg)); }
+      catch {
+        this.logger?.log('error', 'WLED subscriber callback failed.');
+        subscriber.abort();
+      }
+    }
+  }
+
+  private async readSnapshot(signalArg: AbortSignal): Promise<IWledSnapshot> {
+    const snapshot = parseWledSnapshot(await this.requestJson('/json/si', undefined, signalArg), this.mac);
+    this.assertActive(signalArg);
+    this.mac = snapshot.info.mac;
+    this.healthy = true;
+    return structuredClone(snapshot);
+  }
+
+  private enqueue<TResult>(operationArg: (signalArg: AbortSignal) => Promise<TResult>, signalArg?: AbortSignal): Promise<TResult> {
+    this.assertActive(signalArg);
+    if (this.pending >= 32) throw new Error('WLED operation queue is full.');
+    this.pending++;
+    const timeout = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; timeout.abort(); }, this.config.requestTimeoutMs ?? 5000);
+    const signal = AbortSignal.any([this.signal, timeout.signal, ...(signalArg ? [signalArg] : [])]);
+    const cancelled = (): Error => timedOut ? new DeviceCommunicationError('WLED operation timed out.') : new DOMException('WLED operation cancelled.', 'AbortError');
+    let rejectCancellation: ((errorArg: Error) => void) | undefined;
+    const cancellation = new Promise<never>((_, rejectArg) => { rejectCancellation = rejectArg; });
+    const handleAbort = (): void => { this.healthy = false; rejectCancellation?.(cancelled()); };
+    signal.addEventListener('abort', handleAbort, { once: true });
+    if (signal.aborted) handleAbort();
+    const operation = this.tail.then(async () => {
+      if (signal.aborted) throw cancelled();
+      return operationArg(signal);
+    }).catch((errorArg: unknown) => {
+      this.healthy = false;
+      if (timedOut) throw new DeviceCommunicationError('WLED operation timed out.');
+      if (signal.aborted) throw new DOMException('WLED operation cancelled.', 'AbortError');
+      if (errorArg instanceof Error) throw errorArg;
+      throw new DeviceCommunicationError('WLED operation failed.');
+    }).finally(() => {
+      this.pending--;
+      clearTimeout(timer);
+      signal.removeEventListener('abort', handleAbort);
+      rejectCancellation = undefined;
+    });
+    this.tail = operation.then(() => undefined, () => undefined);
+    return Promise.race([operation, cancellation]);
+  }
+
+  private async requestJson(pathArg: string, bodyArg: Record<string, unknown> | undefined, signalArg: AbortSignal): Promise<unknown> {
+    let response: Response;
+    try {
+      response = await fetch(new URL(pathArg, this.endpoint), { method: bodyArg ? 'POST' : 'GET', headers: { accept: 'application/json', ...(bodyArg ? { 'content-type': 'application/json' } : {}) }, body: bodyArg ? JSON.stringify(bodyArg) : undefined, signal: signalArg, redirect: 'error' });
+    } catch { throw new DeviceCommunicationError('WLED HTTP request failed.'); }
+    if (!response.ok || !response.body) {
+      await response.body?.cancel();
+      throw new DeviceCommunicationError(`WLED HTTP request failed with status ${response.status}.`);
+    }
+    const reader = response.body.getReader();
+    const chunks: Uint8Array[] = [];
+    let size = 0;
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        size += value.byteLength;
+        if (size > 1024 * 1024) throw new DeviceCommunicationError('WLED HTTP response exceeds the size limit.');
+        chunks.push(value);
+      }
+      try { return JSON.parse(Buffer.concat(chunks).toString('utf8')) as unknown; }
+      catch { throw new DeviceCommunicationError('WLED returned invalid HTTP JSON.'); }
+    } catch (errorArg) {
+      await reader.cancel();
+      throw errorArg;
+    } finally { reader.releaseLock(); }
+  }
+
+  private assertActive(signalArg?: AbortSignal): void {
+    if (this.destroyed) throw new Error('WLED client has been destroyed.');
+    if (this.signal.aborted || signalArg?.aborted) throw new DOMException('WLED operation cancelled.', 'AbortError');
   }
 }