homebridge 2.0.0-beta.35 → 2.0.0-beta.37

package/dist/matter/{matterServer.js → server.js}

@@ -1,12 +1,7 @@
-/**
- * Matter.js Server Implementation for Homebridge Plugin API
- *
- * This provides a Matter bridge that plugins can use to register
- * Matter accessories via the Homebridge API.
- */
+/* global NodeJS */
 import { randomBytes } from 'node:crypto';
 import { EventEmitter } from 'node:events';
-import { constants, existsSync } from 'node:fs';
+import { constants, existsSync, watch as fsWatch, writeFileSync } from 'node:fs';
 import { access, writeFile } from 'node:fs/promises';
 import { homedir, release } from 'node:os';
 import { join, normalize, resolve } from 'node:path';
@@ -21,15 +16,15 @@ import fse from 'fs-extra';
 import QRCode from 'qrcode-terminal';
 import { Logger } from '../logger.js';
 import getVersion from '../version.js';
-import { MatterAccessoryCache } from './matterAccessoryCache.js';
-import { HomebridgeColorControlServer, HomebridgeDoorLockServer, HomebridgeFanControlServer, HomebridgeIdentifyServer, HomebridgeLevelControlServer, HomebridgeOnOffServer, HomebridgeRvcCleanModeServer, HomebridgeRvcOperationalStateServer, HomebridgeRvcRunModeServer, HomebridgeServiceAreaServer, HomebridgeThermostatServer, HomebridgeWindowCoveringServer, registerHandler, registerPartEndpoint, setAccessoriesMap, } from './matterBehaviors.js';
-import { sanitizeUniqueId, truncateString, validatePort } from './matterConfigValidator.js';
-import { errorHandler } from './matterErrorHandler.js';
-import { createHomebridgeLogFormatter } from './matterLogFormatter.js';
-import { networkMonitor } from './matterNetworkMonitor.js';
-import { applyWindowCoveringFeatures, CLUSTER_IDS, detectBehaviorFeatures, detectWindowCoveringFeatures, determineColorControlFeaturesFromHandlers, extractColorControlFeatures, extractThermostatFeatures, validateAccessoryRequiredFields, } from './matterServerHelpers.js';
-import { MatterStorageManager } from './matterStorage.js';
-import { deviceTypes, MatterDeviceError, } from './matterTypes.js';
+import { MatterAccessoryCache } from './accessoryCache.js';
+import { BehaviorRegistry, HomebridgeColorControlServer, HomebridgeDoorLockServer, HomebridgeFanControlServer, HomebridgeIdentifyServer, HomebridgeLevelControlServer, HomebridgeOnOffServer, HomebridgeRvcCleanModeServer, HomebridgeRvcOperationalStateServer, HomebridgeRvcRunModeServer, HomebridgeServiceAreaServer, HomebridgeThermostatServer, HomebridgeWindowCoveringServer, } from './behaviors/index.js';
+import { sanitizeUniqueId, truncateString, validatePort } from './configValidator.js';
+import { errorHandler } from './errorHandler.js';
+import { createHomebridgeLogFormatter } from './logFormatter.js';
+import { applyWindowCoveringFeatures, CLUSTER_IDS, detectBehaviorFeatures, detectWindowCoveringFeatures, determineColorControlFeaturesFromHandlers, extractColorControlFeatures, extractThermostatFeatures, validateAccessoryRequiredFields, } from './serverHelpers.js';
+import { MatterStorageManager } from './storage.js';
+import { isDeviceType, withBehaviors, withFeatures } from './typeHelpers.js';
+import { deviceTypes, MatterDeviceError, } from './types.js';
 const log = Logger.withPrefix('Matter/Server');
 /**
  * Constants for Matter server configuration
@@ -42,7 +37,7 @@ const SERVER_READY_TIMEOUT_MS = 5000;
 const SERVER_READY_POLL_INTERVAL_MS = 100;
 const SERVER_INIT_DELAY_MS = 200;
 const MAX_PASSCODE_ATTEMPTS = 100;
-const FABRIC_MONITOR_INTERVAL_MS = 2000; // check for fabric changes every 2 seconds
+const FABRIC_MONITOR_INTERVAL_MS = 60000; // check for fabric changes every minute
 /**
  * Matter Server for Homebridge Plugin API
  * Allows plugins to register Matter accessories explicitly
@@ -54,9 +49,31 @@ export class MatterServer extends EventEmitter {
     serverNode = null;
     aggregator = null;
     accessories = new Map();
+    behaviorRegistry;
     isRunning = false;
     MAX_DEVICES = MAX_DEVICES_PER_BRIDGE;
     shutdownHandler = null;
+    // Map cluster names to custom behavior classes
+    // Only clusters with user-triggered commands need custom behaviors
+    static CLUSTER_BEHAVIOR_MAP = {
+        // Core controls
+        onOff: HomebridgeOnOffServer,
+        levelControl: HomebridgeLevelControlServer,
+        colorControl: HomebridgeColorControlServer,
+        // Coverings & locks
+        windowCovering: HomebridgeWindowCoveringServer,
+        doorLock: HomebridgeDoorLockServer,
+        // Climate control
+        fanControl: HomebridgeFanControlServer,
+        thermostat: HomebridgeThermostatServer,
+        // Robotic vacuum cleaners
+        rvcOperationalState: HomebridgeRvcOperationalStateServer,
+        rvcRunMode: HomebridgeRvcRunModeServer,
+        rvcCleanMode: HomebridgeRvcCleanModeServer,
+        serviceArea: HomebridgeServiceAreaServer,
+        // Identification
+        identify: HomebridgeIdentifyServer,
+    };
     // Internal commissioning values (generated, not user-configurable)
     passcode = 0;
     discriminator = 0;
@@ -70,6 +87,7 @@ export class MatterServer extends EventEmitter {
     accessoryCache = null;
     // Fabric monitoring
     fabricMonitorInterval = null;
+    fabricCheckTimeout = null;
     previousFabrics = new Map();
     constructor(config) {
         super();
@@ -84,19 +102,34 @@ export class MatterServer extends EventEmitter {
         else {
             MatterLogger.level = MatterLogLevel.NOTICE;
         }
-        // Set custom log format to match homebridge format:
-        // [DD/MM/YYYY, HH:MM:SS] [Matter/Facility] message
+        // Set custom log format to match homebridge format
         MatterLogger.format = createHomebridgeLogFormatter();
         // Redirect all Matter.js logs to console.log to prevent console.debug() suppression.
         // Matter.js uses console.debug() for DEBUG level logs, which is silently ignored in many Node.js environments.
         MatterLogger.destinations.default.write = (text) => {
-            console.log(text); // eslint-disable-line no-console
+            // Skip empty strings to avoid blank lines (from suppressed log facilities)
+            if (text.trim() !== '') {
+                console.log(text); // eslint-disable-line no-console
+            }
         };
         // Initialize commissioning values (will be loaded from storage in start())
         this.vendorId = DEFAULT_VENDOR_ID;
         this.productId = DEFAULT_PRODUCT_ID;
-        // Provide accessories map reference to behaviors for cache syncing
-        setAccessoriesMap(this.accessories);
+        // Create behavior registry and set it on all behavior classes
+        this.behaviorRegistry = new BehaviorRegistry(this.accessories);
+        // Set the registry on all custom behavior classes
+        HomebridgeOnOffServer.setRegistry(this.behaviorRegistry);
+        HomebridgeLevelControlServer.setRegistry(this.behaviorRegistry);
+        HomebridgeColorControlServer.setRegistry(this.behaviorRegistry);
+        HomebridgeWindowCoveringServer.setRegistry(this.behaviorRegistry);
+        HomebridgeDoorLockServer.setRegistry(this.behaviorRegistry);
+        HomebridgeFanControlServer.setRegistry(this.behaviorRegistry);
+        HomebridgeThermostatServer.setRegistry(this.behaviorRegistry);
+        HomebridgeIdentifyServer.setRegistry(this.behaviorRegistry);
+        HomebridgeRvcOperationalStateServer.setRegistry(this.behaviorRegistry);
+        HomebridgeRvcRunModeServer.setRegistry(this.behaviorRegistry);
+        HomebridgeRvcCleanModeServer.setRegistry(this.behaviorRegistry);
+        HomebridgeServiceAreaServer.setRegistry(this.behaviorRegistry);
     }
     /**
      * Validate and sanitize Matter server configuration
@@ -239,7 +272,8 @@ export class MatterServer extends EventEmitter {
         const digitCounts = new Map();
         for (const digit of passcodeStr) {
             digitCounts.set(digit, (digitCounts.get(digit) || 0) + 1);
-            if (digitCounts.get(digit) > 3) {
+            const count = digitCounts.get(digit);
+            if (count !== undefined && count > 3) {
                 return false;
             }
         }
@@ -285,10 +319,12 @@ export class MatterServer extends EventEmitter {
         }
         catch (error) {
             // Check if this is a storage corruption error
-            const isStorageError = error?.message?.includes('Invalid public key encoding')
-                || error?.message?.includes('FabricManager unavailable')
-                || error?.message?.includes('key-input')
-                || error?.cause?.message?.includes('Invalid public key encoding');
+            const errorMessage = error instanceof Error ? error.message : '';
+            const causeMessage = error instanceof Error && error.cause instanceof Error ? error.cause.message : '';
+            const isStorageError = errorMessage.includes('Invalid public key encoding')
+                || errorMessage.includes('FabricManager unavailable')
+                || errorMessage.includes('key-input')
+                || causeMessage.includes('Invalid public key encoding');
             if (!isStorageError) {
                 // Not a storage error, rethrow
                 throw error;
@@ -306,18 +342,32 @@ export class MatterServer extends EventEmitter {
             const serverNodeStoreJsonFile = `${serverNodeStorePath}.json`;
             try {
                 let removedSomething = false;
-                // Delete the ServerNodeStore subdirectory
-                if (existsSync(serverNodeStorePath)) {
+                // Delete the ServerNodeStore subdirectory (async check and removal)
+                try {
+                    await fse.stat(serverNodeStorePath);
                     log.info(`Removing corrupted ServerNodeStore directory: ${serverNodeStorePath}`);
                     await fse.remove(serverNodeStorePath);
                     removedSomething = true;
                 }
+                catch (err) {
+                    const code = err instanceof Error && 'code' in err ? err.code : undefined;
+                    if (code !== 'ENOENT') {
+                        throw err;
+                    }
+                }
                 // Delete the ServerNodeStore JSON file (contains fabric data)
-                if (existsSync(serverNodeStoreJsonFile)) {
+                try {
+                    await fse.stat(serverNodeStoreJsonFile);
                     log.info(`Removing corrupted ServerNodeStore JSON file: ${serverNodeStoreJsonFile}`);
                     await fse.remove(serverNodeStoreJsonFile);
                     removedSomething = true;
                 }
+                catch (err) {
+                    const code = err instanceof Error && 'code' in err ? err.code : undefined;
+                    if (code !== 'ENOENT') {
+                        throw err;
+                    }
+                }
                 if (removedSomething) {
                     log.info('Corrupted storage removed, retrying ServerNode creation...');
                 }
@@ -353,9 +403,6 @@ export class MatterServer extends EventEmitter {
             // Load or generate commissioning credentials
             await this.loadOrGenerateCredentials();
             log.info(`Configuration: Port=${this.config.port}, Passcode=${this.passcode}, Discriminator=${this.discriminator}`);
-            // Start network monitoring
-            networkMonitor.startMonitoring();
-            this.cleanupHandlers.push(() => networkMonitor.stopMonitoring());
             // Configure network interfaces if specified in the config
             if (this.config.networkInterfaces && this.config.networkInterfaces.length > 0) {
                 const environment = Environment.default;
@@ -474,7 +521,17 @@ export class MatterServer extends EventEmitter {
     }
     /**
      * Run the server after devices have been added (for external accessory mode)
-     * This must be called after registerPlatformAccessories() when using externalAccessory mode
+     *
+     * This must be called after registerPlatformAccessories() when using externalAccessory mode.
+     * In bridge mode, the server starts automatically when accessories are registered.
+     *
+     * @throws {MatterDeviceError} If server node is not initialized or server is already running
+     * @example
+     * ```typescript
+     * await matterServer.start()
+     * await matterServer.registerPlatformAccessories('plugin', 'platform', accessories)
+     * await matterServer.runServer() // External accessory mode only
+     * ```
      */
     async runServer() {
         if (!this.serverNode) {
@@ -655,22 +712,23 @@ export class MatterServer extends EventEmitter {
             log.debug(`Saved commissioning info to ${commissioningFilePath}`);
         }
         catch (error) {
-            log.warn(`Failed to save commissioning info to disk: ${error.message}`);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            log.warn(`Failed to save commissioning info to disk: ${errorMessage}`);
         }
         // Display commissioning information
-        log.info(`\n${'='.repeat(60)}`);
+        log.info(`${'='.repeat(60)}`);
         log.info('📱 MATTER COMMISSIONING INFORMATION');
         log.info('='.repeat(60));
         log.info(`Manual Pairing Code: ${manualPairingCode}`);
         log.info(`Passcode: ${passcode}`);
         log.info(`Discriminator: ${discriminator}`);
-        log.info('\nQR Code for commissioning:');
+        log.info('QR Code for commissioning:');
         // Generate and display QR code in terminal
         QRCode.generate(qrCodePayload, { small: true }, (qrcode) => {
             // eslint-disable-next-line no-console
             console.log(qrcode);
         });
-        log.info(`${'='.repeat(60)}\n`);
+        log.info(`${'='.repeat(60)}`);
     }
     /**
      * Wait for the server to be ready
@@ -690,6 +748,7 @@ export class MatterServer extends EventEmitter {
     }
     /**
      * Start monitoring fabric changes to emit commissioning events
+     * Uses file watching instead of polling for better performance
      */
     startFabricMonitoring() {
         // Stop any existing monitor
@@ -700,22 +759,69 @@ export class MatterServer extends EventEmitter {
             this.previousFabrics.set(fabric.fabricIndex, fabric);
         }
         log.debug('Starting fabric monitoring for commissioning events');
-        // Set up periodic monitoring
-        this.fabricMonitorInterval = setInterval(() => {
-            this.checkFabricChanges();
-        }, FABRIC_MONITOR_INTERVAL_MS);
+        // Watch the storage file for fabric changes instead of polling
+        // This is much more efficient - only checks when the file actually changes
+        if (this.storageManager && this.matterStoragePath) {
+            const fabricStorageFile = join(this.matterStoragePath, `${this.config.uniqueId}.json`);
+            try {
+                // Ensure the storage file exists before watching it
+                // fs.watch will fail with ENOENT if the file doesn't exist
+                if (!existsSync(fabricStorageFile)) {
+                    log.debug(`Creating fabric storage file: ${fabricStorageFile}`);
+                    writeFileSync(fabricStorageFile, '{}', 'utf-8');
+                }
+                // Use fs.watch for efficient file monitoring
+                this.fabricMonitorInterval = fsWatch(fabricStorageFile, (eventType) => {
+                    if (eventType === 'change') {
+                        // Debounce rapid changes (file writes may trigger multiple events)
+                        if (this.fabricCheckTimeout) {
+                            clearTimeout(this.fabricCheckTimeout);
+                        }
+                        this.fabricCheckTimeout = setTimeout(() => {
+                            this.checkFabricChanges();
+                        }, 100); // 100ms debounce
+                    }
+                });
+                log.debug(`Watching fabric storage file for changes: ${fabricStorageFile}`);
+            }
+            catch (error) {
+                // Fall back to polling if file watching fails
+                log.warn('Failed to set up file watcher for fabric monitoring, falling back to polling:', error);
+                this.fabricMonitorInterval = setInterval(() => {
+                    this.checkFabricChanges();
+                }, FABRIC_MONITOR_INTERVAL_MS);
+            }
+        }
+        else {
+            // Fallback to polling if storage not available
+            this.fabricMonitorInterval = setInterval(() => {
+                this.checkFabricChanges();
+            }, FABRIC_MONITOR_INTERVAL_MS);
+        }
         // Add to clean up handlers
         this.cleanupHandlers.push(() => this.stopFabricMonitoring());
     }
     /**
-     * Stop fabric monitoring
+     * Stop fabric monitoring and clean up watchers/timers
      */
     stopFabricMonitoring() {
         if (this.fabricMonitorInterval) {
-            clearInterval(this.fabricMonitorInterval);
+            // Could be either a setInterval or a file watcher
+            if (typeof this.fabricMonitorInterval === 'object' && 'close' in this.fabricMonitorInterval) {
+                // It's a file watcher
+                this.fabricMonitorInterval.close();
+            }
+            else {
+                // It's a setInterval
+                clearInterval(this.fabricMonitorInterval);
+            }
             this.fabricMonitorInterval = null;
             log.debug('Stopped fabric monitoring');
         }
+        if (this.fabricCheckTimeout) {
+            clearTimeout(this.fabricCheckTimeout);
+            this.fabricCheckTimeout = null;
+        }
     }
     /**
      * Check for fabric changes and emit appropriate events
@@ -794,11 +900,21 @@ export class MatterServer extends EventEmitter {
             log.debug('Updated commissioning info file');
         }
         catch (error) {
-            log.debug(`Failed to update commissioning info file: ${error.message}`);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            log.debug(`Failed to update commissioning info file: ${errorMessage}`);
         }
     }
     /**
      * Register Matter platform accessories (Plugin API - matches HAP pattern)
+     *
+     * Registers Matter accessories from a dynamic platform plugin. Accessories are stored
+     * and automatically restored on server restart.
+     *
+     * @param pluginIdentifier - The plugin identifier (e.g., 'homebridge-example')
+     * @param platformName - The platform name from config.json
+     * @param accessories - Array of Matter accessories to register
+     * @throws {MatterDeviceError} If maximum device limit is reached or accessory is invalid
+     * @see {@link MatterAccessory} for accessory structure
      */
     async registerPlatformAccessories(pluginIdentifier, platformName, accessories) {
         for (const accessory of accessories) {
@@ -813,6 +929,36 @@ export class MatterServer extends EventEmitter {
             await this.unregisterAccessory(accessory.uuid);
         }
     }
+    /**
+     * Update Matter platform accessories in the cache
+     * Similar to api.updatePlatformAccessories() for HAP accessories
+     *
+     * This updates the cached accessory information without unregistering and re-registering.
+     * Useful when device metadata changes (name, manufacturer, firmware version, etc.)
+     */
+    async updatePlatformAccessories(accessories) {
+        if (!this.accessoryCache) {
+            log.warn('Cannot update Matter platform accessories - cache not initialized');
+            return;
+        }
+        for (const accessory of accessories) {
+            const internal = accessory;
+            // Verify accessory exists in current session and cache
+            if (!this.accessories.has(accessory.uuid)) {
+                log.warn(`Cannot update Matter accessory ${accessory.uuid} - not registered in current session`);
+                continue;
+            }
+            if (!this.accessoryCache.hasCached(accessory.uuid)) {
+                log.warn(`Cannot update Matter accessory ${accessory.uuid} - not found in cache`);
+                continue;
+            }
+            // Update the in-memory accessory
+            this.accessories.set(accessory.uuid, internal);
+            log.debug(`Updated Matter accessory ${accessory.uuid} (${accessory.displayName})`);
+        }
+        // Save updated accessories to cache
+        this.accessoryCache.requestSave(this.accessories);
+    }
     /**
      * Register a single Matter accessory (internal method)
      */
@@ -832,6 +978,69 @@ export class MatterServer extends EventEmitter {
                 + `New accessory: "${accessory.displayName}"\n`
                 + 'Each accessory must have a unique UUID. Use api.hap.uuid.generate() with a unique string.');
         }
+        // Restore cached state if available
+        this.restoreCachedState(accessory);
+        // Check device limit
+        if (this.accessories.size >= this.MAX_DEVICES) {
+            throw new MatterDeviceError(`Cannot register Matter accessory "${accessory.displayName}": `
+                + `Maximum device limit reached (${this.MAX_DEVICES} devices).\n`
+                + `Current registered devices: ${this.accessories.size}`);
+        }
+        try {
+            // Prepare device type with WindowCovering features
+            let deviceType = accessory.deviceType;
+            const windowCoveringFeatures = detectWindowCoveringFeatures(accessory);
+            if (windowCoveringFeatures.length > 0) {
+                deviceType = applyWindowCoveringFeatures(deviceType, accessory, windowCoveringFeatures);
+            }
+            // Detect cluster features for behavior configuration
+            const features = this.detectClusterFeatures(accessory, deviceType);
+            // Build and apply custom behaviors based on handlers
+            const customBehaviors = this.buildCustomBehaviors(accessory, deviceType, features);
+            if (customBehaviors.length > 0) {
+                deviceType = withBehaviors(deviceType, customBehaviors);
+                log.info(`Applied ${customBehaviors.length} custom behavior(s) to device type`);
+            }
+            // Add BridgedDeviceBasicInformationServer for bridged devices only
+            // This is required by the Matter spec for devices behind an aggregator
+            // External accessories should NOT have this cluster
+            if (!this.config.externalAccessory) {
+                deviceType = withBehaviors(deviceType, [BridgedDeviceBasicInformationServer]);
+                log.debug(`Added BridgedDeviceBasicInformationServer to ${accessory.displayName}`);
+            }
+            // Create endpoint with cluster states
+            const endpointOptions = this.createEndpointOptions(accessory);
+            const endpoint = new Endpoint(deviceType, endpointOptions);
+            if (this.config.debugModeEnabled) {
+                log.debug(`Created endpoint for ${accessory.displayName} with initial cluster states`);
+            }
+            // Add endpoint to aggregator or serverNode depending on mode
+            if (this.config.externalAccessory) {
+                await this.serverNode.add(endpoint);
+                log.debug(`Added ${accessory.displayName} as external accessory to ServerNode`);
+            }
+            else {
+                await this.aggregator.add(endpoint);
+                if (this.config.debugModeEnabled) {
+                    log.debug(`Added endpoint for ${accessory.displayName} to aggregator`);
+                }
+            }
+            // Register command handlers
+            this.registerAccessoryHandlers(accessory);
+            // Create and register child endpoints (parts)
+            const internalParts = await this.createAccessoryParts(accessory);
+            // Finalize registration (store, emit events, save cache)
+            await this.finalizeAccessoryRegistration(accessory, endpoint, internalParts);
+        }
+        catch (error) {
+            log.error(`Failed to register Matter accessory ${accessory.displayName}:`, error);
+            throw new MatterDeviceError(`Failed to register accessory: ${error}`);
+        }
+    }
+    /**
+     * Restore cached state for an accessory
+     */
+    restoreCachedState(accessory) {
         // Check if there's a cached version - merge cached cluster states with new registration.
         // This ensures state persistence across Homebridge restarts.
         if (this.accessoryCache && this.accessoryCache.hasCached(accessory.uuid)) {
@@ -858,345 +1067,304 @@ export class MatterServer extends EventEmitter {
                 log.info(`Restored cached state for Matter accessory: ${accessory.displayName}`);
             }
         }
-        // Check device limit
-        if (this.accessories.size >= this.MAX_DEVICES) {
-            throw new MatterDeviceError(`Cannot register Matter accessory "${accessory.displayName}": `
-                + `Maximum device limit reached (${this.MAX_DEVICES} devices).\n`
-                + `Current registered devices: ${this.accessories.size}`);
+    }
+    /**
+     * Detect cluster features for an accessory
+     * Returns an object containing detected features for various clusters
+     */
+    detectClusterFeatures(accessory, deviceType) {
+        // Detect WindowCovering features
+        const windowCoveringFeatures = detectWindowCoveringFeatures(accessory);
+        // Detect ServiceArea features
+        let serviceAreaFeatures = null;
+        if (accessory.clusters?.serviceArea) {
+            const features = [];
+            // Check if Maps feature should be enabled (when supportedMaps is defined)
+            if (accessory.clusters.serviceArea.supportedMaps) {
+                features.push('Maps');
+            }
+            // Check if ProgressReporting feature should be enabled (when progress is defined)
+            if (accessory.clusters.serviceArea.progress !== undefined) {
+                features.push('ProgressReporting');
+            }
+            if (features.length > 0) {
+                serviceAreaFeatures = features;
+                log.info(`ServiceArea features will be enabled for ${accessory.displayName}: ${features.join(', ')}`);
+            }
         }
-        try {
-            // Modify device type with custom behaviors if handlers are defined
-            let deviceType = accessory.deviceType;
-            // Detect WindowCovering features
-            const windowCoveringFeatures = detectWindowCoveringFeatures(accessory);
-            if (windowCoveringFeatures.length > 0) {
-                deviceType = applyWindowCoveringFeatures(deviceType, accessory, windowCoveringFeatures);
+        // Detect ColorControl features
+        let colorControlFeatures = null;
+        if (accessory.handlers?.colorControl) {
+            colorControlFeatures = detectBehaviorFeatures(deviceType, CLUSTER_IDS.COLOR_CONTROL, extractColorControlFeatures);
+            if (colorControlFeatures) {
+                colorControlFeatures = determineColorControlFeaturesFromHandlers(accessory.handlers.colorControl);
             }
-            if (accessory.handlers) {
-                log.warn(`📝 [${accessory.displayName}] Has handlers: ${Object.keys(accessory.handlers).join(', ')}`);
-                // IMPORTANT: Detect ServiceArea features BEFORE modifying device type
-                let serviceAreaFeatures = null;
-                if (accessory.clusters?.serviceArea) {
-                    const features = [];
-                    // Check if Maps feature should be enabled (when supportedMaps is defined)
-                    if (accessory.clusters.serviceArea.supportedMaps) {
-                        features.push('Maps');
-                    }
-                    // Check if ProgressReporting feature should be enabled (when progress is defined)
-                    if (accessory.clusters.serviceArea.progress !== undefined) {
-                        features.push('ProgressReporting');
-                    }
-                    if (features.length > 0) {
-                        serviceAreaFeatures = features;
-                        log.info(`ServiceArea features will be enabled for ${accessory.displayName}: ${features.join(', ')}`);
+        }
+        // Detect Thermostat features
+        let thermostatFeatures = null;
+        if (accessory.handlers?.thermostat) {
+            thermostatFeatures = detectBehaviorFeatures(deviceType, CLUSTER_IDS.THERMOSTAT, extractThermostatFeatures);
+        }
+        return {
+            windowCoveringFeatures,
+            serviceAreaFeatures,
+            colorControlFeatures,
+            thermostatFeatures,
+        };
+    }
+    /**
+     * Build custom behaviors for an accessory based on handlers
+     */
+    buildCustomBehaviors(accessory, deviceType, features) {
+        const customBehaviors = [];
+        if (!accessory.handlers) {
+            return customBehaviors;
+        }
+        log.debug(`[${accessory.displayName}] Has handlers: ${Object.keys(accessory.handlers).join(', ')}`);
+        // Use the static cluster behavior map
+        const behaviorMap = MatterServer.CLUSTER_BEHAVIOR_MAP;
+        // For RoboticVacuumCleaner, add optional clusters if they're defined in accessory.clusters
+        // These clusters need to be added to the device type even if there are no handlers
+        if (isDeviceType(deviceType, devices.RoboticVacuumCleanerDevice)) {
+            // Import RVC requirements
+            const { RvcCleanModeServer, ServiceAreaServer } = devices.RoboticVacuumCleanerRequirements;
+            // Add RvcCleanMode if defined in clusters
+            if (accessory.clusters?.rvcCleanMode) {
+                // Check if there's a custom behavior with handlers
+                if (accessory.handlers?.rvcCleanMode) {
+                    const behaviorClass = HomebridgeRvcCleanModeServer;
+                    customBehaviors.push(behaviorClass);
+                    log.info('Adding custom RvcCleanMode behavior with handlers');
+                }
+                else {
+                    // No handlers, use base server
+                    customBehaviors.push(RvcCleanModeServer);
+                    log.info('Adding base RvcCleanMode server');
+                }
+            }
+            // Add ServiceArea if defined in clusters
+            if (accessory.clusters?.serviceArea) {
+                // Check if there's a custom behavior with handlers
+                if (accessory.handlers?.serviceArea) {
+                    let behaviorClass = HomebridgeServiceAreaServer;
+                    // Apply features if detected
+                    if (features.serviceAreaFeatures && features.serviceAreaFeatures.length > 0) {
+                        behaviorClass = withFeatures(behaviorClass, features.serviceAreaFeatures);
+                        log.info(`ServiceArea custom behavior will have features: ${features.serviceAreaFeatures.join(', ')}`);
                     }
+                    customBehaviors.push(behaviorClass);
+                    log.info('Adding custom ServiceArea behavior with handlers');
                 }
-                // Detect ColorControl features
-                let colorControlFeatures = null;
-                if (accessory.handlers.colorControl) {
-                    colorControlFeatures = detectBehaviorFeatures(deviceType, CLUSTER_IDS.COLOR_CONTROL, extractColorControlFeatures);
-                    if (colorControlFeatures) {
-                        colorControlFeatures = determineColorControlFeaturesFromHandlers(accessory.handlers.colorControl);
+                else {
+                    // No handlers, use base server with features
+                    let behaviorClass = ServiceAreaServer;
+                    if (features.serviceAreaFeatures && features.serviceAreaFeatures.length > 0) {
+                        behaviorClass = withFeatures(behaviorClass, features.serviceAreaFeatures);
+                        log.info(`ServiceArea base server will have features: ${features.serviceAreaFeatures.join(', ')}`);
                     }
+                    customBehaviors.push(behaviorClass);
+                    log.info('Adding base ServiceArea server');
                 }
-                // Detect Thermostat features
-                let thermostatFeatures = null;
-                if (accessory.handlers.thermostat) {
-                    thermostatFeatures = detectBehaviorFeatures(deviceType, CLUSTER_IDS.THERMOSTAT, extractThermostatFeatures);
+            }
+        }
+        for (const clusterName of Object.keys(accessory.handlers || {})) {
+            // Skip windowCovering if we already applied features via base WindowCoveringServer
+            const skipWindowCoveringBehavior = accessory.context?._skipWindowCoveringBehavior;
+            if (clusterName === 'windowCovering' && skipWindowCoveringBehavior) {
+                log.debug('Skipping custom WindowCovering behavior (using base server with features instead)');
+                continue;
+            }
+            // Skip RVC clusters - they're handled specially above for RoboticVacuumCleaner
+            if (clusterName === 'rvcCleanMode' || clusterName === 'serviceArea') {
+                continue;
+            }
+            let behaviorClass = behaviorMap[clusterName];
+            // Apply ColorControl features if we detected them earlier
+            if (clusterName === 'colorControl' && behaviorClass && features.colorControlFeatures && features.colorControlFeatures.length > 0) {
+                behaviorClass = withFeatures(behaviorClass, features.colorControlFeatures);
+                log.info(`ColorControl custom behavior will preserve features: ${features.colorControlFeatures.join(', ')}`);
+            }
+            // Apply Thermostat features if we detected them earlier
+            if (clusterName === 'thermostat' && behaviorClass && features.thermostatFeatures && features.thermostatFeatures.length > 0) {
+                behaviorClass = withFeatures(behaviorClass, features.thermostatFeatures);
+                log.info(`Thermostat custom behavior will preserve features: ${features.thermostatFeatures.join(', ')}`);
+            }
+            // Apply ServiceArea features if we detected them earlier
+            if (clusterName === 'serviceArea' && behaviorClass && features.serviceAreaFeatures && features.serviceAreaFeatures.length > 0) {
+                behaviorClass = withFeatures(behaviorClass, features.serviceAreaFeatures);
+                log.info(`ServiceArea custom behavior will preserve features: ${features.serviceAreaFeatures.join(', ')}`);
+            }
+            // Apply WindowCovering features to custom behavior as well
+            // (features were already applied to base device type, but custom behavior needs them too)
+            if (clusterName === 'windowCovering') {
+                log.debug(`WindowCovering handler found: behaviorClass=${!!behaviorClass}, windowCoveringFeatures=${features.windowCoveringFeatures}, length=${features.windowCoveringFeatures?.length}`);
+                if (behaviorClass && features.windowCoveringFeatures && features.windowCoveringFeatures.length > 0) {
+                    behaviorClass = withFeatures(behaviorClass, features.windowCoveringFeatures);
+                    log.debug(`WindowCovering custom behavior will have features: ${features.windowCoveringFeatures.join(', ')}`);
                 }
-                // Map cluster names to custom behavior classes
-                // Only clusters with user-triggered commands need custom behaviors
-                const behaviorMap = {
-                    // Core controls
-                    onOff: HomebridgeOnOffServer,
-                    levelControl: HomebridgeLevelControlServer,
-                    colorControl: HomebridgeColorControlServer,
-                    // Coverings & locks
-                    windowCovering: HomebridgeWindowCoveringServer,
-                    doorLock: HomebridgeDoorLockServer,
-                    // Climate control
-                    fanControl: HomebridgeFanControlServer,
-                    thermostat: HomebridgeThermostatServer,
-                    // Robotic vacuum cleaners
-                    rvcOperationalState: HomebridgeRvcOperationalStateServer,
-                    rvcRunMode: HomebridgeRvcRunModeServer,
-                    rvcCleanMode: HomebridgeRvcCleanModeServer,
-                    serviceArea: HomebridgeServiceAreaServer,
-                    // Identification
-                    identify: HomebridgeIdentifyServer,
-                };
-                // Build array of custom behaviors to apply based on what handlers are defined
-                const customBehaviors = [];
-                // For RoboticVacuumCleaner, add optional clusters if they're defined in accessory.clusters
-                // These clusters need to be added to the device type even if there are no handlers
-                if (deviceType === devices.RoboticVacuumCleanerDevice || deviceType.name === 'RoboticVacuumCleaner') {
-                    // Import RVC requirements
-                    const { RvcCleanModeServer, ServiceAreaServer } = devices.RoboticVacuumCleanerRequirements;
-                    // Add RvcCleanMode if defined in clusters
-                    if (accessory.clusters?.rvcCleanMode) {
-                        // Check if there's a custom behavior with handlers
-                        if (accessory.handlers?.rvcCleanMode) {
-                            const behaviorClass = HomebridgeRvcCleanModeServer;
-                            customBehaviors.push(behaviorClass);
-                            log.info('Adding custom RvcCleanMode behavior with handlers');
-                        }
-                        else {
-                            // No handlers, use base server
-                            customBehaviors.push(RvcCleanModeServer);
-                            log.info('Adding base RvcCleanMode server');
-                        }
-                    }
-                    // Add ServiceArea if defined in clusters
-                    if (accessory.clusters?.serviceArea) {
-                        // Check if there's a custom behavior with handlers
-                        if (accessory.handlers?.serviceArea) {
-                            let behaviorClass = HomebridgeServiceAreaServer;
-                            // Apply features if detected
-                            if (serviceAreaFeatures && serviceAreaFeatures.length > 0) {
-                                behaviorClass = behaviorClass.with(...serviceAreaFeatures);
-                                log.info(`ServiceArea custom behavior will have features: ${serviceAreaFeatures.join(', ')}`);
-                            }
-                            customBehaviors.push(behaviorClass);
-                            log.info('Adding custom ServiceArea behavior with handlers');
-                        }
-                        else {
-                            // No handlers, use base server with features
-                            let behaviorClass = ServiceAreaServer;
-                            if (serviceAreaFeatures && serviceAreaFeatures.length > 0) {
-                                behaviorClass = behaviorClass.with(...serviceAreaFeatures);
-                                log.info(`ServiceArea base server will have features: ${serviceAreaFeatures.join(', ')}`);
-                            }
-                            customBehaviors.push(behaviorClass);
-                            log.info('Adding base ServiceArea server');
-                        }
-                    }
+                else {
+                    log.debug(`Skipping WindowCovering feature application: behaviorClass=${!!behaviorClass}, features=${features.windowCoveringFeatures}`);
                 }
-                for (const clusterName of Object.keys(accessory.handlers || {})) {
-                    // Skip windowCovering if we already applied features via base WindowCoveringServer
-                    if (clusterName === 'windowCovering' && accessory.context?._skipWindowCoveringBehavior) {
-                        log.debug('Skipping custom WindowCovering behavior (using base server with features instead)');
-                        continue;
-                    }
-                    // Skip RVC clusters - they're handled specially above for RoboticVacuumCleaner
-                    if (clusterName === 'rvcCleanMode' || clusterName === 'serviceArea') {
-                        continue;
-                    }
-                    let behaviorClass = behaviorMap[clusterName];
-                    // Apply ColorControl features if we detected them earlier
-                    if (clusterName === 'colorControl' && behaviorClass && colorControlFeatures && colorControlFeatures.length > 0) {
-                        behaviorClass = behaviorClass.with(...colorControlFeatures);
-                        log.info(`ColorControl custom behavior will preserve features: ${colorControlFeatures.join(', ')}`);
-                    }
-                    // Apply Thermostat features if we detected them earlier
-                    if (clusterName === 'thermostat' && behaviorClass && thermostatFeatures && thermostatFeatures.length > 0) {
-                        behaviorClass = behaviorClass.with(...thermostatFeatures);
-                        log.info(`Thermostat custom behavior will preserve features: ${thermostatFeatures.join(', ')}`);
-                    }
-                    // Apply ServiceArea features if we detected them earlier
-                    if (clusterName === 'serviceArea' && behaviorClass && serviceAreaFeatures && serviceAreaFeatures.length > 0) {
-                        behaviorClass = behaviorClass.with(...serviceAreaFeatures);
-                        log.info(`ServiceArea custom behavior will preserve features: ${serviceAreaFeatures.join(', ')}`);
-                    }
-                    // Apply WindowCovering features to custom behavior as well
-                    // (features were already applied to base device type, but custom behavior needs them too)
-                    if (clusterName === 'windowCovering') {
-                        log.warn(`🔍 WindowCovering handler found: behaviorClass=${!!behaviorClass}, windowCoveringFeatures=${windowCoveringFeatures}, length=${windowCoveringFeatures?.length}`);
-                        if (behaviorClass && windowCoveringFeatures && windowCoveringFeatures.length > 0) {
-                            behaviorClass = behaviorClass.with(...windowCoveringFeatures);
-                            log.warn(`🔧 WindowCovering custom behavior will have features: ${windowCoveringFeatures.join(', ')}`);
-                        }
-                        else {
-                            log.warn(`⚠️  Skipping WindowCovering feature application: behaviorClass=${!!behaviorClass}, features=${windowCoveringFeatures}`);
-                        }
-                    }
+            }
+            if (behaviorClass) {
+                customBehaviors.push(behaviorClass);
+                log.info(`Will use ${behaviorClass.name} for ${accessory.displayName}`);
+            }
+            else {
+                log.warn(`No custom behavior class available for cluster '${clusterName}' - handlers will be registered but may not be called`);
+            }
+        }
+        return customBehaviors;
+    }
+    /**
+     * Create endpoint options for an accessory
+     */
+    createEndpointOptions(accessory) {
+        const endpointOptions = {
+            id: accessory.uuid,
+            ...accessory.clusters, // Spread cluster states as initial values
+        };
+        // Add bridgedDeviceBasicInformation cluster only for bridged devices
+        // For external accessories, use the root basicInformation instead
+        if (!this.config.externalAccessory) {
+            endpointOptions.bridgedDeviceBasicInformation = {
+                vendorName: accessory.manufacturer,
+                nodeLabel: accessory.displayName, // Main end user name for the device
+                productName: accessory.model,
+                productLabel: accessory.displayName,
+                serialNumber: accessory.serialNumber,
+                reachable: true,
+            };
+        }
+        return endpointOptions;
+    }
+    /**
+     * Register command handlers for an accessory
+     */
+    registerAccessoryHandlers(accessory) {
+        if (!accessory.handlers) {
+            return;
+        }
+        log.info(`Setting up handlers for accessory ${accessory.uuid}`);
+        // Register handlers with the custom behavior classes
+        for (const [clusterName, handlers] of Object.entries(accessory.handlers)) {
+            log.info(`  Processing cluster: ${clusterName}`);
+            for (const [commandName, handler] of Object.entries(handlers)) {
+                this.behaviorRegistry.registerHandler(accessory.uuid, clusterName, commandName, handler);
+            }
+        }
+    }
+    /**
+     * Create and register child endpoints (parts) for an accessory
+     */
+    async createAccessoryParts(accessory) {
+        const internalParts = [];
+        if (!accessory.parts || accessory.parts.length === 0) {
+            return internalParts;
+        }
+        log.info(`Creating ${accessory.parts.length} child endpoint(s) for ${accessory.displayName}`);
+        for (const part of accessory.parts) {
+            // Create unique endpoint ID for this part
+            const partEndpointId = `${accessory.uuid}-part-${part.id}`;
+            // Register the part endpoint mapping for handler context
+            this.behaviorRegistry.registerPartEndpoint(partEndpointId, accessory.uuid, part.id);
+            // Apply custom behaviors to part based on its handlers (same logic as main accessory)
+            let partDeviceType = part.deviceType;
+            const partCustomBehaviors = [];
+            if (part.handlers) {
+                // Use the static cluster behavior map for parts as well
+                const partBehaviorMap = MatterServer.CLUSTER_BEHAVIOR_MAP;
+                for (const clusterName of Object.keys(part.handlers)) {
+                    const behaviorClass = partBehaviorMap[clusterName];
                     if (behaviorClass) {
-                        customBehaviors.push(behaviorClass);
-                        log.info(`Will use ${behaviorClass.name} for ${accessory.displayName}`);
+                        partCustomBehaviors.push(behaviorClass);
+                        log.info(`  Will use ${behaviorClass.name} for part ${part.id}`);
                     }
                     else {
-                        log.warn(`No custom behavior class available for cluster '${clusterName}' - handlers will be registered but may not be called`);
+                        log.warn(`No custom behavior class available for cluster '${clusterName}' on part ${part.id}`);
                     }
                 }
-                if (customBehaviors.length > 0) {
-                    // Cast to any to bypass TypeScript limitations
-                    deviceType = deviceType.with(...customBehaviors);
-                    log.info(`Applied ${customBehaviors.length} custom behavior(s) to device type`);
+                if (partCustomBehaviors.length > 0) {
+                    // Add custom behaviors to part device type
+                    partDeviceType = withBehaviors(partDeviceType, partCustomBehaviors);
+                    log.info(`  Applied ${partCustomBehaviors.length} custom behavior(s) to part ${part.id}`);
                 }
             }
-            // Add BridgedDeviceBasicInformationServer for bridged devices only
-            // This is required by the Matter spec for devices behind an aggregator
-            // External accessories should NOT have this cluster
+            // Add BridgedDeviceBasicInformationServer for bridged parts
             if (!this.config.externalAccessory) {
-                deviceType = deviceType.with(BridgedDeviceBasicInformationServer);
-                log.debug(`Added BridgedDeviceBasicInformationServer to ${accessory.displayName}`);
+                partDeviceType = withBehaviors(partDeviceType, [BridgedDeviceBasicInformationServer]);
             }
-            // Create endpoint with the modified device type AND initial cluster states
-            // IMPORTANT: Cluster states must be provided at creation time, before adding to aggregator
-            // This ensures mandatory attributes are set before Matter.js validates the endpoint
-            const endpointOptions = {
-                id: accessory.uuid,
-                ...accessory.clusters, // Spread cluster states as initial values
+            // Create endpoint options with cluster states
+            const partEndpointOptions = {
+                id: partEndpointId,
+                ...part.clusters,
             };
-            // Add bridgedDeviceBasicInformation cluster only for bridged devices
-            // For external accessories, use the root basicInformation instead
+            // Add bridgedDeviceBasicInformation for the part
             if (!this.config.externalAccessory) {
-                endpointOptions.bridgedDeviceBasicInformation = {
+                partEndpointOptions.bridgedDeviceBasicInformation = {
                     vendorName: accessory.manufacturer,
-                    nodeLabel: accessory.displayName, // Main end user name for the device
+                    nodeLabel: part.displayName || `${accessory.displayName} - ${part.id}`,
                     productName: accessory.model,
-                    productLabel: accessory.displayName,
-                    serialNumber: accessory.serialNumber,
+                    productLabel: part.displayName || part.id,
+                    serialNumber: `${accessory.serialNumber}-${part.id}`,
                     reachable: true,
                 };
             }
-            const endpoint = new Endpoint(deviceType, endpointOptions);
-            if (this.config.debugModeEnabled) {
-                log.debug(`Created endpoint for ${accessory.displayName} with initial cluster states`);
-            }
-            // Add to aggregator or serverNode depending on mode
-            // (validation happens here - cluster states must already be set)
+            // Create the part endpoint
+            const partEndpoint = new Endpoint(partDeviceType, partEndpointOptions);
+            // Add part endpoint to aggregator or serverNode
             if (this.config.externalAccessory) {
-                // In external accessory mode, add device directly to serverNode as root endpoint
-                await this.serverNode.add(endpoint);
-                log.debug(`Added ${accessory.displayName} as external accessory to ServerNode`);
+                await this.serverNode.add(partEndpoint);
             }
             else {
-                // In bridge mode, add to aggregator
-                await this.aggregator.add(endpoint);
-                if (this.config.debugModeEnabled) {
-                    log.debug(`Added endpoint for ${accessory.displayName} to aggregator`);
-                }
+                await this.aggregator.add(partEndpoint);
             }
-            // Set up command handlers if provided
-            if (accessory.handlers) {
-                log.info(`Setting up handlers for accessory ${accessory.uuid}`);
-                // Register handlers with the custom behavior classes
-                for (const [clusterName, handlers] of Object.entries(accessory.handlers)) {
-                    log.info(`  Processing cluster: ${clusterName}`);
+            log.info(`  Created part endpoint: ${part.displayName || part.id} (${partEndpointId})`);
+            // Set up handlers for this part
+            if (part.handlers) {
+                for (const [clusterName, handlers] of Object.entries(part.handlers)) {
                     for (const [commandName, handler] of Object.entries(handlers)) {
-                        registerHandler(accessory.uuid, clusterName, commandName, handler);
-                    }
-                }
-            }
-            // Create and register parts (child endpoints) if provided
-            const internalParts = [];
-            if (accessory.parts && accessory.parts.length > 0) {
-                log.info(`Creating ${accessory.parts.length} child endpoint(s) for ${accessory.displayName}`);
-                for (const part of accessory.parts) {
-                    // Create unique endpoint ID for this part
-                    const partEndpointId = `${accessory.uuid}-part-${part.id}`;
-                    // Register the part endpoint mapping for handler context
-                    registerPartEndpoint(partEndpointId, accessory.uuid, part.id);
-                    // Apply custom behaviors to part based on its handlers (same logic as main accessory)
-                    let partDeviceType = part.deviceType;
-                    const partCustomBehaviors = [];
-                    if (part.handlers) {
-                        // Map cluster names to custom behavior classes for parts
-                        const partBehaviorMap = {
-                            onOff: HomebridgeOnOffServer,
-                            levelControl: HomebridgeLevelControlServer,
-                            colorControl: HomebridgeColorControlServer,
-                            windowCovering: HomebridgeWindowCoveringServer,
-                            doorLock: HomebridgeDoorLockServer,
-                            fanControl: HomebridgeFanControlServer,
-                            thermostat: HomebridgeThermostatServer,
-                            identify: HomebridgeIdentifyServer,
-                        };
-                        for (const clusterName of Object.keys(part.handlers)) {
-                            const behaviorClass = partBehaviorMap[clusterName];
-                            if (behaviorClass) {
-                                partCustomBehaviors.push(behaviorClass);
-                                log.info(`  Will use ${behaviorClass.name} for part ${part.id}`);
-                            }
-                            else {
-                                log.warn(`No custom behavior class available for cluster '${clusterName}' on part ${part.id}`);
-                            }
-                        }
-                        if (partCustomBehaviors.length > 0) {
-                            // Matter.js device types support .with() to add behaviors
-                            partDeviceType = partDeviceType.with(...partCustomBehaviors);
-                            log.info(`  Applied ${partCustomBehaviors.length} custom behavior(s) to part ${part.id}`);
-                        }
-                    }
-                    // Add BridgedDeviceBasicInformationServer for bridged parts
-                    if (!this.config.externalAccessory) {
-                        // Matter.js device types support .with() to add behaviors
-                        partDeviceType = partDeviceType.with(BridgedDeviceBasicInformationServer);
-                    }
-                    // Create endpoint options with cluster states
-                    const partEndpointOptions = {
-                        id: partEndpointId,
-                        ...part.clusters,
-                    };
-                    // Add bridgedDeviceBasicInformation for the part
-                    if (!this.config.externalAccessory) {
-                        partEndpointOptions.bridgedDeviceBasicInformation = {
-                            vendorName: accessory.manufacturer,
-                            nodeLabel: part.displayName || `${accessory.displayName} - ${part.id}`,
-                            productName: accessory.model,
-                            productLabel: part.displayName || part.id,
-                            serialNumber: `${accessory.serialNumber}-${part.id}`,
-                            reachable: true,
-                        };
-                    }
-                    // Create the part endpoint
-                    const partEndpoint = new Endpoint(partDeviceType, partEndpointOptions);
-                    // Add part endpoint to aggregator or serverNode
-                    if (this.config.externalAccessory) {
-                        await this.serverNode.add(partEndpoint);
-                    }
-                    else {
-                        await this.aggregator.add(partEndpoint);
-                    }
-                    log.info(`  Created part endpoint: ${part.displayName || part.id} (${partEndpointId})`);
-                    // Set up handlers for this part
-                    if (part.handlers) {
-                        for (const [clusterName, handlers] of Object.entries(part.handlers)) {
-                            for (const [commandName, handler] of Object.entries(handlers)) {
-                                // Register handler with the part's endpoint ID
-                                registerHandler(partEndpointId, clusterName, commandName, handler);
-                            }
-                        }
-                        log.debug(`  Registered ${Object.keys(part.handlers).length} handler(s) for part ${part.id}`);
+                        // Register handler with the part's endpoint ID
+                        this.behaviorRegistry.registerHandler(partEndpointId, clusterName, commandName, handler);
                     }
-                    // Store the internal part
-                    internalParts.push({
-                        ...part,
-                        endpoint: partEndpoint,
-                    });
                 }
+                log.debug(`  Registered ${Object.keys(part.handlers).length} handler(s) for part ${part.id}`);
             }
-            // Store accessory with internal metadata and event emitter
-            // The event emitter allows plugins to listen for lifecycle events (ready, commissioned, decommissioned)
-            const internalAccessory = {
-                ...accessory,
-                _associatedPlugin: pluginIdentifier,
-                _associatedPlatform: platformName,
-                endpoint,
-                registered: true,
-                _parts: internalParts.length > 0 ? internalParts : undefined,
-                _eventEmitter: new EventEmitter(),
-            };
-            this.accessories.set(accessory.uuid, internalAccessory);
-            log.info(`Registered Matter accessory: ${accessory.displayName} (${accessory.uuid})`);
-            if (this.config.debugModeEnabled) {
-                log.debug(`Total registered accessories: ${this.accessories.size}/${this.MAX_DEVICES}`);
-            }
-            // Emit accessory-registered event
-            this.emit('accessory-registered', accessory);
-            // Notify controllers about the new device (parts list changed)
-            // This allows the Home app to discover new devices without re-pairing
-            await this.notifyPartsListChanged();
-            // Save to cache asynchronously (don't block registration)
-            if (this.accessoryCache) {
-                this.accessoryCache.save(this.accessories).catch((error) => {
-                    log.warn('Failed to save accessory cache:', error);
-                });
-            }
+            // Store the internal part
+            internalParts.push({
+                ...part,
+                endpoint: partEndpoint,
+            });
         }
-        catch (error) {
-            log.error(`Failed to register Matter accessory ${accessory.displayName}:`, error);
-            throw new MatterDeviceError(`Failed to register accessory: ${error}`);
+        return internalParts;
+    }
+    /**
+     * Finalize accessory registration (store, emit events, save cache)
+     */
+    async finalizeAccessoryRegistration(accessory, endpoint, internalParts) {
+        // Store accessory with internal metadata and event emitter
+        // The event emitter allows plugins to listen for lifecycle events (ready, commissioned, decommissioned)
+        // Note: _associatedPlugin and _associatedPlatform are already set by MatterAPIImpl
+        const internalAccessory = {
+            ...accessory,
+            endpoint,
+            registered: true,
+            _parts: internalParts.length > 0 ? internalParts : undefined,
+            _eventEmitter: new EventEmitter(),
+        };
+        this.accessories.set(accessory.uuid, internalAccessory);
+        log.info(`Registered Matter accessory: ${accessory.displayName} (${accessory.uuid})`);
+        if (this.config.debugModeEnabled) {
+            log.debug(`Total registered accessories: ${this.accessories.size}/${this.MAX_DEVICES}`);
+        }
+        // Emit accessory-registered event
+        this.emit('accessory-registered', accessory);
+        // Notify controllers about the new device (parts list changed)
+        // This allows the Home app to discover new devices without re-pairing
+        await this.notifyPartsListChanged();
+        // Request debounced save to cache (reduces disk I/O during rapid registration)
+        if (this.accessoryCache) {
+            this.accessoryCache.requestSave(this.accessories);
         }
     }
     /**
@@ -1211,9 +1379,7 @@ export class MatterServer extends EventEmitter {
             if (this.accessoryCache && this.accessoryCache.getCached(uuid)) {
                 log.debug(`Removing ${uuid} from cache`);
                 this.accessoryCache.removeCached(uuid);
-                this.accessoryCache.save(this.accessories).catch((error) => {
-                    log.warn('Failed to save accessory cache:', error);
-                });
+                this.accessoryCache.requestSave(this.accessories);
             }
             return;
         }
@@ -1231,9 +1397,7 @@ export class MatterServer extends EventEmitter {
             // Update cache (remove the accessory)
             if (this.accessoryCache) {
                 this.accessoryCache.removeCached(uuid);
-                this.accessoryCache.save(this.accessories).catch((error) => {
-                    log.warn('Failed to save accessory cache:', error);
-                });
+                this.accessoryCache.requestSave(this.accessories);
             }
         }
         catch (error) {
@@ -1281,10 +1445,10 @@ export class MatterServer extends EventEmitter {
             displayName = accessory.displayName;
         }
         // Defer the update to avoid "read-only transaction" errors when called from handlers
-        // Matter.js uses transactions, and we need to wait until the transaction fully completes
-        // Use setTimeout with a delay to ensure we're completely outside the transaction
+        // Matter.js uses transactions, and we need to escape the current call stack
+        // setImmediate ensures we're in a new event loop tick without arbitrary delays
         return new Promise((resolve, reject) => {
-            setTimeout(async () => {
+            setImmediate(async () => {
                 try {
                     // Construct the update object
                     const updateObject = { [cluster]: attributes };
@@ -1313,7 +1477,7 @@ export class MatterServer extends EventEmitter {
                     log.error(`Failed to update state for accessory ${uuid}${partInfo}:`, error);
                     reject(new MatterDeviceError(`Failed to update accessory state: ${error}`));
                 }
-            }, 50); // 50ms delay to ensure we're completely outside the transaction
+            });
         });
     }
     /**
@@ -1452,7 +1616,6 @@ export class MatterServer extends EventEmitter {
         this.isRunning = false;
         // Stop monitoring
         this.stopFabricMonitoring();
-        networkMonitor.stopMonitoring();
         try {
             // Save accessory cache before shutting down (BEFORE clearing accessories!)
             if (this.accessoryCache && this.accessories.size > 0) {
@@ -1508,6 +1671,23 @@ export class MatterServer extends EventEmitter {
     }
     /**
      * Get fabric information for commissioned controllers
+     *
+     * Returns information about each paired controller (fabric) including:
+     * - fabricIndex: Unique identifier for the fabric
+     * - fabricId: 64-bit fabric identifier
+     * - nodeId: Node identifier within the fabric
+     * - rootVendorId: Vendor ID of the root node
+     * - label: Optional human-readable label
+     *
+     * @returns Array of fabric information objects, or empty array if no fabrics are commissioned
+     * @example
+     * ```typescript
+     * const fabrics = matterServer.getFabricInfo()
+     * console.log(`Commissioned to ${fabrics.length} controller(s)`)
+     * fabrics.forEach(fabric => {
+     *   console.log(`  Fabric ${fabric.fabricIndex}: ${fabric.label || 'Unnamed'}`)
+     * })
+     * ```
      */
     getFabricInfo() {
         try {
@@ -1641,8 +1821,11 @@ export class MatterServer extends EventEmitter {
             // The fabric monitoring will detect this change and emit the appropriate events
         }
         catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
             log.error(`Failed to remove fabric ${fabricIndex}:`, error);
-            throw new MatterDeviceError(`Failed to remove fabric: ${error.message}`, error);
+            throw new MatterDeviceError(`Failed to remove fabric: ${errorMessage}`, {
+                originalError: error instanceof Error ? error : undefined,
+            });
         }
     }
     /**
@@ -1685,8 +1868,9 @@ export class MatterServer extends EventEmitter {
         }
         catch (error) {
             // Non-fatal error - log but don't throw
-            log.warn(`Failed to notify controllers of parts list change: ${error.message}`);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            log.warn(`Failed to notify controllers of parts list change: ${errorMessage}`);
         }
     }
 }
-//# sourceMappingURL=matterServer.js.map
+//# sourceMappingURL=server.js.map