ultimatedarktower 2.2.0 → 2.5.0

package/CHANGELOG.md

@@ -6,100 +6,147 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ## [Unreleased]
 
+## [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** — 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.
+
+### 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.
+
 ## [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
 [2.1.3]: https://github.com/ChessMess/UltimateDarkTower/compare/v2.1.2...v2.1.3
 [2.1.2]: https://github.com/ChessMess/UltimateDarkTower/compare/v2.1.1...v2.1.2

package/README.md

@@ -158,6 +158,35 @@ npm run test:integration
 -   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 [Reference.md](Reference.md) for API details on `allLightsOn` and `allLightsOff`.
+
 **Prerequisites:**
 
 -   Tower must be powered on and in Bluetooth range

package/dist/esm/index.mjs

@@ -6,8 +6,7 @@ var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
   get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
 }) : x)(function(x) {
-  if (typeof require !== "undefined")
-    return require.apply(this, arguments);
+  if (typeof require !== "undefined") return require.apply(this, arguments);
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 var __esm = (fn, res) => function __init() {
@@ -813,8 +812,7 @@ var init_NodeBluetoothAdapter = __esm({
         }
       }
       async disconnect() {
-        if (!this.peripheral)
-          return;
+        if (!this.peripheral) return;
         try {
           if (this.rxCharacteristic) {
             if (this.boundDataHandler) {
@@ -916,8 +914,7 @@ var init_NodeBluetoothAdapter = __esm({
                 return cUuid === normalizedUuid || cUuid === shortUuid;
               }
             );
-            if (!char)
-              continue;
+            if (!char) continue;
             try {
               const buffer = await char.readAsync();
               if (binary) {
@@ -1135,8 +1132,7 @@ var DOMOutput = class {
     this.maxLines = maxLines;
   }
   write(level, message, timestamp) {
-    if (!this.container)
-      return;
+    if (!this.container) return;
     this.allEntries.push({ level, message, timestamp });
     while (this.allEntries.length > this.maxLines) {
       this.allEntries.shift();
@@ -1144,8 +1140,7 @@ var DOMOutput = class {
     this.refreshDisplay();
   }
   refreshDisplay() {
-    if (!this.container)
-      return;
+    if (!this.container) return;
     this.container.innerHTML = "";
     const enabledLevels = this.getEnabledLevelsFromCheckboxes();
     const textFilter = this.getTextFilter();
@@ -1258,12 +1253,9 @@ var Logger = class _Logger {
     return Array.from(this.enabledLevels);
   }
   shouldLog(level) {
-    if (this.enabledLevels.has("all"))
-      return true;
-    if (level === "all")
-      return true;
-    if (this.enabledLevels.has(level))
-      return true;
+    if (this.enabledLevels.has("all")) return true;
+    if (level === "all") return true;
+    if (this.enabledLevels.has(level)) return true;
     if (this.enabledLevels.size === 1) {
       const singleLevel = Array.from(this.enabledLevels)[0];
       if (singleLevel !== "all") {
@@ -1276,8 +1268,7 @@ var Logger = class _Logger {
     return false;
   }
   log(level, message, context) {
-    if (!this.shouldLog(level))
-      return;
+    if (!this.shouldLog(level)) return;
     const contextPrefix = context ? `${context} ` : "";
     const finalMessage = `${contextPrefix}${message}`;
     const timestamp = /* @__PURE__ */ new Date();
@@ -1835,13 +1826,12 @@ var UdtBleConnection = class {
           this.logger.info(`Device ${key}: ${value}`, "[UDT][BLE]");
         }
       }
-    } catch (error) {
+    } catch {
       this.logger.debug("Device Information Service not available", "[UDT][BLE]");
     }
   }
   async cleanup() {
-    if (this.isDisposed)
-      return;
+    if (this.isDisposed) return;
     this.isDisposed = true;
     this.logger.info("Cleaning up UdtBleConnection instance", "[UDT][BLE]");
     this.stopConnectionMonitoring();
@@ -1958,7 +1948,7 @@ var UdtCommandFactory = class {
   * @param currentState - The current complete tower state
   * @param sample - Audio sample index to play (0-127)
   * @param loop - Whether to loop the audio
-  * @param volume - Audio volume (0-15), optional
+  * @param volume - Audio volume (0-3, 0=loudest, 3=softest). Public API clamps inputs to this range before reaching here.
   * @returns 20-byte command packet
   */
   createStatefulAudioCommand(currentState, sample, loop = false, volume) {
@@ -1971,10 +1961,10 @@ var UdtCommandFactory = class {
   /**
    * Creates a transient audio command that includes current tower state but doesn't persist audio state.
    * This prevents audio from being included in subsequent commands.
-   * @param currentState - The current complete tower state  
+   * @param currentState - The current complete tower state
    * @param sample - Audio sample index to play
    * @param loop - Whether to loop the audio
-   * @param volume - Audio volume (0-15), optional
+   * @param volume - Audio volume (0-3, 0=loudest, 3=softest). Public API clamps inputs to this range before reaching here.
    * @returns Object containing the command packet and the state without audio for local tracking
    */
   createTransientAudioCommand(currentState, sample, loop = false, volume) {
@@ -1988,12 +1978,12 @@ var UdtCommandFactory = class {
     return { command, stateWithoutAudio };
   }
   /**
-   * Creates a transient audio command with additional modifications that includes current tower state 
+   * Creates a transient audio command with additional modifications that includes current tower state
    * but doesn't persist audio state. This prevents audio from being included in subsequent commands.
-   * @param currentState - The current complete tower state  
+   * @param currentState - The current complete tower state
    * @param sample - Audio sample index to play
    * @param loop - Whether to loop the audio
-   * @param volume - Audio volume (0-15), optional
+   * @param volume - Audio volume (0-3, 0=loudest, 3=softest). Public API clamps inputs to this range before reaching here.
    * @param otherModifications - Other tower state modifications to include
    * @returns Object containing the command packet and the state with modifications but without audio
    */
@@ -2725,7 +2715,7 @@ var UdtTowerCommands = class {
    * Audio state is not persisted to prevent sounds from replaying on subsequent commands.
    * @param soundIndex - Index of the sound to play (1-based)
    * @param loop - Whether to loop the audio
-   * @param volume - Audio volume (0-15), optional
+   * @param volume - Audio volume (0-3, 0=loudest, 3=softest), optional. Out-of-range values are clamped.
    * @returns Promise that resolves when command is sent
    */
   async playSoundStateful(soundIndex, loop = false, volume) {
@@ -2734,10 +2724,11 @@ var UdtTowerCommands = class {
       this.deps.logger.error(`attempt to play invalid sound index ${soundIndex}`, "[UDT][CMD]");
       return;
     }
+    const clampedVolume = volume === void 0 ? void 0 : Math.min(3, Math.max(0, Math.round(volume)));
     const currentState = this.deps.getCurrentTowerState();
-    const { command } = this.deps.commandFactory.createTransientAudioCommand(currentState, soundIndex, loop, volume);
-    this.deps.logger.info(`Playing sound ${soundIndex}${loop ? " (looped)" : ""}${volume !== void 0 ? ` at volume ${volume}` : ""}`, "[UDT][CMD]");
-    await this.sendTowerCommand(command, `playSoundStateful(${soundIndex}, ${loop}${volume !== void 0 ? `, ${volume}` : ""})`);
+    const { command } = this.deps.commandFactory.createTransientAudioCommand(currentState, soundIndex, loop, clampedVolume);
+    this.deps.logger.info(`Playing sound ${soundIndex}${loop ? " (looped)" : ""}${clampedVolume !== void 0 ? ` at volume ${clampedVolume}` : ""}`, "[UDT][CMD]");
+    await this.sendTowerCommand(command, `playSoundStateful(${soundIndex}, ${loop}${clampedVolume !== void 0 ? `, ${clampedVolume}` : ""})`);
   }
   /**
    * Rotates a single drum using stateful commands that preserve existing tower state.
@@ -2835,10 +2826,15 @@ var UltimateDarkTower = class {
     this.onCalibrationComplete = () => {
     };
     this.onSkullDrop = (towerSkullCount) => {
+      void towerSkullCount;
     };
     this.onBatteryLevelNotify = (millivolts) => {
+      void millivolts;
     };
     this.onTowerStateUpdate = (newState, oldState, source) => {
+      void newState;
+      void oldState;
+      void source;
     };
     // utility
     this._logDetail = false;
@@ -2869,6 +2865,12 @@ var UltimateDarkTower = class {
     this.commandFactory = new UdtCommandFactory();
     const commandDependencies = this.createCommandDependencies();
     this.towerCommands = new UdtTowerCommands(commandDependencies);
+    if (config?.brokenSeals) {
+      for (const seal of config.brokenSeals) {
+        const sealKey = `${seal.level}-${seal.side}`;
+        this.brokenSeals.add(sealKey);
+      }
+    }
   }
   /**
    * Set up the tower response callback after all components are initialized
@@ -3107,7 +3109,7 @@ var UltimateDarkTower = class {
    * Plays a sound using stateful commands that preserve existing tower state.
    * @param soundIndex - Index of the sound to play (1-based)
    * @param loop - Whether to loop the audio
-   * @param volume - Audio volume (0-15), optional
+   * @param volume - Audio volume (0-3, 0=loudest, 3=softest), optional. Out-of-range values are clamped.
    * @returns Promise that resolves when command is sent
    */
   async playSoundStateful(soundIndex, loop = false, volume) {
@@ -3142,6 +3144,31 @@ var UltimateDarkTower = class {
     this.calculateAndUpdateGlyphPositions("bottom", oldBottomPosition, bottom);
     return result;
   }
+  /**
+   * Turns all tower LEDs on with the specified light effect, sending a single command packet.
+   * Preserves current drum, beam, and audio state while overriding all 6 layers of lights.
+   * @param effect - Light effect to apply (default: LIGHT_EFFECTS.on). Use LIGHT_EFFECTS constants for named values.
+   * @returns Promise that resolves when the command is sent
+   */
+  async allLightsOn(effect = LIGHT_EFFECTS.on) {
+    const currentState = this.getCurrentTowerState();
+    const loop = effect !== LIGHT_EFFECTS.off;
+    const newState = {
+      ...currentState,
+      layer: currentState.layer.map((layer) => ({
+        light: layer.light.map(() => ({ effect, loop }))
+      }))
+    };
+    return this.sendTowerState(newState);
+  }
+  /**
+   * Turns all tower LEDs off, sending a single command packet.
+   * Convenience wrapper around allLightsOn(LIGHT_EFFECTS.off).
+   * @returns Promise that resolves when the command is sent
+   */
+  async allLightsOff() {
+    return this.allLightsOn(LIGHT_EFFECTS.off);
+  }
   //#endregion
   //#region Tower State Management
   /**
@@ -3354,6 +3381,25 @@ var UltimateDarkTower = class {
       return { level, side };
     });
   }
+  /**
+   * Marks a seal as broken in software tracking without sending any commands to the tower.
+   * Use this to restore game state (e.g., resuming a game where seals were already broken).
+   * Unlike breakSeal(), this does NOT trigger sound or light effects on the tower.
+   * @param seal - Seal identifier to mark as broken
+   */
+  markSealBroken(seal) {
+    const sealKey = `${seal.level}-${seal.side}`;
+    this.brokenSeals.add(sealKey);
+  }
+  /**
+   * Marks a seal as unbroken in software tracking without sending any commands to the tower.
+   * Use this to undo a seal break or restore individual seals for game state management.
+   * @param seal - Seal identifier to mark as unbroken
+   */
+  markSealRestored(seal) {
+    const sealKey = `${seal.level}-${seal.side}`;
+    this.brokenSeals.delete(sealKey);
+  }
   /**
    * Resets the broken seals tracking (clears all broken seals).
    */
@@ -3502,7 +3548,7 @@ var UltimateDarkTower_default = UltimateDarkTower;
 init_udtConstants();
 init_udtBluetoothAdapter();
 init_udtTowerState();
-var src_default = UltimateDarkTower_default;
+var index_default = UltimateDarkTower_default;
 export {
   AUDIO_COMMAND_POS,
   BATTERY_STATUS_FREQUENCY,
@@ -3563,7 +3609,7 @@ export {
   VOLUME_DESCRIPTIONS,
   VOLUME_ICONS,
   createDefaultTowerState,
-  src_default as default,
+  index_default as default,
   drumPositionCmds,
   isCalibrated,
   logger,

package/dist/src/UltimateDarkTower.d.ts

@@ -14,6 +14,8 @@ export interface UltimateDarkTowerConfig {
     platform?: BluetoothPlatform;
     /** Custom Bluetooth adapter (for testing or custom platforms like React Native) */
     adapter?: IBluetoothAdapter;
+    /** Initial broken seals to restore game state (software-only, no hardware effects) */
+    brokenSeals?: SealIdentifier[];
 }
 /**
  * @title UltimateDarkTower
@@ -174,7 +176,7 @@ declare class UltimateDarkTower {
      * Plays a sound using stateful commands that preserve existing tower state.
      * @param soundIndex - Index of the sound to play (1-based)
      * @param loop - Whether to loop the audio
-     * @param volume - Audio volume (0-15), optional
+     * @param volume - Audio volume (0-3, 0=loudest, 3=softest), optional. Out-of-range values are clamped.
      * @returns Promise that resolves when command is sent
      */
     playSoundStateful(soundIndex: number, loop?: boolean, volume?: number): Promise<void>;
@@ -196,6 +198,19 @@ declare class UltimateDarkTower {
      * @returns Promise that resolves when rotate command is sent
      */
     rotateWithState(top: TowerSide, middle: TowerSide, bottom: TowerSide, soundIndex?: number): Promise<void>;
+    /**
+     * Turns all tower LEDs on with the specified light effect, sending a single command packet.
+     * Preserves current drum, beam, and audio state while overriding all 6 layers of lights.
+     * @param effect - Light effect to apply (default: LIGHT_EFFECTS.on). Use LIGHT_EFFECTS constants for named values.
+     * @returns Promise that resolves when the command is sent
+     */
+    allLightsOn(effect?: number): Promise<void>;
+    /**
+     * Turns all tower LEDs off, sending a single command packet.
+     * Convenience wrapper around allLightsOn(LIGHT_EFFECTS.off).
+     * @returns Promise that resolves when the command is sent
+     */
+    allLightsOff(): Promise<void>;
     /**
      * Gets the current complete tower state if available.
      * @returns The current tower state object
@@ -295,6 +310,19 @@ declare class UltimateDarkTower {
      * @returns Array of SealIdentifier objects representing all broken seals
      */
     getBrokenSeals(): SealIdentifier[];
+    /**
+     * Marks a seal as broken in software tracking without sending any commands to the tower.
+     * Use this to restore game state (e.g., resuming a game where seals were already broken).
+     * Unlike breakSeal(), this does NOT trigger sound or light effects on the tower.
+     * @param seal - Seal identifier to mark as broken
+     */
+    markSealBroken(seal: SealIdentifier): void;
+    /**
+     * Marks a seal as unbroken in software tracking without sending any commands to the tower.
+     * Use this to undo a seal break or restore individual seals for game state management.
+     * @param seal - Seal identifier to mark as unbroken
+     */
+    markSealRestored(seal: SealIdentifier): void;
     /**
      * Resets the broken seals tracking (clears all broken seals).
      */