ps5-controller-webhid 0.1.0

package/lib/index.d.cts

@@ -0,0 +1,178 @@
+import { ChargeStatus, TriggerFeedbackConfig } from 'dualsense-ts';
+export { ChargeStatus, TriggerEffect, TriggerFeedbackConfig } from 'dualsense-ts';
+
+declare const DUALSENSE_BUTTONS: readonly [{
+    readonly key: "cross";
+    readonly label: "Cross";
+}, {
+    readonly key: "circle";
+    readonly label: "Circle";
+}, {
+    readonly key: "square";
+    readonly label: "Square";
+}, {
+    readonly key: "triangle";
+    readonly label: "Triangle";
+}, {
+    readonly key: "dpadUp";
+    readonly label: "D-pad up";
+}, {
+    readonly key: "dpadRight";
+    readonly label: "D-pad right";
+}, {
+    readonly key: "dpadDown";
+    readonly label: "D-pad down";
+}, {
+    readonly key: "dpadLeft";
+    readonly label: "D-pad left";
+}, {
+    readonly key: "l1";
+    readonly label: "L1";
+}, {
+    readonly key: "r1";
+    readonly label: "R1";
+}, {
+    readonly key: "l2Digital";
+    readonly label: "L2 digital";
+}, {
+    readonly key: "r2Digital";
+    readonly label: "R2 digital";
+}, {
+    readonly key: "l3";
+    readonly label: "L3 / left stick press";
+}, {
+    readonly key: "r3";
+    readonly label: "R3 / right stick press";
+}, {
+    readonly key: "create";
+    readonly label: "Create";
+}, {
+    readonly key: "options";
+    readonly label: "Options";
+}, {
+    readonly key: "touchpad";
+    readonly label: "Touchpad press";
+}, {
+    readonly key: "mute";
+    readonly label: "Mute";
+}, {
+    readonly key: "ps";
+    readonly label: "PS";
+}];
+type DualSenseButton = (typeof DUALSENSE_BUTTONS)[number]['key'];
+type DualSenseButtonState = Record<DualSenseButton, boolean>;
+type DualSenseSide = 'left' | 'right';
+type DualSenseTransport = 'Bluetooth' | 'USB' | 'Disconnected';
+interface Vec2 {
+    x: number;
+    y: number;
+}
+interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+interface TouchPoint extends Vec2 {
+    active: boolean;
+    id: number;
+}
+interface DualSenseSnapshot {
+    connected: boolean;
+    transport: DualSenseTransport;
+    limited: boolean;
+    identityReady: boolean;
+    productName: string;
+    serialNumber: string;
+    boardRevision: string;
+    firmware: string;
+    sticks: {
+        left: Vec2;
+        right: Vec2;
+    };
+    triggers: {
+        left: number;
+        right: number;
+    };
+    buttons: DualSenseButtonState;
+    motion: {
+        gyro: Vec3;
+        accelerometer: Vec3;
+        orientation: Vec3;
+        quaternion: readonly [number, number, number, number];
+        sensorTimestamp: number;
+    };
+    touchpad: {
+        primary: TouchPoint;
+        secondary: TouchPoint;
+    };
+    battery: {
+        level: number;
+        status: ChargeStatus;
+    };
+}
+interface DualSenseClientOptions {
+    pollRateHz?: number;
+    stickDeadzone?: number;
+    orientationBeta?: number;
+}
+interface DualSenseSupport {
+    webHID: boolean;
+    secureContext: boolean;
+    supported: boolean;
+}
+type SnapshotListener = (snapshot: DualSenseSnapshot) => void;
+type ErrorListener = (error: Error) => void;
+declare function createNeutralButtonState(): DualSenseButtonState;
+declare function createNeutralSnapshot(): DualSenseSnapshot;
+
+declare function getDualSenseSupport(): DualSenseSupport;
+/**
+ * Framework-independent DualSense WebHID client.
+ *
+ * PS5 Controller Tester uses this exact class for its hardware tests. Games
+ * can subscribe to snapshots or call `read()` from their own frame loop.
+ */
+declare class DualSenseClient {
+    readonly support: DualSenseSupport;
+    private controller;
+    private currentSnapshot;
+    private readonly snapshotListeners;
+    private readonly errorListeners;
+    private readonly frameInterval;
+    private frame;
+    private lastFrameTime;
+    private lastError;
+    private disposed;
+    private unsubscribeConnection;
+    constructor(options?: DualSenseClientOptions);
+    /** Latest cached state, updated at the configured polling rate. */
+    get current(): DualSenseSnapshot;
+    /** Request browser device permission. Must be called from a user gesture. */
+    connect(): Promise<void>;
+    /** Read fresh state synchronously. Useful inside a game frame loop. */
+    read(): DualSenseSnapshot;
+    /** Subscribe to normalized snapshots. The current snapshot fires immediately. */
+    subscribe(listener: SnapshotListener, emitCurrent?: boolean): () => void;
+    /** Subscribe to initialization, permission, and HID transport errors. */
+    onError(listener: ErrorListener): () => void;
+    /** Set independent left/right haptic intensity from 0 to 1. */
+    setRumble(left: number, right: number): void;
+    /** Play a bounded haptic pulse and always stop afterward. */
+    pulseRumble(left: number, right: number, durationMs: number): Promise<void>;
+    /** Apply one of dualsense-ts's typed adaptive-trigger effects. */
+    setTriggerFeedback(side: DualSenseSide, config: TriggerFeedbackConfig): void;
+    /** Return both adaptive triggers to their normal linear feel. */
+    resetTriggerFeedback(): void;
+    /** Stop haptics and clear adaptive-trigger effects. */
+    resetOutputs(): void;
+    /** Set the controller's current fused orientation as the session neutral. */
+    resetOrientation(): void;
+    /** Release listeners, animation frames, HID resources, and outputs. */
+    dispose(): void;
+    private readonly handlePageExit;
+    private readonly poll;
+    private publishSnapshot;
+    private publishError;
+}
+
+export { DUALSENSE_BUTTONS, type DualSenseButton, type DualSenseButtonState, DualSenseClient, type DualSenseClientOptions, type DualSenseSide, type DualSenseSnapshot, type DualSenseSupport, type DualSenseTransport, type ErrorListener, DualSenseClient as PS5Controller, type DualSenseButton as PS5ControllerButton, type DualSenseClientOptions as PS5ControllerOptions, type DualSenseSnapshot as PS5ControllerState, type SnapshotListener, type TouchPoint, type Vec2, type Vec3, createNeutralButtonState, createNeutralSnapshot, getDualSenseSupport };

package/lib/index.d.ts

@@ -0,0 +1,178 @@
+import { ChargeStatus, TriggerFeedbackConfig } from 'dualsense-ts';
+export { ChargeStatus, TriggerEffect, TriggerFeedbackConfig } from 'dualsense-ts';
+
+declare const DUALSENSE_BUTTONS: readonly [{
+    readonly key: "cross";
+    readonly label: "Cross";
+}, {
+    readonly key: "circle";
+    readonly label: "Circle";
+}, {
+    readonly key: "square";
+    readonly label: "Square";
+}, {
+    readonly key: "triangle";
+    readonly label: "Triangle";
+}, {
+    readonly key: "dpadUp";
+    readonly label: "D-pad up";
+}, {
+    readonly key: "dpadRight";
+    readonly label: "D-pad right";
+}, {
+    readonly key: "dpadDown";
+    readonly label: "D-pad down";
+}, {
+    readonly key: "dpadLeft";
+    readonly label: "D-pad left";
+}, {
+    readonly key: "l1";
+    readonly label: "L1";
+}, {
+    readonly key: "r1";
+    readonly label: "R1";
+}, {
+    readonly key: "l2Digital";
+    readonly label: "L2 digital";
+}, {
+    readonly key: "r2Digital";
+    readonly label: "R2 digital";
+}, {
+    readonly key: "l3";
+    readonly label: "L3 / left stick press";
+}, {
+    readonly key: "r3";
+    readonly label: "R3 / right stick press";
+}, {
+    readonly key: "create";
+    readonly label: "Create";
+}, {
+    readonly key: "options";
+    readonly label: "Options";
+}, {
+    readonly key: "touchpad";
+    readonly label: "Touchpad press";
+}, {
+    readonly key: "mute";
+    readonly label: "Mute";
+}, {
+    readonly key: "ps";
+    readonly label: "PS";
+}];
+type DualSenseButton = (typeof DUALSENSE_BUTTONS)[number]['key'];
+type DualSenseButtonState = Record<DualSenseButton, boolean>;
+type DualSenseSide = 'left' | 'right';
+type DualSenseTransport = 'Bluetooth' | 'USB' | 'Disconnected';
+interface Vec2 {
+    x: number;
+    y: number;
+}
+interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+interface TouchPoint extends Vec2 {
+    active: boolean;
+    id: number;
+}
+interface DualSenseSnapshot {
+    connected: boolean;
+    transport: DualSenseTransport;
+    limited: boolean;
+    identityReady: boolean;
+    productName: string;
+    serialNumber: string;
+    boardRevision: string;
+    firmware: string;
+    sticks: {
+        left: Vec2;
+        right: Vec2;
+    };
+    triggers: {
+        left: number;
+        right: number;
+    };
+    buttons: DualSenseButtonState;
+    motion: {
+        gyro: Vec3;
+        accelerometer: Vec3;
+        orientation: Vec3;
+        quaternion: readonly [number, number, number, number];
+        sensorTimestamp: number;
+    };
+    touchpad: {
+        primary: TouchPoint;
+        secondary: TouchPoint;
+    };
+    battery: {
+        level: number;
+        status: ChargeStatus;
+    };
+}
+interface DualSenseClientOptions {
+    pollRateHz?: number;
+    stickDeadzone?: number;
+    orientationBeta?: number;
+}
+interface DualSenseSupport {
+    webHID: boolean;
+    secureContext: boolean;
+    supported: boolean;
+}
+type SnapshotListener = (snapshot: DualSenseSnapshot) => void;
+type ErrorListener = (error: Error) => void;
+declare function createNeutralButtonState(): DualSenseButtonState;
+declare function createNeutralSnapshot(): DualSenseSnapshot;
+
+declare function getDualSenseSupport(): DualSenseSupport;
+/**
+ * Framework-independent DualSense WebHID client.
+ *
+ * PS5 Controller Tester uses this exact class for its hardware tests. Games
+ * can subscribe to snapshots or call `read()` from their own frame loop.
+ */
+declare class DualSenseClient {
+    readonly support: DualSenseSupport;
+    private controller;
+    private currentSnapshot;
+    private readonly snapshotListeners;
+    private readonly errorListeners;
+    private readonly frameInterval;
+    private frame;
+    private lastFrameTime;
+    private lastError;
+    private disposed;
+    private unsubscribeConnection;
+    constructor(options?: DualSenseClientOptions);
+    /** Latest cached state, updated at the configured polling rate. */
+    get current(): DualSenseSnapshot;
+    /** Request browser device permission. Must be called from a user gesture. */
+    connect(): Promise<void>;
+    /** Read fresh state synchronously. Useful inside a game frame loop. */
+    read(): DualSenseSnapshot;
+    /** Subscribe to normalized snapshots. The current snapshot fires immediately. */
+    subscribe(listener: SnapshotListener, emitCurrent?: boolean): () => void;
+    /** Subscribe to initialization, permission, and HID transport errors. */
+    onError(listener: ErrorListener): () => void;
+    /** Set independent left/right haptic intensity from 0 to 1. */
+    setRumble(left: number, right: number): void;
+    /** Play a bounded haptic pulse and always stop afterward. */
+    pulseRumble(left: number, right: number, durationMs: number): Promise<void>;
+    /** Apply one of dualsense-ts's typed adaptive-trigger effects. */
+    setTriggerFeedback(side: DualSenseSide, config: TriggerFeedbackConfig): void;
+    /** Return both adaptive triggers to their normal linear feel. */
+    resetTriggerFeedback(): void;
+    /** Stop haptics and clear adaptive-trigger effects. */
+    resetOutputs(): void;
+    /** Set the controller's current fused orientation as the session neutral. */
+    resetOrientation(): void;
+    /** Release listeners, animation frames, HID resources, and outputs. */
+    dispose(): void;
+    private readonly handlePageExit;
+    private readonly poll;
+    private publishSnapshot;
+    private publishError;
+}
+
+export { DUALSENSE_BUTTONS, type DualSenseButton, type DualSenseButtonState, DualSenseClient, type DualSenseClientOptions, type DualSenseSide, type DualSenseSnapshot, type DualSenseSupport, type DualSenseTransport, type ErrorListener, DualSenseClient as PS5Controller, type DualSenseButton as PS5ControllerButton, type DualSenseClientOptions as PS5ControllerOptions, type DualSenseSnapshot as PS5ControllerState, type SnapshotListener, type TouchPoint, type Vec2, type Vec3, createNeutralButtonState, createNeutralSnapshot, getDualSenseSupport };

package/lib/index.js

@@ -0,0 +1,323 @@
+import { ChargeStatus, Dualsense, WebHIDProvider } from 'dualsense-ts';
+export { ChargeStatus, TriggerEffect } from 'dualsense-ts';
+
+// src/dualsense/index.ts
+var DUALSENSE_BUTTONS = [
+  { key: "cross", label: "Cross" },
+  { key: "circle", label: "Circle" },
+  { key: "square", label: "Square" },
+  { key: "triangle", label: "Triangle" },
+  { key: "dpadUp", label: "D-pad up" },
+  { key: "dpadRight", label: "D-pad right" },
+  { key: "dpadDown", label: "D-pad down" },
+  { key: "dpadLeft", label: "D-pad left" },
+  { key: "l1", label: "L1" },
+  { key: "r1", label: "R1" },
+  { key: "l2Digital", label: "L2 digital" },
+  { key: "r2Digital", label: "R2 digital" },
+  { key: "l3", label: "L3 / left stick press" },
+  { key: "r3", label: "R3 / right stick press" },
+  { key: "create", label: "Create" },
+  { key: "options", label: "Options" },
+  { key: "touchpad", label: "Touchpad press" },
+  { key: "mute", label: "Mute" },
+  { key: "ps", label: "PS" }
+];
+function createNeutralButtonState() {
+  return Object.fromEntries(
+    DUALSENSE_BUTTONS.map(({ key }) => [key, false])
+  );
+}
+function createNeutralSnapshot() {
+  return {
+    connected: false,
+    transport: "Disconnected",
+    limited: false,
+    identityReady: false,
+    productName: "DualSense",
+    serialNumber: "",
+    boardRevision: "",
+    firmware: "",
+    sticks: {
+      left: { x: 0, y: 0 },
+      right: { x: 0, y: 0 }
+    },
+    triggers: {
+      left: 0,
+      right: 0
+    },
+    buttons: createNeutralButtonState(),
+    motion: {
+      gyro: { x: 0, y: 0, z: 0 },
+      accelerometer: { x: 0, y: 0, z: 0 },
+      orientation: { x: 0, y: 0, z: 0 },
+      quaternion: [1, 0, 0, 0],
+      sensorTimestamp: 0
+    },
+    touchpad: {
+      primary: { active: false, id: 0, x: 0, y: 0 },
+      secondary: { active: false, id: 0, x: 0, y: 0 }
+    },
+    battery: {
+      level: 0,
+      status: ChargeStatus.Discharging
+    }
+  };
+}
+
+// src/dualsense/DualSenseClient.ts
+var degrees = (radians) => radians * 180 / Math.PI;
+var clamp = (value) => Math.min(1, Math.max(0, value));
+var wait = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+function getDualSenseSupport() {
+  const webHID = typeof navigator !== "undefined" && "hid" in navigator;
+  const secureContext = typeof window !== "undefined" && window.isSecureContext;
+  return {
+    webHID,
+    secureContext,
+    supported: webHID && secureContext
+  };
+}
+function readController(controller) {
+  const connected = controller.connection.active;
+  const firmware = controller.firmwareInfo.mainFirmwareVersion;
+  const providerDevice = controller.hid.provider.device;
+  const productName = providerDevice && "productName" in providerDevice ? providerDevice.productName : "DualSense";
+  const quaternion = controller.orientation.quaternion;
+  return {
+    connected,
+    transport: connected ? controller.wireless ? "Bluetooth" : "USB" : "Disconnected",
+    limited: controller.hid.provider.limited ?? false,
+    identityReady: controller.hid.ready,
+    productName,
+    serialNumber: controller.factoryInfo.serialNumber,
+    boardRevision: controller.factoryInfo.boardRevision,
+    firmware: firmware.major || firmware.minor || firmware.patch ? `${firmware.major}.${firmware.minor}.${firmware.patch}` : "",
+    sticks: {
+      left: {
+        x: controller.left.analog.x.state,
+        y: controller.left.analog.y.state
+      },
+      right: {
+        x: controller.right.analog.x.state,
+        y: controller.right.analog.y.state
+      }
+    },
+    triggers: {
+      left: controller.left.trigger.pressure,
+      right: controller.right.trigger.pressure
+    },
+    buttons: {
+      cross: controller.cross.state,
+      circle: controller.circle.state,
+      square: controller.square.state,
+      triangle: controller.triangle.state,
+      dpadUp: controller.dpad.up.state,
+      dpadRight: controller.dpad.right.state,
+      dpadDown: controller.dpad.down.state,
+      dpadLeft: controller.dpad.left.state,
+      l1: controller.left.bumper.state,
+      r1: controller.right.bumper.state,
+      l2Digital: controller.left.trigger.button.state,
+      r2Digital: controller.right.trigger.button.state,
+      l3: controller.left.analog.button.state,
+      r3: controller.right.analog.button.state,
+      create: controller.create.state,
+      options: controller.options.state,
+      touchpad: controller.touchpad.button.state,
+      mute: controller.mute.state,
+      ps: controller.ps.state
+    },
+    motion: {
+      gyro: {
+        x: controller.gyroscope.x.state,
+        y: controller.gyroscope.y.state,
+        z: controller.gyroscope.z.state
+      },
+      accelerometer: {
+        x: controller.accelerometer.x.state,
+        y: controller.accelerometer.y.state,
+        z: controller.accelerometer.z.state
+      },
+      orientation: {
+        x: degrees(controller.orientation.pitch),
+        y: degrees(controller.orientation.yaw),
+        z: degrees(controller.orientation.roll)
+      },
+      quaternion: [
+        quaternion[0],
+        quaternion[1],
+        quaternion[2],
+        quaternion[3]
+      ],
+      sensorTimestamp: controller.sensorTimestamp
+    },
+    touchpad: {
+      primary: {
+        active: controller.touchpad.left.contact.state,
+        id: controller.touchpad.left.tracker.state,
+        x: controller.touchpad.left.x.state,
+        y: controller.touchpad.left.y.state
+      },
+      secondary: {
+        active: controller.touchpad.right.contact.state,
+        id: controller.touchpad.right.tracker.state,
+        x: controller.touchpad.right.x.state,
+        y: controller.touchpad.right.y.state
+      }
+    },
+    battery: {
+      level: controller.battery.level.state,
+      status: controller.battery.status.state
+    }
+  };
+}
+var DualSenseClient = class {
+  support = getDualSenseSupport();
+  controller = null;
+  currentSnapshot = createNeutralSnapshot();
+  snapshotListeners = /* @__PURE__ */ new Set();
+  errorListeners = /* @__PURE__ */ new Set();
+  frameInterval;
+  frame = 0;
+  lastFrameTime = 0;
+  lastError = null;
+  disposed = false;
+  unsubscribeConnection = null;
+  constructor(options = {}) {
+    const pollRateHz = Math.min(240, Math.max(1, options.pollRateHz ?? 60));
+    this.frameInterval = 1e3 / pollRateHz;
+    if (!this.support.supported) return;
+    try {
+      this.controller = new Dualsense({
+        left: { analog: { deadzone: options.stickDeadzone ?? 0.04 } },
+        right: { analog: { deadzone: options.stickDeadzone ?? 0.04 } },
+        orientation: { beta: options.orientationBeta ?? 0.08 }
+      });
+      this.controller.hid.on("error", (error) => this.publishError(error));
+      this.unsubscribeConnection = this.controller.hid.onConnectionChange(
+        () => this.publishSnapshot()
+      );
+      window.addEventListener("pagehide", this.handlePageExit);
+      this.frame = window.requestAnimationFrame(this.poll);
+    } catch (caught) {
+      this.publishError(
+        caught instanceof Error ? caught : new Error("Could not initialize the DualSense WebHID client.")
+      );
+    }
+  }
+  /** Latest cached state, updated at the configured polling rate. */
+  get current() {
+    return this.currentSnapshot;
+  }
+  /** Request browser device permission. Must be called from a user gesture. */
+  async connect() {
+    if (!this.support.webHID) {
+      throw new Error(
+        "WebHID is unavailable. Use desktop Chrome, Edge, or Opera."
+      );
+    }
+    if (!this.support.secureContext) {
+      throw new Error("WebHID requires localhost or HTTPS.");
+    }
+    if (!this.controller) {
+      throw new Error("The DualSense client could not be initialized.");
+    }
+    if (!(this.controller.hid.provider instanceof WebHIDProvider)) {
+      throw new Error("The active controller provider is not WebHID.");
+    }
+    await this.controller.hid.provider.getRequest()();
+  }
+  /** Read fresh state synchronously. Useful inside a game frame loop. */
+  read() {
+    if (this.controller) {
+      this.currentSnapshot = readController(this.controller);
+    }
+    return this.currentSnapshot;
+  }
+  /** Subscribe to normalized snapshots. The current snapshot fires immediately. */
+  subscribe(listener, emitCurrent = true) {
+    this.snapshotListeners.add(listener);
+    if (emitCurrent) listener(this.currentSnapshot);
+    return () => this.snapshotListeners.delete(listener);
+  }
+  /** Subscribe to initialization, permission, and HID transport errors. */
+  onError(listener) {
+    this.errorListeners.add(listener);
+    if (this.lastError) listener(this.lastError);
+    return () => this.errorListeners.delete(listener);
+  }
+  /** Set independent left/right haptic intensity from 0 to 1. */
+  setRumble(left, right) {
+    if (!this.controller?.connection.active) return;
+    this.controller.left.rumble(clamp(left));
+    this.controller.right.rumble(clamp(right));
+  }
+  /** Play a bounded haptic pulse and always stop afterward. */
+  async pulseRumble(left, right, durationMs) {
+    this.setRumble(left, right);
+    try {
+      await wait(Math.max(0, durationMs));
+    } finally {
+      this.setRumble(0, 0);
+    }
+  }
+  /** Apply one of dualsense-ts's typed adaptive-trigger effects. */
+  setTriggerFeedback(side, config) {
+    if (!this.controller?.connection.active) return;
+    this.controller[side].trigger.feedback.set(config);
+  }
+  /** Return both adaptive triggers to their normal linear feel. */
+  resetTriggerFeedback() {
+    this.controller?.resetTriggerFeedback();
+  }
+  /** Stop haptics and clear adaptive-trigger effects. */
+  resetOutputs() {
+    if (!this.controller) return;
+    this.controller.rumble(0);
+    this.controller.resetTriggerFeedback();
+  }
+  /** Set the controller's current fused orientation as the session neutral. */
+  resetOrientation() {
+    this.controller?.orientation.reset();
+  }
+  /** Release listeners, animation frames, HID resources, and outputs. */
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    if (typeof window !== "undefined") {
+      window.removeEventListener("pagehide", this.handlePageExit);
+      window.cancelAnimationFrame(this.frame);
+    }
+    this.unsubscribeConnection?.();
+    this.unsubscribeConnection = null;
+    this.resetOutputs();
+    this.controller?.dispose();
+    this.controller = null;
+    this.snapshotListeners.clear();
+    this.errorListeners.clear();
+  }
+  handlePageExit = () => {
+    this.resetOutputs();
+  };
+  poll = (time) => {
+    if (this.disposed) return;
+    if (time - this.lastFrameTime >= this.frameInterval) {
+      this.publishSnapshot();
+      this.lastFrameTime = time;
+    }
+    this.frame = window.requestAnimationFrame(this.poll);
+  };
+  publishSnapshot() {
+    const snapshot = this.read();
+    for (const listener of this.snapshotListeners) listener(snapshot);
+  }
+  publishError(error) {
+    this.lastError = error;
+    for (const listener of this.errorListeners) listener(error);
+  }
+};
+
+export { DUALSENSE_BUTTONS, DualSenseClient, DualSenseClient as PS5Controller, createNeutralButtonState, createNeutralSnapshot, getDualSenseSupport };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map