@smarthome.exchange/integrations 1.0.0 → 3.0.0

package/ts/integrations/webostv/webostv.classes.integration.ts

@@ -1,14 +1,14 @@
 import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
-import { NoSqlConfigStore } from '../../core/classes.configstore.js';
-import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import { NativeIntegrationOwner } from '../../core/classes.nativeintegrationowner.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, INativeIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { WebostvClient } from './webostv.classes.client.js';
 import { WebostvConfigFlow } from './webostv.classes.configflow.js';
 import { createWebostvDiscoveryDescriptor } from './webostv.discovery.js';
 import { WebostvMapper } from './webostv.mapper.js';
 import type { IWebostvConfig, IWebostvIntegrationOptions, IWebostvSnapshot, TWebostvCommand } from './webostv.types.js';
 import { webostvProfile } from './webostv.types.js';
-import { webostvKeys, webostvObject } from './webostv.validation.js';
+import { normalizeWebostvConfig, normalizeWebostvOptions, webostvKeys, webostvObject } from './webostv.validation.js';
 
 export class WebostvIntegration extends BaseIntegration<IWebostvConfig> {
   public readonly domain = 'webostv';
@@ -16,51 +16,58 @@ export class WebostvIntegration extends BaseIntegration<IWebostvConfig> {
   public readonly status = 'control-runtime' as const;
   public readonly metadata = webostvProfile.metadata;
   public readonly discoveryDescriptor = createWebostvDiscoveryDescriptor();
-  public readonly configFlow = new WebostvConfigFlow();
-  readonly #runtimes = new Set<WebostvRuntime>();
-  readonly #pending = new Set<WebostvClient>();
-  #destroyed = false;
+  public readonly configFlow: WebostvConfigFlow;
+  readonly #owner: NativeIntegrationOwner;
+  readonly #options: Readonly<IWebostvIntegrationOptions>;
   #destroy?: Promise<void>;
 
-  constructor(private readonly options?: IWebostvIntegrationOptions) { super(); }
-
-  public async setup(configArg: IWebostvConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    if (this.#destroyed) throw new Error('webOS integration is destroyed.');
-    if (contextArg.configStore !== undefined && !(contextArg.configStore instanceof NoSqlConfigStore)) throw new TypeError('webOS runtime context requires an encrypted NoSqlConfigStore.');
-    const client = new WebostvClient(configArg, contextArg.configStore ?? this.options, contextArg.abortSignal);
-    this.#pending.add(client);
-    try {
-      const snapshot = await client.getSnapshot(contextArg.abortSignal);
-      if (this.#destroyed) throw new Error('webOS integration was destroyed during setup.');
-      const runtime = new WebostvRuntime(client, snapshot, () => this.#runtimes.delete(runtime));
-      this.#runtimes.add(runtime);
-      return runtime;
-    } catch (errorArg) { await client.destroy(); throw errorArg; }
-    finally { this.#pending.delete(client); }
+  constructor(optionsArg: IWebostvIntegrationOptions = {}) {
+    super();
+    this.#options = normalizeWebostvOptions(optionsArg);
+    this.#owner = new NativeIntegrationOwner(this.domain, { homeId: this.#options.homeId, capacity: this.#options.capacity });
+    this.configFlow = new WebostvConfigFlow({}, this.#owner);
   }
 
-  public destroy(): Promise<void> {
-    if (this.#destroy) return this.#destroy;
-    this.#destroyed = true;
-    this.#destroy = Promise.all([...this.#runtimes].map((runtimeArg) => runtimeArg.destroy()).concat([...this.#pending].map((clientArg) => clientArg.destroy()))).then(() => undefined);
-    return this.#destroy;
+  public setup(configArg: IWebostvConfig, contextArg: INativeIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    const config = normalizeWebostvConfig(configArg);
+    return this.#owner.runSetup(contextArg, config.homeId, async (leaseArg) => {
+      const client = new WebostvClient(config, leaseArg.context, this.#options);
+      let cleanupStarted = false;
+      leaseArg.own(() => {
+        if (cleanupStarted) return client.retryCleanup();
+        cleanupStarted = true;
+        return client.destroy();
+      });
+      const snapshot = await client.getSnapshot();
+      leaseArg.promoteToRuntime();
+      return new WebostvRuntime(client, snapshot, () => leaseArg.close(), (promiseArg) => promiseArg === this.#destroy);
+    });
   }
+
+  public destroy(): Promise<void> { return this.#destroy ??= this.#owner.close(); }
+  public retryCleanup(): Promise<void> { return this.#owner.retryCleanup(); }
 }
 
 export class HomeAssistantWebostvIntegration extends WebostvIntegration {}
 
 class WebostvRuntime implements IIntegrationRuntime {
   public readonly domain = 'webostv';
-  constructor(private readonly client: WebostvClient, private readonly identity: IWebostvSnapshot, private readonly onDestroyed: () => void) {}
+  #destroy?: Promise<void>;
+  constructor(private readonly client: WebostvClient, private readonly identity: IWebostvSnapshot,
+    private readonly close: () => Promise<void>, private readonly isOwnerClose: (promiseArg: unknown) => boolean) {}
   public isHealthy(): boolean { return this.client.isHealthy(); }
   public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> { return WebostvMapper.toDevices(await this.client.getSnapshot(signalArg)); }
   public async entities(): Promise<IIntegrationEntity[]> { return WebostvMapper.toEntities(await this.client.getSnapshot()); }
   public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, signalArg?: AbortSignal): Promise<() => Promise<void>> {
+    const handler = handlerArg as (eventArg: IIntegrationEvent) => void | Promise<void>;
     return this.client.subscribe((eventArg) => {
       const base = { integrationDomain: this.domain, deviceId: WebostvMapper.deviceId(this.identity), timestamp: Date.now() };
-      if (eventArg.type === 'state') handlerArg({ ...base, type: 'state_changed', entityId: `${base.deviceId}:media_player`, data: { entity: WebostvMapper.toEntities(eventArg.snapshot)[0] } });
-      else if (eventArg.type === 'availability') handlerArg({ ...base, type: 'availability_changed', data: { available: eventArg.available } });
-      else handlerArg({ ...base, type: 'error', data: { message: eventArg.error.message } });
+      const result = eventArg.type === 'state'
+        ? handler({ ...base, type: 'state_changed', entityId: `${base.deviceId}:media_player`, data: { entity: WebostvMapper.toEntities(eventArg.snapshot)[0] } })
+        : eventArg.type === 'availability'
+          ? handler({ ...base, type: 'availability_changed', data: { available: eventArg.available } })
+          : handler({ ...base, type: 'error', data: { message: eventArg.error.message } });
+      return result === this.#destroy || this.isOwnerClose(result) ? undefined : result;
     }, signalArg);
   }
 
@@ -81,8 +88,7 @@ class WebostvRuntime implements IIntegrationRuntime {
       else if (service === 'volume_mute') { webostvKeys(data, ['mute']); argument = data.mute; }
       else if (service === 'select_source') { webostvKeys(data, ['inputId']); argument = data.inputId; }
       else webostvKeys(data, []);
-      await this.client.execute(service as TWebostvCommand, argument);
-      return { success: true, data: { acknowledgement: 'tv-response', state: 'observe-subscriptions' } };
+      return { success: true, data: await this.client.execute(service as TWebostvCommand, argument) };
     } catch (errorArg) { return { success: false, error: errorArg instanceof Error ? errorArg.message : 'webOS operation failed.' }; }
   }
 
@@ -92,11 +98,12 @@ class WebostvRuntime implements IIntegrationRuntime {
       const device = webostvObject(request.device, 'feature device');
       const feature = webostvObject(request.feature, 'feature');
       if (device.id !== WebostvMapper.deviceId(this.identity) || device.integrationDomain !== this.domain) throw new Error('webOS feature device is not owned by this runtime.');
-      if (feature.id === 'volume') await this.client.execute('volume_set', request.value, signalArg);
-      else if (feature.id === 'muted') await this.client.execute('volume_mute', request.value, signalArg);
+      let result;
+      if (feature.id === 'volume') result = await this.client.execute('volume_set', request.value, signalArg);
+      else if (feature.id === 'muted') result = await this.client.execute('volume_mute', request.value, signalArg);
       else throw new Error('webOS feature is not writable.');
-      return { success: true, data: { acknowledgement: 'tv-response', state: 'observe-subscriptions' } };
+      return { success: true, data: result };
     } catch (errorArg) { return { success: false, error: errorArg instanceof Error ? errorArg.message : 'webOS feature write failed.' }; }
   }
-  public async destroy(): Promise<void> { await this.client.destroy(); this.onDestroyed(); }
+  public destroy(): Promise<void> { return this.#destroy ??= this.close(); }
 }

package/ts/integrations/webostv/webostv.mapper.ts

@@ -13,15 +13,15 @@ export class WebostvMapper {
     ];
     return [{
       id: this.deviceId(snapshotArg), integrationDomain: 'webostv', name: snapshotArg.name,
-      protocol: 'http', manufacturer: 'LG', model: 'webOS TV', online: snapshotArg.connected,
+      protocol: 'http', manufacturer: 'LG', model: snapshotArg.model, online: snapshotArg.connected,
       features: [
         { id: 'power', capability: 'media', name: 'Power state', readable: true, writable: false },
-        { id: 'volume', capability: 'media', name: 'Volume', readable: true, writable: true, unit: '%' },
-        { id: 'muted', capability: 'media', name: 'Muted', readable: true, writable: true },
+        { id: 'volume', capability: 'media', name: 'Volume', readable: true, writable: snapshotArg.connected && snapshotArg.authorizedCommands.includes('volume_set'), unit: '%' },
+        { id: 'muted', capability: 'media', name: 'Muted', readable: true, writable: snapshotArg.connected && snapshotArg.authorizedCommands.includes('volume_mute') },
         { id: 'current_app', capability: 'media', name: 'Foreground application', readable: true, writable: false },
       ],
       state: states.map(([featureId, value]) => ({ featureId, value, updatedAt: snapshotArg.observedAt })),
-      metadata: { homeId: snapshotArg.homeId, deviceUUID: snapshotArg.deviceUUID, transport: 'ssap-websocket', inputs: structuredClone(snapshotArg.inputs) },
+      metadata: { homeId: snapshotArg.homeId, deviceUUID: snapshotArg.deviceUUID, transport: 'ssap-websocket', inputs: structuredClone(snapshotArg.inputs), authorizedCommands: [...snapshotArg.authorizedCommands], modelKnown: snapshotArg.model !== undefined },
     }];
   }
 

package/ts/integrations/webostv/webostv.types.ts

@@ -1,5 +1,6 @@
 import type * as plugins from '../../plugins.js';
 import type { IConfigEncryptionKeyProvider } from '../../core/classes.configstore.js';
+import type { INativeIntegrationOwnerOptions } from '../../core/classes.nativeintegrationowner.js';
 
 export const webostvDomain = 'webostv';
 export const webostvDefaultName = 'LG webOS TV';
@@ -19,9 +20,11 @@ export interface IWebostvConfig {
   maxPendingRequests?: number;
 }
 
-export interface IWebostvIntegrationOptions {
-  db: plugins.nosqldb.SmartdataDb;
-  keyProvider: IConfigEncryptionKeyProvider;
+export interface IWebostvIntegrationOptions extends INativeIntegrationOwnerOptions {
+  db?: plugins.nosqldb.SmartdataDb;
+  keyProvider?: IConfigEncryptionKeyProvider;
+  /** Runtime-only owner permission. An omitted or empty list authorizes no effects. */
+  allowedCommands?: readonly TWebostvCommand[];
 }
 
 export interface IHomeAssistantWebostvConfig extends IWebostvConfig {}
@@ -30,7 +33,10 @@ export interface IWebostvSnapshot {
   homeId: string;
   deviceUUID: string;
   name: string;
+  /** Actual system/getSystemInfo modelName, absent when the TV did not report one. */
+  model?: string;
   connected: boolean;
+  authorizedCommands: readonly TWebostvCommand[];
   powerState: string;
   volume: number;
   muted: boolean;
@@ -45,6 +51,15 @@ export type TWebostvClientEvent =
   | { type: 'error'; error: Error };
 export type TWebostvCommand = 'turn_on' | 'turn_off' | 'volume_set' | 'volume_up' | 'volume_down' | 'volume_mute' | 'select_source' | 'media_play' | 'media_pause' | 'media_stop';
 
+export interface IWebostvCommandResult {
+  acknowledgement: 'tv-response';
+  physicalCompletion: 'unverified';
+  observationStatus: 'observed' | 'unavailable';
+  observation?: IWebostvSnapshot;
+}
+
+export type TWebostvClientHandler = (eventArg: TWebostvClientEvent) => void | Promise<void>;
+
 export const webostvProfile = {
   domain: webostvDomain, displayName: webostvDefaultName, status: 'control-runtime',
   metadata: { source: 'home-assistant/core', upstreamDomain: webostvDomain, localApi: { implemented: ['verified SSAP registration', 'encrypted durable pairing keys', 'authoritative state subscriptions'], explicitUnsupported: ['fixture or injected-client production configs', 'deep standby wake-on-LAN', 'next/previous media track', 'automatic command replay'] } },

package/ts/integrations/webostv/webostv.validation.ts

@@ -1,4 +1,25 @@
-import type { IWebostvConfig } from './webostv.types.js';
+import type { IWebostvConfig, IWebostvIntegrationOptions, TWebostvCommand } from './webostv.types.js';
+
+export const webostvCommands: readonly TWebostvCommand[] = Object.freeze(['turn_on', 'turn_off', 'volume_set', 'volume_up', 'volume_down', 'volume_mute', 'select_source', 'media_play', 'media_pause', 'media_stop']);
+
+export const normalizeWebostvOptions = (valueArg: IWebostvIntegrationOptions = {}): Readonly<IWebostvIntegrationOptions> => {
+  const value = webostvObject(valueArg, 'webOS owner options');
+  webostvKeys(value, ['homeId', 'capacity', 'db', 'keyProvider', 'allowedCommands']);
+  if ((value.db === undefined) !== (value.keyProvider === undefined)) throw new TypeError('webOS persistence requires both database and keyProvider.');
+  const commands = value.allowedCommands ?? [];
+  if (!Array.isArray(commands) || commands.length > webostvCommands.length || Reflect.ownKeys(commands).some((keyArg) => {
+    const descriptor = Object.getOwnPropertyDescriptor(commands, keyArg);
+    return typeof keyArg !== 'string' || !descriptor || !('value' in descriptor) || (keyArg !== 'length' && !/^(0|[1-9][0-9]*)$/.test(keyArg));
+  })) throw new TypeError('webOS allowedCommands must be a finite data array.');
+  const captured: TWebostvCommand[] = [];
+  for (let index = 0; index < commands.length; index += 1) {
+    const command: unknown = Object.getOwnPropertyDescriptor(commands, String(index))?.value;
+    if (typeof command !== 'string' || !webostvCommands.includes(command as TWebostvCommand) || captured.includes(command as TWebostvCommand)) throw new TypeError('webOS allowedCommands contains an unsupported or duplicate command.');
+    captured.push(command as TWebostvCommand);
+  }
+  return Object.freeze({ homeId: value.homeId as string | undefined, capacity: value.capacity as number | undefined,
+    db: value.db as IWebostvIntegrationOptions['db'], keyProvider: value.keyProvider as IWebostvIntegrationOptions['keyProvider'], allowedCommands: Object.freeze(captured) });
+};
 
 export const webostvObject = (valueArg: unknown, nameArg: string): Record<string, unknown> => {
   if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg) || ![Object.prototype, null].includes(Object.getPrototypeOf(valueArg))) throw new TypeError(`${nameArg} must be a plain object.`);

package/ts/integrations/wiz/index.ts

@@ -4,3 +4,4 @@ export * from './wiz.classes.integration.js';
 export * from './wiz.discovery.js';
 export * from './wiz.mapper.js';
 export * from './wiz.types.js';
+export * from './wiz.validation.js';

package/ts/integrations/wiz/wiz.classes.client.ts

@@ -1,278 +1,108 @@
-import type {
-  IWizClientCommand,
-  IWizCommandResult,
-  IWizConfig,
-  IWizDeviceInfo,
-  IWizEvent,
-  IWizPilotPatch,
-  IWizPilotState,
-  IWizSnapshot,
-  IWizSnapshotDevice,
-  IWizUdpCommand,
-  IWizUdpResponse,
-} from './wiz.types.js';
-import { wizDefaultPort } from './wiz.types.js';
-import { WizMapper } from './wiz.mapper.js';
-
-type TWizEventHandler = (eventArg: IWizEvent) => void;
+import * as plugins from '../../plugins.js';
+import { NativeHomeAdmission } from '../../core/classes.nativehomeadmission.js';
+import type { IIntegrationSetupContext } from '../../core/types.js';
+import type { IWizConfig, IWizSnapshot, IWizWriteResult, TWizControl } from './wiz.types.js';
+import { normalizeWizConfig, wizControl } from './wiz.validation.js';
 
 export class WizClient {
-  private readonly events: IWizEvent[] = [];
-  private readonly eventHandlers = new Set<TWizEventHandler>();
-
-  constructor(private readonly config: IWizConfig) {}
-
-  public async getSnapshot(): Promise<IWizSnapshot> {
-    const host = this.host();
-    if (!host) {
-      return WizMapper.toSnapshot(this.config, false, this.events);
-    }
-
-    try {
-      const pilot = await this.getPilot();
-      const deviceInfo = await this.liveDeviceInfo(pilot).catch(() => this.staticDeviceInfo(pilot));
-      const device: IWizSnapshotDevice = {
-        host,
-        port: this.port(),
-        mac: pilot.mac || deviceInfo.mac || this.config.mac,
-        name: this.config.name || deviceInfo.name,
-        deviceInfo,
-        pilot,
-        available: true,
-      };
-      return WizMapper.toSnapshot({ ...this.config, snapshot: undefined, devices: [device], manualEntries: undefined }, true, this.events);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      this.emit({ type: 'error', data: { message }, timestamp: Date.now() });
-      return WizMapper.toSnapshot(this.config, false, this.events);
-    }
-  }
-
-  public onEvent(handlerArg: TWizEventHandler): () => void {
-    this.eventHandlers.add(handlerArg);
-    return () => this.eventHandlers.delete(handlerArg);
-  }
-
-  public async getPilot(): Promise<IWizPilotState> {
-    const response = await this.sendUdp<IWizPilotState>({ method: 'getPilot', params: {} });
-    const result = this.record(response.result) ? response.result as IWizPilotState : {};
-    this.emit({ type: 'pilot', data: result, timestamp: Date.now() });
-    return result;
-  }
-
-  public async setPilot(payloadArg: IWizPilotPatch): Promise<IWizUdpResponse<Record<string, unknown>>> {
-    return this.sendUdp<Record<string, unknown>>({ method: 'setPilot', params: payloadArg as Record<string, unknown> });
-  }
-
-  public async getSystemConfig(): Promise<IWizUdpResponse<Record<string, unknown>>> {
-    return this.sendUdp<Record<string, unknown>>({ method: 'getSystemConfig', params: {} });
-  }
-
-  public async sendCommand(commandArg: IWizClientCommand): Promise<IWizCommandResult> {
-    let result: IWizCommandResult;
-    if (this.config.commandExecutor) {
-      result = this.commandResult(await this.config.commandExecutor(commandArg), commandArg);
-    } else if (!this.host()) {
-      result = {
-        success: false,
-        error: this.unsupportedLiveControlMessage(),
-        data: { command: commandArg },
-      };
-    } else {
-      try {
-        const response = await this.setPilot(commandArg.payload);
-        result = { success: true, data: response.result || response };
-      } catch (error) {
-        result = {
-          success: false,
-          error: error instanceof Error ? error.message : String(error),
-          data: { command: commandArg },
-        };
-      }
-    }
-
-    this.emit({
-      type: result.success ? 'command_mapped' : 'command_failed',
-      command: commandArg,
-      data: result,
-      timestamp: Date.now(),
-      deviceId: commandArg.deviceId,
-      entityId: commandArg.entityId,
+  readonly #config: ReturnType<typeof normalizeWizConfig>;
+  readonly #protocol: plugins.ecobridgeDeviceManager.WizProtocol;
+  readonly #lifetime = new AbortController();
+  readonly #operations = new Set<Promise<unknown>>();
+  readonly #ownerSignal?: AbortSignal;
+  #healthy = false;
+  #closed = false;
+  #closing?: Promise<void>;
+  #retrying?: Promise<void>;
+
+  constructor(configArg: IWizConfig, contextArg: IIntegrationSetupContext) {
+    this.#config = normalizeWizConfig(configArg);
+    const context = new NativeHomeAdmission('wiz').admit(contextArg, this.#config.homeId);
+    const ownerSignalArg = context.abortSignal;
+    ownerSignalArg?.throwIfAborted();
+    this.#ownerSignal = ownerSignalArg;
+    this.#protocol = new plugins.ecobridgeDeviceManager.WizProtocol({
+      host: this.#config.host, port: this.#config.port, macAddress: this.#config.macAddress,
+      timeoutMs: this.#config.timeoutMs, maxPendingOperations: this.#config.maxPendingOperations, maxExchanges: this.#config.maxExchanges,
     });
-    return result;
   }
 
-  public async destroy(): Promise<void> {
-    this.eventHandlers.clear();
-  }
+  public get homeId(): string { return this.#config.homeId; }
+  public get pollIntervalMs(): number { return this.#config.pollIntervalMs; }
+  public isHealthy(): boolean { return this.#healthy && !this.#closed; }
 
-  private async liveDeviceInfo(pilotArg: IWizPilotState): Promise<IWizDeviceInfo> {
-    const systemConfig = await this.getSystemConfig();
-    const result = this.record(systemConfig.result) ? systemConfig.result : {};
-    return this.staticDeviceInfo(pilotArg, result);
-  }
-
-  private staticDeviceInfo(pilotArg?: IWizPilotState, systemArg: Record<string, unknown> = {}): IWizDeviceInfo {
-    const moduleName = this.stringValue(systemArg.moduleName) || this.config.deviceInfo?.moduleName;
-    const model = this.config.deviceInfo?.model || moduleName;
-    const isSocket = this.config.deviceInfo?.isSocket ?? this.textContainsSocket(model, moduleName, systemArg.typeId);
-    return {
-      ...this.config.deviceInfo,
-      host: this.host(),
-      port: this.port(),
-      mac: this.stringValue(systemArg.mac) || pilotArg?.mac || this.config.mac || this.config.deviceInfo?.mac,
-      name: this.config.name || this.config.deviceInfo?.name,
-      manufacturer: this.config.deviceInfo?.manufacturer || 'WiZ',
-      model,
-      moduleName,
-      fwVersion: this.stringValue(systemArg.fwVersion) || this.config.deviceInfo?.fwVersion,
-      typeId: this.stringValue(systemArg.typeId) || this.numberValue(systemArg.typeId) || this.config.deviceInfo?.typeId,
-      isSocket,
-      features: {
-        light: !isSocket,
-        switch: isSocket,
-        brightness: !isSocket || typeof pilotArg?.dimming === 'number',
-        color: ['r', 'g', 'b'].every((keyArg) => typeof pilotArg?.[keyArg] === 'number') || this.textContains(moduleName, 'rgb'),
-        colorTemp: typeof pilotArg?.temp === 'number' || this.textContains(moduleName, 'tw'),
-        effect: typeof pilotArg?.sceneId === 'number' || typeof pilotArg?.schdPsetId === 'number',
-        fan: typeof pilotArg?.fanState === 'number',
-        power: typeof pilotArg?.pc === 'number',
-        occupancy: pilotArg?.src === 'pir',
-        ...this.config.deviceInfo?.features,
-      },
-    };
+  public getSnapshot(signalArg?: AbortSignal): Promise<IWizSnapshot> {
+    return this.track(async () => {
+      const signal = this.signal(signalArg);
+      const info = await this.#protocol.getDeviceInfo({ signal });
+      signal.throwIfAborted();
+      this.#healthy = true;
+      return Object.freeze({ homeId: this.#config.homeId, host: this.#config.host, port: this.#config.port,
+        name: this.#config.name, info, observedAt: new Date().toISOString() });
+    });
   }
 
-  private async sendUdp<TResult>(commandArg: IWizUdpCommand): Promise<IWizUdpResponse<TResult>> {
-    const host = this.host();
-    if (!host) {
-      throw new Error(this.unsupportedLiveControlMessage());
-    }
-    const port = this.port();
-    const timeoutMs = this.timeoutMs();
-    const { createSocket } = await import('node:dgram');
-    const payload = Buffer.from(JSON.stringify(commandArg));
-
-    return new Promise<IWizUdpResponse<TResult>>((resolve, reject) => {
-      const socket = createSocket('udp4');
-      const timers: Array<ReturnType<typeof setTimeout>> = [];
-      let settled = false;
-
-      const cleanup = () => {
-        for (const timer of timers) {
-          clearTimeout(timer);
-        }
-        socket.removeAllListeners();
-        try {
-          socket.close();
-        } catch {
-          // The socket may already be closed after an early UDP error.
-        }
-      };
-
-      const finish = (errorArg: Error | undefined, responseArg?: IWizUdpResponse<TResult>) => {
-        if (settled) {
-          return;
-        }
-        settled = true;
-        cleanup();
-        if (errorArg) {
-          reject(errorArg);
-        } else {
-          resolve(responseArg || {});
-        }
-      };
-
-      const send = () => {
-        if (settled) {
-          return;
-        }
-        socket.send(payload, port, host, (errorArg) => {
-          if (errorArg) {
-            finish(errorArg);
-          }
-        });
-      };
-
-      socket.on('error', (errorArg) => finish(errorArg));
-      socket.on('message', (messageArg) => {
-        let response: IWizUdpResponse<TResult>;
-        try {
-          response = JSON.parse(messageArg.toString('utf8')) as IWizUdpResponse<TResult>;
-        } catch (error) {
-          finish(error instanceof Error ? error : new Error(String(error)));
-          return;
-        }
-        if (response.method && response.method !== commandArg.method) {
-          return;
-        }
-        if (response.error) {
-          finish(new Error(response.error.message || `WiZ UDP error ${response.error.code ?? 'unknown'}`));
-          return;
+  public write(controlArg: TWizControl, signalArg?: AbortSignal): Promise<IWizWriteResult> {
+    return this.track(async () => {
+      let control: TWizControl;
+      let signal: AbortSignal;
+      try { control = wizControl(controlArg); signal = this.signal(signalArg); }
+      catch { return Object.freeze({ outcome: 'not-sent', physicalStateConfirmed: false }); }
+      try {
+        const result = control.feature === 'power' ? await this.#protocol.setPower(control.value, { signal }) :
+          control.feature === 'brightness' ? await this.#protocol.setBrightness(control.value, { signal }) :
+            await this.#protocol.setRgb(control.value, { signal });
+        this.#healthy = true;
+        return Object.freeze({ outcome: result.outcome, physicalStateConfirmed: false, observedState: result.observedState });
+      } catch (errorArg) {
+        this.#healthy = false;
+        if (errorArg instanceof plugins.ecobridgeDeviceManager.WizProtocolError) {
+          return Object.freeze({ outcome: errorArg.effectOutcome, physicalStateConfirmed: false, errorCode: errorArg.code });
         }
-        this.emit({ type: 'udp_response', data: response, timestamp: Date.now() });
-        finish(undefined, response);
-      });
-
-      send();
-      timers.push(setTimeout(send, 750));
-      timers.push(setTimeout(send, 2250));
-      timers.push(setTimeout(() => finish(new Error(`Timed out waiting for WiZ ${commandArg.method} response from ${host}:${port}.`)), timeoutMs));
+        throw errorArg;
+      }
     });
   }
 
-  private emit(eventArg: IWizEvent): void {
-    this.events.push(eventArg);
-    for (const handler of this.eventHandlers) {
-      handler(eventArg);
+  public destroy(): Promise<void> {
+    if (!this.#closing) {
+      this.#closed = true;
+      this.#healthy = false;
+      this.#closing = Promise.resolve().then(() => this.cleanup());
+      this.#lifetime.abort(new Error('WiZ client is destroyed.'));
     }
+    return this.#closing;
   }
 
-  private commandResult(resultArg: unknown, commandArg: IWizClientCommand): IWizCommandResult {
-    if (this.isCommandResult(resultArg)) {
-      return resultArg;
+  /** Explicitly retries retained cleanup; no protocol operation is replayed. */
+  public retryCleanup(): Promise<void> {
+    if (!this.#closed) return Promise.reject(new Error('WiZ cleanup retry requires terminal shutdown.'));
+    if (!this.#retrying) {
+      this.#retrying = Promise.resolve().then(() => this.cleanup()).finally(() => { this.#retrying = undefined; });
     }
-    return { success: true, data: resultArg ?? { command: commandArg } };
-  }
-
-  private isCommandResult(valueArg: unknown): valueArg is IWizCommandResult {
-    return typeof valueArg === 'object' && valueArg !== null && 'success' in valueArg;
-  }
-
-  private host(): string | undefined {
-    return this.config.host || this.config.manualEntries?.find((entryArg) => entryArg.host)?.host;
-  }
-
-  private port(): number {
-    const manualPort = this.config.manualEntries?.find((entryArg) => entryArg.host)?.port;
-    return this.config.port || manualPort || wizDefaultPort;
-  }
-
-  private timeoutMs(): number {
-    return typeof this.config.timeoutMs === 'number' && this.config.timeoutMs > 0 ? this.config.timeoutMs : 5000;
-  }
-
-  private unsupportedLiveControlMessage(): string {
-    return 'WiZ live UDP control requires a configured host. Snapshot-only WiZ configs are read-only unless commandExecutor is provided.';
-  }
-
-  private textContainsSocket(...valuesArg: unknown[]): boolean {
-    return valuesArg.some((valueArg) => this.textContains(valueArg, 'socket') || this.textContains(valueArg, 'plug'));
-  }
-
-  private textContains(valueArg: unknown, fragmentArg: string): boolean {
-    return typeof valueArg === 'string' && valueArg.toLowerCase().includes(fragmentArg);
+    return this.#retrying;
   }
 
-  private stringValue(valueArg: unknown): string | undefined {
-    return typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
+  private async cleanup(): Promise<void> {
+    const results = await Promise.allSettled([
+      Promise.resolve().then(() => this.#protocol.close()),
+      Promise.allSettled([...this.#operations]),
+    ]);
+    const errors = results.flatMap((resultArg) => resultArg.status === 'rejected' ? [resultArg.reason] : []);
+    if (errors.length) throw new AggregateError(errors, 'WiZ client cleanup failed after draining admitted operations.');
   }
 
-  private numberValue(valueArg: unknown): number | undefined {
-    return typeof valueArg === 'number' && Number.isFinite(valueArg) ? valueArg : undefined;
+  private signal(signalArg?: AbortSignal): AbortSignal {
+    if (this.#closed) throw new Error('WiZ client is destroyed.');
+    const signal = AbortSignal.any([this.#lifetime.signal, ...(this.#ownerSignal ? [this.#ownerSignal] : []), ...(signalArg ? [signalArg] : [])]);
+    signal.throwIfAborted();
+    return signal;
   }
 
-  private record(valueArg: unknown): valueArg is Record<string, unknown> {
-    return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+  private track<T>(workArg: () => Promise<T>): Promise<T> {
+    const operation = workArg().catch((errorArg: unknown) => { this.#healthy = false; throw errorArg; });
+    this.#operations.add(operation);
+    void operation.then(() => this.#operations.delete(operation), () => this.#operations.delete(operation));
+    return operation;
   }
 }