jmri-client 4.2.0-beta.2 → 5.0.0

package/dist/cjs/index.js

@@ -1,32 +1,2383 @@
 "use strict";
-/**
- * jmri-client v3.0
- * WebSocket client for JMRI with real-time updates and throttle control
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.mockData = exports.mockResponseManager = exports.MockResponseManager = exports.lightStateToString = exports.turnoutStateToString = exports.powerStateToString = exports.isValidSpeed = exports.isThrottleFunctionKey = exports.ConnectionState = exports.LightState = exports.TurnoutState = exports.PowerState = exports.WebSocketClient = exports.JmriClient = void 0;
-var client_js_1 = require("./client.js");
-Object.defineProperty(exports, "JmriClient", { enumerable: true, get: function () { return client_js_1.JmriClient; } });
-var websocket_client_js_1 = require("./core/websocket-client.js");
-Object.defineProperty(exports, "WebSocketClient", { enumerable: true, get: function () { return websocket_client_js_1.WebSocketClient; } });
-// Export types
-var index_js_1 = require("./types/index.js");
-// JMRI message types
-Object.defineProperty(exports, "PowerState", { enumerable: true, get: function () { return index_js_1.PowerState; } });
-Object.defineProperty(exports, "TurnoutState", { enumerable: true, get: function () { return index_js_1.TurnoutState; } });
-Object.defineProperty(exports, "LightState", { enumerable: true, get: function () { return index_js_1.LightState; } });
-// Event types
-Object.defineProperty(exports, "ConnectionState", { enumerable: true, get: function () { return index_js_1.ConnectionState; } });
-// Export utility functions
-var throttle_js_1 = require("./types/throttle.js");
-Object.defineProperty(exports, "isThrottleFunctionKey", { enumerable: true, get: function () { return throttle_js_1.isThrottleFunctionKey; } });
-Object.defineProperty(exports, "isValidSpeed", { enumerable: true, get: function () { return throttle_js_1.isValidSpeed; } });
-var jmri_messages_js_1 = require("./types/jmri-messages.js");
-Object.defineProperty(exports, "powerStateToString", { enumerable: true, get: function () { return jmri_messages_js_1.powerStateToString; } });
-Object.defineProperty(exports, "turnoutStateToString", { enumerable: true, get: function () { return jmri_messages_js_1.turnoutStateToString; } });
-Object.defineProperty(exports, "lightStateToString", { enumerable: true, get: function () { return jmri_messages_js_1.lightStateToString; } });
-// Export mock system for testing and demo purposes
-var index_js_2 = require("./mocks/index.js");
-Object.defineProperty(exports, "MockResponseManager", { enumerable: true, get: function () { return index_js_2.MockResponseManager; } });
-Object.defineProperty(exports, "mockResponseManager", { enumerable: true, get: function () { return index_js_2.mockResponseManager; } });
-Object.defineProperty(exports, "mockData", { enumerable: true, get: function () { return index_js_2.mockData; } });
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ConnectionState: () => ConnectionState,
+  JmriClient: () => JmriClient,
+  LightState: () => LightState,
+  MockResponseManager: () => MockResponseManager,
+  PowerState: () => PowerState,
+  TurnoutState: () => TurnoutState,
+  WebSocketClient: () => WebSocketClient,
+  isThrottleFunctionKey: () => isThrottleFunctionKey,
+  isValidSpeed: () => isValidSpeed,
+  lightStateToString: () => lightStateToString,
+  mockData: () => mockData,
+  mockResponseManager: () => mockResponseManager,
+  powerStateToString: () => powerStateToString,
+  turnoutStateToString: () => turnoutStateToString
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_eventemitter310 = require("eventemitter3");
+
+// src/core/websocket-client.ts
+var import_eventemitter35 = require("eventemitter3");
+
+// src/core/websocket-adapter.ts
+var import_eventemitter3 = require("eventemitter3");
+async function createWebSocketAdapter(url, protocols) {
+  const isBrowser = typeof window !== "undefined" && typeof window.WebSocket !== "undefined";
+  if (isBrowser) {
+    return new BrowserWebSocketAdapter(url, protocols);
+  } else {
+    return await NodeWebSocketAdapter.create(url, protocols);
+  }
+}
+var BrowserWebSocketAdapter = class extends import_eventemitter3.EventEmitter {
+  constructor(url, protocols) {
+    super();
+    this.ws = new WebSocket(url, protocols);
+    this.ws.onopen = () => {
+      this.emit("open");
+    };
+    this.ws.onmessage = (event) => {
+      this.emit("message", event.data);
+    };
+    this.ws.onerror = () => {
+      this.emit("error", new Error("WebSocket error"));
+    };
+    this.ws.onclose = (event) => {
+      this.emit("close", event.code, event.reason);
+    };
+  }
+  send(data) {
+    this.ws.send(data);
+  }
+  close(code, reason) {
+    this.ws.close(code, reason);
+  }
+  get readyState() {
+    return this.ws.readyState;
+  }
+};
+var NodeWebSocketAdapter = class _NodeWebSocketAdapter extends import_eventemitter3.EventEmitter {
+  constructor(ws) {
+    super();
+    this.ws = ws;
+    this.ws.on("open", () => {
+      this.emit("open");
+    });
+    this.ws.on("message", (data) => {
+      const message = typeof data === "string" ? data : data.toString();
+      this.emit("message", message);
+    });
+    this.ws.on("error", (error) => {
+      this.emit("error", error);
+    });
+    this.ws.on("close", (code, reason) => {
+      this.emit("close", code, reason);
+    });
+  }
+  static async create(url, protocols) {
+    const { default: WebSocket2 } = await import("ws");
+    const ws = new WebSocket2(url, protocols);
+    return new _NodeWebSocketAdapter(ws);
+  }
+  send(data) {
+    this.ws.send(data);
+  }
+  close(code, reason) {
+    this.ws.close(code, reason);
+  }
+  get readyState() {
+    return this.ws.readyState;
+  }
+};
+
+// src/types/events.ts
+var ConnectionState = /* @__PURE__ */ ((ConnectionState2) => {
+  ConnectionState2["DISCONNECTED"] = "disconnected";
+  ConnectionState2["CONNECTING"] = "connecting";
+  ConnectionState2["CONNECTED"] = "connected";
+  ConnectionState2["RECONNECTING"] = "reconnecting";
+  return ConnectionState2;
+})(ConnectionState || {});
+
+// src/utils/message-id.ts
+var MessageIdGenerator = class {
+  constructor() {
+    this.currentId = 0;
+    this.maxId = Number.MAX_SAFE_INTEGER;
+  }
+  /**
+   * Generate next sequential ID
+   * Wraps around at MAX_SAFE_INTEGER
+   */
+  next() {
+    this.currentId++;
+    if (this.currentId >= this.maxId) {
+      this.currentId = 1;
+    }
+    return this.currentId;
+  }
+  /**
+   * Reset ID counter to 0
+   */
+  reset() {
+    this.currentId = 0;
+  }
+  /**
+   * Get current ID without incrementing
+   */
+  current() {
+    return this.currentId;
+  }
+};
+
+// src/core/message-queue.ts
+var MessageQueue = class {
+  constructor(maxSize = 100) {
+    this.queue = [];
+    this.maxSize = maxSize;
+  }
+  /**
+   * Add message to queue
+   * If queue is full, oldest message is removed
+   */
+  enqueue(message) {
+    if (this.queue.length >= this.maxSize) {
+      this.queue.shift();
+    }
+    this.queue.push(message);
+  }
+  /**
+   * Get all queued messages and clear queue
+   */
+  flush() {
+    const messages = [...this.queue];
+    this.queue = [];
+    return messages;
+  }
+  /**
+   * Clear all queued messages without returning them
+   */
+  clear() {
+    this.queue = [];
+  }
+  /**
+   * Get number of queued messages
+   */
+  size() {
+    return this.queue.length;
+  }
+  /**
+   * Check if queue is empty
+   */
+  isEmpty() {
+    return this.queue.length === 0;
+  }
+  /**
+   * Check if queue is full
+   */
+  isFull() {
+    return this.queue.length >= this.maxSize;
+  }
+};
+
+// src/core/connection-state-manager.ts
+var import_eventemitter32 = require("eventemitter3");
+var VALID_TRANSITIONS = {
+  ["disconnected" /* DISCONNECTED */]: ["connecting" /* CONNECTING */],
+  ["connecting" /* CONNECTING */]: ["connected" /* CONNECTED */, "disconnected" /* DISCONNECTED */],
+  ["connected" /* CONNECTED */]: ["disconnected" /* DISCONNECTED */, "reconnecting" /* RECONNECTING */],
+  ["reconnecting" /* RECONNECTING */]: ["connecting" /* CONNECTING */, "connected" /* CONNECTED */, "disconnected" /* DISCONNECTED */]
+};
+var ConnectionStateManager = class extends import_eventemitter32.EventEmitter {
+  constructor() {
+    super(...arguments);
+    this.currentState = "disconnected" /* DISCONNECTED */;
+  }
+  /**
+   * Get current connection state
+   */
+  getState() {
+    return this.currentState;
+  }
+  /**
+   * Check if currently connected
+   */
+  isConnected() {
+    return this.currentState === "connected" /* CONNECTED */;
+  }
+  /**
+   * Check if currently connecting
+   */
+  isConnecting() {
+    return this.currentState === "connecting" /* CONNECTING */;
+  }
+  /**
+   * Check if currently disconnected
+   */
+  isDisconnected() {
+    return this.currentState === "disconnected" /* DISCONNECTED */;
+  }
+  /**
+   * Check if currently reconnecting
+   */
+  isReconnecting() {
+    return this.currentState === "reconnecting" /* RECONNECTING */;
+  }
+  /**
+   * Transition to new state
+   * Validates transition and emits event
+   */
+  transition(newState) {
+    const validTransitions = VALID_TRANSITIONS[this.currentState];
+    if (!validTransitions.includes(newState)) {
+      throw new Error(
+        `Invalid state transition: ${this.currentState} -> ${newState}`
+      );
+    }
+    const previousState = this.currentState;
+    this.currentState = newState;
+    this.emit("stateChanged", newState, previousState);
+  }
+  /**
+   * Force state without validation (use with caution)
+   */
+  forceState(newState) {
+    const previousState = this.currentState;
+    this.currentState = newState;
+    this.emit("stateChanged", newState, previousState);
+  }
+  /**
+   * Reset to disconnected state
+   */
+  reset() {
+    this.forceState("disconnected" /* DISCONNECTED */);
+  }
+};
+
+// src/core/heartbeat-manager.ts
+var import_eventemitter33 = require("eventemitter3");
+var HeartbeatManager = class extends import_eventemitter33.EventEmitter {
+  constructor(options) {
+    super();
+    this.isRunning = false;
+    this.options = options;
+  }
+  /**
+   * Start heartbeat monitoring
+   * @param sendPing - Callback to send ping message
+   */
+  start(sendPing) {
+    if (!this.options.enabled || this.isRunning) {
+      return;
+    }
+    this.isRunning = true;
+    this.pingInterval = setInterval(() => {
+      sendPing();
+      this.emit("pingSent");
+      this.pongTimeout = setTimeout(() => {
+        this.emit("timeout");
+      }, this.options.timeout);
+    }, this.options.interval);
+  }
+  /**
+   * Stop heartbeat monitoring
+   */
+  stop() {
+    this.isRunning = false;
+    if (this.pingInterval) {
+      clearInterval(this.pingInterval);
+      this.pingInterval = void 0;
+    }
+    if (this.pongTimeout) {
+      clearTimeout(this.pongTimeout);
+      this.pongTimeout = void 0;
+    }
+  }
+  /**
+   * Handle pong received from server
+   */
+  receivedPong() {
+    if (this.pongTimeout) {
+      clearTimeout(this.pongTimeout);
+      this.pongTimeout = void 0;
+    }
+    this.emit("pongReceived");
+  }
+  /**
+   * Check if heartbeat is running
+   */
+  running() {
+    return this.isRunning;
+  }
+  /**
+   * Update heartbeat options
+   */
+  updateOptions(options) {
+    const wasRunning = this.isRunning;
+    if (wasRunning) {
+      this.stop();
+    }
+    this.options = { ...this.options, ...options };
+  }
+};
+
+// src/core/reconnection-manager.ts
+var import_eventemitter34 = require("eventemitter3");
+
+// src/utils/exponential-backoff.ts
+function calculateBackoffDelay(attempt, options) {
+  const exponentialDelay = options.initialDelay * Math.pow(options.multiplier, attempt - 1);
+  const cappedDelay = Math.min(exponentialDelay, options.maxDelay);
+  if (options.jitter) {
+    const jitterAmount = cappedDelay * 0.25;
+    const jitter = (Math.random() * 2 - 1) * jitterAmount;
+    return Math.max(0, Math.round(cappedDelay + jitter));
+  }
+  return Math.round(cappedDelay);
+}
+function shouldReconnect(attempt, maxAttempts) {
+  if (maxAttempts === 0) {
+    return true;
+  }
+  return attempt <= maxAttempts;
+}
+
+// src/core/reconnection-manager.ts
+var ReconnectionManager = class extends import_eventemitter34.EventEmitter {
+  constructor(options) {
+    super();
+    this.currentAttempt = 0;
+    this.isReconnecting = false;
+    this.options = options;
+  }
+  /**
+   * Start reconnection process
+   * @param reconnect - Callback to attempt reconnection
+   */
+  start(reconnect) {
+    if (!this.options.enabled || this.isReconnecting) {
+      return;
+    }
+    this.isReconnecting = true;
+    this.currentAttempt = 0;
+    this.scheduleNextAttempt(reconnect);
+  }
+  /**
+   * Schedule next reconnection attempt
+   */
+  scheduleNextAttempt(reconnect) {
+    this.currentAttempt++;
+    if (!shouldReconnect(this.currentAttempt, this.options.maxAttempts)) {
+      this.emit("maxAttemptsReached", this.currentAttempt - 1);
+      this.stop();
+      return;
+    }
+    const delay = calculateBackoffDelay(this.currentAttempt, this.options);
+    this.emit("attemptScheduled", this.currentAttempt, delay);
+    this.reconnectTimeout = setTimeout(async () => {
+      this.emit("attempting", this.currentAttempt);
+      try {
+        await reconnect();
+        this.stop();
+        this.emit("success", this.currentAttempt);
+      } catch (error) {
+        this.emit("failed", this.currentAttempt, error);
+        this.scheduleNextAttempt(reconnect);
+      }
+    }, delay);
+  }
+  /**
+   * Stop reconnection process
+   */
+  stop() {
+    this.isReconnecting = false;
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = void 0;
+    }
+  }
+  /**
+   * Reset attempt counter
+   */
+  reset() {
+    this.stop();
+    this.currentAttempt = 0;
+  }
+  /**
+   * Check if currently reconnecting
+   */
+  reconnecting() {
+    return this.isReconnecting;
+  }
+  /**
+   * Get current attempt number
+   */
+  getAttempt() {
+    return this.currentAttempt;
+  }
+  /**
+   * Update reconnection options
+   */
+  updateOptions(options) {
+    this.options = { ...this.options, ...options };
+  }
+};
+
+// src/types/jmri-messages.ts
+var PowerState = /* @__PURE__ */ ((PowerState2) => {
+  PowerState2[PowerState2["UNKNOWN"] = 0] = "UNKNOWN";
+  PowerState2[PowerState2["ON"] = 2] = "ON";
+  PowerState2[PowerState2["OFF"] = 4] = "OFF";
+  return PowerState2;
+})(PowerState || {});
+function powerStateToString(state) {
+  switch (state) {
+    case 2 /* ON */:
+      return "ON";
+    case 4 /* OFF */:
+      return "OFF";
+    case 0 /* UNKNOWN */:
+      return "UNKNOWN";
+    default:
+      return "UNKNOWN";
+  }
+}
+var TurnoutState = /* @__PURE__ */ ((TurnoutState2) => {
+  TurnoutState2[TurnoutState2["UNKNOWN"] = 0] = "UNKNOWN";
+  TurnoutState2[TurnoutState2["CLOSED"] = 2] = "CLOSED";
+  TurnoutState2[TurnoutState2["THROWN"] = 4] = "THROWN";
+  TurnoutState2[TurnoutState2["INCONSISTENT"] = 8] = "INCONSISTENT";
+  return TurnoutState2;
+})(TurnoutState || {});
+function turnoutStateToString(state) {
+  switch (state) {
+    case 2 /* CLOSED */:
+      return "CLOSED";
+    case 4 /* THROWN */:
+      return "THROWN";
+    case 8 /* INCONSISTENT */:
+      return "INCONSISTENT";
+    case 0 /* UNKNOWN */:
+    default:
+      return "UNKNOWN";
+  }
+}
+var LightState = /* @__PURE__ */ ((LightState2) => {
+  LightState2[LightState2["UNKNOWN"] = 0] = "UNKNOWN";
+  LightState2[LightState2["ON"] = 2] = "ON";
+  LightState2[LightState2["OFF"] = 4] = "OFF";
+  return LightState2;
+})(LightState || {});
+function lightStateToString(state) {
+  switch (state) {
+    case 2 /* ON */:
+      return "ON";
+    case 4 /* OFF */:
+      return "OFF";
+    case 0 /* UNKNOWN */:
+    default:
+      return "UNKNOWN";
+  }
+}
+
+// src/mocks/mock-data.ts
+var mockData = {
+  "hello": {
+    "type": "hello",
+    "data": {
+      "JMRI": "5.9.2",
+      "json": "5.0",
+      "version": "v5",
+      "heartbeat": 13500,
+      "railroad": "Demo Railroad",
+      "node": "jmri-server",
+      "activeProfile": "Demo Profile"
+    }
+  },
+  "power": {
+    "get": {
+      "on": {
+        "type": "power",
+        "data": {
+          "state": 2
+        }
+      },
+      "off": {
+        "type": "power",
+        "data": {
+          "state": 4
+        }
+      }
+    },
+    "post": {
+      "success": {
+        "type": "power",
+        "data": {
+          "state": 2
+        }
+      }
+    }
+  },
+  "roster": {
+    "list": [
+      {
+        "type": "rosterEntry",
+        "data": {
+          "name": "CSX754",
+          "address": "754",
+          "isLongAddress": true,
+          "road": "CSX",
+          "number": "754",
+          "mfg": "Athearn",
+          "decoderModel": "DH163D",
+          "decoderFamily": "Digitrax DH163",
+          "model": "GP38-2",
+          "comment": "Blue and yellow scheme",
+          "maxSpeedPct": 100,
+          "image": null,
+          "icon": "/roster/CSX754/icon",
+          "shuntingFunction": "",
+          "owner": "",
+          "dateModified": "2026-02-10T00:00:00.000+00:00",
+          "functionKeys": [
+            { "name": "F0", "label": "Headlight", "lockable": true, "icon": null, "selectedIcon": null },
+            { "name": "F1", "label": "Bell", "lockable": true, "icon": null, "selectedIcon": null },
+            { "name": "F2", "label": "Horn", "lockable": false, "icon": null, "selectedIcon": null },
+            { "name": "F3", "label": null, "lockable": false, "icon": null, "selectedIcon": null },
+            { "name": "F4", "label": "Dynamic Brake", "lockable": true, "icon": null, "selectedIcon": null },
+            { "name": "F5", "label": null, "lockable": false, "icon": null, "selectedIcon": null }
+          ],
+          "attributes": [],
+          "rosterGroups": []
+        },
+        "id": 1
+      },
+      {
+        "type": "rosterEntry",
+        "data": {
+          "name": "UP3985",
+          "address": "3985",
+          "isLongAddress": true,
+          "road": "Union Pacific",
+          "number": "3985",
+          "mfg": "Rivarossi",
+          "decoderModel": "Sound decoder",
+          "decoderFamily": "ESU LokSound",
+          "model": "Challenger 4-6-6-4",
+          "comment": "Steam locomotive",
+          "maxSpeedPct": 100,
+          "image": null,
+          "icon": "/roster/UP3985/icon",
+          "shuntingFunction": "",
+          "owner": "",
+          "dateModified": "2026-02-10T00:00:00.000+00:00",
+          "functionKeys": [
+            { "name": "F0", "label": "Headlight", "lockable": true, "icon": null, "selectedIcon": null },
+            { "name": "F1", "label": "Bell", "lockable": true, "icon": null, "selectedIcon": null },
+            { "name": "F2", "label": "Whistle", "lockable": false, "icon": null, "selectedIcon": null },
+            { "name": "F3", "label": "Steam", "lockable": true, "icon": null, "selectedIcon": null },
+            { "name": "F4", "label": null, "lockable": false, "icon": null, "selectedIcon": null }
+          ],
+          "attributes": [],
+          "rosterGroups": []
+        },
+        "id": 2
+      },
+      {
+        "type": "rosterEntry",
+        "data": {
+          "name": "BNSF5240",
+          "address": "5240",
+          "isLongAddress": true,
+          "road": "BNSF",
+          "number": "5240",
+          "mfg": "Kato",
+          "decoderModel": "DCC Sound",
+          "decoderFamily": "Kato",
+          "model": "SD40-2",
+          "comment": "Heritage II paint",
+          "maxSpeedPct": 100,
+          "image": null,
+          "icon": "/roster/BNSF5240/icon",
+          "shuntingFunction": "",
+          "owner": "",
+          "dateModified": "2026-02-10T00:00:00.000+00:00",
+          "functionKeys": [
+            { "name": "F0", "label": "Headlight", "lockable": true, "icon": null, "selectedIcon": null },
+            { "name": "F1", "label": "Bell", "lockable": true, "icon": null, "selectedIcon": null },
+            { "name": "F2", "label": "Horn", "lockable": false, "icon": null, "selectedIcon": null },
+            { "name": "F3", "label": "Dynamic Brake", "lockable": true, "icon": null, "selectedIcon": null },
+            { "name": "F4", "label": null, "lockable": false, "icon": null, "selectedIcon": null },
+            { "name": "F5", "label": "Mars Light", "lockable": true, "icon": null, "selectedIcon": null }
+          ],
+          "attributes": [],
+          "rosterGroups": []
+        },
+        "id": 3
+      }
+    ]
+  },
+  "throttle": {
+    "acquire": {
+      "success": {
+        "type": "throttle",
+        "data": {
+          "throttle": "{THROTTLE_ID}",
+          "address": "{ADDRESS}",
+          "speed": 0,
+          "forward": true,
+          "F0": false,
+          "F1": false,
+          "F2": false,
+          "F3": false,
+          "F4": false
+        }
+      }
+    },
+    "release": {
+      "success": {
+        "type": "throttle",
+        "data": {}
+      }
+    },
+    "control": {
+      "speed": {
+        "type": "throttle",
+        "data": {
+          "throttle": "{THROTTLE_ID}",
+          "speed": "{SPEED}"
+        }
+      },
+      "direction": {
+        "type": "throttle",
+        "data": {
+          "throttle": "{THROTTLE_ID}",
+          "forward": "{FORWARD}"
+        }
+      },
+      "function": {
+        "type": "throttle",
+        "data": {
+          "throttle": "{THROTTLE_ID}",
+          "{FUNCTION}": "{VALUE}"
+        }
+      }
+    }
+  },
+  "light": {
+    "list": [
+      { "type": "light", "data": { "name": "IL1", "userName": "Yard Light", "comment": null, "properties": [], "state": 4 } },
+      { "type": "light", "data": { "name": "IL2", "userName": "Platform Light", "comment": null, "properties": [], "state": 4 } },
+      { "type": "light", "data": { "name": "IL3", "userName": "Signal Lamp", "comment": null, "properties": [], "state": 2 } }
+    ]
+  },
+  "turnout": {
+    "list": [
+      { "type": "turnout", "data": { "name": "LT1", "userName": "Main Diverge", "state": 2 } },
+      { "type": "turnout", "data": { "name": "LT2", "userName": "Yard Lead", "state": 2 } },
+      { "type": "turnout", "data": { "name": "LT3", "userName": "Siding Entry", "state": 4 } }
+    ]
+  },
+  "ping": {
+    "type": "ping"
+  },
+  "pong": {
+    "type": "pong"
+  },
+  "goodbye": {
+    "type": "goodbye"
+  },
+  "error": {
+    "throttleNotFound": {
+      "type": "error",
+      "data": {
+        "code": 404,
+        "message": "Throttle not found"
+      }
+    },
+    "invalidSpeed": {
+      "type": "error",
+      "data": {
+        "code": 400,
+        "message": "Invalid speed value"
+      }
+    },
+    "connectionError": {
+      "type": "error",
+      "data": {
+        "code": 500,
+        "message": "Connection error"
+      }
+    }
+  }
+};
+
+// src/mocks/mock-response-manager.ts
+var MockResponseManager = class {
+  constructor(options = {}) {
+    this.throttles = /* @__PURE__ */ new Map();
+    this.lights = /* @__PURE__ */ new Map([
+      ["IL1", 4 /* OFF */],
+      ["IL2", 4 /* OFF */],
+      ["IL3", 2 /* ON */]
+    ]);
+    this.turnouts = /* @__PURE__ */ new Map([
+      ["LT1", 2 /* CLOSED */],
+      ["LT2", 2 /* CLOSED */],
+      ["LT3", 4 /* THROWN */]
+    ]);
+    this.responseDelay = options.responseDelay ?? 50;
+    this.powerState = options.initialPowerState ?? 4 /* OFF */;
+  }
+  /**
+   * Get a mock response for a given message
+   */
+  async getMockResponse(message) {
+    if (this.responseDelay > 0) {
+      await this.delay(this.responseDelay);
+    }
+    switch (message.type) {
+      case "hello":
+        return this.getHelloResponse();
+      case "power":
+        return this.getPowerResponse(message);
+      case "roster":
+        return this.getRosterResponse(message);
+      case "throttle":
+        return this.getThrottleResponse(message);
+      case "light":
+        return this.getLightResponse(message);
+      case "turnout":
+        return this.getTurnoutResponse(message);
+      case "ping":
+        return this.getPingResponse();
+      case "goodbye":
+        return this.getGoodbyeResponse();
+      default:
+        return null;
+    }
+  }
+  /**
+   * Get hello response (connection establishment)
+   */
+  getHelloResponse() {
+    return JSON.parse(JSON.stringify(mockData.hello));
+  }
+  /**
+   * Get power response
+   */
+  getPowerResponse(message) {
+    if (message.data?.state !== void 0) {
+      this.powerState = message.data.state;
+      return {
+        type: "power",
+        data: { state: this.powerState }
+      };
+    }
+    return {
+      type: "power",
+      data: { state: this.powerState }
+    };
+  }
+  /**
+   * Get roster response
+   */
+  getRosterResponse(message) {
+    if (message.type === "roster" && message.method === "list") {
+      return {
+        type: "roster",
+        data: JSON.parse(JSON.stringify(mockData.roster.list))
+      };
+    }
+    return {
+      type: "roster",
+      data: []
+    };
+  }
+  /**
+   * Get throttle response
+   */
+  getThrottleResponse(message) {
+    const data = message.data || {};
+    if (data.address !== void 0 && !data.throttle) {
+      const throttleId = data.name || `MOCK-${data.address}`;
+      const throttleState = {
+        throttle: throttleId,
+        address: data.address,
+        speed: 0,
+        forward: true,
+        F0: false,
+        F1: false,
+        F2: false,
+        F3: false,
+        F4: false
+      };
+      this.throttles.set(throttleId, throttleState);
+      return {
+        type: "throttle",
+        data: { ...throttleState }
+      };
+    }
+    if (data.release !== void 0 && data.throttle) {
+      this.throttles.delete(data.throttle);
+      return {
+        type: "throttle",
+        data: {}
+      };
+    }
+    if (data.throttle) {
+      const throttleState = this.throttles.get(data.throttle);
+      if (!throttleState) {
+        const newState = {
+          throttle: data.throttle,
+          address: 0,
+          speed: 0,
+          forward: true
+        };
+        this.throttles.set(data.throttle, newState);
+        return {
+          type: "throttle",
+          data: { ...newState }
+        };
+      }
+      if (data.speed !== void 0) {
+        throttleState.speed = data.speed;
+      }
+      if (data.forward !== void 0) {
+        throttleState.forward = data.forward;
+      }
+      for (let i = 0; i <= 28; i++) {
+        const key = `F${i}`;
+        if (data[key] !== void 0) {
+          throttleState[key] = data[key];
+        }
+      }
+      return {
+        type: "throttle",
+        data: {}
+      };
+    }
+    return {
+      type: "throttle",
+      data: {}
+    };
+  }
+  /**
+   * Get light response
+   */
+  getLightResponse(message) {
+    if (message.method === "list") {
+      return {
+        type: "light",
+        data: JSON.parse(JSON.stringify(mockData.light.list))
+      };
+    }
+    const name = message.data?.name;
+    if (!name) {
+      return { type: "light", data: { name: "", state: 0 /* UNKNOWN */ } };
+    }
+    if (message.method === "post" && message.data?.state !== void 0) {
+      this.lights.set(name, message.data.state);
+    }
+    const state = this.lights.get(name) ?? 0 /* UNKNOWN */;
+    return { type: "light", data: { name, state } };
+  }
+  /**
+   * Get turnout response
+   */
+  getTurnoutResponse(message) {
+    if (message.method === "list") {
+      return {
+        type: "turnout",
+        data: JSON.parse(JSON.stringify(mockData.turnout.list))
+      };
+    }
+    const name = message.data?.name;
+    if (!name) {
+      return { type: "turnout", data: { name: "", state: 0 /* UNKNOWN */ } };
+    }
+    if (message.method === "post" && message.data?.state !== void 0) {
+      this.turnouts.set(name, message.data.state);
+    }
+    const state = this.turnouts.get(name) ?? 0 /* UNKNOWN */;
+    return { type: "turnout", data: { name, state } };
+  }
+  /**
+   * Get ping response (pong)
+   */
+  getPingResponse() {
+    return JSON.parse(JSON.stringify(mockData.pong));
+  }
+  /**
+   * Get goodbye response
+   */
+  getGoodbyeResponse() {
+    return JSON.parse(JSON.stringify(mockData.goodbye));
+  }
+  /**
+   * Get current power state
+   */
+  getPowerState() {
+    return this.powerState;
+  }
+  /**
+   * Set power state (for testing)
+   */
+  setPowerState(state) {
+    this.powerState = state;
+  }
+  /**
+   * Get all throttles (for testing)
+   */
+  getThrottles() {
+    return this.throttles;
+  }
+  /**
+   * Get all light states (for testing)
+   */
+  getLights() {
+    return this.lights;
+  }
+  /**
+   * Get all turnout states (for testing)
+   */
+  getTurnouts() {
+    return this.turnouts;
+  }
+  /**
+   * Reset all state (for testing)
+   */
+  reset() {
+    this.powerState = 4 /* OFF */;
+    this.throttles.clear();
+    this.lights = /* @__PURE__ */ new Map([
+      ["IL1", 4 /* OFF */],
+      ["IL2", 4 /* OFF */],
+      ["IL3", 2 /* ON */]
+    ]);
+    this.turnouts = /* @__PURE__ */ new Map([
+      ["LT1", 2 /* CLOSED */],
+      ["LT2", 2 /* CLOSED */],
+      ["LT3", 4 /* THROWN */]
+    ]);
+  }
+  /**
+   * Delay helper
+   */
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+var mockResponseManager = new MockResponseManager({ responseDelay: 0 });
+
+// src/core/websocket-client.ts
+var WebSocketClient = class extends import_eventemitter35.EventEmitter {
+  constructor(options) {
+    super();
+    // Request/response tracking
+    this.pendingRequests = /* @__PURE__ */ new Map();
+    // Connection state
+    this.isManualDisconnect = false;
+    this.options = options;
+    this.url = `${options.protocol}://${options.host}:${options.port}/json/`;
+    this.messageIdGen = new MessageIdGenerator();
+    this.messageQueue = new MessageQueue(options.messageQueueSize);
+    this.stateManager = new ConnectionStateManager();
+    this.heartbeatManager = new HeartbeatManager(options.heartbeat);
+    this.reconnectionManager = new ReconnectionManager(options.reconnection);
+    if (options.mock.enabled) {
+      this.mockManager = new MockResponseManager({
+        responseDelay: options.mock.responseDelay
+      });
+    }
+    this.stateManager.on("stateChanged", (newState, prevState) => {
+      this.emit("connectionStateChanged", newState, prevState);
+    });
+    this.heartbeatManager.on("timeout", () => {
+      this.emit("heartbeat:timeout");
+      this.handleHeartbeatTimeout();
+    });
+    this.heartbeatManager.on("pingSent", () => {
+      this.emit("heartbeat:sent");
+    });
+    this.reconnectionManager.on("attemptScheduled", (attempt, delay) => {
+      this.emit("reconnecting", attempt, delay);
+    });
+    this.reconnectionManager.on("success", () => {
+      this.emit("reconnected");
+    });
+    this.reconnectionManager.on("maxAttemptsReached", (attempts) => {
+      this.emit("reconnectionFailed", attempts);
+    });
+    this.reconnectionManager.on("debug", (message) => {
+      this.emit("debug", message);
+    });
+  }
+  /**
+   * Connect to JMRI WebSocket server (or mock)
+   */
+  async connect() {
+    if (this.stateManager.isConnected() || this.stateManager.isConnecting()) {
+      return;
+    }
+    this.isManualDisconnect = false;
+    this.stateManager.transition("connecting" /* CONNECTING */);
+    if (this.mockManager) {
+      return this.connectMock();
+    }
+    return new Promise(async (resolve, reject) => {
+      try {
+        this.ws = await createWebSocketAdapter(this.url);
+        this.ws.on("open", () => {
+          this.handleOpen();
+          resolve();
+        });
+        this.ws.on("message", (data) => {
+          this.handleMessage(data);
+        });
+        this.ws.on("close", (code, reason) => {
+          if (this.stateManager.isConnecting()) {
+            this.stateManager.transition("disconnected" /* DISCONNECTED */);
+            const error = new Error(`WebSocket connection failed (code: ${code}${reason ? ", reason: " + reason : ""})`);
+            this.emit("error", error);
+            reject(error);
+            this.handleClose(code, reason);
+          } else {
+            this.handleClose(code, reason);
+          }
+        });
+        this.ws.on("error", (error) => {
+          this.emit("error", error);
+          if (this.stateManager.isConnecting()) {
+            this.stateManager.transition("disconnected" /* DISCONNECTED */);
+            reject(error);
+          }
+        });
+      } catch (error) {
+        this.stateManager.transition("disconnected" /* DISCONNECTED */);
+        reject(error);
+      }
+    });
+  }
+  /**
+   * Simulate connection in mock mode
+   */
+  async connectMock() {
+    await this.delay(10);
+    this.handleOpen();
+    const helloResponse = await this.mockManager.getMockResponse({ type: "hello" });
+    if (helloResponse) {
+      this.processMessage(helloResponse);
+    }
+  }
+  /**
+   * Disconnect from JMRI WebSocket server
+   */
+  async disconnect() {
+    if (this.stateManager.isDisconnected()) {
+      return;
+    }
+    this.isManualDisconnect = true;
+    this.reconnectionManager.stop();
+    this.heartbeatManager.stop();
+    if (this.stateManager.isConnected()) {
+      try {
+        await this.sendGoodbye();
+      } catch (error) {
+      }
+    }
+    if (this.ws) {
+      this.ws.close();
+      this.ws = void 0;
+    }
+    this.rejectAllPendingRequests(new Error("Client disconnected"));
+    if (!this.stateManager.isDisconnected()) {
+      this.stateManager.transition("disconnected" /* DISCONNECTED */);
+    }
+  }
+  /**
+   * Send message to JMRI (or mock)
+   */
+  send(message) {
+    if (!this.stateManager.isConnected()) {
+      this.messageQueue.enqueue(message);
+      return;
+    }
+    if (this.mockManager) {
+      this.emit("message:sent", message);
+      return;
+    }
+    if (!this.ws) {
+      throw new Error("WebSocket not initialized");
+    }
+    const json = JSON.stringify(message);
+    this.ws.send(json);
+    this.emit("message:sent", message);
+  }
+  /**
+   * Send request and wait for response (or get mock response)
+   */
+  async request(message, timeout) {
+    if (this.mockManager) {
+      const response = await this.mockManager.getMockResponse(message);
+      this.emit("message:sent", message);
+      if (response) {
+        this.processMessage(response);
+      }
+      return response;
+    }
+    const id = this.messageIdGen.next();
+    message.id = id;
+    return new Promise((resolve, reject) => {
+      const timeoutMs = timeout || this.options.requestTimeout;
+      const timeoutHandle = setTimeout(() => {
+        this.pendingRequests.delete(id);
+        reject(new Error(`Request timeout after ${timeoutMs}ms`));
+      }, timeoutMs);
+      const pendingRequest = {
+        resolve,
+        reject,
+        timeout: timeoutHandle,
+        messageType: message.type
+      };
+      if (message.type === "throttle" && message.data && "name" in message.data) {
+        pendingRequest.matchKey = message.data.name;
+      }
+      this.pendingRequests.set(id, pendingRequest);
+      try {
+        this.send(message);
+      } catch (error) {
+        this.pendingRequests.delete(id);
+        clearTimeout(timeoutHandle);
+        reject(error);
+      }
+    });
+  }
+  /**
+   * Get current connection state
+   */
+  getState() {
+    return this.stateManager.getState();
+  }
+  /**
+   * Check if connected
+   */
+  isConnected() {
+    return this.stateManager.isConnected();
+  }
+  /**
+   * Handle WebSocket open event
+   */
+  handleOpen() {
+    this.stateManager.transition("connected" /* CONNECTED */);
+    this.emit("connected");
+    if (this.options.heartbeat.enabled) {
+      this.heartbeatManager.start(() => this.sendPing());
+    }
+    const queuedMessages = this.messageQueue.flush();
+    for (const message of queuedMessages) {
+      this.send(message);
+    }
+  }
+  /**
+   * Handle WebSocket message event
+   */
+  handleMessage(data) {
+    try {
+      const message = JSON.parse(data);
+      this.processMessage(message);
+    } catch (error) {
+      this.emit("error", new Error(`Failed to parse message: ${error}`));
+    }
+  }
+  /**
+   * Process a parsed message (called by both real and mock mode)
+   */
+  processMessage(message) {
+    this.emit("message:received", message);
+    if (message.type === "pong") {
+      this.heartbeatManager.receivedPong();
+      return;
+    }
+    if (message.type === "hello") {
+      this.emit("hello", message.data);
+      return;
+    }
+    if (message.id !== void 0) {
+      const pending = this.pendingRequests.get(message.id);
+      if (pending) {
+        clearTimeout(pending.timeout);
+        this.pendingRequests.delete(message.id);
+        pending.resolve(message);
+        return;
+      }
+    }
+    if (message.id === void 0) {
+      for (const [id, pending] of this.pendingRequests.entries()) {
+        if (pending.messageType === message.type) {
+          if (message.type === "throttle" && pending.matchKey) {
+            const throttleName = message.data?.throttle || message.data?.name;
+            if (throttleName === pending.matchKey) {
+              clearTimeout(pending.timeout);
+              this.pendingRequests.delete(id);
+              pending.resolve(message);
+              return;
+            }
+          } else {
+            clearTimeout(pending.timeout);
+            this.pendingRequests.delete(id);
+            pending.resolve(message);
+            return;
+          }
+        }
+      }
+    }
+    this.emit("update", message);
+  }
+  /**
+   * Handle WebSocket close event
+   */
+  handleClose(code, reason) {
+    this.heartbeatManager.stop();
+    const wasConnected = this.stateManager.isConnected();
+    const isReconnecting = this.reconnectionManager.reconnecting();
+    if (this.stateManager.isConnected() || this.stateManager.isConnecting()) {
+      this.stateManager.transition("disconnected" /* DISCONNECTED */);
+    }
+    this.emit("disconnected", reason || `Connection closed (code: ${code})`);
+    this.rejectAllPendingRequests(new Error("Connection closed"));
+    if (!this.isManualDisconnect && (wasConnected || isReconnecting) && this.options.reconnection.enabled) {
+      this.stateManager.forceState("reconnecting" /* RECONNECTING */);
+      this.reconnectionManager.start(() => this.connect());
+    }
+  }
+  /**
+   * Handle heartbeat timeout
+   */
+  handleHeartbeatTimeout() {
+    if (this.ws) {
+      this.ws.close();
+    }
+  }
+  /**
+   * Send ping message
+   */
+  sendPing() {
+    this.send({ type: "ping" });
+  }
+  /**
+   * Send goodbye message
+   */
+  async sendGoodbye() {
+    const message = { type: "goodbye" };
+    this.send(message);
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  /**
+   * Reject all pending requests
+   */
+  rejectAllPendingRequests(error) {
+    for (const pending of this.pendingRequests.values()) {
+      clearTimeout(pending.timeout);
+      pending.reject(error);
+    }
+    this.pendingRequests.clear();
+  }
+  /**
+   * Delay helper
+   */
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/managers/power-manager.ts
+var import_eventemitter36 = require("eventemitter3");
+var PowerManager = class extends import_eventemitter36.EventEmitter {
+  constructor(client) {
+    super();
+    this.currentState = 0 /* UNKNOWN */;
+    this.client = client;
+    this.client.on("update", (message) => {
+      if (message.type === "power") {
+        this.handlePowerUpdate(message);
+      }
+    });
+  }
+  /**
+   * Get current track power state
+   * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
+   */
+  async getPower(prefix) {
+    const message = {
+      type: "power",
+      ...prefix !== void 0 && { data: { state: 0 /* UNKNOWN */, prefix } }
+    };
+    const response = await this.client.request(message);
+    if (response.data?.state !== void 0) {
+      this.currentState = response.data.state;
+    }
+    return this.currentState;
+  }
+  /**
+   * Set track power state
+   * @param state - The desired power state
+   * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
+   */
+  async setPower(state, prefix) {
+    const message = {
+      type: "power",
+      method: "post",
+      data: { state, ...prefix !== void 0 && { prefix } }
+    };
+    await this.client.request(message);
+    const oldState = this.currentState;
+    this.currentState = state;
+    if (oldState !== this.currentState) {
+      this.emit("power:changed", this.currentState);
+    }
+  }
+  /**
+   * Turn track power on
+   * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
+   */
+  async powerOn(prefix) {
+    await this.setPower(2 /* ON */, prefix);
+  }
+  /**
+   * Turn track power off
+   * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
+   */
+  async powerOff(prefix) {
+    await this.setPower(4 /* OFF */, prefix);
+  }
+  /**
+   * Get cached power state (no network request)
+   */
+  getCachedState() {
+    return this.currentState;
+  }
+  /**
+   * Handle unsolicited power updates from JMRI
+   */
+  handlePowerUpdate(message) {
+    if (message.data?.state !== void 0) {
+      const oldState = this.currentState;
+      this.currentState = message.data.state;
+      if (oldState !== this.currentState) {
+        this.emit("power:changed", this.currentState);
+      }
+    }
+  }
+};
+
+// src/managers/roster-manager.ts
+var RosterManager = class {
+  constructor(client) {
+    this.rosterCache = /* @__PURE__ */ new Map();
+    this.client = client;
+  }
+  /**
+   * Get all roster entries
+   */
+  async getRoster() {
+    const message = {
+      type: "roster",
+      method: "list"
+    };
+    const response = await this.client.request(message);
+    if (response.data) {
+      this.updateCache(response.data);
+    }
+    return Array.from(this.rosterCache.values());
+  }
+  /**
+   * Get roster entry by name
+   */
+  async getRosterEntryByName(name) {
+    if (this.rosterCache.has(name)) {
+      return this.rosterCache.get(name);
+    }
+    await this.getRoster();
+    return this.rosterCache.get(name);
+  }
+  /**
+   * Get roster entry by address
+   */
+  async getRosterEntryByAddress(address) {
+    if (this.rosterCache.size === 0) {
+      await this.getRoster();
+    }
+    const addressStr = address.toString();
+    for (const wrapper of this.rosterCache.values()) {
+      if (wrapper.data.address === addressStr) {
+        return wrapper;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Search roster by partial name match
+   */
+  async searchRoster(query) {
+    if (this.rosterCache.size === 0) {
+      await this.getRoster();
+    }
+    const lowerQuery = query.toLowerCase();
+    const results = [];
+    for (const wrapper of this.rosterCache.values()) {
+      const entry = wrapper.data;
+      if (entry.name.toLowerCase().includes(lowerQuery) || entry.address.includes(query) || entry.road?.toLowerCase().includes(lowerQuery) || entry.number?.includes(query)) {
+        results.push(wrapper);
+      }
+    }
+    return results;
+  }
+  /**
+   * Get cached roster (no network request)
+   */
+  getCachedRoster() {
+    return Array.from(this.rosterCache.values());
+  }
+  /**
+   * Clear roster cache
+   */
+  clearCache() {
+    this.rosterCache.clear();
+  }
+  /**
+   * Update internal cache from roster data
+   */
+  updateCache(rosterData) {
+    this.rosterCache.clear();
+    if (Array.isArray(rosterData)) {
+      for (const wrapper of rosterData) {
+        if (wrapper.type === "rosterEntry" && wrapper.data) {
+          this.rosterCache.set(wrapper.data.name, wrapper);
+        }
+      }
+    } else {
+      let id = 1;
+      for (const [name, entry] of Object.entries(rosterData)) {
+        const wrapper = {
+          type: "rosterEntry",
+          data: entry,
+          id: id++
+        };
+        this.rosterCache.set(name, wrapper);
+      }
+    }
+  }
+};
+
+// src/managers/throttle-manager.ts
+var import_eventemitter37 = require("eventemitter3");
+
+// src/types/throttle.ts
+function isThrottleFunctionKey(key) {
+  return /^F([0-9]|1[0-9]|2[0-8])$/.test(key);
+}
+function isValidSpeed(speed) {
+  return typeof speed === "number" && speed >= 0 && speed <= 1;
+}
+
+// src/managers/throttle-manager.ts
+var ThrottleManager = class extends import_eventemitter37.EventEmitter {
+  constructor(client) {
+    super();
+    this.throttles = /* @__PURE__ */ new Map();
+    this.client = client;
+    this.clientId = `jmri-client-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    this.client.on("update", (message) => {
+      if (message.type === "throttle") {
+        this.handleThrottleUpdate(message);
+      }
+    });
+    this.client.on("disconnected", () => {
+      this.handleDisconnect();
+    });
+  }
+  /**
+   * Acquire a throttle for a locomotive
+   */
+  async acquireThrottle(options) {
+    const throttleName = `${this.clientId}-${options.address}`;
+    const message = {
+      type: "throttle",
+      data: {
+        name: throttleName,
+        address: options.address,
+        ...options.prefix !== void 0 && { prefix: options.prefix }
+      }
+    };
+    const response = await this.client.request(message);
+    const throttleId = response.data?.throttle || throttleName;
+    if (!throttleId) {
+      throw new Error("Failed to acquire throttle: no throttle ID returned");
+    }
+    const state = {
+      id: throttleId,
+      address: options.address,
+      speed: 0,
+      forward: true,
+      functions: /* @__PURE__ */ new Map(),
+      acquired: true
+    };
+    this.throttles.set(throttleId, state);
+    this.emit("throttle:acquired", throttleId);
+    return throttleId;
+  }
+  /**
+   * Release a throttle
+   */
+  async releaseThrottle(throttleId) {
+    const state = this.throttles.get(throttleId);
+    if (!state) {
+      throw new Error(`Throttle not found: ${throttleId}`);
+    }
+    const message = {
+      type: "throttle",
+      data: {
+        throttle: throttleId,
+        release: null
+      }
+    };
+    await this.client.request(message);
+    this.throttles.delete(throttleId);
+    this.emit("throttle:released", throttleId);
+  }
+  /**
+   * Set throttle speed (0.0 to 1.0)
+   */
+  async setSpeed(throttleId, speed) {
+    const state = this.throttles.get(throttleId);
+    if (!state) {
+      throw new Error(`Throttle not found: ${throttleId}`);
+    }
+    if (!isValidSpeed(speed)) {
+      throw new Error(`Invalid speed: ${speed}. Must be between 0.0 and 1.0`);
+    }
+    const message = {
+      type: "throttle",
+      data: {
+        throttle: throttleId,
+        speed
+      }
+    };
+    this.client.send(message);
+    state.speed = speed;
+    this.emit("throttle:updated", throttleId, { speed });
+  }
+  /**
+   * Set throttle direction
+   */
+  async setDirection(throttleId, forward) {
+    const state = this.throttles.get(throttleId);
+    if (!state) {
+      throw new Error(`Throttle not found: ${throttleId}`);
+    }
+    const message = {
+      type: "throttle",
+      data: {
+        throttle: throttleId,
+        forward
+      }
+    };
+    this.client.send(message);
+    state.forward = forward;
+    this.emit("throttle:updated", throttleId, { forward });
+  }
+  /**
+   * Set throttle function (F0-F28)
+   */
+  async setFunction(throttleId, functionKey, value) {
+    const state = this.throttles.get(throttleId);
+    if (!state) {
+      throw new Error(`Throttle not found: ${throttleId}`);
+    }
+    if (!isThrottleFunctionKey(functionKey)) {
+      throw new Error(`Invalid function key: ${functionKey}`);
+    }
+    const data = {
+      throttle: throttleId,
+      [functionKey]: value
+    };
+    const message = {
+      type: "throttle",
+      data
+    };
+    this.client.send(message);
+    state.functions.set(functionKey, value);
+    this.emit("throttle:updated", throttleId, { [functionKey]: value });
+  }
+  /**
+   * Emergency stop for a throttle (speed to 0)
+   */
+  async emergencyStop(throttleId) {
+    await this.setSpeed(throttleId, 0);
+  }
+  /**
+   * Set throttle to idle (speed to 0, maintain direction)
+   */
+  async idle(throttleId) {
+    await this.setSpeed(throttleId, 0);
+  }
+  /**
+   * Get throttle state
+   */
+  getThrottleState(throttleId) {
+    return this.throttles.get(throttleId);
+  }
+  /**
+   * Get all throttle IDs
+   */
+  getThrottleIds() {
+    return Array.from(this.throttles.keys());
+  }
+  /**
+   * Get all throttle states
+   */
+  getAllThrottles() {
+    return Array.from(this.throttles.values());
+  }
+  /**
+   * Release all throttles
+   */
+  async releaseAllThrottles() {
+    const throttleIds = this.getThrottleIds();
+    for (const throttleId of throttleIds) {
+      try {
+        await this.releaseThrottle(throttleId);
+      } catch (error) {
+        this.emit("error", error);
+      }
+    }
+  }
+  /**
+   * Handle unsolicited throttle updates from JMRI
+   */
+  handleThrottleUpdate(message) {
+    const throttleId = message.data?.throttle;
+    if (!throttleId) {
+      return;
+    }
+    const state = this.throttles.get(throttleId);
+    if (!state) {
+      this.emit("throttle:lost", throttleId);
+      return;
+    }
+    if (message.data.speed !== void 0) {
+      state.speed = message.data.speed;
+    }
+    if (message.data.forward !== void 0) {
+      state.forward = message.data.forward;
+    }
+    for (let i = 0; i <= 28; i++) {
+      const key = `F${i}`;
+      if (message.data[key] !== void 0) {
+        state.functions.set(key, message.data[key]);
+      }
+    }
+    this.emit("throttle:updated", throttleId, message.data);
+  }
+  /**
+   * Handle disconnect - mark all throttles as not acquired
+   */
+  handleDisconnect() {
+    for (const state of this.throttles.values()) {
+      state.acquired = false;
+    }
+  }
+};
+
+// src/managers/turnout-manager.ts
+var import_eventemitter38 = require("eventemitter3");
+var TurnoutManager = class extends import_eventemitter38.EventEmitter {
+  constructor(client) {
+    super();
+    this.turnouts = /* @__PURE__ */ new Map();
+    this.client = client;
+    this.client.on("update", (message) => {
+      if (message.type === "turnout") {
+        this.handleTurnoutUpdate(message);
+      }
+    });
+  }
+  /**
+   * Get the current state of a turnout.
+   * Also registers a server-side listener so subsequent changes are pushed.
+   */
+  async getTurnout(name) {
+    const message = {
+      type: "turnout",
+      data: { name }
+    };
+    const response = await this.client.request(message);
+    const state = response.data?.state ?? 0 /* UNKNOWN */;
+    this.turnouts.set(name, state);
+    return state;
+  }
+  /**
+   * Set a turnout to the given state
+   */
+  async setTurnout(name, state) {
+    const message = {
+      type: "turnout",
+      method: "post",
+      data: { name, state }
+    };
+    await this.client.request(message);
+    const oldState = this.turnouts.get(name);
+    this.turnouts.set(name, state);
+    if (oldState !== state) {
+      this.emit("turnout:changed", name, state);
+    }
+  }
+  /**
+   * Throw a turnout (diverging route)
+   */
+  async throwTurnout(name) {
+    return this.setTurnout(name, 4 /* THROWN */);
+  }
+  /**
+   * Close a turnout (straight through / normal)
+   */
+  async closeTurnout(name) {
+    return this.setTurnout(name, 2 /* CLOSED */);
+  }
+  /**
+   * List all turnouts known to JMRI
+   */
+  async listTurnouts() {
+    const message = {
+      type: "turnout",
+      method: "list"
+    };
+    const response = await this.client.request(message);
+    const entries = Array.isArray(response?.data) ? response.data.map((r) => r.data ?? r) : [];
+    for (const entry of entries) {
+      if (entry.name && entry.state !== void 0) {
+        this.turnouts.set(entry.name, entry.state);
+      }
+    }
+    return entries;
+  }
+  /**
+   * Get cached turnout state without a network request
+   */
+  getTurnoutState(name) {
+    return this.turnouts.get(name);
+  }
+  /**
+   * Get all cached turnout states
+   */
+  getCachedTurnouts() {
+    return new Map(this.turnouts);
+  }
+  /**
+   * Handle unsolicited turnout state updates from JMRI
+   */
+  handleTurnoutUpdate(message) {
+    const name = message.data?.name;
+    const state = message.data?.state;
+    if (!name || state === void 0) return;
+    const oldState = this.turnouts.get(name);
+    this.turnouts.set(name, state);
+    if (oldState !== state) {
+      this.emit("turnout:changed", name, state);
+    }
+  }
+};
+
+// src/managers/light-manager.ts
+var import_eventemitter39 = require("eventemitter3");
+var LightManager = class extends import_eventemitter39.EventEmitter {
+  constructor(client) {
+    super();
+    this.lights = /* @__PURE__ */ new Map();
+    this.client = client;
+    this.client.on("update", (message) => {
+      if (message.type === "light") {
+        this.handleLightUpdate(message);
+      }
+    });
+  }
+  /**
+   * Get the current state of a light.
+   * Also registers a server-side listener so subsequent changes are pushed.
+   */
+  async getLight(name) {
+    const message = {
+      type: "light",
+      data: { name }
+    };
+    const response = await this.client.request(message);
+    const state = response.data?.state ?? 0 /* UNKNOWN */;
+    this.lights.set(name, state);
+    return state;
+  }
+  /**
+   * Set a light to the given state
+   */
+  async setLight(name, state) {
+    const message = {
+      type: "light",
+      method: "post",
+      data: { name, state }
+    };
+    await this.client.request(message);
+    const oldState = this.lights.get(name);
+    this.lights.set(name, state);
+    if (oldState !== state) {
+      this.emit("light:changed", name, state);
+    }
+  }
+  /**
+   * Turn a light on
+   */
+  async turnOnLight(name) {
+    return this.setLight(name, 2 /* ON */);
+  }
+  /**
+   * Turn a light off
+   */
+  async turnOffLight(name) {
+    return this.setLight(name, 4 /* OFF */);
+  }
+  /**
+   * List all lights known to JMRI
+   */
+  async listLights() {
+    const message = {
+      type: "light",
+      method: "list"
+    };
+    const response = await this.client.request(message);
+    const entries = Array.isArray(response?.data) ? response.data.map((r) => r.data ?? r) : [];
+    for (const entry of entries) {
+      if (entry.name && entry.state !== void 0) {
+        this.lights.set(entry.name, entry.state);
+      }
+    }
+    return entries;
+  }
+  /**
+   * Get cached light state without a network request
+   */
+  getLightState(name) {
+    return this.lights.get(name);
+  }
+  /**
+   * Get all cached light states
+   */
+  getCachedLights() {
+    return new Map(this.lights);
+  }
+  /**
+   * Handle unsolicited light state updates from JMRI
+   */
+  handleLightUpdate(message) {
+    const name = message.data?.name;
+    const state = message.data?.state;
+    if (!name || state === void 0) return;
+    const oldState = this.lights.get(name);
+    this.lights.set(name, state);
+    if (oldState !== state) {
+      this.emit("light:changed", name, state);
+    }
+  }
+};
+
+// src/managers/system-connections-manager.ts
+var SystemConnectionsManager = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List all available JMRI system connections and their prefixes.
+   * Use the returned prefix values with power and throttle commands to
+   * target a specific hardware connection when multiple are configured.
+   */
+  async getSystemConnections() {
+    const message = {
+      type: "systemConnections",
+      method: "list"
+    };
+    const response = await this.client.request(message);
+    if (!response.data) {
+      return [];
+    }
+    return Array.isArray(response.data) ? response.data : [response.data];
+  }
+};
+
+// src/types/client-options.ts
+var DEFAULT_CLIENT_OPTIONS = {
+  host: "localhost",
+  port: 12080,
+  protocol: "ws",
+  autoConnect: true,
+  reconnection: {
+    enabled: true,
+    maxAttempts: 0,
+    // infinite
+    initialDelay: 1e3,
+    maxDelay: 3e4,
+    multiplier: 1.5,
+    jitter: true
+  },
+  heartbeat: {
+    enabled: true,
+    interval: 3e4,
+    timeout: 5e3
+  },
+  messageQueueSize: 100,
+  requestTimeout: 1e4,
+  mock: {
+    enabled: false,
+    responseDelay: 50
+  }
+};
+function mergeOptions(userOptions) {
+  const options = { ...DEFAULT_CLIENT_OPTIONS };
+  if (!userOptions) {
+    return options;
+  }
+  if (userOptions.host !== void 0) options.host = userOptions.host;
+  if (userOptions.port !== void 0) options.port = userOptions.port;
+  if (userOptions.protocol !== void 0) options.protocol = userOptions.protocol;
+  if (userOptions.autoConnect !== void 0) options.autoConnect = userOptions.autoConnect;
+  if (userOptions.messageQueueSize !== void 0) options.messageQueueSize = userOptions.messageQueueSize;
+  if (userOptions.requestTimeout !== void 0) options.requestTimeout = userOptions.requestTimeout;
+  if (userOptions.reconnection) {
+    options.reconnection = { ...DEFAULT_CLIENT_OPTIONS.reconnection, ...userOptions.reconnection };
+  }
+  if (userOptions.heartbeat) {
+    options.heartbeat = { ...DEFAULT_CLIENT_OPTIONS.heartbeat, ...userOptions.heartbeat };
+  }
+  if (userOptions.mock) {
+    options.mock = { ...DEFAULT_CLIENT_OPTIONS.mock, ...userOptions.mock };
+  }
+  return options;
+}
+
+// src/client.ts
+var JmriClient = class extends import_eventemitter310.EventEmitter {
+  /**
+   * Create a new JMRI client
+   *
+   * @param options - Client configuration options
+   *
+   * @example
+   * ```typescript
+   * const client = new JmriClient({
+   *   host: 'jmri.local',
+   *   port: 12080
+   * });
+   *
+   * client.on('connected', () => console.log('Connected!'));
+   * client.on('power:changed', (state) => console.log('Power:', state));
+   * ```
+   */
+  constructor(options) {
+    super();
+    this.options = mergeOptions(options);
+    this.wsClient = new WebSocketClient(this.options);
+    this.powerManager = new PowerManager(this.wsClient);
+    this.rosterManager = new RosterManager(this.wsClient);
+    this.throttleManager = new ThrottleManager(this.wsClient);
+    this.turnoutManager = new TurnoutManager(this.wsClient);
+    this.lightManager = new LightManager(this.wsClient);
+    this.systemConnectionsManager = new SystemConnectionsManager(this.wsClient);
+    this.wsClient.on("connected", () => this.emit("connected"));
+    this.wsClient.on("disconnected", (reason) => this.emit("disconnected", reason));
+    this.wsClient.on(
+      "reconnecting",
+      (attempt, delay) => this.emit("reconnecting", attempt, delay)
+    );
+    this.wsClient.on("reconnected", () => this.emit("reconnected"));
+    this.wsClient.on(
+      "reconnectionFailed",
+      (attempts) => this.emit("reconnectionFailed", attempts)
+    );
+    this.wsClient.on(
+      "connectionStateChanged",
+      (state) => this.emit("connectionStateChanged", state)
+    );
+    this.wsClient.on("error", (error) => this.emit("error", error));
+    this.wsClient.on("heartbeat:sent", () => this.emit("heartbeat:sent"));
+    this.wsClient.on("heartbeat:timeout", () => this.emit("heartbeat:timeout"));
+    this.wsClient.on("hello", (data) => this.emit("hello", data));
+    this.powerManager.on(
+      "power:changed",
+      (state) => this.emit("power:changed", state)
+    );
+    this.turnoutManager.on(
+      "turnout:changed",
+      (name, state) => this.emit("turnout:changed", name, state)
+    );
+    this.lightManager.on(
+      "light:changed",
+      (name, state) => this.emit("light:changed", name, state)
+    );
+    this.throttleManager.on(
+      "throttle:acquired",
+      (id) => this.emit("throttle:acquired", id)
+    );
+    this.throttleManager.on(
+      "throttle:updated",
+      (id, data) => this.emit("throttle:updated", id, data)
+    );
+    this.throttleManager.on(
+      "throttle:released",
+      (id) => this.emit("throttle:released", id)
+    );
+    this.throttleManager.on(
+      "throttle:lost",
+      (id) => this.emit("throttle:lost", id)
+    );
+    if (this.options.autoConnect) {
+      this.connect().catch((error) => {
+        this.emit("error", error);
+      });
+    }
+  }
+  /**
+   * Connect to JMRI server
+   */
+  async connect() {
+    return this.wsClient.connect();
+  }
+  /**
+   * Disconnect from JMRI server
+   * Releases all throttles and closes connection
+   */
+  async disconnect() {
+    await this.throttleManager.releaseAllThrottles();
+    return this.wsClient.disconnect();
+  }
+  /**
+   * Get current connection state
+   */
+  getConnectionState() {
+    return this.wsClient.getState();
+  }
+  /**
+   * Check if connected to JMRI
+   */
+  isConnected() {
+    return this.wsClient.isConnected();
+  }
+  // ============================================================================
+  // Power Control
+  // ============================================================================
+  /**
+   * Get current track power state
+   * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
+   */
+  async getPower(prefix) {
+    return this.powerManager.getPower(prefix);
+  }
+  /**
+   * Set track power state
+   * @param state - The desired power state
+   * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
+   */
+  async setPower(state, prefix) {
+    return this.powerManager.setPower(state, prefix);
+  }
+  /**
+   * Turn track power on
+   * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
+   */
+  async powerOn(prefix) {
+    return this.powerManager.powerOn(prefix);
+  }
+  /**
+   * Turn track power off
+   * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
+   */
+  async powerOff(prefix) {
+    return this.powerManager.powerOff(prefix);
+  }
+  // ============================================================================
+  // System Connections
+  // ============================================================================
+  /**
+   * List all available JMRI system connections and their prefixes.
+   * Use the returned prefix values with power and throttle commands to
+   * target a specific hardware connection when multiple are configured.
+   *
+   * @example
+   * ```typescript
+   * const connections = await client.getSystemConnections();
+   * // [{ name: 'LocoNet', prefix: 'L' }, { name: 'DCC++', prefix: 'D' }]
+   * await client.powerOn('L'); // power on via LocoNet only
+   * ```
+   */
+  async getSystemConnections() {
+    return this.systemConnectionsManager.getSystemConnections();
+  }
+  // ============================================================================
+  // Roster Management
+  // ============================================================================
+  /**
+   * Get all roster entries
+   */
+  async getRoster() {
+    return this.rosterManager.getRoster();
+  }
+  /**
+   * Get roster entry by name
+   */
+  async getRosterEntryByName(name) {
+    return this.rosterManager.getRosterEntryByName(name);
+  }
+  /**
+   * Get roster entry by address
+   */
+  async getRosterEntryByAddress(address) {
+    return this.rosterManager.getRosterEntryByAddress(address);
+  }
+  /**
+   * Search roster by partial name match
+   */
+  async searchRoster(query) {
+    return this.rosterManager.searchRoster(query);
+  }
+  // ============================================================================
+  // Turnout Control
+  // ============================================================================
+  /**
+   * Get the current state of a turnout
+   */
+  async getTurnout(name) {
+    return this.turnoutManager.getTurnout(name);
+  }
+  /**
+   * Set a turnout to the given state
+   */
+  async setTurnout(name, state) {
+    return this.turnoutManager.setTurnout(name, state);
+  }
+  /**
+   * Throw a turnout (diverging route)
+   */
+  async throwTurnout(name) {
+    return this.turnoutManager.throwTurnout(name);
+  }
+  /**
+   * Close a turnout (straight through / normal)
+   */
+  async closeTurnout(name) {
+    return this.turnoutManager.closeTurnout(name);
+  }
+  /**
+   * List all turnouts known to JMRI
+   */
+  async listTurnouts() {
+    return this.turnoutManager.listTurnouts();
+  }
+  /**
+   * Get cached turnout state without a network request
+   */
+  getTurnoutState(name) {
+    return this.turnoutManager.getTurnoutState(name);
+  }
+  /**
+   * Get all cached turnout states
+   */
+  getCachedTurnouts() {
+    return this.turnoutManager.getCachedTurnouts();
+  }
+  // ============================================================================
+  // Light Control
+  // ============================================================================
+  /**
+   * Get the current state of a light
+   */
+  async getLight(name) {
+    return this.lightManager.getLight(name);
+  }
+  /**
+   * Set a light to the given state
+   */
+  async setLight(name, state) {
+    return this.lightManager.setLight(name, state);
+  }
+  /**
+   * Turn a light on
+   */
+  async turnOnLight(name) {
+    return this.lightManager.turnOnLight(name);
+  }
+  /**
+   * Turn a light off
+   */
+  async turnOffLight(name) {
+    return this.lightManager.turnOffLight(name);
+  }
+  /**
+   * List all lights known to JMRI
+   */
+  async listLights() {
+    return this.lightManager.listLights();
+  }
+  /**
+   * Get cached light state without a network request
+   */
+  getLightState(name) {
+    return this.lightManager.getLightState(name);
+  }
+  /**
+   * Get all cached light states
+   */
+  getCachedLights() {
+    return this.lightManager.getCachedLights();
+  }
+  // ============================================================================
+  // Throttle Control
+  // ============================================================================
+  /**
+   * Acquire a throttle for a locomotive
+   *
+   * @param options - Throttle acquisition options
+   * @returns Throttle ID for use in other throttle methods
+   *
+   * @example
+   * ```typescript
+   * const throttleId = await client.acquireThrottle({ address: 3 });
+   * await client.setThrottleSpeed(throttleId, 0.5); // Half speed
+   * ```
+   */
+  async acquireThrottle(options) {
+    return this.throttleManager.acquireThrottle(options);
+  }
+  /**
+   * Release a throttle
+   */
+  async releaseThrottle(throttleId) {
+    return this.throttleManager.releaseThrottle(throttleId);
+  }
+  /**
+   * Set throttle speed (0.0 to 1.0)
+   *
+   * @param throttleId - Throttle ID from acquireThrottle
+   * @param speed - Speed value between 0.0 (stopped) and 1.0 (full speed)
+   */
+  async setThrottleSpeed(throttleId, speed) {
+    return this.throttleManager.setSpeed(throttleId, speed);
+  }
+  /**
+   * Set throttle direction
+   *
+   * @param throttleId - Throttle ID from acquireThrottle
+   * @param forward - True for forward, false for reverse
+   */
+  async setThrottleDirection(throttleId, forward) {
+    return this.throttleManager.setDirection(throttleId, forward);
+  }
+  /**
+   * Set throttle function (F0-F28)
+   *
+   * @param throttleId - Throttle ID from acquireThrottle
+   * @param functionKey - Function key (F0-F28)
+   * @param value - True to activate, false to deactivate
+   *
+   * @example
+   * ```typescript
+   * await client.setThrottleFunction(throttleId, 'F0', true);  // Headlight on
+   * await client.setThrottleFunction(throttleId, 'F2', true);  // Horn
+   * ```
+   */
+  async setThrottleFunction(throttleId, functionKey, value) {
+    return this.throttleManager.setFunction(throttleId, functionKey, value);
+  }
+  /**
+   * Emergency stop for a throttle (speed to 0)
+   */
+  async emergencyStop(throttleId) {
+    return this.throttleManager.emergencyStop(throttleId);
+  }
+  /**
+   * Set throttle to idle (speed to 0, maintain direction)
+   */
+  async idleThrottle(throttleId) {
+    return this.throttleManager.idle(throttleId);
+  }
+  /**
+   * Get throttle state
+   */
+  getThrottleState(throttleId) {
+    return this.throttleManager.getThrottleState(throttleId);
+  }
+  /**
+   * Get all throttle IDs
+   */
+  getThrottleIds() {
+    return this.throttleManager.getThrottleIds();
+  }
+  /**
+   * Get all throttle states
+   */
+  getAllThrottles() {
+    return this.throttleManager.getAllThrottles();
+  }
+  /**
+   * Release all throttles
+   */
+  async releaseAllThrottles() {
+    return this.throttleManager.releaseAllThrottles();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ConnectionState,
+  JmriClient,
+  LightState,
+  MockResponseManager,
+  PowerState,
+  TurnoutState,
+  WebSocketClient,
+  isThrottleFunctionKey,
+  isValidSpeed,
+  lightStateToString,
+  mockData,
+  mockResponseManager,
+  powerStateToString,
+  turnoutStateToString
+});