ultimatedarktower 3.0.0 → 4.0.0

package/dist/esm/index.mjs

@@ -125,7 +125,9 @@ var init_udtConstants = __esm({
       rotationDrumTop: 16,
       rotationDrumMiddle: 17,
       rotationDrumBottom: 18,
-      monthStarted: 19
+      monthStarted: 19,
+      wholeTowerBreathing: 20,
+      slowFlareThenFade: 21
     };
     TOWER_MESSAGES = {
       TOWER_STATE: { name: "Tower State", value: 0, critical: false },
@@ -452,9 +454,10 @@ var init_WebBluetoothAdapter = __esm({
           await this.rxCharacteristic.startNotifications();
           this.boundOnCharacteristicValueChanged = (event) => {
             const target = event.target;
-            const receivedData = new Uint8Array(target.value.byteLength);
-            for (let i = 0; i < target.value.byteLength; i++) {
-              receivedData[i] = target.value.getUint8(i);
+            const dataView = target.value;
+            const receivedData = new Uint8Array(dataView.byteLength);
+            for (let i = 0; i < dataView.byteLength; i++) {
+              receivedData[i] = dataView.getUint8(i);
             }
             if (this.characteristicCallback) {
               this.characteristicCallback(receivedData);
@@ -468,11 +471,12 @@ var init_WebBluetoothAdapter = __esm({
           if (error instanceof BluetoothDeviceNotFoundError || error instanceof BluetoothUserCancelledError || error instanceof BluetoothConnectionError) {
             throw error;
           }
-          const errorMsg = error?.message ?? String(error);
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          const errorName = error instanceof Error ? error.name : "";
           if (errorMsg.includes("User cancelled")) {
             throw new BluetoothUserCancelledError("User cancelled device selection", error);
           }
-          if (errorMsg.includes("not found") || error?.name === "NotFoundError") {
+          if (errorMsg.includes("not found") || errorName === "NotFoundError") {
             throw new BluetoothDeviceNotFoundError("Device not found", error);
           }
           throw new BluetoothConnectionError(`Failed to connect: ${errorMsg}`, error);
@@ -482,11 +486,11 @@ var init_WebBluetoothAdapter = __esm({
         if (!this.device) {
           return;
         }
-        if (this.device.gatt.connected) {
+        if (this.device.gatt?.connected) {
           if (this.boundOnDeviceDisconnected) {
             this.device.removeEventListener("gattserverdisconnected", this.boundOnDeviceDisconnected);
           }
-          await this.device.gatt.disconnect();
+          await this.device.gatt?.disconnect();
         }
         this.device = null;
         this.txCharacteristic = null;
@@ -602,8 +606,9 @@ var init_NodeBluetoothAdapter = __esm({
         try {
           await noble.waitForPoweredOnAsync();
         } catch (error) {
+          const msg = error instanceof Error ? error.message : String(error);
           throw new BluetoothConnectionError(
-            `Bluetooth adapter not ready: ${error.message}`,
+            `Bluetooth adapter not ready: ${msg}`,
             error
           );
         }
@@ -638,10 +643,10 @@ var init_NodeBluetoothAdapter = __esm({
           this.allCharacteristics = characteristics;
           this.txCharacteristic = characteristics.find(
             (c) => this.normalizeUuid(c.uuid) === txUuid
-          );
+          ) ?? null;
           this.rxCharacteristic = characteristics.find(
             (c) => this.normalizeUuid(c.uuid) === rxUuid
-          );
+          ) ?? null;
           if (!this.txCharacteristic || !this.rxCharacteristic) {
             throw new BluetoothConnectionError(
               "TX or RX characteristic not found on device"
@@ -659,8 +664,9 @@ var init_NodeBluetoothAdapter = __esm({
           if (error instanceof BluetoothDeviceNotFoundError || error instanceof BluetoothConnectionError || error instanceof BluetoothTimeoutError) {
             throw error;
           }
+          const msg = error instanceof Error ? error.message : String(error);
           throw new BluetoothConnectionError(
-            `Connection failed: ${error.message}`,
+            `Connection failed: ${msg}`,
             error
           );
         }
@@ -698,8 +704,9 @@ var init_NodeBluetoothAdapter = __esm({
           const buffer = Buffer.from(data);
           await this.txCharacteristic.writeAsync(buffer, false);
         } catch (error) {
+          const msg = error instanceof Error ? error.message : String(error);
           throw new BluetoothConnectionError(
-            `Write failed: ${error.message}`,
+            `Write failed: ${msg}`,
             error
           );
         }
@@ -1227,11 +1234,19 @@ var Logger = class _Logger {
   constructor() {
     this.outputs = [];
     this.enabledLevels = /* @__PURE__ */ new Set(["all"]);
+    this.diagnosticsTarget = null;
     this.outputs.push(new ConsoleOutput());
   }
   static {
     this.instance = null;
   }
+  /**
+   * Bridge warn/error log lines into a diagnostics recorder so they appear
+   * in the disconnect incident ring buffer in correct chronological order.
+   */
+  setDiagnosticsTarget(target) {
+    this.diagnosticsTarget = target;
+  }
   static getInstance() {
     if (!_Logger.instance) {
       _Logger.instance = new _Logger();
@@ -1286,6 +1301,13 @@ var Logger = class _Logger {
         console.error("Logger output error:", error);
       }
     });
+    if ((level === "warn" || level === "error") && this.diagnosticsTarget?.enabled) {
+      try {
+        this.diagnosticsTarget.recordLog(level, message, context);
+      } catch (error) {
+        console.error("Diagnostics log bridge error:", error);
+      }
+    }
   }
   debug(message, context) {
     this.log("debug", message, context);
@@ -1531,7 +1553,12 @@ var BluetoothAdapterFactory = class {
 
 // src/udtBleConnection.ts
 var UdtBleConnection = class {
-  constructor(logger2, callbacks, adapter) {
+  constructor(logger2, callbacks, adapter, recorder) {
+    this.recorder = null;
+    // Snapshot providers wired by UltimateDarkTower so the recorder can capture
+    // higher-level state (command queue, tower state, broken seals) at the
+    // moment a disconnect cause fires.
+    this.snapshotProviders = null;
     // Connection state
     this.isConnected = false;
     this.isDisposed = false;
@@ -1576,6 +1603,7 @@ var UdtBleConnection = class {
     this.logger = logger2;
     this.callbacks = callbacks;
     this.responseProcessor = new TowerResponseProcessor();
+    this.recorder = recorder ?? null;
     this.bluetoothAdapter = adapter || BluetoothAdapterFactory.create("auto" /* AUTO */);
     this.bluetoothAdapter.onCharacteristicValueChanged((data) => {
       this.onRxData(data);
@@ -1587,6 +1615,35 @@ var UdtBleConnection = class {
       this.bleAvailabilityChange(available);
     });
   }
+  setDiagnosticsSnapshotProviders(providers) {
+    this.snapshotProviders = providers;
+  }
+  /**
+   * Record a disconnect incident with the recorder. Public so higher layers
+   * (e.g. UltimateDarkTower's beforeunload handler) can synthesize causes
+   * like 'page_unload' that aren't tied to a specific BLE detection path.
+   */
+  recordIncidentPublic(cause) {
+    return this.recordIncident(cause);
+  }
+  recordIncident(cause) {
+    if (!this.recorder || !this.recorder.enabled) return null;
+    const queueSnapshot = this.snapshotProviders?.commandQueue() ?? {
+      queueLength: 0,
+      isProcessing: false,
+      currentCommand: null
+    };
+    const towerState = this.snapshotProviders?.towerState() ?? null;
+    const brokenSeals = this.snapshotProviders?.brokenSeals() ?? [];
+    return this.recorder.recordIncident({
+      cause,
+      connectionStatus: this.getConnectionStatus(),
+      deviceInformation: this.getDeviceInformation(),
+      commandQueue: queueSnapshot,
+      towerState,
+      brokenSeals
+    });
+  }
   async connect() {
     if (this.isDisposed) {
       throw new Error("UdtBleConnection instance has been disposed and cannot reconnect");
@@ -1601,6 +1658,7 @@ var UdtBleConnection = class {
       this.isConnected = true;
       this.lastSuccessfulCommand = Date.now();
       this.lastBatteryHeartbeat = Date.now();
+      this.recorder?.beginSession();
       await this.readDeviceInformation();
       if (this.enableConnectionMonitoring) {
         this.startConnectionMonitoring();
@@ -1609,11 +1667,14 @@ var UdtBleConnection = class {
     } catch (error) {
       this.logger.error(`Tower Connection Error: ${error}`, "[UDT][BLE]");
       this.isConnected = false;
-      this.callbacks.onTowerDisconnect();
+      throw error;
     }
   }
   async disconnect() {
     this.stopConnectionMonitoring();
+    if (this.isConnected) {
+      this.recordIncident("user_initiated");
+    }
     if (this.bluetoothAdapter.isConnected()) {
       await this.bluetoothAdapter.disconnect();
       this.logger.info("Tower disconnected", "[UDT]");
@@ -1625,6 +1686,7 @@ var UdtBleConnection = class {
    * Used by UdtTowerCommands instead of direct characteristic access.
    */
   async writeCommand(command) {
+    this.recorder?.recordCommandPayload("cmd_sent", command, { len: command.length });
     return await this.bluetoothAdapter.writeCharacteristic(command);
   }
   /**
@@ -1635,6 +1697,9 @@ var UdtBleConnection = class {
     this.lastSuccessfulCommand = Date.now();
     const { cmdKey } = this.responseProcessor.getTowerCommand(receivedData[0]);
     const isBattery = this.responseProcessor.isBatteryResponse(cmdKey);
+    if (this.recorder?.enabled && !isBattery) {
+      this.recorder.recordCommandPayload("cmd_response", receivedData, { cmdKey, len: receivedData.length });
+    }
     const shouldLogCommand = this.logTowerResponses && this.responseProcessor.shouldLogResponse(cmdKey, this.logTowerResponseConfig) && !isBattery;
     if (shouldLogCommand) {
       this.logger.info(`${cmdKey}`, "[UDT][BLE][RCVD]");
@@ -1649,6 +1714,7 @@ var UdtBleConnection = class {
       this.lastBatteryHeartbeat = Date.now();
       const millivolts = getMilliVoltsFromTowerResponse(receivedData);
       const batteryPercentage = milliVoltsToPercentage(millivolts);
+      this.recorder?.recordBattery(millivolts, milliVoltsToPercentageNumber(millivolts));
       const didBatteryLevelChange = this.lastBatteryPercentage !== "" && this.lastBatteryPercentage !== batteryPercentage;
       const batteryLogFrequencyPassed = Date.now() - this.lastBatteryLog >= this.batteryLogFrequency;
       const shouldLog = this.batteryLogEnabled && (this.batteryLogOnChangeOnly ? didBatteryLevelChange || this.lastBatteryPercentage === "" : batteryLogFrequencyPassed);
@@ -1668,17 +1734,20 @@ var UdtBleConnection = class {
     const dataSkullDropCount = receivedData[SKULL_DROP_COUNT_POS];
     const state = rtdt_unpack_state(receivedData);
     this.logger.debug(`Tower State: ${JSON.stringify(state)} `, "[UDT][BLE]");
+    this.recorder?.recordEvent("tower_state_response");
     if (this.performingCalibration) {
       this.performingCalibration = false;
       this.performingLongCommand = false;
       this.lastBatteryHeartbeat = Date.now();
       this.callbacks.onCalibrationComplete();
       this.logger.info("Tower calibration complete", "[UDT]");
+      this.recorder?.recordEvent("calibration_complete");
     }
     if (dataSkullDropCount !== this.towerSkullDropCount) {
       if (dataSkullDropCount) {
         this.callbacks.onSkullDrop(dataSkullDropCount);
         this.logger.info(`Skull drop detected: app:${this.towerSkullDropCount < 0 ? "empty" : this.towerSkullDropCount}  tower:${dataSkullDropCount}`, "[UDT]");
+        this.recorder?.recordEvent("skull_drop", { count: dataSkullDropCount });
       } else {
         this.logger.info(`Skull count reset to ${dataSkullDropCount}`, "[UDT]");
       }
@@ -1704,11 +1773,15 @@ var UdtBleConnection = class {
     this.logger.info("Bluetooth availability changed", "[UDT][BLE]");
     if (!available && this.isConnected) {
       this.logger.warn("Bluetooth became unavailable - handling disconnection", "[UDT][BLE]");
+      this.recordIncident("bt_unavailable");
       this.handleDisconnection();
     }
   }
   onTowerDeviceDisconnected() {
     this.logger.warn("Tower device disconnected unexpectedly", "[UDT][BLE]");
+    if (this.isConnected) {
+      this.recordIncident("adapter_event");
+    }
     this.handleDisconnection();
   }
   handleDisconnection() {
@@ -1741,6 +1814,7 @@ var UdtBleConnection = class {
     }
     if (!this.bluetoothAdapter.isGattConnected()) {
       this.logger.warn("GATT connection lost detected during health check", "[UDT][BLE]");
+      this.recordIncident("gatt_health_check");
       this.handleDisconnection();
       return;
     }
@@ -1758,12 +1832,17 @@ var UdtBleConnection = class {
           this.logger.info("Verifying tower connection status before triggering disconnection...", "[UDT][BLE]");
           if (this.bluetoothAdapter.isGattConnected()) {
             this.logger.info("GATT connection still available - heartbeat timeout may be temporary", "[UDT][BLE]");
+            this.recorder?.recordEvent("heartbeat_late", {
+              sinceMs: timeSinceLastBatteryHeartbeat,
+              threshold: timeoutThreshold
+            });
             this.lastBatteryHeartbeat = Date.now();
             this.logger.info("Reset battery heartbeat timer - will monitor for another timeout period", "[UDT][BLE]");
             return;
           }
         }
         this.logger.warn("Tower possibly disconnected due to battery depletion or power loss", "[UDT][BLE]");
+        this.recordIncident("heartbeat_timeout");
         this.handleDisconnection();
         return;
       }
@@ -1771,6 +1850,7 @@ var UdtBleConnection = class {
     const timeSinceLastResponse = Date.now() - this.lastSuccessfulCommand;
     if (timeSinceLastResponse > this.connectionTimeoutThreshold) {
       this.logger.warn("General connection timeout detected - no responses received", "[UDT][BLE]");
+      this.recordIncident("response_timeout");
       this.handleDisconnection();
     }
   }
@@ -2103,8 +2183,7 @@ init_udtConstants();
 
 // src/udtCommandQueue.ts
 var CommandQueue = class {
-  // 30 seconds
-  constructor(logger2, sendCommandFn) {
+  constructor(logger2, sendCommandFn, recorder) {
     this.logger = logger2;
     this.sendCommandFn = sendCommandFn;
     this.queue = [];
@@ -2112,6 +2191,12 @@ var CommandQueue = class {
     this.timeoutHandle = null;
     this.isProcessing = false;
     this.timeoutMs = 3e4;
+    // 30 seconds
+    this.recorder = null;
+    this.recorder = recorder ?? null;
+  }
+  setRecorder(recorder) {
+    this.recorder = recorder;
   }
   /**
    * Enqueue a command for processing
@@ -2128,6 +2213,11 @@ var CommandQueue = class {
       };
       this.queue.push(queuedCommand);
       this.logger.debug(`Command queued: ${description || "unnamed"} (queue size: ${this.queue.length})`, "[UDT]");
+      this.recorder?.recordEvent("cmd_enqueued", {
+        id: queuedCommand.id,
+        description,
+        queueDepth: this.queue.length
+      });
       if (!this.isProcessing) {
         this.processNext();
       }
@@ -2151,6 +2241,11 @@ var CommandQueue = class {
       await this.sendCommandFn(command);
     } catch (error) {
       this.clearTimeout();
+      this.recorder?.recordEvent("cmd_failed", {
+        id,
+        description,
+        error: error?.message ?? String(error)
+      });
       this.currentCommand = null;
       this.isProcessing = false;
       reject(error);
@@ -2176,8 +2271,14 @@ var CommandQueue = class {
    */
   onTimeout() {
     if (this.currentCommand) {
-      const { description, id } = this.currentCommand;
+      const { description, id, timestamp } = this.currentCommand;
       this.logger.warn(`Command timeout after ${this.timeoutMs}ms: ${description || id}`, "[UDT]");
+      this.recorder?.recordEvent("cmd_timeout", {
+        id,
+        description,
+        ageMs: Date.now() - timestamp,
+        queueDepth: this.queue.length
+      });
       const reject = this.currentCommand.reject;
       this.currentCommand = null;
       this.isProcessing = false;
@@ -2232,7 +2333,8 @@ var UdtTowerCommands = class {
     this.deps = dependencies;
     this.commandQueue = new CommandQueue(
       this.deps.logger,
-      (command) => this.sendTowerCommandDirect(command)
+      (command) => this.sendTowerCommandDirect(command),
+      this.deps.recorder
     );
   }
   /**
@@ -2291,6 +2393,7 @@ var UdtTowerCommands = class {
   async calibrate() {
     if (!this.deps.bleConnection.performingCalibration) {
       this.deps.logger.info("Performing Tower Calibration", "[UDT][CMD]");
+      this.deps.recorder?.recordEvent("calibration_started");
       await this.sendTowerCommand(new Uint8Array([TOWER_COMMANDS.calibration]), "calibrate");
       this.deps.bleConnection.performingCalibration = true;
       this.deps.bleConnection.performingLongCommand = true;
@@ -2584,29 +2687,8 @@ var UdtTowerCommands = class {
       stateWithVolume.audio = { sample: 0, loop: false, volume: actualVolume };
       await this.sendTowerStateStateful(stateWithVolume);
     }
-    this.deps.logger.info("Playing tower seal sound", "[UDT]");
-    await this.playSoundStateful(TOWER_AUDIO_LIBRARY.TowerSeal.value, false, actualVolume);
-    const sideCorners = {
-      north: ["northeast", "northwest"],
-      east: ["northeast", "southeast"],
-      south: ["southeast", "southwest"],
-      west: ["southwest", "northwest"]
-    };
-    const ledgeLights = sideCorners[seal.side].map((corner) => ({
-      position: corner,
-      style: "on"
-    }));
-    const doorwayLights = [{
-      level: seal.level,
-      position: seal.side,
-      style: "breatheFast"
-    }];
-    const lights = {
-      ledge: ledgeLights,
-      doorway: doorwayLights
-    };
-    this.deps.logger.info(`Breaking seal ${seal.level}-${seal.side} - lighting ledges and doorways with breath effect`, "[UDT]");
-    await this.lights(lights);
+    this.deps.logger.info(`Breaking seal ${seal.level}-${seal.side} - triggering firmware sealReveal animation`, "[UDT]");
+    await this.lightOverrides(TOWER_LIGHT_SEQUENCES.sealReveal, TOWER_AUDIO_LIBRARY.TowerSeal.value);
   }
   /**
    * Randomly rotates specified tower levels to random positions.
@@ -2807,9 +2889,201 @@ var UdtTowerCommands = class {
   }
 };
 
+// src/udtDiagnostics.ts
+var RING_BUFFER_SIZE = 500;
+var RING_BUFFER_DRAIN = 50;
+var BATTERY_HISTORY_SIZE = 60;
+var PAYLOAD_MAX_BYTES = 32;
+var LIBRARY_VERSION = "3.0.0";
+function detectPlatform() {
+  if (typeof window !== "undefined" && typeof window.navigator !== "undefined") {
+    return "web";
+  }
+  if (typeof process !== "undefined" && process.versions?.node) {
+    return "node";
+  }
+  return "custom";
+}
+function makeId() {
+  const g = globalThis;
+  if (g.crypto && typeof g.crypto.randomUUID === "function") {
+    try {
+      return g.crypto.randomUUID();
+    } catch {
+    }
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
+}
+function bytesToHex(data, maxBytes = PAYLOAD_MAX_BYTES) {
+  const slice = data.length > maxBytes ? data.subarray(0, maxBytes) : data;
+  let out = "";
+  for (let i = 0; i < slice.length; i++) {
+    out += slice[i].toString(16).padStart(2, "0");
+  }
+  if (data.length > maxBytes) {
+    out += `..(+${data.length - maxBytes})`;
+  }
+  return out;
+}
+var InMemorySink = class {
+  constructor(maxIncidents = 50) {
+    this.incidents = [];
+    this.maxIncidents = maxIncidents;
+  }
+  onIncident(report) {
+    this.incidents.push(report);
+    if (this.incidents.length > this.maxIncidents) {
+      this.incidents.splice(0, this.incidents.length - this.maxIncidents);
+    }
+  }
+  list() {
+    return [...this.incidents];
+  }
+  get(incidentId) {
+    return this.incidents.find((r) => r.incidentId === incidentId);
+  }
+  clear() {
+    this.incidents = [];
+  }
+};
+var UdtDiagnosticsRecorder = class {
+  constructor(config) {
+    this.events = [];
+    this.batteryHistory = [];
+    this.sessionId = "";
+    this.connectedAt = null;
+    this.lastIncident = null;
+    this.enabled = config.enabled;
+    this.capturePayloads = config.capturePayloads ?? false;
+    this.sinks = config.sinks ?? [];
+  }
+  setSinks(sinks) {
+    this.sinks = sinks;
+  }
+  getSinks() {
+    return [...this.sinks];
+  }
+  addSink(sink) {
+    this.sinks.push(sink);
+  }
+  /** Mark the start of a connected session. Called from BLE connect path. */
+  beginSession() {
+    if (!this.enabled) return;
+    this.sessionId = makeId();
+    this.connectedAt = Date.now();
+    this.events = [];
+    this.batteryHistory = [];
+    this.recordEvent("connect");
+  }
+  recordEvent(kind, data) {
+    if (!this.enabled) return;
+    const event = { t: Date.now(), kind };
+    if (data) event.data = data;
+    this.events.push(event);
+    if (this.events.length > RING_BUFFER_SIZE) {
+      this.events.splice(0, RING_BUFFER_DRAIN);
+    }
+    for (const sink of this.sinks) {
+      if (sink.onEvent) {
+        try {
+          sink.onEvent(event);
+        } catch (e) {
+          console.error("Diagnostics sink onEvent error:", e);
+        }
+      }
+    }
+  }
+  recordCommandPayload(kind, data, extra) {
+    if (!this.enabled) return;
+    const payload = { ...extra };
+    if (this.capturePayloads) {
+      payload.payloadHex = bytesToHex(data);
+      payload.payloadLen = data.length;
+    }
+    this.recordEvent(kind, payload);
+  }
+  recordBattery(mv, pct) {
+    if (!this.enabled) return;
+    this.batteryHistory.push({ t: Date.now(), mv, pct });
+    if (this.batteryHistory.length > BATTERY_HISTORY_SIZE) {
+      this.batteryHistory.splice(0, this.batteryHistory.length - BATTERY_HISTORY_SIZE);
+    }
+  }
+  /** Forwards a log line into the events ring (called by Logger when bridged). */
+  recordLog(level, message, context) {
+    if (!this.enabled) return;
+    this.recordEvent("log", { level, message, context });
+  }
+  /**
+   * Capture an incident snapshot and dispatch to sinks.
+   * Must be called BEFORE the BLE layer clears state.
+   */
+  recordIncident(inputs) {
+    if (!this.enabled) return null;
+    const triggeredAt = Date.now();
+    const inFlightCommandAgeMs = inputs.commandQueue.currentCommand ? triggeredAt - inputs.commandQueue.currentCommand.timestamp : null;
+    const report = {
+      schemaVersion: 1,
+      incidentId: makeId(),
+      sessionId: this.sessionId || makeId(),
+      cause: inputs.cause,
+      triggeredAt,
+      connectedAt: this.connectedAt,
+      sessionDurationMs: this.connectedAt ? triggeredAt - this.connectedAt : 0,
+      connectionStatus: { ...inputs.connectionStatus },
+      deviceInformation: { ...inputs.deviceInformation },
+      commandQueue: {
+        queueLength: inputs.commandQueue.queueLength,
+        isProcessing: inputs.commandQueue.isProcessing,
+        currentCommand: inputs.commandQueue.currentCommand ? { ...inputs.commandQueue.currentCommand } : null
+      },
+      inFlightCommandAgeMs,
+      towerState: inputs.towerState ? JSON.parse(JSON.stringify(inputs.towerState)) : null,
+      brokenSeals: [...inputs.brokenSeals],
+      recentEvents: [...this.events],
+      batteryHistory: [...this.batteryHistory],
+      library: { version: LIBRARY_VERSION, platform: detectPlatform() },
+      userAgent: typeof navigator !== "undefined" ? navigator.userAgent : void 0
+    };
+    this.lastIncident = report;
+    this.recordEvent("disconnect", { cause: inputs.cause });
+    for (const sink of this.sinks) {
+      try {
+        const result = sink.onIncident(report);
+        if (result && typeof result.then === "function") {
+          result.catch((e) => console.error("Diagnostics sink onIncident error:", e));
+        }
+      } catch (e) {
+        console.error("Diagnostics sink onIncident error:", e);
+      }
+    }
+    return report;
+  }
+  getRingBuffer() {
+    return [...this.events];
+  }
+  getBatteryHistory() {
+    return [...this.batteryHistory];
+  }
+  getSessionId() {
+    return this.sessionId;
+  }
+  getConnectedAt() {
+    return this.connectedAt;
+  }
+  getLastIncident() {
+    return this.lastIncident;
+  }
+  clearRingBuffer() {
+    this.events = [];
+    this.batteryHistory = [];
+  }
+};
+
 // src/UltimateDarkTower.ts
 var UltimateDarkTower = class {
   constructor(config) {
+    this.beforeUnloadHandler = null;
     // tower configuration
     this.retrySendCommandCountRef = { value: 0 };
     this.retrySendCommandMax = DEFAULT_RETRY_SEND_COMMAND_MAX;
@@ -2851,8 +3125,10 @@ var UltimateDarkTower = class {
     // utility
     this._logDetail = false;
     this.initializeLogger();
+    this.initializeDiagnostics(config?.diagnostics);
     this.initializeComponents(config);
     this.setupTowerResponseCallback();
+    this.installBeforeUnloadHandler();
   }
   /**
    * Initialize the logger with default console output
@@ -2861,6 +3137,20 @@ var UltimateDarkTower = class {
     this.logger = new Logger();
     this.logger.addOutput(new ConsoleOutput());
   }
+  /**
+   * Initialize the diagnostics recorder. Always constructed; `enabled` defaults
+   * to false, so when no config is supplied the recorder is a no-op aside from
+   * a single boolean check at each hook site.
+   */
+  initializeDiagnostics(config) {
+    const sinks = config?.sinks ?? (config?.enabled ? [new InMemorySink()] : []);
+    this.diagnosticsRecorder = new UdtDiagnosticsRecorder({
+      enabled: config?.enabled ?? false,
+      capturePayloads: config?.capturePayloads,
+      sinks
+    });
+    this.logger.setDiagnosticsTarget(this.diagnosticsRecorder);
+  }
   /**
    * Initialize all tower components and their dependencies
    */
@@ -2872,11 +3162,16 @@ var UltimateDarkTower = class {
       adapter = BluetoothAdapterFactory.create(config.platform);
     }
     this.towerEventCallbacks = this.createTowerEventCallbacks();
-    this.bleConnection = new UdtBleConnection(this.logger, this.towerEventCallbacks, adapter);
+    this.bleConnection = new UdtBleConnection(this.logger, this.towerEventCallbacks, adapter, this.diagnosticsRecorder);
     this.responseProcessor = new TowerResponseProcessor(this.logDetail);
     this.commandFactory = new UdtCommandFactory();
     const commandDependencies = this.createCommandDependencies();
     this.towerCommands = new UdtTowerCommands(commandDependencies);
+    this.bleConnection.setDiagnosticsSnapshotProviders({
+      commandQueue: () => this.towerCommands.getQueueStatus(),
+      towerState: () => this.currentTowerState,
+      brokenSeals: () => Array.from(this.brokenSeals)
+    });
     if (config?.brokenSeals) {
       for (const seal of config.brokenSeals) {
         const sealKey = `${seal.level}-${seal.side}`;
@@ -2884,6 +3179,23 @@ var UltimateDarkTower = class {
       }
     }
   }
+  /**
+   * Browser-only: synthesize a `page_unload` incident if the page closes while
+   * connected. Without this, refreshing the page during a hang loses the
+   * lead-up context. IndexedDB writes during unload are best-effort.
+   */
+  installBeforeUnloadHandler() {
+    if (typeof window === "undefined" || typeof window.addEventListener !== "function") return;
+    this.beforeUnloadHandler = () => {
+      if (this.diagnosticsRecorder.enabled && this.bleConnection?.isConnected) {
+        try {
+          this.bleConnection.recordIncidentPublic("page_unload");
+        } catch {
+        }
+      }
+    };
+    window.addEventListener("beforeunload", this.beforeUnloadHandler);
+  }
   /**
    * Set up the tower response callback after all components are initialized
    */
@@ -2938,7 +3250,8 @@ var UltimateDarkTower = class {
       retrySendCommandCount: this.retrySendCommandCountRef,
       retrySendCommandMax: this.retrySendCommandMax,
       getCurrentTowerState: () => this.currentTowerState,
-      setTowerState: (newState, source) => this.setTowerState(newState, source)
+      setTowerState: (newState, source) => this.setTowerState(newState, source),
+      recorder: this.diagnosticsRecorder
     };
   }
   /**
@@ -3230,6 +3543,7 @@ var UltimateDarkTower = class {
   updateTowerStateFromResponse(stateData) {
     const newState = rtdt_unpack_state(stateData);
     newState.audio = { sample: 0, loop: false, volume: this.currentTowerState.audio.volume };
+    newState.led_sequence = 0;
     this.setTowerState(newState, "tower response");
   }
   //#endregion
@@ -3547,19 +3861,680 @@ var UltimateDarkTower = class {
   async cleanup() {
     this.logger.info("Cleaning up UltimateDarkTower instance", "[UDT]");
     this.towerCommands.clearQueue();
+    if (this.beforeUnloadHandler && typeof window !== "undefined") {
+      window.removeEventListener("beforeunload", this.beforeUnloadHandler);
+      this.beforeUnloadHandler = null;
+    }
+    this.logger.setDiagnosticsTarget(null);
     await this.bleConnection.cleanup();
   }
   //#endregion
+  //#region Diagnostics (BLE flight recorder)
+  /**
+   * Get the diagnostics recorder for direct access (live ring buffer, sinks,
+   * runtime enable/disable). Always returns a recorder; check `.enabled` to
+   * see whether capture is active.
+   */
+  getDiagnosticsRecorder() {
+    return this.diagnosticsRecorder;
+  }
+  /**
+   * Toggle diagnostics capture at runtime without reconstructing the tower.
+   * When enabled mid-session, the next BLE event begins populating the buffer.
+   */
+  setDiagnosticsEnabled(enabled) {
+    this.diagnosticsRecorder.enabled = enabled;
+  }
+  /**
+   * Whether diagnostics capture is currently active.
+   */
+  isDiagnosticsEnabled() {
+    return this.diagnosticsRecorder.enabled;
+  }
+  /**
+   * Get the most recent disconnect incident report, or null if none captured
+   * since this instance was created.
+   */
+  getLastIncident() {
+    return this.diagnosticsRecorder.getLastIncident();
+  }
+  /**
+   * Export current ring buffer + last incident as JSON for sharing/analysis.
+   * Useful as a one-liner in a "copy diagnostic info" button.
+   */
+  exportDiagnosticsJSON() {
+    return JSON.stringify({
+      schemaVersion: 1,
+      capturedAt: Date.now(),
+      sessionId: this.diagnosticsRecorder.getSessionId(),
+      ringBuffer: this.diagnosticsRecorder.getRingBuffer(),
+      batteryHistory: this.diagnosticsRecorder.getBatteryHistory(),
+      lastIncident: this.diagnosticsRecorder.getLastIncident()
+    }, null, 2);
+  }
+  //#endregion
 };
 var UltimateDarkTower_default = UltimateDarkTower;
 
 // src/index.ts
 init_udtConstants();
 init_udtBluetoothAdapter();
+
+// src/sinks/IndexedDBSink.ts
+var DB_NAME = "udt-diagnostics";
+var DB_VERSION = 1;
+var STORE_NAME = "incidents";
+function indexedDBAvailable() {
+  try {
+    return typeof indexedDB !== "undefined";
+  } catch {
+    return false;
+  }
+}
+function openDb() {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(DB_NAME, DB_VERSION);
+    req.onupgradeneeded = () => {
+      const db = req.result;
+      if (!db.objectStoreNames.contains(STORE_NAME)) {
+        const store = db.createObjectStore(STORE_NAME, { keyPath: "incidentId" });
+        store.createIndex("triggeredAt", "triggeredAt", { unique: false });
+      }
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+var IndexedDBSink = class {
+  constructor(maxIncidents = 50) {
+    this.dbPromise = null;
+    this.maxIncidents = maxIncidents;
+    this.available = indexedDBAvailable();
+  }
+  async getDb() {
+    if (!this.available) return null;
+    if (!this.dbPromise) {
+      this.dbPromise = openDb().catch((err) => {
+        this.available = false;
+        this.dbPromise = null;
+        throw err;
+      });
+    }
+    try {
+      return await this.dbPromise;
+    } catch {
+      return null;
+    }
+  }
+  async onIncident(report) {
+    const db = await this.getDb();
+    if (!db) return;
+    await new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE_NAME, "readwrite");
+      const store = tx.objectStore(STORE_NAME);
+      store.put(report);
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+      tx.onabort = () => reject(tx.error);
+    }).catch((e) => console.error("IndexedDBSink put failed:", e));
+    await this.evictOld();
+  }
+  async list() {
+    const db = await this.getDb();
+    if (!db) return [];
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE_NAME, "readonly");
+      const store = tx.objectStore(STORE_NAME);
+      const req = store.getAll();
+      req.onsuccess = () => {
+        const all = req.result.slice();
+        all.sort((a, b) => b.triggeredAt - a.triggeredAt);
+        resolve(all);
+      };
+      req.onerror = () => reject(req.error);
+    });
+  }
+  async get(incidentId) {
+    const db = await this.getDb();
+    if (!db) return void 0;
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE_NAME, "readonly");
+      const store = tx.objectStore(STORE_NAME);
+      const req = store.get(incidentId);
+      req.onsuccess = () => resolve(req.result);
+      req.onerror = () => reject(req.error);
+    });
+  }
+  async delete(incidentId) {
+    const db = await this.getDb();
+    if (!db) return;
+    await new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE_NAME, "readwrite");
+      tx.objectStore(STORE_NAME).delete(incidentId);
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    }).catch((e) => console.error("IndexedDBSink delete failed:", e));
+  }
+  async clear() {
+    const db = await this.getDb();
+    if (!db) return;
+    await new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE_NAME, "readwrite");
+      tx.objectStore(STORE_NAME).clear();
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    }).catch((e) => console.error("IndexedDBSink clear failed:", e));
+  }
+  /** Insert an externally-supplied report (e.g. from a JSON import). */
+  async put(report) {
+    return this.onIncident(report);
+  }
+  async evictOld() {
+    const db = await this.getDb();
+    if (!db) return;
+    await new Promise((resolve) => {
+      const tx = db.transaction(STORE_NAME, "readwrite");
+      const store = tx.objectStore(STORE_NAME);
+      const countReq = store.count();
+      countReq.onsuccess = () => {
+        const total = countReq.result;
+        if (total <= this.maxIncidents) {
+          resolve();
+          return;
+        }
+        const toRemove = total - this.maxIncidents;
+        const idx = store.index("triggeredAt");
+        const cursorReq = idx.openCursor();
+        let removed = 0;
+        cursorReq.onsuccess = () => {
+          const cursor = cursorReq.result;
+          if (!cursor || removed >= toRemove) {
+            resolve();
+            return;
+          }
+          cursor.delete();
+          removed++;
+          cursor.continue();
+        };
+        cursorReq.onerror = () => resolve();
+      };
+      countReq.onerror = () => resolve();
+    });
+  }
+};
+
+// src/udtSeedParser.ts
+var ALPHABET = "a123456789bcdefghijklmnpqrstuvwxyz";
+var BASE = 34;
+var SETUP_LENGTH = 6;
+var RNG_SEED_LENGTH = 6;
+var SEED_LENGTH = SETUP_LENGTH + RNG_SEED_LENGTH;
+var CHAR_TO_VALUE = /* @__PURE__ */ new Map();
+var VALUE_TO_CHAR = /* @__PURE__ */ new Map();
+for (let i = 0; i < ALPHABET.length; i++) {
+  CHAR_TO_VALUE.set(ALPHABET[i], i);
+  VALUE_TO_CHAR.set(i, ALPHABET[i]);
+}
+var TIER1_FOES = ["Brigands", "Oreks", "Shadow Wolves", "Spine Fiends"];
+var TIER2_FOES = ["Frost Trolls", "Clan of Neuri", "Lemures", "Widowmade Spiders"];
+var TIER3_FOES = ["Dragons", "Mormos", "Striga", "Titans"];
+var ADVERSARIES = [
+  "Ashstrider",
+  "Bane of Omens",
+  "Empress of Shades",
+  "Gaze Eternal",
+  "Gravemaw",
+  "Isa the Exile",
+  "Lingering Rot",
+  "Utuk'Ku"
+];
+var ALLIES = [
+  "Gleb",
+  "Grigor",
+  "Hakan",
+  "Letha",
+  "Miras",
+  "Nimet",
+  "Tomas",
+  "Vasa",
+  "Yana",
+  "Zaida"
+];
+var DIFFICULTIES = ["Heroic", "Gritty"];
+var GAME_SOURCES = ["Core", "Competitive"];
+function charToValue(c) {
+  const v = CHAR_TO_VALUE.get(c.toLowerCase());
+  if (v === void 0) {
+    throw new Error(`Invalid seed character: '${c}'`);
+  }
+  return v;
+}
+function valueToChar(v) {
+  const c = VALUE_TO_CHAR.get(v);
+  if (c === void 0) {
+    throw new Error(`Invalid seed value: ${v} (must be 0\u2013${BASE - 1})`);
+  }
+  return c;
+}
+function validateSeed(seed) {
+  const stripped = seed.replace(/[-\s]/g, "").toLowerCase();
+  if (stripped.length !== SEED_LENGTH) {
+    throw new Error(`Invalid seed length: expected ${SEED_LENGTH} characters, got ${stripped.length}`);
+  }
+  for (const c of stripped) {
+    if (!CHAR_TO_VALUE.has(c)) {
+      throw new Error(`Invalid seed character: '${c}'`);
+    }
+  }
+  const upper = stripped.toUpperCase();
+  return `${upper.slice(0, 4)}-${upper.slice(4, 8)}-${upper.slice(8, 12)}`;
+}
+function decodeSeed(seed) {
+  const normalized = validateSeed(seed);
+  const stripped = normalized.replace(/-/g, "").toLowerCase();
+  const setup = [];
+  for (let i = 0; i < SETUP_LENGTH; i++) {
+    setup.push(charToValue(stripped[i]));
+  }
+  let rngSeed = 0;
+  for (let i = 0; i < RNG_SEED_LENGTH; i++) {
+    const value = charToValue(stripped[SETUP_LENGTH + i]);
+    rngSeed += value * Math.round(Math.pow(BASE, i));
+  }
+  const foeByteA = setup[0];
+  const tier1 = foeByteA & 3;
+  const tier2 = (foeByteA & 12) >> 2;
+  const foeByteB = setup[1];
+  const tier3 = (foeByteA & 16) >> 4 | (foeByteB & 16) >> 3;
+  const adversaryIndex = foeByteB & 15;
+  const allyIndex = setup[2];
+  const extra = setup[3];
+  const difficultyIndex = extra & 1;
+  const expansionBits = (extra & 6) >> 1;
+  const sourceBits = (extra & 8) >> 2;
+  const playerCount = (setup[5] & 3) + 1;
+  const expansions = [];
+  if (expansionBits & 1) expansions.push("Monuments");
+  if (expansionBits & 2) expansions.push("Alliances");
+  let source;
+  switch (sourceBits) {
+    case 2:
+      source = "Competitive";
+      break;
+    default:
+      source = "Core";
+      break;
+  }
+  const seedBank = {
+    initializationSeed: rngSeed,
+    questSeed: rngSeed - 1,
+    seedString: normalized
+  };
+  return {
+    seed: normalized,
+    tier1Foe: TIER1_FOES[tier1],
+    tier2Foe: TIER2_FOES[tier2],
+    tier3Foe: TIER3_FOES[tier3],
+    adversary: ADVERSARIES[adversaryIndex],
+    ally: ALLIES[allyIndex],
+    difficulty: DIFFICULTIES[difficultyIndex],
+    source,
+    expansions,
+    playerCount,
+    rngSeed,
+    seedBank,
+    setup
+  };
+}
+function decodeRngSeed(seed) {
+  const normalized = validateSeed(seed);
+  const stripped = normalized.replace(/-/g, "").toLowerCase();
+  let rngSeed = 0;
+  for (let i = 0; i < RNG_SEED_LENGTH; i++) {
+    const value = charToValue(stripped[SETUP_LENGTH + i]);
+    rngSeed += value * Math.round(Math.pow(BASE, i));
+  }
+  return rngSeed;
+}
+function createSeed(config) {
+  let foeByteA = 0;
+  let foeByteB = 0;
+  const tier1Index = TIER1_FOES.indexOf(config.foes[0]);
+  const tier2Index = TIER2_FOES.indexOf(config.foes[1]);
+  const tier3Index = TIER3_FOES.indexOf(config.foes[2]);
+  if (tier1Index < 0) throw new Error(`Invalid Tier 1 foe: ${config.foes[0]}`);
+  if (tier2Index < 0) throw new Error(`Invalid Tier 2 foe: ${config.foes[1]}`);
+  if (tier3Index < 0) throw new Error(`Invalid Tier 3 foe: ${config.foes[2]}`);
+  foeByteA = tier1Index & 3;
+  foeByteA |= (tier2Index & 3) << 2;
+  foeByteA |= (tier3Index & 1) << 4;
+  foeByteB |= (tier3Index >> 1 & 1) << 4;
+  const adversaryIndex = ADVERSARIES.indexOf(config.adversary);
+  if (adversaryIndex < 0) throw new Error(`Invalid adversary: ${config.adversary}`);
+  foeByteB |= adversaryIndex & 15;
+  const allyIndex = ALLIES.indexOf(config.ally);
+  if (allyIndex < 0) throw new Error(`Invalid ally: ${config.ally}`);
+  let extraByte = 0;
+  if (config.difficulty === "Gritty") extraByte |= 1;
+  for (const expansion of config.expansions) {
+    switch (expansion) {
+      case "Monuments":
+        extraByte |= 2;
+        break;
+      case "Alliances":
+        extraByte |= 4;
+        break;
+    }
+  }
+  if (config.source === "Competitive") extraByte |= 8;
+  const versionByte = 0;
+  const playerCountByte = Math.max(0, Math.min(3, config.playerCount - 1));
+  let seedStr = valueToChar(foeByteA) + valueToChar(foeByteB) + valueToChar(allyIndex) + valueToChar(extraByte) + valueToChar(versionByte) + valueToChar(playerCountByte);
+  let rngValue = 0;
+  for (let i = 0; i < RNG_SEED_LENGTH; i++) {
+    const value = Math.floor(Math.random() * BASE);
+    seedStr += valueToChar(value);
+    rngValue += value * Math.round(Math.pow(BASE, i));
+  }
+  const upper = seedStr.toUpperCase();
+  const formatted = `${upper.slice(0, 4)}-${upper.slice(4, 8)}-${upper.slice(8, 12)}`;
+  return { seed: formatted, rngValue };
+}
+function encodeSeed(config, rngValue) {
+  let foeByteA = 0;
+  let foeByteB = 0;
+  const tier1Index = TIER1_FOES.indexOf(config.foes[0]);
+  const tier2Index = TIER2_FOES.indexOf(config.foes[1]);
+  const tier3Index = TIER3_FOES.indexOf(config.foes[2]);
+  if (tier1Index < 0) throw new Error(`Invalid Tier 1 foe: ${config.foes[0]}`);
+  if (tier2Index < 0) throw new Error(`Invalid Tier 2 foe: ${config.foes[1]}`);
+  if (tier3Index < 0) throw new Error(`Invalid Tier 3 foe: ${config.foes[2]}`);
+  foeByteA = tier1Index & 3;
+  foeByteA |= (tier2Index & 3) << 2;
+  foeByteA |= (tier3Index & 1) << 4;
+  foeByteB |= (tier3Index >> 1 & 1) << 4;
+  const adversaryIndex = ADVERSARIES.indexOf(config.adversary);
+  if (adversaryIndex < 0) throw new Error(`Invalid adversary: ${config.adversary}`);
+  foeByteB |= adversaryIndex & 15;
+  const allyIndex = ALLIES.indexOf(config.ally);
+  if (allyIndex < 0) throw new Error(`Invalid ally: ${config.ally}`);
+  let extraByte = 0;
+  if (config.difficulty === "Gritty") extraByte |= 1;
+  for (const expansion of config.expansions) {
+    switch (expansion) {
+      case "Monuments":
+        extraByte |= 2;
+        break;
+      case "Alliances":
+        extraByte |= 4;
+        break;
+    }
+  }
+  if (config.source === "Competitive") extraByte |= 8;
+  const versionByte = 0;
+  const playerCountByte = Math.max(0, Math.min(3, config.playerCount - 1));
+  let seedStr = valueToChar(foeByteA) + valueToChar(foeByteB) + valueToChar(allyIndex) + valueToChar(extraByte) + valueToChar(versionByte) + valueToChar(playerCountByte);
+  let remaining = rngValue;
+  for (let i = 0; i < RNG_SEED_LENGTH; i++) {
+    const digit = remaining % BASE;
+    seedStr += valueToChar(digit);
+    remaining = Math.floor(remaining / BASE);
+  }
+  const upper = seedStr.toUpperCase();
+  return `${upper.slice(0, 4)}-${upper.slice(4, 8)}-${upper.slice(8, 12)}`;
+}
+function compareSeedsRaw(seed1, seed2) {
+  const n1 = validateSeed(seed1);
+  const n2 = validateSeed(seed2);
+  const s1 = n1.replace(/-/g, "").toLowerCase();
+  const s2 = n2.replace(/-/g, "").toLowerCase();
+  const diffs = [];
+  for (let i = 0; i < SEED_LENGTH; i++) {
+    const v1 = charToValue(s1[i]);
+    const v2 = charToValue(s2[i]);
+    if (v1 !== v2) {
+      diffs.push({
+        charIndex: i,
+        value1: v1,
+        value2: v2,
+        char1: s1[i],
+        char2: s2[i]
+      });
+    }
+  }
+  return {
+    seed1: n1,
+    seed2: n2,
+    diffs,
+    setupDiffs: diffs.filter((d) => d.charIndex < SETUP_LENGTH),
+    rngDiffs: diffs.filter((d) => d.charIndex >= SETUP_LENGTH)
+  };
+}
+var SETUP_FIELD_LABELS = {
+  0: "Tier1/Tier2/Tier3lo",
+  1: "Adversary/Tier3hi",
+  2: "Ally",
+  3: "Difficulty/Expansions/Source",
+  4: "Version",
+  5: "PlayerCount"
+};
+function dumpSeedChars(seed) {
+  const normalized = validateSeed(seed);
+  const stripped = normalized.replace(/-/g, "").toLowerCase();
+  const chars = [];
+  for (let i = 0; i < SEED_LENGTH; i++) {
+    const isSetup = i < SETUP_LENGTH;
+    chars.push({
+      index: i,
+      char: stripped[i],
+      value: charToValue(stripped[i]),
+      section: isSetup ? "setup" : "rng",
+      field: isSetup ? SETUP_FIELD_LABELS[i] : void 0
+    });
+  }
+  return { seed: normalized, chars };
+}
+
+// src/udtSystemRandom.ts
+var INT32_MAX = 2147483647;
+var MSEED = 161803398;
+function toInt32(n) {
+  return n | 0;
+}
+var SystemRandom = class {
+  /**
+   * Create a new PRNG instance with the given seed.
+   * Matches C# `new System.Random(seed)` exactly.
+   */
+  constructor(seed) {
+    this.seedArray = new Array(56).fill(0);
+    this.inext = 0;
+    this.inextp = 0;
+    this.initialize(seed);
+  }
+  /**
+   * Replicate .NET's System.Random constructor seeding algorithm.
+   */
+  initialize(seed) {
+    let subtraction;
+    if (seed === -2147483648) {
+      subtraction = INT32_MAX;
+    } else {
+      subtraction = Math.abs(seed);
+    }
+    let mj = toInt32(MSEED - subtraction);
+    this.seedArray[55] = mj;
+    let mk = 1;
+    for (let i = 1; i < 55; i++) {
+      const ii = 21 * i % 55;
+      this.seedArray[ii] = mk;
+      mk = toInt32(mj - mk);
+      if (mk < 0) mk = toInt32(mk + INT32_MAX);
+      mj = this.seedArray[ii];
+    }
+    for (let k = 1; k < 5; k++) {
+      for (let i = 1; i < 56; i++) {
+        this.seedArray[i] = toInt32(this.seedArray[i] - this.seedArray[1 + (i + 30) % 55]);
+        if (this.seedArray[i] < 0) {
+          this.seedArray[i] = toInt32(this.seedArray[i] + INT32_MAX);
+        }
+      }
+    }
+    this.inext = 0;
+    this.inextp = 21;
+  }
+  /**
+   * Internal sample — returns value in range [0, Int32.MaxValue).
+   * Matches C#'s InternalSample().
+   */
+  internalSample() {
+    let retVal;
+    let locINext = this.inext;
+    let locINextp = this.inextp;
+    if (++locINext >= 56) locINext = 1;
+    if (++locINextp >= 56) locINextp = 1;
+    retVal = toInt32(this.seedArray[locINext] - this.seedArray[locINextp]);
+    if (retVal === INT32_MAX) retVal--;
+    if (retVal < 0) retVal = toInt32(retVal + INT32_MAX);
+    this.seedArray[locINext] = retVal;
+    this.inext = locINext;
+    this.inextp = locINextp;
+    return retVal;
+  }
+  /**
+   * Sample — returns a double in range [0.0, 1.0).
+   * Matches C#'s Sample().
+   */
+  sample() {
+    return this.internalSample() * (1 / INT32_MAX);
+  }
+  /**
+   * Returns a non-negative random integer less than Int32.MaxValue.
+   * Matches C# `Random.Next()`.
+   */
+  next() {
+    return this.internalSample();
+  }
+  /**
+   * Returns a non-negative random integer less than maxValue.
+   * Matches C# `Random.Next(maxValue)`.
+   */
+  nextMax(maxValue) {
+    if (maxValue < 0) {
+      throw new Error("maxValue must be non-negative");
+    }
+    return toInt32(this.sample() * maxValue);
+  }
+  /**
+   * Returns a random integer in range [minValue, maxValue).
+   * Matches C# `Random.Next(minValue, maxValue)`.
+   */
+  nextRange(minValue, maxValue) {
+    if (minValue > maxValue) {
+      throw new Error("minValue must be less than or equal to maxValue");
+    }
+    const range = maxValue - minValue;
+    if (range <= INT32_MAX) {
+      return toInt32(this.sample() * range) + minValue;
+    }
+    return toInt32(this.internalSample() * (1 / INT32_MAX) * range) + minValue;
+  }
+  /**
+   * Returns a random double in range [0.0, 1.0).
+   * Matches C# `Random.NextDouble()`.
+   */
+  nextDouble() {
+    return this.sample();
+  }
+};
+
+// src/udtGameBoard.ts
+var BOARD_GROUPINGS = {
+  /** Dayside and Fivepint (North kingdom lakes). */
+  LONG_WATER: "Long Water",
+  /** Delmsmire, Arkartus, and Yellowpike (West kingdom forests). */
+  THE_GREAT_WOODS: "The Great Woods",
+  /** The Throne, The Cloister, and Archmont (South kingdom grasslands). */
+  REGAL_RUN: "Regal Run"
+};
+var BOARD_LOCATIONS = [
+  // ── North ───────────────────────────────────────────────────────────────
+  { name: "Broken Lands", terrain: "Hills", kingdom: "north" },
+  { name: "Dayside", terrain: "Lake", building: "Bazaar", kingdom: "north", grouping: BOARD_GROUPINGS.LONG_WATER },
+  { name: "Egan's End", terrain: "Grasslands", building: "Village", kingdom: "north" },
+  { name: "Fivepint", terrain: "Lake", kingdom: "north", grouping: BOARD_GROUPINGS.LONG_WATER },
+  { name: "Green Bridge", terrain: "Grasslands", kingdom: "north" },
+  { name: "Lodestone Mountains", terrain: "Mountains", kingdom: "north" },
+  { name: "Lower Ice Fangs", terrain: "Mountains", kingdom: "north" },
+  { name: "Muted Forest", terrain: "Forest", kingdom: "north" },
+  { name: "Peaks of the Djinn", terrain: "Mountains", kingdom: "north" },
+  { name: "Pearl of the North", terrain: "Grasslands", kingdom: "north" },
+  { name: "Radiant Mountains", terrain: "Mountains", building: "Citadel", kingdom: "north" },
+  { name: "Rimeweald", terrain: "Forest", kingdom: "north" },
+  { name: "The Tundra", terrain: "Desert", kingdom: "north" },
+  { name: "Tower Scar Desert", terrain: "Desert", kingdom: "north" },
+  { name: "Upper Ice Fangs", terrain: "Mountains", building: "Sanctuary", kingdom: "north" },
+  // ── East ────────────────────────────────────────────────────────────────
+  { name: "Big Sister", terrain: "Mountains", kingdom: "east" },
+  { name: "Bleak Wastes", terrain: "Desert", kingdom: "east" },
+  { name: "Copper Grove", terrain: "Forest", kingdom: "east" },
+  { name: "Dragontooth Lake", terrain: "Lake", kingdom: "east" },
+  { name: "Duwani", terrain: "Grasslands", building: "Village", kingdom: "east" },
+  { name: "Forest of Shades", terrain: "Forest", kingdom: "east" },
+  { name: "Greater Tombstones", terrain: "Hills", building: "Sanctuary", kingdom: "east" },
+  { name: "Inner Kinghills", terrain: "Hills", building: "Citadel", kingdom: "east" },
+  { name: "Jewel Hills", terrain: "Hills", kingdom: "east" },
+  { name: "Lake of Songs", terrain: "Lake", kingdom: "east" },
+  { name: "Lesser Tombstones", terrain: "Hills", kingdom: "east" },
+  { name: "Outer Kinghills", terrain: "Hills", kingdom: "east" },
+  { name: "The Decaying Wilds", terrain: "Grasslands", kingdom: "east" },
+  { name: "Three Rivers", terrain: "Grasslands", building: "Bazaar", kingdom: "east" },
+  { name: "Utar's Barrows", terrain: "Desert", kingdom: "east" },
+  // ── West ────────────────────────────────────────────────────────────────
+  { name: "Anza", terrain: "Grasslands", building: "Village", kingdom: "west" },
+  { name: "Arkartus", terrain: "Forest", building: "Sanctuary", kingdom: "west", grouping: BOARD_GROUPINGS.THE_GREAT_WOODS },
+  { name: "Ash Hills", terrain: "Hills", kingdom: "west" },
+  { name: "Cloudhold", terrain: "Mountains", kingdom: "west" },
+  { name: "Delmsmire", terrain: "Forest", kingdom: "west", grouping: BOARD_GROUPINGS.THE_GREAT_WOODS },
+  { name: "Hissing Groves", terrain: "Forest", building: "Citadel", kingdom: "west" },
+  { name: "Idran Forest", terrain: "Forest", kingdom: "west" },
+  { name: "Lonelight Hills", terrain: "Hills", kingdom: "west" },
+  { name: "Lost Lands", terrain: "Desert", kingdom: "west" },
+  { name: "Plains of Plovo", terrain: "Grasslands", building: "Bazaar", kingdom: "west" },
+  { name: "Plains of Woldra", terrain: "Grasslands", kingdom: "west" },
+  { name: "The Empty Glade", terrain: "Grasslands", kingdom: "west" },
+  { name: "The Grass Sea", terrain: "Grasslands", kingdom: "west" },
+  { name: "Weeping Waters", terrain: "Lake", kingdom: "west" },
+  { name: "Yellowpike", terrain: "Forest", kingdom: "west", grouping: BOARD_GROUPINGS.THE_GREAT_WOODS },
+  // ── South ───────────────────────────────────────────────────────────────
+  { name: "Archmont", terrain: "Grasslands", kingdom: "south", grouping: BOARD_GROUPINGS.REGAL_RUN },
+  { name: "Azkol's Bane", terrain: "Desert", kingdom: "south" },
+  { name: "Bone Hills", terrain: "Hills", kingdom: "south" },
+  { name: "Howling Desert", terrain: "Desert", building: "Citadel", kingdom: "south" },
+  { name: "Irontops", terrain: "Mountains", kingdom: "south" },
+  { name: "Little Sister", terrain: "Mountains", kingdom: "south" },
+  { name: "Middle Sister", terrain: "Mountains", kingdom: "south" },
+  { name: "Mountains of the Watchers", terrain: "Mountains", kingdom: "south" },
+  { name: "Pine Barrens", terrain: "Forest", kingdom: "south" },
+  { name: "Sands of Madness", terrain: "Desert", building: "Sanctuary", kingdom: "south" },
+  { name: "Southern Wastes", terrain: "Desert", building: "Village", kingdom: "south" },
+  { name: "The Cloister", terrain: "Grasslands", kingdom: "south", grouping: BOARD_GROUPINGS.REGAL_RUN },
+  { name: "The Emerald Expanse", terrain: "Grasslands", building: "Bazaar", kingdom: "south" },
+  { name: "The Throne", terrain: "Grasslands", kingdom: "south", grouping: BOARD_GROUPINGS.REGAL_RUN },
+  { name: "Ulamel's Hollow", terrain: "Grasslands", kingdom: "south" }
+];
+var BOARD_LOCATION_BY_NAME = Object.fromEntries(BOARD_LOCATIONS.map((loc) => [loc.name, loc]));
+
+// src/index.ts
 var index_default = UltimateDarkTower_default;
 export {
+  ADVERSARIES,
+  ALLIES,
   AUDIO_COMMAND_POS,
   BATTERY_STATUS_FREQUENCY,
+  BOARD_GROUPINGS,
+  BOARD_LOCATIONS,
+  BOARD_LOCATION_BY_NAME,
   BluetoothAdapterFactory,
   BluetoothConnectionError,
   BluetoothDeviceNotFoundError,
@@ -3573,6 +4548,7 @@ export {
   DEFAULT_CONNECTION_MONITORING_FREQUENCY,
   DEFAULT_CONNECTION_MONITORING_TIMEOUT,
   DEFAULT_RETRY_SEND_COMMAND_MAX,
+  DIFFICULTIES,
   DIS_FIRMWARE_REVISION_UUID,
   DIS_HARDWARE_REVISION_UUID,
   DIS_IEEE_REGULATORY_UUID,
@@ -3585,7 +4561,10 @@ export {
   DIS_SYSTEM_ID_UUID,
   DOMOutput,
   DRUM_PACKETS,
+  GAME_SOURCES,
   GLYPHS,
+  InMemorySink,
+  IndexedDBSink,
   LAYER_TO_POSITION,
   LEDGE_BASE_LIGHT_POSITIONS,
   LED_CHANNEL_LOOKUP,
@@ -3595,7 +4574,11 @@ export {
   RING_LIGHT_POSITIONS,
   SKULL_DROP_COUNT_POS,
   STATE_DATA_LENGTH,
+  SystemRandom,
   TC,
+  TIER1_FOES,
+  TIER2_FOES,
+  TIER3_FOES,
   TOWER_AUDIO_LIBRARY,
   TOWER_COMMANDS,
   TOWER_COMMAND_HEADER_SIZE,
@@ -3612,18 +4595,29 @@ export {
   UART_RX_CHARACTERISTIC_UUID,
   UART_SERVICE_UUID,
   UART_TX_CHARACTERISTIC_UUID,
+  UdtDiagnosticsRecorder,
   UltimateDarkTower_default as UltimateDarkTower,
   VOLTAGE_LEVELS,
   VOLUME_DESCRIPTIONS,
   VOLUME_ICONS,
+  bytesToHex,
+  charToValue,
+  compareSeedsRaw,
   createDefaultTowerState,
+  createSeed,
+  decodeRngSeed,
+  decodeSeed,
   index_default as default,
   drumPositionCmds,
+  dumpSeedChars,
+  encodeSeed,
   isCalibrated,
   logger,
   milliVoltsToPercentage,
   milliVoltsToPercentageNumber,
   parseDifferentialReadings,
   rtdt_pack_state,
-  rtdt_unpack_state
+  rtdt_unpack_state,
+  validateSeed,
+  valueToChar
 };