@smarthome.exchange/integrations 1.0.0 → 2.0.0

package/ts/integrations/onkyo/readme.md

@@ -0,0 +1,126 @@
+# Selected native Onkyo integration
+
+`OnkyoIntegration` uses the published `OnkyoProtocol` from
+`@ecobridge.xyz/devicemanager@4.5.0` for one selected Onkyo receiver main zone over
+a persistent eISCP TCP connection. Device definitions use the canonical `tcp`
+protocol from `@smarthome.exchange/interfaces@2.1.0`.
+
+```typescript
+import { OnkyoIntegration } from '@smarthome.exchange/integrations';
+
+const integration = new OnkyoIntegration();
+const runtime = await integration.setup({
+  homeId: 'home-1',
+  host: '192.168.1.40',
+  macAddress: '0009B0D24B75',
+  model: 'TX-NR609',
+  allowUnencryptedLan: true,
+  volumeLimitRaw: 30,
+}, { homeId: 'home-1' });
+try {
+  const device = (await runtime.devices())[0];
+  const result = await runtime.callService!({
+    domain: 'onkyo', service: 'set_power',
+    target: { deviceId: device.id }, data: { power: true },
+  });
+  console.log(result);
+} finally {
+  await integration.destroy();
+}
+```
+
+The embedding host must select `context.homeId` independently of configuration,
+form values, discovery or store scope. Setup and config flow require that explicit
+selection; configuration must match it. Construction without options is inert.
+An optional constructor `{ homeId }` adds a consistency binding and still requires
+the explicit context. One instance binds synchronously to its first validated host
+home, including when later receiver setup fails. Flow and setup share that binding.
+This trusted host contract is not authentication by a home-id string.
+
+Configuration is captured plain data. It requires a matching `homeId`, one
+private/link-local/loopback unicast IPv4 `host`, twelve hexadecimal MAC digits,
+the exact selected `model`, `allowUnencryptedLan: true`, and an integer
+`volumeLimitRaw` from 0 through 100. Optional `port` defaults to 60128;
+`requestTimeoutMs` defaults to 5000 and accepts 1–60000; `maxPendingOperations`
+defaults to 16 and accepts 1–128. `name` is optional. Unknown keys, accessors,
+hidden properties, injected clients/executors/snapshots, hostname resolution,
+and configurable source/volume conversion maps are rejected.
+
+Setup checks live NRI identity and an enabled main zone. Every control checks
+fresh identity and capabilities through the public protocol. MAC/model binding
+selects the receiver; eISCP does not authenticate or encrypt the LAN peer.
+
+Device ids are `onkyo:<encoded homeId>:<uppercase MAC>` and the media entity id
+adds `:main`. Every service needs an exact owned device or entity target. If
+both target ids are supplied, both must match. Feature writes validate the
+owned home/device and a fresh canonical writable feature; caller-provided
+`writable` flags cannot grant capability.
+
+| Service | Exact data |
+| --- | --- |
+| `onkyo.status`, `onkyo.snapshot`, `onkyo.refresh` | Empty or absent data; live sequential inspection |
+| `onkyo.set_power` | `{ power: boolean }` |
+| `onkyo.set_mute`, `onkyo.volume_mute` | `{ muted: boolean }` |
+| `onkyo.set_volume_raw` | `{ volumeRaw: integer }` |
+| `onkyo.set_input`, `onkyo.select_source` | `{ inputId: '10' }`; advertised two-digit selector id |
+
+The same control services accept the `media_player` domain. Feature ids are
+`power`, `mute`, `volume_raw`, and `input`, when observed. Identity, connectivity,
+and advertised input lists are read-only. Unavailable reports produce absent
+state features. Power/mute need current boolean reports; input writes need
+current selector availability and enabled advertised main-zone choices.
+
+Volume values are absolute integer receiver wire units. Writes require an
+advertised `volstep="1"`, a positive `volmax` at most 100, and an observed raw
+level consistent with that contract. The configured ceiling and current
+advertised maximum both apply. Unknown/half-step contracts stay read-only.
+There is no normalized Home Assistant `volume_level`, percent conversion,
+guessed model scaling, increment, or toggle control.
+
+Success returns a matching receiver report after dispatch with
+`observation: 'matching-receiver-state'`, `commandAcknowledged: false`, and
+`causalityConfirmed: false`. eISCP has no request id; this report does not prove
+the command caused a physical change. Failures retain `effectOutcome` from the
+protocol: `not-sent` before dispatch or `indeterminate` after dispatch. A
+different report never counts as success. Controls are never retried or
+replayed. Inspection is sequential and `observedAt` records its completion.
+
+`subscribe()` emits observations from explicit inspection/control calls, plus
+operation errors. It opens no polling timer and provides no unsolicited push
+subscription. Subscriber cancellation unregisters its listener; runtime,
+integration, or caller lifetime cancellation joins active/queued operations
+and terminal protocol/socket cleanup. Shutdown is idempotent. A terminal
+protocol cannot reconnect; create a new authorized runtime explicitly.
+Integration shutdown collects cleanup failures, waits for every admitted resource,
+pending setup, config-flow submission and active client operation to settle, then
+reports the failures together in an `AggregateError`. Repeated shutdown returns
+the same terminal promise. Failed cleanup stays owned and consumes the shared
+capacity (16 by default; constructor `capacity` is a positive integer).
+`retryCleanup()` explicitly retries retained cleanup handles, never receiver effects.
+Closing is terminal and cannot select a different home or reopen an old form.
+
+Manual/custom discovery candidates must supply `integrationDomain: 'onkyo'`,
+selected host, MAC and model. The descriptor does no automatic network scan.
+`probeSelectedOnkyo({ host, port?, requestTimeoutMs?, signal? })` delegates one
+selected-unicast UDP query to the public protocol and returns a custom candidate
+with the advertised TCP port. Config flow fixes its endpoint and identity,
+captures the host home and lifetime before effects, collects acknowledgement and
+ceiling, then validates TCP readiness before completion. Home is not editable; a
+submitted conflicting home fails before opening a connection. Standalone
+`OnkyoConfigFlow` also requires explicit context home and supports `destroy()`.
+
+A supplied `configStore` must be an actual public `NoSqlConfigStore` with scope
+matching exactly this home and the `onkyo` domain. A store is optional for these
+protocol paths. The caller owns the public NoSQL store, database, and persistence
+lifetime. This integration does not create, close, read, write, or delete store
+data and does not persist receiver observations.
+
+Direct `OnkyoClient` construction likewise requires a separate native context as
+its second argument, such as `{ homeId: 'home-1' }`. Its snapshot home comes from
+that captured admission; an optional third signal carries an owning lease lifetime.
+
+Tests use bounded real TCP/UDP fixtures. No physical receiver or firmware has
+been certified. Other zones, media transport commands, HDMI routing, arbitrary
+raw commands, broadcast discovery, and cryptographic LAN authentication are
+outside the supported contract. `HomeAssistantOnkyoIntegration` remains a class
+alias with the same native semantics.

package/ts/integrations/panasonic_viera/panasonic_viera.classes.client.ts

@@ -1,426 +1,129 @@
 import * as plugins from '../../plugins.js';
-import { SimpleLocalClient, type ISimpleLocalSnapshot, type IServiceCallRequest, type IServiceCallResult } from '../../core/index.js';
-import { PanasonicVieraMapper } from './panasonic_viera.mapper.js';
-import type { IPanasonicVieraConfig, IPanasonicVieraRawApiData } from './panasonic_viera.types.js';
-import { panasonicVieraDefaultPort, panasonicVieraDefaultTimeoutMs, panasonicVieraProfile } from './panasonic_viera.types.js';
-
-interface IPanasonicVieraSession {
-  key: Buffer;
-  iv: Buffer;
-  hmacKey: Buffer;
-  id?: string;
-  sequenceNumber?: number;
-}
-
-export class PanasonicVieraClient extends SimpleLocalClient<IPanasonicVieraConfig> {
-  private cachedSnapshot?: ISimpleLocalSnapshot;
-  private encryptedSession?: IPanasonicVieraSession;
+import { NativeHomeAdmission } from '../../core/classes.nativehomeadmission.js';
+import type { IPanasonicVieraClientOptions, IPanasonicVieraConfig, IPanasonicVieraSnapshot, TPanasonicVieraKey, TPanasonicVieraKeyReceipt } from './panasonic_viera.types.js';
+import { drainPanasonicVieraCleanup, normalizePanasonicVieraConfig, panasonicVieraRecord } from './panasonic_viera.validation.js';
+
+export class PanasonicVieraClient {
+  private readonly config: Readonly<IPanasonicVieraConfig>;
+  private readonly protocol: plugins.ecobridgeDeviceManager.PanasonicProtocol;
+  private readonly lifetime = new AbortController();
+  private readonly operations = new Set<Promise<unknown>>();
+  private readonly ownerSignal?: AbortSignal;
+  private readonly onDestroyed?: () => void;
+  private state: 'new' | 'starting' | 'ready' | 'closed' = 'new';
+  private closePromise?: Promise<void>;
+  private retryPromise?: Promise<void>;
+  private cleanupComplete = false;
+  private readonly onOwnerAbort = (): void => {
+    // An event listener cannot return the close result. Retain it for destroy(), while observing its rejection.
+    void this.destroy().catch(() => undefined);
+  };
 
-  constructor(private readonly clientConfig: IPanasonicVieraConfig) {
-    super(panasonicVieraProfile, clientConfig);
+  public constructor(configArg: IPanasonicVieraConfig, optionsArg: IPanasonicVieraClientOptions) {
+    this.config = normalizePanasonicVieraConfig(configArg);
+    const options = panasonicVieraRecord(optionsArg, ['homeId', 'configStore', 'logger', 'abortSignal', 'onDestroyed']);
+    if (options.onDestroyed !== undefined && typeof options.onDestroyed !== 'function') {
+      throw new TypeError('Panasonic Viera client lifetime options are invalid.');
+    }
+    const { onDestroyed: _onDestroyed, ...contextOptions } = options;
+    const context = new NativeHomeAdmission('panasonic_viera').admit(contextOptions, this.config.homeId);
+    this.protocol = new plugins.ecobridgeDeviceManager.PanasonicProtocol({
+      address: this.config.host, descriptionUrl: this.config.descriptionUrl,
+      expectedUdn: this.config.expectedUdn, expectedModelName: this.config.expectedModelName,
+      timeoutMs: this.config.timeoutMs, maxResponseBytes: this.config.maxResponseBytes,
+    });
+    this.ownerSignal = context.abortSignal;
+    this.onDestroyed = optionsArg.onDestroyed;
+    if (this.ownerSignal?.aborted) this.onOwnerAbort();
+    else this.ownerSignal?.addEventListener('abort', this.onOwnerAbort, { once: true });
   }
 
-  public async getSnapshot(forceRefreshArg = false): Promise<ISimpleLocalSnapshot> {
-    if (!forceRefreshArg && this.cachedSnapshot) {
-      return clone(this.cachedSnapshot);
-    }
-
-    if (!forceRefreshArg && this.clientConfig.snapshot) {
-      this.cachedSnapshot = PanasonicVieraMapper.toSnapshot({ config: this.clientConfig, source: 'snapshot', online: this.clientConfig.snapshot.online });
-      return clone(this.cachedSnapshot);
-    }
+  public get isClosed(): boolean { return this.state === 'closed'; }
+  public get isHealthy(): boolean { return this.state === 'ready' && this.protocol.isStarted; }
 
-    if (this.endpoint()) {
+  public start(abortSignalArg?: AbortSignal): Promise<IPanasonicVieraSnapshot> {
+    this.assertOpen();
+    if (this.state !== 'new') return Promise.reject(new Error('Panasonic Viera startup is single-use.'));
+    this.state = 'starting';
+    return this.track(async () => {
       try {
-        const rawData = await this.fetchRawData();
-        this.cachedSnapshot = PanasonicVieraMapper.toSnapshot({ config: this.clientConfig, rawData, online: true, source: 'http' });
+        const profile = await this.protocol.start({ signal: this.operationSignal(abortSignalArg) });
+        this.assertOpen();
+        this.state = 'ready';
+        return this.snapshot(profile);
       } catch (errorArg) {
-        this.cachedSnapshot = this.createOfflineSnapshot(errorMessage(errorArg));
-      }
-      return clone(this.cachedSnapshot);
-    }
-
-    this.cachedSnapshot = await super.getSnapshot(forceRefreshArg);
-    return clone(this.cachedSnapshot);
-  }
-
-  public async refresh(): Promise<IServiceCallResult> {
-    this.cachedSnapshot = undefined;
-    const snapshot = await this.getSnapshot(Boolean(this.endpoint()));
-    const success = snapshot.online && !snapshot.error;
-    return { success, error: success ? undefined : snapshot.error || 'Panasonic Viera refresh requires a live SOAP endpoint, injected client, snapshotProvider, snapshot, entities, or rawData.', data: snapshot };
-  }
-
-  public async execute(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (this.clientConfig.client?.execute || this.clientConfig.commandExecutor) {
-      return super.execute(requestArg);
-    }
-
-    if (!this.endpoint()) {
-      return super.execute(requestArg);
-    }
-
-    try {
-      const data = requestArg.data || {};
-      if (requestArg.service === 'volume_set' || requestArg.service === 'set_volume') {
-        const volume = numberValue(data.volume_level ?? data.volumeLevel ?? data.volume);
-        if (volume === undefined) {
-          throw new Error('Panasonic Viera volume_set requires data.volume_level or data.volume.');
-        }
-        await this.setVolume(volume <= 1 ? Math.round(volume * 100) : Math.round(volume));
-        this.cachedSnapshot = undefined;
-        return { success: true, data: { volume } };
-      }
-
-      if (requestArg.service === 'volume_mute' || requestArg.service === 'set_mute') {
-        const mute = booleanValue(data.is_volume_muted ?? data.mute ?? data.muted);
-        if (mute === undefined) {
-          await this.sendKey('NRC_MUTE-ONOFF');
-          this.cachedSnapshot = undefined;
-          return { success: true, data: { key: 'NRC_MUTE-ONOFF' } };
-        }
-        await this.setMute(mute);
-        this.cachedSnapshot = undefined;
-        return { success: true, data: { muted: mute } };
+        // Close the protocol here; destroy drains this wrapper after the rejection settles.
+        this.state = 'closed';
+        this.ownerSignal?.removeEventListener('abort', this.onOwnerAbort);
+        this.lifetime.abort(errorArg);
+        try { await this.protocol.close(); }
+        catch (cleanupErrorArg) { throw new AggregateError([errorArg, cleanupErrorArg], 'Panasonic Viera admission and cleanup failed.'); }
+        throw errorArg;
       }
-
-      const key = keyForService(requestArg.service, data);
-      if (!key) {
-        return { success: false, error: `Unsupported Panasonic Viera service: ${requestArg.service}` };
-      }
-      await this.sendKey(key);
-      this.cachedSnapshot = undefined;
-      return { success: true, data: { key } };
-    } catch (errorArg) {
-      return { success: false, error: errorMessage(errorArg) };
-    }
-  }
-
-  public async destroy(): Promise<void> {
-    await this.clientConfig.client?.destroy?.();
-  }
-
-  private async fetchRawData(): Promise<IPanasonicVieraRawApiData> {
-    const deviceInfoXml = await this.requestText('/nrc/ddd.xml');
-    const deviceInfo = parseDeviceInfo(deviceInfoXml);
-    const rawData: IPanasonicVieraRawApiData = {
-      deviceInfo,
-      fetchedAt: new Date().toISOString(),
-    };
-
-    try {
-      rawData.volume = await this.getVolume();
-    } catch (errorArg) {
-      rawData.volumeError = errorMessage(errorArg);
-    }
-
-    try {
-      rawData.muted = await this.getMute();
-    } catch (errorArg) {
-      rawData.muteError = errorMessage(errorArg);
-    }
-
-    return rawData;
-  }
-
-  private async getVolume(): Promise<number> {
-    const text = await this.soapRequest('/dmr/control_0', 'schemas-upnp-org:service:RenderingControl:1', 'GetVolume', '<InstanceID>0</InstanceID><Channel>Master</Channel>');
-    const volume = numberValue(extractXmlValue(text, 'CurrentVolume'));
-    if (volume === undefined) {
-      throw new Error('Panasonic Viera GetVolume response did not include CurrentVolume.');
-    }
-    return volume;
-  }
-
-  private async setVolume(volumeArg: number): Promise<void> {
-    if (volumeArg < 0 || volumeArg > 100) {
-      throw new Error('Panasonic Viera volume must be between 0 and 100.');
-    }
-    await this.soapRequest('/dmr/control_0', 'schemas-upnp-org:service:RenderingControl:1', 'SetVolume', `<InstanceID>0</InstanceID><Channel>Master</Channel><DesiredVolume>${volumeArg}</DesiredVolume>`);
-  }
-
-  private async getMute(): Promise<boolean> {
-    const text = await this.soapRequest('/dmr/control_0', 'schemas-upnp-org:service:RenderingControl:1', 'GetMute', '<InstanceID>0</InstanceID><Channel>Master</Channel>');
-    return extractXmlValue(text, 'CurrentMute') !== '0';
-  }
-
-  private async setMute(muteArg: boolean): Promise<void> {
-    await this.soapRequest('/dmr/control_0', 'schemas-upnp-org:service:RenderingControl:1', 'SetMute', `<InstanceID>0</InstanceID><Channel>Master</Channel><DesiredMute>${muteArg ? '1' : '0'}</DesiredMute>`);
-  }
-
-  private async sendKey(keyArg: string): Promise<void> {
-    await this.soapRequest('/nrc/control_0', 'panasonic-com:service:p00NetworkControl:1', 'X_SendKey', `<X_KeyEvent>${escapeXml(keyArg)}</X_KeyEvent>`);
-  }
-
-  private async soapRequest(pathArg: string, urnArg: string, actionArg: string, paramsArg: string, bodyElementArg = 'm'): Promise<string> {
-    let action = actionArg;
-    let params = paramsArg;
-    let bodyElement = bodyElementArg;
-    let encrypted = false;
-
-    if (this.shouldEncrypt(urnArg, actionArg)) {
-      const session = await this.ensureEncryptedSession();
-      session.sequenceNumber = (session.sequenceNumber || 1) + 1;
-      const originalCommand = `<X_SessionId>${session.id}</X_SessionId><X_SequenceNumber>${String(session.sequenceNumber).padStart(8, '0')}</X_SequenceNumber><X_OriginalCommand><u:${actionArg} xmlns:u="urn:${urnArg}">${paramsArg}</u:${actionArg}></X_OriginalCommand>`;
-      const encryptedCommand = this.encryptSoapPayload(originalCommand, session);
-      action = 'X_EncryptedCommand';
-      params = `<X_ApplicationId>${escapeXml(this.clientConfig.appId || '')}</X_ApplicationId><X_EncInfo>${encryptedCommand}</X_EncInfo>`;
-      bodyElement = 'u';
-      encrypted = true;
-    }
-
-    const body = `<?xml version="1.0" encoding="utf-8"?><s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><s:Body><${bodyElement}:${action} xmlns:${bodyElement}="urn:${urnArg}">${params}</${bodyElement}:${action}></s:Body></s:Envelope>`;
-    const text = await this.requestText(pathArg, {
-      method: 'POST',
-      body,
-      headers: {
-        'Content-Type': 'text/xml; charset=utf-8',
-        SOAPAction: `"urn:${urnArg}#${action}"`,
-      },
     });
-
-    if (!encrypted) {
-      return text;
-    }
-
-    const encResult = extractXmlValue(text, 'X_EncResult');
-    if (!encResult) {
-      throw new Error('Panasonic Viera encrypted SOAP response did not include X_EncResult.');
-    }
-    return this.decryptSoapPayload(encResult, await this.ensureEncryptedSession());
-  }
-
-  private shouldEncrypt(urnArg: string, actionArg: string): boolean {
-    return urnArg === 'panasonic-com:service:p00NetworkControl:1'
-      && !['X_GetEncryptSessionId', 'X_DisplayPinCode', 'X_RequestAuth'].includes(actionArg)
-      && Boolean(this.clientConfig.appId && this.clientConfig.encryptionKey);
-  }
-
-  private async ensureEncryptedSession(): Promise<IPanasonicVieraSession> {
-    if (!this.clientConfig.appId || !this.clientConfig.encryptionKey) {
-      throw new Error('Panasonic Viera encrypted commands require config.appId and config.encryptionKey.');
-    }
-    if (!this.encryptedSession) {
-      this.encryptedSession = deriveSession(this.clientConfig.encryptionKey);
-    }
-    if (this.encryptedSession.id) {
-      return this.encryptedSession;
-    }
-
-    const encInfo = this.encryptSoapPayload(`<X_ApplicationId>${escapeXml(this.clientConfig.appId)}</X_ApplicationId>`, this.encryptedSession);
-    const text = await this.soapRequest('/nrc/control_0', 'panasonic-com:service:p00NetworkControl:1', 'X_GetEncryptSessionId', `<X_ApplicationId>${escapeXml(this.clientConfig.appId)}</X_ApplicationId><X_EncInfo>${encInfo}</X_EncInfo>`, 'u');
-    const encResult = extractXmlValue(text, 'X_EncResult');
-    if (!encResult) {
-      throw new Error('Panasonic Viera session response did not include X_EncResult.');
-    }
-    const decrypted = this.decryptSoapPayload(encResult, this.encryptedSession);
-    const sessionId = extractXmlValue(decrypted, 'X_SessionId');
-    if (!sessionId) {
-      throw new Error('Panasonic Viera encrypted session response did not include X_SessionId.');
-    }
-    this.encryptedSession.id = sessionId;
-    this.encryptedSession.sequenceNumber = 1;
-    return this.encryptedSession;
   }
 
-  private encryptSoapPayload(dataArg: string, sessionArg: IPanasonicVieraSession): string {
-    const header = Buffer.concat([plugins.crypto.randomBytes(12), uint32be(Buffer.byteLength(dataArg, 'latin1'))]);
-    const payload = Buffer.concat([header, Buffer.from(dataArg, 'latin1')]);
-    const padLength = (16 - (payload.length % 16)) % 16;
-    const paddedPayload = padLength ? Buffer.concat([payload, Buffer.alloc(padLength)]) : payload;
-    const cipher = plugins.crypto.createCipheriv('aes-128-cbc', sessionArg.key, sessionArg.iv);
-    cipher.setAutoPadding(false);
-    const ciphertext = Buffer.concat([cipher.update(paddedPayload), cipher.final()]);
-    const signature = plugins.crypto.createHmac('sha256', sessionArg.hmacKey).update(ciphertext).digest();
-    return Buffer.concat([ciphertext, signature]).toString('base64');
+  public getSnapshot(abortSignalArg?: AbortSignal): Promise<IPanasonicVieraSnapshot> {
+    this.assertOpen();
+    if (this.state === 'new') return this.start(abortSignalArg);
+    if (this.state !== 'ready') return Promise.reject(new Error('Panasonic Viera startup is in progress.'));
+    return this.track(async () => this.snapshot(await this.protocol.readProfile({ signal: this.operationSignal(abortSignalArg) })));
   }
 
-  private decryptSoapPayload(dataArg: string, sessionArg: IPanasonicVieraSession): string {
-    const encrypted = Buffer.from(dataArg, 'base64');
-    const decipher = plugins.crypto.createDecipheriv('aes-128-cbc', sessionArg.key, sessionArg.iv);
-    decipher.setAutoPadding(false);
-    const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]).toString('latin1');
-    return decrypted.slice(16).split('\0')[0];
+  public sendKey(keyArg: TPanasonicVieraKey, abortSignalArg?: AbortSignal): Promise<TPanasonicVieraKeyReceipt> {
+    this.assertOpen();
+    if (this.state !== 'ready') return Promise.reject(new Error('Panasonic Viera has not completed live admission.'));
+    return this.track(() => this.protocol.sendKey(keyArg, { signal: this.operationSignal(abortSignalArg) }));
   }
 
-  private async requestText(pathArg: string, optionsArg: { method?: 'GET' | 'POST'; body?: string; headers?: Record<string, string> } = {}): Promise<string> {
-    const endpoint = this.requireEndpoint();
-    const url = new URL(pathArg.replace(/^\/+/, ''), `${endpoint.origin}/`);
-    const timeoutMs = this.clientConfig.timeoutMs || panasonicVieraDefaultTimeoutMs;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-      const response = await globalThis.fetch(url, {
-        method: optionsArg.method || 'GET',
-        headers: { Accept: 'text/xml, application/xml;q=0.9, */*;q=0.8', ...(optionsArg.headers || {}) },
-        body: optionsArg.body,
-        signal: controller.signal,
-      });
-      const text = await response.text();
-      if (!response.ok) {
-        throw new Error(`Panasonic Viera request ${url.pathname} failed with ${response.status}: ${extractXmlValue(text, 'errorDescription') || text.slice(0, 160)}`);
-      }
-      return text;
-    } finally {
-      clearTimeout(timer);
+  public destroy(): Promise<void> {
+    if (!this.closePromise) {
+      this.state = 'closed';
+      this.ownerSignal?.removeEventListener('abort', this.onOwnerAbort);
+      const operations = [...this.operations];
+      this.closePromise = Promise.resolve().then(() => drainPanasonicVieraCleanup([this.protocol.close()], operations,
+        'Panasonic Viera client cleanup failed.')).then(() => { this.onDestroyed?.(); this.cleanupComplete = true; });
+      this.lifetime.abort(new Error('Panasonic Viera client is closed.'));
     }
+    return this.closePromise;
   }
 
-  private requireEndpoint(): URL {
-    const endpoint = this.endpoint();
-    if (!endpoint) {
-      throw new Error('Panasonic Viera local SOAP API requires config.host or config.url.');
+  /** Explicit cleanup retry only. The original destroy rejection remains observable; transport work is never replayed. */
+  public retryCleanup(): Promise<void> {
+    if (!this.closePromise) return Promise.reject(new Error('Panasonic Viera cleanup must first be closed.'));
+    if (this.cleanupComplete) return Promise.resolve();
+    if (!this.retryPromise) {
+      const closed = this.closePromise;
+      this.retryPromise = Promise.resolve().then(async () => {
+        await closed.catch(() => undefined);
+        await drainPanasonicVieraCleanup([this.protocol.close()], [...this.operations], 'Panasonic Viera explicit cleanup retry failed.');
+        this.onDestroyed?.();
+        this.cleanupComplete = true;
+      });
+      const settled = (): void => { this.retryPromise = undefined; };
+      void this.retryPromise.then(settled, settled);
     }
-    return endpoint;
+    return this.retryPromise;
   }
 
-  private endpoint(): URL | undefined {
-    const configuredUrl = stringValue(this.clientConfig.url);
-    if (configuredUrl) {
-      return normalizeBaseUrl(configuredUrl, this.clientConfig.port, this.clientConfig.useTls);
-    }
-    const host = stringValue(this.clientConfig.host);
-    if (!host) {
-      return undefined;
-    }
-    return normalizeBaseUrl(host, this.clientConfig.port || panasonicVieraDefaultPort, this.clientConfig.useTls);
+  private snapshot(profileArg: plugins.ecobridgeDeviceManager.IPanasonicProfile): IPanasonicVieraSnapshot {
+    this.assertOpen();
+    return Object.freeze({ homeId: this.config.homeId, name: this.config.name ?? profileArg.identity.name, profile: profileArg });
   }
 
-  private createOfflineSnapshot(errorArg: string): ISimpleLocalSnapshot {
-    return PanasonicVieraMapper.toSnapshot({ config: this.clientConfig, online: false, source: 'runtime', error: errorArg });
+  private operationSignal(signalArg?: AbortSignal): AbortSignal {
+    if (signalArg !== undefined && !(signalArg instanceof AbortSignal)) throw new TypeError('Panasonic Viera cancellation must be an AbortSignal.');
+    return signalArg ? AbortSignal.any([this.lifetime.signal, signalArg]) : this.lifetime.signal;
   }
-}
-
-const keyMap: Record<string, string> = {
-  media_play: 'NRC_PLAY-ONOFF',
-  media_pause: 'NRC_PAUSE-ONOFF',
-  media_stop: 'NRC_STOP-ONOFF',
-  media_next_track: 'NRC_FF-ONOFF',
-  media_previous_track: 'NRC_REW-ONOFF',
-  volume_up: 'NRC_VOLUP-ONOFF',
-  volume_down: 'NRC_VOLDOWN-ONOFF',
-  turn_on: 'NRC_POWER-ONOFF',
-  turn_off: 'NRC_POWER-ONOFF',
-  toggle: 'NRC_POWER-ONOFF',
-};
 
-const keyForService = (serviceArg: string, dataArg: Record<string, unknown>): string | undefined => {
-  const explicit = stringValue(dataArg.command) || stringValue(dataArg.key) || stringValue(dataArg.button);
-  if (serviceArg === 'press' && explicit) {
-    return normalizeKey(explicit);
+  private assertOpen(): void {
+    if (this.isClosed) throw new Error('Panasonic Viera client is closed.');
   }
-  return keyMap[serviceArg];
-};
 
-const normalizeKey = (valueArg: string): string => {
-  if (valueArg.startsWith('NRC_')) {
-    return valueArg;
+  private track<TResult>(executeArg: () => Promise<TResult>): Promise<TResult> {
+    if (this.operations.size !== 0) return Promise.reject(new Error('Panasonic Viera has an active operation.'));
+    const operation = Promise.resolve().then(executeArg).finally(() => this.operations.delete(operation));
+    this.operations.add(operation);
+    return operation;
   }
-  const normalized = valueArg.toUpperCase().replace(/[^A-Z0-9]+/g, '_');
-  const aliases: Record<string, string> = {
-    PLAY: 'NRC_PLAY-ONOFF',
-    PAUSE: 'NRC_PAUSE-ONOFF',
-    STOP: 'NRC_STOP-ONOFF',
-    POWER: 'NRC_POWER-ONOFF',
-    VOLUME_UP: 'NRC_VOLUP-ONOFF',
-    VOLUME_DOWN: 'NRC_VOLDOWN-ONOFF',
-    MUTE: 'NRC_MUTE-ONOFF',
-    ENTER: 'NRC_ENTER-ONOFF',
-    UP: 'NRC_UP-ONOFF',
-    DOWN: 'NRC_DOWN-ONOFF',
-    LEFT: 'NRC_LEFT-ONOFF',
-    RIGHT: 'NRC_RIGHT-ONOFF',
-    HOME: 'NRC_HOME-ONOFF',
-    MENU: 'NRC_MENU-ONOFF',
-    BACK: 'NRC_RETURN-ONOFF',
-  };
-  return aliases[normalized] || `NRC_${normalized}-ONOFF`;
-};
-
-const deriveSession = (encryptionKeyArg: string): IPanasonicVieraSession => {
-  const iv = Buffer.from(encryptionKeyArg, 'base64').subarray(0, 16);
-  if (iv.length !== 16) {
-    throw new Error('Panasonic Viera encryptionKey must decode to a 16 byte AES IV.');
-  }
-  const key = Buffer.alloc(16);
-  for (let index = 0; index < 16; index += 4) {
-    key[index] = iv[index + 2];
-    key[index + 1] = iv[index + 3];
-    key[index + 2] = iv[index];
-    key[index + 3] = iv[index + 1];
-  }
-  return { key, iv, hmacKey: Buffer.concat([iv, iv]) };
-};
-
-const uint32be = (valueArg: number): Buffer => {
-  const buffer = Buffer.alloc(4);
-  buffer.writeUInt32BE(valueArg, 0);
-  return buffer;
-};
-
-const parseDeviceInfo = (xmlArg: string): Record<string, unknown> => ({
-  UDN: extractXmlValue(xmlArg, 'UDN'),
-  friendlyName: extractXmlValue(xmlArg, 'friendlyName'),
-  manufacturer: extractXmlValue(xmlArg, 'manufacturer'),
-  modelName: extractXmlValue(xmlArg, 'modelName'),
-  modelNumber: extractXmlValue(xmlArg, 'modelNumber'),
-});
-
-const extractXmlValue = (xmlArg: string, tagArg: string): string | undefined => {
-  const pattern = new RegExp(`<(?:\\w+:)?${tagArg}[^>]*>([\\s\\S]*?)</(?:\\w+:)?${tagArg}>`, 'i');
-  const match = pattern.exec(xmlArg);
-  return match?.[1]?.trim();
-};
-
-const escapeXml = (valueArg: string): string => valueArg.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
-
-const normalizeBaseUrl = (valueArg: string, portArg: number | undefined, useTlsArg?: boolean): URL | undefined => {
-  try {
-    const parsed = new URL(valueArg.includes('://') ? valueArg : `${useTlsArg ? 'https' : 'http'}://${valueArg}`);
-    if (portArg) {
-      parsed.port = String(portArg);
-    }
-    parsed.pathname = '';
-    parsed.search = '';
-    parsed.hash = '';
-    return parsed;
-  } catch {
-    return undefined;
-  }
-};
-
-const stringValue = (valueArg: unknown): string | undefined => {
-  return typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
-};
-
-const numberValue = (valueArg: unknown): number | undefined => {
-  if (typeof valueArg === 'number' && Number.isFinite(valueArg)) {
-    return valueArg;
-  }
-  if (typeof valueArg === 'string' && valueArg.trim() && Number.isFinite(Number(valueArg))) {
-    return Number(valueArg);
-  }
-  return undefined;
-};
-
-const booleanValue = (valueArg: unknown): boolean | undefined => {
-  if (typeof valueArg === 'boolean') {
-    return valueArg;
-  }
-  if (typeof valueArg === 'number') {
-    return valueArg !== 0;
-  }
-  if (typeof valueArg === 'string') {
-    if (valueArg === '1' || valueArg.toLowerCase() === 'true') {
-      return true;
-    }
-    if (valueArg === '0' || valueArg.toLowerCase() === 'false') {
-      return false;
-    }
-  }
-  return undefined;
-};
-
-const clone = <TValue>(valueArg: TValue): TValue => JSON.parse(JSON.stringify(valueArg)) as TValue;
-
-const errorMessage = (errorArg: unknown): string => errorArg instanceof Error ? errorArg.message : String(errorArg);
+}