@zendrex/buttplug.js 0.1.0

package/dist/index.js

@@ -0,0 +1,3084 @@
+// src/client.ts
+import Emittery from "emittery";
+
+// src/lib/logger.ts
+var noopLogger = {
+  debug() {
+  },
+  info() {
+  },
+  warn() {
+  },
+  error() {
+  },
+  child() {
+    return noopLogger;
+  }
+};
+function createLogger(prefix) {
+  return {
+    debug(message) {
+      console.debug(`[${prefix}] ${message}`);
+    },
+    info(message) {
+      console.info(`[${prefix}] ${message}`);
+    },
+    warn(message) {
+      console.warn(`[${prefix}] ${message}`);
+    },
+    error(message) {
+      console.error(`[${prefix}] ${message}`);
+    },
+    child(childPrefix) {
+      return createLogger(`${prefix}:${childPrefix}`);
+    }
+  };
+}
+var consoleLogger = createLogger("buttplug");
+
+// src/lib/context.ts
+var currentLogger;
+function getLogger() {
+  return currentLogger ?? noopLogger;
+}
+function runWithLogger(logger, fn) {
+  const prev = currentLogger;
+  currentLogger = logger;
+  try {
+    return fn();
+  } finally {
+    currentLogger = prev;
+  }
+}
+
+// src/core/utils.ts
+function raceTimeout(promise, ms) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => setTimeout(() => reject(new Error("Timeout")), ms))
+  ]);
+}
+function outputFeaturesEqual(a, b) {
+  const sortedA = [...a].sort((x, y) => x.index - y.index);
+  const sortedB = [...b].sort((x, y) => x.index - y.index);
+  for (const [i, ao] of sortedA.entries()) {
+    const bo = sortedB[i];
+    if (!bo || ao.type !== bo.type || ao.index !== bo.index || ao.description !== bo.description || ao.range[0] !== bo.range[0] || ao.range[1] !== bo.range[1] || ao.durationRange?.[0] !== bo.durationRange?.[0] || ao.durationRange?.[1] !== bo.durationRange?.[1]) {
+      return false;
+    }
+  }
+  return true;
+}
+function inputFeaturesEqual(a, b) {
+  const sortedA = [...a].sort((x, y) => x.index - y.index);
+  const sortedB = [...b].sort((x, y) => x.index - y.index);
+  for (const [i, ai] of sortedA.entries()) {
+    const bi = sortedB[i];
+    if (!bi || ai.type !== bi.type || ai.index !== bi.index || ai.description !== bi.description || ai.canRead !== bi.canRead || ai.canSubscribe !== bi.canSubscribe || ai.range[0] !== bi.range[0] || ai.range[1] !== bi.range[1]) {
+      return false;
+    }
+  }
+  return true;
+}
+function featuresEqual(a, b) {
+  if (a.outputs.length !== b.outputs.length || a.inputs.length !== b.inputs.length) {
+    return false;
+  }
+  return outputFeaturesEqual(a.outputs, b.outputs) && inputFeaturesEqual(a.inputs, b.inputs);
+}
+
+// src/core/device-reconciler.ts
+function reconcileDevices(options) {
+  const { currentDevices, incomingRaw, createDevice, callbacks } = options;
+  const logger = getLogger();
+  const incomingIndices = new Set(incomingRaw.map((d) => d.DeviceIndex));
+  const currentIndices = new Set(currentDevices.keys());
+  for (const index of currentIndices) {
+    if (!incomingIndices.has(index)) {
+      const device = currentDevices.get(index);
+      if (device) {
+        logger.debug(`Device removed: ${device.name} (index ${index})`);
+        currentDevices.delete(index);
+        callbacks.onRemoved(device);
+      }
+    }
+  }
+  for (const rawDevice of incomingRaw) {
+    if (currentIndices.has(rawDevice.DeviceIndex)) {
+      const existingDevice = currentDevices.get(rawDevice.DeviceIndex);
+      const newDevice = createDevice(rawDevice);
+      if (existingDevice && !featuresEqual(existingDevice.features, newDevice.features)) {
+        currentDevices.set(rawDevice.DeviceIndex, newDevice);
+        logger.debug(`Device updated: ${newDevice.name} (index ${newDevice.index})`);
+        callbacks.onUpdated(newDevice, existingDevice);
+      }
+    } else {
+      const device = createDevice(rawDevice);
+      currentDevices.set(rawDevice.DeviceIndex, device);
+      logger.debug(`Device added: ${device.name} (index ${device.index})`);
+      callbacks.onAdded(device);
+    }
+  }
+  callbacks.onList(Array.from(currentDevices.values()));
+}
+
+// src/lib/errors.ts
+var ErrorCode = {
+  UNKNOWN: 0,
+  INIT: 1,
+  PING: 2,
+  MESSAGE: 3,
+  DEVICE: 4
+};
+var ButtplugError = class extends Error {
+  name = "ButtplugError";
+  /**
+   * @param message - Human-readable error description
+   * @param cause - The underlying error that caused this failure
+   */
+  constructor(message, cause) {
+    super(message, { cause });
+  }
+};
+var ConnectionError = class extends ButtplugError {
+  name = "ConnectionError";
+};
+var HandshakeError = class extends ButtplugError {
+  name = "HandshakeError";
+};
+var ProtocolError = class extends ButtplugError {
+  name = "ProtocolError";
+  /** The protocol {@link ErrorCode} returned by the server. */
+  code;
+  /**
+   * @param code - The protocol error code
+   * @param message - Human-readable error description
+   * @param cause - The underlying error that caused this failure
+   */
+  constructor(code, message, cause) {
+    super(message, cause);
+    this.code = code;
+  }
+};
+var DeviceError = class extends ButtplugError {
+  name = "DeviceError";
+  /** Index of the device that triggered the error. */
+  deviceIndex;
+  /**
+   * @param deviceIndex - Index of the device that triggered the error
+   * @param message - Human-readable error description
+   * @param cause - The underlying error that caused this failure
+   */
+  constructor(deviceIndex, message, cause) {
+    super(message, cause);
+    this.deviceIndex = deviceIndex;
+  }
+};
+var TimeoutError = class extends ButtplugError {
+  name = "TimeoutError";
+  /** Name of the operation that timed out. */
+  operation;
+  /** Duration in milliseconds before the timeout triggered. */
+  timeoutMs;
+  /**
+   * @param operation - Name of the operation that timed out
+   * @param timeoutMs - Duration in milliseconds before the timeout triggered
+   * @param cause - The underlying error that caused this failure
+   */
+  constructor(operation, timeoutMs, cause) {
+    super(`${operation} timed out after ${timeoutMs}ms`, cause);
+    this.operation = operation;
+    this.timeoutMs = timeoutMs;
+  }
+};
+function formatError(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/protocol/constants.ts
+var PROTOCOL_VERSION_MAJOR = 4;
+var PROTOCOL_VERSION_MINOR = 0;
+var DEFAULT_CLIENT_NAME = "buttplug.js";
+var DEFAULT_REQUEST_TIMEOUT = 1e4;
+var DEFAULT_PING_INTERVAL = 1e3;
+var MAX_MESSAGE_ID = 4294967295;
+
+// src/protocol/messages.ts
+function createRequestServerInfo(id, clientName) {
+  return {
+    RequestServerInfo: {
+      Id: id,
+      ClientName: clientName,
+      ProtocolVersionMajor: PROTOCOL_VERSION_MAJOR,
+      ProtocolVersionMinor: PROTOCOL_VERSION_MINOR
+    }
+  };
+}
+function createStartScanning(id) {
+  return {
+    StartScanning: { Id: id }
+  };
+}
+function createStopScanning(id) {
+  return {
+    StopScanning: { Id: id }
+  };
+}
+function createRequestDeviceList(id) {
+  return {
+    RequestDeviceList: { Id: id }
+  };
+}
+function createPing(id) {
+  return {
+    Ping: { Id: id }
+  };
+}
+function createDisconnect(id) {
+  return {
+    Disconnect: { Id: id }
+  };
+}
+function createStopCmd(id, options) {
+  if (options?.featureIndex !== void 0 && options.deviceIndex === void 0) {
+    throw new Error("StopCmd: featureIndex requires deviceIndex to be set");
+  }
+  return {
+    StopCmd: {
+      Id: id,
+      ...options?.deviceIndex !== void 0 && { DeviceIndex: options.deviceIndex },
+      ...options?.featureIndex !== void 0 && { FeatureIndex: options.featureIndex },
+      ...options?.inputs !== void 0 && { Inputs: options.inputs },
+      ...options?.outputs !== void 0 && { Outputs: options.outputs }
+    }
+  };
+}
+function serializeMessage(message) {
+  return JSON.stringify([message]);
+}
+function serializeMessages(messages) {
+  return JSON.stringify(messages);
+}
+
+// src/protocol/schema.ts
+import { z } from "zod";
+var OUTPUT_TYPE_VALUES = [
+  "Vibrate",
+  "Rotate",
+  "RotateWithDirection",
+  "Oscillate",
+  "Constrict",
+  "Spray",
+  "Temperature",
+  "Led",
+  "Position",
+  "HwPositionWithDuration"
+];
+var OutputTypeSchema = z.enum(OUTPUT_TYPE_VALUES);
+var INPUT_TYPE_VALUES = ["Battery", "RSSI", "Pressure", "Button", "Position"];
+var InputTypeSchema = z.enum(INPUT_TYPE_VALUES);
+var InputCommandTypeSchema = z.enum(["Read", "Subscribe", "Unsubscribe"]);
+var BaseMessageSchema = z.object({
+  Id: z.number().int().min(0).max(MAX_MESSAGE_ID)
+});
+var RequestServerInfoSchema = BaseMessageSchema.extend({
+  ClientName: z.string().min(1),
+  ProtocolVersionMajor: z.number().int(),
+  ProtocolVersionMinor: z.number().int()
+});
+var StartScanningSchema = BaseMessageSchema;
+var StopScanningSchema = BaseMessageSchema;
+var RequestDeviceListSchema = BaseMessageSchema;
+var PingSchema = BaseMessageSchema;
+var DisconnectSchema = BaseMessageSchema;
+var StopCmdSchema = BaseMessageSchema.extend({
+  DeviceIndex: z.number().int().optional(),
+  FeatureIndex: z.number().int().optional(),
+  Inputs: z.boolean().optional(),
+  Outputs: z.boolean().optional()
+});
+var UnsignedScalarOutputDataSchema = z.object({
+  Value: z.number().int().nonnegative()
+});
+var SignedScalarOutputDataSchema = z.object({
+  Value: z.number().int()
+});
+var RotateWithDirectionOutputDataSchema = z.object({
+  Value: z.number().int().nonnegative(),
+  Clockwise: z.boolean()
+});
+var HwPositionOutputDataSchema = z.object({
+  Position: z.number().int().nonnegative(),
+  Duration: z.number().int().nonnegative()
+});
+var OutputCommandSchema = z.union([
+  z.strictObject({ Vibrate: UnsignedScalarOutputDataSchema }),
+  z.strictObject({ Rotate: UnsignedScalarOutputDataSchema }),
+  z.strictObject({ RotateWithDirection: RotateWithDirectionOutputDataSchema }),
+  z.strictObject({ Oscillate: UnsignedScalarOutputDataSchema }),
+  z.strictObject({ Constrict: UnsignedScalarOutputDataSchema }),
+  z.strictObject({ Spray: UnsignedScalarOutputDataSchema }),
+  z.strictObject({ Temperature: SignedScalarOutputDataSchema }),
+  z.strictObject({ Led: UnsignedScalarOutputDataSchema }),
+  z.strictObject({ Position: UnsignedScalarOutputDataSchema }),
+  z.strictObject({ HwPositionWithDuration: HwPositionOutputDataSchema })
+]);
+var OutputCmdSchema = BaseMessageSchema.extend({
+  DeviceIndex: z.number().int(),
+  FeatureIndex: z.number().int(),
+  Command: OutputCommandSchema
+});
+var InputCmdSchema = BaseMessageSchema.extend({
+  DeviceIndex: z.number().int(),
+  FeatureIndex: z.number().int(),
+  Type: InputTypeSchema,
+  Command: InputCommandTypeSchema
+});
+var ClientMessageSchema = z.union([
+  z.strictObject({ RequestServerInfo: RequestServerInfoSchema }),
+  z.strictObject({ StartScanning: StartScanningSchema }),
+  z.strictObject({ StopScanning: StopScanningSchema }),
+  z.strictObject({ RequestDeviceList: RequestDeviceListSchema }),
+  z.strictObject({ Ping: PingSchema }),
+  z.strictObject({ Disconnect: DisconnectSchema }),
+  z.strictObject({ StopCmd: StopCmdSchema }),
+  z.strictObject({ OutputCmd: OutputCmdSchema }),
+  z.strictObject({ InputCmd: InputCmdSchema })
+]);
+var ServerInfoSchema = BaseMessageSchema.extend({
+  ServerName: z.string().nullish(),
+  ProtocolVersionMajor: z.number().int(),
+  ProtocolVersionMinor: z.number().int(),
+  MaxPingTime: z.number().int()
+});
+var OkSchema = BaseMessageSchema;
+var ErrorMsgSchema = BaseMessageSchema.extend({
+  ErrorCode: z.nativeEnum(ErrorCode),
+  ErrorMessage: z.string()
+});
+var SensorValueSchema = z.object({ Value: z.number().int() });
+var InputDataSchema = z.union([
+  z.strictObject({ Battery: SensorValueSchema }),
+  z.strictObject({ RSSI: SensorValueSchema }),
+  z.strictObject({ Pressure: SensorValueSchema }),
+  z.strictObject({ Button: SensorValueSchema }),
+  z.strictObject({ Position: SensorValueSchema })
+]);
+var InputReadingSchema = BaseMessageSchema.extend({
+  DeviceIndex: z.number().int(),
+  FeatureIndex: z.number().int(),
+  Reading: InputDataSchema
+});
+var RawFeatureOutputSchema = z.object({
+  Value: z.tuple([z.number().int(), z.number().int()]),
+  Duration: z.tuple([z.number().int().nonnegative(), z.number().int().nonnegative()]).optional()
+});
+var RawFeatureInputSchema = z.object({
+  Command: z.array(InputCommandTypeSchema),
+  Value: z.array(z.tuple([z.number().int(), z.number().int()]))
+});
+var RawDeviceFeatureSchema = z.object({
+  FeatureIndex: z.number().int(),
+  FeatureDescription: z.string(),
+  Output: z.record(z.string(), RawFeatureOutputSchema).nullish(),
+  Input: z.record(z.string(), RawFeatureInputSchema).nullish()
+});
+var RawDeviceSchema = z.object({
+  DeviceName: z.string(),
+  DeviceIndex: z.number().int(),
+  DeviceMessageTimingGap: z.number().int(),
+  DeviceDisplayName: z.string().nullish(),
+  DeviceFeatures: z.record(z.string(), RawDeviceFeatureSchema)
+});
+var DeviceListSchema = BaseMessageSchema.extend({
+  Devices: z.record(z.string(), RawDeviceSchema)
+});
+var ScanningFinishedSchema = BaseMessageSchema;
+var ServerMessageSchema = z.union([
+  z.strictObject({ ServerInfo: ServerInfoSchema }),
+  z.strictObject({ Ok: OkSchema }),
+  z.strictObject({ Error: ErrorMsgSchema }),
+  z.strictObject({ DeviceList: DeviceListSchema }),
+  z.strictObject({ ScanningFinished: ScanningFinishedSchema }),
+  z.strictObject({ InputReading: InputReadingSchema })
+]);
+var OutputFeatureSchema = z.object({
+  type: OutputTypeSchema,
+  index: z.number().int(),
+  description: z.string(),
+  range: z.tuple([z.number().int(), z.number().int()]),
+  durationRange: z.tuple([z.number().int(), z.number().int()]).optional()
+});
+var InputFeatureSchema = z.object({
+  type: InputTypeSchema,
+  index: z.number().int(),
+  description: z.string(),
+  range: z.tuple([z.number().int(), z.number().int()]),
+  canRead: z.boolean(),
+  canSubscribe: z.boolean()
+});
+var DeviceFeaturesSchema = z.object({
+  outputs: z.array(OutputFeatureSchema),
+  inputs: z.array(InputFeatureSchema)
+});
+var FeatureValueSchema = z.object({
+  index: z.number().int(),
+  value: z.number().int()
+});
+var RotationValueSchema = z.object({
+  index: z.number().int(),
+  speed: z.number().int(),
+  clockwise: z.boolean()
+});
+var PositionValueSchema = z.object({
+  index: z.number().int(),
+  position: z.number().int(),
+  duration: z.number().int()
+});
+
+// src/protocol/parser.ts
+function parseServerMessages(raw, logger = noopLogger) {
+  const parsed = JSON.parse(raw);
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    throw new Error("Invalid server message: expected non-empty array");
+  }
+  const messages = [];
+  for (const element of parsed) {
+    if (typeof element !== "object" || element === null) {
+      throw new Error("Invalid server message: expected object");
+    }
+    const keys = Object.keys(element);
+    if (keys.length !== 1) {
+      throw new Error(`Invalid server message: expected exactly one key, got ${keys.length}`);
+    }
+    const result = ServerMessageSchema.safeParse(element);
+    if (result.success) {
+      messages.push(result.data);
+    } else {
+      logger.warn(`Unknown server message type: ${keys[0]}`);
+    }
+  }
+  return messages;
+}
+function getMessageType(message) {
+  const keys = Object.keys(message);
+  if (keys.length !== 1) {
+    throw new Error("Invalid message: expected exactly one key");
+  }
+  return keys[0];
+}
+function extractId(message) {
+  const type = getMessageType(message);
+  const inner = message[type];
+  if (typeof inner?.Id !== "number") {
+    throw new Error(`Message type "${type}" has no valid Id field`);
+  }
+  return inner.Id;
+}
+function isServerInfo(message) {
+  return "ServerInfo" in message;
+}
+function isOk(message) {
+  return "Ok" in message;
+}
+function isError(message) {
+  return "Error" in message;
+}
+function isDeviceList(message) {
+  return "DeviceList" in message;
+}
+function isScanningFinished(message) {
+  return "ScanningFinished" in message;
+}
+function isInputReading(message) {
+  return "InputReading" in message;
+}
+function getServerInfo(message) {
+  return message.ServerInfo;
+}
+function getError(message) {
+  return message.Error;
+}
+function getDeviceList(message) {
+  return message.DeviceList;
+}
+function getInputReading(message) {
+  return message.InputReading;
+}
+
+// src/core/handshake.ts
+async function performHandshake(options) {
+  const { router, clientName, pingManager, logger = noopLogger } = options;
+  let response;
+  try {
+    const responses = await router.send(createRequestServerInfo(router.nextId(), clientName));
+    response = responses[0];
+  } catch (err) {
+    throw new HandshakeError(
+      `Handshake failed: ${err instanceof Error ? err.message : String(err)}`,
+      err instanceof Error ? err : void 0
+    );
+  }
+  if (!isServerInfo(response)) {
+    throw new HandshakeError("Handshake failed: unexpected response type");
+  }
+  const serverInfo = getServerInfo(response);
+  if (serverInfo.ProtocolVersionMajor !== PROTOCOL_VERSION_MAJOR) {
+    throw new HandshakeError(
+      `Server protocol version ${serverInfo.ProtocolVersionMajor} is incompatible (client requires ${PROTOCOL_VERSION_MAJOR})`
+    );
+  }
+  const negotiatedMinor = Math.min(PROTOCOL_VERSION_MINOR, serverInfo.ProtocolVersionMinor);
+  logger.info(`Protocol version negotiated: ${PROTOCOL_VERSION_MAJOR}.${negotiatedMinor}`);
+  pingManager.start(serverInfo.MaxPingTime);
+  return serverInfo;
+}
+
+// src/core/message-router.ts
+var MessageRouter = class {
+  /** In-flight requests awaiting server responses, keyed by message ID. */
+  #pending = /* @__PURE__ */ new Map();
+  #send;
+  #timeout;
+  #logger;
+  #onDeviceList;
+  #onScanningFinished;
+  #onInputReading;
+  #onError;
+  #messageId = 0;
+  /**
+   * @param options - Router configuration including transport function and event callbacks
+   */
+  constructor(options) {
+    this.#send = options.send;
+    this.#timeout = options.timeout ?? DEFAULT_REQUEST_TIMEOUT;
+    this.#logger = (options.logger ?? noopLogger).child("router");
+    this.#onDeviceList = options.onDeviceList;
+    this.#onScanningFinished = options.onScanningFinished;
+    this.#onInputReading = options.onInputReading;
+    this.#onError = options.onError;
+  }
+  /**
+   * Returns the next message ID, wrapping around at {@link MAX_MESSAGE_ID}.
+   *
+   * @returns A monotonically increasing ID for use in outgoing messages
+   */
+  nextId() {
+    this.#messageId = this.#messageId % MAX_MESSAGE_ID + 1;
+    return this.#messageId;
+  }
+  /**
+   * Sends one or more client messages and returns promises for their responses.
+   *
+   * Each message is tracked by its ID with an automatic timeout. If the transport
+   * function throws, all pending requests from this batch are cleaned up.
+   *
+   * @param input - A single message or array of messages to send
+   * @returns A promise resolving to an array of server responses, one per input message
+   * @throws {TimeoutError} if a response is not received within the configured timeout
+   * @throws {ProtocolError} if a message has an invalid structure
+   */
+  send(input) {
+    const messages = Array.isArray(input) ? input : [input];
+    const serialized = serializeMessages(messages);
+    const label = messages.length === 1 ? "message" : `batch (${messages.length})`;
+    this.#logger.debug(`Sending ${label}: ${serialized}`);
+    const promises = messages.map((message) => {
+      const id = this.#extractMessageId(message);
+      return new Promise((resolve, reject) => {
+        const timeoutHandle = setTimeout(() => {
+          this.#pending.delete(id);
+          reject(new TimeoutError(`Request (ID ${id})`, this.#timeout));
+        }, this.#timeout);
+        this.#pending.set(id, {
+          resolve,
+          reject: (err) => {
+            clearTimeout(timeoutHandle);
+            reject(err);
+          },
+          timeout: timeoutHandle
+        });
+      });
+    });
+    try {
+      this.#send(serialized);
+    } catch (err) {
+      const ids = messages.map((m) => this.#extractMessageId(m));
+      for (const id of ids) {
+        const pending = this.#pending.get(id);
+        if (pending?.timeout) {
+          clearTimeout(pending.timeout);
+        }
+        this.#pending.delete(id);
+      }
+      throw err instanceof Error ? err : new Error(String(err));
+    }
+    return Promise.all(promises);
+  }
+  /**
+   * Processes a raw incoming message string from the server.
+   *
+   * Parses the JSON, then routes each message to its pending request or to
+   * the appropriate event callback.
+   *
+   * @param raw - The raw JSON string received from the server
+   */
+  handleMessage(raw) {
+    this.#logger.debug(`Received message: ${raw}`);
+    let messages;
+    try {
+      messages = parseServerMessages(raw, this.#logger);
+    } catch (err) {
+      this.#logger.error(`Failed to parse message: ${formatError(err)}`);
+      return;
+    }
+    for (const message of messages) {
+      this.#processMessage(message);
+    }
+  }
+  /**
+   * Cancels a single pending request by ID, rejecting its promise with the given error.
+   *
+   * @param id - The message ID of the request to cancel
+   * @param error - The error to reject the pending promise with
+   */
+  cancelPending(id, error) {
+    const pending = this.#pending.get(id);
+    if (pending) {
+      if (pending.timeout !== null) {
+        clearTimeout(pending.timeout);
+      }
+      this.#pending.delete(id);
+      pending.reject(error);
+    }
+  }
+  /**
+   * Cancels all pending requests, rejecting each with the given error.
+   *
+   * @param error - The error to reject all pending promises with
+   */
+  cancelAll(error) {
+    const entries = Array.from(this.#pending.values());
+    this.#pending.clear();
+    for (const pending of entries) {
+      if (pending.timeout !== null) {
+        clearTimeout(pending.timeout);
+      }
+      pending.reject(error);
+    }
+  }
+  /** Resets the message ID counter — required after reconnect to avoid collision with old IDs. */
+  resetId() {
+    this.#messageId = 0;
+  }
+  /** Number of in-flight requests currently awaiting responses. */
+  get pendingCount() {
+    return this.#pending.size;
+  }
+  /**
+   * Routes a parsed message to its pending request or to the event handler.
+   * Messages with ID 0 or unmatched IDs are treated as unsolicited events.
+   */
+  #processMessage(message) {
+    const id = extractId(message);
+    if (id === 0) {
+      this.#routeEvent(message);
+      return;
+    }
+    const pending = this.#pending.get(id);
+    if (!pending) {
+      this.#routeEvent(message);
+      return;
+    }
+    if (pending.timeout !== null) {
+      clearTimeout(pending.timeout);
+    }
+    this.#pending.delete(id);
+    if (isOk(message) || isServerInfo(message) || isInputReading(message)) {
+      pending.resolve(message);
+      return;
+    }
+    if (isError(message)) {
+      const error = getError(message);
+      pending.reject(new ProtocolError(error.ErrorCode, error.ErrorMessage));
+      return;
+    }
+    if (isDeviceList(message)) {
+      pending.resolve(message);
+      return;
+    }
+    this.#logger.warn(`Unexpected response type for pending request ${id}`);
+    pending.resolve(message);
+  }
+  /**
+   * Dispatches an unsolicited server event to the appropriate callback.
+   * Logs a warning if the message type has no registered handler.
+   */
+  #routeEvent(message) {
+    if (isDeviceList(message)) {
+      const deviceList = getDeviceList(message);
+      this.#onDeviceList?.(Object.values(deviceList.Devices));
+      return;
+    }
+    if (isScanningFinished(message)) {
+      this.#onScanningFinished?.();
+      return;
+    }
+    if (isInputReading(message)) {
+      const reading = getInputReading(message);
+      this.#onInputReading?.(reading);
+      return;
+    }
+    if (isError(message)) {
+      const error = getError(message);
+      this.#onError?.(error);
+      return;
+    }
+    this.#logger.warn(`Unexpected message type: ${JSON.stringify(message)}`);
+  }
+  /**
+   * Extracts the numeric message ID from a client message envelope.
+   * @throws {ProtocolError} if the message is malformed or missing an ID
+   */
+  #extractMessageId(message) {
+    const keys = Object.keys(message);
+    if (keys.length !== 1) {
+      throw new ProtocolError(ErrorCode.MESSAGE, "Invalid message: expected exactly one key");
+    }
+    const inner = message[keys[0]];
+    if (typeof inner.Id !== "number") {
+      throw new ProtocolError(ErrorCode.MESSAGE, "Invalid message: missing or non-numeric Id field");
+    }
+    return inner.Id;
+  }
+};
+
+// src/protocol/types.ts
+function sensorKey(deviceIndex, featureIndex, type) {
+  return `${deviceIndex}-${featureIndex}-${type}`;
+}
+
+// src/core/sensor-handler.ts
+var SensorHandler = class {
+  /** Active subscriptions keyed by composite sensor key. */
+  #subscriptions = /* @__PURE__ */ new Map();
+  #logger;
+  /**
+   * @param logger - Logger instance for subscription lifecycle events
+   */
+  constructor(logger) {
+    this.#logger = logger.child("sensor");
+  }
+  /**
+   * Registers a callback for a specific sensor on a device.
+   *
+   * @param key - Composite sensor key from {@link sensorKey}
+   * @param callback - Function invoked with the sensor value on each reading
+   * @param info - Device index, feature index, and input type for the sensor
+   */
+  register(key, callback, info) {
+    if (this.#subscriptions.has(key)) {
+      throw new Error(`Sensor subscription already exists: ${key}. Unsubscribe before re-subscribing.`);
+    }
+    this.#subscriptions.set(key, { callback, ...info });
+    this.#logger.debug(`Registered sensor subscription: ${key}`);
+  }
+  /**
+   * Removes a sensor subscription by key.
+   *
+   * @param key - Composite sensor key to unregister
+   */
+  unregister(key) {
+    this.#subscriptions.delete(key);
+    this.#logger.debug(`Unregistered sensor subscription: ${key}`);
+  }
+  /**
+   * Routes an incoming sensor reading to a matching subscription callback,
+   * or falls back to the provided emit function if no subscription matches.
+   *
+   * @param reading - The input reading from the server
+   * @param emit - Fallback emitter for unmatched readings
+   */
+  handleReading(reading, emit) {
+    const readingData = reading.Reading;
+    const readingKey = Object.keys(readingData)[0];
+    if (!(readingKey && readingKey in readingData)) {
+      emit(reading);
+      return;
+    }
+    const type = readingKey;
+    const subKey = sensorKey(reading.DeviceIndex, reading.FeatureIndex, type);
+    const sub = this.#subscriptions.get(subKey);
+    if (sub) {
+      const wrapper = readingData[type];
+      if (wrapper !== void 0) {
+        sub.callback(wrapper.Value);
+        return;
+      }
+    }
+    emit(reading);
+  }
+  /**
+   * Sends unsubscribe commands for all subscriptions on a device, then cleans up locally.
+   *
+   * If the client is disconnected, skips sending commands and only removes local state.
+   *
+   * @param options - Device index, router for sending commands, and connection status
+   */
+  unsubscribeDevice(options) {
+    const { deviceIndex, router, connected } = options;
+    if (!connected) {
+      this.cleanupDevice(deviceIndex);
+      return;
+    }
+    try {
+      for (const [, sub] of this.#subscriptions) {
+        if (sub.deviceIndex === deviceIndex) {
+          const id = router.nextId();
+          router.send({
+            InputCmd: {
+              Id: id,
+              DeviceIndex: sub.deviceIndex,
+              FeatureIndex: sub.featureIndex,
+              Type: sub.type,
+              Command: "Unsubscribe"
+            }
+          }).catch(() => {
+          });
+        }
+      }
+    } finally {
+      this.cleanupDevice(deviceIndex);
+    }
+  }
+  /**
+   * Removes all local subscriptions for a device without sending unsubscribe commands.
+   *
+   * @param deviceIndex - Server-assigned index of the device to clean up
+   */
+  cleanupDevice(deviceIndex) {
+    const keysToDelete = [];
+    for (const [key, sub] of this.#subscriptions) {
+      if (sub.deviceIndex === deviceIndex) {
+        keysToDelete.push(key);
+      }
+    }
+    for (const key of keysToDelete) {
+      this.#subscriptions.delete(key);
+      this.#logger.debug(`Cleaned up subscription on device removal: ${key}`);
+    }
+  }
+  /** Removes all sensor subscriptions — used during client shutdown. */
+  clear() {
+    this.#subscriptions.clear();
+  }
+};
+
+// src/builders/validation.ts
+function validateRange(value, range) {
+  const [min, max] = range;
+  const rounded = Math.round(value);
+  const clamped = Math.max(min, Math.min(max, rounded));
+  if (rounded !== clamped) {
+    getLogger().debug(`Value ${value} clamped to ${clamped} (range [${min}, ${max}])`);
+  }
+  return clamped;
+}
+
+// src/builders/commands.ts
+function buildPositionMessage(options) {
+  const { client, deviceIndex, positionType, feature, position, duration } = options;
+  if (positionType === "Position" && duration !== 0) {
+    throw new DeviceError(
+      deviceIndex,
+      `Position output type does not support duration (got ${duration}ms). Use HwPositionWithDuration for timed movements.`
+    );
+  }
+  const validatedValue = validateRange(position, feature.range);
+  const validatedDuration = feature.durationRange ? validateRange(duration, feature.durationRange) : duration;
+  const command = positionType === "HwPositionWithDuration" ? { HwPositionWithDuration: { Position: validatedValue, Duration: validatedDuration } } : { Position: { Value: validatedValue } };
+  const id = client.nextId();
+  return {
+    OutputCmd: {
+      Id: id,
+      DeviceIndex: deviceIndex,
+      FeatureIndex: feature.index,
+      Command: command
+    }
+  };
+}
+function buildPositionMessages(options) {
+  const { client, deviceIndex, positionType, features, position, duration } = options;
+  const messages = [];
+  if (Array.isArray(position)) {
+    if (position.length === 0) {
+      throw new DeviceError(deviceIndex, "Values array must not be empty");
+    }
+    for (const p of position) {
+      const feature = features[p.index];
+      if (!feature) {
+        throw new DeviceError(
+          deviceIndex,
+          `Invalid position index ${p.index} (device has ${features.length} position feature(s))`
+        );
+      }
+      messages.push(
+        buildPositionMessage({
+          client,
+          deviceIndex,
+          positionType,
+          feature,
+          position: p.position,
+          duration: p.duration
+        })
+      );
+    }
+  } else {
+    for (const feature of features) {
+      messages.push(buildPositionMessage({ client, deviceIndex, positionType, feature, position, duration }));
+    }
+  }
+  return messages;
+}
+function buildRotateMessages(options) {
+  const { client, deviceIndex, features, rotationType, speed, clockwise } = options;
+  const messages = [];
+  if (Array.isArray(speed)) {
+    if (speed.length === 0) {
+      throw new DeviceError(deviceIndex, "Values array must not be empty");
+    }
+    for (const r of speed) {
+      const feature = features[r.index];
+      if (!feature) {
+        throw new DeviceError(
+          deviceIndex,
+          `Invalid rotation index ${r.index} (device has ${features.length} rotation feature(s))`
+        );
+      }
+      const validatedValue = validateRange(r.speed, feature.range);
+      const command = rotationType === "RotateWithDirection" ? { RotateWithDirection: { Value: validatedValue, Clockwise: r.clockwise } } : { Rotate: { Value: validatedValue } };
+      const id = client.nextId();
+      messages.push({
+        OutputCmd: {
+          Id: id,
+          DeviceIndex: deviceIndex,
+          FeatureIndex: feature.index,
+          Command: command
+        }
+      });
+    }
+  } else {
+    for (const feature of features) {
+      const validatedValue = validateRange(speed, feature.range);
+      const command = rotationType === "RotateWithDirection" ? { RotateWithDirection: { Value: validatedValue, Clockwise: clockwise } } : { Rotate: { Value: validatedValue } };
+      const id = client.nextId();
+      messages.push({
+        OutputCmd: {
+          Id: id,
+          DeviceIndex: deviceIndex,
+          FeatureIndex: feature.index,
+          Command: command
+        }
+      });
+    }
+  }
+  return messages;
+}
+function buildScalarOutputMessages(options) {
+  const { client, deviceIndex, type, features, values, errorLabel } = options;
+  if (Array.isArray(values)) {
+    if (values.length === 0) {
+      throw new DeviceError(deviceIndex, "Values array must not be empty");
+    }
+    const messages2 = [];
+    for (const entry of values) {
+      const feature = features[entry.index];
+      if (!feature) {
+        throw new DeviceError(
+          deviceIndex,
+          `Invalid ${errorLabel} index ${entry.index} (device has ${features.length} ${errorLabel} feature(s))`
+        );
+      }
+      const validatedValue = validateRange(entry.value, feature.range);
+      const id = client.nextId();
+      messages2.push({
+        OutputCmd: {
+          Id: id,
+          DeviceIndex: deviceIndex,
+          FeatureIndex: feature.index,
+          Command: { [type]: { Value: validatedValue } }
+        }
+      });
+    }
+    return messages2;
+  }
+  const messages = [];
+  for (const feature of features) {
+    const validatedValue = validateRange(values, feature.range);
+    const id = client.nextId();
+    messages.push({
+      OutputCmd: {
+        Id: id,
+        DeviceIndex: deviceIndex,
+        FeatureIndex: feature.index,
+        Command: { [type]: { Value: validatedValue } }
+      }
+    });
+  }
+  return messages;
+}
+async function sendMessages(client, messages) {
+  if (messages.length === 0) {
+    return;
+  }
+  await client.send(messages);
+}
+
+// src/builders/features.ts
+var OUTPUT_TYPES = OUTPUT_TYPE_VALUES;
+var INPUT_TYPES = INPUT_TYPE_VALUES;
+var outputIndex = /* @__PURE__ */ new WeakMap();
+var inputIndex = /* @__PURE__ */ new WeakMap();
+function buildOutputIndex(features) {
+  const map = /* @__PURE__ */ new Map();
+  for (const f of features.outputs) {
+    const list = map.get(f.type);
+    if (list) {
+      list.push(f);
+    } else {
+      map.set(f.type, [f]);
+    }
+  }
+  return map;
+}
+function buildInputIndex(features) {
+  const map = /* @__PURE__ */ new Map();
+  for (const f of features.inputs) {
+    const list = map.get(f.type);
+    if (list) {
+      list.push(f);
+    } else {
+      map.set(f.type, [f]);
+    }
+  }
+  return map;
+}
+function getOutputIndex(features) {
+  let idx = outputIndex.get(features);
+  if (!idx) {
+    idx = buildOutputIndex(features);
+    outputIndex.set(features, idx);
+  }
+  return idx;
+}
+function getInputIndex(features) {
+  let idx = inputIndex.get(features);
+  if (!idx) {
+    idx = buildInputIndex(features);
+    inputIndex.set(features, idx);
+  }
+  return idx;
+}
+var KNOWN_OUTPUT_KEYS = new Set(OUTPUT_TYPES);
+var KNOWN_INPUT_KEYS = new Set(INPUT_TYPES);
+function collectOutputs(feature) {
+  if (!feature.Output) {
+    return [];
+  }
+  const logger = getLogger();
+  const results = [];
+  for (const key of Object.keys(feature.Output)) {
+    if (!KNOWN_OUTPUT_KEYS.has(key)) {
+      logger.warn(`Unknown output type "${key}" at feature index ${feature.FeatureIndex}, skipping`);
+    }
+  }
+  for (const outputType of OUTPUT_TYPES) {
+    const outputConfig = feature.Output[outputType];
+    if (outputConfig) {
+      results.push(parseOutputFeature(outputType, feature.FeatureIndex, feature, outputConfig));
+    }
+  }
+  return results;
+}
+function collectInputs(feature) {
+  if (!feature.Input) {
+    return [];
+  }
+  const logger = getLogger();
+  const results = [];
+  for (const key of Object.keys(feature.Input)) {
+    if (!KNOWN_INPUT_KEYS.has(key)) {
+      logger.warn(`Unknown input type "${key}" at feature index ${feature.FeatureIndex}, skipping`);
+    }
+  }
+  for (const inputType of INPUT_TYPES) {
+    const inputConfig = feature.Input[inputType];
+    if (inputConfig) {
+      results.push(parseInputFeature(inputType, feature.FeatureIndex, feature, inputConfig));
+    }
+  }
+  return results;
+}
+function parseFeatures(raw) {
+  const outputs = [];
+  const inputs = [];
+  const features = raw.DeviceFeatures ?? {};
+  const sortedFeatures = Object.values(features).sort((a, b) => a.FeatureIndex - b.FeatureIndex);
+  for (const feature of sortedFeatures) {
+    for (const output of collectOutputs(feature)) {
+      outputs.push(output);
+    }
+    for (const input of collectInputs(feature)) {
+      inputs.push(input);
+    }
+  }
+  const result = { outputs, inputs };
+  outputIndex.set(result, buildOutputIndex(result));
+  inputIndex.set(result, buildInputIndex(result));
+  return result;
+}
+function parseOutputFeature(type, index, feature, output) {
+  return {
+    type,
+    index,
+    description: feature.FeatureDescription,
+    range: output.Value,
+    durationRange: output.Duration
+  };
+}
+function parseInputFeature(type, index, feature, input) {
+  const canRead = input.Command.includes("Read");
+  const canSubscribe = input.Command.includes("Subscribe");
+  const range = input.Value[0] ?? [0, 0];
+  return {
+    type,
+    index,
+    description: feature.FeatureDescription,
+    range,
+    canRead,
+    canSubscribe
+  };
+}
+function hasOutputType(features, type) {
+  const idx = getOutputIndex(features);
+  const list = idx.get(type);
+  return list !== void 0 && list.length > 0;
+}
+function getOutputsByType(features, type) {
+  return getOutputIndex(features).get(type) ?? [];
+}
+function getInputsByType(features, type) {
+  return getInputIndex(features).get(type) ?? [];
+}
+
+// src/device.ts
+var Device = class {
+  #client;
+  #raw;
+  #features;
+  #logger;
+  #lastCommandTime = 0;
+  constructor(options) {
+    this.#client = options.client;
+    this.#raw = options.raw;
+    this.#logger = (options.logger ?? getLogger()).child("device");
+    this.#features = parseFeatures(options.raw);
+  }
+  /**
+   * Sets vibration intensity on all or individual motors.
+   *
+   * @param intensity - A single value for all motors, or per-motor {@link FeatureValue} entries
+   * @throws DeviceError if the device does not support vibration
+   */
+  async vibrate(intensity) {
+    await this.#sendScalarOutput({ type: "Vibrate", errorLabel: "vibration", values: intensity });
+  }
+  /**
+   * Sets oscillation speed on all or individual motors.
+   *
+   * @param speed - A single value for all motors, or per-motor {@link FeatureValue} entries
+   * @throws DeviceError if the device does not support oscillation
+   */
+  async oscillate(speed) {
+    await this.#sendScalarOutput({ type: "Oscillate", errorLabel: "oscillation", values: speed });
+  }
+  /**
+   * Sets constriction pressure on all or individual actuators.
+   *
+   * @param value - A single value for all actuators, or per-actuator {@link FeatureValue} entries
+   * @throws DeviceError if the device does not support constriction
+   */
+  async constrict(value) {
+    await this.#sendScalarOutput({ type: "Constrict", errorLabel: "constriction", values: value });
+  }
+  /**
+   * Controls spray output on all or individual actuators.
+   *
+   * @param value - A single value for all actuators, or per-actuator {@link FeatureValue} entries
+   * @throws DeviceError if the device does not support spraying
+   */
+  async spray(value) {
+    await this.#sendScalarOutput({ type: "Spray", errorLabel: "spraying", values: value });
+  }
+  /**
+   * Sets temperature on all or individual actuators.
+   *
+   * @param value - A single value for all actuators, or per-actuator {@link FeatureValue} entries
+   * @throws DeviceError if the device does not support temperature control
+   */
+  async temperature(value) {
+    await this.#sendScalarOutput({ type: "Temperature", errorLabel: "temperature control", values: value });
+  }
+  /**
+   * Controls LED brightness on all or individual actuators.
+   *
+   * @param value - A single value for all actuators, or per-actuator {@link FeatureValue} entries
+   * @throws DeviceError if the device does not support LED control
+   */
+  async led(value) {
+    await this.#sendScalarOutput({ type: "Led", errorLabel: "LED control", values: value });
+  }
+  async rotate(speed, options) {
+    this.#checkTimingGap();
+    if (!this.canRotate) {
+      throw new DeviceError(this.index, "Device does not support rotation");
+    }
+    const rotationType = hasOutputType(this.#features, "RotateWithDirection") ? "RotateWithDirection" : "Rotate";
+    const features = getOutputsByType(this.#features, rotationType);
+    const clockwise = options?.clockwise ?? true;
+    const messages = buildRotateMessages({
+      client: this.#client,
+      deviceIndex: this.index,
+      features,
+      rotationType,
+      speed,
+      clockwise
+    });
+    this.#logger.debug(`Rotate command: ${messages.length} motor(s) on device ${this.name}`);
+    await sendMessages(this.#client, messages);
+  }
+  async position(position, options) {
+    this.#checkTimingGap();
+    if (!this.canPosition) {
+      throw new DeviceError(this.index, "Device does not support position control");
+    }
+    if (typeof position === "number" && options?.duration === void 0) {
+      throw new DeviceError(this.index, "Duration is required when using a uniform position value");
+    }
+    const positionType = hasOutputType(this.#features, "HwPositionWithDuration") ? "HwPositionWithDuration" : "Position";
+    const features = getOutputsByType(this.#features, positionType);
+    const duration = typeof position === "number" ? options?.duration ?? 0 : 0;
+    const messages = buildPositionMessages({
+      client: this.#client,
+      deviceIndex: this.index,
+      positionType,
+      features,
+      position,
+      duration
+    });
+    this.#logger.debug(`Position command: ${messages.length} axis/axes on device ${this.name}`);
+    await sendMessages(this.#client, messages);
+  }
+  /**
+   * Stops activity on this device.
+   *
+   * Can target a specific feature index or filter by input/output type.
+   * Without options, stops all features.
+   *
+   * @param options - Optional filters for which features to stop
+   * @throws DeviceError if the specified feature index does not exist
+   */
+  async stop(options) {
+    this.#checkTimingGap();
+    if (options?.featureIndex !== void 0) {
+      const isOutput = this.#features.outputs.some((f) => f.index === options.featureIndex);
+      const isInput = this.#features.inputs.some((f) => f.index === options.featureIndex);
+      if (!(isOutput || isInput)) {
+        throw new DeviceError(this.index, `No feature at index ${options.featureIndex}`);
+      }
+      if (isOutput && !isInput && options.outputs === false) {
+        throw new DeviceError(
+          this.index,
+          `Feature at index ${options.featureIndex} is output-only, but outputs filter is false`
+        );
+      }
+      if (isInput && !isOutput && options.inputs === false) {
+        throw new DeviceError(
+          this.index,
+          `Feature at index ${options.featureIndex} is input-only, but inputs filter is false`
+        );
+      }
+    }
+    this.#logger.debug(`Stop command on device ${this.name} (index ${this.index})`);
+    const id = this.#client.nextId();
+    await this.#client.send({
+      StopCmd: {
+        Id: id,
+        DeviceIndex: this.index,
+        ...options?.featureIndex !== void 0 && { FeatureIndex: options.featureIndex },
+        ...options?.inputs !== void 0 && { Inputs: options.inputs },
+        ...options?.outputs !== void 0 && { Outputs: options.outputs }
+      }
+    });
+  }
+  /**
+   * Sends a raw output command to a specific feature.
+   *
+   * Values are validated against the feature's declared range and clamped if out of bounds.
+   *
+   * @param options - The feature index and output command payload
+   * @throws DeviceError if no matching output feature exists at the given index
+   */
+  async output(options) {
+    this.#checkTimingGap();
+    const { featureIndex, command } = options;
+    const commandType = Object.keys(command)[0];
+    const feature = this.#features.outputs.find((f) => f.index === featureIndex && f.type === commandType);
+    if (!feature) {
+      throw new DeviceError(this.index, `No "${commandType}" output feature at index ${featureIndex}`);
+    }
+    const commandData = Object.values(command)[0];
+    if (commandType === "HwPositionWithDuration") {
+      const data = commandData;
+      data.Position = validateRange(data.Position, feature.range);
+    } else {
+      const data = commandData;
+      data.Value = validateRange(data.Value, feature.range);
+    }
+    const validatedCommand = command;
+    this.#logger.debug(`Output command: ${commandType} on device ${this.name} feature ${featureIndex}`);
+    const id = this.#client.nextId();
+    await this.#client.send({
+      OutputCmd: {
+        Id: id,
+        DeviceIndex: this.index,
+        FeatureIndex: featureIndex,
+        Command: validatedCommand
+      }
+    });
+  }
+  /**
+   * Performs a one-shot read of a sensor value.
+   *
+   * @param type - The sensor type to read (e.g. `"Battery"`, `"RSSI"`)
+   * @param sensorIndex - Index of the sensor if the device has multiple of the same type
+   * @returns The numeric sensor value
+   * @throws DeviceError if the sensor does not exist or does not support reading
+   */
+  async readSensor(type, sensorIndex = 0) {
+    const feature = this.#requireSensor({ type, sensorIndex, capability: "canRead" });
+    const response = await this.#sendInputCmd({ featureIndex: feature.index, type, command: "Read" });
+    if ("InputReading" in response) {
+      const reading = response.InputReading.Reading;
+      const wrapper = type in reading ? reading[type] : void 0;
+      if (wrapper !== void 0) {
+        return wrapper.Value;
+      }
+    }
+    throw new DeviceError(this.index, `Failed to read ${type} sensor: unexpected response`);
+  }
+  /**
+   * Subscribes to continuous sensor readings.
+   *
+   * @param type - The sensor type to subscribe to
+   * @param callback - Invoked each time a new reading arrives
+   * @param sensorIndex - Index of the sensor if the device has multiple of the same type
+   * @returns An async unsubscribe function that stops the subscription
+   * @throws DeviceError if the sensor does not exist or does not support subscriptions
+   */
+  async subscribeSensor(type, callback, sensorIndex = 0) {
+    const feature = this.#requireSensor({ type, sensorIndex, capability: "canSubscribe" });
+    const subscriptionKey = sensorKey(this.index, feature.index, type);
+    await this.#sendInputCmd({ featureIndex: feature.index, type, command: "Subscribe" });
+    this.#client.registerSensorSubscription(subscriptionKey, callback, {
+      deviceIndex: this.index,
+      featureIndex: feature.index,
+      type
+    });
+    return async () => {
+      this.#client.unregisterSensorSubscription(subscriptionKey);
+      await this.#sendInputCmd({ featureIndex: feature.index, type, command: "Unsubscribe" });
+    };
+  }
+  /**
+   * Explicitly unsubscribes from a sensor subscription by type and sensor index.
+   *
+   * @param type - The sensor type to unsubscribe from
+   * @param sensorIndex - Index of the sensor if the device has multiple of the same type
+   */
+  async unsubscribe(type, sensorIndex = 0) {
+    const features = getInputsByType(this.#features, type);
+    const feature = features[sensorIndex];
+    if (!feature) {
+      throw new DeviceError(this.index, `Device does not have ${type} sensor at index ${sensorIndex}`);
+    }
+    const subscriptionKey = sensorKey(this.index, feature.index, type);
+    this.#client.unregisterSensorSubscription(subscriptionKey);
+    await this.#sendInputCmd({ featureIndex: feature.index, type, command: "Unsubscribe" });
+  }
+  /**
+   * Checks whether this device supports a given output type.
+   *
+   * @param type - The output type to check
+   * @returns `true` if at least one feature supports the output type
+   */
+  canOutput(type) {
+    return hasOutputType(this.#features, type);
+  }
+  /**
+   * Checks whether this device can perform a one-shot read of a given sensor type.
+   *
+   * @param type - The input type to check
+   * @returns `true` if at least one matching sensor supports reading
+   */
+  canRead(type) {
+    return getInputsByType(this.#features, type).some((f) => f.canRead);
+  }
+  /**
+   * Checks whether this device supports subscriptions for a given sensor type.
+   *
+   * @param type - The input type to check
+   * @returns `true` if at least one matching sensor supports subscriptions
+   */
+  canSubscribe(type) {
+    return getInputsByType(this.#features, type).some((f) => f.canSubscribe);
+  }
+  /** Server-assigned device index. */
+  get index() {
+    return this.#raw.DeviceIndex;
+  }
+  /** Internal device name from firmware. */
+  get name() {
+    return this.#raw.DeviceName;
+  }
+  /** User-facing display name, or `null` if the server did not provide one. */
+  get displayName() {
+    return this.#raw.DeviceDisplayName ?? null;
+  }
+  /** Minimum interval in milliseconds between messages recommended by the server. */
+  get messageTimingGap() {
+    return this.#raw.DeviceMessageTimingGap;
+  }
+  /** Parsed input and output feature descriptors for this device. */
+  get features() {
+    return this.#features;
+  }
+  /** Whether this device supports any form of rotation output. */
+  get canRotate() {
+    return this.canOutput("Rotate") || this.canOutput("RotateWithDirection");
+  }
+  /** Whether this device supports any form of position output. */
+  get canPosition() {
+    return this.canOutput("Position") || this.canOutput("HwPositionWithDuration");
+  }
+  /** Warns when commands are sent faster than the device's timing gap. */
+  #checkTimingGap() {
+    const gap = this.#raw.DeviceMessageTimingGap;
+    if (gap <= 0) {
+      return;
+    }
+    const now = Date.now();
+    const elapsed = now - this.#lastCommandTime;
+    if (this.#lastCommandTime > 0 && elapsed < gap) {
+      this.#logger.warn(
+        `Command sent ${elapsed}ms after previous (timing gap is ${gap}ms) \u2014 server may drop this command`
+      );
+    }
+    this.#lastCommandTime = now;
+  }
+  /**
+   * Validates sensor existence and capability.
+   *
+   * @throws DeviceError if sensor doesn't exist or lacks the capability
+   */
+  #requireSensor(params) {
+    const { type, sensorIndex, capability } = params;
+    const features = getInputsByType(this.#features, type);
+    const feature = features[sensorIndex];
+    if (!feature) {
+      throw new DeviceError(this.index, `Device does not have ${type} sensor at index ${sensorIndex}`);
+    }
+    const label = capability === "canRead" ? "reading" : "subscriptions";
+    if (!feature[capability]) {
+      throw new DeviceError(this.index, `${type} sensor at index ${sensorIndex} does not support ${label}`);
+    }
+    return feature;
+  }
+  /** Executes InputCmd and returns the server's first response. */
+  async #sendInputCmd(params) {
+    const { featureIndex, type, command } = params;
+    const id = this.#client.nextId();
+    const responses = await this.#client.send({
+      InputCmd: { Id: id, DeviceIndex: this.index, FeatureIndex: featureIndex, Type: type, Command: command }
+    });
+    return responses[0];
+  }
+  /**
+   * Sends scalar output commands after validating feature support.
+   *
+   * @throws DeviceError if the output type is not supported
+   */
+  async #sendScalarOutput(params) {
+    this.#checkTimingGap();
+    const { type, errorLabel, values } = params;
+    if (!this.canOutput(type)) {
+      throw new DeviceError(this.index, `Device does not support ${errorLabel}`);
+    }
+    const features = getOutputsByType(this.#features, type);
+    const messages = buildScalarOutputMessages({
+      client: this.#client,
+      deviceIndex: this.index,
+      type,
+      features,
+      values,
+      errorLabel
+    });
+    this.#logger.debug(`${type} command: ${messages.length} actuator(s) on device ${this.name}`);
+    await sendMessages(this.#client, messages);
+  }
+};
+
+// src/transport/connection.ts
+var WebSocketTransport = class {
+  /** Logger for connection diagnostics. */
+  #logger;
+  /** Map of event names to sets of handler callbacks. */
+  #listeners = /* @__PURE__ */ new Map();
+  /** Active WebSocket instance, null when disconnected. */
+  #ws = null;
+  /** Current connection lifecycle state. */
+  #state = "disconnected";
+  /** Tracks in-flight connection attempt to deduplicate concurrent connect calls. */
+  #connectPromise = null;
+  /** Set by disconnect() when a connect() is in flight to signal early teardown. */
+  #disconnectRequested = false;
+  /** Stored handler references for cleanup. */
+  #handleMessage = null;
+  #handleClose = null;
+  #handleError = null;
+  constructor(options = {}) {
+    this.#logger = (options.logger ?? noopLogger).child("ws-transport");
+  }
+  /**
+   * Opens a WebSocket connection to the given URL.
+   *
+   * Returns immediately if already connected. Deduplicates concurrent
+   * connect calls by returning the same in-flight promise.
+   *
+   * @param url - The WebSocket endpoint to connect to
+   * @throws {ConnectionError} if the connection fails or is closed during handshake
+   */
+  connect(url) {
+    if (this.#state === "connected") {
+      return Promise.resolve();
+    }
+    if (this.#connectPromise) {
+      return this.#connectPromise;
+    }
+    this.#state = "connecting";
+    this.#disconnectRequested = false;
+    this.#logger.debug(`Opening WebSocket connection to ${url}`);
+    this.#connectPromise = new Promise((resolve, reject) => {
+      try {
+        this.#ws = new WebSocket(url);
+      } catch (error) {
+        this.#state = "disconnected";
+        reject(
+          new ConnectionError(
+            `Failed to create WebSocket: ${formatError(error)}`,
+            error instanceof Error ? error : void 0
+          )
+        );
+        return;
+      }
+      const handleOpen = () => {
+        cleanup();
+        if (this.#disconnectRequested) {
+          this.#disconnectRequested = false;
+          this.#cleanup();
+          resolve();
+          return;
+        }
+        this.#state = "connected";
+        this.#attachHandlers();
+        this.#logger.info("WebSocket connected");
+        this.#emit("open");
+        resolve();
+      };
+      const handleError = (event) => {
+        cleanup();
+        this.#logger.error(`WebSocket error during connect: ${event.type}`);
+        const error = new ConnectionError(`WebSocket error: ${event.type}`);
+        this.#state = "disconnected";
+        this.#ws = null;
+        this.#emit("error", error);
+        reject(error);
+      };
+      const handleClose = (event) => {
+        cleanup();
+        this.#state = "disconnected";
+        this.#ws = null;
+        const reason = event.reason || `Code: ${event.code}`;
+        this.#logger.info(`WebSocket closed during connect (code: ${event.code})`);
+        this.#emit("close", event.code, reason);
+        reject(new ConnectionError(`WebSocket closed during connect: ${reason}`));
+      };
+      const cleanup = () => {
+        if (this.#ws) {
+          this.#ws.removeEventListener("open", handleOpen);
+          this.#ws.removeEventListener("error", handleError);
+          this.#ws.removeEventListener("close", handleClose);
+        }
+      };
+      this.#ws.addEventListener("open", handleOpen);
+      this.#ws.addEventListener("error", handleError);
+      this.#ws.addEventListener("close", handleClose);
+    }).finally(() => {
+      this.#connectPromise = null;
+    });
+    return this.#connectPromise;
+  }
+  /**
+   * Closes the active WebSocket connection.
+   *
+   * No-ops if already disconnected. Waits for the close handshake to complete
+   * if the socket is currently open or closing.
+   */
+  disconnect() {
+    if (this.#state === "disconnected") {
+      return Promise.resolve();
+    }
+    if (this.#connectPromise) {
+      this.#disconnectRequested = true;
+    }
+    this.#logger.info("Disconnecting WebSocket");
+    if (!this.#ws || this.#ws.readyState === WebSocket.CLOSED) {
+      this.#cleanup();
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      const ws = this.#ws;
+      if (ws?.readyState === WebSocket.CLOSING) {
+        const onClose2 = () => {
+          ws.removeEventListener("close", onClose2);
+          this.#cleanup();
+          resolve();
+        };
+        ws.addEventListener("close", onClose2);
+        return;
+      }
+      if (!ws) {
+        this.#cleanup();
+        resolve();
+        return;
+      }
+      const onClose = () => {
+        ws.removeEventListener("close", onClose);
+        this.#cleanup();
+        resolve();
+      };
+      ws.addEventListener("close", onClose);
+      ws.close(1e3, "Client disconnect");
+    });
+  }
+  /**
+   * Sends a text message over the active WebSocket.
+   *
+   * @param data - The string payload to send
+   * @throws {ConnectionError} if the WebSocket is not in the OPEN state or send fails
+   */
+  send(data) {
+    if (!this.#ws || this.#ws.readyState !== WebSocket.OPEN) {
+      throw new ConnectionError("Cannot send: WebSocket is not connected");
+    }
+    try {
+      this.#ws.send(data);
+    } catch (error) {
+      throw new ConnectionError(
+        `Failed to send data: ${formatError(error)}`,
+        error instanceof Error ? error : void 0
+      );
+    }
+  }
+  /**
+   * Subscribes a handler for the given transport event.
+   *
+   * @param event - The event to listen for
+   * @param handler - The callback to invoke when the event fires
+   */
+  on(event, handler) {
+    let handlers = this.#listeners.get(event);
+    if (!handlers) {
+      handlers = /* @__PURE__ */ new Set();
+      this.#listeners.set(event, handlers);
+    }
+    handlers.add(handler);
+  }
+  /**
+   * Removes a previously registered handler for the given event.
+   *
+   * @param event - The event to stop listening for
+   * @param handler - The callback to remove
+   */
+  off(event, handler) {
+    const handlers = this.#listeners.get(event);
+    if (handlers) {
+      handlers.delete(handler);
+    }
+  }
+  /** Current connection lifecycle state. */
+  get state() {
+    return this.#state;
+  }
+  /** Dispatches an event to all registered handlers for that event name. */
+  #emit(event, ...args) {
+    const handlers = this.#listeners.get(event);
+    if (!handlers) {
+      return;
+    }
+    for (const handler of handlers) {
+      try {
+        handler(...args);
+      } catch (err) {
+        this.#logger.error(`Error in ${event} handler: ${formatError(err)}`);
+      }
+    }
+  }
+  /** Wires up message, close, and error listeners on the active WebSocket. */
+  #attachHandlers() {
+    const ws = this.#ws;
+    if (!ws) {
+      return;
+    }
+    this.#handleMessage = (event) => {
+      if (typeof event.data === "string") {
+        this.#emit("message", event.data);
+      }
+    };
+    this.#handleClose = (event) => {
+      this.#removeHandlers();
+      this.#state = "disconnected";
+      this.#ws = null;
+      const reason = event.reason || `Code: ${event.code}`;
+      this.#logger.info(`WebSocket closed (code: ${event.code}, reason: ${reason})`);
+      this.#emit("close", event.code, reason);
+    };
+    this.#handleError = (event) => {
+      this.#logger.error(`WebSocket error: ${event.type}`);
+      this.#emit("error", new ConnectionError(`WebSocket error: ${event.type}`));
+    };
+    ws.addEventListener("message", this.#handleMessage);
+    ws.addEventListener("close", this.#handleClose);
+    ws.addEventListener("error", this.#handleError);
+  }
+  /** Removes message/close/error listeners from the active WebSocket. */
+  #removeHandlers() {
+    const ws = this.#ws;
+    if (!ws) {
+      return;
+    }
+    if (this.#handleMessage) {
+      ws.removeEventListener("message", this.#handleMessage);
+      this.#handleMessage = null;
+    }
+    if (this.#handleClose) {
+      ws.removeEventListener("close", this.#handleClose);
+      this.#handleClose = null;
+    }
+    if (this.#handleError) {
+      ws.removeEventListener("error", this.#handleError);
+      this.#handleError = null;
+    }
+  }
+  /** Removes listeners, nulls the socket reference, and resets state to disconnected. */
+  #cleanup() {
+    this.#removeHandlers();
+    this.#ws = null;
+    this.#state = "disconnected";
+    this.#logger.debug("WebSocket cleaned up");
+  }
+};
+
+// src/transport/ping.ts
+var MIN_PING_INTERVAL_MS = 100;
+var DEFAULT_PING_TIMEOUT_MS = 5e3;
+var PingManager = class {
+  /** Sends a protocol-level ping and resolves when the pong arrives. */
+  #sendPing;
+  /** Cancels an in-flight ping with the given error (e.g. on timeout). */
+  #cancelPing;
+  /** Logger for ping diagnostics. */
+  #logger;
+  /** Whether automatic periodic pings are enabled. */
+  #autoPing;
+  /** Callback invoked when a ping fails with a non-timeout error. */
+  #onError;
+  /** Callback to initiate disconnect when a ping times out. */
+  #onDisconnect;
+  /** Returns whether the transport is currently connected. */
+  #isConnected;
+  /** Interval timer that triggers periodic ping attempts. */
+  #pingTimer = null;
+  /** Tracks whether a ping request is currently awaiting a response. */
+  #pingInFlight = false;
+  /** Maximum time in ms the server allows between pings. */
+  #maxPingTime = 0;
+  constructor(options) {
+    this.#sendPing = options.sendPing;
+    this.#cancelPing = options.cancelPing;
+    this.#logger = (options.logger ?? noopLogger).child("ping");
+    this.#autoPing = options.autoPing ?? true;
+    this.#onError = options.onError;
+    this.#onDisconnect = options.onDisconnect;
+    this.#isConnected = options.isConnected;
+  }
+  /**
+   * Starts the periodic ping timer.
+   *
+   * The ping interval is 60% of `maxPingTime`, clamped to a minimum of 100ms.
+   * Stops any previously running timer before starting a new one.
+   *
+   * **Important**: Callers must call {@link PingManager.stop} when the transport
+   * disconnects to prevent pings from being sent to a closed connection.
+   *
+   * @param maxPingTime - Maximum time in ms the server allows between pings
+   */
+  start(maxPingTime) {
+    if (this.#pingInFlight) {
+      this.#cancelPing(new TimeoutError("Ping", 0));
+    }
+    this.stop();
+    this.#maxPingTime = maxPingTime;
+    if (!this.#autoPing || maxPingTime <= 0) {
+      return;
+    }
+    const pingInterval = Math.max(Math.floor(maxPingTime * 0.6), MIN_PING_INTERVAL_MS);
+    this.#logger.debug(`Starting ping timer with interval ${pingInterval}ms`);
+    this.#pingTimer = setInterval(() => {
+      if (!this.#isConnected()) {
+        return;
+      }
+      if (this.#pingInFlight) {
+        this.#logger.warn("Skipping ping: previous ping still in flight");
+        return;
+      }
+      this.#pingInFlight = true;
+      this.#doPing().finally(() => {
+        this.#pingInFlight = false;
+      });
+    }, pingInterval);
+  }
+  /** Stops the ping timer and resets in-flight state. */
+  stop() {
+    if (this.#pingTimer !== null) {
+      clearInterval(this.#pingTimer);
+      this.#pingTimer = null;
+      this.#pingInFlight = false;
+      this.#logger.debug("Stopped ping timer");
+    }
+  }
+  /** Sends a single ping and handles timeout or failure. */
+  async #doPing() {
+    this.#logger.debug("Sending ping");
+    const maxPingTime = this.#maxPingTime || DEFAULT_PING_TIMEOUT_MS;
+    const timer = setTimeout(() => {
+      this.#cancelPing(new TimeoutError("Ping", maxPingTime));
+    }, maxPingTime);
+    try {
+      await this.#sendPing();
+    } catch (err) {
+      const isTimeout = err instanceof TimeoutError;
+      this.#logger.error(`Ping failed: ${formatError(err)}`);
+      this.#onError(err instanceof Error ? err : new Error(String(err)));
+      if (isTimeout && this.#isConnected()) {
+        await this.#onDisconnect("Ping response timeout");
+      } else if (!isTimeout) {
+        this.#logger.warn("Ping failed with non-timeout error, not disconnecting");
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+
+// src/transport/constants.ts
+var ReconnectDefaults = {
+  DELAY: 1e3,
+  MAX_DELAY: 3e4,
+  MAX_ATTEMPTS: 10
+};
+
+// src/transport/reconnect.ts
+var MAX_BACKOFF_EXPONENT = 30;
+var ReconnectHandler = class {
+  /** The WebSocket endpoint URL to reconnect to. */
+  #url;
+  /** The transport instance to reconnect. */
+  #transport;
+  /** Base delay in ms before the first reconnect attempt. */
+  #reconnectDelay;
+  /** Upper bound in ms for exponential backoff. */
+  #maxReconnectDelay;
+  /** Maximum number of reconnect attempts before giving up. */
+  #maxReconnectAttempts;
+  /** Logger for reconnection diagnostics. */
+  #logger;
+  /** Callback invoked before each reconnect attempt. */
+  #onReconnecting;
+  /** Callback invoked when reconnection succeeds. */
+  #onReconnected;
+  /** Callback invoked when all reconnect attempts are exhausted. */
+  #onFailed;
+  /** Current reconnect attempt number, incremented before each attempt. */
+  #reconnectAttempt = 0;
+  /** Timer that schedules the next reconnect attempt. */
+  #reconnectTimer = null;
+  /** Whether a reconnection sequence is currently active. */
+  #reconnecting = false;
+  /** Whether the reconnection sequence was explicitly cancelled. */
+  #cancelled = false;
+  constructor(options) {
+    this.#url = options.url;
+    this.#transport = options.transport;
+    this.#reconnectDelay = options.reconnectDelay ?? ReconnectDefaults.DELAY;
+    this.#maxReconnectDelay = options.maxReconnectDelay ?? ReconnectDefaults.MAX_DELAY;
+    this.#maxReconnectAttempts = options.maxReconnectAttempts ?? ReconnectDefaults.MAX_ATTEMPTS;
+    this.#logger = (options.logger ?? noopLogger).child("reconnect");
+    this.#onReconnecting = options.onReconnecting;
+    this.#onReconnected = options.onReconnected;
+    this.#onFailed = options.onFailed;
+  }
+  /**
+   * Begins the reconnection sequence.
+   *
+   * No-ops if a reconnection is already in progress.
+   */
+  start() {
+    if (this.#reconnecting) {
+      return;
+    }
+    this.#logger.info("Starting reconnection sequence");
+    this.#reconnecting = true;
+    this.#cancelled = false;
+    this.#attemptReconnect();
+  }
+  /** Cancels the reconnection sequence and clears any pending timers. */
+  cancel() {
+    this.#logger.debug("Reconnect cancelled");
+    this.#cancelled = true;
+    if (this.#reconnectTimer) {
+      clearTimeout(this.#reconnectTimer);
+      this.#reconnectTimer = null;
+    }
+    this.#reconnecting = false;
+    this.#reconnectAttempt = 0;
+  }
+  /** Whether a reconnection sequence is currently in progress. */
+  get active() {
+    return this.#reconnecting;
+  }
+  /** Safely invokes a user callback, catching and logging any errors. */
+  #safeCallback(name, fn) {
+    try {
+      fn();
+    } catch (err) {
+      this.#logger.error(`Error in ${name} callback: ${formatError(err)}`);
+    }
+  }
+  /** Schedules the next reconnect attempt with exponential backoff. */
+  #attemptReconnect() {
+    if (this.#cancelled || !this.#reconnecting) {
+      return;
+    }
+    this.#reconnectAttempt++;
+    if (this.#reconnectAttempt > this.#maxReconnectAttempts) {
+      const reason = `Failed to reconnect after ${this.#maxReconnectAttempts} attempts`;
+      this.#logger.error(reason);
+      this.#reconnecting = false;
+      if (this.#onFailed) {
+        this.#safeCallback("onFailed", () => this.#onFailed?.(reason));
+      }
+      return;
+    }
+    if (this.#onReconnecting) {
+      this.#safeCallback("onReconnecting", () => this.#onReconnecting?.(this.#reconnectAttempt));
+    }
+    const exponent = Math.min(this.#reconnectAttempt - 1, MAX_BACKOFF_EXPONENT);
+    const delay = Math.min(this.#reconnectDelay * 2 ** exponent, this.#maxReconnectDelay);
+    this.#logger.info(
+      `Reconnect attempt ${this.#reconnectAttempt}/${this.#maxReconnectAttempts} (delay: ${delay}ms)`
+    );
+    this.#reconnectTimer = setTimeout(async () => {
+      if (this.#cancelled || !this.#reconnecting) {
+        return;
+      }
+      try {
+        if (this.#transport.state !== "disconnected") {
+          await this.#transport.disconnect();
+        }
+        await this.#transport.connect(this.#url);
+        if (this.#cancelled) {
+          return;
+        }
+        this.#reconnecting = false;
+        this.#reconnectAttempt = 0;
+        this.#logger.info("Reconnection successful");
+        if (this.#onReconnected) {
+          this.#safeCallback("onReconnected", () => this.#onReconnected?.());
+        }
+      } catch (err) {
+        if (this.#cancelled) {
+          return;
+        }
+        this.#logger.debug(`Reconnect attempt ${this.#reconnectAttempt} failed: ${formatError(err)}`);
+        this.#attemptReconnect();
+      }
+    }, delay);
+  }
+};
+
+// src/client.ts
+var STOP_DEVICES_TIMEOUT_MS = 2e3;
+var DISCONNECT_TIMEOUT_MS = 3e3;
+var ButtplugClient = class extends Emittery {
+  #url;
+  #clientName;
+  #baseLogger;
+  #logger;
+  #transport;
+  #messageRouter;
+  #pingManager;
+  #sensorHandler;
+  #reconnectHandler;
+  #devices = /* @__PURE__ */ new Map();
+  #scanning = false;
+  #serverInfo = null;
+  #connectPromise = null;
+  #isHandshaking = false;
+  constructor(url, options = {}) {
+    super();
+    this.#url = url;
+    this.#clientName = options.clientName ?? DEFAULT_CLIENT_NAME;
+    this.#baseLogger = options.logger ?? noopLogger;
+    this.#logger = this.#baseLogger.child("client");
+    this.#transport = new WebSocketTransport({ logger: this.#baseLogger });
+    this.#transport.on("message", (data) => {
+      this.#messageRouter.handleMessage(data);
+    });
+    this.#transport.on("close", (_code, reason) => {
+      this.#safetyStop();
+      this.#pingManager.stop();
+      this.emit("disconnected", { reason });
+    });
+    this.#transport.on("error", (error) => {
+      this.emit("error", { error });
+    });
+    const routerOpts = {
+      send: (data) => this.#transport.send(data),
+      timeout: options.requestTimeout,
+      logger: this.#baseLogger,
+      onDeviceList: (devices) => runWithLogger(
+        this.#logger,
+        () => reconcileDevices({
+          currentDevices: this.#devices,
+          incomingRaw: devices,
+          createDevice: (raw) => new Device({ client: this, raw }),
+          callbacks: {
+            onAdded: (d) => this.emit("deviceAdded", { device: d }),
+            onRemoved: (d) => this.emit("deviceRemoved", { device: d }),
+            onUpdated: (d, old) => this.emit("deviceUpdated", { device: d, previousDevice: old }),
+            onList: (list) => this.emit("deviceList", { devices: list })
+          }
+        })
+      ),
+      onScanningFinished: () => {
+        this.#scanning = false;
+        this.emit("scanningFinished", void 0);
+      },
+      onInputReading: (reading) => {
+        this.#sensorHandler.handleReading(reading, (r) => this.emit("inputReading", { reading: r }));
+      },
+      onError: (error) => {
+        this.#logger.warn(`System error from server: [${error.ErrorCode}] ${error.ErrorMessage}`);
+        this.emit("error", { error: new ProtocolError(error.ErrorCode, error.ErrorMessage) });
+        if (error.ErrorCode === ErrorCode.PING) {
+          this.#logger.error("Server ping timeout \u2014 server will halt devices and disconnect");
+          this.disconnect("Server ping timeout");
+        }
+      }
+    };
+    this.#messageRouter = new MessageRouter(routerOpts);
+    this.#pingManager = new PingManager({
+      sendPing: async () => {
+        await this.#messageRouter.send(createPing(this.#messageRouter.nextId()));
+      },
+      cancelPing: (error) => this.#messageRouter.cancelAll(error),
+      logger: this.#baseLogger,
+      autoPing: options.autoPing ?? true,
+      onError: (error) => this.emit("error", { error }),
+      onDisconnect: (reason) => this.disconnect(reason),
+      isConnected: () => this.connected
+    });
+    this.#sensorHandler = new SensorHandler(this.#baseLogger);
+    if (options.autoReconnect) {
+      this.#reconnectHandler = new ReconnectHandler({
+        url: this.#url,
+        transport: this.#transport,
+        reconnectDelay: options.reconnectDelay,
+        maxReconnectDelay: options.maxReconnectDelay,
+        maxReconnectAttempts: options.maxReconnectAttempts,
+        logger: this.#baseLogger,
+        onReconnecting: (attempt) => {
+          this.#pingManager.stop();
+          this.emit("reconnecting", { attempt });
+        },
+        onReconnected: () => this.#handleReconnected(),
+        onFailed: (reason) => {
+          this.#logger.error(`Reconnection failed: ${reason}`);
+          this.emit("error", { error: new ConnectionError(reason) });
+        }
+      });
+    } else {
+      this.#reconnectHandler = null;
+    }
+    this.on("disconnected", () => {
+      this.#scanning = false;
+      this.#serverInfo = null;
+      this.#sensorHandler.clear();
+      for (const device of this.#devices.values()) {
+        this.emit("deviceRemoved", { device });
+      }
+      this.#devices.clear();
+      if (this.#reconnectHandler) {
+        this.#reconnectHandler.start();
+      }
+    });
+    this.on("deviceRemoved", ({ device }) => {
+      this.#sensorHandler.unsubscribeDevice({
+        deviceIndex: device.index,
+        router: this.#messageRouter,
+        connected: this.#serverInfo !== null && this.connected
+      });
+    });
+  }
+  /**
+   * Opens a WebSocket connection and performs the Buttplug handshake.
+   *
+   * @throws ConnectionError if the transport fails to connect
+   * @throws HandshakeError if the server rejects the handshake
+   */
+  async connect() {
+    if (this.connected && this.#serverInfo) {
+      return;
+    }
+    if (this.#connectPromise) {
+      return this.#connectPromise;
+    }
+    this.#connectPromise = this.#performConnect();
+    try {
+      await this.#connectPromise;
+    } finally {
+      this.#connectPromise = null;
+    }
+  }
+  /**
+   * Gracefully disconnects from the server.
+   *
+   * Stops all devices, sends a protocol-level disconnect message, then closes
+   * the WebSocket. Both stop and disconnect steps are time-bounded so the
+   * method does not hang indefinitely.
+   *
+   * @param reason - Optional human-readable reason for the disconnection
+   */
+  async disconnect(reason) {
+    if (this.#reconnectHandler?.active) {
+      this.#reconnectHandler.cancel();
+      this.#pingManager.stop();
+      this.emit("disconnected", { reason: reason ?? "Client disconnected" });
+    }
+    if (!this.connected) {
+      return;
+    }
+    this.#logger.info(`Disconnecting${reason ? `: ${reason}` : ""}`);
+    this.#pingManager.stop();
+    this.#reconnectHandler?.cancel();
+    if (this.#serverInfo !== null && !this.#isHandshaking) {
+      try {
+        await raceTimeout(this.stopAll(), STOP_DEVICES_TIMEOUT_MS);
+      } catch {
+        this.#logger.warn("Stop all devices timed out during disconnect");
+      }
+      try {
+        await raceTimeout(
+          this.#messageRouter.send(createDisconnect(this.#messageRouter.nextId())),
+          DISCONNECT_TIMEOUT_MS
+        );
+      } catch {
+        this.#logger.warn("Disconnect message failed or timed out");
+      }
+    }
+    this.#messageRouter.cancelAll(new ConnectionError("Client disconnected"));
+    await this.#transport.disconnect();
+  }
+  /**
+   * Begins scanning for devices on the server.
+   *
+   * @throws ConnectionError if the client is not connected
+   */
+  async startScanning() {
+    this.#requireConnection("start scanning");
+    await this.#messageRouter.send(createStartScanning(this.#messageRouter.nextId()));
+    this.#scanning = true;
+  }
+  /**
+   * Stops an active device scan on the server.
+   *
+   * @throws ConnectionError if the client is not connected
+   */
+  async stopScanning() {
+    this.#requireConnection("stop scanning");
+    await this.#messageRouter.send(createStopScanning(this.#messageRouter.nextId()));
+    this.#scanning = false;
+  }
+  /**
+   * Sends a global stop command to halt all devices on the server.
+   *
+   * @throws ConnectionError if the client is not connected
+   */
+  async stopAll() {
+    this.#requireConnection("stop devices");
+    await this.#messageRouter.send(createStopCmd(this.#messageRouter.nextId()));
+  }
+  /**
+   * Requests the current device list from the server.
+   *
+   * The response triggers device reconciliation and emits
+   * `deviceAdded`, `deviceRemoved`, `deviceUpdated`, and `deviceList` events.
+   *
+   * @throws ConnectionError if the client is not connected
+   */
+  async requestDeviceList() {
+    this.#requireConnection("request device list");
+    const responses = await this.#messageRouter.send(createRequestDeviceList(this.#messageRouter.nextId()));
+    for (const response of responses) {
+      if (isDeviceList(response)) {
+        const deviceList = getDeviceList(response);
+        runWithLogger(
+          this.#logger,
+          () => reconcileDevices({
+            currentDevices: this.#devices,
+            incomingRaw: Object.values(deviceList.Devices),
+            createDevice: (raw) => new Device({ client: this, raw }),
+            callbacks: {
+              onAdded: (d) => this.emit("deviceAdded", { device: d }),
+              onRemoved: (d) => this.emit("deviceRemoved", { device: d }),
+              onUpdated: (d, old) => this.emit("deviceUpdated", { device: d, previousDevice: old }),
+              onList: (list) => this.emit("deviceList", { devices: list })
+            }
+          })
+        );
+      }
+    }
+  }
+  /**
+   * Sends one or more raw protocol messages to the server.
+   *
+   * @param messages - A single message or array of messages to send
+   * @returns Server response messages
+   * @throws ConnectionError if the client is not connected
+   */
+  async send(messages) {
+    this.#requireConnection("send message");
+    return await this.#messageRouter.send(messages);
+  }
+  /**
+   * Returns the next monotonically increasing message ID.
+   *
+   * @returns A unique message ID for the next outgoing message
+   */
+  nextId() {
+    return this.#messageRouter.nextId();
+  }
+  /**
+   * Registers a callback for incoming sensor readings.
+   *
+   * @param key - Unique subscription key (typically from `sensorKey()`)
+   * @param callback - Function invoked when a matching reading arrives
+   * @param info - Device, feature, and input type identifying the subscription
+   */
+  registerSensorSubscription(key, callback, info) {
+    this.#sensorHandler.register(key, callback, info);
+  }
+  /**
+   * Removes a previously registered sensor subscription.
+   *
+   * @param key - The subscription key to remove
+   */
+  unregisterSensorSubscription(key) {
+    this.#sensorHandler.unregister(key);
+  }
+  /**
+   * Retrieves a device by its server-assigned index.
+   *
+   * @param index - The device index
+   * @returns The {@link Device} instance, or `undefined` if not found
+   */
+  getDevice(index) {
+    return this.#devices.get(index);
+  }
+  /** Whether the WebSocket transport is currently connected. */
+  get connected() {
+    return this.#transport.state === "connected";
+  }
+  /** Whether a device scan is currently in progress. */
+  get scanning() {
+    return this.#scanning;
+  }
+  /** Server information received during handshake, or `null` if not connected. */
+  get serverInfo() {
+    return this.#serverInfo;
+  }
+  /** Snapshot of all currently known {@link Device} instances. */
+  get devices() {
+    return Array.from(this.#devices.values());
+  }
+  /** Best-effort StopCmd bypassing connection checks for safety-critical scenarios. */
+  #safetyStop() {
+    try {
+      if (this.#transport.state === "connected") {
+        const msg = createStopCmd(this.#messageRouter.nextId());
+        this.#transport.send(serializeMessage(msg));
+      }
+    } catch {
+      this.#logger.warn("Safety stop failed \u2014 transport may already be closed");
+    }
+  }
+  /**
+   * Validates connection state before performing an action.
+   *
+   * @throws ConnectionError if not connected
+   */
+  #requireConnection(action) {
+    if (!this.connected) {
+      throw new ConnectionError(`Cannot ${action}: not connected`);
+    }
+  }
+  /** Executes the transport connection and protocol handshake. */
+  async #performConnect() {
+    this.#logger.info(`Connecting to ${this.#url}`);
+    await this.#transport.connect(this.#url);
+    this.#isHandshaking = true;
+    try {
+      this.#serverInfo = await performHandshake({
+        router: this.#messageRouter,
+        clientName: this.#clientName,
+        pingManager: this.#pingManager,
+        logger: this.#logger
+      });
+    } finally {
+      this.#isHandshaking = false;
+    }
+    this.#logger.info(`Connected to server: ${this.#serverInfo?.ServerName ?? "unknown"}`);
+    this.emit("connected", void 0);
+  }
+  /**
+   * Re-handshakes and reconciles device state after reconnection.
+   *
+   * Resets all client state, performs a new handshake, and requests the device list.
+   * Emits an error and disconnects if the handshake fails.
+   */
+  async #handleReconnected() {
+    this.#logger.info("Reconnected, performing handshake");
+    this.#messageRouter.cancelAll(new ConnectionError("Reconnecting"));
+    this.#messageRouter.resetId();
+    this.#serverInfo = null;
+    this.#scanning = false;
+    this.#sensorHandler.clear();
+    try {
+      this.#serverInfo = await performHandshake({
+        router: this.#messageRouter,
+        clientName: this.#clientName,
+        pingManager: this.#pingManager,
+        logger: this.#logger
+      });
+      this.emit("reconnected", void 0);
+      await this.requestDeviceList();
+    } catch (err) {
+      this.#logger.error(`Handshake failed after reconnect: ${formatError(err)}`);
+      this.emit("error", { error: err instanceof Error ? err : new Error(String(err)) });
+      await this.disconnect("Handshake failed after reconnect");
+    }
+  }
+};
+
+// src/patterns/easing.ts
+var clamp = (t) => Math.min(1, Math.max(0, t));
+var linear = (t) => clamp(t);
+var easeIn = (t) => clamp(t) ** 3;
+var easeOut = (t) => 1 - (1 - clamp(t)) ** 3;
+var easeInOut = (t) => {
+  const c = clamp(t);
+  return c < 0.5 ? 4 * c ** 3 : 1 - (-2 * c + 2) ** 3 / 2;
+};
+var step = (t) => clamp(t) < 1 ? 0 : 1;
+var EASING_FUNCTIONS = {
+  linear,
+  easeIn,
+  easeOut,
+  easeInOut,
+  step
+};
+var ease = (t, easing) => {
+  const fn = EASING_FUNCTIONS[easing];
+  return fn ? fn(t) : clamp(t);
+};
+
+// src/patterns/types.ts
+import { z as z2 } from "zod";
+var EASING_VALUES = ["linear", "easeIn", "easeOut", "easeInOut", "step"];
+var EasingSchema = z2.enum(EASING_VALUES);
+var KeyframeSchema = z2.object({
+  value: z2.number().min(0).max(1),
+  duration: z2.number().int().nonnegative(),
+  easing: EasingSchema.optional()
+});
+var TrackSchema = z2.object({
+  featureIndex: z2.number().int().nonnegative(),
+  keyframes: z2.array(KeyframeSchema).min(1),
+  clockwise: z2.boolean().optional(),
+  outputType: OutputTypeSchema.optional()
+});
+var PRESET_NAMES = ["pulse", "wave", "ramp_up", "ramp_down", "heartbeat", "surge", "stroke"];
+var PresetPatternSchema = z2.object({
+  type: z2.literal("preset"),
+  preset: z2.enum(PRESET_NAMES),
+  intensity: z2.number().min(0).max(1).optional(),
+  speed: z2.number().min(0.25).max(4).optional(),
+  loop: z2.union([z2.boolean(), z2.number().int().positive()]).optional()
+});
+var CustomPatternSchema = z2.object({
+  type: z2.literal("custom"),
+  tracks: z2.array(TrackSchema).min(1),
+  intensity: z2.number().min(0).max(1).optional(),
+  loop: z2.union([z2.boolean(), z2.number().int().positive()]).optional()
+});
+var PatternDescriptorSchema = z2.discriminatedUnion("type", [PresetPatternSchema, CustomPatternSchema]);
+
+// src/patterns/presets.ts
+var MOTOR_OUTPUT_TYPES = ["Vibrate", "Rotate", "RotateWithDirection", "Oscillate", "Constrict"];
+var POSITION_OUTPUT_TYPES = ["Position", "HwPositionWithDuration"];
+var PRESETS = {
+  pulse: {
+    description: "Square wave on/off",
+    outputTypes: MOTOR_OUTPUT_TYPES,
+    tracks: [
+      [
+        { value: 0, duration: 0 },
+        { value: 1, duration: 0 },
+        { value: 1, duration: 500 },
+        { value: 0, duration: 0 },
+        { value: 0, duration: 500 }
+      ]
+    ],
+    loop: true
+  },
+  wave: {
+    description: "Smooth sine wave oscillation",
+    outputTypes: MOTOR_OUTPUT_TYPES,
+    tracks: [
+      [
+        { value: 0, duration: 0 },
+        { value: 0.5, duration: 500, easing: "easeInOut" },
+        { value: 1, duration: 500, easing: "easeInOut" },
+        { value: 0.5, duration: 500, easing: "easeInOut" },
+        { value: 0, duration: 500, easing: "easeInOut" }
+      ]
+    ],
+    loop: true
+  },
+  ramp_up: {
+    description: "Gradual increase to maximum",
+    outputTypes: MOTOR_OUTPUT_TYPES,
+    tracks: [
+      [
+        { value: 0, duration: 0 },
+        { value: 1, duration: 3e3, easing: "easeIn" }
+      ]
+    ],
+    loop: false
+  },
+  ramp_down: {
+    description: "Gradual decrease to zero",
+    outputTypes: MOTOR_OUTPUT_TYPES,
+    tracks: [
+      [
+        { value: 1, duration: 0 },
+        { value: 0, duration: 3e3, easing: "easeOut" }
+      ]
+    ],
+    loop: false
+  },
+  heartbeat: {
+    description: "Ba-bump heartbeat rhythm",
+    outputTypes: MOTOR_OUTPUT_TYPES,
+    tracks: [
+      [
+        { value: 0, duration: 0 },
+        { value: 1, duration: 0 },
+        { value: 1, duration: 100 },
+        { value: 0.3, duration: 50 },
+        { value: 0.8, duration: 0 },
+        { value: 0.8, duration: 100 },
+        { value: 0, duration: 0 },
+        { value: 0, duration: 750 }
+      ]
+    ],
+    loop: true
+  },
+  surge: {
+    description: "Build to peak then release",
+    outputTypes: MOTOR_OUTPUT_TYPES,
+    tracks: [
+      [
+        { value: 0.1, duration: 0 },
+        { value: 0.7, duration: 2e3, easing: "easeIn" },
+        { value: 1, duration: 500 },
+        { value: 1, duration: 1e3 },
+        { value: 0.1, duration: 1500, easing: "easeOut" }
+      ]
+    ],
+    loop: false
+  },
+  stroke: {
+    description: "Full-range position strokes",
+    outputTypes: POSITION_OUTPUT_TYPES,
+    tracks: [
+      [
+        { value: 0, duration: 0, easing: "easeInOut" },
+        { value: 1, duration: 1e3, easing: "easeInOut" },
+        { value: 0, duration: 1e3, easing: "easeInOut" }
+      ]
+    ],
+    loop: true
+  }
+};
+function getPresetInfo() {
+  return Object.entries(PRESETS).map(([name, def]) => ({
+    name,
+    description: def.description,
+    compatibleOutputTypes: def.outputTypes,
+    defaultLoop: def.loop
+  }));
+}
+
+// src/patterns/scheduler.ts
+function interpolateKeyframes(keyframes, elapsed) {
+  let accumulated = 0;
+  const first = keyframes[0];
+  if (!first) {
+    return 0;
+  }
+  let value = first.value;
+  for (const kf of keyframes) {
+    if (kf.duration === 0) {
+      if (elapsed >= accumulated) {
+        value = kf.value;
+      }
+      continue;
+    }
+    const prevValue = value;
+    if (elapsed < accumulated + kf.duration) {
+      const t = (elapsed - accumulated) / kf.duration;
+      const result = prevValue + (kf.value - prevValue) * ease(t, kf.easing);
+      return Math.max(0, Math.min(1, result));
+    }
+    accumulated += kf.duration;
+    value = kf.value;
+  }
+  return Math.max(0, Math.min(1, value));
+}
+function buildScalarCommand(track, value) {
+  switch (track.outputType) {
+    case "Vibrate":
+      return { Vibrate: { Value: value } };
+    case "Rotate":
+      return { Rotate: { Value: value } };
+    case "RotateWithDirection":
+      return { RotateWithDirection: { Value: value, Clockwise: track.clockwise } };
+    case "Oscillate":
+      return { Oscillate: { Value: value } };
+    case "Constrict":
+      return { Constrict: { Value: value } };
+    case "Position":
+      return { Position: { Value: value } };
+    default:
+      return { Vibrate: { Value: value } };
+  }
+}
+function getCycleDuration(tracks) {
+  let max = 0;
+  for (const track of tracks) {
+    let total = 0;
+    for (const kf of track.keyframes) {
+      total += kf.duration;
+    }
+    if (total > max) {
+      max = total;
+    }
+  }
+  return max;
+}
+function evaluateScalarTrack(state, track, elapsed, device, buildCommand, onError) {
+  const { keyframes, featureIndex, range } = track;
+  const value = interpolateKeyframes(keyframes, elapsed);
+  const mapped = Math.round(range[0] + value * (range[1] - range[0]));
+  if (state.lastSentValues.get(featureIndex) === mapped) {
+    return;
+  }
+  const command = buildCommand(track, mapped);
+  device.output({ featureIndex, command }).catch((err) => onError(state, err));
+  state.lastSentValues.set(featureIndex, mapped);
+}
+function evaluateHwPositionTrack(state, track, elapsed, device, onError) {
+  const { keyframes, featureIndex, range, durationRange } = track;
+  let accumulated = 0;
+  let activeIndex = 0;
+  for (const [i, kf2] of keyframes.entries()) {
+    if (kf2.duration === 0 && elapsed >= accumulated) {
+      if (state.lastSentKeyframeIndex.get(featureIndex) !== i) {
+        const mappedValue2 = Math.round(range[0] + kf2.value * (range[1] - range[0]));
+        const command2 = {
+          HwPositionWithDuration: { Position: mappedValue2, Duration: 0 }
+        };
+        device.output({ featureIndex, command: command2 }).catch((err) => onError(state, err));
+        state.lastSentKeyframeIndex.set(featureIndex, i);
+      }
+      activeIndex = i;
+      continue;
+    }
+    if (elapsed < accumulated + kf2.duration) {
+      activeIndex = i;
+      break;
+    }
+    accumulated += kf2.duration;
+    activeIndex = i;
+  }
+  const kf = keyframes[activeIndex];
+  if (!kf || kf.duration === 0) {
+    return;
+  }
+  if (state.lastSentKeyframeIndex.get(featureIndex) === activeIndex) {
+    return;
+  }
+  const mappedValue = Math.round(range[0] + kf.value * (range[1] - range[0]));
+  let duration = kf.duration;
+  if (durationRange) {
+    duration = Math.max(durationRange[0], Math.min(durationRange[1], duration));
+  }
+  const command = {
+    HwPositionWithDuration: { Position: mappedValue, Duration: duration }
+  };
+  device.output({ featureIndex, command }).catch((err) => onError(state, err));
+  state.lastSentKeyframeIndex.set(featureIndex, activeIndex);
+}
+
+// src/patterns/track-resolver.ts
+function resolveTracks(device, descriptor, featureIndex) {
+  if (descriptor.type === "preset") {
+    return resolvePresetTracks(device, descriptor, featureIndex);
+  }
+  return resolveCustomTracks(device, descriptor);
+}
+function resolvePresetTracks(device, descriptor, featureIndex) {
+  const preset = PRESETS[descriptor.preset];
+  if (!preset) {
+    throw new DeviceError(device.index, `Unknown preset: ${descriptor.preset}`);
+  }
+  const intensity = descriptor.intensity ?? 1;
+  const speed = descriptor.speed ?? 1;
+  const matchingFeatures = [];
+  for (const outputType of preset.outputTypes) {
+    const features = getOutputsByType(device.features, outputType);
+    for (const feature of features) {
+      if (featureIndex === void 0 || feature.index === featureIndex) {
+        matchingFeatures.push({ feature, outputType });
+      }
+    }
+  }
+  if (featureIndex !== void 0 && matchingFeatures.length === 0) {
+    throw new DeviceError(
+      device.index,
+      `Feature at index ${featureIndex} is not compatible with preset "${descriptor.preset}"`
+    );
+  }
+  const tracks = [];
+  for (const [i, match] of matchingFeatures.entries()) {
+    const presetTrack = preset.tracks[i % preset.tracks.length];
+    if (!presetTrack) {
+      continue;
+    }
+    const keyframes = presetTrack.map((kf) => ({
+      value: kf.value * intensity,
+      duration: speed > 0 ? kf.duration / speed : kf.duration,
+      easing: kf.easing ?? "linear"
+    }));
+    tracks.push({
+      featureIndex: match.feature.index,
+      outputType: match.outputType,
+      keyframes,
+      range: match.feature.range,
+      durationRange: match.feature.durationRange,
+      clockwise: true
+    });
+  }
+  return tracks;
+}
+function resolveCustomTracks(device, descriptor) {
+  const intensity = descriptor.intensity ?? 1;
+  const tracks = [];
+  for (const track of descriptor.tracks) {
+    const feature = track.outputType ? device.features.outputs.find(
+      (f) => f.index === track.featureIndex && f.type === track.outputType
+    ) : device.features.outputs.find((f) => f.index === track.featureIndex);
+    if (!feature) {
+      throw new DeviceError(
+        device.index,
+        `No output feature at index ${track.featureIndex}${track.outputType ? ` with type "${track.outputType}"` : ""}`
+      );
+    }
+    const keyframes = track.keyframes.map((kf) => ({
+      value: kf.value * intensity,
+      duration: kf.duration,
+      easing: kf.easing ?? "linear"
+    }));
+    tracks.push({
+      featureIndex: feature.index,
+      outputType: feature.type,
+      keyframes,
+      range: feature.range,
+      durationRange: feature.durationRange,
+      clockwise: track.clockwise ?? true
+    });
+  }
+  return tracks;
+}
+
+// src/patterns/engine.ts
+var DEFAULT_TIMEOUT_MS = 18e5;
+var MIN_TICK_INTERVAL_MS = 50;
+var noop = () => {
+};
+var PatternEngine = class {
+  /** Client interface for device access and event subscription. */
+  #client;
+  /** Active pattern states keyed by pattern ID. */
+  #patterns = /* @__PURE__ */ new Map();
+  /** Default safety timeout in milliseconds. */
+  #defaultTimeout;
+  /** Unsubscribe function for the client disconnect event. */
+  #unsubDisconnect;
+  /** Unsubscribe function for the device removed event. */
+  #unsubDeviceRemoved;
+  /** Whether this engine has been disposed. */
+  #disposed = false;
+  /**
+   * @param client - Client providing device access and event hooks
+   * @param options - Optional configuration for default timeout behavior
+   */
+  constructor(client, options) {
+    this.#client = client;
+    this.#defaultTimeout = options?.defaultTimeout ?? DEFAULT_TIMEOUT_MS;
+    this.#unsubDisconnect = client.on("disconnected", () => {
+      this.#stopMatchingPatterns("disconnect");
+    });
+    this.#unsubDeviceRemoved = client.on("deviceRemoved", ({ device }) => {
+      this.#stopMatchingPatterns("deviceRemoved", device.index);
+    });
+  }
+  // biome-ignore lint/suspicious/useAwait: async API contract per spec — errors become rejected promises
+  async play(device, pattern, options) {
+    const deviceIndex = typeof device === "number" ? device : device.index;
+    if (this.#disposed) {
+      throw new DeviceError(deviceIndex, "PatternEngine has been disposed");
+    }
+    const descriptor = this.#buildDescriptor(pattern, options);
+    const parsed = PatternDescriptorSchema.parse(descriptor);
+    const resolvedDevice = typeof device === "number" ? this.#client.getDevice(device) : device;
+    if (!resolvedDevice) {
+      throw new DeviceError(deviceIndex, `Device at index ${deviceIndex} not found`);
+    }
+    const tracks = resolveTracks(resolvedDevice, parsed, options?.featureIndex);
+    if (tracks.length === 0) {
+      throw new DeviceError(deviceIndex, "No compatible features found on device");
+    }
+    for (const s of this.#patterns.values()) {
+      if (s.deviceIndex === deviceIndex) {
+        this.#stopPatternInternal(s, "manual");
+      }
+    }
+    const loop = parsed.type === "preset" ? parsed.loop ?? PRESETS[parsed.preset]?.loop ?? false : parsed.loop ?? false;
+    let remainingLoops;
+    if (loop === true) {
+      remainingLoops = Number.POSITIVE_INFINITY;
+    } else if (typeof loop === "number") {
+      remainingLoops = loop;
+    } else {
+      remainingLoops = 1;
+    }
+    const id = crypto.randomUUID();
+    const tickInterval = Math.max(resolvedDevice.messageTimingGap, MIN_TICK_INTERVAL_MS);
+    const now = performance.now();
+    const state = {
+      id,
+      deviceIndex,
+      descriptor: parsed,
+      tracks,
+      loop,
+      remainingLoops,
+      startedAt: now,
+      stopped: false,
+      timerId: null,
+      safetyTimerId: null,
+      tickInterval,
+      expectedTickTime: now,
+      lastSentValues: /* @__PURE__ */ new Map(),
+      lastSentKeyframeIndex: /* @__PURE__ */ new Map(),
+      options: options ?? {}
+    };
+    this.#patterns.set(id, state);
+    const timeout = options?.timeout ?? this.#defaultTimeout;
+    if (timeout > 0) {
+      state.safetyTimerId = setTimeout(() => this.#stopPatternInternal(state, "timeout"), timeout);
+    }
+    state.timerId = setTimeout(() => this.#tick(state, resolvedDevice), 0);
+    return id;
+  }
+  /**
+   * Stops a specific pattern by its ID.
+   *
+   * No-op if the pattern ID is not found (already stopped or never started).
+   *
+   * @param patternId - The pattern instance ID returned by {@link play}
+   */
+  // biome-ignore lint/suspicious/useAwait: async API contract per spec
+  async stop(patternId) {
+    const state = this.#patterns.get(patternId);
+    if (!state) {
+      return;
+    }
+    this.#stopPatternInternal(state, "manual");
+  }
+  /**
+   * Stops all active patterns.
+   *
+   * @returns Number of patterns that were stopped
+   */
+  stopAll() {
+    return this.#stopMatchingPatterns("manual");
+  }
+  /**
+   * Stops all active patterns targeting a specific device.
+   *
+   * @param deviceIndex - The device index to stop patterns for
+   * @returns Number of patterns that were stopped
+   */
+  stopByDevice(deviceIndex) {
+    return this.#stopMatchingPatterns("manual", deviceIndex);
+  }
+  /**
+   * Returns a snapshot of all active patterns.
+   *
+   * @returns Array of {@link PatternInfo} snapshots
+   */
+  list() {
+    const now = performance.now();
+    return [...this.#patterns.values()].map((state) => ({
+      id: state.id,
+      deviceIndex: state.deviceIndex,
+      featureIndices: state.tracks.map((t) => t.featureIndex),
+      descriptor: state.descriptor,
+      startedAt: state.startedAt,
+      elapsed: now - state.startedAt
+    }));
+  }
+  /**
+   * Returns metadata for all available built-in presets.
+   *
+   * @returns Array of {@link PresetInfo} descriptors
+   */
+  listPresets() {
+    return getPresetInfo();
+  }
+  /**
+   * Disposes the engine, stopping all patterns and unsubscribing from client events.
+   *
+   * Subsequent calls to {@link play} will throw. Idempotent.
+   */
+  dispose() {
+    if (this.#disposed) {
+      return;
+    }
+    this.#disposed = true;
+    this.#unsubDisconnect();
+    this.#unsubDeviceRemoved();
+    this.#stopMatchingPatterns("manual");
+  }
+  /** Evaluates all tracks at the current time and schedules the next tick. */
+  #tick(state, device) {
+    if (state.stopped) {
+      return;
+    }
+    const elapsed = performance.now() - state.startedAt;
+    const cycleDuration = getCycleDuration(state.tracks);
+    const cycleElapsed = cycleDuration > 0 && elapsed >= cycleDuration ? cycleDuration : elapsed;
+    const onError = (s, err) => this.#handleOutputError(s, err);
+    for (const track of state.tracks) {
+      if (track.outputType === "HwPositionWithDuration") {
+        evaluateHwPositionTrack(state, track, cycleElapsed, device, onError);
+      } else {
+        evaluateScalarTrack(state, track, cycleElapsed, device, buildScalarCommand, onError);
+      }
+    }
+    if (cycleDuration > 0 && elapsed >= cycleDuration) {
+      if (state.remainingLoops === Number.POSITIVE_INFINITY) {
+        state.startedAt += cycleDuration;
+        state.lastSentKeyframeIndex.clear();
+      } else if (state.remainingLoops > 1) {
+        state.remainingLoops--;
+        state.startedAt += cycleDuration;
+        state.lastSentKeyframeIndex.clear();
+      } else {
+        this.#stopPatternInternal(state, "complete", true);
+        return;
+      }
+    }
+    const drift = performance.now() - state.expectedTickTime;
+    const nextDelay = Math.max(0, state.tickInterval - drift);
+    state.expectedTickTime = performance.now() + nextDelay;
+    state.timerId = setTimeout(() => this.#tick(state, device), nextDelay);
+  }
+  /** Builds a {@link PatternDescriptor} from the shorthand pattern argument and options. */
+  #buildDescriptor(pattern, options) {
+    if (typeof pattern === "string") {
+      return {
+        type: "preset",
+        preset: pattern,
+        intensity: options?.intensity,
+        speed: options?.speed,
+        loop: options?.loop
+      };
+    }
+    if (Array.isArray(pattern)) {
+      return {
+        type: "custom",
+        tracks: pattern,
+        intensity: options?.intensity,
+        loop: options?.loop
+      };
+    }
+    return pattern;
+  }
+  /** Stops the pattern on device or protocol errors; ignores transient failures. */
+  #handleOutputError(state, err) {
+    if (err instanceof DeviceError || err instanceof ProtocolError) {
+      this.#stopPatternInternal(state, "error");
+    }
+  }
+  /** Stops all patterns, optionally filtered by device index. */
+  #stopMatchingPatterns(reason, deviceIndex) {
+    const patterns = deviceIndex !== void 0 ? [...this.#patterns.values()].filter((s) => s.deviceIndex === deviceIndex) : [...this.#patterns.values()];
+    for (const state of patterns) {
+      this.#stopPatternInternal(state, reason);
+    }
+    return patterns.length;
+  }
+  /** Stops a pattern, clears its timers, sends zero-value stop commands, and fires callbacks. */
+  #stopPatternInternal(state, reason, complete = false) {
+    if (state.stopped) {
+      return;
+    }
+    state.stopped = true;
+    if (state.timerId !== null) {
+      clearTimeout(state.timerId);
+      state.timerId = null;
+    }
+    if (state.safetyTimerId !== null) {
+      clearTimeout(state.safetyTimerId);
+      state.safetyTimerId = null;
+    }
+    this.#patterns.delete(state.id);
+    const device = this.#client.getDevice(state.deviceIndex);
+    if (device) {
+      for (const track of state.tracks) {
+        if (track.outputType === "Position" || track.outputType === "HwPositionWithDuration") {
+          device.stop({ featureIndex: track.featureIndex }).catch(noop);
+        } else {
+          const command = buildScalarCommand(track, track.range[0]);
+          device.output({ featureIndex: track.featureIndex, command }).catch(noop);
+        }
+      }
+    }
+    if (complete) {
+      state.options.onComplete?.(state.id);
+    }
+    state.options.onStop?.(state.id, reason);
+  }
+};
+export {
+  ButtplugClient,
+  ButtplugError,
+  ClientMessageSchema,
+  ConnectionError,
+  DEFAULT_CLIENT_NAME,
+  DEFAULT_PING_INTERVAL,
+  DEFAULT_REQUEST_TIMEOUT,
+  Device,
+  DeviceError,
+  DeviceFeaturesSchema,
+  EASING_FUNCTIONS,
+  EASING_VALUES,
+  ErrorCode,
+  FeatureValueSchema,
+  HandshakeError,
+  HwPositionOutputDataSchema,
+  INPUT_TYPES,
+  INPUT_TYPE_VALUES,
+  InputCommandTypeSchema,
+  InputDataSchema,
+  InputFeatureSchema,
+  InputReadingSchema,
+  InputTypeSchema,
+  KeyframeSchema,
+  MAX_MESSAGE_ID,
+  OUTPUT_TYPES,
+  OUTPUT_TYPE_VALUES,
+  OutputCommandSchema,
+  OutputFeatureSchema,
+  OutputTypeSchema,
+  PRESETS,
+  PRESET_NAMES,
+  PROTOCOL_VERSION_MAJOR,
+  PROTOCOL_VERSION_MINOR,
+  PatternDescriptorSchema,
+  PatternEngine,
+  PingManager,
+  PositionValueSchema,
+  ProtocolError,
+  ReconnectDefaults,
+  ReconnectHandler,
+  RotateWithDirectionOutputDataSchema,
+  RotationValueSchema,
+  SensorValueSchema,
+  ServerInfoSchema,
+  ServerMessageSchema,
+  SignedScalarOutputDataSchema,
+  TimeoutError,
+  UnsignedScalarOutputDataSchema,
+  WebSocketTransport,
+  consoleLogger,
+  formatError,
+  getLogger,
+  getPresetInfo,
+  noopLogger,
+  runWithLogger
+};