@kelnishi/satmouse-client 0.1.0

package/dist/react/index.d.ts

@@ -0,0 +1,239 @@
+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;
+}
+/** 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;
+}
+type ConnectionState = "disconnected" | "connecting" | "connected";
+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;
+    /** 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 _state;
+    private _protocol;
+    get state(): ConnectionState;
+    get protocol(): TransportProtocol;
+    constructor(options?: ConnectOptions);
+    connect(): Promise<void>;
+    disconnect(): void;
+    fetchDeviceInfo(): Promise<DeviceInfo$1[]>;
+    private tryTransport;
+    private setState;
+    private scheduleReconnect;
+    private clearReconnect;
+}
+
+interface FlipConfig {
+    tx: boolean;
+    ty: boolean;
+    tz: boolean;
+    rx: boolean;
+    ry: boolean;
+    rz: boolean;
+}
+interface SensitivityConfig {
+    translation: number;
+    rotation: number;
+}
+/** Maps each input axis to an output axis. E.g., { tx: "tz", tz: "tx" } swaps X and Z translation. */
+type AxisMap = {
+    tx: keyof Vec3;
+    ty: keyof Vec3;
+    tz: keyof Vec3;
+    rx: keyof Vec3;
+    ry: keyof Vec3;
+    rz: keyof Vec3;
+};
+
+interface InputConfig {
+    sensitivity: SensitivityConfig;
+    flip: FlipConfig;
+    deadZone: number;
+    dominant: boolean;
+    axisRemap: AxisMap;
+    lockPosition: boolean;
+    lockRotation: boolean;
+}
+
+interface StorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+
+interface InputManagerEvents {
+    /** Processed spatial data (after all transforms) */
+    spatialData: (data: SpatialData) => void;
+    /** Raw spatial data (before transforms) */
+    rawSpatialData: (data: SpatialData) => void;
+    /** Button event (pass-through from connection) */
+    buttonEvent: (data: ButtonEvent) => void;
+    /** Connection state changed */
+    stateChange: (state: ConnectionState, protocol: TransportProtocol) => void;
+    /** Device connected/disconnected */
+    deviceStatus: (event: "connected" | "disconnected", device: DeviceInfo$1) => void;
+    /** Configuration changed */
+    configChange: (config: InputConfig) => void;
+}
+/**
+ * Unified device service that wraps one or more SatMouseConnections
+ * and provides a single processed event stream.
+ *
+ * Applies a configurable transform pipeline to spatial data:
+ *   deadZone → dominant → flip → axisRemap → sensitivity → lock
+ *
+ * Persists settings to storage (localStorage by default).
+ */
+declare class InputManager extends TypedEmitter<InputManagerEvents> {
+    private connections;
+    private storage?;
+    private _config;
+    get config(): InputConfig;
+    constructor(config?: Partial<InputConfig>, storage?: StorageAdapter);
+    /** Add a connection to the managed set */
+    addConnection(connection: SatMouseConnection): void;
+    /** Remove a connection */
+    removeConnection(connection: SatMouseConnection): void;
+    /** Connect all managed connections */
+    connect(): Promise<void>;
+    /** Disconnect all managed connections */
+    disconnect(): void;
+    /** Fetch device info from all connections */
+    fetchDeviceInfo(): Promise<DeviceInfo$1[]>;
+    /** Update configuration. Persists by default. */
+    updateConfig(partial: Partial<InputConfig>, persist?: boolean): void;
+    /** Register a callback for processed spatial data. Returns unsubscribe function. */
+    onSpatialData(callback: (data: SpatialData) => void): () => void;
+    /** Register a callback for button events. Returns unsubscribe function. */
+    onButtonEvent(callback: (data: ButtonEvent) => void): () => void;
+    private wireConnection;
+    private processSpatialData;
+}
+
+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 };