@smarthome.exchange/integrations 0.1.0 → 1.0.0

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');
   }
 }

package/ts/integrations/wled/wled.classes.configflow.ts

@@ -1,9 +1,30 @@
-import { SimpleLocalConfigFlow } from '../../core/index.js';
+import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
+import { WledClient } from './wled.classes.client.js';
+import { wledPlainFields } from './wled.commands.js';
+import { WledCandidateValidator } from './wled.discovery.js';
+import { wledConfig } from './wled.validation.js';
 import type { IWledConfig } from './wled.types.js';
-import { wledProfile } from './wled.types.js';
 
-export class WledConfigFlow extends SimpleLocalConfigFlow<IWledConfig> {
-  constructor() {
-    super(wledProfile);
+export class WledConfigFlow implements IConfigFlow<IWledConfig> {
+  public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IWledConfig>> {
+    void contextArg;
+    const admitted = await new WledCandidateValidator().validate(candidateArg);
+    const endpoint = admitted.candidate;
+    if (!endpoint) return { kind: 'error', error: 'WLED config flow requires an admitted WLED manual or mDNS endpoint.' };
+    return {
+      kind: 'form', title: 'Connect WLED', description: 'Validate the controller HTTP endpoint and pin its returned MAC identity. WLED has no API authentication or native TLS.',
+      fields: [{ name: 'host', label: 'Host', type: 'text', required: true }, { name: 'port', label: 'Port', type: 'number' }, { name: 'expectedMac', label: 'Expected MAC', type: 'text' }],
+      submit: async (valuesArg) => {
+        if (!wledPlainFields(valuesArg, ['host', 'port', 'expectedMac'])) return { kind: 'error', error: 'WLED config contains unsupported settings.' };
+        let client: WledClient | undefined;
+        try {
+          const config = wledConfig({ host: valuesArg.host === undefined ? endpoint.host : valuesArg.host, port: valuesArg.port === undefined ? endpoint.port : valuesArg.port, expectedMac: valuesArg.expectedMac === undefined ? endpoint.macAddress : valuesArg.expectedMac });
+          client = new WledClient(config);
+          const snapshot = await client.getSnapshot();
+          return { kind: 'done', title: 'WLED configured', config: { ...config, expectedMac: snapshot.info.mac } };
+        } catch { return { kind: 'error', error: 'Could not validate the WLED endpoint or MAC identity.' }; }
+        finally { await client?.destroy(); }
+      },
+    };
   }
 }

package/ts/integrations/wled/wled.classes.integration.ts

@@ -1,17 +1,152 @@
-import { SimpleLocalIntegration } from '../../core/index.js';
+import * as plugins from '../../plugins.js';
+import { BaseIntegration } from '../../core/classes.baseintegration.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import { WledClient } from './wled.classes.client.js';
 import { WledConfigFlow } from './wled.classes.configflow.js';
+import { wledPlainFields, validateWledChange } from './wled.commands.js';
 import { createWledDiscoveryDescriptor } from './wled.discovery.js';
-import type { IWledConfig } from './wled.types.js';
-import { wledDomain, wledProfile } from './wled.types.js';
+import { WledMapper } from './wled.mapper.js';
+import type { IWledConfig, IWledSnapshot, IWledStateChange } from './wled.types.js';
+import { wledProfile } from './wled.types.js';
+import { WledWriteError } from './wled.errors.js';
 
-export class WledIntegration extends SimpleLocalIntegration<IWledConfig> {
-  public readonly domain = wledDomain;
+export class WledIntegration extends BaseIntegration<IWledConfig> {
+  public readonly domain = 'wled';
+  public readonly displayName = 'WLED';
+  public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createWledDiscoveryDescriptor();
   public readonly configFlow = new WledConfigFlow();
+  public readonly metadata = wledProfile.metadata;
+  private readonly runtimes = new Set<WledRuntime>();
+  private readonly pendingClients = new Set<WledClient>();
+  private destroyed = false;
 
-  constructor() {
-    super(wledProfile);
+  public async setup(configArg: IWledConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    if (this.destroyed) throw new Error('WLED integration has been destroyed.');
+    const client = new WledClient(configArg, contextArg.abortSignal, contextArg.logger);
+    this.pendingClients.add(client);
+    try {
+      const snapshot = await client.getSnapshot();
+      if (this.destroyed) throw new Error('WLED integration has been destroyed.');
+      const runtime = new WledRuntime(client, snapshot, () => this.runtimes.delete(runtime));
+      this.runtimes.add(runtime);
+      this.pendingClients.delete(client);
+      return runtime;
+    } catch (errorArg) {
+      await client.destroy();
+      this.pendingClients.delete(client);
+      throw errorArg;
+    }
+  }
+
+  public async destroy(): Promise<void> {
+    this.destroyed = true;
+    await Promise.all([...this.runtimes].map((runtimeArg) => runtimeArg.destroy()).concat([...this.pendingClients].map(async (clientArg) => {
+      await clientArg.destroy();
+      this.pendingClients.delete(clientArg);
+    })));
   }
 }
 
 export class HomeAssistantWledIntegration extends WledIntegration {}
+
+class WledRuntime implements IIntegrationRuntime {
+  public readonly domain = 'wled';
+
+  constructor(private readonly client: WledClient, private snapshot: IWledSnapshot, private readonly onDestroyed: () => void) {}
+
+  public isHealthy(): boolean { return this.client.isHealthy(); }
+  public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    this.snapshot = await this.client.getSnapshot(signalArg);
+    return WledMapper.toDevices(this.snapshot, this.isHealthy());
+  }
+  public async entities(): Promise<IIntegrationEntity[]> {
+    this.snapshot = await this.client.getSnapshot();
+    return WledMapper.toEntities(this.snapshot, this.isHealthy());
+  }
+
+  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, signalArg?: AbortSignal): Promise<() => Promise<void>> {
+    let previous = WledMapper.toEntities(this.snapshot);
+    return this.client.subscribe((eventArg) => {
+      const emit = (event: Omit<IIntegrationEvent, 'integrationDomain' | 'deviceId' | 'timestamp'>): void => handlerArg({
+        ...event, integrationDomain: this.domain, deviceId: WledMapper.deviceId(this.snapshot), timestamp: Date.now(),
+      });
+      if (eventArg.type === 'snapshot') {
+        this.snapshot = eventArg.snapshot;
+        const current = WledMapper.toEntities(this.snapshot, true);
+        for (const entity of current) {
+          const old = previous.find((entryArg) => entryArg.id === entity.id);
+          if (JSON.stringify(old) !== JSON.stringify(entity)) emit({ type: old ? 'state_changed' : 'entity_added', entityId: entity.id, data: { entity } });
+        }
+        for (const entity of previous) if (!current.some((entryArg) => entryArg.id === entity.id)) emit({ type: 'entity_removed', entityId: entity.id });
+        previous = current;
+      } else if (eventArg.type === 'availability') emit({ type: 'availability_changed', data: { available: eventArg.available } });
+      else emit({ type: 'error', data: { message: eventArg.error.message } });
+    }, signalArg);
+  }
+
+  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
+    try {
+      if (!wledPlainFields(requestArg, ['domain', 'service', 'target', 'data']) || !wledPlainFields(requestArg.target, ['deviceId', 'entityId'])) throw new Error('WLED requires a plain service request and exact target.');
+      if (requestArg.domain !== 'light' || !['turn_on', 'turn_off', 'set_level', 'set_color'].includes(requestArg.service)) throw new Error('WLED supports light.turn_on, turn_off, set_level and set_color.');
+      const segmentId = this.targetSegment(requestArg.target);
+      const fields = requestArg.service === 'turn_off' ? [] : requestArg.service === 'set_level' ? ['brightness'] : requestArg.service === 'set_color' ? ['rgb_color', 'white'] : ['brightness', 'rgb_color', 'white'];
+      const data = requestArg.data ?? {};
+      if (!wledPlainFields(data, fields) || Object.values(data).some((valueArg) => valueArg === undefined)) throw new Error('WLED service contains unsupported or undefined data.');
+      if (requestArg.service === 'set_level' && data.brightness === undefined || requestArg.service === 'set_color' && data.rgb_color === undefined && data.white === undefined) throw new Error('WLED service requires an explicit value.');
+      const change = validateWledChange({
+        on: requestArg.service === 'turn_on' ? true : requestArg.service === 'turn_off' ? false : undefined,
+        brightness: data.brightness, rgb: data.rgb_color, white: data.white,
+      });
+      this.snapshot = await this.client.setState(segmentId, change);
+      return { success: true, data: structuredClone(this.snapshot) };
+    } catch (errorArg) { return this.failure(errorArg); }
+  }
+
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    try {
+      if (!wledPlainFields(requestArg, ['device', 'feature', 'value'], ['device', 'feature', 'value']) ||
+        !wledPlainFields(requestArg.device, ['id', 'integrationDomain', 'name', 'room', 'protocol', 'manufacturer', 'model', 'online', 'features', 'state', 'metadata'], ['id', 'integrationDomain']) ||
+        !wledPlainFields(requestArg.feature, ['id', 'capability', 'name', 'readable', 'writable', 'unit'], ['id'])) throw new Error('WLED feature writes require a plain request, device, feature and own value without accessors.');
+      if (requestArg.device.id !== WledMapper.deviceId(this.snapshot) || requestArg.device.integrationDomain !== this.domain) throw new Error('WLED feature target does not belong to this controller.');
+      const device = WledMapper.toDevices(this.snapshot)[0];
+      const feature = device.features.find((entryArg) => entryArg.id === requestArg.feature.id);
+      if (!feature?.writable) throw new Error('WLED feature is not a writable capability of this controller.');
+      const segment = /^segment_(\d+)_(power|brightness|rgb|white)$/.exec(feature.id);
+      const key = segment?.[2] ?? feature.id;
+      const change: IWledStateChange = {};
+      if (key === 'power') {
+        if (typeof requestArg.value !== 'boolean') throw new Error('WLED power requires a boolean.');
+        change.on = requestArg.value;
+      } else if (key === 'brightness' || key === 'white') {
+        if (typeof requestArg.value !== 'number') throw new Error('WLED brightness and white require integer values.');
+        change[key] = requestArg.value;
+      } else if (key === 'rgb') {
+        if (typeof requestArg.value !== 'string' || !/^#[a-f\d]{6}$/i.test(requestArg.value)) throw new Error('WLED RGB feature requires #rrggbb.');
+        const value = requestArg.value;
+        change.rgb = [Number.parseInt(value.slice(1, 3), 16), Number.parseInt(value.slice(3, 5), 16), Number.parseInt(value.slice(5, 7), 16)];
+      } else throw new Error('WLED feature is not supported.');
+      this.snapshot = await this.client.setState(segment ? Number(segment[1]) : undefined, change, signalArg);
+      return { success: true, data: structuredClone(this.snapshot) };
+    } catch (errorArg) { return this.failure(errorArg); }
+  }
+
+  public async destroy(): Promise<void> { await this.client.destroy(); this.onDestroyed(); }
+
+  private targetSegment(targetArg: { entityId?: string; deviceId?: string }): number | undefined {
+    const deviceId = WledMapper.deviceId(this.snapshot);
+    if (targetArg.deviceId !== undefined && targetArg.deviceId !== deviceId) throw new Error('WLED device target does not belong to this controller.');
+    if (targetArg.entityId === undefined) {
+      if (targetArg.deviceId !== deviceId) throw new Error('WLED requires an exact controller or segment target.');
+      return undefined;
+    }
+    if (targetArg.entityId === WledMapper.entityId(this.snapshot)) return undefined;
+    const segment = this.snapshot.state.seg.find((entryArg) => WledMapper.entityId(this.snapshot, entryArg.id) === targetArg.entityId);
+    if (!segment) throw new Error('WLED entity target does not belong to an active segment of this controller.');
+    return segment.id;
+  }
+
+  private failure(errorArg: unknown): IServiceCallResult {
+    return { success: false, error: errorArg instanceof Error ? errorArg.message : 'WLED operation failed.', data: { effectOutcome: errorArg instanceof WledWriteError ? errorArg.effectOutcome : 'not-sent' } };
+  }
+}

package/ts/integrations/wled/wled.classes.subscription.ts

@@ -0,0 +1,122 @@
+import * as plugins from '../../plugins.js';
+import { DeviceCommunicationError } from '../../core/errors.js';
+import { parseWledSnapshot } from './wled.validation.js';
+import type { IWledSnapshot } from './wled.types.js';
+
+interface IWledSubscriptionOptions {
+  url: URL;
+  mac: string;
+  timeoutMs: number;
+  signal: AbortSignal;
+  onSnapshot(snapshotArg: IWledSnapshot): void;
+  onAvailability(availableArg: boolean): void;
+  onError(errorArg: Error): void;
+}
+
+export class WledSubscription {
+  private socket?: plugins.ws.WebSocket;
+  private starting?: Promise<void>;
+  private resolveStart?: () => void;
+  private rejectStart?: (errorArg: Error) => void;
+  private closing?: Promise<void>;
+  private resolveClose?: () => void;
+  private deadline?: ReturnType<typeof setTimeout>;
+  private stopping = false;
+  private closed = false;
+  private healthy = false;
+
+  constructor(private readonly options: IWledSubscriptionOptions) {}
+
+  public get isHealthy(): boolean { return this.healthy && !this.stopping; }
+  public get isClosed(): boolean { return this.closed; }
+  public get isStopping(): boolean { return this.stopping; }
+
+  public start(): Promise<void> {
+    if (this.starting) return this.starting;
+    if (this.stopping || this.options.signal.aborted) return Promise.reject(new DOMException('WLED subscription cancelled.', 'AbortError'));
+    this.starting = new Promise<void>((resolveArg, rejectArg) => { this.resolveStart = resolveArg; this.rejectStart = rejectArg; });
+    this.closing = new Promise<void>((resolveArg) => { this.resolveClose = resolveArg; });
+    this.options.signal.addEventListener('abort', this.handleAbort, { once: true });
+    this.deadline = setTimeout(() => this.fail(new DeviceCommunicationError('WLED websocket initial state timed out.')), this.options.timeoutMs);
+    try {
+      this.socket = new plugins.ws.WebSocket(this.options.url, { handshakeTimeout: this.options.timeoutMs, followRedirects: false, perMessageDeflate: false, maxPayload: 1024 * 1024 });
+      this.socket.on('message', this.handleMessage);
+      this.socket.on('error', this.handleError);
+      this.socket.on('close', this.handleClose);
+    } catch {
+      this.fail(new DeviceCommunicationError('WLED websocket connection failed.'));
+      this.finishClose();
+    }
+    return this.starting;
+  }
+
+  public async stop(): Promise<void> {
+    this.stopping = true;
+    this.setHealthy(false);
+    clearTimeout(this.deadline);
+    this.rejectStart?.(new DOMException('WLED subscription cancelled.', 'AbortError'));
+    this.rejectStart = undefined;
+    this.resolveStart = undefined;
+    if (!this.socket || this.closed) { this.finishClose(); return; }
+    // This receive-only socket owns no outstanding command acknowledgement to preserve.
+    this.socket.terminate();
+    await this.closing;
+  }
+
+  private readonly handleMessage = (dataArg: plugins.ws.RawData, binaryArg: boolean): void => {
+    if (this.stopping) return;
+    try {
+      if (binaryArg) throw new DeviceCommunicationError('WLED returned an unexpected binary websocket message.');
+      const data = Array.isArray(dataArg) ? Buffer.concat(dataArg) : dataArg instanceof ArrayBuffer ? Buffer.from(new Uint8Array(dataArg)) : dataArg;
+      const value: unknown = JSON.parse(data.toString('utf8'));
+      const snapshot = parseWledSnapshot(value, this.options.mac);
+      this.options.onSnapshot(snapshot);
+      clearTimeout(this.deadline);
+      this.setHealthy(true);
+      this.resolveStart?.();
+      this.resolveStart = undefined;
+      this.rejectStart = undefined;
+    } catch (errorArg) {
+      this.fail(errorArg instanceof DeviceCommunicationError ? errorArg : new DeviceCommunicationError('WLED returned invalid websocket JSON.'));
+    }
+  };
+
+  private readonly handleError = (): void => {
+    if (!this.stopping) this.fail(new DeviceCommunicationError('WLED websocket connection failed.'));
+  };
+
+  private readonly handleClose = (): void => {
+    if (!this.stopping) this.fail(new DeviceCommunicationError('WLED websocket connection closed.'));
+    this.finishClose();
+  };
+
+  private readonly handleAbort = (): void => { void this.stop(); };
+
+  private fail(errorArg: Error): void {
+    this.setHealthy(false);
+    clearTimeout(this.deadline);
+    this.rejectStart?.(errorArg);
+    this.rejectStart = undefined;
+    this.resolveStart = undefined;
+    this.options.onError(errorArg);
+    void this.stop();
+  }
+
+  private setHealthy(valueArg: boolean): void {
+    if (this.healthy === valueArg) return;
+    this.healthy = valueArg;
+    this.options.onAvailability(valueArg);
+  }
+
+  private finishClose(): void {
+    if (this.closed) return;
+    this.closed = true;
+    clearTimeout(this.deadline);
+    this.options.signal.removeEventListener('abort', this.handleAbort);
+    this.socket?.removeListener('message', this.handleMessage);
+    this.socket?.removeListener('error', this.handleError);
+    this.socket?.removeListener('close', this.handleClose);
+    this.resolveClose?.();
+    this.resolveClose = undefined;
+  }
+}

package/ts/integrations/wled/wled.commands.ts

@@ -0,0 +1,54 @@
+import type { IWledSnapshot, IWledStateChange } from './wled.types.js';
+import { isWledRecord, wledInteger } from './wled.validation.js';
+
+export const wledPlainFields = (valueArg: unknown, fieldsArg: string[], requiredFieldsArg: string[] = []): valueArg is Record<string, unknown> => {
+  if (!isWledRecord(valueArg) || Object.getPrototypeOf(valueArg) !== Object.prototype) return false;
+  const descriptors = Object.getOwnPropertyDescriptors(valueArg);
+  return Reflect.ownKeys(valueArg).every((keyArg) => typeof keyArg === 'string' && fieldsArg.includes(keyArg) && 'value' in descriptors[keyArg]) &&
+    requiredFieldsArg.every((keyArg) => descriptors[keyArg] !== undefined && 'value' in descriptors[keyArg]);
+};
+
+const wledRgb = (valueArg: unknown): [number, number, number] => {
+  const invalid = (): never => { throw new Error('WLED RGB requires three own integer color channels between 0 and 255.'); };
+  if (!Array.isArray(valueArg) || valueArg.length !== 3) return invalid();
+  const descriptors = Object.getOwnPropertyDescriptors(valueArg);
+  if (Reflect.ownKeys(valueArg).some((keyArg) => typeof keyArg !== 'string' || !['0', '1', '2', 'length'].includes(keyArg) || !('value' in descriptors[keyArg]))) return invalid();
+  const channel = (indexArg: string): number => {
+    const descriptor = descriptors[indexArg];
+    const value: unknown = descriptor?.value;
+    if (!descriptor || !('value' in descriptor) || !wledInteger(value, 0, 255)) return invalid();
+    return value;
+  };
+  return [channel('0'), channel('1'), channel('2')];
+};
+
+export const validateWledChange = (valueArg: unknown): IWledStateChange => {
+  if (!wledPlainFields(valueArg, ['on', 'brightness', 'rgb', 'white']) || Object.keys(valueArg).length === 0) throw new Error('WLED state changes require explicit supported values.');
+  if (valueArg.on !== undefined && typeof valueArg.on !== 'boolean' || valueArg.brightness !== undefined && !wledInteger(valueArg.brightness, 1, 255) || valueArg.white !== undefined && !wledInteger(valueArg.white, 0, 255)) throw new Error('WLED requires boolean power and bounded integer brightness or white values.');
+  let rgb: [number, number, number] | undefined;
+  if (valueArg.rgb !== undefined) rgb = wledRgb(valueArg.rgb);
+  const change: IWledStateChange = { on: valueArg.on, brightness: valueArg.brightness, rgb, white: valueArg.white };
+  if (Object.values(change).every((entryArg) => entryArg === undefined)) throw new Error('WLED state changes must contain a value.');
+  return change;
+};
+
+export const wledPayload = (snapshotArg: IWledSnapshot, segmentIdArg: number | undefined, changeArg: IWledStateChange): Record<string, unknown> => {
+  const payload: Record<string, unknown> = {};
+  if (changeArg.on !== undefined) payload.on = changeArg.on;
+  if (changeArg.brightness !== undefined) payload.bri = changeArg.brightness;
+  if (segmentIdArg === undefined) {
+    if (changeArg.rgb !== undefined || changeArg.white !== undefined) throw new Error('WLED color writes require an exact segment target.');
+    return { ...payload, udpn: { nn: true } };
+  }
+  const segment = snapshotArg.state.seg.find((entryArg) => entryArg.id === segmentIdArg);
+  if (!segment) throw new Error('WLED target segment is not active on the connected controller.');
+  const capabilities = snapshotArg.info.leds.seglc?.[segmentIdArg] ?? 0;
+  if (changeArg.rgb !== undefined && !(capabilities & 1) || changeArg.white !== undefined && (!(capabilities & 2) || segment.col[0].length !== 4)) throw new Error('WLED segment does not advertise the requested color capability.');
+  if (changeArg.rgb !== undefined || changeArg.white !== undefined) {
+    const color = [...segment.col[0]];
+    if (changeArg.rgb !== undefined) color.splice(0, 3, ...changeArg.rgb);
+    if (changeArg.white !== undefined) color[3] = changeArg.white;
+    payload.col = [color];
+  }
+  return { seg: [{ id: segmentIdArg, ...payload }], udpn: { nn: true } };
+};

package/ts/integrations/wled/wled.discovery.ts

@@ -1,4 +1,53 @@
-import { createSimpleLocalDiscoveryDescriptor } from '../../core/index.js';
-import { wledProfile } from './wled.types.js';
+import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
+import type { IDiscoveryCandidate, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
+import { isWledRecord, normalizeWledMac, wledConfig } from './wled.validation.js';
 
-export const createWledDiscoveryDescriptor = () => createSimpleLocalDiscoveryDescriptor(wledProfile);
+const unmatched = (): IDiscoveryMatch => ({ matched: false, confidence: 'low', reason: 'Record is not an explicit WLED endpoint or official WLED mDNS advertisement.' });
+
+const plainRecord = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  isWledRecord(valueArg) && Object.getPrototypeOf(valueArg) === Object.prototype && Reflect.ownKeys(valueArg).every((keyArg) => typeof keyArg === 'string' && 'value' in Object.getOwnPropertyDescriptor(valueArg, keyArg)!);
+
+const candidate = (valueArg: unknown, sourceArg: 'manual' | 'mdns'): IDiscoveryMatch => {
+  if (!plainRecord(valueArg) || valueArg.integrationDomain !== undefined && valueArg.integrationDomain !== 'wled') return unmatched();
+  if (sourceArg === 'manual' && valueArg.integrationDomain !== 'wled') return unmatched();
+  let expectedMac: string | undefined;
+  if (sourceArg === 'mdns') {
+    if (typeof valueArg.type !== 'string' || !/^_wled\._tcp(?:\.local)?\.?$/i.test(valueArg.type) || !plainRecord(valueArg.txt)) return unmatched();
+    try { expectedMac = normalizeWledMac(valueArg.txt.mac); } catch { return unmatched(); }
+  } else if (valueArg.macAddress !== undefined) {
+    try { expectedMac = normalizeWledMac(valueArg.macAddress); } catch { return unmatched(); }
+  }
+  try {
+    const config = wledConfig({ host: valueArg.host, port: valueArg.port, expectedMac });
+    const result: IDiscoveryCandidate = { source: sourceArg, integrationDomain: 'wled', host: config.host, port: config.port, macAddress: expectedMac, manufacturer: 'WLED' };
+    // Discovery data is untrusted; no arbitrary metadata becomes connection settings.
+    return { matched: true, confidence: 'high', reason: 'WLED endpoint admitted; setup will verify its JSON API and MAC.', candidate: result, normalizedDeviceId: expectedMac ? `wled.device.${expectedMac}` : undefined };
+  } catch { return unmatched(); }
+};
+
+export class WledManualMatcher implements IDiscoveryMatcher {
+  public readonly id = 'wled-manual-match';
+  public readonly source = 'manual' as const;
+  public async matches(valueArg: unknown): Promise<IDiscoveryMatch> { return candidate(valueArg, 'manual'); }
+}
+
+export class WledMdnsMatcher implements IDiscoveryMatcher {
+  public readonly id = 'wled-mdns-match';
+  public readonly source = 'mdns' as const;
+  public async matches(valueArg: unknown): Promise<IDiscoveryMatch> { return candidate(valueArg, 'mdns'); }
+}
+
+export class WledCandidateValidator implements IDiscoveryValidator {
+  public readonly id = 'wled-candidate-validator';
+  public async validate(valueArg: IDiscoveryCandidate): Promise<IDiscoveryMatch> {
+    if (!plainRecord(valueArg) || valueArg.source !== 'manual' && valueArg.source !== 'mdns' || valueArg.integrationDomain !== 'wled') return unmatched();
+    if (valueArg.source === 'mdns') {
+      try { normalizeWledMac(valueArg.macAddress); } catch { return unmatched(); }
+    }
+    const result = candidate(valueArg, 'manual');
+    return result.candidate ? { ...result, candidate: { ...result.candidate, source: valueArg.source === 'mdns' ? 'mdns' : 'manual' } } : result;
+  }
+}
+
+export const createWledDiscoveryDescriptor = (): DiscoveryDescriptor => new DiscoveryDescriptor({ integrationDomain: 'wled', displayName: 'WLED' })
+  .addMatcher(new WledManualMatcher()).addMatcher(new WledMdnsMatcher()).addValidator(new WledCandidateValidator());