ultimatedarktower 2.5.0 → 4.0.0

package/CHANGELOG.md

@@ -6,6 +6,66 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ## [Unreleased]
 
+## [4.0.0] - 2026-05-28
+
+- **Tower Emulator has been added** — Utilising the UltimateDarkTowerDisplay the example app can now connect to a software rendered version of the tower. The controller and the software tower share actual packets, so this can be a useful feature for testing certain features of both the UDT library and the UDT Display Library.
+
+### Fixed
+
+- **Eliminated all 85 `@typescript-eslint/no-explicit-any` lint warnings** — All `any` types across source and test files replaced with proper TypeScript types (`unknown`, type-narrowed catch blocks, typed mock helpers, typed cast chains). Also added a `no-undef` disable comment for the `globalThis` usage in `udtDiagnostics.ts`. Local interface declarations for the Web Bluetooth API (`BluetoothDevice`, `BluetoothRemoteGATTCharacteristic`, etc.) were added to `WebBluetoothAdapter.ts` since these types are not included in TypeScript's standard DOM lib. The codebase now reports `0 problems (0 errors, 0 warnings)` from ESLint.
+
+### Added
+
+- **Tower Controller gains a "Seals" tab for 3D emulator seal visibility** — When connected in Tower Emulator mode, a new "Seals" tab appears in the left column of the Tower Controller. It shows a labeled 3×4 grid (Top/Mid/Btm × N/E/S/W) of toggle buttons: clicking a button removes the corresponding seal from the 3D emulator view (button turns dark red); clicking again restores it. "Remove All" and "Replace All" action buttons operate on all 12 seals at once. Seal state is kept in sync with the existing Library tab seal grid on all mutation paths (`breakSeal`, Library grid clicks, "Clear All Lights"). The seal state is communicated to the emulator popup via a new `applySeals` postMessage type, which calls `TowerRenderView.applySeals()` on the display. When not in emulator+connected mode the tab shows an explanatory notice.
+
+- **BLE disconnect diagnostics ("flight recorder")** — Opt-in structured capture of BLE disconnect incidents. Each of the five disconnect detection paths is tagged with a typed `DisconnectCause` (`adapter_event`, `gatt_health_check`, `heartbeat_timeout`, `response_timeout`, `bt_unavailable`) plus `user_initiated` and browser-only `page_unload`. Captures a snapshot of `ConnectionStatus`, command queue (including in-flight command + age), tower state, broken seals, the last ~500 structured BLE events (commands sent/received, timeouts, near-miss heartbeats, log lines), and the last 60 battery readings. Pluggable `DiagnosticsSink` interface mirrors `LogOutput`; ships with `InMemorySink` and `IndexedDBSink` (browser-only, durable across page refresh). Off by default — when disabled, hot paths add a single boolean check. Configure via `new UltimateDarkTower({ diagnostics: { enabled: true, ... } })` or toggle at runtime via `tower.setDiagnosticsEnabled(true)`. Public API: `getDiagnosticsRecorder()`, `getLastIncident()`, `exportDiagnosticsJSON()`. Tower Controller example gains a "BLE Debug" tab with capture toggle, live event stream, persistent incident log, breakdown-by-cause metrics, and JSON export. See [`docs/BLE_DIAGNOSTICS.md`](docs/BLE_DIAGNOSTICS.md). Schema version 1.
+
+- **Seed parser** — New `src/udtSeedParser.ts` provides complete base-34 seed encoding and decoding, matching the game's C# `SeedParser` class. Exports `decodeSeed()`, `createSeed()`, `encodeSeed()`, `validateSeed()`, `compareSeedsRaw()`, `dumpSeedChars()`, and all related types (`DecodedSeed`, `SeedConfig`, `SeedBank`, `SeedComparison`, `CharDiff`, `CharDump`, foe/adversary/ally union types, and lookup arrays).
+
+- **C# System.Random replica** — New `src/udtSystemRandom.ts` implements a byte-exact TypeScript replica of .NET Framework's `System.Random` (modified Knuth subtractive generator). Exports the `SystemRandom` class with `next()`, `nextMax()`, `nextRange()`, and `nextDouble()` methods. Verified against C#-generated test vectors for multiple seeds including edge cases. This is the foundation for future game state prediction from seeds.
+
+- **Game board data** — New `src/udtGameBoard.ts` exports types and constants for all 60 Return to Dark Tower board locations: `TerrainType`, `BuildingType`, `BoardKingdom`, `BoardGrouping`, `BoardLocation`, `BOARD_LOCATIONS` (array), `BOARD_LOCATION_BY_NAME` (name-keyed lookup), and `BOARD_GROUPINGS` (Long Water, The Great Woods, Regal Run).
+
+- **Tower Emulator shows audio playback notifications** — When an audio command is sent while connected to the Tower Emulator, the emulator popup now briefly displays the sound name, loop state, and volume level. The notification auto-dismisses after 4 seconds. Detection is done at the adapter level by reading the audio bytes from the outgoing command packet, so all audio commands are captured regardless of which API method triggered them.
+
+### Changed
+
+- **Tower Emulator now renders a 3D tower model** — The emulator popup now uses `TowerRenderView` from `ultimatedarktowerdisplay` with the `'3d-view'` renderer, replacing the previous `TowerDisplay` default of readout text + 2D SVG side view. The existing connection-status banner and audio-event banner remain above the render, and the render view shows a "Tower Emulator" title bar.
+
+- **Tower Emulator plays LED light sequences with bound audio** — `Tower.lightOverrides(N)` (the controller's Light Override dropdown) now drives a transient LED animation on the emulator's 3D tower **and** plays the firmware-bound audio sample alongside it (mirroring real-tower behavior). Same architectural fix as the audio cut-off: the framework strips `state.led_sequence` on every response (parallel to audio), so the popup was previously seeing `SequenceAnimator.apply(0)` immediately after each light-override command and killing the sequence before any frames played. `TowerEmulatorAdapter` now exposes an `onLightSequenceCommand` callback (parallel to `onAudioCommand`); the controller posts a `playSequence` message to the popup, which calls the display package's new `playSequence(id)` transient API (UltimateDarkTowerDisplay ≥ 0.7.0). The popup enables `audio.bindSequenceToSample: true` in its `TowerRenderView` config so the bound sample fires automatically via `playSampleOneShot` inside `playSequence` — same firmware behavior the display's own example app emulates. Detection reads `data[19]` (the `led_sequence` byte) from outgoing stateful commands.
+
+- **Tower Emulator plays tower audio (full samples, no cut-off)** — The emulator popup now plays the same audio samples the real tower would, end-to-end. A "Click to enable audio" button appears on first load (required by browser autoplay policy); after clicking, all subsequent audio commands play through the popup. The popup's existing green audio-event banner continues to show sample name / loop / volume in parallel. Audio is driven via the display package's new `playSample(id, opts?)` one-shot API (requires `ultimatedarktowerdisplay` ≥ 0.6.0) — the previous synthetic-state workaround caused samples to cut off after ~100ms because the framework's audio-reset state updates triggered the display's `sync(0)` → `stop()` pipeline. The one-shot path is independent of state-driven `sync()`, so it plays to completion. Polyphony works (overlapping samples). The emulator's esbuild target was bumped from `es2017` to `es2020` and the output format from `iife` to `esm` (with a `<script type="module">` tag) so that the display package's per-file `new URL('./assets/<file>.ogg', import.meta.url)` references resolve at runtime against the bundle URL. Audio samples are copied from `UltimateDarkTowerDisplay/src/audio/assets/` to `dist/examples/controller/assets/` by `build-examples.js`.
+
+- **`breakSeal()` now uses the firmware `sealReveal` LED override** — Previously composed ledge and doorway light states manually and sent them as a `lights()` command alongside the audio command. Now sends a single `lightOverrides(TOWER_LIGHT_SEQUENCES.sealReveal, ...)` packet that triggers the firmware's built-in seal reveal animation. The tower blocks until the animation completes before acknowledging the command, so callers no longer need an explicit delay between `breakSeal()` calls.
+
+### Removed
+
+- **Old seed decoder** — Deleted `src/udtSeedDecoder.ts` and its exports (`extractBits`, `seedGroupToNumber`, `BitDiff`, `BitDump`, `DecodedField`). The old implementation used an incorrect base-36/62-bit model. All functionality is replaced by `udtSeedParser.ts` with the confirmed base-34 encoding.
+
+### Fixed
+
+- **`connect()` swallowed errors instead of propagating to callers** — `udtBleConnection.connect()` caught all errors from the Bluetooth adapter (including `BluetoothUserCancelledError`) and called `onTowerDisconnect()` instead of re-throwing. This prevented callers from detecting user cancellation or connection failures. The catch block also incorrectly fired a disconnect event for a tower that was never connected. Errors are now re-thrown after logging, and the spurious disconnect callback has been removed.
+
+- **Tower Emulator popup blocked on GitHub Pages (HTTPS)** — Moved `window.open` for the emulator display window to before the first `await` in `connectToTowerEmulator()`, ensuring it runs within the original user-gesture call stack and is not blocked by browser popup blockers on HTTPS origins.
+
+## [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
@@ -16,7 +76,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ### 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.
+- **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
 

package/README.md

@@ -10,55 +10,55 @@ A JavaScript/TypeScript library for controlling the Bluetooth-enabled tower from
 
 I have spent many hours reverse engineering the Tower's protocol in order to create this library, I look forward to what others will create using this! - Chris
 
-## 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)
+## Live Examples
 
-## Features
+Try the library in action! Just power on your Tower and visit:
 
--   **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
+- **[Tower Controller](https://chessmess.github.io/UltimateDarkTower/dist/examples/controller/TowerController.html)** - Replicates official app functionality and gives examples of library functionality.
 
-## Live Examples
+_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)._
 
-Try the library in action! Just power on your Tower and visit:
+## Table of Contents
 
--   **[Tower Controller](https://chessmess.github.io/UltimateDarkTower/dist/examples/controller/TowerController.html)** - Replicates official app functionality and gives examples of library functionality.
+- [UltimateDarkTower](#ultimatedarktower)
+    - [Live Examples](#live-examples)
+    - [Table of Contents](#table-of-contents)
+    - [Features](#features)
+    - [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)
+    - [Integration Testing](#integration-testing)
+        - [Lights Integration Test](#lights-integration-test)
+    - [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)
 
--   **[Tower Game](https://chessmess.github.io/UltimateDarkTower/dist/examples/game/TowerGame.html)** - "The Tower's Challenge" - a complete game using just the tower
+## Features
 
-_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)._
+- **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
 
 ## Installation
 
@@ -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 docs/API_REFERENCE.md for the full interface
 }
 
 const tower = new UltimateDarkTower({ adapter: new MyCustomAdapter() });
@@ -127,22 +127,32 @@ const tower = new UltimateDarkTower({ adapter: new MyCustomAdapter() });
 
 ## Documentation
 
-### 📖 [Complete API Reference](Reference.md)
+### 📖 [Complete API Reference](docs/API_REFERENCE.md)
 
 Comprehensive documentation with TypeScript examples, best practices, and troubleshooting guides.
 
+### 📄 [Seed Format Specification](docs/SEED_FORMAT.md)
+
+Complete documentation of the Return to Dark Tower game seed encoding — base-34 alphabet, setup section bitwise layout, RNG seed polynomial, and what each seed field controls.
+
+### 🛠 [BLE Diagnostics (Flight Recorder)](docs/BLE_DIAGNOSTICS.md)
+
+Opt-in diagnostic system for capturing BLE disconnect incidents. Tags each detection path, snapshots connection / queue / tower state at the moment of the drop, and includes a ring buffer of recent events so you can see the lead-up. Off by default; the controller example has a "BLE Debug" tab that exposes the full UI (toggle, live event stream, persistent incident log, JSON export).
+
 ### 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
+- **Seed Parser** - Decode, encode, validate, and compare game seeds
+- **SystemRandom** - C# System.Random PRNG replica for game state prediction
+- **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,9 +164,9 @@ 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
 
@@ -164,9 +174,9 @@ The lights integration test validates the `allLightsOn` and `allLightsOff` API m
 
 **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
+- 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:**
 
@@ -176,21 +186,21 @@ npm run test:integration:lights
 
 **Prerequisites:**
 
--   Tower must be powered on and in Bluetooth range
--   `@stoprocent/noble` must be installed
+- 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
+- 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`.
+See [API_REFERENCE.md](docs/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
 
@@ -230,6 +240,9 @@ src/
 ├── udtCommandQueue.ts        # Command queue management
 ├── udtTowerResponse.ts       # Response handling
 ├── udtTowerState.ts          # Tower state management
+├── udtGameBoard.ts           # Board locations, kingdoms, and terrain data
+├── udtSeedParser.ts          # Game seed encoding/decoding (base-34)
+├── udtSystemRandom.ts        # C# System.Random PRNG replica
 ├── udtHelpers.ts             # Utility helper functions
 ├── udtLogger.ts              # Logging system
 ├── udtConstants.ts           # Constants and type definitions
@@ -271,10 +284,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](docs/API_REFERENCE.md) for performance best practices and workarounds.
 
 ## Community