@switchbot/homebridge-switchbot 5.0.0-beta.13 → 5.0.0-beta.130

package/todo/COMPLETED.md

@@ -0,0 +1,542 @@
+# Batch Import & Discovery UI Enhancements ✅ COMPLETED
+
+- [x] Add checkboxes to select multiple devices
+  - Users can now select multiple discovered devices using checkboxes in the discovery UI for batch actions.
+- [x] Add "Add Selected to Config" button
+  - A prominent "Add Selected to Config" button enables batch import of all selected devices, streamlining onboarding.
+- [x] Implement bulk configuration with smart defaults
+  - When importing multiple devices, the system applies smart defaults (type, name, MAC, etc.) and auto-fills config fields, reducing manual entry and errors.
+- [x] Show firmware update available indicators
+  - Devices with available firmware updates display an orange "Update Available" badge in the discovery UI.
+- [x] Show offline/unreachable warnings
+  - Devices that are offline or unreachable show a red "Offline" badge, based on status or last-seen timestamp.
+- [x] Add "Needs Attention" section at top
+  - Devices needing action (low battery, firmware update, offline) are grouped in a "Needs Attention" section at the top of the discovery UI for quick access.
+
+**Status:** All batch import and discovery UI features are implemented and live. Only battery level trending (historical data) remains as a future enhancement.
+# Integration: node-switchbot Beta Updates (March 2026)
+
+### Duplicate Detection ✅ COMPLETED
+
+- [x] The UI disables the "Add to Config" button and shows an "Already Added" badge for devices already in the config, preventing duplicate entries. Badges for recommended connection (BLE/API) are also shown based on signal/device type.
+
+**Status:** Duplicate detection is enforced in the UI, so users cannot add the same device twice. Connection recommendation badges are also displayed.
+# Integration: node-switchbot Beta Updates (March 2026)
+
+### One-Click Device Import ✅ COMPLETED
+
+- [x] Add "Add to Config" button next to each discovered device. Dramatically speeds up onboarding, reduces manual steps for users.
+
+**Status:** Each discovered device in the UI now has an "Add to Config" button. This enables one-click import directly from the discovery list.
+
+### Auto-populate Device Config Modal ✅ COMPLETED
+
+- [x] When importing, the config modal is auto-filled with discovered values (name, type, MAC, etc). Reduces user error and makes adding devices nearly frictionless.
+
+**Status:** The import modal pre-fills all relevant fields with discovered device data, streamlining the import process.
+
+### Pre-fill MAC Address for BLE Devices ✅ COMPLETED
+
+- [x] The import modal auto-fills the MAC address field with the discovered device's address, ensuring BLE devices are always added with the correct MAC.
+
+**Status:** The MAC address is pre-filled in the config modal for BLE devices, preventing user error and connection issues.
+
+### Duplicate Detection ✅ COMPLETED
+
+- [x] The UI disables the "Add to Config" button and shows an "Already Added" badge for devices already in the config, preventing duplicate entries.
+
+**Status:** Duplicate detection is enforced in the UI, so users cannot add the same device twice.
+# Integration: node-switchbot Beta Updates (March 2026)
+
+### Duplicate Detection ✅ COMPLETED
+
+- [x] The UI disables the "Add to Config" button and shows an "Already Added" badge for devices already in the config, preventing duplicate entries.
+
+**Status:** Duplicate detection is enforced in the UI, so users cannot add the same device twice.
+# Integration: node-switchbot Beta Updates (March 2026)
+
+### Pre-fill MAC Address for BLE Devices ✅ COMPLETED
+
+- [x] The import modal auto-fills the MAC address field with the discovered device's address, ensuring BLE devices are always added with the correct MAC.
+
+**Status:** The MAC address is pre-filled in the config modal for BLE devices, preventing user error and connection issues.
+# Integration: node-switchbot Beta Updates (March 2026)
+
+### One-Click Device Import ✅ COMPLETED
+
+- [x] Add "Add to Config" button next to each discovered device. Dramatically speeds up onboarding, reduces manual steps for users.
+
+**Status:** Each discovered device in the UI now has an "Add to Config" button. This enables one-click import directly from the discovery list.
+
+### Auto-populate Device Config Modal ✅ COMPLETED
+
+- [x] When importing, the config modal is auto-filled with discovered values (name, type, MAC, etc). Reduces user error and makes adding devices nearly frictionless.
+
+**Status:** The import modal pre-fills all relevant fields with discovered device data, streamlining the import process.
+# Integration: node-switchbot Beta Updates (March 2026)
+- [x] Update device registry and class mapping to match node-switchbot
+- [x] Add notification handling for BLE devices (per-command notification futures, unsolicited notification logging)
+
+- [x] Map new device types to Homebridge plugin (HubMini Matter, Hub3, Keypad Vision/Pro, Plug Mini EU, Roller Shade, Garage Door Opener, Floor Lamp, Art Frame, RGBICWW variants, K10/K11/K20/S10/S20 vacuums, Lock Lite/Vision/Pro/WiFi, Circulator Fan, Smart Thermostat Radiator, Climate Panel, Evaporative Humidifier, Strip Light 3, etc.)
+- [x] Expose new device features in UI (air quality, preset modes, calibration, direction, multi-command, extended info, segmented control, etc.)
+- [x] Integrate BLE encryption for all supported devices (relay, lock, air purifier, light strip, bulb, etc.)
+# BLE Response Length Validation ✅ COMPLETED
+
+- [x] Implement response length validation for BLE status parsing
+
+**Status:** All BLE status parsing now validates the response buffer/array length before parsing. Invalid responses are logged and rejected, improving robustness and diagnostics for all BLE devices.
+
+---
+# Error Class Handling Integration ✅ COMPLETED
+
+- [x] Add support for new error classes and improved error handling (SwitchbotOperationError, SwitchbotAuthenticationError, CharacteristicMissingError)
+
+**Status:** The plugin now imports and uses node-switchbot v4 error classes, with robust instanceof-based handling and compatible fallbacks. All error types are logged and surfaced appropriately, and the code is ready for future node-switchbot error model changes.
+
+---
+### Batch Enable/Disable Devices ✅ COMPLETED
+
+- [x] Allow batch enable/disable of devices
+
+**Status:** The UI now provides 'Enable Selected' and 'Disable Selected' buttons, allowing users to batch enable or disable devices directly from the discovery view.
+
+---
+
+### Batch Operation Progress Indicator ✅ COMPLETED
+
+- [x] Show progress for batch operations
+
+**Status:** The UI now displays a progress indicator during batch add/configure operations, giving users real-time feedback on operation status and completion.
+
+---
+
+### Real-Time RSSI Updates During Scan ✅ COMPLETED
+
+- [x] Update RSSI values in real-time during scan
+
+**Status:** The UI now polls for BLE scan results and updates device RSSI values live during the scan window, providing real-time signal strength feedback.
+
+---
+
+### Needs Attention Section in Discovery UI ✅ COMPLETED
+
+- [x] Add 'Needs Attention' section at the top of the device discovery UI
+
+**Status:** Devices with low battery (<20%), firmware updates available, or offline/unreachable status are now aggregated and displayed in a prominent 'Needs Attention' section at the top of the discovery UI. This helps users quickly identify and address devices that require action.
+
+---
+
+# Completed TODOs
+
+### Firmware Update Available Indicator ✅ COMPLETED
+
+### Offline/Unreachable Warning Indicator ✅ COMPLETED
+
+- [x] Show offline/unreachable warnings
+
+**Status:** Devices that are offline or unreachable (either via a boolean property or if last seen > 1 hour ago) now display a red 'Offline' badge in the discovery UI next to the device name.
+
+
+- [x] Show firmware update available indicators
+
+**Status:** Devices with a firmware update available now display an orange 'Update Available' badge in the discovery UI next to the device name.
+
+
+This file tracks all completed features and improvements for the SwitchBot Homebridge Plugin.
+
+---
+
+## Recent Completed Work
+
+### Connection Testing (First Slice) ✅ COMPLETED
+
+- [x] Added "Test Connection" button per device (discovered and configured cards)
+- [x] Added backend connectivity check endpoint (`/test-connection`)
+- [x] Attempted basic status read via device fetch during test
+- [x] Added success/failure indicator with inline result details
+- [x] Displayed measured connection latency (ms)
+- [x] Displayed connection method result (BLE/OpenAPI/Auto)
+
+  **Status:** Users can now run per-device connection checks directly from the UI and immediately see method and latency results.
+
+### Matter Neon Wire Rope Light Registration Verification ✅ COMPLETED
+
+- [x] **Verify Matter registration for "Family Room Neon Wire Rope Light" succeeds without behavior rollback**
+  - [x] Added targeted Matter integration regression test for `RGBIC Neon Wire Rope Light`
+  - [x] Verified normalization to Matter type `lightstrip`
+  - [x] Verified `colorControl.colorMode` default is present (`0`) to satisfy conformance
+  - [x] Validated registration path end-to-end with Matter harness
+
+  **Status:** Neon Wire Rope Light registration now has regression coverage and registers with conformant ColorControl defaults.
+
+### Matter Lightstrip Conformance ✅ COMPLETED
+
+- [x] **Fix Matter lightstrip registration conformance requiring `colorControl.colorMode`**
+  - [x] **Issue:** Matter accessory initialization failed for color lightstrip devices with conformance errors
+  - [x] **Error:** `Conformance "M": Matter requires you to set this attribute ... colorControl.state.colorMode`
+  - [x] **Fix:** Added required `colorMode` default for lightstrip color control state while avoiding disallowed default writes
+
+  **Status:** Lightstrip accessories now provide required ColorControl state for Matter initialization.
+
+
+### Battery Warnings in Device List ✅ COMPLETED
+
+- [x] Show battery warnings (< 20%) with yellow/red indicators
+
+**Status:** Devices with battery below 20% now display a yellow (10–19%) or red (<10%) warning badge in the discovery UI, with a tooltip for low/critical battery.
+
+### Streaming BLE Device Discovery ✅ COMPLETED
+
+- [x] Show devices as they're discovered (streaming results via polling)
+
+**Status:** Devices now appear in the UI as soon as they're discovered during BLE scan, providing a real-time streaming experience.
+
+---
+
+### Discovery Better Loading States ✅ COMPLETED
+
+- [x] Show progress indicator phases: `Scanning BLE` → `Fetching OpenAPI` → `Complete`
+- [x] Added spinner/progress visuals for each phase
+- [x] Display partial discovery results while later phases continue
+- [x] Show elapsed time for current phase and total discovery time
+- [x] Added cancel button for long discovery runs
+
+  **Status:** Discovery UX now provides real-time progress and immediate partial feedback.
+
+### Discovery Device Grouping ✅ COMPLETED
+
+- [x] Implemented grouping by connection type
+- [x] Implemented grouping by hub
+- [x] Added expandable/collapsible group headers
+- [x] Added group counts in headers
+- [x] Persisted expanded/collapsed state in localStorage
+
+  **Status:** Discovery lists are grouped, collapsible, and stateful across sessions.
+
+### Discovery Connection Recommendations ✅ COMPLETED
+
+- [x] Added `⚡ Recommended: BLE` badge for strong RSSI devices
+- [x] Added `☁️ Recommended: API` badge for hub-dependent devices
+- [x] Added recommendation tooltips explaining reasoning
+- [x] Applied device-type-aware recommendation heuristics
+
+  **Status:** Discovery cards now provide actionable connection guidance.
+
+### Configurable BLE Scan ✅ COMPLETED
+
+- [x] Added scan duration settings (3s/5s/10s/15s)
+- [x] Added option to disable BLE scanning
+- [x] Added adjustable BLE timeout setting
+- [x] Persisted BLE scan preferences in localStorage
+- [x] Added Bluetooth availability status indicator
+
+  **Status:** BLE discovery behavior is user-configurable and persisted.
+
+### Discovery History/Cache ✅ COMPLETED
+
+- [x] Cache last discovery results for 5 minutes
+- [x] Show "Last scanned: X minutes ago" with timestamp
+- [x] Add "Refresh" button to re-scan
+- [x] Show cached results immediately on page load
+- [x] Auto-refresh option with configurable interval
+
+  **Status:** Discovery now restores recent results instantly and supports manual/automatic refresh.
+
+### Discovery UX Polish ✅ COMPLETED
+
+- [x] Added `Hide Added` discovery filter to exclude already-configured devices
+- [x] Improved BLE settings row alignment (`Scan`, `Timeout`, and units)
+- [x] Reduced extra spacing between BLE settings row and Bluetooth adapter status
+- [x] Hide `Scan` and `Timeout` controls when `Disable BLE scan` is enabled
+
+  **Status:** Discovery controls are cleaner and faster to use for repeat configuration workflows.
+
+### Detailed Device Info Panel ✅ COMPLETED
+
+- [x] Added click-to-expand toggle button (▾) to device cards with rotation animation
+- [x] Created expandable details panel showing extended device information:
+  - [x] Device ID with copy button
+  - [x] MAC Address with copy button
+  - [x] Device Type
+  - [x] Model
+  - [x] Hub ID (if applicable)
+  - [x] Battery level (if available)
+  - [x] Firmware version (if available)
+  - [x] Cloud Service status (enabled/disabled)
+  - [x] Last Seen timestamp (human-readable format)
+- [x] Implemented copy-to-clipboard functionality with visual feedback (📋 → ✓ for 2s)
+- [x] Styled details panel with SwitchBot theme (light gray background, compact rows)
+- [x] Persisted expand/collapse state in-session (resets on page reload)
+
+  **Status:** Device cards now provide quick access to extended metadata with one-click copying of ID and MAC. Details panel uses clean, readable table layout within the card.
+
+### Extended Details in Configured Devices ✅ COMPLETED
+
+- [x] Added expandable toggle (▾) to configured device cards in config section
+- [x] Details panel shows same extended information as discovered devices:
+  - [x] Device ID with copy button
+  - [x] MAC Address with copy button  
+  - [x] Device Type
+  - [x] Model
+  - [x] Hub ID (if applicable)
+  - [x] Battery level (if available)
+  - [x] Firmware version (if available)
+  - [x] Cloud Service status
+  - [x] Last Seen timestamp
+- [x] Toggle button rotates when expanded/collapsed (smooth animation)
+- [x] Details available directly from card without opening Edit modal
+
+  **Status:** Configured devices now have the same quick-access details panel as discovered devices, making it easy to view metadata without opening the Edit dialog.
+
+### Real-Time BLE Scanning (Partial) ✅ PARTIALLY COMPLETED
+
+- [x] Added animated "pulsing" indicator during active BLE scan using CSS animation
+- [x] Implemented "X devices found..." counter that displays during scan
+  - Shows BLE device count after BLE phase completes
+  - Updates to merged count when OpenAPI phase completes
+  - Auto-hides when discovery finishes
+- [x] Counter shows pulse animation (1.5s opacity fade cycle) while scanning
+- [x] Gracefully removes pulse animation and hides counter on cancellation/error
+- [ ] Real-time streaming results via polling (partial implementation - displays final count per phase)
+- [ ] Real-time RSSI updates during scan (requires server-side streaming support)
+
+  **Status:** Discovery now shows visual feedback with a pulsing "X devices found" counter. Full streaming of individual results per-device would require backend support for Server-Sent Events (SSE) or WebSocket streaming. Current implementation displays phase-wise device counts (BLE count → merged final count).
+
+---
+
+## Code Refactoring & Architecture
+
+### Server-Side Refactoring ✅ COMPLETED
+
+- [x] **Split `server.ts` into modular structure**
+  - [x] Created `src/homebridge-ui/endpoints/discovery.ts` - Discovery endpoint
+  - [x] Created `src/homebridge-ui/endpoints/config.ts` - Config management endpoint
+  - [x] Created `src/homebridge-ui/endpoints/devices.ts` - Device CRUD operations
+  - [x] Created `src/homebridge-ui/endpoints/credentials.ts` - Credentials endpoint
+  - [x] Created `src/homebridge-ui/utils/config-parser.ts` - Config parsing helpers
+  - [x] Created `src/homebridge-ui/utils/logger.ts` - Logging utility
+  - [x] Updated `src/homebridge-ui/server.ts` - Main entry point (imports and registers endpoints)
+
+  **Status:** Server endpoints are fully modularized and organized by concern.
+
+---
+
+## Bug Fixes
+
+### Matter Window Covering Conformance ✅ COMPLETED
+
+- [x] **Fix Matter window covering Drapery enum validation error**
+  - [x] **Issue:** Matter accessory registration failed for Curtain devices
+  - [x] **Error:** `Conformance "LF & !TL": Matter does not allow enum value Drapery (ID 4) here`
+  - [x] **Related Runtime Failure:** `[Matter/Server] Failed to register Matter accessory ... [endpoint-behaviors] Behaviors have errors` with rollback from Matter transaction initialization
+  - [x] **Root Cause:** `windowCovering.type` used `Drapery` for lift-only curtain mappings
+  - [x] **Fix:** Updated curtain Matter default to a compliant lift-only covering enum and added regression coverage
+
+  **Status:** Curtain-type Matter accessories now register without the Drapery conformance failure.
+
+### Invalid Device Type Validation ✅ COMPLETED
+
+- [x] **Fix invalid device type in config schema validation**
+  - [x] **Issue:** Config validation rejects devices with invalid `configDeviceType` values (e.g., "Lock Vision Pro" is not in valid enum)
+  - [x] **Error:** "Value is not accepted. Valid values: ..." error shown in Homebridge UI
+  - [x] **Root Cause:** Device types in existing configs may not match current DEVICE_TYPES enum (legacy names, typos, or renamed devices)
+  - [x] **Affected Devices:** Any device with `configDeviceType` not matching DEVICE_TYPES enum
+  - [x] **Solution:** Implemented device type validation migration and auto-correction
+
+  **Implementation:**
+  - Added `normalizeDeviceType()` — Validates and maps invalid types to valid equivalents
+  - Added `isValidDeviceType()` — Checks if device type is in DEVICE_TYPES enum
+  - Added `getValidDeviceTypes()` — Returns set of all valid device types
+  - Created `src/homebridge-ui/utils/device-migration.ts` — Migration utilities for batch validation
+  - Updated `src/homebridge-ui/endpoints/config.ts` — Device loading now validates types and warns about invalid ones
+  - Added migration mapping: `"Lock Vision Pro"` → `"Keypad Vision Pro"` (and others)
+  - Config endpoint returns `validationWarnings` with invalid device types and suggestions
+
+  **Status:** Device type validation is now automatic. Invalid types are detected and suggestions provided to users. Auto-correction mappings handle legacy/typo device names.
+
+---
+
+### Client-Side Refactoring
+
+#### Phase 1: Quick Wins
+
+##### Extract DEVICE_TYPES constant ✅ COMPLETED
+
+- [x] Created `src/device-types.ts` as single source of truth
+- [x] Updated `src/homebridge-ui/public/js/constants.ts` to import from shared source
+- [x] Added `DEVICE_TYPE_NORMALIZATION_MAP` for plugin type lookups
+- [x] Updated `src/deviceFactory.ts` to use normalized type mappings
+- [x] Created `scripts/sync-device-types.mjs` to auto-sync config.schema.json
+- [x] Integrated sync into build process (runs before tsc)
+
+**Status:** Device types now single-sourced with auto-sync. Config schema, UI dropdown, and plugin type handling all stay aligned automatically.
+
+##### Extract CSS styles ✅ COMPLETED
+
+![Modal Theme Mockup](mockups/modal-switchbot-theme.svg)
+
+- [x] Created `src/homebridge-ui/public/css/styles.css`
+- [x] Moved all inline styles from `src/homebridge-ui/public/index.html` (2.3kb)
+- [x] Updated HTML to `<link rel="stylesheet" href="css/styles.css">`
+- [x] Verified build copies CSS to dist/
+- [x] Tested in browser to confirm styles still work
+- [x] Added SwitchBot red color variables and theme
+- [x] Enhanced modal styling with red accent borders
+- [x] Improved button styling with hover animations
+
+**Status:** CSS now externalized and properly linked. Build copies files correctly to dist/. Modal uses SwitchBot red theme with Homebridge-like appearance.
+
+#### Phase 2: JavaScript Modularization ✅ COMPLETED
+
+- [x] Created `src/homebridge-ui/public/js/api.ts` - API client functions
+- [x] Created `src/homebridge-ui/public/js/discovery.ts` - Discovery UI rendering
+- [x] Created `src/homebridge-ui/public/js/modals.ts` - Modal management
+- [x] Created `src/homebridge-ui/public/js/credentials.ts` - Credentials UI
+- [x] Created `src/homebridge-ui/public/js/toast.ts` & `modal.ts` - UI helpers
+- [x] Created `src/homebridge-ui/public/js/app.ts` - Main app init
+- [x] Updated `src/homebridge-ui/public/index.html` to use bundled app.js
+
+**Status:** UI is modularized in TypeScript. Build bundles into app.js (47.0kb). Direct TypeScript imports provide type safety.
+
+---
+
+## Discovery System Enhancements
+
+### Signal Strength Visualization ✅ COMPLETED
+
+![Signal Strength Mockup](mockups/signal-strength-visualization.svg)
+
+- [x] Implement RSSI color-coding system:
+  - [x] Green: > -60 dBm (excellent)
+  - [x] Yellow: -60 to -75 dBm (good)
+  - [x] Orange: -75 to -85 dBm (fair)
+  - [x] Red: < -85 dBm (poor/unreliable)
+- [x] Add signal strength bars visual indicator (4-bar system)
+- [x] Add tooltip explaining signal quality
+
+**Implementation:**
+- Added `getRssiSignalQuality()` — Determines RSSI level, color, description, and bar count
+- Added `renderSignalBars()` — Visual 4-bar indicator (filled based on signal strength)
+- Added `renderSignalQualityBadge()` — Color-coded badge showing quality level (Excellent/Good/Fair/Poor)
+- Updated `renderDiscoveredDevices()` — Displays bars and badges next to device names for BLE/wireless devices
+- Tooltips show detailed signal info on hover
+
+**Status:** Signal visualization now displays for all discovered devices with RSSI data. Color-coded bars and badges provide instant visual feedback about connection quality.
+
+### Filtering & Sorting ✅ COMPLETED
+
+![Filtering & Sorting Mockup](mockups/filtering-sorting.svg)
+
+- [x] Add filter buttons: "All | BLE Only | API Only | Both | IR Devices"
+- [x] Add sort dropdown: "Signal Strength | Name | Type | Connection"
+- [x] Add search box to filter by name/ID/type (real-time filtering)
+- [x] Persist filter/sort preferences in localStorage
+
+**Implementation:**
+- Added `filterDevices()` — Filters by connection type (BLE/API/Both/IR) and search query (matches name/id/type/model)
+- Added `sortDevices()` — Sorts by name (alphabetical), signal strength (RSSI descending), device type, or connection type
+- Added `getDiscoveryPreferences()` & `setDiscoveryPreferences()` — Persist user preferences in localStorage
+- Updated `discovery.ts` — Creates filter buttons, sort dropdown, and search input dynamically
+- All filtering/sorting is client-side (instant, no API calls)
+- Search is debounced (300ms) for smooth typing
+- Filter buttons highlight active selection
+- Status shows "Showing X of Y device(s)" when filtered
+
+**Status:** Full filtering and sorting implemented with localStorage persistence. Discovery page now shows:
+- Filter bar with 5 buttons (All/BLE/API/Both/IR)
+- Sort dropdown with 4 options (Name/Signal Strength/Type/Connection)
+- Real-time search box
+- All preferences saved and restored on next discovery
+
+### One-Click Device Import ✅ COMPLETED
+
+- [x] Added "Add to Config" button for each discovered device
+- [x] Added auto-populated import modal with discovered name/type defaults
+- [x] Added BLE MAC pre-fill in import flow and persistence to config on single add
+- [x] Added confirmation toast/status messaging on successful import
+
+**Implementation:**
+- Updated discovery row action in `render.ts` to use explicit "Add to Config" CTA
+- Added `importDiscoveredDevice()` modal in `modals.ts` for prefilled import settings
+- Extended single-add client payload in `api.ts` to include optional `address`, `model`, and `rssi`
+- Extended `/add-device` endpoint in `devices.ts` to persist discovered metadata (MAC/model/RSSI)
+
+**Status:** One-click import now supports prefilled configuration and BLE MAC carry-through for direct connection setup.
+
+### Duplicate Detection ✅ COMPLETED
+
+- [x] Check if discovered device ID already exists in config
+- [x] Show badge: "✓ Already Added" (green) or "➕ New Device" (blue)
+- [x] Disable/hide "Add" button for already-added devices
+- [x] Add "View in Config" link for existing devices
+
+**Implementation:**
+- Discovery view now fetches configured device IDs and tags discovered rows as existing/new
+- Existing devices show `Already Added` state with disabled add action
+- Existing devices include a `View in Config` action that scrolls and highlights the configured entry
+
+**Status:** Duplicate devices are clearly identified at discovery time, preventing accidental re-adds and improving navigation to existing config entries.
+
+---
+
+## Bug Fixes & Technical Debt
+
+### Fix Discovery Not Showing Devices ✅ COMPLETED
+
+- [x] **Issue:** No devices appear in discovery results after clicking "Discover Devices"
+- [x] **Root Cause:** Discovery UI cleared the `#discoveredList` div (including the `<ul id="discoveredDevices">` element), but then tried to replace a non-existent element when rendering discovered devices
+- [x] **Effect:** `document.getElementById('discoveredDevices')?.replaceWith(ul)` silently failed due to optional chaining, leaving the list empty
+
+**Implementation:**
+- Modified `discoverDevices()` in `discovery.ts` to create a new `<ul id="discoveredDevices">` container if it doesn't exist after clearing controls
+- Updated `updateDiscoveryView()` to check if the element exists before using `replaceWith()`, with fallback to append if element is missing
+- Added proper element lifecycle management for discovery list rendering
+
+**Status:** Discovery now properly displays all discovered devices. Devices appear correctly with filters, sorting, and duplicate detection badges.
+
+### Fix lint & lint:fix scripts ✅ COMPLETED
+
+- [x] Update ESLint configuration to include `src/homebridge-ui/**/*.ts` files
+- [x] Add HTML linting for `src/homebridge-ui/**/*.html` files
+- [x] Installed `eslint-plugin-html` for inline JavaScript in HTML
+- [x] Update `npm run lint` script to lint both plugin and UI code
+- [x] Update `npm run lint:fix` script to auto-fix both plugin and UI code
+- [x] Fixed existing ESLint errors (regex patterns, multi-statement lines)
+- [x] Lint now passes successfully
+- [x] Test that `npm run lint` runs successfully without errors
+
+**Changes Made:**
+- Installed `eslint-plugin-html` package
+- Updated `eslint.config.js` to import and configure HTML plugin
+- Added `html: true` to formatters in ESLint config
+- Updated package.json scripts: `lint` and `lint:fix` now include `src/homebridge-ui/**/*.html`
+- Moved regex patterns to module scope in `server.ts` and `genericDevice.ts`
+- Split multi-statement lines to comply with `style/max-statements-per-line` rule
+- All lint errors fixed - `npm run lint` passes with 0 errors
+
+### Fix TypeScript compilation errors in discovery endpoint ✅ COMPLETED
+
+- [x] Fixed: Changed `discover({ duration: 5000 })` to `discover({ timeout: 5000 })`
+- [x] Fixed: Changed `switchbot.getDevices()` to use `switchbot.getAPIClient()?.getDevices()`
+- [x] Reviewed node-switchbot v4.0.0-beta.3 API documentation and type definitions
+- [x] Updated discovery implementation to use correct API types (APIDevice, APIInfraredRemote)
+- [x] Fixed property names: `deviceId`, `deviceName`, `deviceType`, `remoteType`
+- [x] Removed references to non-existent properties (`id`, `name`, `type`, `model`, `deviceModel`)
+
+**Changes Made:**
+- Updated BLE discovery to use `timeout` parameter instead of `duration`
+- Changed OpenAPI access to use `switchbot.getAPIClient()?.getDevices()`
+- Simplified response parsing: `apiData.deviceList` and `apiData.infraredRemoteList` (no `body` wrapper)
+- Fixed all property accesses to match APIDevice and APIInfraredRemote interfaces
+- Build now succeeds with 0 TypeScript errors
+- All 39 tests still pass
+
+---
+
+## Notes
+
+- All completed features have been tested and verified working
+- Bundle size increased from 35.8kb → 47.0kb with new features
+- Zero TypeScript compilation errors
+- All lint checks passing
+- UI mockups available in `todo/mockups/` directory

package/todo/README.md

@@ -0,0 +1,59 @@
+# TODO Documentation
+
+This directory contains all task tracking and planning documentation for the SwitchBot Homebridge Plugin.
+
+## Structure
+
+```
+todo/
+├── README.md           # This file
+├── TODO.md            # Active tasks and upcoming features
+├── COMPLETED.md       # Completed features and improvements
+└── mockups/           # UI design mockups
+    ├── signal-strength-visualization.svg
+    ├── filtering-sorting.svg
+    └── modal-switchbot-theme.svg
+```
+
+## Files
+
+### [TODO.md](TODO.md)
+Active tasks and features planned for future releases. Organized by priority:
+- **Must Do (Next Release)** - Critical features blocking next release
+- **Should Do (Soon)** - Important features for near-term releases
+- **Nice to Have (Future)** - Enhancement ideas for future consideration
+
+### [COMPLETED.md](COMPLETED.md)
+Archive of completed features and bug fixes. Each completed item includes:
+- Implementation details
+- Date completed
+- Links to related code/files
+- UI mockups (if applicable)
+
+### [mockups/](mockups/)
+SVG mockups showing UI designs for completed and planned features:
+- **signal-strength-visualization.svg** - RSSI bars and quality badges for BLE devices
+- **filtering-sorting.svg** - Discovery page filters, sort options, and search
+- **modal-switchbot-theme.svg** - Edit device modal with SwitchBot red theme
+
+## Workflow
+
+1. **Planning** - New features start as unchecked items in TODO.md
+2. **Development** - Mark items as in-progress while working
+3. **Completion** - When complete, move entire section to COMPLETED.md with implementation details
+4. **UI Features** - Create SVG mockup before or after implementation for documentation
+
+## Priority Levels
+
+- **Priority: Critical** - Bugs affecting functionality or compatibility
+- **Priority: High** - Features needed for next release
+- **Priority: Medium** - Quality of life improvements
+- **Priority: Low** - Nice-to-have enhancements
+
+## Notes
+
+- Always update COMPLETED.md when marking features as done
+- Include implementation details and learnings
+- Create mockups for all UI features
+- Keep TODO.md focused on active/upcoming work
+- Archive helps track project progress over time