ultimatedarktower 3.0.0 → 4.0.1

package/CHANGELOG.md

@@ -6,6 +6,54 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ## [Unreleased]
 
+## [4.0.1] - 2026-05-28
+
+### Fixed
+
+- **`rotateWithState()` no longer bounces already-rotated drums back to their old positions** — `rotateDrumStateful()` was reading the live tower state to build its 20-byte stateful packet but never updating that state after sending. Inside `rotateWithState()` the three sequential calls therefore all read the same pre-rotation state, so call 2's packet re-sent the original top-drum position (rotating it back) and call 3's packet re-sent the original middle position. Local state is now updated immediately after the command is built, so subsequent calls in the loop encode the correct cumulative positions. Same pattern as the prior `setLEDStateful` fix.
+
+## [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

package/README.md

@@ -10,12 +10,20 @@ 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
 
+## 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.
+
+_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)._
+
 ## Table of Contents
 
 - [UltimateDarkTower](#ultimatedarktower)
+    - [Live Examples](#live-examples)
     - [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)
@@ -27,6 +35,8 @@ I have spent many hours reverse engineering the Tower's protocol in order to cre
     - [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)
@@ -50,16 +60,6 @@ I have spent many hours reverse engineering the Tower's protocol in order to cre
 - **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 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)._
-
 ## Installation
 
 ### Browser / Web Applications
@@ -119,7 +119,7 @@ import UltimateDarkTower, { IBluetoothAdapter } from 'ultimatedarktower';
 
 class MyCustomAdapter implements IBluetoothAdapter {
     // Implement all IBluetoothAdapter methods
-    // See API_REFERENCE.md for the full interface
+    // See docs/API_REFERENCE.md for the full interface
 }
 
 const tower = new UltimateDarkTower({ adapter: new MyCustomAdapter() });
@@ -127,10 +127,18 @@ const tower = new UltimateDarkTower({ adapter: new MyCustomAdapter() });
 
 ## Documentation
 
-### 📖 [Complete API Reference](API_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
@@ -139,6 +147,8 @@ Comprehensive documentation with TypeScript examples, best practices, and troubl
 - **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
@@ -185,7 +195,7 @@ npm run test:integration:lights
 - All lights breathe effect for 3 seconds
 - All lights off
 
-See [API_REFERENCE.md](API_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:**
 
@@ -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
@@ -274,7 +287,7 @@ examples/
 - **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 [API_REFERENCE.md](API_REFERENCE.md) for performance best practices and workarounds.
+> See [API_REFERENCE.md](docs/API_REFERENCE.md) for performance best practices and workarounds.
 
 ## Community