ultimatedarktower 2.3.0 → 3.0.0

package/CHANGELOG.md

@@ -6,109 +6,163 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ## [Unreleased]
 
+## [3.0.0] - 2026-03-24
+
+### Changed
+
+- **`onBatteryLevelNotify` now fires on every battery response** — The callback is no longer gated by battery logging settings, ensuring internal battery state and UI indicators always stay current regardless of log configuration.
+- **Renamed battery notification properties to battery logging properties** — `batteryNotifyEnabled` → `batteryLogEnabled`, `batteryNotifyFrequency` → `batteryLogFrequency`, `batteryNotifyOnValueChangeOnly` → `batteryLogOnChangeOnly`. The new names clarify that these properties control the library's internal log output, not the `onBatteryLevelNotify` callback.
+- **`lights()` now sends a single command instead of per-light commands** — Previously sent individual `setLEDStateful` commands for each light (up to 24 commands), which could overflow the tower's buffer. Now accumulates all light changes into one state packet sent as a single command.
+
+### Fixed
+
+- **Battery indicator not updating when battery logging set to NONE** — The Tower Status battery display now always updates regardless of the battery logging setting.
+- **Battery `[RCVD]` log lines ignoring "Changes" filter** — The generic `[UDT][BLE][RCVD] BATTERY_READING` log line was not respecting `batteryLogOnChangeOnly`. Battery responses now skip the generic RCVD log and are logged exclusively by the dedicated battery logging block, which correctly respects all three logging properties.
+- **Ledge and base light effects not looping** — Effects like "breathe" played once and faded away on ledge and base lights because their `loop` flag was hardcoded to `false`. All light types now set `loop` based on whether the effect is active (`effect !== LIGHT_EFFECTS.off`), matching the behaviour of `allLightsOn()`.
+
+### Added
+
+- **Battery logging properties documented in API_REFERENCE.md** — `batteryLogEnabled`, `batteryLogFrequency`, and `batteryLogOnChangeOnly` are now documented with descriptions, types, defaults, and usage examples.
+
+## [2.5.0] - 2026-03-23
+
+### Added
+
+- **`markSealBroken()` method** — Marks a seal as broken in software tracking without sending hardware commands. Enables restoring game state (e.g., resuming a saved game).
+- **`markSealRestored()` method** — Marks a seal as unbroken in software tracking without sending hardware commands. Enables undoing a seal break or restoring individual seals.
+- **`brokenSeals` config option** — Accepts an array of `SealIdentifier` in `UltimateDarkTowerConfig` to initialize seal state at construction time.
+
+### Changed
+
+- **Improved seal management documentation** — API_REFERENCE.md now explains that seals are physical plastic covers on the tower (12 total), that seal state is tracked purely in software (not by firmware), and documents all new seal state management APIs.
+
+## [2.4.0] - 2026-03-19
+
+### Changed
+
+- **Migrated project baseline to Node.js 18+** — Updated `engines.node` to `>=18.0.0`, aligned CI matrix validation to Node 18 and 20, and refreshed contributing guidance to reflect active runtime support.
+
+### Fixed
+
+- **Cleared development-tooling security advisories without permanent overrides** — Upgraded direct dev dependencies (`ts-jest`, `@typescript-eslint/parser`, `@typescript-eslint/eslint-plugin`, and `esbuild`) so the lockfile now resolves patched transitive versions for `minimatch`, `ajv`, `js-yaml`, and `flatted` without retaining temporary npm `overrides`. Full `npm audit` now reports zero vulnerabilities while preserving the existing Jest, ESLint, and build configuration.
+- **Stabilised `ts-jest` coverage resolution after dependency cleanup** — Added an explicit `jest-util` devDependency so `ts-jest` can resolve its runtime helper consistently during Jest coverage runs.
+- **Adjusted BLE device-info fallback for newer lint rules** — Removed an unused catch binding in `readDeviceInformation()` so the code remains compatible with the stricter `@typescript-eslint` rules introduced by the dependency upgrades.
+- **Started staged modernization dependency refresh** — Updated core dev tooling to current non-breaking lines (`typescript` to `^5.9.3`, `prettier` to `3.8.1`, `@types/node` to `^24.12.0`, `@types/jest` to `^30.0.0`, and `@stoprocent/noble` to `^2.3.17`) and revalidated with full CI and `npm audit`.
+- **Consolidated duplicate ESLint configuration files** — Unified lint configuration into `.eslintrc.js` and removed `.eslintrc.json` to reduce rule drift and prepare cleanly for future ESLint major migration work.
+- **Updated Node matrix CI for active support policy** — CI matrix now validates Node 18 and 20 only, matching the new runtime baseline.
+- **Added ESLint flat-config preview path for staged migration** — Added `eslint.config.mjs` and preview scripts (`lint:flat:preview`) so ESLint 9 compatibility can be tested incrementally while the current CI lint path remains unchanged.
+- **Achieved ESLint rule parity between legacy and flat-config paths** — Updated `eslint.config.mjs` to include `js.configs.recommended` (base ESLint rules) and explicitly disable `no-unused-vars` in favour of `@typescript-eslint/no-unused-vars` with argument patterns, ensuring both `npm run lint` and `npm run lint:flat:preview` produce identical output (86 warnings). Both lint paths now feature full parity for future seamless migration to ESLint 9.
+- **Upgraded Jest toolchain toward current major** — Upgraded `jest` and `jest-util` to the 30.x line and aligned Jest type definitions to `@types/jest` 30.x while keeping `ts-jest` on latest available stable 29.x until a compatible 30.x release is published.
+
+## [2.3.1] - 2026-03-09
+
+### Added
+
+- **Troubleshooting modal in TowerController example** — A "Troubleshooting" button now appears in the TowerController web app button bar. Clicking it opens a modal overlay displaying the full Restoration Games troubleshooting guide (tower jams, disconnects, firmware errors 133/257, and battery specifications). The modal can be dismissed via the close button, clicking the backdrop, or pressing Escape. The button is visually de-emphasised (reduced opacity, smaller text, extra left margin) to indicate it is secondary to Connect/Disconnect/Calibrate.
+
 ## [2.3.0] - 2026-02-23
 
 ### Added
 
--   **`allLightsOn(effect?)` and `allLightsOff()` convenience methods** — Turns all 24 tower LEDs on or off with a single command packet. `allLightsOn` accepts an optional `effect` parameter (default: `LIGHT_EFFECTS.on`); `allLightsOff` is a convenience wrapper around `allLightsOn(LIGHT_EFFECTS.off)`. Both preserve existing drum, beam, and audio state.
+- **`allLightsOn(effect?)` and `allLightsOff()` convenience methods** — Turns all 24 tower LEDs on or off with a single command packet. `allLightsOn` accepts an optional `effect` parameter (default: `LIGHT_EFFECTS.on`); `allLightsOff` is a convenience wrapper around `allLightsOn(LIGHT_EFFECTS.off)`. Both preserve existing drum, beam, and audio state.
 
 ### Changed
 
--   **Public audio volume API now clamps inputs to 0–3** — The `volume` parameter accepted by `playSoundStateful`, `breakSeal`, and related methods is now clamped to the range 0–3 (0=loudest, 1=medium, 2=quiet, 3=softest/mute) before being sent to the tower. The tower's 4-bit device field accepts 0–15, but the firmware only defines behaviour for 0–3; out-of-range inputs now silently clamp rather than producing undefined tower behaviour. If you were passing values outside 0–3, update them to the equivalent in-range value.
+- **Public audio volume API now clamps inputs to 0–3** — The `volume` parameter accepted by `playSoundStateful`, `breakSeal`, and related methods is now clamped to the range 0–3 (0=loudest, 1=medium, 2=quiet, 3=softest/mute) before being sent to the tower. The tower's 4-bit device field accepts 0–15, but the firmware only defines behaviour for 0–3; out-of-range inputs now silently clamp rather than producing undefined tower behaviour. If you were passing values outside 0–3, update them to the equivalent in-range value.
 
 ## [2.2.0] - 2026-02-20
 
 ### Fixed
 
--   **`setLEDStateful` stale-state accumulation** — `setLEDStateful` never called `setTowerState`, so `onTowerStateUpdate` callbacks were never fired for LED changes and any code calling it in a loop (including `lights()`) risked reading stale state if `this.currentTowerState` was replaced between iterations. State is now updated explicitly before the command is sent.
--   **`cleanup()` reconnect hazard** — `cleanup()` called `disconnect()` which fired `onTowerDisconnect`, meaning a reconnect-on-disconnect handler could call `connect()` on an instance mid-teardown. `isDisposed` is now set before any disconnect logic runs so the callback cannot re-enter `connect()`.
--   **`cleanup()` not idempotent** — Calling `cleanup()` more than once would re-run the full teardown sequence. It now returns early if the instance is already disposed.
--   **`MockBluetoothAdapter.cleanup()` leaving callbacks registered** — The mock adapter's `cleanup()` now clears all three event callbacks, matching the behaviour of `NodeBluetoothAdapter`.
+- **`setLEDStateful` stale-state accumulation** — `setLEDStateful` never called `setTowerState`, so `onTowerStateUpdate` callbacks were never fired for LED changes and any code calling it in a loop (including `lights()`) risked reading stale state if `this.currentTowerState` was replaced between iterations. State is now updated explicitly before the command is sent.
+- **`cleanup()` reconnect hazard** — `cleanup()` called `disconnect()` which fired `onTowerDisconnect`, meaning a reconnect-on-disconnect handler could call `connect()` on an instance mid-teardown. `isDisposed` is now set before any disconnect logic runs so the callback cannot re-enter `connect()`.
+- **`cleanup()` not idempotent** — Calling `cleanup()` more than once would re-run the full teardown sequence. It now returns early if the instance is already disposed.
+- **`MockBluetoothAdapter.cleanup()` leaving callbacks registered** — The mock adapter's `cleanup()` now clears all three event callbacks, matching the behaviour of `NodeBluetoothAdapter`.
 
 ### Changed
 
--   **`connect()` throws after disposal** — Calling `connect()` on a `UdtBleConnection` instance after `cleanup()` now throws `Error: UdtBleConnection instance has been disposed and cannot reconnect`. Use `disconnect()` for reversible disconnection.
+- **`connect()` throws after disposal** — Calling `connect()` on a `UdtBleConnection` instance after `cleanup()` now throws `Error: UdtBleConnection instance has been disposed and cannot reconnect`. Use `disconnect()` for reversible disconnection.
 
 ## [2.1.3] - 2026-02-19
 
 ### Fixed
 
--   **`@stoprocent/noble` not loading in ESM build** — In Node.js ESM contexts, `require` is not defined, causing esbuild's `__require` shim to silently fail and leave `noble` as `undefined`. The ESM bundle now injects `import{createRequire}from'module';const require=createRequire(import.meta.url);` as a banner so `@stoprocent/noble` loads correctly via CJS `require` within the ESM module.
+- **`@stoprocent/noble` not loading in ESM build** — In Node.js ESM contexts, `require` is not defined, causing esbuild's `__require` shim to silently fail and leave `noble` as `undefined`. The ESM bundle now injects `import{createRequire}from'module';const require=createRequire(import.meta.url);` as a banner so `@stoprocent/noble` loads correctly via CJS `require` within the ESM module.
 
 ## [2.1.2] - 2026-02-19
 
 ### Fixed
 
--   **ESM named imports broken** — `import { UltimateDarkTower } from 'ultimatedarktower'` previously threw `SyntaxError: The requested module does not provide an export named 'UltimateDarkTower'` in Node.js ESM projects because the `"import"` export condition pointed to the CommonJS build. The package now ships a true ES Module bundle so named imports work correctly.
+- **ESM named imports broken** — `import { UltimateDarkTower } from 'ultimatedarktower'` previously threw `SyntaxError: The requested module does not provide an export named 'UltimateDarkTower'` in Node.js ESM projects because the `"import"` export condition pointed to the CommonJS build. The package now ships a true ES Module bundle so named imports work correctly.
 
 ### Added
 
--   **ESM build** (`dist/esm/index.mjs`) — a native ES Module bundle produced by esbuild, included in the published package alongside the existing CommonJS build
+- **ESM build** (`dist/esm/index.mjs`) — a native ES Module bundle produced by esbuild, included in the published package alongside the existing CommonJS build
 
 ### Changed
 
--   `package.json` `exports["import"]` condition now points to `dist/esm/index.mjs` instead of the CommonJS output; `exports["require"]` is unchanged
--   `package.json` `files` now includes `dist/esm/**/*`
+- `package.json` `exports["import"]` condition now points to `dist/esm/index.mjs` instead of the CommonJS output; `exports["require"]` is unchanged
+- `package.json` `files` now includes `dist/esm/**/*`
 
 ## [2.1.1] - 2026-02-19
 
 ### Added
 
--   Integration test for tower calibration using Node.js Bluetooth adapter, located in `tests/integration/calibration.integration.ts`
--   `npm run test:integration` script to run integration tests requiring real hardware
--   Integration tests are now organized under `tests/integration/` and are not run by default with unit tests or during publish
+- Integration test for tower calibration using Node.js Bluetooth adapter, located in `tests/integration/calibration.integration.ts`
+- `npm run test:integration` script to run integration tests requiring real hardware
+- Integration tests are now organized under `tests/integration/` and are not run by default with unit tests or during publish
 
 ## [2.1.0] - 2026-02-19
 
 ### Added
 
--   **Public Tower State Types** — Exported `TowerState`, `Light`, `Layer`, `Drum`, `Audio`, and `Beam` type interfaces for direct tower state manipulation
--   **Tower State Utilities** — Exported `rtdt_unpack_state`, `rtdt_pack_state`, `isCalibrated`, and `createDefaultTowerState` for converting between `TowerState` objects and binary tower data
--   **Differential Readings** — Exported `parseDifferentialReadings` function and `ParsedDifferentialReadings` type for parsing tower sensor data
--   **`TowerResponseConfig` Type** — Exported interface for controlling which tower responses are logged via `logTowerResponseConfig`
+- **Public Tower State Types** — Exported `TowerState`, `Light`, `Layer`, `Drum`, `Audio`, and `Beam` type interfaces for direct tower state manipulation
+- **Tower State Utilities** — Exported `rtdt_unpack_state`, `rtdt_pack_state`, `isCalibrated`, and `createDefaultTowerState` for converting between `TowerState` objects and binary tower data
+- **Differential Readings** — Exported `parseDifferentialReadings` function and `ParsedDifferentialReadings` type for parsing tower sensor data
+- **`TowerResponseConfig` Type** — Exported interface for controlling which tower responses are logged via `logTowerResponseConfig`
 
 ### Changed
 
--   **`TowerResponseConfig`** — Moved from private interface in `UltimateDarkTower.ts` to exported interface in `udtTowerResponse.ts`
--   **`shouldLogResponse`** — Updated parameter type from `any` to `TowerResponseConfig` for type safety
--   **Controller Example** — Updated imports to use the package index instead of internal module paths
+- **`TowerResponseConfig`** — Moved from private interface in `UltimateDarkTower.ts` to exported interface in `udtTowerResponse.ts`
+- **`shouldLogResponse`** — Updated parameter type from `any` to `TowerResponseConfig` for type safety
+- **Controller Example** — Updated imports to use the package index instead of internal module paths
 
 ## [2.0.0] - 2025-02-18
 
 ### Added
 
--   **Node.js Support** — `NodeBluetoothAdapter` using `@stoprocent/noble` for BLE communication in Node.js environments (macOS, Linux, Windows)
--   **Platform Auto-Detection** — `BluetoothAdapterFactory` automatically selects the correct adapter based on the runtime environment (browser vs Node.js vs Electron)
--   **`BluetoothPlatform` Enum** — Explicit platform selection via `BluetoothPlatform.WEB`, `BluetoothPlatform.NODE`, or `BluetoothPlatform.AUTO`
--   **`IBluetoothAdapter` Interface** — Public adapter interface for implementing custom Bluetooth adapters (React Native, Cordova, etc.)
--   **Platform-Agnostic Error Types** — `BluetoothConnectionError`, `BluetoothDeviceNotFoundError`, `BluetoothNotAvailableError`, `BluetoothCharacteristicError`, `BluetoothAdapterError` for consistent error handling across platforms
--   **Node.js CLI Example** — Interactive command-line example application (`examples/node/`)
--   **Adapter Layer Tests** — Unit tests for `NodeBluetoothAdapter`, `WebBluetoothAdapter`, `BluetoothAdapterFactory`, `UdtBleConnection`, and error types
+- **Node.js Support** — `NodeBluetoothAdapter` using `@stoprocent/noble` for BLE communication in Node.js environments (macOS, Linux, Windows)
+- **Platform Auto-Detection** — `BluetoothAdapterFactory` automatically selects the correct adapter based on the runtime environment (browser vs Node.js vs Electron)
+- **`BluetoothPlatform` Enum** — Explicit platform selection via `BluetoothPlatform.WEB`, `BluetoothPlatform.NODE`, or `BluetoothPlatform.AUTO`
+- **`IBluetoothAdapter` Interface** — Public adapter interface for implementing custom Bluetooth adapters (React Native, Cordova, etc.)
+- **Platform-Agnostic Error Types** — `BluetoothConnectionError`, `BluetoothDeviceNotFoundError`, `BluetoothNotAvailableError`, `BluetoothCharacteristicError`, `BluetoothAdapterError` for consistent error handling across platforms
+- **Node.js CLI Example** — Interactive command-line example application (`examples/node/`)
+- **Adapter Layer Tests** — Unit tests for `NodeBluetoothAdapter`, `WebBluetoothAdapter`, `BluetoothAdapterFactory`, `UdtBleConnection`, and error types
 
 ### Changed
 
--   **`udtBleConnection`** — Refactored to use `IBluetoothAdapter` interface instead of direct Web Bluetooth API calls, enabling multi-platform support
--   **`UltimateDarkTower` Constructor** — Now accepts `UltimateDarkTowerConfig` with optional `platform` or `adapter` properties for platform selection
--   **Peer Dependency** — Updated `@stoprocent/noble` peer dependency from `^1.15.0` to `^2.0.0`
+- **`udtBleConnection`** — Refactored to use `IBluetoothAdapter` interface instead of direct Web Bluetooth API calls, enabling multi-platform support
+- **`UltimateDarkTower` Constructor** — Now accepts `UltimateDarkTowerConfig` with optional `platform` or `adapter` properties for platform selection
+- **Peer Dependency** — Updated `@stoprocent/noble` peer dependency from `^1.15.0` to `^2.0.0`
 
 ## [1.0.0] - 2025-08-18
 
 ### Added
 
--   Initial release
--   Web Bluetooth support for Chrome, Edge, and Samsung Internet
--   Tower control API (lights, sounds, drum rotation)
--   Glyph position tracking with automatic updates on drum rotation
--   Seal management for game mechanics
--   Tower state management and validation
--   Multi-layered disconnect detection (heartbeat, GATT events, command timeout)
--   Callback-based event system for tower events
--   Comprehensive logging system with multiple outputs
--   Battery monitoring with low battery warnings
--   TypeScript definitions and type safety
--   Tower Controller example web app
--   Tower Game ("The Tower's Challenge") example web app
--   Complete API reference documentation
+- Initial release
+- Web Bluetooth support for Chrome, Edge, and Samsung Internet
+- Tower control API (lights, sounds, drum rotation)
+- Glyph position tracking with automatic updates on drum rotation
+- Seal management for game mechanics
+- Tower state management and validation
+- Multi-layered disconnect detection (heartbeat, GATT events, command timeout)
+- Callback-based event system for tower events
+- Comprehensive logging system with multiple outputs
+- Battery monitoring with low battery warnings
+- TypeScript definitions and type safety
+- Tower Controller example web app
+- Tower Game ("The Tower's Challenge") example web app
+- Complete API reference documentation
 
 [2.3.0]: https://github.com/ChessMess/UltimateDarkTower/compare/v2.2.0...v2.3.0
 [2.2.0]: https://github.com/ChessMess/UltimateDarkTower/compare/v2.1.3...v2.2.0

package/README.md

@@ -12,51 +12,51 @@ I have spent many hours reverse engineering the Tower's protocol in order to cre
 
 ## Table of Contents
 
--   [UltimateDarkTower](#ultimatedarktower)
-    -   [Table of Contents](#table-of-contents)
-    -   [Features](#features)
-    -   [Live Examples](#live-examples)
-    -   [Installation](#installation)
-        -   [Browser / Web Applications](#browser--web-applications)
-        -   [Node.js Applications](#nodejs-applications)
-    -   [Quick Start](#quick-start)
-        -   [Browser (auto-detected)](#browser-auto-detected)
-        -   [Node.js (auto-detected)](#nodejs-auto-detected)
-        -   [Explicit Platform Selection](#explicit-platform-selection)
-        -   [Custom Adapter (React Native, etc.)](#custom-adapter-react-native-etc)
-    -   [Documentation](#documentation)
-        -   [📖 Complete API Reference](#-complete-api-reference)
-        -   [Key Topics Covered:](#key-topics-covered)
-    -   [Development](#development)
-        -   [Building and Testing](#building-and-testing)
-        -   [Project Structure](#project-structure)
-    -   [Platform Support](#platform-support)
-        -   [Built-in Support (auto-detected)](#built-in-support-auto-detected)
-        -   [Custom Adapter Support](#custom-adapter-support)
-        -   [Browser Support](#browser-support)
-    -   [Known Issues](#known-issues)
-    -   [Community](#community)
+- [UltimateDarkTower](#ultimatedarktower)
+    - [Table of Contents](#table-of-contents)
+    - [Features](#features)
+    - [Live Examples](#live-examples)
+    - [Installation](#installation)
+        - [Browser / Web Applications](#browser--web-applications)
+        - [Node.js Applications](#nodejs-applications)
+    - [Quick Start](#quick-start)
+        - [Browser (auto-detected)](#browser-auto-detected)
+        - [Node.js (auto-detected)](#nodejs-auto-detected)
+        - [Explicit Platform Selection](#explicit-platform-selection)
+        - [Custom Adapter (React Native, etc.)](#custom-adapter-react-native-etc)
+    - [Documentation](#documentation)
+        - [📖 Complete API Reference](#-complete-api-reference)
+        - [Key Topics Covered:](#key-topics-covered)
+    - [Development](#development)
+        - [Building and Testing](#building-and-testing)
+        - [Project Structure](#project-structure)
+    - [Platform Support](#platform-support)
+        - [Built-in Support (auto-detected)](#built-in-support-auto-detected)
+        - [Custom Adapter Support](#custom-adapter-support)
+        - [Browser Support](#browser-support)
+    - [Known Issues](#known-issues)
+    - [Community](#community)
 
 ## Features
 
--   **Multi-Platform Bluetooth** - Works in browsers (Web Bluetooth), Node.js (`@stoprocent/noble`), Electron, and React Native via custom adapters
--   **Bluetooth Connection Management** - Reliable connection with automatic monitoring and disconnect detection
--   **Tower Control** - Complete control over lights, sounds, and drum rotation
--   **Game State Tracking** - Track glyph positions, broken seals, and skull counts
--   **Event System** - Callback-based event handling for tower events
--   **ESM + CJS** - Ships both an ES Module build and a CommonJS build; works with `import` and `require` without configuration
--   **TypeScript Support** - Full TypeScript definitions and type safety
--   **Comprehensive Logging** - Multi-output logging system for debugging
--   **Battery Monitoring** - Real-time battery level tracking and low battery warnings
--   **Extensible Adapter Pattern** - Implement `IBluetoothAdapter` for custom platforms
+- **Multi-Platform Bluetooth** - Works in browsers (Web Bluetooth), Node.js (`@stoprocent/noble`), Electron, and React Native via custom adapters
+- **Bluetooth Connection Management** - Reliable connection with automatic monitoring and disconnect detection
+- **Tower Control** - Complete control over lights, sounds, and drum rotation
+- **Game State Tracking** - Track glyph positions, broken seals, and skull counts
+- **Event System** - Callback-based event handling for tower events
+- **ESM + CJS** - Ships both an ES Module build and a CommonJS build; works with `import` and `require` without configuration
+- **TypeScript Support** - Full TypeScript definitions and type safety
+- **Comprehensive Logging** - Multi-output logging system for debugging
+- **Battery Monitoring** - Real-time battery level tracking and low battery warnings
+- **Extensible Adapter Pattern** - Implement `IBluetoothAdapter` for custom platforms
 
 ## Live Examples
 
 Try the library in action! Just power on your Tower and visit:
 
--   **[Tower Controller](https://chessmess.github.io/UltimateDarkTower/dist/examples/controller/TowerController.html)** - Replicates official app functionality and gives examples of library functionality.
+- **[Tower Controller](https://chessmess.github.io/UltimateDarkTower/dist/examples/controller/TowerController.html)** - Replicates official app functionality and gives examples of library functionality.
 
--   **[Tower Game](https://chessmess.github.io/UltimateDarkTower/dist/examples/game/TowerGame.html)** - "The Tower's Challenge" - a complete game using just the tower
+- **[Tower Game](https://chessmess.github.io/UltimateDarkTower/dist/examples/game/TowerGame.html)** - "The Tower's Challenge" - a complete game using just the tower
 
 _Requires Web Bluetooth support (Chrome, Edge, Samsung Internet). For iOS, use the [Bluefy app](https://apps.apple.com/us/app/bluefy-web-ble-browser/id1492822055)._
 
@@ -119,7 +119,7 @@ import UltimateDarkTower, { IBluetoothAdapter } from 'ultimatedarktower';
 
 class MyCustomAdapter implements IBluetoothAdapter {
     // Implement all IBluetoothAdapter methods
-    // See Reference.md for the full interface
+    // See API_REFERENCE.md for the full interface
 }
 
 const tower = new UltimateDarkTower({ adapter: new MyCustomAdapter() });
@@ -127,22 +127,22 @@ const tower = new UltimateDarkTower({ adapter: new MyCustomAdapter() });
 
 ## Documentation
 
-### 📖 [Complete API Reference](Reference.md)
+### 📖 [Complete API Reference](API_REFERENCE.md)
 
 Comprehensive documentation with TypeScript examples, best practices, and troubleshooting guides.
 
 ### Key Topics Covered:
 
--   **Multi-Platform Setup** - Configuration for Web, Node.js, Electron, and React Native
--   **Connection Management** - Connecting, disconnecting, and monitoring connection health
--   **Bluetooth Adapters** - Custom adapter interface for extending platform support
--   **Tower Control** - Detailed coverage of all tower commands (lights, sounds, rotation)
--   **Glyph System** - Automatic tracking of glyph positions as towers rotate
--   **Seal Management** - Breaking seals and tracking game state
--   **Event Handling** - Callback system for tower events
--   **Logging System** - Multi-output logging for debugging and monitoring
--   **Best Practices** - Performance tips, error handling, and common patterns
--   **Troubleshooting** - Solutions for common issues and debugging techniques
+- **Multi-Platform Setup** - Configuration for Web, Node.js, Electron, and React Native
+- **Connection Management** - Connecting, disconnecting, and monitoring connection health
+- **Bluetooth Adapters** - Custom adapter interface for extending platform support
+- **Tower Control** - Detailed coverage of all tower commands (lights, sounds, rotation)
+- **Glyph System** - Automatic tracking of glyph positions as towers rotate
+- **Seal Management** - Breaking seals and tracking game state
+- **Event Handling** - Callback system for tower events
+- **Logging System** - Multi-output logging for debugging and monitoring
+- **Best Practices** - Performance tips, error handling, and common patterns
+- **Troubleshooting** - Solutions for common issues and debugging techniques
 
 ## Integration Testing
 
@@ -154,14 +154,43 @@ To run the calibration integration test:
 npm run test:integration
 ```
 
--   This will connect to the tower, perform a full calibration sequence, and print the resulting glyph positions.
--   The test will fail if the tower is not available or calibration does not complete within 60 seconds.
--   Integration tests are not included in automated test runs or npm publish.
+- This will connect to the tower, perform a full calibration sequence, and print the resulting glyph positions.
+- The test will fail if the tower is not available or calibration does not complete within 60 seconds.
+- Integration tests are not included in automated test runs or npm publish.
+
+### Lights Integration Test
+
+The lights integration test validates the `allLightsOn` and `allLightsOff` API methods using real tower hardware.
+
+**Test steps:**
+
+- Turns all 24 LEDs on (solid effect) for 2 seconds
+- Turns all 24 LEDs on (breathe effect) for 3 seconds
+- Turns all 24 LEDs off
+
+**How to run:**
+
+```bash
+npm run test:integration:lights
+```
+
+**Prerequisites:**
+
+- Tower must be powered on and in Bluetooth range
+- `@stoprocent/noble` must be installed
+
+**Visual verification:**
+
+- All lights on (solid) for 2 seconds
+- All lights breathe effect for 3 seconds
+- All lights off
+
+See [API_REFERENCE.md](API_REFERENCE.md) for API details on `allLightsOn` and `allLightsOff`.
 
 **Prerequisites:**
 
--   Tower must be powered on and in Bluetooth range
--   `@stoprocent/noble` must be installed (it is a peer dependency)
+- Tower must be powered on and in Bluetooth range
+- `@stoprocent/noble` must be installed (it is a peer dependency)
 
 ## Development
 
@@ -242,10 +271,10 @@ examples/
 
 ## Known Issues
 
--   **Sounds** - Sounds show as command complete which is true even though the sound itself has not completed. This is just the way the tower works. I'll have to add time lengths to each at some point, just don't use the command complete response as a way of thinking the associated sound has finished playing and you can play another sound.
--   **Light Sequences** - Same as sound for lights that play for a duration.
+- **Sounds** - Sounds show as command complete which is true even though the sound itself has not completed. This is just the way the tower works. I'll have to add time lengths to each at some point, just don't use the command complete response as a way of thinking the associated sound has finished playing and you can play another sound.
+- **Light Sequences** - Same as sound for lights that play for a duration.
 
-> See [Reference.md](Reference.md) for performance best practices and workarounds.
+> See [API_REFERENCE.md](API_REFERENCE.md) for performance best practices and workarounds.
 
 ## Community