ultimatedarktower 2.1.0 → 2.1.2

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [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.
+
+### 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
+
+### 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/**/*`
+
+## [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
+
+## [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`
+
+### 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
+
+## [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
+
+### 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`
+
+## [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
+
+[2.1.2]: https://github.com/ChessMess/UltimateDarkTower/compare/v2.1.1...v2.1.2
+[2.1.1]: https://github.com/ChessMess/UltimateDarkTower/compare/v2.1.0...v2.1.1
+[2.1.0]: https://github.com/ChessMess/UltimateDarkTower/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/ChessMess/UltimateDarkTower/compare/v1.0.0...v2.0.0
+[1.0.0]: https://github.com/ChessMess/UltimateDarkTower/releases/tag/v1.0.0

package/README.md

@@ -44,6 +44,7 @@ I have spent many hours reverse engineering the Tower's protocol in order to cre
 -   **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
@@ -143,6 +144,25 @@ Comprehensive documentation with TypeScript examples, best practices, and troubl
 -   **Best Practices** - Performance tips, error handling, and common patterns
 -   **Troubleshooting** - Solutions for common issues and debugging techniques
 
+## Integration Testing
+
+Integration tests that require real hardware are located in `tests/integration/` and are not run by default with the main test suite. These tests use the Node.js Bluetooth adapter and require a physical Return to Dark Tower device in range.
+
+To run the calibration integration test:
+
+```bash
+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.
+
+**Prerequisites:**
+
+-   Tower must be powered on and in Bluetooth range
+-   `@stoprocent/noble` must be installed (it is a peer dependency)
+
 ## Development
 
 ### Building and Testing