@kelnishi/satmouse-client 0.9.4 → 0.9.6

package/README.md

@@ -0,0 +1,118 @@
+# @kelnishi/satmouse-client
+
+Client SDK for [SatMouse](https://kelnishi.github.io/SatMouse/) — stream 6DOF spatial input from SpaceMouse and other devices to web apps and PWAs.
+
+Three tree-shakeable modules:
+
+| Module | Import | Purpose |
+|---|---|---|
+| **core** | `@kelnishi/satmouse-client` | Connection, discovery, binary decode. Zero dependencies. |
+| **utils** | `@kelnishi/satmouse-client/utils` | InputManager, transforms, per-device config, action mapping, persistence |
+| **react** | `@kelnishi/satmouse-client/react` | Provider, hooks, headless components |
+
+## Quick Start
+
+```bash
+npm install @kelnishi/satmouse-client
+```
+
+### Vanilla
+
+```typescript
+import { SatMouseConnection } from "@kelnishi/satmouse-client";
+import { InputManager } from "@kelnishi/satmouse-client/utils";
+
+const connection = new SatMouseConnection();
+const manager = new InputManager();
+manager.addConnection(connection);
+
+manager.onSpatialData((data) => {
+  console.log(data.translation, data.rotation);
+});
+
+await connection.connect();
+```
+
+### React
+
+```tsx
+import { SatMouseProvider, useSpatialData } from "@kelnishi/satmouse-client/react";
+
+function App() {
+  return (
+    <SatMouseProvider>
+      <Scene />
+    </SatMouseProvider>
+  );
+}
+
+function Scene() {
+  const data = useSpatialData();
+  // data.translation.x/y/z, data.rotation.x/y/z
+}
+```
+
+## Per-Device Configuration
+
+```typescript
+const manager = new InputManager({
+  sensitivity: { translation: 0.001, rotation: 0.001 },
+  devices: {
+    "hid-054c-*": { sensitivity: { translation: 0.002 } },
+    "spacemouse-c635": { flip: { rz: false } },
+  },
+});
+
+// Query devices and their resolved config
+const devices = manager.getDevicesWithConfig();
+
+// Update per-device
+manager.updateDeviceConfig("spacemouse-c635", {
+  sensitivity: { rotation: 0.005 },
+});
+```
+
+## Action Mapping
+
+Remap input axes to named actions. Default passes through 1:1.
+
+```typescript
+import { InputManager, swapActions, DEFAULT_ACTION_MAP } from "@kelnishi/satmouse-client/utils";
+
+// Swap ty and tz
+const manager = new InputManager({
+  actionMap: swapActions(DEFAULT_ACTION_MAP, "ty", "tz"),
+});
+
+// Per-device remapping
+manager.updateDeviceConfig("hid-054c-*", {
+  actionMap: {
+    tx: { source: "tx" },
+    tz: { source: "ty", invert: true },
+    ry: { source: "rx", scale: 2.0 },
+  },
+});
+
+// Named action values
+manager.onActionValues((values) => {
+  scene.pan(values.tx, values.ty);
+  scene.zoom(values.tz);
+});
+```
+
+## Connection Options
+
+```typescript
+// Auto-discover via Thing Description
+new SatMouseConnection();
+
+// Direct URL
+new SatMouseConnection({ wsUrl: "ws://192.168.1.42:18945/spatial" });
+
+// Via satmouse:// URI
+new SatMouseConnection({ uri: "satmouse://connect?host=192.168.1.42" });
+```
+
+## License
+
+MIT — [GitHub](https://github.com/kelnishi/SatMouse)

package/dist/react/index.cjs

@@ -427,6 +427,57 @@ function launchSatMouse(options) {
   });
 }
 
+// src/utils/action-map.ts
+var DEFAULT_ACTION_MAP = {
+  tx: { source: "tx" },
+  ty: { source: "ty" },
+  tz: { source: "tz" },
+  rx: { source: "rx" },
+  ry: { source: "ry" },
+  rz: { source: "rz" }
+};
+function readAxis(data, axis) {
+  switch (axis) {
+    case "tx":
+      return data.translation.x;
+    case "ty":
+      return data.translation.y;
+    case "tz":
+      return data.translation.z;
+    case "rx":
+      return data.rotation.x;
+    case "ry":
+      return data.rotation.y;
+    case "rz":
+      return data.rotation.z;
+  }
+}
+function applyActionMap(data, map) {
+  const result = {};
+  for (const [action, binding] of Object.entries(map)) {
+    let value = readAxis(data, binding.source);
+    if (binding.invert) value = -value;
+    value *= binding.scale ?? 1;
+    result[action] = value;
+  }
+  return result;
+}
+function actionValuesToSpatialData(values, timestamp) {
+  return {
+    translation: {
+      x: values.tx ?? 0,
+      y: values.ty ?? 0,
+      z: values.tz ?? 0
+    },
+    rotation: {
+      x: values.rx ?? 0,
+      y: values.ry ?? 0,
+      z: values.rz ?? 0
+    },
+    timestamp
+  };
+}
+
 // src/utils/config.ts
 var DEFAULT_CONFIG = {
   sensitivity: { translation: 1e-3, rotation: 1e-3 },
@@ -436,6 +487,7 @@ var DEFAULT_CONFIG = {
   axisRemap: { tx: "x", ty: "y", tz: "z", rx: "x", ry: "y", rz: "z" },
   lockPosition: false,
   lockRotation: false,
+  actionMap: { ...DEFAULT_ACTION_MAP },
   devices: {}
 };
 function mergeConfig(base, partial) {
@@ -445,6 +497,7 @@ function mergeConfig(base, partial) {
     sensitivity: { ...base.sensitivity, ...partial.sensitivity },
     flip: { ...base.flip, ...partial.flip },
     axisRemap: { ...base.axisRemap, ...partial.axisRemap },
+    actionMap: partial.actionMap ? { ...base.actionMap, ...partial.actionMap } : { ...base.actionMap },
     devices: { ...base.devices }
   };
   if (partial.devices) {
@@ -484,6 +537,7 @@ function resolveDeviceConfig(config, deviceId) {
     deadZone: deviceOverride.deadZone ?? config.deadZone,
     dominant: deviceOverride.dominant ?? config.dominant,
     axisRemap: { ...config.axisRemap, ...deviceOverride.axisRemap },
+    actionMap: deviceOverride.actionMap ? { ...config.actionMap, ...deviceOverride.actionMap } : config.actionMap,
     lockPosition: deviceOverride.lockPosition ?? config.lockPosition,
     lockRotation: deviceOverride.lockRotation ?? config.lockRotation
   };
@@ -650,6 +704,7 @@ var InputManager = class extends TypedEmitter {
       deadZone: resolved.deadZone,
       dominant: resolved.dominant,
       axisRemap: resolved.axisRemap,
+      actionMap: resolved.actionMap,
       lockPosition: resolved.lockPosition,
       lockRotation: resolved.lockRotation
     };
@@ -679,11 +734,17 @@ var InputManager = class extends TypedEmitter {
     this.on("buttonEvent", callback);
     return () => this.off("buttonEvent", callback);
   }
+  /** Register a callback for action values. Returns unsubscribe function. */
+  onActionValues(callback) {
+    this.on("actionValues", callback);
+    return () => this.off("actionValues", callback);
+  }
   wireConnection(connection) {
     connection.on("spatialData", (raw) => {
       this.emit("rawSpatialData", raw);
-      const processed = this.processSpatialData(raw);
-      if (processed) this.emit("spatialData", processed);
+      const { spatial, actions } = this.processSpatialData(raw);
+      if (spatial) this.emit("spatialData", spatial);
+      if (actions) this.emit("actionValues", actions);
     });
     connection.on("buttonEvent", (event) => this.emit("buttonEvent", event));
     connection.on("stateChange", (state, proto) => this.emit("stateChange", state, proto));
@@ -707,7 +768,9 @@ var InputManager = class extends TypedEmitter {
     if (cfg.lockRotation) {
       data = { ...data, rotation: { x: 0, y: 0, z: 0 } };
     }
-    return data;
+    const actions = applyActionMap(data, cfg.actionMap);
+    const spatial = actionValuesToSpatialData(actions, data.timestamp);
+    return { spatial, actions };
   }
 };
 var SatMouseContext = react.createContext(null);