@kelnishi/satmouse-client 0.10.1 → 0.10.2

package/dist/react/index.d.cts

@@ -0,0 +1,253 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/** Minimal typed event emitter — no node:events dependency for browser compatibility */
+declare class TypedEmitter<Events> {
+    private listeners;
+    on<K extends string & keyof Events>(event: K, listener: Events[K] & Function): this;
+    off<K extends string & keyof Events>(event: K, listener: Events[K] & Function): this;
+    protected emit<K extends string & keyof Events>(event: K, ...args: Events[K] extends (...a: infer A) => void ? A : never): void;
+    removeAllListeners(): void;
+}
+
+interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/** 6DOF spatial input frame — matches spatial-data.schema.json */
+interface SpatialData {
+    translation: Vec3;
+    rotation: Vec3;
+    timestamp: number;
+    /** Source device ID (e.g., "cnx-c635", "hid-054c-5c4") */
+    deviceId?: string;
+}
+/** Button press/release event — matches button-event.schema.json */
+interface ButtonEvent {
+    button: number;
+    pressed: boolean;
+    timestamp: number;
+}
+/** Device metadata from the bridge */
+interface DeviceInfo$1 {
+    id: string;
+    name: string;
+    model?: string;
+    vendor?: string;
+    vendorId?: number;
+    productId?: number;
+    connectionType?: "usb" | "wireless" | "bluetooth" | "unknown";
+    connected?: boolean;
+    /** Axes this device provides (e.g., ["tx","ty","tz","rx","ry","rz"] or ["tx","ty","rx","ry","tz+","rz+"]) */
+    axes?: string[];
+    /** Human-readable labels for axes (same order as axes array) */
+    axisLabels?: string[];
+    /** Number of buttons this device provides */
+    buttonCount?: number;
+}
+type ConnectionState = "disconnected" | "connecting" | "connected" | "failed";
+type TransportProtocol = "webtransport" | "websocket" | "none";
+interface SatMouseEvents {
+    spatialData: (data: SpatialData) => void;
+    buttonEvent: (data: ButtonEvent) => void;
+    stateChange: (state: ConnectionState, protocol: TransportProtocol) => void;
+    deviceStatus: (event: "connected" | "disconnected", device: DeviceInfo$1) => void;
+    error: (error: Error) => void;
+}
+interface ConnectOptions {
+    /**
+     * SatMouse URI: satmouse://connect?host=<ip>&wsPort=<port>&wtPort=<port>
+     * When provided, host/ports are extracted and used for discovery + transport.
+     * All params are optional — defaults to localhost:4444/4443.
+     */
+    uri?: string;
+    /** URL to td.json. Defaults to /td.json relative to window.location */
+    tdUrl?: string;
+    /** Direct WebSocket URL (skips discovery) */
+    wsUrl?: string;
+    /** Direct WebTransport URL (skips discovery) */
+    wtUrl?: string;
+    /** Certificate hash for self-signed WebTransport certs (base64) */
+    certHash?: string;
+    /** Preferred transport order. Default: ["webtransport", "websocket"] */
+    transports?: TransportProtocol[];
+    /** Auto-reconnect delay in ms. 0 to disable. Default: 2000 */
+    reconnectDelay?: number;
+    /** Max reconnect attempts before giving up. Default: 3 */
+    maxRetries?: number;
+    /** WebSocket subprotocol. Default: "satmouse-json" */
+    wsSubprotocol?: "satmouse-json" | "satmouse-binary";
+}
+
+/**
+ * Core connection to a SatMouse bridge.
+ *
+ * Handles discovery (via WoT Thing Description), transport negotiation
+ * (WebTransport with WebSocket fallback), event dispatch, and auto-reconnect.
+ */
+declare class SatMouseConnection extends TypedEmitter<SatMouseEvents> {
+    private options;
+    private transport;
+    private reconnectTimer;
+    private intentionalClose;
+    private deviceInfoUrl;
+    private retryCount;
+    private _state;
+    private _protocol;
+    get state(): ConnectionState;
+    get protocol(): TransportProtocol;
+    constructor(options?: ConnectOptions);
+    connect(): Promise<void>;
+    /** Reset retry count and reconnect. Use after "failed" state. */
+    retry(): void;
+    disconnect(): void;
+    fetchDeviceInfo(): Promise<DeviceInfo$1[]>;
+    private tryTransport;
+    private setState;
+    private scheduleReconnect;
+    private clearReconnect;
+}
+
+/** Axis identifier — full or half */
+type InputAxis = "tx" | "ty" | "tz" | "rx" | "ry" | "rz" | "tx+" | "ty+" | "tz+" | "rx+" | "ry+" | "rz+" | "tx-" | "ty-" | "tz-" | "rx-" | "ry-" | "rz-";
+/** A single axis route — reads from source, writes to target */
+interface AxisRoute {
+    source: InputAxis;
+    target: InputAxis;
+    /** Negate the value (default: false) */
+    flip?: boolean;
+}
+
+/** Per-device configuration */
+interface DeviceConfig {
+    /** Axis routing — each entry maps a device input to an output with optional flip */
+    routes?: AxisRoute[];
+    /** Scale multiplier applied to all axes (default: 1) */
+    scale?: number;
+    /** Dead zone threshold (0-1). Values below this are zeroed. */
+    deadZone?: number;
+    /** Only pass the strongest axis, zero all others */
+    dominant?: boolean;
+}
+/** Global configuration */
+interface InputConfig {
+    /** Default axis routes (used when device has no override) */
+    routes: AxisRoute[];
+    /** Default scale */
+    scale: number;
+    /** Dead zone threshold */
+    deadZone: number;
+    /** Dominant axis mode */
+    dominant: boolean;
+    /** Lock translation to zero */
+    lockPosition: boolean;
+    /** Lock rotation to zero */
+    lockRotation: boolean;
+    /** Per-device overrides keyed by device ID or pattern (e.g., "cnx-*") */
+    devices: Record<string, DeviceConfig>;
+}
+
+interface StorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+
+interface InputManagerEvents {
+    spatialData: (data: SpatialData) => void;
+    rawSpatialData: (data: SpatialData) => void;
+    buttonEvent: (data: ButtonEvent) => void;
+    stateChange: (state: ConnectionState, protocol: TransportProtocol) => void;
+    deviceStatus: (event: "connected" | "disconnected", device: DeviceInfo$1) => void;
+    configChange: (config: InputConfig) => void;
+}
+interface DeviceWithConfig {
+    device: DeviceInfo$1;
+    config: DeviceConfig;
+}
+declare class InputManager extends TypedEmitter<InputManagerEvents> {
+    private connections;
+    private storage?;
+    private knownDevices;
+    private deviceAccumulators;
+    private accDirty;
+    private flushTimer;
+    private _config;
+    get config(): InputConfig;
+    constructor(config?: Partial<InputConfig>, storage?: StorageAdapter);
+    addConnection(connection: SatMouseConnection): void;
+    removeConnection(connection: SatMouseConnection): void;
+    connect(): Promise<void>;
+    disconnect(): void;
+    fetchDeviceInfo(): Promise<DeviceInfo$1[]>;
+    getDevicesWithConfig(): DeviceWithConfig[];
+    getDeviceConfig(deviceId: string): DeviceConfig;
+    updateConfig(partial: Partial<InputConfig>, persist?: boolean): void;
+    updateDeviceConfig(deviceId: string, partial: DeviceConfig, persist?: boolean): void;
+    resetDeviceConfig(deviceId: string, persist?: boolean): void;
+    resetAllConfig(): void;
+    onSpatialData(callback: (data: SpatialData) => void): () => void;
+    onButtonEvent(callback: (data: ButtonEvent) => void): () => void;
+    private wireConnection;
+    private flushAccumulator;
+    /** Per-device: deadZone → dominant → routes (flip + scale + remap in one pass) */
+    private processPerDevice;
+    /** Get the effective routes for a device: device config override > device axes metadata > global default */
+    private resolveRoutes;
+}
+
+interface SatMouseContextValue {
+    manager: InputManager;
+    state: ConnectionState;
+    protocol: TransportProtocol;
+    config: InputConfig;
+    updateConfig: (partial: Partial<InputConfig>) => void;
+}
+declare const SatMouseContext: react.Context<SatMouseContextValue | null>;
+interface SatMouseProviderProps {
+    connectOptions?: ConnectOptions;
+    config?: Partial<InputConfig>;
+    autoConnect?: boolean;
+    children: ReactNode;
+}
+declare function SatMouseProvider({ connectOptions, config: configOverrides, autoConnect, children, }: SatMouseProviderProps): react_jsx_runtime.JSX.Element;
+
+/** Access the SatMouse context. Throws if used outside SatMouseProvider. */
+declare function useSatMouse(): SatMouseContextValue;
+/**
+ * Subscribe to processed spatial data.
+ * Batches updates to requestAnimationFrame to avoid re-rendering at device rate.
+ */
+declare function useSpatialData(): SpatialData | null;
+/**
+ * Subscribe to raw (pre-transform) spatial data.
+ * Batches updates to requestAnimationFrame.
+ */
+declare function useRawSpatialData(): SpatialData | null;
+/** Subscribe to button events via callback. Does not trigger re-renders. */
+declare function useButtonEvent(callback: (event: ButtonEvent) => void): void;
+
+interface ConnectionStatusProps {
+    className?: string;
+}
+declare function ConnectionStatus({ className }: ConnectionStatusProps): react_jsx_runtime.JSX.Element;
+
+interface DeviceInfoProps {
+    className?: string;
+    /** Timeout in ms before showing "no device". Default: 5000 */
+    timeout?: number;
+}
+declare function DeviceInfo({ className, timeout }: DeviceInfoProps): react_jsx_runtime.JSX.Element;
+
+interface SettingsPanelProps {
+    className?: string;
+}
+declare function SettingsPanel({ className }: SettingsPanelProps): react_jsx_runtime.JSX.Element;
+
+interface DebugPanelProps {
+    className?: string;
+}
+declare function DebugPanel({ className }: DebugPanelProps): react_jsx_runtime.JSX.Element;
+
+export { ConnectionStatus, type ConnectionStatusProps, DebugPanel, type DebugPanelProps, DeviceInfo, type DeviceInfoProps, SatMouseContext, type SatMouseContextValue, SatMouseProvider, type SatMouseProviderProps, SettingsPanel, type SettingsPanelProps, useButtonEvent, useRawSpatialData, useSatMouse, useSpatialData };

package/dist/react/index.d.ts

@@ -0,0 +1,253 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/** Minimal typed event emitter — no node:events dependency for browser compatibility */
+declare class TypedEmitter<Events> {
+    private listeners;
+    on<K extends string & keyof Events>(event: K, listener: Events[K] & Function): this;
+    off<K extends string & keyof Events>(event: K, listener: Events[K] & Function): this;
+    protected emit<K extends string & keyof Events>(event: K, ...args: Events[K] extends (...a: infer A) => void ? A : never): void;
+    removeAllListeners(): void;
+}
+
+interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/** 6DOF spatial input frame — matches spatial-data.schema.json */
+interface SpatialData {
+    translation: Vec3;
+    rotation: Vec3;
+    timestamp: number;
+    /** Source device ID (e.g., "cnx-c635", "hid-054c-5c4") */
+    deviceId?: string;
+}
+/** Button press/release event — matches button-event.schema.json */
+interface ButtonEvent {
+    button: number;
+    pressed: boolean;
+    timestamp: number;
+}
+/** Device metadata from the bridge */
+interface DeviceInfo$1 {
+    id: string;
+    name: string;
+    model?: string;
+    vendor?: string;
+    vendorId?: number;
+    productId?: number;
+    connectionType?: "usb" | "wireless" | "bluetooth" | "unknown";
+    connected?: boolean;
+    /** Axes this device provides (e.g., ["tx","ty","tz","rx","ry","rz"] or ["tx","ty","rx","ry","tz+","rz+"]) */
+    axes?: string[];
+    /** Human-readable labels for axes (same order as axes array) */
+    axisLabels?: string[];
+    /** Number of buttons this device provides */
+    buttonCount?: number;
+}
+type ConnectionState = "disconnected" | "connecting" | "connected" | "failed";
+type TransportProtocol = "webtransport" | "websocket" | "none";
+interface SatMouseEvents {
+    spatialData: (data: SpatialData) => void;
+    buttonEvent: (data: ButtonEvent) => void;
+    stateChange: (state: ConnectionState, protocol: TransportProtocol) => void;
+    deviceStatus: (event: "connected" | "disconnected", device: DeviceInfo$1) => void;
+    error: (error: Error) => void;
+}
+interface ConnectOptions {
+    /**
+     * SatMouse URI: satmouse://connect?host=<ip>&wsPort=<port>&wtPort=<port>
+     * When provided, host/ports are extracted and used for discovery + transport.
+     * All params are optional — defaults to localhost:4444/4443.
+     */
+    uri?: string;
+    /** URL to td.json. Defaults to /td.json relative to window.location */
+    tdUrl?: string;
+    /** Direct WebSocket URL (skips discovery) */
+    wsUrl?: string;
+    /** Direct WebTransport URL (skips discovery) */
+    wtUrl?: string;
+    /** Certificate hash for self-signed WebTransport certs (base64) */
+    certHash?: string;
+    /** Preferred transport order. Default: ["webtransport", "websocket"] */
+    transports?: TransportProtocol[];
+    /** Auto-reconnect delay in ms. 0 to disable. Default: 2000 */
+    reconnectDelay?: number;
+    /** Max reconnect attempts before giving up. Default: 3 */
+    maxRetries?: number;
+    /** WebSocket subprotocol. Default: "satmouse-json" */
+    wsSubprotocol?: "satmouse-json" | "satmouse-binary";
+}
+
+/**
+ * Core connection to a SatMouse bridge.
+ *
+ * Handles discovery (via WoT Thing Description), transport negotiation
+ * (WebTransport with WebSocket fallback), event dispatch, and auto-reconnect.
+ */
+declare class SatMouseConnection extends TypedEmitter<SatMouseEvents> {
+    private options;
+    private transport;
+    private reconnectTimer;
+    private intentionalClose;
+    private deviceInfoUrl;
+    private retryCount;
+    private _state;
+    private _protocol;
+    get state(): ConnectionState;
+    get protocol(): TransportProtocol;
+    constructor(options?: ConnectOptions);
+    connect(): Promise<void>;
+    /** Reset retry count and reconnect. Use after "failed" state. */
+    retry(): void;
+    disconnect(): void;
+    fetchDeviceInfo(): Promise<DeviceInfo$1[]>;
+    private tryTransport;
+    private setState;
+    private scheduleReconnect;
+    private clearReconnect;
+}
+
+/** Axis identifier — full or half */
+type InputAxis = "tx" | "ty" | "tz" | "rx" | "ry" | "rz" | "tx+" | "ty+" | "tz+" | "rx+" | "ry+" | "rz+" | "tx-" | "ty-" | "tz-" | "rx-" | "ry-" | "rz-";
+/** A single axis route — reads from source, writes to target */
+interface AxisRoute {
+    source: InputAxis;
+    target: InputAxis;
+    /** Negate the value (default: false) */
+    flip?: boolean;
+}
+
+/** Per-device configuration */
+interface DeviceConfig {
+    /** Axis routing — each entry maps a device input to an output with optional flip */
+    routes?: AxisRoute[];
+    /** Scale multiplier applied to all axes (default: 1) */
+    scale?: number;
+    /** Dead zone threshold (0-1). Values below this are zeroed. */
+    deadZone?: number;
+    /** Only pass the strongest axis, zero all others */
+    dominant?: boolean;
+}
+/** Global configuration */
+interface InputConfig {
+    /** Default axis routes (used when device has no override) */
+    routes: AxisRoute[];
+    /** Default scale */
+    scale: number;
+    /** Dead zone threshold */
+    deadZone: number;
+    /** Dominant axis mode */
+    dominant: boolean;
+    /** Lock translation to zero */
+    lockPosition: boolean;
+    /** Lock rotation to zero */
+    lockRotation: boolean;
+    /** Per-device overrides keyed by device ID or pattern (e.g., "cnx-*") */
+    devices: Record<string, DeviceConfig>;
+}
+
+interface StorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+
+interface InputManagerEvents {
+    spatialData: (data: SpatialData) => void;
+    rawSpatialData: (data: SpatialData) => void;
+    buttonEvent: (data: ButtonEvent) => void;
+    stateChange: (state: ConnectionState, protocol: TransportProtocol) => void;
+    deviceStatus: (event: "connected" | "disconnected", device: DeviceInfo$1) => void;
+    configChange: (config: InputConfig) => void;
+}
+interface DeviceWithConfig {
+    device: DeviceInfo$1;
+    config: DeviceConfig;
+}
+declare class InputManager extends TypedEmitter<InputManagerEvents> {
+    private connections;
+    private storage?;
+    private knownDevices;
+    private deviceAccumulators;
+    private accDirty;
+    private flushTimer;
+    private _config;
+    get config(): InputConfig;
+    constructor(config?: Partial<InputConfig>, storage?: StorageAdapter);
+    addConnection(connection: SatMouseConnection): void;
+    removeConnection(connection: SatMouseConnection): void;
+    connect(): Promise<void>;
+    disconnect(): void;
+    fetchDeviceInfo(): Promise<DeviceInfo$1[]>;
+    getDevicesWithConfig(): DeviceWithConfig[];
+    getDeviceConfig(deviceId: string): DeviceConfig;
+    updateConfig(partial: Partial<InputConfig>, persist?: boolean): void;
+    updateDeviceConfig(deviceId: string, partial: DeviceConfig, persist?: boolean): void;
+    resetDeviceConfig(deviceId: string, persist?: boolean): void;
+    resetAllConfig(): void;
+    onSpatialData(callback: (data: SpatialData) => void): () => void;
+    onButtonEvent(callback: (data: ButtonEvent) => void): () => void;
+    private wireConnection;
+    private flushAccumulator;
+    /** Per-device: deadZone → dominant → routes (flip + scale + remap in one pass) */
+    private processPerDevice;
+    /** Get the effective routes for a device: device config override > device axes metadata > global default */
+    private resolveRoutes;
+}
+
+interface SatMouseContextValue {
+    manager: InputManager;
+    state: ConnectionState;
+    protocol: TransportProtocol;
+    config: InputConfig;
+    updateConfig: (partial: Partial<InputConfig>) => void;
+}
+declare const SatMouseContext: react.Context<SatMouseContextValue | null>;
+interface SatMouseProviderProps {
+    connectOptions?: ConnectOptions;
+    config?: Partial<InputConfig>;
+    autoConnect?: boolean;
+    children: ReactNode;
+}
+declare function SatMouseProvider({ connectOptions, config: configOverrides, autoConnect, children, }: SatMouseProviderProps): react_jsx_runtime.JSX.Element;
+
+/** Access the SatMouse context. Throws if used outside SatMouseProvider. */
+declare function useSatMouse(): SatMouseContextValue;
+/**
+ * Subscribe to processed spatial data.
+ * Batches updates to requestAnimationFrame to avoid re-rendering at device rate.
+ */
+declare function useSpatialData(): SpatialData | null;
+/**
+ * Subscribe to raw (pre-transform) spatial data.
+ * Batches updates to requestAnimationFrame.
+ */
+declare function useRawSpatialData(): SpatialData | null;
+/** Subscribe to button events via callback. Does not trigger re-renders. */
+declare function useButtonEvent(callback: (event: ButtonEvent) => void): void;
+
+interface ConnectionStatusProps {
+    className?: string;
+}
+declare function ConnectionStatus({ className }: ConnectionStatusProps): react_jsx_runtime.JSX.Element;
+
+interface DeviceInfoProps {
+    className?: string;
+    /** Timeout in ms before showing "no device". Default: 5000 */
+    timeout?: number;
+}
+declare function DeviceInfo({ className, timeout }: DeviceInfoProps): react_jsx_runtime.JSX.Element;
+
+interface SettingsPanelProps {
+    className?: string;
+}
+declare function SettingsPanel({ className }: SettingsPanelProps): react_jsx_runtime.JSX.Element;
+
+interface DebugPanelProps {
+    className?: string;
+}
+declare function DebugPanel({ className }: DebugPanelProps): react_jsx_runtime.JSX.Element;
+
+export { ConnectionStatus, type ConnectionStatusProps, DebugPanel, type DebugPanelProps, DeviceInfo, type DeviceInfoProps, SatMouseContext, type SatMouseContextValue, SatMouseProvider, type SatMouseProviderProps, SettingsPanel, type SettingsPanelProps, useButtonEvent, useRawSpatialData, useSatMouse, useSpatialData };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kelnishi/satmouse-client",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "Client SDK for SatMouse 6DOF spatial input bridge",
   "type": "module",
   "sideEffects": ["./src/elements/*.ts", "./dist/elements/*"],